@sublang/playbook 15.1.0 → 16.0.0

package/docs/embedding.md

@@ -38,7 +38,7 @@ tree, which pnpm's strict linking will not allow.
 
 ```ts
 import createPlaybookRuntime, {
-  type ReviewPlaybookHostCapabilities,
+  type PlaybookHostCapabilities,
 } from '@sublang/playbook/review/playbook';
 import type {
   CaptainCallOptions,
@@ -156,7 +156,7 @@ const playbookSessionId = randomUUID();
 // machine input, or a persisted snapshot. A host outside the CLI constructs
 // the repository and effect-ledger members through the facade described in
 // "Constructing worktree host capabilities" below.
-declare const hostCapabilities: ReviewPlaybookHostCapabilities;
+declare const hostCapabilities: PlaybookHostCapabilities;
 
 const runtime = createPlaybookRuntime({
   configuredOptions: {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "15.1.0",
+  "version": "16.0.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, DEV, BRANCH, and PR workflows driven by GEARS specs.",
   "license": "Apache-2.0",

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

@@ -1,34 +1,46 @@
 export type BranchStateId = 'createBranch';
 export type BranchSourceItem = 'BRANCH-1';
+/**
+ * Stable working-leaf ids that may suspend on a Boss question and be resumed
+ * by `BOSS_REPLY`. The machine has at most one active player task, so the
+ * scalar Boss-reply form applies.
+ */
+declare const RESUMABLE_STATE_IDS: readonly ["createBranch"];
+export type ResumableStateId = (typeof RESUMABLE_STATE_IDS)[number];
+/** JSON-safe normalization of a rejected invocation, retained for inspection. */
+export type NormalizedError = {
+    readonly name: string;
+    readonly message: string;
+    readonly stack?: string;
+};
+/** Question record raised by the suspended Coder working leaf. */
 export type PendingBossQuestion = {
-    readonly questionId: 'createBranch';
-    readonly resumeStateId: 'createBranch';
-    readonly sourceItem: 'BRANCH-1';
+    readonly questionId: ResumableStateId;
+    readonly resumeStateId: ResumableStateId;
+    readonly sourceItem: BranchSourceItem;
     readonly asker: {
         readonly kind: 'role';
         readonly roleId: 'coder';
     };
     readonly question: string;
 };
+/** Typed input for the delegated `player` actor. */
 export type PlayerInput = {
     readonly stateId: 'createBranch';
     readonly role: 'coder';
     readonly sourceItem: 'BRANCH-1';
     readonly prompt: string;
     readonly result: Readonly<Record<string, string>>;
+    /** Backs the prompt's `<caller-input>` placeholder with the exact caller input. */
     readonly callerInput: string;
     readonly pendingBossQuestion?: PendingBossQuestion;
     readonly bossReply?: string;
 };
+/** Discriminated result contract of the delegated `player` actor. */
 export type PlayerOutput = {
     readonly guard: 'branched';
     readonly branch: string;
-    /**
-     * Receipt-owned effect evidence (DR-045): the branching call's
-     * `unchanged` receipt observes the commit the branch was created from
-     * as HEAD, so the linked runtime injects it and never takes it from
-     * Coder's prose.
-     */
+    /** Exact base revision from repository authority, not from Coder's prose. */
     readonly baseRevision: string;
     readonly issueSummary: string;
 } | {
@@ -38,47 +50,55 @@ export type PlayerOutput = {
     readonly guard: 'needsBossReply';
     readonly question: string;
 };
+/**
+ * Terminal result: exactly the packaged `branch` workflow's public output
+ * interface (workflow-contracts.json), derived from typed context.
+ */
 export type BranchPlaybookOutput = {
     readonly status: 'branched';
-    /** Exact name of the new branch now checked out. */
+    /** Exact new branch name. */
     readonly branch: string;
-    /** Exact receipt-observed revision the branch was created from. */
+    /** Exact receipt-observed repository revision the branch was created from. */
     readonly baseRevision: string;
-    /** Coder's concise summary of the issue and its comments, or of the request. */
+    /** Concise issue-and-comments or request summary. */
     readonly issueSummary: string;
 } | {
     readonly status: 'refused';
-    /** Coder's complete report carrying the reason no branch was created. */
+    /** Complete refusal report. */
     readonly coderOutput: string;
 };
-export type BranchInput = Readonly<Record<string, never>>;
+/** The machine reads no input: the caller input arrives on `START_BRANCH`. */
+export type BranchInput = Readonly<Record<never, never>>;
+export type BranchCompletion = 'branched' | 'refused';
 export type BranchContext = {
     readonly callerInput?: string;
     readonly branch?: string;
-    /** Observed HEAD of the branching call's unchanged receipt (DR-045). */
     readonly baseRevision?: string;
     readonly issueSummary?: string;
     readonly coderOutput?: string;
-    readonly completion?: 'branched' | 'refused';
-    readonly lastError?: unknown;
+    readonly completion?: BranchCompletion;
+    readonly lastError?: NormalizedError;
     readonly pendingBossQuestion?: PendingBossQuestion;
     readonly bossReply?: string;
 };
+/** Typed Boss surfaces: the caller's entry event and the Boss reply. */
 export type BranchEvent = {
     readonly type: 'START_BRANCH';
     readonly callerInput: string;
 } | {
     readonly type: 'BOSS_REPLY';
     readonly answer: string;
-    readonly questionId?: 'createBranch';
+    readonly questionId?: ResumableStateId;
 };
+/** No parallel group in this playbook. */
+export declare const concurrentRoleSets: readonly (readonly string[])[];
 export declare const branchMachine: import("xstate").StateMachine<BranchContext, {
     readonly type: "START_BRANCH";
     readonly callerInput: string;
 } | {
     readonly type: "BOSS_REPLY";
     readonly answer: string;
-    readonly questionId?: "createBranch";
+    readonly questionId?: ResumableStateId;
 }, {
     [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>> | undefined;
 }, {
@@ -96,16 +116,22 @@ export declare const branchMachine: import("xstate").StateMachine<BranchContext,
     type: "rememberActorError";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "rememberPendingQuestion";
+    type: "rememberMalformedPlayerOutput";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "rememberBossReply";
+    type: "clearBossReplyContext";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "rememberEmptyBossReplyError";
+    type: "setPendingBossQuestion";
+    params: {
+        readonly stateId: ResumableStateId;
+        readonly sourceItem: BranchSourceItem;
+    };
+} | {
+    type: "rememberMalformedBossReply";
     params: import("xstate").NonReducibleUnknown;
 } | {
-    type: "rememberMalformedPlayerOutput";
+    type: "acceptBossReply";
     params: import("xstate").NonReducibleUnknown;
 } | {
     type: "startBranch";
@@ -118,9 +144,16 @@ export declare const branchMachine: import("xstate").StateMachine<BranchContext,
     params: import("xstate").NonReducibleUnknown;
 }, {
     type: "needsBossReply";
-    params: unknown;
+    params: {
+        readonly stateId: ResumableStateId;
+    };
 } | {
-    type: "emptyBossReply";
+    type: "canResume";
+    params: {
+        readonly stateId: ResumableStateId;
+    };
+} | {
+    type: "givesRequest";
     params: unknown;
 } | {
     type: "isBranched";
@@ -128,20 +161,17 @@ export declare const branchMachine: import("xstate").StateMachine<BranchContext,
 } | {
     type: "isRefused";
     params: unknown;
-} | {
-    type: "resumesCreateBranch";
-    params: unknown;
-}, never, "failed" | "ready" | "awaitBossReply" | "refused" | "createBranch" | "branched", string, Readonly<Record<string, never>>, {
+}, never, "failed" | "ready" | "awaitBossReply" | "refused" | "createBranch" | "branched", string, Readonly<Record<never, never>>, {
     readonly status: "branched";
-    /** Exact name of the new branch now checked out. */
+    /** Exact new branch name. */
     readonly branch: string;
-    /** Exact receipt-observed revision the branch was created from. */
+    /** Exact receipt-observed repository revision the branch was created from. */
     readonly baseRevision: string;
-    /** Coder's concise summary of the issue and its comments, or of the request. */
+    /** Concise issue-and-comments or request summary. */
     readonly issueSummary: string;
 } | {
     readonly status: "refused";
-    /** Coder's complete report carrying the reason no branch was created. */
+    /** Complete refusal report. */
     readonly coderOutput: string;
 }, import("xstate").EventObject, import("xstate").MetaObject, {
     id: "branch";

package/reference/sdlc/branch.playbook/branch.fsm.js

@@ -1,11 +1,15 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
-//
-// Generated by slc/gears2fsm.md from ./branch.gears.md.
 import { assign, fromPromise, setup } from 'xstate';
+/**
+ * Stable working-leaf ids that may suspend on a Boss question and be resumed
+ * by `BOSS_REPLY`. The machine has at most one active player task, so the
+ * scalar Boss-reply form applies.
+ */
+const RESUMABLE_STATE_IDS = ['createBranch'];
+/** No parallel group in this playbook. */
+export const concurrentRoleSets = [];
 const CREATE_BRANCH_PROMPT = [
-    '> Original request: <caller-input>',
-    '',
     'Prepare a new branch for this work without changing any file or making any commit.',
     'Identify the GitHub issue the request names, if any, and read it with its comments (`gh issue view --comments` with the issue number).',
     'If the request could refer to more than one issue, or does not say which work to branch for, ask Boss before creating anything.',
@@ -14,19 +18,22 @@ const CREATE_BRANCH_PROMPT = [
     'Create the branch from the current commit and check it out; do not pull, reset, stash, or move HEAD to another commit.',
     'Report the exact branch name, the commit it was created from, and a concise summary of the issue and its comments, or of the request when no issue is named.',
     'If the working tree is not clean, `gh` is not authenticated, the named issue does not exist or cannot be read, or a branch with that name already exists locally or on the remote, create nothing and report the failure with its reason.',
+    '',
+    '> Original request: <caller-input>',
 ].join('\n');
+const NEEDS_BOSS_REPLY_RESULT = "The acting agent's prose surfaces a clarifying question for Boss that the agent cannot answer alone. Output shall include `question: <verbatim question text from the acting agent's prose>`.";
 const CREATE_BRANCH_RESULTS = {
-    branched: 'Coder created the new branch from the current commit and checked it out, reporting its exact name and a concise summary of the issue and its comments, or of the request when no issue is named; the absence of a reported obstacle is not support. Output shall include `branch: <exact branch name>`, `baseRevision: <repository revision>`, and `issueSummary: <concise summary>`.',
-    refused: 'Coder created nothing and reported the failure with its reason: the working tree is not clean, `gh` is not authenticated, the named issue does not exist or cannot be read, or a branch with that name already exists locally or on the remote. Output shall include `coderOutput: <verbatim final text>`.',
-    needsBossReply: "The acting agent's prose surfaces a clarifying question for Boss that the agent cannot answer alone. Output shall include `question: <verbatim question text from the acting agent's prose>`.",
+    branched: "Coder affirmatively reported that it created the new branch from the current commit and checked it out, with the exact branch name and a concise summary of the issue and its comments, or of the request when no issue is named; the absence of a reported obstacle is not support. The branch workflow is then complete and returns the exact branch name, the exact base revision taken from repository authority, and the issue summary to its caller. Output shall include `branch: <exact branch name>`, `baseRevision: <exact base revision from repository authority, not from Coder's prose>`, and `issueSummary: <concise summary of the issue and its comments, or of the request when no issue is named>`.",
+    refused: "Coder affirmatively reported that it created no branch and gave the failure with its reason, such as a working tree that is not clean, gh not being authenticated, a named issue that does not exist or cannot be read, or a branch with that name already existing locally or on the remote. The branch workflow then fails and reports Coder's complete result with its reason to its caller; no branch was created. Output shall include `coderOutput: <verbatim final text>`.",
+    needsBossReply: NEEDS_BOSS_REPLY_RESULT,
 };
 const STATE_DESCRIPTIONS = {
-    ready: 'Waiting for a development request to branch for.',
-    createBranch: 'Coder is reading the named issue and creating and checking out a new branch at the current commit.',
-    awaitBossReply: 'Waiting for Boss to answer Coder.',
-    failed: 'The branch workflow failed and is waiting for a new development request.',
-    branched: "A new branch for the request is checked out at the caller's current commit; no file changed and no commit was made.",
-    refused: 'No branch was created: Coder reported the obstacle with its reason — a dirty working tree, an unauthenticated `gh`, an unreadable issue, or a branch-name collision.',
+    ready: 'Waiting for the caller to give a development request to branch for.',
+    createBranch: 'Coder is identifying the request\'s issue and creating and checking out a new branch at the current commit.',
+    awaitBossReply: "Waiting for Boss to answer the acting agent's question.",
+    failed: 'The branch workflow failed and is waiting for the caller to give the request again.',
+    branched: 'A new branch for the request was created at the current commit and checked out; the workflow returns its exact name, the exact base revision taken from repository authority, and the issue summary.',
+    refused: "No branch was created: Coder reported the failure with its reason, and the workflow fails and reports Coder's complete result to its caller.",
 };
 function playbookMeta(stateId, role) {
     return {
@@ -37,9 +44,7 @@ function playbookMeta(stateId, role) {
         },
     };
 }
