@sublang/playbook 4.0.0 → 5.0.0

package/slc/link.md

@@ -143,7 +143,7 @@ exactly one `pendingCall` is active.
 Control-plane exceptions reject the runtime method rather than masquerade as a
 recoverable workflow `failed` result.
 
-`PlaybookRuntimeOptions` is host-agnostic and carries only _per-run_ knobs such as identity strings (e.g., model names a playbook substitutes into prompt placeholders) and strategy overrides the linker exposes.
+`PlaybookRuntimeOptions` is host-agnostic and carries only _per-run_ knobs such as identity strings (e.g., model names a playbook substitutes into prompt placeholders), strategy overrides the linker exposes, and — where the compiled playbook's policy needs a host seam — host-supplied port-shaped callbacks the linker exposes as option members whose types the artifact itself declares, so the six-member `PlaybookPorts` contract and the shared contract module stay free of host types.
 The link compiler emits a typed options interface per playbook based on the FSM's `CodingInput` (or equivalent).
 The CLI's absence of `--link-option` values does not mean that
 `PlaybookRuntimeOptions` is empty. CLI link options are compile-time inputs;
@@ -240,6 +240,10 @@ type PlaybookCallStart =
 
 `PlayerResult` mirrors the status, resume token, final text, and error fields of cligent's `PlayerRunResult` ([TMUX-033](https://github.com/sublang-ai/cligent/blob/main/specs/user/tmux-play.md#tmux-033)).
 The runtime treats `status !== 'ok'` as a player failure and routes it through the FSM's error path (§Abort).
+An `ok` player result whose `finalText` is missing, empty, or whitespace-only
+earns exactly one corrective re-ask: the same player call repeated under the
+stored resume selection, traced as its own player-call pair, before a second
+such result routes through the same error path.
 
 `callCaptain` runs a direct-Captain FSM actor against the host's Captain
 agent. The linked runtime shall pass
@@ -257,9 +261,13 @@ array requests a tool-free call, while omission preserves the host Captain's
 configured tools.
 `CaptainResult` carries no resume token or player-continuation selection.
 A non-`ok`
-result, or an `ok` result without non-empty `finalText`, shall record that
-failure on the call's single finish trace and reject the actor through the
-FSM's error path. These structured host-result failures are recoverable
+result, or an `ok` result whose `finalText` is missing, empty, or
+whitespace-only, shall record that failure on the call's single finish trace.
+A non-`ok` result shall then reject the actor through the FSM's error path
+with no corrective re-ask; an empty `ok` result shall first earn exactly one
+corrective re-ask — the same call repeated, traced as its own
+started/finished pair — and only a second such result shall reject the actor
+the same way. These structured host-result failures are recoverable
 workflow failures, not control-plane failures: the runtime shall let the actor
 take `onError`, drive it to quiescence, drain ordered emissions, and resolve
 the public method with `{ outcome: 'failed' }` carrying the failure state's
@@ -347,6 +355,8 @@ type PlaybookTraceType =
   | 'captain.call.finished'
   | 'playbook.call.started'
   | 'playbook.call.finished'
+  | 'apply.started'
+  | 'apply.finished'
   | 'fsm.transition'
   | 'status.emitted'
   | 'boss.input.settled'
@@ -373,10 +383,19 @@ The trace types are `session.started`, `boss.input.received`,
 `judge.call.started`, `judge.call.finished`, `player.call.started`,
 `player.call.finished`, `captain.call.started`, `captain.call.finished`,
 `playbook.call.started`,
-`playbook.call.finished`, `fsm.transition`, `status.emitted`,
+`playbook.call.finished`, `apply.started`, `apply.finished`,
+`fsm.transition`, `status.emitted`,
 `boss.input.settled`, and `session.disposed`.
 Call pairs carry exact prompts and replies, normalized failures, actor and state
 identity, and their boundary-specific options.
+`apply.started` and `apply.finished` are the paired schema-2 boundary of an
+executed `apply()` call on a runtime implementing the optional control surface
+(§Control surface): both carry the action id and idempotency `key` (plus the
+singular `stateId` on start when one exists), the pair shares one
+session-unique `apply-<n>` call id and the boundary's turn id, and the finish
+adds the receipt `disposition` with its `reason`, normalized `error`, or
+projected `run` result, all JSON-safe. A repeated idempotency key returns the
+recorded receipt without a new pair.
 Direct-Captain start and finish payloads shall carry `allowedTools` exactly when
 the originating `CaptainCallOptions` selects it and shall omit the member when
 the call preserves the host Captain's configured tools.
