@sublang/playbook 13.1.0 → 13.2.0

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

@@ -0,0 +1,1251 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+//
+// Generated by slc/gears2fsm.md from ./pr.gears.md.
+
+import { assign, fromPromise, setup } from 'xstate';
+
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+export type PrStateId =
+  | 'openPullRequest'
+  | 'waitForChecks'
+  | 'fixChecks'
+  | 'publishFix'
+  | 'waitForChecksAfterFix'
+  | 'mergePullRequest'
+  | 'updateLocalDefault';
+
+export type PrSourceItem =
+  | 'PR-1'
+  | 'PR-2'
+  | 'PR-3'
+  | 'PR-4'
+  | 'PR-5'
+  | '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';
+
+export type PrChildPlaybookId = 'code';
+
+export type PendingBossQuestion = {
+  readonly questionId: 'openPullRequest';
+  readonly resumeStateId: 'openPullRequest';
+  readonly sourceItem: 'PR-1';
+  readonly asker: { readonly kind: 'role'; readonly roleId: 'coder' };
+  readonly question: string;
+};
+
+export type PlayerInput = {
+  readonly stateId: 'openPullRequest';
+  readonly role: 'coder';
+  readonly sourceItem: 'PR-1';
+  readonly prompt: string;
+  readonly result: Readonly<Record<string, string>>;
+  readonly callerInput: string;
+  readonly pendingBossQuestion?: PendingBossQuestion;
+  readonly bossReply?: string;
+};
+
+export type PlayerOutput =
+  | {
+      readonly guard: 'opened';
+      readonly pullRequest: string;
+      readonly pullRequestUrl: string;
+    }
+  | { 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 ScriptInput = {
+  readonly stateId: PrScriptStateId;
+  readonly sourceItem: PrScriptSourceItem;
+  readonly command: string;
+  readonly result: Readonly<Record<string, string>>;
+};
+
+export type ScriptOutput =
+  | { readonly guard: 'checksPassed'; readonly exitStatus: number }
+  | { readonly guard: 'checksFailed'; readonly exitStatus: number }
+  | { readonly guard: 'fixPublished'; readonly exitStatus: number }
+  | { readonly guard: 'fixNotPublished'; readonly exitStatus: number }
+  | { readonly guard: 'checksStillFailing'; readonly exitStatus: number }
+  | { readonly guard: 'merged'; readonly exitStatus: number }
+  | { readonly guard: 'mergeRefused'; readonly exitStatus: number }
+  | { readonly guard: 'localDefaultUpdated'; readonly exitStatus: number }
+  | { readonly guard: 'localDefaultNotUpdated'; readonly exitStatus: number };
+
+export type CompactError = {
+  readonly name: string;
+  readonly message: string;
+};
+
+/** Sanitized canonical child result relayed as PR's own failure outcome. */
+export type CompletedChildResult =
+  | {
+      readonly playbookId: PrChildPlaybookId;
+      readonly status: 'ok';
+      readonly output?: JsonValue;
+    }
+  | {
+      readonly playbookId: PrChildPlaybookId;
+      readonly status: 'aborted' | 'error';
+      readonly error: CompactError;
+    };
+
+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;
+    }
+  | {
+      readonly status: 'not-merged';
+      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 status: 'not-merged';
+      readonly reason: 'fix-not-published' | 'checks-failed' | 'merge-refused';
+      readonly pullRequest: string;
+      readonly pullRequestUrl: string;
+    };
+
+export type PrCompletion =
+  | 'merged'
+  | 'not-published'
+  | 'fix-failed'
+  | 'fix-not-published'
+  | 'checks-failed'
+  | 'merge-refused';
+
+/** 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 pendingBossQuestion?: PendingBossQuestion;
+  readonly bossReply?: string;
+};
+
+export type PrEvent =
+  | { readonly type: 'START_PR'; readonly callerInput: string }
+  | {
+      readonly type: 'BOSS_REPLY';
+      readonly answer: string;
+      readonly questionId?: 'openPullRequest';
+    };
+
+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.",
+  'If an open pull request for this branch already exists, use it; otherwise open one against the repository default branch with `gh pr create`.',
+  '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.',
+].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>`.',
+  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,
+} as const;
+
+// The mechanical steps are static POSIX shell text (slc/optimize.md): no
+// placeholder, no runtime value, and no prose — `gh` infers the pull request
+// from the checked-out branch.
+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 = [
+  '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 MERGE_PULL_REQUEST_COMMAND =
+  'gh pr merge --merge --delete-branch --match-head-commit "$(git rev-parse HEAD)"';
+
+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.",
+  checksFailed:
+    "The command exited with a nonzero status: the pull request's checks failed.",
+} as const;
+
+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.",
+  fixNotPublished:
+    "The command exited with a nonzero status: the push was rejected or the pull request's head did not advance to the pushed commit.",
+} 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.",
+  checksStillFailing:
+    "The command exited with a nonzero status: the pull request's checks are still failing after the one fix attempt.",
+} as const;
+
+const MERGE_PULL_REQUEST_RESULTS = {
+  merged:
+    'The command exited with status zero: the pull request is merged with a merge commit on the repository default branch, the remote and local branch are deleted, and the local default branch is checked out.',
+  mergeRefused:
+    'The command exited with a nonzero status: GitHub refused the merge, or the merge landed but the local switch to the default branch or the branch deletion failed.',
+} as const;
+
+const UPDATE_LOCAL_DEFAULT_RESULTS = {
+  localDefaultUpdated:
+    'The command exited with status zero: the local default branch is 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.',
+} 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.',
+  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.",
+  fixChecks:
+    'The CODE playbook is fixing the cause of the red checks on the checked-out branch.',
+  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.",
+  mergePullRequest:
+    'Merging the pull request into the repository default branch.',
+  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, both branches are deleted, and the local default branch is fast-forwarded to the merged head.',
+  mergedLocalBehind:
+    'The pull request is merged with a merge commit on the repository default branch and both branches are deleted, but the local default branch could not be 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.',
+  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.",
+  fixNotPublished:
+    "The fix could not be published: 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:
+    'GitHub refused the merge, or the merge landed but the local switch to the default branch or the branch deletion failed; the pull request is in the state GitHub reports.',
+} as const;
+
+function playbookMeta<StateId extends keyof typeof STATE_DESCRIPTIONS>(
+  stateId: StateId,
+  role?: 'coder',
+) {
+  return {
+    playbook: {
+      stateId,
+      description: STATE_DESCRIPTIONS[stateId],
+      ...(role === undefined ? {} : { role }),
+    },
+  };
+}
+
+// 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,
+  terminal: 'success' | 'failure',
+) {
+  return {
+    playbook: {
+      stateId,
+      description: STATE_DESCRIPTIONS[stateId],
+      terminal,
+    },
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+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 isOpened({ event }: { event: unknown }): boolean {
+  return (
+    outputGuard(event, 'opened') &&
+    outputString(event, 'pullRequest') !== undefined &&
+    outputString(event, 'pullRequestUrl') !== undefined
+  );
+}
+
+function isNotPublished({ event }: { event: unknown }): boolean {
+  return (
+    outputGuard(event, 'notPublished') &&
+    outputString(event, 'coderOutput') !== undefined
+  );
+}
+
+function needsBossReply({ event }: { event: unknown }): boolean {
+  return (
+    outputGuard(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(
+  guard: ScriptOutput['guard'],
+): (args: { event: unknown }) => boolean {
+  return ({ event }) => {
+    const exitStatus = scriptExitStatus(event);
+    return (
+      outputGuard(event, guard) && exitStatus !== undefined && exitStatus !== 0
+    );
+  };
+}
+
+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
+  );
+}
+
+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[] {
+  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
+  );
+}
+
+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))
+  );
+}
+
+function nestedResultFromError(
+  error: unknown,
+): Record<string, unknown> | 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') {
+    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 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 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') {
+    return {
+      playbookId,
+      status: 'ok',
+      ...(failure.output === undefined ? {} : { output: failure.output }),
+    };
+  }
+  return {
+    playbookId,
+    status: failure?.status === 'aborted' ? 'aborted' : 'error',
+    error: authoredChildError(event, playbookId),
+  };
+}
+
+function insufficientChildResult(
+  event: unknown,
+  playbookId: PrChildPlaybookId,
+): CompletedChildResult {
+  const output = childOutputOf(event);
+  return {
+    playbookId,
+    status: 'ok',
+    ...(output === undefined ? {} : { 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,
+  };
+}
+
+const machineSetup = setup({
+  types: {} as {
+    context: PrContext;
+    events: PrEvent;
+    input: PrInput;
+    output: PrPlaybookOutput;
+  },
+  actors: {
+    player: fromPromise<PlayerOutput, PlayerInput>(async () => {
+      throw new Error('player actor must be provided by the runner');
+    }),
+    playbook: fromPromise<JsonValue | undefined, PlaybookInput>(async () => {
+      throw new Error('playbook actor must be provided by the runner');
+    }),
+    script: fromPromise<ScriptOutput, ScriptInput>(async () => {
+      throw new Error('script actor must be provided by the runner');
+    }),
+  },
+  guards: {
+    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'),
+  },
+  actions: {
+    'playbook.acceptedOutcome': (
+      _args,
+      _params: {
+        readonly source: string;
+        readonly target: string;
+        readonly acceptedOutcome: string;
+      },
+    ) => undefined,
+    startPr: assign(({ event }) => {
+      if (event.type !== 'START_PR') return {};
+      return {
+        callerInput: event.callerInput,
+        pullRequest: undefined,
+        pullRequestUrl: undefined,
+        completion: undefined,
+        localDefaultUpdated: undefined,
+        coderOutput: undefined,
+        childFailure: undefined,
+        lastError: undefined,
+        pendingBossQuestion: undefined,
+        bossReply: undefined,
+      };
+    }),
+    rememberPullRequest: 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,
+    })),
+    rememberPendingQuestion: 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,
+      };
+    }),
+    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,
+    }),
+    completeWithInsufficientCodeResult: assign(({ 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({
+      completion: 'merge-refused' as const,
+    }),
+    completeMerged: assign({
+      completion: 'merged' as const,
+      localDefaultUpdated: true,
+    }),
+    completeMergedLocalBehind: assign({
+      completion: 'merged' as const,
+      localDefaultUpdated: false,
+    }),
+    rememberActorError: assign(({ event }) => ({
+      lastError: (event as unknown as { readonly error?: unknown }).error,
+    })),
+    rememberMalformedPlayerOutput: assign({
+      lastError: () =>
+        new Error('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.`,
+        ),
+      }),
+    ),
+  },
+});
+
+export const prMachine = machineSetup.createMachine({
+  id: 'pr',
+  initial: 'ready',
+  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");
+      }
+      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');
+      }
+      return {
+        status: 'not-merged',
+        reason: 'fix-failed',
+        ...pullRequestIdentity(context),
+        childResult: context.childFailure,
+      };
+    }
+    if (
+      context.completion === 'fix-not-published' ||
+      context.completion === 'checks-failed' ||
+      context.completion === 'merge-refused'
+    ) {
+      return {
+        status: 'not-merged',
+        reason: context.completion,
+        ...pullRequestIdentity(context),
+      };
+    }
+    throw new Error('PR reached a final state without a recorded completion');
+  },
+  states: {
+    ready: {
+      id: 'ready',
+      description: STATE_DESCRIPTIONS.ready,
+      meta: playbookMeta('ready'),
+      tags: ['playbook.parked'],
+      on: {
+        START_PR: { target: 'openPullRequest', actions: 'startPr' },
+      },
+    },
+    openPullRequest: {
+      id: 'openPullRequest',
+      description: STATE_DESCRIPTIONS.openPullRequest,
+      meta: playbookMeta('openPullRequest', 'coder'),
+      tags: ['playbook.busy'],
+      invoke: {
+        src: 'player',
+        input: ({ context }): PlayerInput => ({
+          stateId: 'openPullRequest',
+          role: 'coder',
+          sourceItem: 'PR-1',
+          prompt: OPEN_PULL_REQUEST_PROMPT,
+          result: OPEN_PULL_REQUEST_RESULTS,
+          callerInput: context.callerInput ?? '',
+          ...(context.pendingBossQuestion === undefined
+            ? {}
+            : { pendingBossQuestion: context.pendingBossQuestion }),
+          ...(context.bossReply === undefined
+            ? {}
+            : { bossReply: context.bossReply }),
+        }),
+        onDone: [
+          {
+            guard: 'isOpened',
+            target: 'waitForChecks',
+            actions: [
+              {
+                type: 'playbook.acceptedOutcome',
+                params: {
+                  source: 'openPullRequest',
+                  target: 'waitForChecks',
+                  acceptedOutcome: 'opened',
+                },
+              },
+              'rememberPullRequest',
+            ],
+          },
+          {
+            guard: 'isNotPublished',
+            target: 'notPublished',
+            actions: [
+              {
+                type: 'playbook.acceptedOutcome',
+                params: {
+                  source: 'openPullRequest',
+                  target: 'notPublished',
+                  acceptedOutcome: 'notPublished',
+                },
+              },
+              'completeNotPublished',
+            ],
+          },
+          {
+            guard: 'needsBossReply',
+            target: 'awaitBossReply',
+            actions: [
+              {
+                type: 'playbook.acceptedOutcome',
+                params: {
+                  source: 'openPullRequest',
+                  target: 'awaitBossReply',
+                  acceptedOutcome: 'needsBossReply',
+                },
+              },
+              'rememberPendingQuestion',
+            ],
+          },
+          {
+            target: 'failed',
+            actions: 'rememberMalformedPlayerOutput',
+          },
+        ],
+        onError: { target: 'failed', actions: 'rememberActorError' },
+      },
+    },
+    waitForChecks: {
+      id: 'waitForChecks',
+      description: STATE_DESCRIPTIONS.waitForChecks,
+      meta: playbookMeta('waitForChecks'),
+      tags: ['playbook.busy'],
+      invoke: {
+        src: 'script',
+        input: (): ScriptInput => ({
+          stateId: 'waitForChecks',
+          sourceItem: 'PR-2',
+          command: WAIT_FOR_CHECKS_COMMAND,
+          result: WAIT_FOR_CHECKS_RESULTS,
+        }),
+        onDone: [
+          { guard: 'checksPassed', target: 'mergePullRequest' },
+          { guard: 'checksFailed', target: 'fixChecks' },
+          {
+            target: 'failed',
+            actions: {
+              type: 'rememberMalformedScriptOutput',
+              params: { sourceItem: 'PR-2' },
+            },
+          },
+        ],
+        onError: { target: 'failed', actions: 'rememberActorError' },
+      },
+    },
+    fixChecks: {
+      id: 'fixChecks',
+      description: STATE_DESCRIPTIONS.fixChecks,
+      meta: playbookMeta('fixChecks'),
+      tags: ['playbook.suspended'],
+      invoke: {
+        src: 'playbook',
+        input: ({ context }): PlaybookInput => ({
+          stateId: 'fixChecks',
+          sourceItem: 'PR-3',
+          playbookId: 'code',
+          text: fixChecksCallText(context),
+        }),
+        onDone: [
+          { guard: 'isCodeSuccess', target: 'publishFix' },
+          {
+            target: 'fixFailed',
+            actions: 'completeWithInsufficientCodeResult',
+          },
+        ],
+        onError: [
+          {
+            guard: 'authoredCodeFailure',
+            target: 'fixFailed',
+            actions: 'completeWithCodeFailure',
+          },
+          { target: 'failed', actions: 'rememberActorError' },
+        ],
+      },
+    },
+    publishFix: {
+      id: 'publishFix',
+      description: STATE_DESCRIPTIONS.publishFix,
+      meta: playbookMeta('publishFix'),
+      tags: ['playbook.busy'],
+      invoke: {
+        src: 'script',
+        input: (): ScriptInput => ({
+          stateId: 'publishFix',
+          sourceItem: 'PR-4',
+          command: PUBLISH_FIX_COMMAND,
+          result: PUBLISH_FIX_RESULTS,
+        }),
+        onDone: [
+          { guard: 'fixPublished', target: 'waitForChecksAfterFix' },
+          {
+            guard: 'fixNotPublished',
+            target: 'fixNotPublished',
+            actions: 'completeFixNotPublished',
+          },
+          {
+            target: 'failed',
+            actions: {
+              type: 'rememberMalformedScriptOutput',
+              params: { sourceItem: 'PR-4' },
+            },
+          },
+        ],
+        onError: { target: 'failed', actions: 'rememberActorError' },
+      },
+    },
+    waitForChecksAfterFix: {
+      id: 'waitForChecksAfterFix',
+      description: STATE_DESCRIPTIONS.waitForChecksAfterFix,
+      meta: playbookMeta('waitForChecksAfterFix'),
+      tags: ['playbook.busy'],
+      invoke: {
+        src: 'script',
+        input: (): ScriptInput => ({
+          stateId: 'waitForChecksAfterFix',
+          sourceItem: 'PR-5',
+          command: WAIT_FOR_CHECKS_COMMAND,
+          result: WAIT_FOR_CHECKS_AFTER_FIX_RESULTS,
+        }),
+        onDone: [
+          { guard: 'checksPassed', target: 'mergePullRequest' },
+          {
+            guard: 'checksStillFailing',
+            target: 'checksStillFailing',
+            actions: 'completeChecksStillFailing',
+          },
+          {
+            target: 'failed',
+            actions: {
+              type: 'rememberMalformedScriptOutput',
+              params: { sourceItem: 'PR-5' },
+            },
+          },
+        ],
+        onError: { target: 'failed', actions: 'rememberActorError' },
+      },
+    },
+    mergePullRequest: {
+      id: 'mergePullRequest',
+      description: STATE_DESCRIPTIONS.mergePullRequest,
+      meta: playbookMeta('mergePullRequest'),
+      tags: ['playbook.busy'],
+      invoke: {
+        src: 'script',
+        input: (): ScriptInput => ({
+          stateId: 'mergePullRequest',
+          sourceItem: 'PR-6',
+          command: MERGE_PULL_REQUEST_COMMAND,
+          result: MERGE_PULL_REQUEST_RESULTS,
+        }),
+        onDone: [
+          { guard: 'merged', target: 'updateLocalDefault' },
+          {
+            guard: 'mergeRefused',
+            target: 'mergeRefused',
+            actions: 'completeMergeRefused',
+          },
+          {
+            target: 'failed',
+            actions: {
+              type: 'rememberMalformedScriptOutput',
+              params: { sourceItem: 'PR-6' },
+            },
+          },
+        ],
+        onError: { target: 'failed', actions: 'rememberActorError' },
+      },
+    },
+    updateLocalDefault: {
+      id: 'updateLocalDefault',
+      description: STATE_DESCRIPTIONS.updateLocalDefault,
+      meta: playbookMeta('updateLocalDefault'),
+      tags: ['playbook.busy'],
+      invoke: {
+        src: 'script',
+        input: (): ScriptInput => ({
+          stateId: 'updateLocalDefault',
+          sourceItem: 'PR-7',
+          command: UPDATE_LOCAL_DEFAULT_COMMAND,
+          result: UPDATE_LOCAL_DEFAULT_RESULTS,
+        }),
+        onDone: [
+          {
+            guard: 'localDefaultUpdated',
+            target: 'merged',
+            actions: 'completeMerged',
+          },
+          {
+            guard: 'localDefaultNotUpdated',
+            target: 'mergedLocalBehind',
+            actions: 'completeMergedLocalBehind',
+          },
+          {
+            target: 'failed',
+            actions: {
+              type: 'rememberMalformedScriptOutput',
+              params: { sourceItem: 'PR-7' },
+            },
+          },
+        ],
+        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' },
+      },
+    },
+    merged: {
+      id: 'merged',
+      description: STATE_DESCRIPTIONS.merged,
+      meta: terminalMeta('merged', 'success'),
+      type: 'final',
+    },
+    mergedLocalBehind: {
+      id: 'mergedLocalBehind',
+      description: STATE_DESCRIPTIONS.mergedLocalBehind,
+      meta: terminalMeta('mergedLocalBehind', 'success'),
+      type: 'final',
+    },
+    notPublished: {
+      id: 'notPublished',
+      description: STATE_DESCRIPTIONS.notPublished,
+      meta: terminalMeta('notPublished', 'failure'),
+      type: 'final',
+    },
+    fixFailed: {
+      id: 'fixFailed',
+      description: STATE_DESCRIPTIONS.fixFailed,
+      meta: terminalMeta('fixFailed', 'failure'),
+      type: 'final',
+    },
+    fixNotPublished: {
+      id: 'fixNotPublished',
+      description: STATE_DESCRIPTIONS.fixNotPublished,
+      meta: terminalMeta('fixNotPublished', 'failure'),
+      type: 'final',
+    },
+    checksStillFailing: {
+      id: 'checksStillFailing',
+      description: STATE_DESCRIPTIONS.checksStillFailing,
+      meta: terminalMeta('checksStillFailing', 'failure'),
+      type: 'final',
+    },
+    mergeRefused: {
+      id: 'mergeRefused',
+      description: STATE_DESCRIPTIONS.mergeRefused,
+      meta: terminalMeta('mergeRefused', 'failure'),
+      type: 'final',
+    },
+  },
+});
+
+export default prMachine;