nolo-cli 0.1.18 → 0.1.20

package/ai/taskRun/taskRunProtocol.ts

@@ -0,0 +1,823 @@
+import { randomUUID } from "node:crypto";
+
+export const TASK_RUN_SCHEMA_VERSION = 1;
+
+export const TASK_RUN_TOOL_ACTIONS = [
+  "readContext",
+  "readTaskContext",
+  "queryReadyWorkItems",
+  "updateWorkItems",
+  "upsertWorkItem",
+  "claimOrDispatch",
+  "claimWorkItem",
+  "openDialog",
+  "recordArtifact",
+  "markBlocked",
+  "setBlocker",
+  "clearBlocker",
+  "requestReview",
+  "recordReview",
+  "submitOutcome",
+  "completeWorkItem",
+  "closeWorkItem",
+] as const;
+
+export type TaskRunToolAction = (typeof TASK_RUN_TOOL_ACTIONS)[number];
+
+export type TaskRunPhase =
+  | "planned"
+  | "running"
+  | "blocked"
+  | "needs_review"
+  | "needs_changes"
+  | "ready_for_alpha"
+  | "alpha_deployed"
+  | "main_approval_required"
+  | "main_ready"
+  | "ready_to_commit"
+  | "completed";
+
+export type TaskRunWorkItem = {
+  id: string;
+  kind?: "work" | "review" | "coordination" | string;
+  title: string;
+  ownerAgent?: string;
+  status:
+    | "pending"
+    | "ready"
+    | "running"
+    | "blocked"
+    | "needs_review"
+    | "needs_changes"
+    | "completed";
+  dependsOn?: string[];
+  parallelGroup?: string;
+  writeScope?: string[];
+  reviewPolicy?: "none" | "after_item" | "after_group" | "before_commit";
+  reviewOfWorkItemId?: string;
+  dialogIds?: string[];
+  artifactRefs?: string[];
+  blockerIds?: string[];
+  outcome?: {
+    summary: string;
+    submittedAt: string;
+    artifactRefs?: string[];
+    closedAt?: string;
+    closeSummary?: string;
+    closeReason?: string;
+  };
+};
+
+export type TaskRunAgentRun = {
+  id: string;
+  agentKey: string;
+  role?: string;
+  workItemId?: string;
+  dialogId?: string;
+  status: "queued" | "running" | "completed" | "failed" | "timed_out";
+  startedAt: string;
+  updatedAt: string;
+  resultSummary?: string;
+  errorCode?: string;
+};
+
+export type TaskRunArtifact = {
+  id: string;
+  kind: "diff" | "patch" | "commit" | "test" | "screenshot" | "log" | "handoff" | string;
+  ref: string;
+  summary: string;
+  createdAt: string;
+  producerRunId?: string;
+  workItemId?: string;
+};
+
+export type TaskRunDialog = {
+  id: string;
+  purpose: "assignment" | "review" | "status" | "question" | "handoff" | string;
+  participantAgentKeys: string[];
+  workItemIds?: string[];
+  message?: string;
+  status: "open" | "closed";
+  openedAt: string;
+  closedAt?: string;
+};
+
+export type TaskRunEvent = {
+  id: string;
+  type: string;
+  actorId?: string;
+  agentKey?: string;
+  workItemId?: string;
+  dialogId?: string;
+  artifactId?: string;
+  reviewStatus?: TaskRunReview["status"];
+  reason?: string;
+  payload?: Record<string, unknown>;
+  createdAt: string;
+};
+
+export type TaskRunBlocker = {
+  id: string;
+  layer: string;
+  code: string;
+  message: string;
+  createdAt: string;
+  evidence?: string[];
+  resolvedAt?: string;
+};
+
+export type TaskRunReviewFinding = {
+  priority: "P0" | "P1" | "P2" | "P3";
+  summary: string;
+  file?: string;
+  line?: number;
+  workItemId?: string;
+};
+
+export type TaskRunReview = {
+  status: "not_requested" | "requested" | "passed" | "needs_changes" | "blocked";
+  reviewerAgentKey?: string;
+  targetWorkItemId?: string;
+  reviewWorkItemId?: string;
+  dialogId?: string;
+  reviewedArtifactIds?: string[];
+  findings?: TaskRunReviewFinding[];
+  updatedAt: string;
+};
+
+export type TaskRunAutonomy = "manual" | "supervised" | "auto24h";
+
+export type TaskRunBudgetRule = {
+  provider?: string;
+  model?: string;
+  freeUntil?: string;
+  dailyUsdLimit?: number;
+  hardStopAfter?: string;
+  note?: string;
+};
+
+export type TaskRunCodexPolicy = {
+  mode: "quality_gate_only" | "supervisor" | "allowed";
+  requireFor?: string[];
+  avoidFor?: string[];
+  note?: string;
+};
+
+export type TaskRunCodexUsageSnapshot = {
+  source: "local_codex_session";
+  observedAt?: string;
+  planType?: string;
+  primary?: {
+    usedPercent?: number;
+    windowMinutes?: number;
+    resetsAt?: number;
+  };
+  secondary?: {
+    usedPercent?: number;
+    windowMinutes?: number;
+    resetsAt?: number;
+  };
+  lastTotalTokens?: number;
+  totalTokens?: number;
+};
+
+export type TaskRunControlPolicy = {
+  autonomy?: TaskRunAutonomy;
+  nextWakeAt?: string;
+  pausedReason?: string;
+  budget?: {
+    dailyUsdLimit?: number;
+    modelBudget?: Record<string, TaskRunBudgetRule>;
+    runnerBudget?: Record<string, TaskRunBudgetRule>;
+  };
+  codexPolicy?: TaskRunCodexPolicy;
+  codexUsageSnapshot?: TaskRunCodexUsageSnapshot;
+};
+
+export type TaskRunContext = {
+  schemaVersion: typeof TASK_RUN_SCHEMA_VERSION;
+  taskRunId: string;
+  taskRowId: string;
+  objective: string;
+  phase: TaskRunPhase;
+  control?: TaskRunControlPolicy;
+  updatedAt: string;
+};
+
+export type TaskRunMeta = {
+  taskRun?: TaskRunContext;
+  workItems?: TaskRunWorkItem[];
+  agentRuns?: TaskRunAgentRun[];
+  artifacts?: TaskRunArtifact[];
+  dialogs?: TaskRunDialog[];
+  taskEvents?: TaskRunEvent[];
+  review?: TaskRunReview;
+  blockers?: TaskRunBlocker[];
+  [key: string]: unknown;
+};
+
+export type TaskRunRowLike = {
+  rowId: string;
+  title?: string;
+  meta?: TaskRunMeta;
+};
+
+export type TaskRunDispatchPlan = {
+  ready: TaskRunWorkItem[];
+  waiting: Array<TaskRunWorkItem & { waitingOn: string[] }>;
+  active: TaskRunWorkItem[];
+  completed: TaskRunWorkItem[];
+};
+
+const createProtocolId = (): string => randomUUID().replace(/-/g, "");
+
+const unique = (values: Array<string | undefined>): string[] => [
+  ...new Set(values.filter((value): value is string => Boolean(value))),
+];
+
+export const DEFAULT_TASK_RUN_CONTROL_POLICY: TaskRunControlPolicy = {
+  autonomy: "supervised",
+  budget: {
+    modelBudget: {
+      projectManager: {
+        provider: "custom",
+        model: "kimi-k2.5",
+        note: "Default low-cost PM routing.",
+      },
+      frontend: {
+        model: "kimi-2.6",
+        freeUntil: "2026-05-22",
+        dailyUsdLimit: 1,
+        note: "Frontend implementation should prefer Kimi 2.6 while the free window is active.",
+      },
+      mimoCustomKey: {
+        provider: "mimo",
+        freeUntil: "2026-05-31",
+        note: "Free-use window before normal budget enforcement.",
+      },
+    },
+  },
+  codexPolicy: {
+    mode: "quality_gate_only",
+    requireFor: ["supervision", "critical_review", "complex_unblock", "main_or_release_decision"],
+    avoidFor: ["routine_implementation", "first_pass_triage", "formatting", "low_risk_probe"],
+    note: "Codex membership usage is still window-limited, so spend it on supervision and quality gates.",
+  },
+};
+
+const cloneTaskRunControlPolicy = (policy: TaskRunControlPolicy): TaskRunControlPolicy =>
+  JSON.parse(JSON.stringify(policy));
+
+const cloneMeta = (meta: TaskRunMeta | undefined): TaskRunMeta => ({ ...(meta ?? {}) });
+
+const touchTaskRun = (meta: TaskRunMeta, now: string, phase?: TaskRunPhase): void => {
+  if (!meta.taskRun) return;
+  meta.taskRun = {
+    ...meta.taskRun,
+    ...(phase ? { phase } : {}),
+    updatedAt: now,
+  };
+};
+
+const phaseForWorkItemStatus = (status: TaskRunWorkItem["status"]): TaskRunPhase | undefined => {
+  if (status === "running") return "running";
+  if (status === "blocked") return "blocked";
+  if (status === "needs_review") return "needs_review";
+  if (status === "needs_changes") return "needs_changes";
+  return undefined;
+};
+
+const appendTaskRunEvent = (args: {
+  meta: TaskRunMeta;
+  type: string;
+  now: string;
+  createId?: () => string;
+  actorId?: string;
+  agentKey?: string;
+  workItemId?: string;
+  dialogId?: string;
+  artifactId?: string;
+  reviewStatus?: TaskRunReview["status"];
+  reason?: string;
+  payload?: Record<string, unknown>;
+}): TaskRunEvent => {
+  const event: TaskRunEvent = {
+    id: args.createId?.() ?? createProtocolId(),
+    type: args.type,
+    ...(args.actorId ? { actorId: args.actorId } : {}),
+    ...(args.agentKey ? { agentKey: args.agentKey } : {}),
+    ...(args.workItemId ? { workItemId: args.workItemId } : {}),
+    ...(args.dialogId ? { dialogId: args.dialogId } : {}),
+    ...(args.artifactId ? { artifactId: args.artifactId } : {}),
+    ...(args.reviewStatus ? { reviewStatus: args.reviewStatus } : {}),
+    ...(args.reason ? { reason: args.reason } : {}),
+    ...(args.payload ? { payload: args.payload } : {}),
+    createdAt: args.now,
+  };
+  args.meta.taskEvents = [...(args.meta.taskEvents ?? []), event];
+  return event;
+};
+
+export function prepareTaskRunMeta(args: {
+  row: TaskRunRowLike;
+  now?: string;
+  createId?: () => string;
+}): { meta: TaskRunMeta; taskRun: TaskRunContext } {
+  const now = args.now ?? new Date().toISOString();
+  const meta = cloneMeta(args.row.meta);
+  const existing = meta.taskRun;
+  const { allowedActions: _legacyAllowedActions, ...existingTaskRun } = existing ?? {};
+  const taskRun: TaskRunContext = {
+    ...existingTaskRun,
+    schemaVersion: TASK_RUN_SCHEMA_VERSION,
+    taskRunId: existing?.taskRunId ?? `taskrun-${args.row.rowId}-${args.createId?.() ?? createProtocolId()}`,
+    taskRowId: existing?.taskRowId ?? args.row.rowId,
+    objective: existing?.objective ?? args.row.title ?? args.row.rowId,
+    phase: existing?.phase ?? "planned",
+    control: existing?.control ?? cloneTaskRunControlPolicy(DEFAULT_TASK_RUN_CONTROL_POLICY),
+    updatedAt: now,
+  };
+  meta.taskRun = taskRun;
+  return { meta, taskRun };
+}
+
+export function planTaskRunDispatch(meta: TaskRunMeta): TaskRunDispatchPlan {
+  const workItems = meta.workItems ?? [];
+  const completedIds = new Set(workItems.filter((item) => item.status === "completed").map((item) => item.id));
+  const ready: TaskRunWorkItem[] = [];
+  const waiting: Array<TaskRunWorkItem & { waitingOn: string[] }> = [];
+  const active: TaskRunWorkItem[] = [];
+  const completed: TaskRunWorkItem[] = [];
+
+  for (const item of workItems) {
+    if (item.status === "completed") {
+      completed.push(item);
+      continue;
+    }
+    if (item.status === "running" || item.status === "needs_review") {
+      active.push(item);
+      continue;
+    }
+    if (item.status === "blocked") {
+      waiting.push({ ...item, waitingOn: item.blockerIds ?? [] });
+      continue;
+    }
+    if (item.status === "needs_changes") {
+      ready.push(item);
+      continue;
+    }
+    const missingDeps = (item.dependsOn ?? []).filter((depId) => !completedIds.has(depId));
+    if (missingDeps.length > 0) {
+      waiting.push({ ...item, waitingOn: missingDeps });
+      continue;
+    }
+    ready.push(item);
+  }
+
+  return { ready, waiting, active, completed };
+}
+
+export function upsertTaskRunWorkItems(args: {
+  meta: TaskRunMeta;
+  workItems: TaskRunWorkItem[];
+  now?: string;
+}): TaskRunMeta {
+  const now = args.now ?? new Date().toISOString();
+  const meta = cloneMeta(args.meta);
+  const items = [...(meta.workItems ?? [])];
+  for (const input of args.workItems) {
+    const index = items.findIndex((item) => item.id === input.id);
+    const existing = index >= 0 ? items[index] : undefined;
+    const workItem = existing
+      ? {
+          ...existing,
+          ...input,
+          dependsOn: unique([...(existing.dependsOn ?? []), ...(input.dependsOn ?? [])]),
+          writeScope: unique([...(existing.writeScope ?? []), ...(input.writeScope ?? [])]),
+          dialogIds: unique([...(existing.dialogIds ?? []), ...(input.dialogIds ?? [])]),
+          artifactRefs: unique([...(existing.artifactRefs ?? []), ...(input.artifactRefs ?? [])]),
+          blockerIds: unique([...(existing.blockerIds ?? []), ...(input.blockerIds ?? [])]),
+        }
+      : input;
+    if (index >= 0) {
+      items[index] = workItem;
+    } else {
+      items.push(workItem);
+    }
+    appendTaskRunEvent({
+      meta,
+      type: index >= 0 ? "work_item.updated" : "work_item.created",
+      workItemId: workItem.id,
+      now,
+      payload: { status: workItem.status, ownerAgent: workItem.ownerAgent },
+    });
+    touchTaskRun(meta, now, phaseForWorkItemStatus(workItem.status));
+  }
+  meta.workItems = items;
+  return meta;
+}
+
+export function updateTaskRunWorkItem(args: {
+  meta: TaskRunMeta;
+  id: string;
+  status?: TaskRunWorkItem["status"];
+  dialogIds?: string[];
+  artifactRefs?: string[];
+  blockerIds?: string[];
+  now?: string;
+}): { meta: TaskRunMeta; workItem?: TaskRunWorkItem } {
+  const now = args.now ?? new Date().toISOString();
+  const meta = cloneMeta(args.meta);
+  const items = [...(meta.workItems ?? [])];
+  const index = items.findIndex((item) => item.id === args.id);
+  if (index < 0) return { meta };
+  const existing = items[index];
+  const workItem = {
+    ...existing,
+    ...(args.status ? { status: args.status } : {}),
+    dialogIds: unique([...(existing.dialogIds ?? []), ...(args.dialogIds ?? [])]),
+    artifactRefs: unique([...(existing.artifactRefs ?? []), ...(args.artifactRefs ?? [])]),
+    blockerIds: unique([...(existing.blockerIds ?? []), ...(args.blockerIds ?? [])]),
+  };
+  items[index] = workItem;
+  meta.workItems = items;
+  appendTaskRunEvent({
+    meta,
+    type: args.status ? "work_item.status_changed" : "work_item.updated",
+    workItemId: workItem.id,
+    now,
+    payload: {
+      fromStatus: existing.status,
+      toStatus: workItem.status,
+      artifactRefs: args.artifactRefs,
+      blockerIds: args.blockerIds,
+      dialogIds: args.dialogIds,
+    },
+  });
+  touchTaskRun(meta, now, args.status ? phaseForWorkItemStatus(args.status) : undefined);
+  return { meta, workItem };
+}
+
+export function recordTaskRunDialog(args: {
+  meta: TaskRunMeta;
+  purpose: TaskRunDialog["purpose"];
+  participantAgentKeys: string[];
+  workItemIds?: string[];
+  message?: string;
+  now?: string;
+  createId?: () => string;
+}): { meta: TaskRunMeta; dialog: TaskRunDialog } {
+  const now = args.now ?? new Date().toISOString();
+  const meta = cloneMeta(args.meta);
+  const dialog: TaskRunDialog = {
+    id: args.createId?.() ?? createProtocolId(),
+    purpose: args.purpose,
+    participantAgentKeys: unique(args.participantAgentKeys),
+    ...(args.workItemIds?.length ? { workItemIds: unique(args.workItemIds) } : {}),
+    ...(args.message ? { message: args.message } : {}),
+    status: "open",
+    openedAt: now,
+  };
+  meta.dialogs = [...(meta.dialogs ?? []), dialog];
+  appendTaskRunEvent({
+    meta,
+    type: "dialog.opened",
+    dialogId: dialog.id,
+    now,
+    payload: {
+      purpose: dialog.purpose,
+      participantAgentKeys: dialog.participantAgentKeys,
+      workItemIds: dialog.workItemIds,
+    },
+  });
+  let nextMeta = meta;
+  for (const workItemId of dialog.workItemIds ?? []) {
+    nextMeta = updateTaskRunWorkItem({ meta: nextMeta, id: workItemId, dialogIds: [dialog.id], now }).meta;
+  }
+  touchTaskRun(nextMeta, now);
+  return { meta: nextMeta, dialog };
+}
+
+export function recordTaskRunArtifact(args: {
+  meta: TaskRunMeta;
+  artifact: Omit<TaskRunArtifact, "id" | "createdAt">;
+  now?: string;
+  createId?: () => string;
+}): { meta: TaskRunMeta; artifact: TaskRunArtifact } {
+  const now = args.now ?? new Date().toISOString();
+  const meta = cloneMeta(args.meta);
+  const artifact = { id: args.createId?.() ?? createProtocolId(), ...args.artifact, createdAt: now };
+  meta.artifacts = [...(meta.artifacts ?? []), artifact];
+  appendTaskRunEvent({
+    meta,
+    type: "artifact.recorded",
+    artifactId: artifact.id,
+    workItemId: artifact.workItemId,
+    now,
+    payload: { kind: artifact.kind, ref: artifact.ref, summary: artifact.summary },
+  });
+  touchTaskRun(meta, now);
+  return { meta, artifact };
+}
+
+export function recordTaskRunBlocker(args: {
+  meta: TaskRunMeta;
+  blocker: Omit<TaskRunBlocker, "id" | "createdAt">;
+  now?: string;
+  createId?: () => string;
+}): { meta: TaskRunMeta; blocker: TaskRunBlocker } {
+  const now = args.now ?? new Date().toISOString();
+  const meta = cloneMeta(args.meta);
+  const blocker = { id: args.createId?.() ?? createProtocolId(), ...args.blocker, createdAt: now };
+  meta.blockers = [...(meta.blockers ?? []), blocker];
+  appendTaskRunEvent({
+    meta,
+    type: "blocker.recorded",
+    now,
+    payload: { blockerId: blocker.id, layer: blocker.layer, code: blocker.code, message: blocker.message },
+  });
+  touchTaskRun(meta, now, "blocked");
+  return { meta, blocker };
+}
+
+export function clearTaskRunBlocker(args: {
+  meta: TaskRunMeta;
+  blockerId: string;
+  workItemId?: string;
+  now?: string;
+}): { meta: TaskRunMeta; blocker?: TaskRunBlocker; workItem?: TaskRunWorkItem } {
+  const now = args.now ?? new Date().toISOString();
+  const meta = cloneMeta(args.meta);
+  const blockers = [...(meta.blockers ?? [])];
+  const blockerIndex = blockers.findIndex((blocker) => blocker.id === args.blockerId);
+  if (blockerIndex < 0) return { meta };
+  const blocker = { ...blockers[blockerIndex], resolvedAt: now };
+  blockers[blockerIndex] = blocker;
+  meta.blockers = blockers;
+  let workItem: TaskRunWorkItem | undefined;
+  if (args.workItemId) {
+    const items = [...(meta.workItems ?? [])];
+    const itemIndex = items.findIndex((item) => item.id === args.workItemId);
+    if (itemIndex >= 0) {
+      const existing = items[itemIndex];
+      const blockerIds = (existing.blockerIds ?? []).filter((id) => id !== args.blockerId);
+      workItem = {
+        ...existing,
+        blockerIds,
+        ...(existing.status === "blocked" && blockerIds.length === 0 ? { status: "pending" as const } : {}),
+      };
+      items[itemIndex] = workItem;
+      meta.workItems = items;
+    }
+  }
+  appendTaskRunEvent({
+    meta,
+    type: "blocker.cleared",
+    workItemId: args.workItemId,
+    now,
+    payload: { blockerId: blocker.id },
+  });
+  touchTaskRun(meta, now);
+  return { meta, blocker, workItem };
+}
+
+export function recordTaskRunAgentDispatch(args: {
+  meta: TaskRunMeta;
+  workItemId: string;
+  agentKey: string;
+  role?: string;
+  now?: string;
+  createId?: () => string;
+}): { meta: TaskRunMeta; workItem?: TaskRunWorkItem; agentRun?: TaskRunAgentRun } {
+  const now = args.now ?? new Date().toISOString();
+  const updated = updateTaskRunWorkItem({ meta: args.meta, id: args.workItemId, status: "running", now });
+  if (!updated.workItem) return { meta: updated.meta };
+  const agentRun: TaskRunAgentRun = {
+    id: args.createId?.() ?? createProtocolId(),
+    agentKey: args.agentKey,
+    role: args.role,
+    workItemId: args.workItemId,
+    status: "queued",
+    startedAt: now,
+    updatedAt: now,
+  };
+  updated.meta.agentRuns = [...(updated.meta.agentRuns ?? []), agentRun];
+  appendTaskRunEvent({
+    meta: updated.meta,
+    type: "work_item.claimed",
+    agentKey: args.agentKey,
+    workItemId: args.workItemId,
+    now,
+    payload: { agentRunId: agentRun.id, role: args.role },
+  });
+  touchTaskRun(updated.meta, now, "running");
+  return { meta: updated.meta, workItem: updated.workItem, agentRun };
+}
+
+export function submitTaskRunOutcome(args: {
+  meta: TaskRunMeta;
+  workItemId: string;
+  summary: string;
+  artifactIds?: string[];
+  dialogId?: string;
+  now?: string;
+}): { meta: TaskRunMeta; workItem?: TaskRunWorkItem } {
+  const now = args.now ?? new Date().toISOString();
+  const updated = updateTaskRunWorkItem({
+    meta: args.meta,
+    id: args.workItemId,
+    status: "needs_review",
+    dialogIds: args.dialogId ? [args.dialogId] : undefined,
+    artifactRefs: args.artifactIds,
+    now,
+  });
+  if (!updated.workItem) return updated;
+  const items = [...(updated.meta.workItems ?? [])];
+  const index = items.findIndex((item) => item.id === args.workItemId);
+  const workItem = {
+    ...updated.workItem,
+    outcome: {
+      summary: args.summary,
+      submittedAt: now,
+      ...(args.artifactIds?.length ? { artifactRefs: unique(args.artifactIds) } : {}),
+    },
+  };
+  if (index >= 0) items[index] = workItem;
+  updated.meta.workItems = items;
+  appendTaskRunEvent({
+    meta: updated.meta,
+    type: "work_item.outcome_submitted",
+    workItemId: args.workItemId,
+    dialogId: args.dialogId,
+    now,
+    payload: { summary: args.summary, artifactIds: args.artifactIds },
+  });
+  touchTaskRun(updated.meta, now, "needs_review");
+  return { meta: updated.meta, workItem };
+}
+
+export function closeTaskRunWorkItem(args: {
+  meta: TaskRunMeta;
+  workItemId: string;
+  summary: string;
+  reason?: string;
+  artifactIds?: string[];
+  dialogId?: string;
+  now?: string;
+}): { meta: TaskRunMeta; workItem?: TaskRunWorkItem } {
+  const now = args.now ?? new Date().toISOString();
+  const updated = updateTaskRunWorkItem({
+    meta: args.meta,
+    id: args.workItemId,
+    status: "completed",
+    dialogIds: args.dialogId ? [args.dialogId] : undefined,
+    artifactRefs: args.artifactIds,
+    now,
+  });
+  if (!updated.workItem) return updated;
+  const items = [...(updated.meta.workItems ?? [])];
+  const index = items.findIndex((item) => item.id === args.workItemId);
+  const workItem = {
+    ...updated.workItem,
+    outcome: {
+      ...(updated.workItem.outcome ?? { summary: args.summary, submittedAt: now }),
+      closedAt: now,
+      closeSummary: args.summary,
+      ...(args.reason ? { closeReason: args.reason } : {}),
+      ...(args.artifactIds?.length
+        ? { artifactRefs: unique([...(updated.workItem.outcome?.artifactRefs ?? []), ...args.artifactIds]) }
+        : {}),
+    },
+  };
+  if (index >= 0) items[index] = workItem;
+  updated.meta.workItems = items;
+  appendTaskRunEvent({
+    meta: updated.meta,
+    type: "work_item.closed",
+    workItemId: args.workItemId,
+    dialogId: args.dialogId,
+    now,
+    reason: args.reason,
+    payload: { summary: args.summary, artifactIds: args.artifactIds },
+  });
+  touchTaskRun(updated.meta, now);
+  return { meta: updated.meta, workItem };
+}
+
+export function requestTaskRunReview(args: {
+  meta: TaskRunMeta;
+  reviewerAgentKey: string;
+  targetWorkItemId?: string;
+  artifactIds?: string[];
+  dialogId?: string;
+  message?: string;
+  now?: string;
+  createId?: () => string;
+}): { meta: TaskRunMeta; review: TaskRunReview } {
+  const now = args.now ?? new Date().toISOString();
+  const meta = cloneMeta(args.meta);
+  const reviewWorkItemId = args.targetWorkItemId
+    ? `review-${args.targetWorkItemId}-${args.createId?.() ?? createProtocolId()}`
+    : undefined;
+  let reviewDialogId = args.dialogId;
+  let nextMeta = meta;
+  if (args.targetWorkItemId) {
+    const reviewWorkItem: TaskRunWorkItem = {
+      id: reviewWorkItemId ?? `review-${args.targetWorkItemId}`,
+      kind: "review",
+      title: `Review ${args.targetWorkItemId}`,
+      ownerAgent: args.reviewerAgentKey,
+      status: "ready",
+      dependsOn: [args.targetWorkItemId],
+      reviewPolicy: "none",
+      reviewOfWorkItemId: args.targetWorkItemId,
+      artifactRefs: args.artifactIds,
+    };
+    nextMeta = upsertTaskRunWorkItems({ meta: nextMeta, workItems: [reviewWorkItem], now });
+    if (!reviewDialogId) {
+      const opened = recordTaskRunDialog({
+        meta: nextMeta,
+        purpose: "review",
+        participantAgentKeys: [args.reviewerAgentKey],
+        workItemIds: [args.targetWorkItemId, reviewWorkItem.id],
+        message: args.message ?? `Please review ${args.targetWorkItemId}.`,
+        now,
+        createId: args.createId,
+      });
+      nextMeta = opened.meta;
+      reviewDialogId = opened.dialog.id;
+    }
+  }
+  const review: TaskRunReview = {
+    ...(nextMeta.review ?? { status: "not_requested", updatedAt: now }),
+    status: "requested",
+    reviewerAgentKey: args.reviewerAgentKey,
+    ...(args.targetWorkItemId ? { targetWorkItemId: args.targetWorkItemId } : {}),
+    ...(reviewWorkItemId ? { reviewWorkItemId } : {}),
+    ...(reviewDialogId ? { dialogId: reviewDialogId } : {}),
+    reviewedArtifactIds: unique([...(nextMeta.review?.reviewedArtifactIds ?? []), ...(args.artifactIds ?? [])]),
+    updatedAt: now,
+  };
+  nextMeta.review = review;
+  appendTaskRunEvent({
+    meta: nextMeta,
+    type: "review.requested",
+    workItemId: args.targetWorkItemId,
+    dialogId: reviewDialogId,
+    reviewStatus: "requested",
+    agentKey: args.reviewerAgentKey,
+    now,
+    payload: { artifactIds: args.artifactIds, reviewWorkItemId },
+  });
+  touchTaskRun(nextMeta, now, "needs_review");
+  return { meta: nextMeta, review };
+}
+
+export function recordTaskRunReview(args: {
+  meta: TaskRunMeta;
+  status: Exclude<TaskRunReview["status"], "not_requested" | "requested">;
+  targetWorkItemId?: string;
+  reviewerAgentKey?: string;
+  artifactIds?: string[];
+  dialogId?: string;
+  findings?: TaskRunReviewFinding[];
+  now?: string;
+}): { meta: TaskRunMeta; review: TaskRunReview } {
+  const now = args.now ?? new Date().toISOString();
+  const meta = cloneMeta(args.meta);
+  const review: TaskRunReview = {
+    ...(meta.review ?? { status: "not_requested", updatedAt: now }),
+    status: args.status,
+    ...(args.reviewerAgentKey ? { reviewerAgentKey: args.reviewerAgentKey } : {}),
+    ...(args.targetWorkItemId ? { targetWorkItemId: args.targetWorkItemId } : {}),
+    ...(args.dialogId ? { dialogId: args.dialogId } : {}),
+    reviewedArtifactIds: unique([...(meta.review?.reviewedArtifactIds ?? []), ...(args.artifactIds ?? [])]),
+    findings: args.findings ?? meta.review?.findings,
+    updatedAt: now,
+  };
+  meta.review = review;
+  let nextMeta = meta;
+  const targetWorkItemId = args.targetWorkItemId ?? meta.review?.targetWorkItemId;
+  if (args.status === "needs_changes" && targetWorkItemId) {
+    nextMeta = updateTaskRunWorkItem({
+      meta: nextMeta,
+      id: targetWorkItemId,
+      status: "needs_changes",
+      artifactRefs: args.artifactIds,
+      dialogIds: args.dialogId ? [args.dialogId] : undefined,
+      now,
+    }).meta;
+  }
+  appendTaskRunEvent({
+    meta: nextMeta,
+    type: "review.recorded",
+    dialogId: args.dialogId,
+    workItemId: targetWorkItemId,
+    reviewStatus: args.status,
+    agentKey: args.reviewerAgentKey,
+    now,
+    payload: { artifactIds: args.artifactIds, findings: args.findings },
+  });
+  touchTaskRun(nextMeta, now, args.status === "passed" ? "ready_for_alpha" : args.status);
+  return { meta: nextMeta, review };
+}