@@ -392,16 +411,23 @@ its message and optional data; consumers shall not have to recover state
 identity from a nested ad hoc object.
 Judge results use `reply`; player start and finish payloads both carry the
 selected `resume`; Captain start and finish payloads both carry
-the exact composed prompt, `visibility: 'visible'`, the direct invocation's
-`stateId` and `sourceItem`, and no player resume selection or resume token;
+the exact composed prompt, the boundary's selected `visibility`, the direct
+invocation's `stateId` and `sourceItem`, and no player resume selection or
+resume token — a visible workflow call carries its runtime-owned
+`resume: false` selection, while a hidden controller call
+(§Captain adjudication) omits the `resume` member altogether, its
+durable-conversation selection being host-owned;
 judge `purpose` is
 `boss-input-classification`, `player-output-adjudication`, or
 `captain-output-adjudication`; and every error uses
 `{ name, message, stack? }` rather than a raw string or `Error` instance.
 The Captain finish payload shall preserve the exact `CaptainResult` status and
 final text when present, while carrying any failure in normalized form.
-An `ok` result without `finalText` therefore retains status `ok` but also
-carries the normalized missing-text failure that makes the actor reject.
+An `ok` result without non-empty `finalText` therefore retains status `ok` but
+also carries the normalized missing-text failure; the corrective re-ask that
+follows (§PlaybookPorts contract) traces as its own started/finished pair, and,
+when that corrective call happens, only a second such finish makes the actor
+reject.
 If the Captain port rejects before returning a result, the finish instead
 carries explicit `status: 'aborted'` when the combined signal has aborted or
 `status: 'error'` otherwise. A finish boundary never omits status merely
@@ -596,8 +622,17 @@ Where the current ready or reconstructed terminal machine accepts exactly one
 ordinary textual entry event and no Boss question is pending, the runtime
 shall send that event deterministically and attach the exact original text to
 its declared textual payload field without invoking `callJudge`.
