@poetic-ai/poetic 1.42.0

package/integrations/bb-plugin-poetic/src/model.ts

@@ -0,0 +1,1302 @@
+import { z } from 'zod';
+import type { JudgeOperationsView } from './judge-operations-view.js';
+import type { CanonicalTaskStatus, PlanningWorkspaceProjection } from './planning-service.js';
+import { planningWorkspaceProjectionSchema } from './planning-workspace-schema.js';
+import { repositorySchema } from './repository-schema.js';
+import { type GetTaskDetailOutput, getTaskDetailOutputSchema } from './task-detail-schema.js';
+
+export const RUN_SNAPSHOT_VERSION = '1.0.0' as const;
+
+export const HOST_TRUST_DISCLOSURE = {
+  fullTrust: true,
+  hostEquivalentExecution: true,
+  providerAuth: 'native',
+  planningSync: false,
+  gitPush: false,
+  summary:
+    'This full-trust local plugin runs Poetic as your host user in the selected repository. Fusion may use native provider authentication and create worktrees or artifacts. This milestone action does not synchronize managed planning state or push Git changes.',
+} as const;
+
+export const TRACKED_EXECUTION_DISCLOSURE = {
+  fullTrust: true,
+  hostEquivalentExecution: true,
+  providerAuth: 'native',
+  planningSync: true,
+  gitCommits: true,
+  gitPush: true,
+  pullRequestCreation: true,
+  explicitFinalization: true,
+  summary:
+    'Tracked execution runs the installed canonical Poetic backlog lifecycle as your host user. It requires a clean checkout and may create or switch branches, synchronize managed planning state, invoke providers, create commits, push Git changes, and open a pull request. Finalization remains a separate explicit Poetic action.',
+} as const;
+
+/**
+ * Closed BB task-action vocabulary. Each name maps to one fixed Poetic plan-task
+ * lifecycle command; the contract never accepts a free-form command, argv, flag,
+ * status matrix, or generic task update.
+ */
+export const TASK_ACTION_VOCABULARY = [
+  'start',
+  'block',
+  'unblock',
+  'review',
+  'complete',
+  'cancel',
+  'reopen',
+] as const;
+
+export type TaskActionKind = (typeof TASK_ACTION_VOCABULARY)[number];
+
+/**
+ * Actions that archive or reopen terminal planning state. The request schema
+ * requires an extra archival/terminal confirmation for these only.
+ */
+export const TASK_ACTION_TERMINAL_KINDS = ['complete', 'cancel', 'reopen'] as const;
+
+export type TaskActionTerminalKind = (typeof TASK_ACTION_TERMINAL_KINDS)[number];
+
+/**
+ * Actions that require a non-empty reason string in the request schema.
+ */
+export const TASK_ACTION_REASON_KINDS = ['block', 'cancel', 'reopen'] as const;
+
+export type TaskActionReasonKind = (typeof TASK_ACTION_REASON_KINDS)[number];
+
+/**
+ * Disclosure for BB task lifecycle actions over managed planning files.
+ * Distinct from Fusion (no planning sync/push), tracked backlog execution
+ * (branch/PR/finalization lifecycle), and run cancellation (process control).
+ */
+export const TASK_PLANNING_DISCLOSURE = {
+  fullTrust: true,
+  hostEquivalentExecution: true,
+  providerAuth: 'native',
+  planningSync: true,
+  gitCommits: true,
+  gitPush: true,
+  managedPlanningMutation: true,
+  pullRequestCreation: false,
+  fusionLaunch: false,
+  trackedBacklogExecution: false,
+  runCancellation: false,
+  summary:
+    "Task lifecycle actions run the installed Poetic plan-task commands as your host user in the selected repository and branch. They mutate managed planning state, and Poetic's built-in managed sync commits and pushes those planning changes. They do not launch Fusion, start tracked backlog execution, create pull requests, or cancel runs. Complete archives a finished task; cancel archives without completion; reopen restores an archived or done task. BB never passes --no-sync or --force.",
+} as const;
+
+/**
+ * Consent the UI must collect before any task lifecycle action. Every field is
+ * a required true literal so partial or false consent fails schema validation.
+ */
+export interface TaskActionConsent {
+  hostExecution: true;
+  managedPlanningMutation: true;
+  automaticCommitAndPush: true;
+  selectedRepositoryAndBranch: true;
+}
+
+/**
+ * Extra consent for complete, cancel, and reopen (archival or terminal restore).
+ */
+export interface TaskActionTerminalConsent extends TaskActionConsent {
+  archivalOrTerminalConfirmation: true;
+}
+
+export type TaskActionAdmissionScope = {
+  repositoryPath: string;
+  taskId: string;
+};
+
+/**
+ * Fixed Poetic argv prefix for each action in the closed vocabulary. Nothing is
+ * appended beyond the managed task id and, for the reason actions, the single
+ * `--reason=<text>` token: no `--no-sync`, no `--force`, no `--to`, no `--json`,
+ * and no caller-supplied flag can reach the child process.
+ */
+const TASK_ACTION_COMMAND: Readonly<Record<TaskActionKind, readonly string[]>> = {
+  start: ['plan', 'task', 'start'],
+  block: ['plan', 'task', 'block'],
+  unblock: ['plan', 'task', 'unblock'],
+  review: ['plan', 'task', 'review'],
+  complete: ['plan', 'task', 'complete'],
+  cancel: ['plan', 'task', 'cancel'],
+  reopen: ['plan', 'task', 'reopen'],
+};
+
+/**
+ * The action identity the adapter needs, narrowed so a reason is present exactly
+ * for the reason actions. The validated RPC request satisfies this shape.
+ */
+export type TaskActionCommandRequest =
+  | { action: Exclude<TaskActionKind, TaskActionReasonKind>; taskId: string }
+  | { action: TaskActionReasonKind; taskId: string; reason: string };
+
+/**
+ * Build the fixed argv for one task action.
+ *
+ * The reason is passed as a single `--reason=<text>` token so a reason that
+ * begins with a dash can never be read as another option, and the whole argv is
+ * spawned without a shell.
+ */
+export function taskActionArgv(request: TaskActionCommandRequest): string[] {
+  const argv = [...TASK_ACTION_COMMAND[request.action], request.taskId];
+  switch (request.action) {
+    case 'block':
+    case 'cancel':
+    case 'reopen':
+      argv.push(`--reason=${request.reason}`);
+      break;
+    default:
+      break;
+  }
+  return argv;
+}
+
+/**
+ * What Poetic's own invocation reported, for the current invocation only.
+ *
+ * `state` is exit evidence and nothing more: it never outranks the authoritative
+ * Planning Workspace and task reread, and it never asserts that managed sync
+ * reached the remote — hence the always-false
+ * `remoteSyncConfirmedByExitCode`. `attempts` is fixed at 1 because a timeout or
+ * an ambiguous completion is never retried automatically.
+ */
+export interface TaskActionCommandEvidence {
+  state: 'succeeded' | 'failed';
+  attempts: 1;
+  argv: string[];
+  diagnostics: string | null;
+  remoteSyncConfirmedByExitCode: false;
+}
+
+/**
+ * Authoritative result of one applied task action: the command evidence plus a
+ * complete workspace reread and a fresh reread of the selected task.
+ */
+export interface TaskActionOutcome {
+  action: TaskActionKind;
+  taskId: string;
+  command: TaskActionCommandEvidence;
+  /** Advisory sync disclosure derived only from the fresh workspace reread. */
+  syncWarnings: string[];
+  workspace: PlanningWorkspaceProjection;
+  taskDetail: GetTaskDetailOutput;
+}
+
+/**
+ * Surface Poetic's current planning-sync evidence from a fresh workspace reread.
+ *
+ * Everything here comes from what Poetic published, never from the action's exit
+ * code, so a successful command with unpushed planning commits or a recorded
+ * sync failure still reads as a warning rather than as remote success.
+ */
+export function taskActionSyncWarnings(workspace: PlanningWorkspaceProjection): string[] {
+  const warnings: string[] = [];
+  const health = workspace.data.syncHealth;
+  if (health.state !== 'in-sync') {
+    warnings.push(health.detail ?? `Poetic reports planning sync state ${health.state}.`);
+  }
+  for (const note of workspace.notes) {
+    if (note.scope === 'sync-health') warnings.push(note.detail);
+  }
+  return [...new Set(warnings)];
+}
+
+/**
+ * Process-local admission for BB task actions. Prevents overlapping submissions
+ * for the same repository path and task id inside this plugin process only.
+ * Does not claim cross-process ownership, file locks, or Poetic-side exclusivity.
+ */
+export class ProcessLocalTaskActionAdmission {
+  private readonly claims = new Set<string>();
+
+  private scopeKey(scope: TaskActionAdmissionScope): string {
+    return `${scope.repositoryPath}\u0000${scope.taskId}`;
+  }
+
+  /**
+   * Claim exclusive process-local admission for one repository+task. Returns a
+   * release function that is safe to call more than once. Throws when another
+   * claim for the same scope is still held in this process.
+   */
+  claim(scope: TaskActionAdmissionScope): () => void {
+    const key = this.scopeKey(scope);
+    if (this.claims.has(key)) {
+      throw new Error(
+        `A BB task action is already in progress for task ${scope.taskId} in this repository. Process-local admission refuses overlapping submissions; this is not cross-process ownership.`
+      );
+    }
+    this.claims.add(key);
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      this.claims.delete(key);
+    };
+  }
+
+  isBusy(scope: TaskActionAdmissionScope): boolean {
+    return this.claims.has(this.scopeKey(scope));
+  }
+}
+
+/**
+ * Pure presentation and interaction for the BB task lifecycle controls.
+ *
+ * Nothing below reads Poetic internals, managed planning files, Git, the
+ * filesystem, or the network, and nothing mutates planning state. Displayed
+ * eligibility is advisory only: it never gates a submission and never predicts a
+ * resulting status. Poetic's own command outcome and its fresh rereads remain the
+ * only authority, so no queue movement or terminal state is ever derived here.
+ */
+
+/**
+ * Consent checkboxes exactly as the operator left them. Plain booleans: nothing
+ * here counts as consent until `taskActionConsentPayload` converts it, and that
+ * conversion fails closed on a partial acknowledgement.
+ */
+export interface TaskActionConsentState {
+  hostExecution: boolean;
+  managedPlanningMutation: boolean;
+  automaticCommitAndPush: boolean;
+  selectedRepositoryAndBranch: boolean;
+  /** Required for complete, cancel, and reopen only. */
+  archivalOrTerminalConfirmation: boolean;
+}
+
+export const EMPTY_TASK_ACTION_CONSENT: Readonly<TaskActionConsentState> = {
+  hostExecution: false,
+  managedPlanningMutation: false,
+  automaticCommitAndPush: false,
+  selectedRepositoryAndBranch: false,
+  archivalOrTerminalConfirmation: false,
+};
+
+/** Reason text per reason action, as typed. Empty means no reason was given. */
+export type TaskActionReasonState = Readonly<Record<TaskActionReasonKind, string>>;
+
+export const EMPTY_TASK_ACTION_REASONS: TaskActionReasonState = {
+  block: '',
+  cancel: '',
+  reopen: '',
+};
+
+export function isTaskActionTerminalKind(action: TaskActionKind): action is TaskActionTerminalKind {
+  return (TASK_ACTION_TERMINAL_KINDS as readonly TaskActionKind[]).includes(action);
+}
+
+export function isTaskActionReasonKind(action: TaskActionKind): action is TaskActionReasonKind {
+  return (TASK_ACTION_REASON_KINDS as readonly TaskActionKind[]).includes(action);
+}
+
+/**
+ * Convert collected consent into the exact shape the RPC schema requires, or
+ * null when the acknowledgement is incomplete. Returning null is the enforcement
+ * point: a caller cannot build a request without full consent.
+ */
+export function taskActionConsentPayload(
+  action: TaskActionKind,
+  consent: TaskActionConsentState
+): TaskActionConsent | TaskActionTerminalConsent | null {
+  if (
+    !consent.hostExecution ||
+    !consent.managedPlanningMutation ||
+    !consent.automaticCommitAndPush ||
+    !consent.selectedRepositoryAndBranch
+  ) {
+    return null;
+  }
+  const base: TaskActionConsent = {
+    hostExecution: true,
+    managedPlanningMutation: true,
+    automaticCommitAndPush: true,
+    selectedRepositoryAndBranch: true,
+  };
+  if (!isTaskActionTerminalKind(action)) return base;
+  if (!consent.archivalOrTerminalConfirmation) return null;
+  return { ...base, archivalOrTerminalConfirmation: true };
+}
+
+/**
+ * Control labels. `complete` names completion and archival together, `unblock`
+ * names only the return to active planning so it can never read as completion,
+ * and `cancel` names the task explicitly so it stays distinct from cancelling a
+ * run.
+ */
+export const TASK_ACTION_LABELS: Readonly<Record<TaskActionKind, string>> = {
+  start: 'Start task',
+  block: 'Block task',
+  unblock: 'Unblock task',
+  review: 'Move task to review',
+  complete: 'Complete and archive task',
+  cancel: 'Cancel task',
+  reopen: 'Reopen task',
+};
+
+/** Concise action-first labels for buttons; detailed effects remain adjacent. */
+export const TASK_ACTION_BUTTON_LABELS: Readonly<Record<TaskActionKind, string>> = {
+  start: 'Start Task',
+  block: 'Block Task',
+  unblock: 'Unblock Task',
+  review: 'Move to Review',
+  complete: 'Complete Task',
+  cancel: 'Cancel Task',
+  reopen: 'Reopen Task',
+};
+
+/**
+ * What each Poetic command is asked to do. These describe the request, never a
+ * predicted result: the recorded status always comes from Poetic's own reread.
+ */
+export const TASK_ACTION_EFFECTS: Readonly<Record<TaskActionKind, string>> = {
+  start: 'Asks Poetic to start this task. Poetic decides and records the resulting status.',
+  block: 'Asks Poetic to record this task as blocked with your reason.',
+  unblock:
+    'Asks Poetic to clear the recorded block and return this task to active planning. This is not completion: it never records a done, cancelled, or archived state.',
+  review: 'Asks Poetic to move this task into review.',
+  complete:
+    'Asks Poetic to complete this task and archive it out of active planning. Completion and archival happen together.',
+  cancel:
+    'Asks Poetic to cancel this task and archive it without completion. This is a planning action: it does not cancel a Poetic run or stop any running process.',
+  reopen: 'Asks Poetic to reopen this task from a done or cancelled state.',
+};
+
+/**
+ * Statuses in which Poetic's last read makes an action a usual next step. This
+ * is a display hint only; every control stays submittable so Poetic, not BB,
+ * decides what a transition means.
+ */
+const TASK_ACTION_USUAL_STATUS: Readonly<Record<TaskActionKind, readonly CanonicalTaskStatus[]>> = {
+  start: ['todo'],
+  block: ['todo', 'in_progress', 'review'],
+  unblock: ['blocked'],
+  review: ['in_progress'],
+  complete: ['in_progress', 'review'],
+  cancel: ['todo', 'in_progress', 'review', 'blocked'],
+  reopen: ['done', 'cancelled'],
+};
+
+/**
+ * One progression-oriented presentation hint for each canonical status. This
+ * never hides or admits an action; Poetic remains the transition authority.
+ */
+const TASK_ACTION_RECOMMENDED: Readonly<Record<CanonicalTaskStatus, TaskActionKind>> = {
+  todo: 'start',
+  in_progress: 'review',
+  review: 'complete',
+  blocked: 'unblock',
+  done: 'reopen',
+  cancelled: 'reopen',
+};
+
+/**
+ * Advisory eligibility hint. `advisory` is a true literal so this can never be
+ * read as an authoritative decision, and `unknown` stays distinct from `unusual`.
+ */
+export interface TaskActionAdvisoryView {
+  state: 'usual' | 'unusual' | 'unknown';
+  label: string;
+  advisory: true;
+}
+
+function taskActionAdvisory(
+  action: TaskActionKind,
+  status: CanonicalTaskStatus | null
+): TaskActionAdvisoryView {
+  if (status === null) {
+    return {
+      state: 'unknown',
+      label:
+        'Poetic reported no status for this task, so BB cannot indicate whether this action is usual here. Poetic decides.',
+      advisory: true,
+    };
+  }
+  if (TASK_ACTION_USUAL_STATUS[action].includes(status)) {
+    return {
+      state: 'usual',
+      label:
+        'Usual next step for the status Poetic last reported. Poetic still decides the result.',
+      advisory: true,
+    };
+  }
+  return {
+    state: 'unusual',
+    label:
+      'Not a usual next step for the status Poetic last reported. Submitting is still allowed; Poetic accepts or refuses it.',
+    advisory: true,
+  };
+}
+
+/** The canonical read state BB holds for the selected task. */
+export type TaskActionDetailState = 'available' | 'missing' | 'unavailable' | 'none';
+
+/** One unresolved submission this panel owns. */
+export interface TaskActionSubmissionState {
+  taskId: string;
+  action: TaskActionKind;
+}
+
+export interface TaskActionGateInput {
+  action: TaskActionKind;
+  taskId: string;
+  /** Raw reason text; trimmed here and required for the reason actions. */
+  reason: string;
+  consent: TaskActionConsentState;
+  /** Unresolved submission this panel already owns, or null. */
+  inFlight: TaskActionSubmissionState | null;
+  detailState: TaskActionDetailState;
+}
+
+/**
+ * The single refusal gate for a task action, shared by the rendered controls and
+ * by request construction so a disabled control and a refused submission always
+ * agree. Returns the plain reason, or null when the action may be submitted.
+ */
+export function taskActionRefusal(input: TaskActionGateInput): string | null {
+  switch (input.detailState) {
+    case 'missing':
+      return `Poetic reports no managed task ${input.taskId}, so no lifecycle action is submitted.`;
+    case 'unavailable':
+      return `Poetic could not describe task ${input.taskId}, so no lifecycle action is submitted.`;
+    case 'none':
+      return 'BB holds no canonical task detail for this task, so no lifecycle action is submitted.';
+    default:
+      break;
+  }
+  const inFlight = input.inFlight;
+  if (inFlight) {
+    if (inFlight.taskId === input.taskId && inFlight.action === input.action) {
+      return `This panel already submitted ${TASK_ACTION_LABELS[input.action].toLowerCase()} for ${input.taskId} and Poetic has not answered yet.`;
+    }
+    return `This panel already submitted ${TASK_ACTION_LABELS[inFlight.action].toLowerCase()} for ${inFlight.taskId} and Poetic has not answered yet. Wait for that action before submitting another.`;
+  }
+  if (isTaskActionReasonKind(input.action) && input.reason.trim().length === 0) {
+    return `Poetic requires a reason for ${TASK_ACTION_LABELS[input.action].toLowerCase()}. Enter one before submitting.`;
+  }
+  if (taskActionConsentPayload(input.action, input.consent) === null) {
+    return isTaskActionTerminalKind(input.action)
+      ? 'Accept every consent line, including the archival or terminal confirmation, before submitting.'
+      : 'Accept every consent line before submitting.';
+  }
+  return null;
+}
+
+/** The validated repository and task identity every request carries. */
+interface TaskActionRequestTarget {
+  projectId: string;
+  sourceId: string;
+  taskId: string;
+}
+
+/**
+ * A fully validated applyTaskAction request. One member per action so it matches
+ * the frozen discriminated RPC schema exactly; nothing beyond the target, the
+ * task id, the required reason, and consent can be carried.
+ */
+export type TaskActionRequestPayload =
+  | (TaskActionRequestTarget & { action: 'start'; consent: TaskActionConsent })
+  | (TaskActionRequestTarget & { action: 'block'; reason: string; consent: TaskActionConsent })
+  | (TaskActionRequestTarget & { action: 'unblock'; consent: TaskActionConsent })
+  | (TaskActionRequestTarget & { action: 'review'; consent: TaskActionConsent })
+  | (TaskActionRequestTarget & { action: 'complete'; consent: TaskActionTerminalConsent })
+  | (TaskActionRequestTarget & {
+      action: 'cancel';
+      reason: string;
+      consent: TaskActionTerminalConsent;
+    })
+  | (TaskActionRequestTarget & {
+      action: 'reopen';
+      reason: string;
+      consent: TaskActionTerminalConsent;
+    });
+
+export type TaskActionRequestDecision =
+  | { admitted: true; request: TaskActionRequestPayload }
+  | { admitted: false; reason: string };
+
+export interface TaskActionRequestInput extends TaskActionGateInput {
+  projectId: string;
+  sourceId: string;
+}
+
+/**
+ * Build one applyTaskAction request, or refuse it. Required reasons, full
+ * consent, an available canonical read, and single-submission admission are all
+ * enforced here, before any RPC call exists.
+ */
+export function buildTaskActionRequest(input: TaskActionRequestInput): TaskActionRequestDecision {
+  const refusal = taskActionRefusal(input);
+  if (refusal !== null) return { admitted: false, reason: refusal };
+  const target: TaskActionRequestTarget = {
+    projectId: input.projectId,
+    sourceId: input.sourceId,
+    taskId: input.taskId,
+  };
+  const reason = input.reason.trim();
+  // The gate above passed, so `taskActionConsentPayload` accepted this consent:
+  // every base field is acknowledged, and for a terminal action the archival
+  // confirmation is too. These literals are therefore what consent already says,
+  // built without a cast so the RPC schema still type-checks each member.
+  const consent: TaskActionConsent = {
+    hostExecution: true,
+    managedPlanningMutation: true,
+    automaticCommitAndPush: true,
+    selectedRepositoryAndBranch: true,
+  };
+  const terminalConsent: TaskActionTerminalConsent = {
+    ...consent,
+    archivalOrTerminalConfirmation: true,
+  };
+  switch (input.action) {
+    case 'start':
+      return { admitted: true, request: { ...target, action: 'start', consent } };
+    case 'unblock':
+      return { admitted: true, request: { ...target, action: 'unblock', consent } };
+    case 'review':
+      return { admitted: true, request: { ...target, action: 'review', consent } };
+    case 'block':
+      return { admitted: true, request: { ...target, action: 'block', reason, consent } };
+    case 'complete':
+      return {
+        admitted: true,
+        request: { ...target, action: 'complete', consent: terminalConsent },
+      };
+    case 'cancel':
+      return {
+        admitted: true,
+        request: { ...target, action: 'cancel', reason, consent: terminalConsent },
+      };
+    case 'reopen':
+      return {
+        admitted: true,
+        request: { ...target, action: 'reopen', reason, consent: terminalConsent },
+      };
+  }
+}
+
+/** One rendered lifecycle control. */
+export interface TaskActionControlView {
+  action: TaskActionKind;
+  label: string;
+  buttonLabel: string;
+  effectLabel: string;
+  /**
+   * Always `task-lifecycle`: these controls act on managed planning state, never
+   * on a run, so cancelling a task can never be rendered as cancelling a run.
+   */
+  domain: 'task-lifecycle';
+  requiresReason: boolean;
+  requiresTerminalConfirmation: boolean;
+  advisory: TaskActionAdvisoryView;
+  /** True while this panel's unresolved submission is exactly this action. */
+  busy: boolean;
+  /** True while this panel holds any unresolved lifecycle submission. */
+  taskBusy: boolean;
+  submittable: boolean;
+  /** Plain reason the control cannot be submitted; null when it can. */
+  blockedReason: string | null;
+}
+
+export interface TaskActionControlsView {
+  state: 'available' | 'unavailable';
+  taskId: string;
+  /** Why no controls are offered; null when they are. */
+  unavailableReason: string | null;
+  controls: readonly TaskActionControlView[];
+  /** Progression-oriented display hint only; null when status is unavailable. */
+  recommendedAction: TaskActionKind | null;
+  advisoryNotice: string;
+  concurrencyNotice: string;
+}
+
+export interface TaskActionControlsInput {
+  taskId: string;
+  detailState: TaskActionDetailState;
+  /** Poetic's last reported status, used only for the advisory hint. */
+  status: CanonicalTaskStatus | null;
+  reasons: TaskActionReasonState;
+  consent: TaskActionConsentState;
+  inFlight: TaskActionSubmissionState | null;
+}
+
+export const TASK_ACTION_ADVISORY_NOTICE =
+  'Eligibility shown here is advisory. Poetic accepts or refuses every action, and its command outcome plus its fresh reread are the only authority.';
+
+export const TASK_ACTION_CONCURRENCY_NOTICE =
+  'This panel submits one task lifecycle action at a time. Another BB panel or another process can still submit concurrently; Poetic-side admission, not this panel, is the authority for that.';
+
+/**
+ * Project the lifecycle controls for one selected task. Pure: the same input
+ * always yields the same view. No control is hidden on an advisory hint, and no
+ * resulting status, queue position, or terminal state is derived.
+ */
+export function buildTaskActionControlsView(
+  input: TaskActionControlsInput
+): TaskActionControlsView {
+  const taskBusy = input.inFlight !== null;
+  const controls = TASK_ACTION_VOCABULARY.map((action) => {
+    const reason = isTaskActionReasonKind(action) ? input.reasons[action] : '';
+    const blockedReason = taskActionRefusal({
+      action,
+      taskId: input.taskId,
+      reason,
+      consent: input.consent,
+      inFlight: input.inFlight,
+      detailState: input.detailState,
+    });
+    return {
+      action,
+      label: TASK_ACTION_LABELS[action],
+      buttonLabel: TASK_ACTION_BUTTON_LABELS[action],
+      effectLabel: TASK_ACTION_EFFECTS[action],
+      domain: 'task-lifecycle' as const,
+      requiresReason: isTaskActionReasonKind(action),
+      requiresTerminalConfirmation: isTaskActionTerminalKind(action),
+      advisory: taskActionAdvisory(action, input.status),
+      busy: taskBusy && input.inFlight?.action === action,
+      taskBusy,
+      submittable: blockedReason === null,
+      blockedReason,
+    };
+  });
+
+  if (input.detailState !== 'available') {
+    return {
+      state: 'unavailable',
+      taskId: input.taskId,
+      unavailableReason:
+        controls[0]?.blockedReason ??
+        'BB holds no canonical task detail for this task, so no lifecycle action is offered.',
+      controls: [],
+      recommendedAction: null,
+      advisoryNotice: TASK_ACTION_ADVISORY_NOTICE,
+      concurrencyNotice: TASK_ACTION_CONCURRENCY_NOTICE,
+    };
+  }
+
+  return {
+    state: 'available',
+    taskId: input.taskId,
+    unavailableReason: null,
+    controls,
+    recommendedAction: input.status === null ? null : TASK_ACTION_RECOMMENDED[input.status],
+    advisoryNotice: TASK_ACTION_ADVISORY_NOTICE,
+    concurrencyNotice: TASK_ACTION_CONCURRENCY_NOTICE,
+  };
+}
+
+/** One consent line in the confirmation, with its current acknowledgement. */
+export interface TaskActionConsentLineView {
+  key: keyof TaskActionConsentState;
+  label: string;
+  accepted: boolean;
+  required: boolean;
+}
+
+const TASK_ACTION_CONSENT_LABELS: Readonly<Record<keyof TaskActionConsentState, string>> = {
+  hostExecution: 'Poetic runs as my host user in the repository shown above.',
+  managedPlanningMutation: 'This mutates managed planning state that Poetic owns.',
+  automaticCommitAndPush:
+    "Poetic's built-in managed sync commits and pushes these planning changes.",
+  selectedRepositoryAndBranch: 'I mean this repository path and this branch.',
+  archivalOrTerminalConfirmation:
+    'I confirm the archival or terminal effect of this action on the task.',
+};
+
+/** Placeholder shown in the disclosed command line while no reason is entered. */
+export const TASK_ACTION_REASON_PLACEHOLDER = '<your reason>';
+
+export interface TaskActionConfirmationInput extends TaskActionGateInput {
+  /** Selected repository path, rendered verbatim. */
+  repositoryPath: string;
+  /** Branch Poetic reported, or null for a detached HEAD. */
+  branch: string | null;
+}
+
+/**
+ * The mutation confirmation for one action: what will run, where, on which
+ * branch, with which reason, and which consent is still outstanding. Repository
+ * path and branch are always disclosed, and a detached HEAD is named rather than
+ * blanked.
+ */
+export interface TaskActionConfirmationView {
+  action: TaskActionKind;
+  taskId: string;
+  headline: string;
+  /** Label of the control that actually submits, named for this action. */
+  submitLabel: string;
+  effectLabel: string;
+  repositoryPath: string;
+  branchLabel: string;
+  targetLine: string;
+  /** The exact fixed Poetic command that will run. */
+  commandLine: string;
+  /** The reason that will be sent, or null when the action takes none. */
+  reasonLine: string | null;
+  disclosureSummary: string;
+  consentLines: readonly TaskActionConsentLineView[];
+  submittable: boolean;
+  blockedReason: string | null;
+}
+
+export function buildTaskActionConfirmationView(
+  input: TaskActionConfirmationInput
+): TaskActionConfirmationView {
+  const reason = input.reason.trim();
+  const argv = isTaskActionReasonKind(input.action)
+    ? taskActionArgv({
+        action: input.action,
+        taskId: input.taskId,
+        reason: reason.length === 0 ? TASK_ACTION_REASON_PLACEHOLDER : reason,
+      })
+    : taskActionArgv({ action: input.action, taskId: input.taskId });
+  const branchLabel = input.branch ?? 'detached HEAD (no named branch)';
+  const terminal = isTaskActionTerminalKind(input.action);
+  const consentKeys: Array<keyof TaskActionConsentState> = [
+    'hostExecution',
+    'managedPlanningMutation',
+    'automaticCommitAndPush',
+    'selectedRepositoryAndBranch',
+    ...(terminal ? (['archivalOrTerminalConfirmation'] as const) : []),
+  ];
+  const blockedReason = taskActionRefusal(input);
+  return {
+    action: input.action,
+    taskId: input.taskId,
+    headline: `Confirm ${TASK_ACTION_LABELS[input.action].toLowerCase()}`,
+    submitLabel: `Submit ${TASK_ACTION_LABELS[input.action].toLowerCase()}`,
+    effectLabel: TASK_ACTION_EFFECTS[input.action],
+    repositoryPath: input.repositoryPath,
+    branchLabel,
+    targetLine: `Task ${input.taskId} in ${input.repositoryPath} on ${branchLabel}`,
+    commandLine: `poetic ${argv.join(' ')}`,
+    reasonLine: isTaskActionReasonKind(input.action)
+      ? reason.length === 0
+        ? 'No reason entered yet; Poetic requires one for this action.'
+        : reason
+      : null,
+    disclosureSummary: TASK_PLANNING_DISCLOSURE.summary,
+    consentLines: consentKeys.map((key) => ({
+      key,
+      label: TASK_ACTION_CONSENT_LABELS[key],
+      accepted: input.consent[key],
+      required: true,
+    })),
+    submittable: blockedReason === null,
+    blockedReason,
+  };
+}
+
+/** What the applied action reported, as the panel received it. */
+export interface TaskActionOutcomeInput {
+  action: TaskActionKind;
+  taskId: string;
+  command: TaskActionCommandEvidence;
+  syncWarnings: readonly string[];
+  taskDetail: GetTaskDetailOutput;
+}
+
+/**
+ * Plain rendering of one applied action. CLI diagnostics stay verbatim, a
+ * failure and a timeout are reported as ambiguous rather than as a known state,
+ * sync evidence stays advisory, and the canonical reread is named as the only
+ * authority. No status, queue position, or terminal state is derived here.
+ */
+export interface TaskActionOutcomeView {
+  action: TaskActionKind;
+  taskId: string;
+  state: 'succeeded' | 'failed';
+  headline: string;
+  commandLine: string;
+  attemptsNotice: string;
+  /** Poetic's own diagnostics, verbatim; null when it reported none. */
+  diagnostics: string | null;
+  /** Set whenever the outcome cannot be read as a known applied state. */
+  ambiguityNotice: string | null;
+  syncWarnings: readonly string[];
+  syncNotice: string;
+  taskState: 'available' | 'missing' | 'unavailable';
+  taskStateNotice: string;
+  refreshedNotice: string;
+}
+
+export const TASK_ACTION_REFRESHED_NOTICE =
+  "Queues and task detail below are Poetic's fresh reread. BB moved nothing in the queue and predicted no resulting status.";
+
+export function buildTaskActionOutcomeView(input: TaskActionOutcomeInput): TaskActionOutcomeView {
+  const diagnostics = input.command.diagnostics;
+  const timedOut = diagnostics !== null && /timed out|timeout/i.test(diagnostics);
+  const failed = input.command.state === 'failed';
+  const task = input.taskDetail.task;
+  const taskStateNotice =
+    task.state === 'available'
+      ? 'Poetic re-read this task after the action; the canonical detail shown is that reread.'
+      : task.state === 'missing'
+        ? `Poetic reports no managed task ${input.taskId} after this action. BB did not infer a completed, cancelled, or archived state.`
+        : `Poetic could not describe task ${input.taskId} after this action: ${task.reason}`;
+  return {
+    action: input.action,
+    taskId: input.taskId,
+    state: input.command.state,
+    headline: failed
+      ? `Poetic reported the ${input.action} command failed for ${input.taskId}.`
+      : `Poetic reported the ${input.action} command completed for ${input.taskId}.`,
+    commandLine: `poetic ${input.command.argv.join(' ')}`,
+    attemptsNotice: 'BB ran this once and never retries it automatically.',
+    diagnostics,
+    ambiguityNotice: timedOut
+      ? "Poetic's diagnostics mention a timeout, so whether the command finished is unknown. Nothing was retried; the canonical reread is the only authority."
+      : failed
+        ? 'A failed command may still have applied part of its change. Nothing was retried; the canonical reread is the only authority.'
+        : null,
+    syncWarnings: [...input.syncWarnings],
+    syncNotice:
+      input.syncWarnings.length === 0
+        ? 'Poetic reported no planning sync warnings on this reread. A zero exit still never confirms the managed sync reached the remote.'
+        : "A zero exit never confirms the managed sync reached the remote; the warnings above are Poetic's own fresh evidence.",
+    taskState: task.state,
+    taskStateNotice,
+    refreshedNotice: TASK_ACTION_REFRESHED_NOTICE,
+  };
+}
+
+/**
+ * Consent every task lifecycle action must acknowledge: host-equivalent
+ * execution, managed planning mutation, automatic commit/push sync, and the
+ * selected repository/branch. No false/partial consent is accepted.
+ */
+export const taskActionConsentSchema = z
+  .object({
+    hostExecution: z.literal(true),
+    managedPlanningMutation: z.literal(true),
+    automaticCommitAndPush: z.literal(true),
+    selectedRepositoryAndBranch: z.literal(true),
+  })
+  .strict();
+
+/**
+ * Complete, cancel, and reopen additionally confirm archival or terminal
+ * restore effects (archive finished/cancelled tasks; reopen restores them).
+ */
+export const taskActionTerminalConsentSchema = taskActionConsentSchema
+  .extend({
+    archivalOrTerminalConfirmation: z.literal(true),
+  })
+  .strict();
+
+/** Non-empty free-text reason required for block, cancel, and reopen only. */
+const taskActionReasonSchema = z.string().trim().min(1).max(4_000);
+
+/**
+ * A managed task id addresses one file under Poetic's managed task directory, so
+ * it must be a single safe path component: no separators, no traversal, and no
+ * leading dot or dash that could read as a hidden file or a flag.
+ */
+const taskActionTaskIdSchema = z
+  .string()
+  .min(1)
+  .max(200)
+  .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, 'A task id must be a single safe path component.');
+
+const taskActionTargetFields = {
+  projectId: z.string().min(1),
+  sourceId: z.string().min(1),
+  taskId: taskActionTaskIdSchema,
+} as const;
+
+/**
+ * Closed discriminated applyTaskAction request. Only the frozen vocabulary is
+ * accepted. Reasons are schema-required for block/cancel/reopen. Complete has
+ * no force field. No action can request --no-sync, argv, cwd, env, executable,
+ * generic update, or a free-form lifecycle matrix.
+ */
+export const applyTaskActionInputSchema = z.discriminatedUnion('action', [
+  z
+    .object({
+      ...taskActionTargetFields,
+      action: z.literal('start'),
+      consent: taskActionConsentSchema,
+    })
+    .strict(),
+  z
+    .object({
+      ...taskActionTargetFields,
+      action: z.literal('block'),
+      reason: taskActionReasonSchema,
+      consent: taskActionConsentSchema,
+    })
+    .strict(),
+  z
+    .object({
+      ...taskActionTargetFields,
+      action: z.literal('unblock'),
+      consent: taskActionConsentSchema,
+    })
+    .strict(),
+  z
+    .object({
+      ...taskActionTargetFields,
+      action: z.literal('review'),
+      consent: taskActionConsentSchema,
+    })
+    .strict(),
+  z
+    .object({
+      ...taskActionTargetFields,
+      action: z.literal('complete'),
+      consent: taskActionTerminalConsentSchema,
+    })
+    .strict(),
+  z
+    .object({
+      ...taskActionTargetFields,
+      action: z.literal('cancel'),
+      reason: taskActionReasonSchema,
+      consent: taskActionTerminalConsentSchema,
+    })
+    .strict(),
+  z
+    .object({
+      ...taskActionTargetFields,
+      action: z.literal('reopen'),
+      reason: taskActionReasonSchema,
+      consent: taskActionTerminalConsentSchema,
+    })
+    .strict(),
+]);
+
+export const taskPlanningDisclosureSchema = z
+  .object({
+    fullTrust: z.literal(true),
+    hostEquivalentExecution: z.literal(true),
+    providerAuth: z.literal('native'),
+    planningSync: z.literal(true),
+    gitCommits: z.literal(true),
+    gitPush: z.literal(true),
+    managedPlanningMutation: z.literal(true),
+    pullRequestCreation: z.literal(false),
+    fusionLaunch: z.literal(false),
+    trackedBacklogExecution: z.literal(false),
+    runCancellation: z.literal(false),
+    summary: z.string(),
+  })
+  .strict();
+
+/**
+ * Poetic's reported outcome for the current invocation. `argv` discloses the
+ * exact fixed argv that ran, `attempts` is a literal 1 (no automatic retry), and
+ * `remoteSyncConfirmedByExitCode` is a literal false so a zero exit can never be
+ * rendered as confirmed remote synchronization.
+ */
+const taskActionCommandEvidenceSchema = z
+  .object({
+    state: z.enum(['succeeded', 'failed']),
+    attempts: z.literal(1),
+    argv: z.array(z.string().min(1)),
+    diagnostics: z.string().nullable(),
+    remoteSyncConfirmedByExitCode: z.literal(false),
+  })
+  .strict();
+
+/**
+ * Authoritative post-action output: repository identity, the task-planning
+ * disclosure, the accepted action, the current invocation's evidence, current
+ * sync warnings, a full Planning Workspace reread, and a fresh reread of the
+ * selected task. Poetic remains mutation authority; BB does not invent status
+ * transitions, and the rereads outrank the exit code.
+ */
+export const applyTaskActionOutputSchema = z
+  .object({
+    repository: repositorySchema,
+    disclosure: taskPlanningDisclosureSchema,
+    action: z.enum(TASK_ACTION_VOCABULARY),
+    taskId: taskActionTaskIdSchema,
+    command: taskActionCommandEvidenceSchema,
+    syncWarnings: z.array(z.string()),
+    workspace: planningWorkspaceProjectionSchema,
+    taskDetail: getTaskDetailOutputSchema,
+  })
+  .strict();
+
+/**
+ * Frozen public RPC method for task lifecycle actions. The vocabulary and
+ * schemas are fixed here; BPTA-06 registers this method on the live contract.
+ */
+export const applyTaskActionMethod = {
+  input: applyTaskActionInputSchema,
+  output: applyTaskActionOutputSchema,
+} as const;
+
+/** Live registered RPC methods on the BB plugin, in registration order. */
+export const LIVE_POETIC_RPC_METHODS = [
+  'listProjects',
+  'capabilities',
+  'listBacklog',
+  'planningWorkspace',
+  'getBacklog',
+  'getTask',
+  'launchFusion',
+  'launchCompetition',
+  'launchTrackedBacklog',
+  'observeCompetition',
+  'pollRuns',
+  'cancelRun',
+  'applyTaskAction',
+  'readResult',
+  'previewPatch',
+  'competitionDefaults',
+  'setupStatus',
+  // BPAU-07A registration delta. The three mutation names are frozen by
+  // BPAU-00; the two sprint reads are added because neither was registered
+  // before this sprint. Nothing is removed, renamed, or combined.
+  'applyBacklogAuthoring',
+  'applyTaskAuthoring',
+  'applySprintComposition',
+  'listSprints',
+  'getSprint',
+  'applyBacklogFinalize',
+  'applySprintClose',
+] as const;
+
+export type CompatibilityState =
+  | 'exact'
+  | 'compatible_minor_difference'
+  | 'incompatible'
+  | 'unavailable';
+
+export interface RepositoryView {
+  projectId: string;
+  projectName: string;
+  sourceId: string;
+  path: string;
+  branch: string | null;
+  branchState: 'ready' | 'protected' | 'detached';
+  poeticVersion: string | null;
+  compatibility: CompatibilityState;
+  state: 'ready' | 'warning' | 'blocked';
+  messages: string[];
+}
+
+export interface BacklogItem {
+  id: string;
+  title: string;
+  status: string;
+  priority: string | null;
+  complexity: number | null;
+  domain: string | null;
+}
+
+/**
+ * Poetic's own status vocabulary for a tracked backlog execution, as published
+ * by the kind-tagged operational readback. Never re-derived here.
+ */
+export type TrackedExecutionStatus =
+  | 'queued'
+  | 'running'
+  | 'blocked'
+  | 'succeeded'
+  | 'failed'
+  | 'cancelled'
+  | 'unknown';
+
+export type TrackedExecutionProcessState = 'alive' | 'gone' | 'unobserved';
+
+/**
+ * Authoritative provenance/process evidence for a tracked execution of one
+ * backlog item, read from Poetic on every request. It is used only to refuse an
+ * unsafe duplicate launch; it is never stored, cached, or rendered as run state.
+ */
+export interface TrackedExecutionEvidence {
+  status: TrackedExecutionStatus;
+  /** The provenance record's own status label, never re-interpreted. */
+  provenanceStatus: string;
+  processState: TrackedExecutionProcessState;
+  executingPid: number | null;
+  terminal: boolean;
+  stale: boolean;
+  label: string;
+  compatibility: CompatibilityState;
+  evidence: Array<{ kind: EvidenceKind; value: string }>;
+  workflowId: string | null;
+  taskIds: string[];
+  branch: string | null;
+  pullRequestNumber: number | null;
+  lastCompletedStep: string | null;
+  failedAtStep: string | null;
+  errorMessage: string | null;
+  blockers: string[];
+  finalizationState: string;
+}
+
+export interface BacklogDetail extends BacklogItem {
+  body: string;
+  createdAt: string | null;
+  filePath: string;
+  /**
+   * Null when Poetic reports no local provenance record. `.poetic/provenance`
+   * is local-only, so absence is never proof that nothing is executing.
+   */
+  execution: TrackedExecutionEvidence | null;
+}
+
+export type EvidenceKind =
+  | 'artifact'
+  | 'branch'
+  | 'changed_file'
+  | 'commit'
+  | 'delivery'
+  | 'judge'
+  | 'patch'
+  | 'pull_request'
+  | 'synthesis'
+  | 'verification'
+  | 'workflow'
+  | 'blocker'
+  | 'finalization'
+  | 'worktree';
+
+export interface RunEvidence {
+  kind: EvidenceKind;
+  value: string;
+  variant?: string;
+  repository: string;
+  runId: string;
+}
+
+/**
+ * Whether this plugin still holds the local OS process handle it launched.
+ *
+ * `owned`       — the launched child is still supervised by this adapter.
+ * `lost`        — a handle existed and is gone (process exit, plugin reload, or
+ *                 BB server restart). Nothing is replayed; state is re-read.
+ * `never-owned` — the run was discovered from Poetic, not launched here.
+ */
+export type ProcessHandleState = 'owned' | 'lost' | 'never-owned';
+
+/**
+ * What proves a run is controllable right now. Cancellation requires one of the
+ * two positive values; `none` disables the control rather than guessing.
+ */
+export type ControlEvidence = 'local-process' | 'poetic-live-process' | 'none';
+
+/**
+ * Which canonical Poetic result readback describes this run. It names the
+ * existing kind-tagged readback BB must request for the run and never a new
+ * result authority, so a card can be navigated to its own result view without
+ * re-deriving the kind from the standalone command string.
+ */
+export type RunResultKind = 'competition' | 'fusion' | 'backlog-execute';
+
+export interface RunCard {
+  operationId: string;
+  runId: string | null;
+  /** The canonical readback kind for this run's result view. */
+  resultKind: RunResultKind;
+  backlogItemId: string;
+  title: string;
+  repository: string;
+  branch: string;
+  status: 'starting' | 'running' | 'blocked' | 'succeeded' | 'failed' | 'cancelled' | 'unknown';
+  phase: string;
+  progressLine: string;
+  /** Whether the visible line is model narration or the deterministic fallback. */
+  progressSource: 'deterministic' | 'narrated';
+  progressNarratedAt: string | null;
+  /** True when an older narration was replaced by newer authoritative facts. */
+  progressStale: boolean;
+  /** Advisory narrator latency only; never a control or completion signal. */
+  progressLatencyMs: number | null;
+  progressAdvisory: string | null;
+  progressSignature: string | null;
+  terminal: boolean;
+  /** True only when Poetic still exposes an addressable, non-terminal run. */
+  cancelEligible: boolean;
+  /** Whether this plugin still holds the OS process handle it launched. */
+  processHandle: ProcessHandleState;
+  /**
+   * The evidence that authorizes cancellation. `none` means the control is
+   * disabled: no confirmed live process exists to interrupt.
+   */
+  controlEvidence: ControlEvidence;
+  /**
+   * True once cancellation has been requested through Poetic's own cancellation
+   * surfaces. It does not assert a terminal state; the terminal state still
+   * comes from Poetic or from the observed exit of the launched run.
+   */
+  cancelRequested: boolean;
+  compatibility: CompatibilityState;
+  evidence: RunEvidence[];
+  standaloneCommand: string | null;
+  error: string | null;
+  /**
+   * Judge operations cockpit for this run, rendered from Poetic's optional
+   * judge-operations projection. Null when Poetic published no such projection —
+   * including for every record written before the projection existed — so absence
+   * renders as unavailable evidence rather than as a judge result.
+   */
+  judgeOperations: JudgeOperationsView | null;
+}
+
+/**
+ * Deterministic fingerprint of every field that affects rendered or actionable
+ * run-card state. Omitting any of these lets mergeRunCards discard authoritative
+ * updates (phase, evidence, compatibility, standalone command, identity labels)
+ * while still returning the previous array for true no-ops.
+ */
+function runSignature(run: RunCard): string {
+  return JSON.stringify([
+    run.operationId,
+    run.runId,
+    run.resultKind,
+    run.backlogItemId,
+    run.title,
+    run.repository,
+    run.branch,
+    run.status,
+    run.phase,
+    run.progressLine,
+    run.progressSource,
+    run.progressNarratedAt,
+    run.progressStale,
+    run.progressLatencyMs,
+    run.progressAdvisory,
+    run.progressSignature,
+    run.terminal,
+    run.cancelEligible,
+    run.processHandle,
+    run.controlEvidence,
+    run.cancelRequested,
+    run.compatibility,
+    run.evidence,
+    run.standaloneCommand,
+    run.error,
+    run.judgeOperations,
+  ]);
+}
+
+/**
+ * Merge freshly reported run cards into the panel's list. A Poetic run id is the
+ * stable identity across adapter restarts; the local operation id is used only
+ * until Poetic emits that id. Returns the previous array unchanged when nothing
+ * observable moved, so polling does not churn the panel.
+ */
+export function mergeRunCards(previous: RunCard[], incoming: RunCard[]): RunCard[] {
+  const sameIdentity = (left: RunCard, right: RunCard) =>
+    left.operationId === right.operationId ||
+    (left.runId !== null && right.runId !== null && left.runId === right.runId);
+  const next = [...previous];
+  for (const run of incoming) {
+    const matchingIndex = next.findIndex((existing) => sameIdentity(existing, run));
+    if (matchingIndex === -1) {
+      next.push(run);
+      continue;
+    }
+    next[matchingIndex] = run;
+    for (let index = next.length - 1; index > matchingIndex; index -= 1) {
+      if (sameIdentity(next[index] as RunCard, run)) next.splice(index, 1);
+    }
+  }
+  const unchanged =
+    next.length === previous.length &&
+    next.every((run, index) => runSignature(run) === runSignature(previous[index] as RunCard));
+  return unchanged ? previous : next;
+}