@sublang/playbook 15.1.0 → 17.0.0

package/reference/sdlc/pr.playbook/pr.fsm.ts

@@ -1,9 +1,11 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 //
-// Generated by slc/gears2fsm.md from ./pr.gears.md.
+// Generated by gears2fsm from ./pr.gears.md.
 
 import { assign, fromPromise, setup } from 'xstate';
+import { validatePlaybookCallResult } from '@sublang/playbook/xstate-runtime';
+import type { PlaybookCallResult } from '@sublang/playbook/runtime';
 
 export type JsonValue =
   | null
@@ -18,7 +20,7 @@ export type PrStateId =
   | 'waitForChecks'
   | 'fixChecks'
   | 'publishFix'
-  | 'waitForChecksAfterFix'
+  | 'waitForFixChecks'
   | 'mergePullRequest'
   | 'updateLocalDefault';
 
@@ -31,16 +33,11 @@ export type PrSourceItem =
   | 'PR-6'
   | 'PR-7';
 
-export type PrScriptStateId =
-  | 'waitForChecks'
-  | 'publishFix'
-  | 'waitForChecksAfterFix'
-  | 'mergePullRequest'
-  | 'updateLocalDefault';
-
-export type PrScriptSourceItem = 'PR-2' | 'PR-4' | 'PR-5' | 'PR-6' | 'PR-7';
+/** Working leaves a Boss reply may resume (scalar Boss-reply form). */
+export type ResumableStateId = 'openPullRequest';
 