-The default Captain's ready entry is
-`{ type: 'BOSS_INTENT', bossIntent: turn.text }`.
+The default Captain — the controller playbook of
+[gears2fsm "Setup"](gears2fsm.md#setup) — is deterministic at every parked
+entry: the runtime maps each Boss turn from the exact text and the host's
+deterministic command-parse resolution, supplied through the linked options'
+controller port, to the rewritten machine's hub entry union —
+`{ type: 'BOSS_TURN', bossText: turn.text }` for an undecided turn,
+`{ type: 'PARSED_RESPOND', bossText: turn.text }` for a parse-resolved
+`respond`, `{ type: 'PARSED_ACTION', bossText: turn.text, decision }` carrying
+the injected parse-resolved decision object, and `{ type: 'SHUTDOWN' }` for the
+host's teardown resolution — and invokes no classifier judge call; the exact
+original text still rides only the runtime-owned textual payload field.
 All other non-empty turns shall use `callJudge` only to choose one of the FSM's
 event kinds and non-text routing fields, or no FSM action.
 The classifier prompt shall include the exact, unmodified `turn.text` in a
@@ -677,7 +712,7 @@ If a host forwards text beginning with `/` to `handleBossInput`, the runtime tre
 Hosts that receive structured control input shall resolve host-level concerns before choosing a playbook runtime.
 Once they call `handleBossInput`, they shall pass the Boss content as text and shall not pre-classify in-playbook FSM events or rely on slash forms as a runtime protocol.
 
-`BOSS_INTERRUPT` (or the FSM's equivalent explicit-state-jump event) is reached only by the judge choosing it and supplying its required target payload.
+Within `handleBossInput` classification, `BOSS_INTERRUPT` (or the FSM's equivalent explicit-state-jump event) is reached only by the judge choosing it and supplying its required target payload; `apply()` of a runtime-advertised action (§Control surface) is the second, runtime-validated path to the same events, and on neither path does the host fabricate an FSM event itself.
 It is _not_ an abort surface; aborts go through the abort signal and the strategies in §Abort.
 Hosts where the abort signal is terminal (e.g., SIGINT runs shutdown) shall not route abort to `BOSS_INTERRUPT`.
 
@@ -746,6 +781,55 @@ presentation. The linked
 runtime shall not make a second visible Captain call or expose the hidden
 structured adjudication merely to present the same response.
 
+That visible-call presentation — visible Captain prose as the Boss
+presentation, a separate hidden adjudicator that never authors the
+`question`/`response` fields, and runtime injection of the visible
+`finalText` — stays scoped to visible-presentation playbooks such as CODE
+and DISCUSS. For a controller playbook, whose FSM declares the controller
+decision-state class of [gears2fsm "Setup"](gears2fsm.md#setup), the
+Captain-call presentation admits the hidden controller form instead
+(DR-029): the decision and closing-reply Captain calls run
+`{ visibility: 'hidden' }` on the host's durable conversation, whose resume
+token the host pins and rotates (DR-029), and the decision call's reply
+is the `{ action, … }` control JSON itself — validated by the linked runtime
+against the declared decision-state contract rather than adjudicated through
+a separate judge call, with exactly one corrective re-ask appending the
+rejection reason and the restated reply contract (the DR-025 corrective
+pattern). Because the host owns that conversation, the `resume` member the
+runtime is required to pass on a controller call carries no continuity
+meaning: the runtime passes `resume: false` because it holds no token, and
+the host's pinned durable selection overrides it — a controller call shall
+never be read as a request for a fresh conversation.
+
+The validated selection is not itself an effect. The linked runtime shall
+submit it through the host-supplied controller port the linker exposed as an
+option member (§PlaybookRuntime contract) and shall take the returned
+settlement as the only evidence of what happened. That settlement, carried
+beside the selected action as the guard discriminant, is the decision
+invocation's own result — the actor output the decision state's `onDone` arms
+select on and its evidence action records — so the effect reports through the
+same invocation that decided it, with no second boundary and no host-sent
+event. A controller prose state (a parse-resolved `respond` reply, an acting
+turn's closing reply) settles on its declared single outcome and returns no
+prose to the machine at all.
+
+That reply is control data, never Boss presentation: the runtime
+shall not inject the `question` or `response` presentation fields into a
+controller result — no visible Captain call exists to own them. Controller
+prose reaches the Boss only as host-validated captain speech surfaced
+through the host's presentation seam, cligent `CaptainContext.emitReply`
+(DR-029). Because no prose returns to the machine and no presentation
+field is injected, the host's own `callCaptain` implementation is that seam:
+it already holds the `CaptainResult` of the call it just served, and it
+identifies which call that is from the paired `captain.call.started` boundary
+the runtime emits before invoking the port, whose identity carries the
+invoking `stateId` and `sourceItem` (§Playbook trace). No prose therefore
+needs a return path through the machine, and none exists.
+The visible-call `question`/`response` injection rule above and
+the `{ visibility: 'visible', resume: false }` workflow-call selection
+(§PlaybookPorts contract, §Captain prompt composition) stay the
+visible-presentation shape for non-controller playbooks.
+
 The adjudicator shall fail loudly on:
 
 - A guard the state does not declare,
@@ -791,9 +875,9 @@ independent cleanup evidence.
 ## Script execution
 
 Where the FSM declares the typed `script` actor from
-[gears2fsm "Setup"](gears2fsm.md#setup), the linked runtime shall provide
-its implementation through the shared factory (§Output); the linker shall
-not regenerate a script executor inside each emitted module.
+[gears2fsm "Setup"](gears2fsm.md#setup), a factory-backed linked runtime shall
+provide its implementation through the shared factory (§Output); the linker
+shall not regenerate a script executor inside a factory-backed emitted module.
 A script invocation is the one actor kind that runs without any agent:
 it makes no `callPlayer`, `callCaptain`, or `callJudge` call and needs no
 adjudication.
@@ -1170,6 +1254,162 @@ not `active` or whose state descriptor cannot be normalized shall fail
 A restore failure shall leave the runtime unbound so `dispose` remains
 callable and terminal.
 
+## Control surface (optional)
+
+A linked runtime may implement the optional control-surface capability of
+`@sublang/playbook/runtime` — `describe()` and `apply(...)` — so a host can
+observe the parked machine and execute a runtime-advertised recovery or jump
+action without fabricating an FSM event (DR-029). A runtime that
+implements either member shall implement both; every runtime the shared
+`createXStatePlaybookRuntime` factory constructs implements the pair. A
+runtime lacking the pair advertises no actions, and plain text delivery is
+the only verb against it. Presence is feature-detected like the
+parked-session snapshot capability; the pair changes no runtime ABI and no
+artifact or snapshot schema.
+
+```typescript
+interface PlaybookControlAction {
+  id: string;      // stable within the returned view
+  label: string;   // runtime-written, Boss-appropriate
+}
+
+interface PlaybookControlView {
+  state: PlaybookState;
+  stateDescription?: string;  // runtime-published meaning of the current state
+  context?: JsonValue;   // the runtime's authored projection, sanitized
+  pendingQuestions: readonly PlaybookPendingBossQuestion[];
+  lastError?: NormalizedError;
+  actions: readonly PlaybookControlAction[];
+}
+
+type PlaybookControlReceipt =
+  | { disposition: 'rejected'; reason: string }          // before any effect
+  | { disposition: 'executed'; run: PlaybookRunResult }
+  | { disposition: 'failed'; error: NormalizedError };   // effects may exist
+
+// Optional PlaybookRuntime members — both or neither:
+describe?(): PlaybookControlView;
+apply?(input: { actionId: string; key: string; signal: AbortSignal }): Promise<PlaybookControlReceipt>;
+```
+
+`describe()` shall be side-effect free — it emits no trace, status, or
+telemetry and moves no machine state — and is valid at parked quiescence
+outside an active `handleBossInput`/`resumePlaybookCall`/`apply` boundary;
+during an active boundary, before `init`, or after disposal begins it shall
+throw. The view carries the current normalized state descriptor, the state
+description defined below, the authored context projection defined below, the
+pending Boss questions with their stable ids, the last recorded error in
+normalized form, and the currently valid actions.
+
+`stateDescription` is the runtime's own Boss-facing statement of what its
+current state means, taken from the same source state descriptions the action
+labels below are written from. A controller host has no other grounding for a
+status answer, and an internal state id is not text a reply may repeat, so the
+runtime publishes the meaning rather than leaving the host to substitute the
+identifier for it. A state whose source declares no description carries no
+`stateDescription`: an id is never promoted into a description, so a host is
+never handed an identifier dressed as meaning.
+
+The view's `context` is an explicit projection the linked runtime **authors**,
+never an allow-by-default serialization of the FSM context (PBRT-52).
+Only the runtime knows which of its context members are safe and relevant
+for a controller prompt, while the host receiving the view cannot inspect an
+opaque blob for the player rosters, option values, and raw player output its
+own prompts must exclude; exporting by default makes the two obligations
+unsatisfiable together and gives every member added to an FSM later the wrong
+default. The rules:
+
+- The emitted module declares the projection in its `spec` as
+  `controlContextFields` — the FSM context member names its view exposes, in
+  the order it names them — and the factory exports those and nothing else.
+- A runtime naming no member carries no `context` at all, so a member is
+  private until an artifact names it and extending an FSM leaks nothing by
+  omission.
+- Sanitization sits on top of the projection, not in place of it: a named
+  member is still normalized (raw `Error` values normalized) and dropped when
+  it cannot be made JSON-safe, rather than thrown, since `describe` stays
+  side-effect free and total.
+- The two members the view surfaces first-class — the pending Boss question
+  and the last error — cannot be named. A projection naming either is a
+  construction error, failing runtime construction rather than being silently
+  ignored.
+- The host still composes its own prompt block from the projection rather than
+  pasting the projection in, so no runtime's exported value can forge a block
+  into an envelope the host owns.
+
+Actions derive from the live snapshot, only at the same safe point the
+parked-session snapshot uses (actor status `active`, quiescent, no pending
+nested call); anywhere else `actions` is empty while the rest of the view
+still describes the state. Two families exist, labeled from source state
+descriptions:
+
+- **Failure-state retry** — while the singular state id is the recoverable
+  failure state and the runtime holds a recorded last classified event (the
+  event a public Boss boundary sent that drove the run into `failed`, kept
+  with its recorded payload), and the live snapshot accepts that event, the
+  runtime shall advertise `retry:<EVENT_TYPE>` replaying exactly that
+  recorded event.
+- **Jump entries** — for each registered resumable state id whose
+  explicit-state-jump event (`BOSS_INTERRUPT` with that `targetId`, optional
+  textual fields omitted) the live snapshot accepts, guards included, the
+  runtime shall advertise `jump:<stateId>`.
+
+A candidate whose event requires a payload the runtime cannot source from
+recorded state shall be excluded from `actions` — `apply` never invents free
+text and never enters Boss-input classification. A candidate whose *label*
+could only be an identifier is excluded on the same terms: a label never falls
+back to a target id or to the replayed event type, because a controller host
+names an executed or refused action by its label and never by its id, so an
+identifier used as a label defeats that substitution. A jump whose target
+publishes no description is therefore not advertised — borrowing another
+state's description would name the wrong state — and a retry falls back from
+its target's description to its own source state's, and is not advertised when
+neither exists.
+
+`apply({ actionId, key, signal })` shall revalidate the action against the
+live state and settle `{ disposition: 'rejected', reason }` with no effect
+when it is no longer advertised. It shall execute an accepted action at most
+once per idempotency `key`: the receipt is recorded at acceptance, before
+the settlement emissions, and a repeated key returns the recorded receipt
+verbatim with no revalidation, no execution, and no new trace pair within the
+runtime instance.
+Only accepted receipts (`executed` or `failed`) are recorded and final for
+their key. A rejection settles before acceptance and records nothing under
+its key — a later call with that key revalidates afresh, traces its own
+pair, and may execute once the action is advertised — and a key whose call
+threw before reaching acceptance (lifecycle misuse, invalid input, a
+pre-acceptance abort, a rejected start-boundary sink) likewise records
+nothing, so a later call with that key may execute. Executing sends the
+validated event through the same actor drive as `handleBossInput` — state
+transitions, player/judge boundaries, statuses, and traces flow unchanged —
+and settles `executed` with the projected run result, or `failed` with the
+normalized error when the run settles in the failure state, aborts, or a
+post-acceptance control-plane error lands (effects may exist). `signal`
+follows §Abort exactly as a Boss-turn signal does; an abort after acceptance
+settles the `failed` receipt rather than rejecting. The boundary traces as
+the paired `apply.started` / `apply.finished` events of §Playbook trace, and
+`apply` shares the single active-boundary sentinel with `handleBossInput`
+and `resumePlaybookCall`.
+
+Acceptance is also the line past which `apply` does not throw, and
+publication — the `apply.finished` emission — is the line past which its
+receipt no longer changes. A settlement failure after acceptance but before
+publication (a rejecting emission drain) settles the `failed` receipt carrying
+its normalized error, replacing the one recorded at acceptance so the finish
+trace, the returned receipt, and any replay of the key report one settlement.
+A settlement failure at or after publication (a rejecting `apply.finished`
+sink) does not: the disposition is already emitted, so no rewrite can make the
+trace and the return agree, and a receipt states what happened to the effect
+rather than what happened to its telemetry. The published receipt stands, is
+returned and replayed verbatim, and the delivery failure travels on the
+runtime's emission-failure channel to surface from the next public boundary
+that drains.
+
+The recorded receipts and the recorded last classified event are
+process-local: the schema-1 parked-session snapshot persists neither, and a
+restored runtime advertises a retry again only after its next classified
+event.
+
 ## Abort
 
 `handleBossInput.signal` is the abort surface.
@@ -1245,19 +1485,25 @@ The `playbook.trace` copies are the host-agnostic runtime-boundary record requir
 
 ## Output
 
-The link compiler emits **one thin** TypeScript module per playbook.
+The link compiler emits one TypeScript module per playbook.
+For an FSM that declares no `type: 'parallel'` state, it shall emit the thin
+shared-factory module defined below.
+For an FSM that declares a parallel state, it shall emit bespoke linked
+machinery satisfying this document's runtime contract and shall not invoke
+`createXStatePlaybookRuntime`, whose supported domain is single-region FSMs
+under [DR-019](../specs/decisions/019-shared-linked-runtime-factory.md).
 The FSM-interpreter machinery — actor wiring, boundary tracing, Boss-event
 mapping, adjudication, script execution, nested-playbook bridging, session
 lifecycle, abort handling, and the optional parked-session snapshot
-capability — is not regenerated per artifact: it ships once as the shared
-`createXStatePlaybookRuntime(machine, spec)` factory exported by
+capability — is not regenerated for a factory-backed artifact: it ships once
+as the shared `createXStatePlaybookRuntime(machine, spec)` factory exported by
 `@sublang/playbook/xstate-runtime`, and the emitted module hands its FSM and
 a small per-playbook `spec` to that factory. Every behavioral section of
 this definition still binds the emitted module's runtime; the shared factory
 is how the emitted module satisfies them, so a runtime fix ships as a
 package release instead of a re-link of every artifact.
 
-The emitted module:
+The thin emitted module:
 
 - Imports the FSM artifact by relative path with an extension-bearing
   runtime specifier. When the linked TypeScript is part of a package that
@@ -1297,10 +1543,23 @@ The emitted module:
   exceptions not covered by the canonical kebab-token-to-camel-field mapping
   and the canonical `<#>` → `irNumber` special case; the
   transition-event payload fields the FSM's Boss union declares; a
-  non-default player binding where the linker inputs supplied one; and any
+  non-default player binding where the linker inputs supplied one; the
+  `controlContextFields` projection of §Control surface; and any
   per-playbook strategy override (classifier, prompt composers,
   required-field extraction, status formatting) an earlier section of this
-  definition requires for that playbook. The metadata shall keep the shared
+  definition requires for that playbook.
+  `controlContextFields` is authored, not derived: the linker names the FSM
+  context members the playbook's controller view exposes and no others, in the
+  order the view should render them, omitting the member entirely where the
+  playbook exposes no context. It is the one spec member whose default is
+  *nothing* rather than everything — the factory exports no context for a
+  module that supplies none — so a module emitted without it advertises a
+  playbook with no Boss-visible context rather than one whose whole FSM
+  context is Boss-visible. The linker shall not name a member the view
+  surfaces first-class (the pending Boss question, the last error), which is a
+  construction error, and shall not name a member carrying a resolved player
+  roster, an option value, or player-authored text, which a controller host's
+  prompts are required to exclude or to fence. The metadata shall keep the shared
   classifier's reply contract exactly flat `{ type, ...declaredFields }` and
   distinguish judge-authored routing fields from exact-text fields the
   runtime attaches itself. Everything else — player/script/captain/nested actor
@@ -1352,10 +1611,16 @@ The emitted module:
 - Default-exports the factory call as `createPlaybookRuntime`, typed
   `PlaybookRuntimeFactory<PlaybookRuntimeOptions>`.
 - Exposes, under an `_internal` export, the pure helpers verification
-  needs — at least the player-prompt and Captain-prompt composers
-  (`composePlayerPrompt` and `composeCaptainPrompt`), which may re-export
-  the shared defaults when the spec does not override composition — so
-  compilation-correctness tests can exercise composition without a host.
+  needs — at least the prompt composers its own machine uses, which may
+  re-export the shared defaults when the spec does not override composition —
+  so compilation-correctness tests can exercise composition without a host.
+  A playbook that calls players exposes `composePlayerPrompt`; a playbook
+  whose states make direct-Captain calls exposes `composeCaptainPrompt`. A
+  controller playbook that calls no players exposes no player composer:
+  there is no composition to verify, and a stub under that name would
+  describe work the module cannot do. `_internal` is not a public API — the
+  leading underscore says so — and nothing in it is semver-stable; a helper
+  a host is meant to call is a top-level export and is governed as one.
 - Holds no host-specific types and no host primitive calls. The runtime
   speaks only `PlaybookPorts` for every agent and host concern; the
   `node:child_process` dependency of §Script execution lives in the shared
@@ -1375,6 +1640,9 @@ The emitted module:
   dependency runs one way — from each linked module to the shared
   engine and contract, never the reverse.
 
+Both output profiles remain subject to the behavioral sections above and the
+verification requirements below.
+
 When a co-located integration test for the linked runtime already exists, the
 link compiler shall run it before reporting success and treat any failure as a
 generation failure. It shall not delete, skip, or weaken that suite to make a

package/src/runtime.d.ts

@@ -108,7 +108,7 @@ export interface PlaybookSession {
     depth: number;
     ports: PlaybookPorts;
 }
-export type PlaybookTraceType = 'session.started' | 'boss.input.received' | 'judge.call.started' | 'judge.call.finished' | 'player.call.started' | 'player.call.finished' | 'captain.call.started' | 'captain.call.finished' | 'playbook.call.started' | 'playbook.call.finished' | 'fsm.transition' | 'status.emitted' | 'boss.input.settled' | 'session.disposed';
+export type PlaybookTraceType = 'session.started' | 'boss.input.received' | 'judge.call.started' | 'judge.call.finished' | 'player.call.started' | 'player.call.finished' | 'captain.call.started' | 'captain.call.finished' | 'playbook.call.started' | 'playbook.call.finished' | 'apply.started' | 'apply.finished' | 'fsm.transition' | 'status.emitted' | 'boss.input.settled' | 'session.disposed';
 export interface PlaybookTraceEvent {
     schemaVersion: 2;
     sessionId: string;
@@ -148,10 +148,38 @@ export interface PlaybookRuntimeSnapshot {
     state: PlaybookState;
     pendingBossQuestions: readonly PlaybookPendingBossQuestion[];
 }
+export interface PlaybookControlAction {
+    id: string;
+    label: string;
+}
+export interface PlaybookControlView {
+    state: PlaybookState;
+    stateDescription?: string;
+    context?: JsonValue;
+    pendingQuestions: readonly PlaybookPendingBossQuestion[];
+    lastError?: NormalizedError;
+    actions: readonly PlaybookControlAction[];
+}
+export type PlaybookControlReceipt = {
+    disposition: 'rejected';
+    reason: string;
+} | {
+    disposition: 'executed';
+    run: PlaybookRunResult;
+} | {
+    disposition: 'failed';
+    error: NormalizedError;
+};
 export interface PlaybookRuntime {
     init(session: PlaybookSession): Promise<void>;
     exportSnapshot?(): PlaybookRuntimeSnapshot | undefined;
     restore?(session: PlaybookSession, snapshot: PlaybookRuntimeSnapshot): Promise<void>;
+    describe?(): PlaybookControlView;
+    apply?(input: {
+        actionId: string;
+        key: string;
+        signal: AbortSignal;
+    }): Promise<PlaybookControlReceipt>;
     handleBossInput(turn: {
         text: string;
         signal: AbortSignal;

package/src/runtime.ts

@@ -157,6 +157,8 @@ export type PlaybookTraceType =
   | 'captain.call.finished'
   | 'playbook.call.started'
   | 'playbook.call.finished'
+  | 'apply.started'
+  | 'apply.finished'
   | 'fsm.transition'
   | 'status.emitted'
   | 'boss.input.settled'
@@ -206,6 +208,38 @@ export interface PlaybookRuntimeSnapshot {
   pendingBossQuestions: readonly PlaybookPendingBossQuestion[];
 }
 
+// DR-029: one currently valid, runtime-advertised control action. The id
+// is stable within the returned view; the label is runtime-written,
+// Boss-appropriate text derived from source state descriptions.
+export interface PlaybookControlAction {
+  id: string;
+  label: string;
+}
+
+// DR-029: the sanitized control view `describe()` returns — current
+// state and the runtime-written description of what that state means,
+// the authored context projection, pending Boss questions, the last
+// recorded error, and the currently valid actions. `stateDescription` is
+// the Boss-appropriate grounding a host may speak from; the state id is
+// internal and is absent from it whenever the runtime's source declares
+// no description for the state it is in.
+export interface PlaybookControlView {
+  state: PlaybookState;
+  stateDescription?: string;
+  context?: JsonValue;
+  pendingQuestions: readonly PlaybookPendingBossQuestion[];
+  lastError?: NormalizedError;
+  actions: readonly PlaybookControlAction[];
+}
+
+// DR-029: the receipt `apply()` returns says which of three things
+// happened — rejected before any effect, executed with the settled run
+// result, or failed after effects may exist.
+export type PlaybookControlReceipt =
+  | { disposition: 'rejected'; reason: string }
+  | { disposition: 'executed'; run: PlaybookRunResult }
+  | { disposition: 'failed'; error: NormalizedError };
+
 export interface PlaybookRuntime {
   init(session: PlaybookSession): Promise<void>;
   // DR-014 §1 optional durable-session capability: a runtime implements
@@ -218,6 +252,19 @@ export interface PlaybookRuntime {
     session: PlaybookSession,
     snapshot: PlaybookRuntimeSnapshot,
   ): Promise<void>;
+  // DR-029 optional control-surface capability: a runtime implements
+  // both members or neither. `describe` is side-effect free and valid at
+  // parked quiescence outside an active boundary; `apply` revalidates the
+  // named action against the live state, executes it at most once per
+  // idempotency key within that runtime instance, and returns a receipt. A
+  // runtime lacking the pair advertises no actions; plain text delivery is
+  // the only verb against it.
+  describe?(): PlaybookControlView;
+  apply?(input: {
+    actionId: string;
+    key: string;
+    signal: AbortSignal;
+  }): Promise<PlaybookControlReceipt>;
   handleBossInput(turn: {
     text: string;
     signal: AbortSignal;