-// DR-048: a final state additionally declares whether its outcome means the
-// workflow succeeded or failed, so BRANCH's own caller learns that from the
-// machine rather than from BRANCH's output fields.
+/** A final state also publishes whether its outcome is success or failure. */
 function terminalMeta(stateId, terminal) {
     return {
         playbook: {
@@ -59,33 +64,69 @@ function isRecord(value) {
 function isNonEmptyString(value) {
     return typeof value === 'string' && value.trim().length > 0;
 }
-function playerOutput(event) {
-    if (!isRecord(event))
+/**
+ * Narrows an unknown event's `output` structurally to the declared `player`
+ * contract. Output missing a field its guard requires narrows to `undefined`.
+ */
+function playerOutputOf(event) {
+    if (!isRecord(event) || !isRecord(event.output))
         return undefined;
-    return isRecord(event.output) ? event.output : undefined;
-}
-function outputGuard(event, guard) {
-    return playerOutput(event)?.guard === guard;
-}
-function outputString(event, field) {
-    const value = playerOutput(event)?.[field];
-    return isNonEmptyString(value) ? value : undefined;
+    const output = event.output;
+    if (output.guard === 'branched' &&
+        isNonEmptyString(output.branch) &&
+        isNonEmptyString(output.baseRevision) &&
+        isNonEmptyString(output.issueSummary)) {
+        return {
+            guard: 'branched',
+            branch: output.branch,
+            baseRevision: output.baseRevision,
+            issueSummary: output.issueSummary,
+        };
+    }
+    if (output.guard === 'refused' && isNonEmptyString(output.coderOutput)) {
+        return { guard: 'refused', coderOutput: output.coderOutput };
+    }
+    if (output.guard === 'needsBossReply' && isNonEmptyString(output.question)) {
+        return { guard: 'needsBossReply', question: output.question };
+    }
+    return undefined;
 }
-// DR-045: the branched outcome is accepted only with the receipt-observed
-// base revision the linked runtime injects; Coder's prose never supplies it.
-function isBranched({ event }) {
-    return (outputGuard(event, 'branched') &&
-        outputString(event, 'branch') !== undefined &&
-        outputString(event, 'baseRevision') !== undefined &&
-        outputString(event, 'issueSummary') !== undefined);
+/** Narrows an unknown event's `error` structurally to a JSON-safe record. */
+function normalizedErrorOf(event) {
+    const error = isRecord(event) ? event.error : undefined;
+    if (error instanceof Error) {
+        const name = error.name || 'Error';
+        return typeof error.stack === 'string'
+            ? { name, message: error.message, stack: error.stack }
+            : { name, message: error.message };
+    }
+    if (isRecord(error)) {
+        const name = typeof error.name === 'string' ? error.name : 'Error';
+        const message = typeof error.message === 'string'
+            ? error.message
+            : 'player actor rejected without a normalized error';
+        return typeof error.stack === 'string'
+            ? { name, message, stack: error.stack }
+            : { name, message };
+    }
+    return {
+        name: 'Error',
+        message: typeof error === 'string'
+            ? error
+            : 'player actor rejected without a normalized error',
+    };
 }
-function isRefused({ event }) {
-    return (outputGuard(event, 'refused') &&
-        outputString(event, 'coderOutput') !== undefined);
+function isResumableStateId(value) {
+    return RESUMABLE_STATE_IDS.includes(value);
 }
-function needsBossReply({ event }) {
-    return (outputGuard(event, 'needsBossReply') &&
-        outputString(event, 'question') !== undefined);
+/** Builds one guarded `BOSS_REPLY` resume arm per registered working-leaf id. */
+function resumableStates(ids) {
+    return ids.map((id) => ({
+        guard: { type: 'canResume', params: { stateId: id } },
+        target: `#${id}`,
+        reenter: true,
+        actions: 'acceptBossReply',
+    }));
 }
 const machineSetup = setup({
     types: {},
@@ -95,87 +136,114 @@ const machineSetup = setup({
         }),
     },
     guards: {
-        isBranched,
-        isRefused,
-        needsBossReply,
-        emptyBossReply: ({ event }) => event.type === 'BOSS_REPLY' && event.answer.trim().length === 0,
-        resumesCreateBranch: ({ context, event }) => event.type === 'BOSS_REPLY' &&
-            event.answer.trim().length > 0 &&
-            context.pendingBossQuestion?.resumeStateId === 'createBranch' &&
-            (event.questionId === undefined || event.questionId === 'createBranch'),
+        // The entry guard validates the text the current event supplies, before
+        // the entry action copies it into context.
+        givesRequest: ({ event }) => event.type === 'START_BRANCH' && isNonEmptyString(event.callerInput),
+        isBranched: ({ event }) => playerOutputOf(event)?.guard === 'branched',
+        isRefused: ({ event }) => playerOutputOf(event)?.guard === 'refused',
+        needsBossReply: ({ event }, params) => playerOutputOf(event)?.guard === 'needsBossReply' &&
+            isResumableStateId(params.stateId),
+        canResume: ({ context, event }, params) => {
+            if (event.type !== 'BOSS_REPLY' || !isNonEmptyString(event.answer)) {
+                return false;
+            }
+            const pending = context.pendingBossQuestion;
+            if (pending === undefined || pending.resumeStateId !== params.stateId) {
+                return false;
+            }
+            return (event.questionId === undefined ||
+                event.questionId === pending.questionId);
+        },
     },
     actions: {
         'playbook.acceptedOutcome': (_args, _params) => undefined,
-        startBranch: assign(({ event }) => {
+        startBranch: assign(({ context, event }) => {
             if (event.type !== 'START_BRANCH')
                 return {};
             return {
                 callerInput: event.callerInput,
-                branch: undefined,
-                baseRevision: undefined,
-                issueSummary: undefined,
-                coderOutput: undefined,
-                completion: undefined,
-                lastError: undefined,
-                pendingBossQuestion: undefined,
-                bossReply: undefined,
+                ...(context.lastError === undefined ? {} : { lastError: undefined }),
+                ...(context.pendingBossQuestion === undefined
+                    ? {}
+                    : { pendingBossQuestion: undefined }),
+                ...(context.bossReply === undefined ? {} : { bossReply: undefined }),
             };
         }),
-        rememberBranched: assign(({ event }) => ({
-            branch: outputString(event, 'branch'),
-            // DR-045: the receipt-observed HEAD the branch was created from.
-            baseRevision: outputString(event, 'baseRevision'),
-            issueSummary: outputString(event, 'issueSummary'),
-            completion: 'branched',
-            pendingBossQuestion: undefined,
-            bossReply: undefined,
-        })),
-        rememberRefused: assign(({ event }) => ({
-            coderOutput: outputString(event, 'coderOutput'),
-            completion: 'refused',
-            pendingBossQuestion: undefined,
-            bossReply: undefined,
-        })),
-        rememberPendingQuestion: assign(({ event }) => {
-            const question = outputString(event, 'question');
-            if (question === undefined || !outputGuard(event, 'needsBossReply')) {
-                return { lastError: new Error('Coder question output was malformed') };
-            }
+        rememberBranched: assign(({ context, event }) => {
+            const output = playerOutputOf(event);
+            if (output?.guard !== 'branched')
+                return {};
+            return {
+                branch: output.branch,
+                baseRevision: output.baseRevision,
+                issueSummary: output.issueSummary,
+                completion: 'branched',
+                ...(context.pendingBossQuestion === undefined
+                    ? {}
+                    : { pendingBossQuestion: undefined }),
+                ...(context.bossReply === undefined ? {} : { bossReply: undefined }),
+            };
+        }),
+        rememberRefused: assign(({ context, event }) => {
+            const output = playerOutputOf(event);
+            if (output?.guard !== 'refused')
+                return {};
+            return {
+                coderOutput: output.coderOutput,
+                completion: 'refused',
+                ...(context.pendingBossQuestion === undefined
+                    ? {}
+                    : { pendingBossQuestion: undefined }),
+                ...(context.bossReply === undefined ? {} : { bossReply: undefined }),
+            };
+        }),
+        setPendingBossQuestion: assign(({ context, event }, params) => {
+            const output = playerOutputOf(event);
+            if (output?.guard !== 'needsBossReply')
+                return {};
             return {
                 pendingBossQuestion: {
-                    questionId: 'createBranch',
-                    resumeStateId: 'createBranch',
-                    sourceItem: 'BRANCH-1',
+                    questionId: params.stateId,
+                    resumeStateId: params.stateId,
+                    sourceItem: params.sourceItem,
                     asker: { kind: 'role', roleId: 'coder' },
-                    question,
+                    question: output.question,
                 },
-                bossReply: undefined,
+                ...(context.bossReply === undefined ? {} : { bossReply: undefined }),
             };
         }),
-        rememberBossReply: assign(({ event }) => event.type === 'BOSS_REPLY' ? { bossReply: event.answer } : {}),
-        rememberEmptyBossReplyError: assign({
-            lastError: () => new Error('BOSS_REPLY received an empty answer'),
-            pendingBossQuestion: undefined,
-            bossReply: undefined,
-        }),
+        acceptBossReply: assign(({ event }) => event.type === 'BOSS_REPLY' ? { bossReply: event.answer } : {}),
+        clearBossReplyContext: assign(({ context }) => context.pendingBossQuestion === undefined &&
+            context.bossReply === undefined
+            ? {}
+            : { pendingBossQuestion: undefined, bossReply: undefined }),
         rememberActorError: assign(({ event }) => ({
-            lastError: event.error,
+            lastError: normalizedErrorOf(event),
+        })),
+        rememberMalformedPlayerOutput: assign(() => ({
+            lastError: {
+                name: 'MalformedPlayerOutput',
+                message: 'Coder result for BRANCH-1 did not satisfy a declared outcome of its result contract.',
+            },
+        })),
+        rememberMalformedBossReply: assign(() => ({
+            lastError: {
+                name: 'MalformedBossReply',
+                message: 'BOSS_REPLY carried an empty answer or named no pending question.',
+            },
         })),
-        rememberMalformedPlayerOutput: assign({
-            lastError: () => new Error('Coder result for BRANCH-1 did not match an available outcome.'),
-        }),
     },
 });
 export const branchMachine = machineSetup.createMachine({
     id: 'branch',
     initial: 'ready',
-    context: {},
+    context: () => ({}),
     output: ({ context }) => {
         if (context.completion === 'branched') {
             if (!isNonEmptyString(context.branch) ||
                 !isNonEmptyString(context.baseRevision) ||
                 !isNonEmptyString(context.issueSummary)) {
-                throw new Error('BRANCH reached branched without the exact branch name, a receipt-observed base revision, and an issue summary');
+                throw new Error('BRANCH reached branched without the exact branch name, base revision, and issue summary');
             }
             return {
                 status: 'branched',
@@ -186,7 +254,7 @@ export const branchMachine = machineSetup.createMachine({
         }
         if (context.completion === 'refused') {
             if (!isNonEmptyString(context.coderOutput)) {
-                throw new Error("BRANCH reached refused without Coder's report");
+                throw new Error("BRANCH reached refused without Coder's complete result");
             }
             return { status: 'refused', coderOutput: context.coderOutput };
         }
@@ -199,7 +267,11 @@ export const branchMachine = machineSetup.createMachine({
             meta: playbookMeta('ready'),
             tags: ['playbook.parked'],
             on: {
-                START_BRANCH: { target: 'createBranch', actions: 'startBranch' },
+                START_BRANCH: {
+                    guard: 'givesRequest',
+                    target: 'createBranch',
+                    actions: 'startBranch',
+                },
             },
         },
         createBranch: {
@@ -215,6 +287,8 @@ export const branchMachine = machineSetup.createMachine({
                     sourceItem: 'BRANCH-1',
                     prompt: CREATE_BRANCH_PROMPT,
                     result: CREATE_BRANCH_RESULTS,
+                    // Entry is guarded on a non-empty caller input, so this state is
+                    // never entered without it.
                     callerInput: context.callerInput ?? '',
                     ...(context.pendingBossQuestion === undefined
                         ? {}
@@ -255,7 +329,10 @@ export const branchMachine = machineSetup.createMachine({
                         ],
                     },
                     {
-                        guard: 'needsBossReply',
+                        guard: {
+                            type: 'needsBossReply',
+                            params: { stateId: 'createBranch' },
+                        },
                         target: 'awaitBossReply',
                         actions: [
                             {
@@ -266,7 +343,10 @@ export const branchMachine = machineSetup.createMachine({
                                     acceptedOutcome: 'needsBossReply',
                                 },
                             },
-                            'rememberPendingQuestion',
+                            {
+                                type: 'setPendingBossQuestion',
+                                params: { stateId: 'createBranch', sourceItem: 'BRANCH-1' },
+                            },
                         ],
                     },
                     {
@@ -284,19 +364,17 @@ export const branchMachine = machineSetup.createMachine({
             tags: ['playbook.parked'],
             on: {
                 BOSS_REPLY: [
+                    ...resumableStates(RESUMABLE_STATE_IDS),
                     {
-                        guard: 'emptyBossReply',
-                        target: '#failed',
-                        actions: 'rememberEmptyBossReplyError',
-                    },
-                    {
-                        guard: 'resumesCreateBranch',
-                        target: '#createBranch',
-                        reenter: true,
-                        actions: 'rememberBossReply',
+                        target: 'failed',
+                        actions: ['rememberMalformedBossReply', 'clearBossReplyContext'],
                     },
                 ],
-                START_BRANCH: { target: 'createBranch', actions: 'startBranch' },
+                START_BRANCH: {
+                    guard: 'givesRequest',
+                    target: 'createBranch',
+                    actions: 'startBranch',
+                },
             },
         },
         failed: {
@@ -305,7 +383,11 @@ export const branchMachine = machineSetup.createMachine({
             meta: playbookMeta('failed'),
             tags: ['playbook.parked'],
             on: {
-                START_BRANCH: { target: 'createBranch', actions: 'startBranch' },
+                START_BRANCH: {
+                    guard: 'givesRequest',
+                    target: 'createBranch',
+                    actions: 'startBranch',
+                },
             },
         },
         branched: {