-export type PrChildPlaybookId = 'code';
+/** No parallel group: the playbook runs one delegated role at a time. */
+export const concurrentRoleSets: readonly (readonly string[])[] = [];
 
 export type PendingBossQuestion = {
   readonly questionId: 'openPullRequest';
@@ -56,6 +53,7 @@ export type PlayerInput = {
   readonly sourceItem: 'PR-1';
   readonly prompt: string;
   readonly result: Readonly<Record<string, string>>;
+  /** `<caller-input>`: the complete caller input, relayed in quotes. */
   readonly callerInput: string;
   readonly pendingBossQuestion?: PendingBossQuestion;
   readonly bossReply?: string;
@@ -70,17 +68,19 @@ export type PlayerOutput =
   | { readonly guard: 'notPublished'; readonly coderOutput: string }
   | { readonly guard: 'needsBossReply'; readonly question: string };
 
-export type PlaybookInput = {
-  readonly stateId: 'fixChecks';
-  readonly sourceItem: 'PR-3';
-  readonly playbookId: PrChildPlaybookId;
-  readonly text: string;
-};
+export type ScriptStateId =
+  | 'waitForChecks'
+  | 'publishFix'
+  | 'waitForFixChecks'
+  | 'mergePullRequest'
+  | 'updateLocalDefault';
 
 export type ScriptInput = {
-  readonly stateId: PrScriptStateId;
-  readonly sourceItem: PrScriptSourceItem;
+  readonly stateId: ScriptStateId;
+  readonly sourceItem: 'PR-2' | 'PR-4' | 'PR-5' | 'PR-6' | 'PR-7';
+  /** The script blockquote, with its runtime values bound as shell literals. */
   readonly command: string;
+  /** Zero-exit guard first, then the nonzero-exit guard. */
   readonly result: Readonly<Record<string, string>>;
 };
 
@@ -95,38 +95,53 @@ export type ScriptOutput =
   | { readonly guard: 'localDefaultUpdated'; readonly exitStatus: number }
   | { readonly guard: 'localDefaultNotUpdated'; readonly exitStatus: number };
 
+export type PrChildPlaybookId = 'code';
+
+export type PlaybookInput = {
+  readonly stateId: 'fixChecks';
+  readonly sourceItem?: 'PR-3';
+  readonly playbookId: PrChildPlaybookId;
+  readonly text: string;
+};
+
+/** The playbook actor resolves with the child's own machine output. */
+export type PlaybookOutput = JsonValue | undefined;
+
 export type CompactError = {
   readonly name: string;
   readonly message: string;
 };
 
-/** Sanitized canonical child result relayed as PR's own failure outcome. */
-export type CompletedChildResult =
+export type ErrorRecord = {
+  readonly name: string;
+  readonly message: string;
+  readonly stack?: string;
+};
+
+/** Sanitized canonical `code` result relayed by the `fix-failed` outcome. */
+export type CompletedCodeResult =
   | {
-      readonly playbookId: PrChildPlaybookId;
+      readonly playbookId: 'code';
       readonly status: 'ok';
       readonly output?: JsonValue;
     }
   | {
-      readonly playbookId: PrChildPlaybookId;
+      readonly playbookId: 'code';
       readonly status: 'aborted' | 'error';
       readonly error: CompactError;
     };
 
+/** Public `pr` output interface (workflow-contracts catalog). */
 export type PrPlaybookOutput =
   | {
       readonly status: 'merged';
-      /** The pull request number, exactly as Coder reported it. */
       readonly pullRequest: string;
-      /** The pull request URL, exactly as Coder reported it. */
       readonly pullRequestUrl: string;
-      /** Whether the local default branch was fast-forwarded to the merged head. */
       readonly localDefaultUpdated: boolean;
     }
   | {
       readonly status: 'not-merged';
       readonly reason: 'not-published';
-      /** Coder's complete result carrying the reason. */
       readonly coderOutput: string;
     }
   | {
@@ -134,8 +149,7 @@ export type PrPlaybookOutput =
       readonly reason: 'fix-failed';
       readonly pullRequest: string;
       readonly pullRequestUrl: string;
-      /** The relayed canonical `code` result that ended the one fix attempt. */
-      readonly childResult: CompletedChildResult;
+      readonly childResult: CompletedCodeResult;
     }
   | {
       readonly status: 'not-merged';
@@ -143,17 +157,14 @@ export type PrPlaybookOutput =
       readonly pullRequest: string;
       readonly pullRequestUrl: string;
     }
-  /**
-   * The merge command exited nonzero. It ran, so whether GitHub merged the
-   * pull request is unknown — script output never enters context — and the
-   * result claims neither a merge nor its absence.
-   */
   | {
       readonly status: 'merge-unconfirmed';
       readonly pullRequest: string;
       readonly pullRequestUrl: string;
     };
 
+export type PrInput = Readonly<Record<string, never>>;
+
 export type PrCompletion =
   | 'merged'
   | 'not-published'
@@ -162,18 +173,15 @@ export type PrCompletion =
   | 'checks-failed'
   | 'merge-unconfirmed';
 
-/** The machine reads no input: the caller input arrives on `START_PR`. */
-export type PrInput = Readonly<Record<never, never>>;
-
 export type PrContext = {
   readonly callerInput?: string;
   readonly pullRequest?: string;
   readonly pullRequestUrl?: string;
-  readonly completion?: PrCompletion;
-  readonly localDefaultUpdated?: boolean;
   readonly coderOutput?: string;
-  readonly childFailure?: CompletedChildResult;
-  readonly lastError?: unknown;
+  readonly childResult?: CompletedCodeResult;
+  readonly localDefaultUpdated?: boolean;
+  readonly completion?: PrCompletion;
+  readonly lastError?: ErrorRecord;
   readonly pendingBossQuestion?: PendingBossQuestion;
   readonly bossReply?: string;
 };
@@ -186,9 +194,13 @@ export type PrEvent =
       readonly questionId?: 'openPullRequest';
     };
 
+const CALLER_INPUT_PLACEHOLDER = '<caller-input>';
+const PULL_REQUEST_URL_PLACEHOLDER = '<pull-request-url>';
+
+/** The one nested target, shared by `invoke.input` and result validation. */
+const CODE_PLAYBOOK_ID = 'code' as const satisfies PrChildPlaybookId;
+
 const OPEN_PULL_REQUEST_PROMPT = [
-  '> Original request: <caller-input>',
-  '',
   'Publish the branch and open its pull request without changing any file or making any commit.',
   'Confirm that the working tree is clean and that the checked-out branch is the branch to deliver, not the repository default branch.',
   "Push the branch to the repository's GitHub remote with its upstream set; never force-push.",
@@ -196,153 +208,126 @@ const OPEN_PULL_REQUEST_PROMPT = [
   'Give the pull request a title naming the change and a body with a summary of what changed and why from the base revision to the last commit, the verification the commits report, and a `Closes #N` line for issue number N when the request names one.',
   'Report the pull request number and URL exactly.',
   'If the working tree is not clean, the checked-out branch is wrong, the push is rejected, or the pull request cannot be opened, open nothing further 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 OPEN_PULL_REQUEST_RESULTS = {
   opened:
-    'Coder pushed the branch with its upstream set and reported the open pull request for it. Output shall include `pullRequest: <pull request number>` and `pullRequestUrl: <pull request URL>`.',
+    "Coder's result affirmatively supports that the pull request is open. Output shall include `pullRequest: <exact pull request number as reported>` and `pullRequestUrl: <exact pull request URL as reported>`.",
   notPublished:
-    'Coder reported that the branch could not be published or its pull request could not be opened, with the reason. Output shall include `coderOutput: <verbatim final text>`.',
-  needsBossReply: NEEDS_BOSS_REPLY_RESULT,
+    "Coder's result affirmatively supports that the branch or its pull request was not published; the workflow fails and returns Coder's complete result with its reason to its caller. 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>`.",
 } as const;
 
-// The mechanical steps are static POSIX shell text (slc/optimize.md) with no
-// prose. `gh` infers the pull request from the checked-out branch, which the
-// run does not own, so the two steps that act on the pull request itself relay
-// one runtime value — the pull request PR-1 published — through the same
-// placeholder relay an acting prompt uses.
-// The placeholder occupies a single-quoted shell word, and binding replaces
-// that whole word — quotes included — with the value's own quoted literal.
-const QUOTED_PULL_REQUEST_URL = "'<pull-request-url>'";
-
-// A retained value is reported text, so it reaches the shell as one
-// single-quoted literal word: no command substitution, no expansion, no word
-// splitting. A single quote inside the value closes the literal, escapes
-// itself, and reopens it — the only character single quotes cannot hold.
-function shellLiteral(value: string): string {
-  return `'${value.split("'").join("'\\''")}'`;
-}
-
-// Bind the retained identity into a script command. Without it the quoted
-// placeholder stays, and no `gh` output equals it, so the step refuses instead
-// of acting on whatever the checkout now infers. Every script state is
-// reachable only after `rememberPullRequest`, so the refusal is unreachable by
-// construction and exists to keep the failure closed if that ever changes.
-function scriptCommand(command: string, context: PrContext): string {
-  const url = context.pullRequestUrl;
-  if (!isNonEmptyString(url)) return command;
-  // A function replacement keeps `$`-patterns in the value from being read as
-  // replacement syntax.
-  return command.replaceAll(QUOTED_PULL_REQUEST_URL, () => shellLiteral(url));
-}
-
-const WAIT_FOR_CHECKS_COMMAND = [
-  'n=0',
-  "while gh pr checks 2>&1 | grep -q 'no checks reported'; do",
-  'n=$((n + 1))',
-  '[ "$n" -ge 6 ] && exit 0',
-  'sleep 10',
-  'done',
-  'gh pr checks --watch --fail-fast >/dev/null 2>&1',
-].join('\n');
-
-const PUBLISH_FIX_COMMAND = [
-  '[ "$(gh pr view --json url --jq .url)" = \'<pull-request-url>\' ] || exit 1',
-  'git push || exit 1',
-  'n=0',
-  'until [ "$(gh pr view --json headRefOid --jq .headRefOid 2>/dev/null)" = "$(git rev-parse HEAD)" ]; do',
-  'n=$((n + 1))',
-  '[ "$n" -ge 12 ] && exit 1',
-  'sleep 5',
-  'done',
+const CHECK_WAIT_COMMAND = [
+  `n=0`,
+  `while gh pr checks 2>&1 | grep -q 'no checks reported'; do`,
+  `n=$((n + 1))`,
+  `[ "$n" -ge 6 ] && exit 0`,
+  `sleep 10`,
+  `done`,
+  `gh pr checks --watch --fail-fast >/dev/null 2>&1`,
 ].join('\n');
 
-const MERGE_PULL_REQUEST_COMMAND =
-  "pr=$(gh pr view --json url --jq .url) || exit 1\n[ \"$pr\" = '<pull-request-url>' ] || exit 1\nbase=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name) || exit 1\n[ -n \"$base\" ] || exit 1\n[ \"$(gh pr view \"$pr\" --json baseRefName --jq .baseRefName)\" = \"$base\" ] || exit 1\ngh pr merge --merge --delete-branch --match-head-commit \"$(git rev-parse HEAD)\" || exit 1\n[ \"$(gh pr view \"$pr\" --json state --jq .state)\" = MERGED ] || exit 1\n[ \"$(git branch --show-current)\" = \"$base\" ]";
-
-const UPDATE_LOCAL_DEFAULT_COMMAND = 'git pull --ff-only';
-
 const WAIT_FOR_CHECKS_RESULTS = {
   checksPassed:
-    "The command exited with status zero: the pull request's checks passed, or the repository still reported no checks after a brief wait for them to register.",
+    'The command exited with status zero: the checks passed; a pull request whose repository still reports no checks after a brief wait for them to register counts as passed.',
   checksFailed:
-    "The command exited with a nonzero status: the pull request's checks failed.",
+    'The command exited with a nonzero status: the checks failed.',
 } as const;
 
+const PUBLISH_FIX_COMMAND_TEMPLATE = [
+  `[ "$(gh pr view --json url --jq .url)" = '<pull-request-url>' ] || exit 1`,
+  `git push || exit 1`,
+  `n=0`,
+  `until [ "$(gh pr view --json headRefOid --jq .headRefOid 2>/dev/null)" = "$(git rev-parse HEAD)" ]; do`,
+  `n=$((n + 1))`,
+  `[ "$n" -ge 12 ] && exit 1`,
+  `sleep 5`,
+  `done`,
+].join('\n');
+
 const PUBLISH_FIX_RESULTS = {
   fixPublished:
-    "The command exited with status zero: the fix is pushed and the pull request's head is the pushed commit.",
+    "The command exited with status zero, once the pull request's head is the pushed commit: the fix is published.",
   fixNotPublished:
-    "The command exited with a nonzero status: the checkout no longer infers the published pull request, the push was rejected, or the pull request's head did not advance to the pushed commit.",
+    'The command exited with a nonzero status: the fix is not published, an authored failure of the workflow that leaves the pull request open.',
 } as const;
 
-const WAIT_FOR_CHECKS_AFTER_FIX_RESULTS = {
-  checksPassed:
-    "The command exited with status zero: the pull request's checks passed after the fix, or the repository still reported no checks after a brief wait for them to register.",
+const WAIT_FOR_FIX_CHECKS_RESULTS = {
+  checksPassed: 'The command exited with status zero: the checks passed.',
   checksStillFailing:
-    "The command exited with a nonzero status: the pull request's checks are still failing after the one fix attempt.",
+    'The command exited with a nonzero status: the checks are still failing, an authored failure of the workflow that leaves the pull request open; there is no second fix attempt.',
 } as const;
 
-const MERGE_PULL_REQUEST_RESULTS = {
-  merged:
-    'The command exited with status zero: the pull request targeted the repository default branch and is merged into it with a merge commit, deletion of the remote and local branch was requested, and the local default branch is checked out.',
+const MERGE_COMMAND_TEMPLATE = [
+  `pr=$(gh pr view --json url --jq .url) || exit 1`,
+  `[ "$pr" = '<pull-request-url>' ] || exit 1`,
+  `base=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name) || exit 1`,
+  `[ -n "$base" ] || exit 1`,
+  `[ "$(gh pr view "$pr" --json baseRefName --jq .baseRefName)" = "$base" ] || exit 1`,
+  `gh pr merge --merge --delete-branch --match-head-commit "$(git rev-parse HEAD)" || exit 1`,
+  `[ "$(gh pr view "$pr" --json state --jq .state)" = MERGED ] || exit 1`,
+  `[ "$(git branch --show-current)" = "$base" ]`,
+].join('\n');
+
+const MERGE_RESULTS = {
+  merged: 'The command exited with status zero: the pull request is merged.',
   mergeRefused:
-    'The command exited with a nonzero status: the checkout no longer infers the published pull request, the pull request does not target the repository default branch, GitHub refused the merge, its merged state could not be confirmed, or the local switch to the default branch or the branch deletion failed.',
+    'The command exited with a nonzero status: the merge is refused, an authored failure of the workflow that leaves the pull request in the state GitHub reports, because the checkout no longer infers the published pull request, the pull request targets another branch, GitHub refused the merge for a conflict, a branch protection, a forbidden merge method, or a head that moved, or the merge may have landed while its confirmation, the local switch to the default branch, or the branch deletion failed; a refused merge does not establish that the pull request is unmerged, so the workflow reports it as an unconfirmed merge rather than as not merged.',
 } as const;
 
-const UPDATE_LOCAL_DEFAULT_RESULTS = {
+const LOCAL_UPDATE_COMMAND = `git pull --ff-only`;
+
+const LOCAL_UPDATE_RESULTS = {
   localDefaultUpdated:
-    'The command exited with status zero: the local default branch is fast-forwarded to the merged head.',
+    'The command exited with status zero: the local default branch is updated; the workflow completes, returning the pull request number and URL, the fact that the pull request is merged, and that the local default branch was fast-forwarded to the merged head.',
   localDefaultNotUpdated:
-    'The command exited with a nonzero status: the local default branch was not fast-forwarded to the merged head.',
+    'The command exited with a nonzero status: the local default branch is not updated; the workflow completes, since the pull request is merged either way, returning the pull request number and URL, the fact that the pull request is merged, and that the local default branch was not fast-forwarded to the merged head.',
 } as const;
 
-// PR-3's coding request is static prompt text of the nested call template.
 const FIX_CODING_REQUEST =
   "The pull request's checks are red on the checked-out branch. Inspect the failing checks with `gh pr checks` and `gh run view --log-failed`, fix their cause on this branch with a minimal change, and make the checks pass.";
 
 const STATE_DESCRIPTIONS = {
-  ready: 'Waiting for the caller input that names the branch to deliver.',
+  ready: 'Waiting for a reviewed branch to deliver through a pull request.',
   openPullRequest:
-    'Coder is publishing the branch and opening its pull request.',
-  waitForChecks:
-    "Waiting for the pull request's checks to settle before any fix attempt.",
+    'Coder is publishing the branch and opening its pull request without changing any file or making any commit.',
+  awaitBossReply: "Waiting for Boss to answer the acting agent's question.",
+  waitForChecks: "Waiting for the pull request's checks before any fix attempt.",
   fixChecks:
-    'The CODE playbook is fixing the cause of the red checks on the checked-out branch.',
+    "The CODE playbook is making the one fix attempt for the pull request's failing checks.",
   publishFix:
-    "Publishing the fix to the pull request and waiting for the pull request's head to reach the pushed commit.",
-  waitForChecksAfterFix:
-    "Waiting for the pull request's checks to settle after the one fix attempt.",
+    'Pushing the fix to the published pull request and waiting until its head is the pushed commit.',
+  waitForFixChecks:
+    "Waiting for the pull request's checks after the one fix attempt.",
   mergePullRequest:
-    'Merging the pull request into the repository default branch.',
+    'Merging the published pull request into the repository default branch and confirming the merge.',
   updateLocalDefault:
     'Fast-forwarding the local default branch to the merged head.',
-  awaitBossReply: 'Waiting for Boss to answer Coder.',
   failed:
-    'The pull-request delivery workflow failed and is waiting for new caller input.',
-  merged:
-    'The pull request is merged with a merge commit on the repository default branch, which is checked out and fast-forwarded to the merged head; the merge requested deletion of the remote and local branch.',
-  mergedLocalBehind:
-    'The pull request is merged with a merge commit on the repository default branch, which is checked out but could not be fast-forwarded to the merged head; the merge requested deletion of the remote and local branch.',
+    'The pull-request workflow failed outside its authored outcomes and is waiting for a new delivery request.',
+  mergedLocalUpdated:
+    'The pull request is merged and the local default branch was fast-forwarded to the merged head.',
+  mergedLocalNotUpdated:
+    'The pull request is merged, but the local default branch was not fast-forwarded to the merged head.',
   notPublished:
-    'The branch was not published or its pull request could not be opened; Coder reported the reason and no pull request is guaranteed to exist.',
+    "The branch or its pull request was not published; the workflow failed with Coder's complete result and its reason.",
   fixFailed:
-    "The pull request's checks were red and the single CODE fix attempt returned an authored abort, failure, or insufficient terminal result; the pull request remains open.",
+    "The one CODE fix attempt ended in an authored abort or failure, or a terminal result that did not prove its success; the workflow failed relaying that result and left the pull request open.",
   fixNotPublished:
-    "The fix could not be published: the checked-out branch no longer carries the published pull request, the push was rejected, or the pull request's head did not advance to the pushed commit; the pull request remains open.",
-  checksStillFailing:
-    "The pull request's checks are still failing after the one fix attempt; the pull request remains open.",
-  mergeRefused:
-    'The merge did not complete: the checked-out branch no longer carries the published pull request, the pull request does not target the repository default branch, GitHub refused the merge, or the merge may have landed while its confirmation, the local switch to the default branch, or the branch deletion failed; the pull request is in the state GitHub reports.',
+    'The fix was not published; the workflow failed and left the pull request open.',
+  checksFailed:
+    'The checks are still failing after the one fix attempt; the workflow failed and left the pull request open.',
+  mergeUnconfirmed:
+    'The merge was refused or could not be confirmed; the workflow failed with an unconfirmed merge, leaving the pull request in the state GitHub reports.',
 } as const;
 
-function playbookMeta<StateId extends keyof typeof STATE_DESCRIPTIONS>(
-  stateId: StateId,
-  role?: 'coder',
-) {
+type DescribedStateId = keyof typeof STATE_DESCRIPTIONS;
+
+function playbookMeta(stateId: DescribedStateId, role?: 'coder') {
   return {
     playbook: {
       stateId,
@@ -352,11 +337,8 @@ function playbookMeta<StateId extends keyof typeof STATE_DESCRIPTIONS>(
   };
 }
 
-// DR-048: a final state additionally declares whether its outcome means the
-// workflow succeeded or failed, so PR's own caller learns that from the
-// machine rather than from PR's output fields.
-function terminalMeta<StateId extends keyof typeof STATE_DESCRIPTIONS>(
-  stateId: StateId,
+function terminalMeta(
+  stateId: DescribedStateId,
   terminal: 'success' | 'failure',
 ) {
   return {
@@ -380,23 +362,134 @@ function isNonEmptyString(value: unknown): value is string {
   return typeof value === 'string' && value.trim().length > 0;
 }
 
+function isCanonicalIndex(key: string, length: number): boolean {
+  return /^(0|[1-9][0-9]*)$/.test(key) && Number(key) < length;
+}
+
+/** Strict JSON validation; tracks only the active recursion path. */
+function isJsonValue(value: unknown, path: Set<object> = new Set()): boolean {
+  if (value === null) return true;
+  switch (typeof value) {
+    case 'boolean':
+    case 'string':
+      return true;
+    case 'number':
+      return Number.isFinite(value);
+    case 'object':
+      break;
+    default:
+      return false;
+  }
+  const container = value as object;
+  if (path.has(container)) return false;
+  path.add(container);
+  try {
+    if (Array.isArray(container)) {
+      if (Object.getPrototypeOf(container) !== Array.prototype) return false;
+      const length = container.length;
+      const keys = Reflect.ownKeys(container);
+      if (keys.length !== length + 1) return false;
+      for (const key of keys) {
+        if (typeof key !== 'string') return false;
+        const descriptor = Object.getOwnPropertyDescriptor(container, key);
+        if (descriptor === undefined || !('value' in descriptor)) return false;
+        if (key === 'length') {
+          if (descriptor.enumerable || descriptor.configurable) return false;
+          if (descriptor.value !== length) return false;
+          continue;
+        }
+        if (!isCanonicalIndex(key, length) || !descriptor.enumerable) {
+          return false;
+        }
+        if (!isJsonValue(descriptor.value, path)) return false;
+      }
+      return true;
+    }
+    if (!isRecord(container)) return false;
+    for (const key of Reflect.ownKeys(container)) {
+      if (typeof key !== 'string') return false;
+      const descriptor = Object.getOwnPropertyDescriptor(container, key);
+      if (
+        descriptor === undefined ||
+        !descriptor.enumerable ||
+        !('value' in descriptor)
+      ) {
+        return false;
+      }
+      if (!isJsonValue(descriptor.value, path)) return false;
+    }
+    return true;
+  } finally {
+    path.delete(container);
+  }
+}
+
+function normalizeError(error: unknown): ErrorRecord {
+  if (error instanceof Error) {
+    return {
+      name: error.name || 'Error',
+      message: error.message,
+      ...(typeof error.stack === 'string' ? { stack: error.stack } : {}),
+    };
+  }
+  return { name: 'Error', message: String(error) };
+}
+
+/** Binds a value as its own single-quoted shell literal. */
+function shellLiteral(value: string): string {
+  return `'${value.split("'").join("'\\''")}'`;
+}
+
+/**
+ * Replaces the single-quoted `'<pull-request-url>'` shell word, quotes
+ * included, with the bound literal; an absent value keeps the placeholder.
+ */
+function bindPullRequestUrl(template: string, context: PrContext): string {
+  const url = context.pullRequestUrl;
+  if (url === undefined) return template;
+  return template
+    .split(`'${PULL_REQUEST_URL_PLACEHOLDER}'`)
+    .join(shellLiteral(url));
+}
+
+/** Quoted relay: empty values add no line; multi-line values quote each line. */
+function quotedRelay(values: readonly (readonly [string, string])[]): string {
+  return values
+    .filter(([, value]) => value.length > 0)
+    .map(([label, value]) =>
+      `${label}: ${value}`
+        .split('\n')
+        .map((line) => `> ${line}`)
+        .join('\n'),
+    )
+    .join('\n');
+}
+
+function fixCallText(context: PrContext): string {
+  return quotedRelay([
+    ['Original request', context.callerInput ?? CALLER_INPUT_PLACEHOLDER],
+    ['Pull request', context.pullRequestUrl ?? PULL_REQUEST_URL_PLACEHOLDER],
+    ['Coding request', FIX_CODING_REQUEST],
+  ]);
+}
+
 function actorOutput(event: unknown): Record<string, unknown> | undefined {
   if (!isRecord(event)) return undefined;
   return isRecord(event.output) ? event.output : undefined;
 }
 
-function outputGuard(event: unknown, guard: string): boolean {
-  return actorOutput(event)?.guard === guard;
-}
-
 function outputString(event: unknown, field: string): string | undefined {
   const value = actorOutput(event)?.[field];
   return isNonEmptyString(value) ? value : undefined;
 }
 
+function playerGuard(event: unknown, guard: PlayerOutput['guard']): boolean {
+  return actorOutput(event)?.guard === guard;
+}
+
 function isOpened({ event }: { event: unknown }): boolean {
   return (
-    outputGuard(event, 'opened') &&
+    playerGuard(event, 'opened') &&
     outputString(event, 'pullRequest') !== undefined &&
     outputString(event, 'pullRequestUrl') !== undefined
   );
@@ -404,40 +497,29 @@ function isOpened({ event }: { event: unknown }): boolean {
 
 function isNotPublished({ event }: { event: unknown }): boolean {
   return (
-    outputGuard(event, 'notPublished') &&
+    playerGuard(event, 'notPublished') &&
     outputString(event, 'coderOutput') !== undefined
   );
 }
 
 function needsBossReply({ event }: { event: unknown }): boolean {
   return (
-    outputGuard(event, 'needsBossReply') &&
+    playerGuard(event, 'needsBossReply') &&
     outputString(event, 'question') !== undefined
   );
 }
 
-// A script actor resolves mechanically from the exit status: the first
-// declared guard with status zero, the second with the nonzero status.
-function scriptExitStatus(event: unknown): number | undefined {
-  const value = actorOutput(event)?.exitStatus;
-  return Number.isInteger(value) ? (value as number) : undefined;
-}
-
-function zeroExitGuard(
-  guard: ScriptOutput['guard'],
-): (args: { event: unknown }) => boolean {
-  return ({ event }) =>
-    outputGuard(event, guard) && scriptExitStatus(event) === 0;
-}
-
-function nonzeroExitGuard(
+/** Script outcome: the declared guard, consistent with its exit status. */
+function scriptOutcome(
   guard: ScriptOutput['guard'],
+  exit: 'zero' | 'nonzero',
 ): (args: { event: unknown }) => boolean {
   return ({ event }) => {
-    const exitStatus = scriptExitStatus(event);
-    return (
-      outputGuard(event, guard) && exitStatus !== undefined && exitStatus !== 0
-    );
+    const output = actorOutput(event);
+    if (output === undefined || output.guard !== guard) return false;
+    const status = output.exitStatus;
+    if (typeof status !== 'number' || !Number.isInteger(status)) return false;
+    return exit === 'zero' ? status === 0 : status !== 0;
   };
 }
 
@@ -445,309 +527,95 @@ function childOutputOf(event: unknown): unknown {
   return isRecord(event) ? event.output : undefined;
 }
 
-// CODE's canonical successful terminal output discriminates completion with
-// `status: 'complete'`, carries the exact last CODE-owned commit, and
-// affirms that every phase's review passed.
-function isCodeSuccessValue(value: unknown): boolean {
-  return (
-    isRecord(value) &&
-    value.status === 'complete' &&
-    isNonEmptyString(value.lastCodeCommit) &&
-    value.allReviewsPassed === true
-  );
-}
-
+/**
+ * The public success variant of the `code` output interface: CODE completed
+ * with every review passed, naming its last commit and evaluated revision.
+ */
 function isCodeSuccess({ event }: { event: unknown }): boolean {
-  return isCodeSuccessValue(childOutputOf(event));
-}
-
-function isStateValue(value: unknown, ancestors = new Set<object>()): boolean {
-  if (typeof value === 'string') return true;
-  if (!isRecord(value) || ancestors.has(value)) return false;
-  const next = new Set(ancestors).add(value);
-  return Reflect.ownKeys(value).every(
-    (key) =>
-      typeof key === 'string' &&
-      Object.prototype.propertyIsEnumerable.call(value, key) &&
-      isStateValue(value[key], next),
-  );
-}
-
-function isStringArray(value: unknown): value is readonly string[] {
+  const output = childOutputOf(event);
   return (
-    Array.isArray(value) &&
-    Reflect.ownKeys(value).length === value.length + 1 &&
-    Reflect.ownKeys(value).every((key) => {
-      if (key === 'length') return true;
-      return (
-        typeof key === 'string' &&
-        /^(0|[1-9][0-9]*)$/.test(key) &&
-        Number(key) < value.length
-      );
-    }) &&
-    value.every((entry) => isNonEmptyString(entry)) &&
-    new Set(value).size === value.length
+    isRecord(output) &&
+    output.status === 'complete' &&
+    isNonEmptyString(output.lastCodeCommit) &&
+    isNonEmptyString(output.finalEvaluatedRevision) &&
+    output.allReviewsPassed === true
   );
 }
 
-function isPlaybookState(value: unknown): boolean {
-  if (!isRecord(value)) return false;
-  const allowed = new Set([
-    'value',
-    'activeStateIds',
-    'tags',
-    'status',
-    'quiescent',
-    'stateId',
-  ]);
-  if (
-    Reflect.ownKeys(value).some(
-      (key) => typeof key !== 'string' || !allowed.has(key),
-    ) ||
-    !Object.prototype.hasOwnProperty.call(value, 'value') ||
-    !Object.prototype.hasOwnProperty.call(value, 'activeStateIds') ||
-    !Object.prototype.hasOwnProperty.call(value, 'tags') ||
-    !Object.prototype.hasOwnProperty.call(value, 'status') ||
-    !Object.prototype.hasOwnProperty.call(value, 'quiescent')
-  ) {
-    return false;
-  }
-  return (
-    isStateValue(value.value) &&
-    isStringArray(value.activeStateIds) &&
-    isStringArray(value.tags) &&
-    (value.status === 'active' ||
-      value.status === 'done' ||
-      value.status === 'error' ||
-      value.status === 'stopped') &&
-    typeof value.quiescent === 'boolean' &&
-    (!Object.prototype.hasOwnProperty.call(value, 'stateId') ||
-      (isNonEmptyString(value.stateId) &&
-        value.activeStateIds.length === 1 &&
-        value.activeStateIds[0] === value.stateId))
-  );
+/** A delivered CODE result that does not prove success, as valid JSON. */
+function isInsufficientCodeResult({ event }: { event: unknown }): boolean {
+  const output = childOutputOf(event);
+  return output === undefined || isJsonValue(output);
 }
 
-function nestedResultFromError(
+export function authoredChildResult(
   error: unknown,
-): Record<string, unknown> | undefined {
+  expectedPlaybookId: string,
+): PlaybookCallResult | undefined {
   if (!(error instanceof Error)) return undefined;
-  const result = (error as Error & { readonly result?: unknown }).result;
-  return isRecord(result) ? result : undefined;
-}
-
-type AuthoredChildFailure =
-  | {
-      readonly status: 'aborted' | 'error';
-      readonly error?: CompactError;
-    }
-  // DR-048: a child that completed at an authored failure terminal. The
-  // bridge rejects it through the same error path, so PR recognizes the
-  // failure from the child's own machine and never from its output fields.
-  | {
-      readonly status: 'ok';
-      readonly output?: JsonValue;
-    };
-
-function isFailureTerminalRecord(value: unknown): boolean {
-  if (!isRecord(value)) return false;
-  const allowed = new Set(['stateId', 'kind', 'description']);
-  return (
-    Reflect.ownKeys(value).every(
-      (key) => typeof key === 'string' && allowed.has(key),
-    ) &&
-    isNonEmptyString(value.stateId) &&
-    value.kind === 'failure' &&
-    (!Object.prototype.hasOwnProperty.call(value, 'description') ||
-      typeof value.description === 'string')
-  );
-}
-
-function normalizedChildFailure(
-  error: unknown,
-  playbookId: PrChildPlaybookId,
-): AuthoredChildFailure | undefined {
-  const result = nestedResultFromError(error);
-  if (result === undefined) return undefined;
-  const allowed = new Set([
-    'status',
-    'playbookId',
-    'childSessionId',
-    'state',
-    ...(result.status === 'ok' ? ['output', 'terminal'] : ['error']),
-  ]);
-  if (
-    Reflect.ownKeys(result).some(
-      (key) => typeof key !== 'string' || !allowed.has(key),
-    ) ||
-    (result.status !== 'aborted' &&
-      result.status !== 'error' &&
-      result.status !== 'ok') ||
-    result.playbookId !== playbookId
-  ) {
-    return undefined;
-  }
-  if (
-    Object.prototype.hasOwnProperty.call(result, 'childSessionId') &&
-    !isNonEmptyString(result.childSessionId)
-  ) {
-    return undefined;
-  }
-  if (result.status === 'ok') {
-    if (
-      !Object.prototype.hasOwnProperty.call(result, 'terminal') ||
-      !isFailureTerminalRecord(result.terminal) ||
-      !isNonEmptyString(result.childSessionId) ||
-      (Object.prototype.hasOwnProperty.call(result, 'state') &&
-        !isPlaybookState(result.state))
-    ) {
-      return undefined;
-    }
-    return {
-      status: 'ok',
-      ...(result.output === undefined
-        ? {}
-        : { output: result.output as JsonValue }),
-    };
-  }
-  if (
-    Object.prototype.hasOwnProperty.call(result, 'state') &&
-    !isPlaybookState(result.state)
-  ) {
-    return undefined;
-  }
-  let normalizedError: CompactError | undefined;
-  if (Object.prototype.hasOwnProperty.call(result, 'error')) {
-    if (!isRecord(result.error)) return undefined;
-    const errorKeys = Reflect.ownKeys(result.error);
-    if (
-      errorKeys.some(
-        (key) =>
-          typeof key !== 'string' ||
-          (key !== 'name' && key !== 'message' && key !== 'stack'),
-      ) ||
-      !Object.prototype.hasOwnProperty.call(result.error, 'name') ||
-      !Object.prototype.hasOwnProperty.call(result.error, 'message') ||
-      !isNonEmptyString(result.error.name) ||
-      typeof result.error.message !== 'string' ||
-      (Object.prototype.hasOwnProperty.call(result.error, 'stack') &&
-        typeof result.error.stack !== 'string')
-    ) {
-      return undefined;
-    }
-    normalizedError = {
-      name: result.error.name,
-      message: result.error.message,
-    };
-  } else if (result.status === 'error') {
+  try {
+    const result = validatePlaybookCallResult(
+      (error as Error & { result?: unknown }).result,
+      expectedPlaybookId,
+    );
+    return result.status !== 'ok' || result.terminal?.kind === 'failure'
+      ? result
+      : undefined;
+  } catch {
     return undefined;
   }
-  return {
-    status: result.status,
-    ...(normalizedError === undefined ? {} : { error: normalizedError }),
-  };
 }
 
-function authoredChildFailureGuard(
-  playbookId: PrChildPlaybookId,
-): (args: { event: unknown }) => boolean {
-  return ({ event }) => {
-    const error = isRecord(event) ? event.error : undefined;
-    return normalizedChildFailure(error, playbookId) !== undefined;
-  };
+function eventError(event: unknown): unknown {
+  return isRecord(event) ? event.error : undefined;
 }
 
-function authoredChildError(
-  event: unknown,
-  playbookId: PrChildPlaybookId,
-): CompactError {
-  const outer = isRecord(event) ? event.error : undefined;
-  const failure = normalizedChildFailure(outer, playbookId);
-  if (failure !== undefined && failure.status !== 'ok' && failure.error) {
-    return failure.error;
-  }
-  if (failure?.status === 'aborted') {
-    return {
-      name: 'AbortError',
-      message: `${playbookId.toUpperCase()} was aborted.`,
-    };
-  }
-  if (outer instanceof Error) {
-    return { name: outer.name || 'Error', message: outer.message };
-  }
-  return { name: 'Error', message: String(outer) };
+function isAuthoredCodeFailure({ event }: { event: unknown }): boolean {
+  return authoredChildResult(eventError(event), CODE_PLAYBOOK_ID) !== undefined;
 }
 
-function relayedChildFailure(
-  event: unknown,
-  playbookId: PrChildPlaybookId,
-): CompletedChildResult {
-  const outer = isRecord(event) ? event.error : undefined;
-  const failure = normalizedChildFailure(outer, playbookId);
-  // DR-048: a completed child that reached an authored failure terminal
-  // relays its own output, exactly as a terminal result that did not prove
-  // success does through the retained onDone field check.
-  if (failure?.status === 'ok') {
+function relayedCodeResult(event: unknown): CompletedCodeResult | undefined {
+  const result = authoredChildResult(eventError(event), CODE_PLAYBOOK_ID);
+  if (result === undefined) return undefined;
+  if (result.status === 'ok') {
     return {
-      playbookId,
+      playbookId: CODE_PLAYBOOK_ID,
       status: 'ok',
-      ...(failure.output === undefined ? {} : { output: failure.output }),
+      ...(result.output === undefined ? {} : { output: result.output }),
     };
   }
-  return {
-    playbookId,
-    status: failure?.status === 'aborted' ? 'aborted' : 'error',
-    error: authoredChildError(event, playbookId),
-  };
+  const error: CompactError =
+    result.error === undefined
+      ? {
+          name: 'AbortError',
+          message: `${CODE_PLAYBOOK_ID.toUpperCase()} was aborted.`,
+        }
+      : { name: result.error.name, message: result.error.message };
+  return { playbookId: CODE_PLAYBOOK_ID, status: result.status, error };
 }
 
-function insufficientChildResult(
-  event: unknown,
-  playbookId: PrChildPlaybookId,
-): CompletedChildResult {
+function insufficientCodeResult(event: unknown): CompletedCodeResult {
   const output = childOutputOf(event);
   return {
-    playbookId,
+    playbookId: CODE_PLAYBOOK_ID,
     status: 'ok',
-    ...(output === undefined ? {} : { output: output as JsonValue }),
+    ...(output === undefined || !isJsonValue(output)
+      ? {}
+      : { output: output as JsonValue }),
   };
 }
 
-function quotedRelay(values: readonly (readonly [string, string])[]): string {
-  return values
-    .filter(([, value]) => value.length > 0)
-    .map(([label, value]) =>
-      `${label}: ${value}`
-        .split('\n')
-        .map((line) => `> ${line}`)
-        .join('\n'),
-    )
-    .join('\n');
-}
-
-/** PR-3's composed child input: the caller input, the pull request, and the static coding request. */
-export function fixChecksCallText(context: PrContext): string {
-  return quotedRelay([
-    ['Original request', context.callerInput ?? ''],
-    ['Pull request', context.pullRequestUrl ?? ''],
-    ['Coding request', FIX_CODING_REQUEST],
-  ]);
-}
-
-function pullRequestIdentity(context: PrContext): {
-  readonly pullRequest: string;
-  readonly pullRequestUrl: string;
-} {
-  if (
-    !isNonEmptyString(context.pullRequest) ||
-    !isNonEmptyString(context.pullRequestUrl)
-  ) {
-    throw new Error('PR reached a final state without its pull request identity');
-  }
-  return {
-    pullRequest: context.pullRequest,
-    pullRequestUrl: context.pullRequestUrl,
-  };
+function resumableStates(ids: readonly ResumableStateId[]) {
+  return ids.map((id) => ({
+    guard: ({ context, event }: { context: PrContext; event: PrEvent }) =>
+      event.type === 'BOSS_REPLY' &&
+      event.answer.trim().length > 0 &&
+      context.pendingBossQuestion?.resumeStateId === id &&
+      (event.questionId === undefined || event.questionId === id),
+    target: `#${id}` as const,
+    reenter: true,
+    actions: 'rememberBossReply' as const,
+  }));
 }
 
 const machineSetup = setup({
@@ -761,7 +629,7 @@ const machineSetup = setup({
     player: fromPromise<PlayerOutput, PlayerInput>(async () => {
       throw new Error('player actor must be provided by the runner');
     }),
-    playbook: fromPromise<JsonValue | undefined, PlaybookInput>(async () => {
+    playbook: fromPromise<PlaybookOutput, PlaybookInput>(async () => {
       throw new Error('playbook actor must be provided by the runner');
     }),
     script: fromPromise<ScriptOutput, ScriptInput>(async () => {
@@ -769,28 +637,26 @@ const machineSetup = setup({
     }),
   },
   guards: {
+    validStartPr: ({ event }) =>
+      event.type === 'START_PR' && isNonEmptyString(event.callerInput),
     isOpened,
     isNotPublished,
     needsBossReply,
-    checksPassed: zeroExitGuard('checksPassed'),
-    checksFailed: nonzeroExitGuard('checksFailed'),
-    isCodeSuccess,
-    authoredCodeFailure: authoredChildFailureGuard('code'),
-    fixPublished: zeroExitGuard('fixPublished'),
-    fixNotPublished: nonzeroExitGuard('fixNotPublished'),
-    checksStillFailing: nonzeroExitGuard('checksStillFailing'),
-    merged: zeroExitGuard('merged'),
-    mergeRefused: nonzeroExitGuard('mergeRefused'),
-    localDefaultUpdated: zeroExitGuard('localDefaultUpdated'),
-    localDefaultNotUpdated: nonzeroExitGuard('localDefaultNotUpdated'),
     emptyBossReply: ({ event }) =>
       event.type === 'BOSS_REPLY' && event.answer.trim().length === 0,
-    resumesOpenPullRequest: ({ context, event }) =>
-      event.type === 'BOSS_REPLY' &&
-      event.answer.trim().length > 0 &&
-      context.pendingBossQuestion?.resumeStateId === 'openPullRequest' &&
-      (event.questionId === undefined ||
-        event.questionId === 'openPullRequest'),
+    waitForChecksPassed: scriptOutcome('checksPassed', 'zero'),
+    waitForChecksFailed: scriptOutcome('checksFailed', 'nonzero'),
+    isCodeSuccess,
+    isInsufficientCodeResult,
+    isAuthoredCodeFailure,
+    fixPublished: scriptOutcome('fixPublished', 'zero'),
+    fixNotPublished: scriptOutcome('fixNotPublished', 'nonzero'),
+    waitForFixChecksPassed: scriptOutcome('checksPassed', 'zero'),
+    checksStillFailing: scriptOutcome('checksStillFailing', 'nonzero'),
+    merged: scriptOutcome('merged', 'zero'),
+    mergeRefused: scriptOutcome('mergeRefused', 'nonzero'),
+    localDefaultUpdated: scriptOutcome('localDefaultUpdated', 'zero'),
+    localDefaultNotUpdated: scriptOutcome('localDefaultNotUpdated', 'nonzero'),
   },
   actions: {
     'playbook.acceptedOutcome': (
@@ -807,143 +673,169 @@ const machineSetup = setup({
         callerInput: event.callerInput,
         pullRequest: undefined,
         pullRequestUrl: undefined,
-        completion: undefined,
-        localDefaultUpdated: undefined,
         coderOutput: undefined,
-        childFailure: undefined,
+        childResult: undefined,
+        localDefaultUpdated: undefined,
+        completion: undefined,
         lastError: undefined,
         pendingBossQuestion: undefined,
         bossReply: undefined,
       };
     }),
-    rememberPullRequest: assign(({ event }) => ({
+    rememberOpened: assign(({ event }) => ({
       pullRequest: outputString(event, 'pullRequest'),
       pullRequestUrl: outputString(event, 'pullRequestUrl'),
-      pendingBossQuestion: undefined,
-      bossReply: undefined,
     })),
     completeNotPublished: assign(({ event }) => ({
-      completion: 'not-published' as const,
       coderOutput: outputString(event, 'coderOutput'),
-      pendingBossQuestion: undefined,
-      bossReply: undefined,
+      completion: 'not-published' as const,
     })),
-    rememberPendingQuestion: assign(({ event }) => {
+    setPendingBossQuestion: assign(({ event }) => {
       const question = outputString(event, 'question');
-      if (question === undefined || !outputGuard(event, 'needsBossReply')) {
-        return { lastError: new Error('Coder question output was malformed') };
-      }
-      return {
-        pendingBossQuestion: {
-          questionId: 'openPullRequest' as const,
-          resumeStateId: 'openPullRequest' as const,
-          sourceItem: 'PR-1' as const,
-          asker: { kind: 'role' as const, roleId: 'coder' as const },
-          question,
-        },
-        bossReply: undefined,
+      if (question === undefined) return {};
+      const pending: PendingBossQuestion = {
+        questionId: 'openPullRequest',
+        resumeStateId: 'openPullRequest',
+        sourceItem: 'PR-1',
+        asker: { kind: 'role', roleId: 'coder' },
+        question,
       };
+      return { pendingBossQuestion: pending, bossReply: undefined };
+    }),
+    clearBossReplyContext: assign({
+      pendingBossQuestion: undefined,
+      bossReply: undefined,
     }),
     rememberBossReply: assign(({ event }) =>
       event.type === 'BOSS_REPLY' ? { bossReply: event.answer } : {},
     ),
     rememberEmptyBossReplyError: assign({
-      lastError: () => new Error('BOSS_REPLY received an empty answer'),
+      lastError: (): ErrorRecord => ({
+        name: 'Error',
+        message: 'BOSS_REPLY received an empty answer',
+      }),
       pendingBossQuestion: undefined,
       bossReply: undefined,
     }),
+    completeWithCodeFailure: assign(({ event }) => {
+      const childResult = relayedCodeResult(event);
+      return childResult === undefined
+        ? {}
+        : { childResult, completion: 'fix-failed' as const };
+    }),
     completeWithInsufficientCodeResult: assign(({ event }) => ({
+      childResult: insufficientCodeResult(event),
       completion: 'fix-failed' as const,
-      childFailure: insufficientChildResult(event, 'code'),
-    })),
-    completeWithCodeFailure: assign(({ event }) => ({
-      completion: 'fix-failed' as const,
-      childFailure: relayedChildFailure(event, 'code'),
     })),
     completeFixNotPublished: assign({
       completion: 'fix-not-published' as const,
     }),
-    completeChecksStillFailing: assign({
-      completion: 'checks-failed' as const,
-    }),
-    completeMergeRefused: assign({
+    completeChecksFailed: assign({ completion: 'checks-failed' as const }),
+    completeMergeUnconfirmed: assign({
       completion: 'merge-unconfirmed' as const,
     }),
-    completeMerged: assign({
+    completeMergedLocalUpdated: assign({
       completion: 'merged' as const,
       localDefaultUpdated: true,
     }),
-    completeMergedLocalBehind: assign({
+    completeMergedLocalNotUpdated: assign({
       completion: 'merged' as const,
       localDefaultUpdated: false,
     }),
     rememberActorError: assign(({ event }) => ({
-      lastError: (event as unknown as { readonly error?: unknown }).error,
+      lastError: normalizeError(eventError(event)),
     })),
     rememberMalformedPlayerOutput: assign({
-      lastError: () =>
-        new Error('Coder result for PR-1 did not match an available outcome.'),
+      lastError: (): ErrorRecord => ({
+        name: 'Error',
+        message: 'Coder result for PR-1 did not match an available outcome.',
+      }),
     }),
-    rememberMalformedScriptOutput: assign(
-      (_args, params: { readonly sourceItem: PrScriptSourceItem }) => ({
-        lastError: new Error(
-          `Script result for ${params.sourceItem} did not match a declared outcome.`,
-        ),
+    rememberMalformedScriptOutput: assign({
+      lastError: (): ErrorRecord => ({
+        name: 'Error',
+        message: 'Script result did not match its declared outcomes.',
       }),
-    ),
+    }),
+    rememberMalformedChildOutput: assign({
+      lastError: (): ErrorRecord => ({
+        name: 'TypeError',
+        message: 'CODE delivered output that is not JSON-safe.',
+      }),
+    }),
   },
 });
 
+function pullRequestIdentity(context: PrContext): {
+  readonly pullRequest: string;
+  readonly pullRequestUrl: string;
+} {
+  if (
+    !isNonEmptyString(context.pullRequest) ||
+    !isNonEmptyString(context.pullRequestUrl)
+  ) {
+    throw new Error(
+      'PR reached a final state without the reported pull request number and URL',
+    );
+  }
+  return {
+    pullRequest: context.pullRequest,
+    pullRequestUrl: context.pullRequestUrl,
+  };
+}
+
 export const prMachine = machineSetup.createMachine({
   id: 'pr',
   initial: 'ready',
-  context: () => ({}),
+  context: {},
   output: ({ context }): PrPlaybookOutput => {
-    if (context.completion === 'merged') {
-      return {
-        status: 'merged',
-        ...pullRequestIdentity(context),
-        localDefaultUpdated: context.localDefaultUpdated === true,
-      };
-    }
-    if (context.completion === 'not-published') {
-      if (!isNonEmptyString(context.coderOutput)) {
-        throw new Error("PR reached notPublished without Coder's result");
+    switch (context.completion) {
+      case 'merged': {
+        if (typeof context.localDefaultUpdated !== 'boolean') {
+          throw new Error('PR reached merged without the local update fact');
+        }
+        return {
+          status: 'merged',
+          ...pullRequestIdentity(context),
+          localDefaultUpdated: context.localDefaultUpdated,
+        };
       }
-      return {
-        status: 'not-merged',
-        reason: 'not-published',
-        coderOutput: context.coderOutput,
-      };
-    }
-    if (context.completion === 'fix-failed') {
-      if (context.childFailure === undefined) {
-        throw new Error('PR reached fixFailed without a child result');
+      case 'not-published': {
+        if (!isNonEmptyString(context.coderOutput)) {
+          throw new Error("PR reached not-published without Coder's report");
+        }
+        return {
+          status: 'not-merged',
+          reason: 'not-published',
+          coderOutput: context.coderOutput,
+        };
       }
-      return {
-        status: 'not-merged',
-        reason: 'fix-failed',
-        ...pullRequestIdentity(context),
-        childResult: context.childFailure,
-      };
-    }
-    if (context.completion === 'merge-unconfirmed') {
-      return {
-        status: 'merge-unconfirmed',
-        ...pullRequestIdentity(context),
-      };
-    }
-    if (
-      context.completion === 'fix-not-published' ||
-      context.completion === 'checks-failed'
-    ) {
-      return {
-        status: 'not-merged',
-        reason: context.completion,
-        ...pullRequestIdentity(context),
-      };
+      case 'fix-failed': {
+        if (context.childResult === undefined) {
+          throw new Error('PR reached fix-failed without the CODE result');
+        }
+        return {
+          status: 'not-merged',
+          reason: 'fix-failed',
+          ...pullRequestIdentity(context),
+          childResult: context.childResult,
+        };
+      }
+      case 'fix-not-published':
+      case 'checks-failed':
+        return {
+          status: 'not-merged',
+          reason: context.completion,
+          ...pullRequestIdentity(context),
+        };
+      case 'merge-unconfirmed':
+        return {
+          status: 'merge-unconfirmed',
+          ...pullRequestIdentity(context),
+        };
+      default:
+        throw new Error('PR reached a final state without a recorded completion');
     }
-    throw new Error('PR reached a final state without a recorded completion');
   },
   states: {
     ready: {
@@ -952,7 +844,11 @@ export const prMachine = machineSetup.createMachine({
       meta: playbookMeta('ready'),
       tags: ['playbook.parked'],
       on: {
-        START_PR: { target: 'openPullRequest', actions: 'startPr' },
+        START_PR: {
+          guard: 'validStartPr',
+          target: 'openPullRequest',
+          actions: 'startPr',
+        },
       },
     },
     openPullRequest: {
@@ -968,7 +864,7 @@ export const prMachine = machineSetup.createMachine({
           sourceItem: 'PR-1',
           prompt: OPEN_PULL_REQUEST_PROMPT,
           result: OPEN_PULL_REQUEST_RESULTS,
-          callerInput: context.callerInput ?? '',
+          callerInput: context.callerInput ?? CALLER_INPUT_PLACEHOLDER,
           ...(context.pendingBossQuestion === undefined
             ? {}
             : { pendingBossQuestion: context.pendingBossQuestion }),
@@ -989,7 +885,8 @@ export const prMachine = machineSetup.createMachine({
                   acceptedOutcome: 'opened',
                 },
               },
-              'rememberPullRequest',
+              'rememberOpened',
+              'clearBossReplyContext',
             ],
           },
           {
@@ -1005,6 +902,7 @@ export const prMachine = machineSetup.createMachine({
                 },
               },
               'completeNotPublished',
+              'clearBossReplyContext',
             ],
           },
           {
@@ -1019,15 +917,33 @@ export const prMachine = machineSetup.createMachine({
                   acceptedOutcome: 'needsBossReply',
                 },
               },
-              'rememberPendingQuestion',
+              'setPendingBossQuestion',
             ],
           },
+          { target: 'failed', actions: 'rememberMalformedPlayerOutput' },
+        ],
+        onError: { target: 'failed', actions: 'rememberActorError' },
+      },
+    },
+    awaitBossReply: {
+      id: 'awaitBossReply',
+      description: STATE_DESCRIPTIONS.awaitBossReply,
+      meta: playbookMeta('awaitBossReply'),
+      tags: ['playbook.parked'],
+      on: {
+        BOSS_REPLY: [
           {
-            target: 'failed',
-            actions: 'rememberMalformedPlayerOutput',
+            guard: 'emptyBossReply',
+            target: '#failed',
+            actions: 'rememberEmptyBossReplyError',
           },
+          ...resumableStates(['openPullRequest']),
         ],
-        onError: { target: 'failed', actions: 'rememberActorError' },
+        START_PR: {
+          guard: 'validStartPr',
+          target: 'openPullRequest',
+          actions: 'startPr',
+        },
       },
     },
     waitForChecks: {
@@ -1040,19 +956,13 @@ export const prMachine = machineSetup.createMachine({
         input: (): ScriptInput => ({
           stateId: 'waitForChecks',
           sourceItem: 'PR-2',
-          command: WAIT_FOR_CHECKS_COMMAND,
+          command: CHECK_WAIT_COMMAND,
           result: WAIT_FOR_CHECKS_RESULTS,
         }),
         onDone: [
-          { guard: 'checksPassed', target: 'mergePullRequest' },
-          { guard: 'checksFailed', target: 'fixChecks' },
-          {
-            target: 'failed',
-            actions: {
-              type: 'rememberMalformedScriptOutput',
-              params: { sourceItem: 'PR-2' },
-            },
-          },
+          { guard: 'waitForChecksPassed', target: 'mergePullRequest' },
+          { guard: 'waitForChecksFailed', target: 'fixChecks' },
+          { target: 'failed', actions: 'rememberMalformedScriptOutput' },
         ],
         onError: { target: 'failed', actions: 'rememberActorError' },
       },
@@ -1067,19 +977,21 @@ export const prMachine = machineSetup.createMachine({
         input: ({ context }): PlaybookInput => ({
           stateId: 'fixChecks',
           sourceItem: 'PR-3',
-          playbookId: 'code',
-          text: fixChecksCallText(context),
+          playbookId: CODE_PLAYBOOK_ID,
+          text: fixCallText(context),
         }),
         onDone: [
           { guard: 'isCodeSuccess', target: 'publishFix' },
           {
+            guard: 'isInsufficientCodeResult',
             target: 'fixFailed',
             actions: 'completeWithInsufficientCodeResult',
           },
+          { target: 'failed', actions: 'rememberMalformedChildOutput' },
         ],
         onError: [
           {
-            guard: 'authoredCodeFailure',
+            guard: 'isAuthoredCodeFailure',
             target: 'fixFailed',
             actions: 'completeWithCodeFailure',
           },
@@ -1097,54 +1009,42 @@ export const prMachine = machineSetup.createMachine({
         input: ({ context }): ScriptInput => ({
           stateId: 'publishFix',
           sourceItem: 'PR-4',
-          command: scriptCommand(PUBLISH_FIX_COMMAND, context),
+          command: bindPullRequestUrl(PUBLISH_FIX_COMMAND_TEMPLATE, context),
           result: PUBLISH_FIX_RESULTS,
         }),
         onDone: [
-          { guard: 'fixPublished', target: 'waitForChecksAfterFix' },
+          { guard: 'fixPublished', target: 'waitForFixChecks' },
           {
             guard: 'fixNotPublished',
             target: 'fixNotPublished',
             actions: 'completeFixNotPublished',
           },
-          {
-            target: 'failed',
-            actions: {
-              type: 'rememberMalformedScriptOutput',
-              params: { sourceItem: 'PR-4' },
-            },
-          },
+          { target: 'failed', actions: 'rememberMalformedScriptOutput' },
         ],
         onError: { target: 'failed', actions: 'rememberActorError' },
       },
     },
-    waitForChecksAfterFix: {
-      id: 'waitForChecksAfterFix',
-      description: STATE_DESCRIPTIONS.waitForChecksAfterFix,
-      meta: playbookMeta('waitForChecksAfterFix'),
+    waitForFixChecks: {
+      id: 'waitForFixChecks',
+      description: STATE_DESCRIPTIONS.waitForFixChecks,
+      meta: playbookMeta('waitForFixChecks'),
       tags: ['playbook.busy'],
       invoke: {
         src: 'script',
         input: (): ScriptInput => ({
-          stateId: 'waitForChecksAfterFix',
+          stateId: 'waitForFixChecks',
           sourceItem: 'PR-5',
-          command: WAIT_FOR_CHECKS_COMMAND,
-          result: WAIT_FOR_CHECKS_AFTER_FIX_RESULTS,
+          command: CHECK_WAIT_COMMAND,
+          result: WAIT_FOR_FIX_CHECKS_RESULTS,
         }),
         onDone: [
-          { guard: 'checksPassed', target: 'mergePullRequest' },
+          { guard: 'waitForFixChecksPassed', target: 'mergePullRequest' },
           {
             guard: 'checksStillFailing',
-            target: 'checksStillFailing',
-            actions: 'completeChecksStillFailing',
-          },
-          {
-            target: 'failed',
-            actions: {
-              type: 'rememberMalformedScriptOutput',
-              params: { sourceItem: 'PR-5' },
-            },
+            target: 'checksFailed',
+            actions: 'completeChecksFailed',
           },
+          { target: 'failed', actions: 'rememberMalformedScriptOutput' },
         ],
         onError: { target: 'failed', actions: 'rememberActorError' },
       },
@@ -1159,23 +1059,17 @@ export const prMachine = machineSetup.createMachine({
         input: ({ context }): ScriptInput => ({
           stateId: 'mergePullRequest',
           sourceItem: 'PR-6',
-          command: scriptCommand(MERGE_PULL_REQUEST_COMMAND, context),
-          result: MERGE_PULL_REQUEST_RESULTS,
+          command: bindPullRequestUrl(MERGE_COMMAND_TEMPLATE, context),
+          result: MERGE_RESULTS,
         }),
         onDone: [
           { guard: 'merged', target: 'updateLocalDefault' },
           {
             guard: 'mergeRefused',
-            target: 'mergeRefused',
-            actions: 'completeMergeRefused',
-          },
-          {
-            target: 'failed',
-            actions: {
-              type: 'rememberMalformedScriptOutput',
-              params: { sourceItem: 'PR-6' },
-            },
+            target: 'mergeUnconfirmed',
+            actions: 'completeMergeUnconfirmed',
           },
+          { target: 'failed', actions: 'rememberMalformedScriptOutput' },
         ],
         onError: { target: 'failed', actions: 'rememberActorError' },
       },
@@ -1190,72 +1084,48 @@ export const prMachine = machineSetup.createMachine({
         input: (): ScriptInput => ({
           stateId: 'updateLocalDefault',
           sourceItem: 'PR-7',
-          command: UPDATE_LOCAL_DEFAULT_COMMAND,
-          result: UPDATE_LOCAL_DEFAULT_RESULTS,
+          command: LOCAL_UPDATE_COMMAND,
+          result: LOCAL_UPDATE_RESULTS,
         }),
         onDone: [
           {
             guard: 'localDefaultUpdated',
-            target: 'merged',
-            actions: 'completeMerged',
+            target: 'mergedLocalUpdated',
+            actions: 'completeMergedLocalUpdated',
           },
           {
             guard: 'localDefaultNotUpdated',
-            target: 'mergedLocalBehind',
-            actions: 'completeMergedLocalBehind',
-          },
-          {
-            target: 'failed',
-            actions: {
-              type: 'rememberMalformedScriptOutput',
-              params: { sourceItem: 'PR-7' },
-            },
+            target: 'mergedLocalNotUpdated',
+            actions: 'completeMergedLocalNotUpdated',
           },
+          { target: 'failed', actions: 'rememberMalformedScriptOutput' },
         ],
         onError: { target: 'failed', actions: 'rememberActorError' },
       },
     },
-    awaitBossReply: {
-      id: 'awaitBossReply',
-      description: STATE_DESCRIPTIONS.awaitBossReply,
-      meta: playbookMeta('awaitBossReply'),
-      tags: ['playbook.parked'],
-      on: {
-        BOSS_REPLY: [
-          {
-            guard: 'emptyBossReply',
-            target: '#failed',
-            actions: 'rememberEmptyBossReplyError',
-          },
-          {
-            guard: 'resumesOpenPullRequest',
-            target: '#openPullRequest',
-            reenter: true,
-            actions: 'rememberBossReply',
-          },
-        ],
-        START_PR: { target: 'openPullRequest', actions: 'startPr' },
-      },
-    },
     failed: {
       id: 'failed',
       description: STATE_DESCRIPTIONS.failed,
       meta: playbookMeta('failed'),
       tags: ['playbook.parked'],
       on: {
-        START_PR: { target: 'openPullRequest', actions: 'startPr' },
+        START_PR: {
+          guard: 'validStartPr',
+          target: 'openPullRequest',
+          actions: 'startPr',
+        },
       },
     },
-    merged: {
-      id: 'merged',
-      description: STATE_DESCRIPTIONS.merged,
-      meta: terminalMeta('merged', 'success'),
+    mergedLocalUpdated: {
+      id: 'mergedLocalUpdated',
+      description: STATE_DESCRIPTIONS.mergedLocalUpdated,
+      meta: terminalMeta('mergedLocalUpdated', 'success'),
       type: 'final',
     },
-    mergedLocalBehind: {
-      id: 'mergedLocalBehind',
-      description: STATE_DESCRIPTIONS.mergedLocalBehind,
-      meta: terminalMeta('mergedLocalBehind', 'success'),
+    mergedLocalNotUpdated: {
+      id: 'mergedLocalNotUpdated',
+      description: STATE_DESCRIPTIONS.mergedLocalNotUpdated,
+      meta: terminalMeta('mergedLocalNotUpdated', 'success'),
       type: 'final',
     },
     notPublished: {
@@ -1276,16 +1146,16 @@ export const prMachine = machineSetup.createMachine({
       meta: terminalMeta('fixNotPublished', 'failure'),
       type: 'final',
     },
-    checksStillFailing: {
-      id: 'checksStillFailing',
-      description: STATE_DESCRIPTIONS.checksStillFailing,
-      meta: terminalMeta('checksStillFailing', 'failure'),
+    checksFailed: {
+      id: 'checksFailed',
+      description: STATE_DESCRIPTIONS.checksFailed,
+      meta: terminalMeta('checksFailed', 'failure'),
       type: 'final',
     },
-    mergeRefused: {
-      id: 'mergeRefused',
-      description: STATE_DESCRIPTIONS.mergeRefused,
-      meta: terminalMeta('mergeRefused', 'failure'),
+    mergeUnconfirmed: {
+      id: 'mergeUnconfirmed',
+      description: STATE_DESCRIPTIONS.mergeUnconfirmed,
+      meta: terminalMeta('mergeUnconfirmed', 'failure'),
       type: 'final',
     },
   },