@stigmer/server 3.14.0-dev.20260910084630

package/src/domain/agentexecution/filereview/autokeep.ts

@@ -0,0 +1,249 @@
+/**
+ * The approved-command auto-keep policy (DD-28) — ports
+ * filereview/autokeep.go.
+ *
+ * A turn whose ONLY mutation source was shell commands the human
+ * explicitly authorized (per-command approval, APPROVE_ALL category
+ * lease, or the pre-armed spec.auto_approve_all) must not re-gate its
+ * file effects at the turn-boundary review — the user consented to the
+ * command, and the command's file effects are the consented outcome. One
+ * consent, one gate.
+ *
+ * TRUST MODEL. The runner asserts the turn FACTS on the candidate event
+ * (TurnCommandProvenance) — the same trust level as the captured bytes.
+ * The CONSENT is verified HERE against records only the server writes:
+ * every cited row's approval_action was authored by SubmitApproval (and
+ * is preserved against runner writes), and the auto_approve_all flag is
+ * checked against the spec. A runner can therefore never mint
+ * authorization it was never given.
+ *
+ * The decision is a REAL FILE_DECIDED event (origin
+ * POLICY_APPROVED_COMMAND, actor "policy", digest-bound to the reviewed
+ * aggregate) — not a projection shortcut — so the fold keeps one
+ * semantics, the audit trail shows who decided, and the runner reconciles
+ * it exactly like a human keep-all.
+ */
+import { create } from "@bufbuild/protobuf";
+
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  FileChangeSetStatus,
+  FileDecisionAction,
+  FileDecisionOrigin,
+  FileDecisionScope,
+  FileReviewEventType,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type {
+  FileChangeSet,
+  FileDecision,
+  TurnCommandProvenance,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import { FileDecisionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+
+import type { Logger } from "../../../boot/logger.js";
+import {
+  ACTOR_POLICY,
+  approveBlockedReason,
+  decisionScopeId,
+  findChangeSet,
+  recordFileDecisionEventWithActor,
+} from "./author.js";
+import { projectFileChangeSets } from "./project.js";
+
+/**
+ * The audit-trail text on a policy decision. The UI label derives from
+ * FileDecision.origin; this is for the record itself.
+ */
+const AUTO_KEEP_REASON =
+  "Kept automatically: every change in this turn was produced by a command the user approved";
+
+/**
+ * Evaluates every undecided AWAITING_REVIEW change set whose candidate
+ * carries TurnCommandProvenance and — when the consent verifies and the
+ * set is fully reviewable — authors the policy APPROVE. Returns how many
+ * sets were auto-kept.
+ *
+ * Idempotent: the deterministic decision/event id makes re-evaluation on
+ * every status write a no-op once decided, and a racing human decision
+ * wins by first-append. Fail-closed: any verification miss leaves the set
+ * awaiting manual review, exactly as if no provenance existed.
+ *
+ * Must run inside the store write lock (with appendRunnerEvents, before
+ * the projection) so the authored decision lands in the same write as the
+ * candidate that qualified it — the workflow's gate check then never sees
+ * a transient AWAITING_REVIEW for an auto-kept set.
+ */
+export function autoKeepApprovedCommandSets(
+  status: AgentExecutionStatus,
+  executionId: string,
+  autoApproveAll: boolean,
+  logger: Logger,
+): number {
+  const stream = status.fileReviewEventStream;
+  if (stream === undefined || stream.events.length === 0) {
+    return 0;
+  }
+  const changeSets = projectFileChangeSets(status.phase, stream);
+  if (changeSets.length === 0) {
+    return 0;
+  }
+
+  let kept = 0;
+  for (const ev of stream.events) {
+    if (ev.eventType !== FileReviewEventType.CANDIDATE_CAPTURED) {
+      continue;
+    }
+    const provenance =
+      ev.payload.case === "candidateCaptured"
+        ? ev.payload.value.commandProvenance
+        : undefined;
+    if (provenance === undefined) {
+      continue;
+    }
+    const cs = findChangeSet(changeSets, ev.changeSetId);
+    if (
+      cs === undefined ||
+      cs.status !== FileChangeSetStatus.AWAITING_REVIEW
+    ) {
+      continue;
+    }
+    if (cs.decisions.length > 0) {
+      // A (possibly partial) human decision exists — the human owns this
+      // set.
+      continue;
+    }
+    // The same fail-closed completeness gate a human APPROVE passes, with
+    // NO binary acknowledgment: an unreviewable or binary-blocked set is
+    // never auto-kept — it falls back to manual review.
+    const blockedReason = approveBlockedReason(
+      cs,
+      FileDecisionScope.CHANGE_SET,
+      "",
+      false,
+    );
+    if (blockedReason !== "") {
+      logger.info("Auto-keep skipped: set not fully reviewable — manual review", {
+        executionId,
+        changeSetId: cs.id,
+        blockedReason,
+      });
+      continue;
+    }
+    if (!verifyCommandConsent(status, provenance, autoApproveAll)) {
+      logger.warn(
+        "Auto-keep skipped: claimed consent did not verify against server-authored approvals — manual review",
+        {
+          executionId,
+          changeSetId: cs.id,
+          consentToolCallIds: provenance.consentToolCallIds,
+        },
+      );
+      continue;
+    }
+
+    const decision = buildPolicyAutoKeepDecision(cs);
+    recordFileDecisionEventWithActor(
+      status,
+      executionId,
+      decision,
+      ACTOR_POLICY,
+    );
+    kept++;
+    logger.info(
+      "Auto-kept change set: every change produced by an approved command (DD-28)",
+      {
+        executionId,
+        changeSetId: cs.id,
+        consentToolCallIds: provenance.consentToolCallIds,
+        authorizedByAutoApproveAll: provenance.authorizedByAutoApproveAll,
+      },
+    );
+  }
+  return kept;
+}
+
+/**
+ * The policy twin of buildFileDecision: a CHANGE_SET-scoped APPROVE bound
+ * to the aggregate digest the runner captured, origin
+ * POLICY_APPROVED_COMMAND, no reviewer (the actor is "policy"). Shares
+ * the deterministic id space, so a concurrent human decision on the same
+ * set collapses to whichever was appended first.
+ */
+function buildPolicyAutoKeepDecision(cs: FileChangeSet): FileDecision {
+  const decision = create(FileDecisionSchema, {
+    changeSetId: cs.id,
+    scope: FileDecisionScope.CHANGE_SET,
+    action: FileDecisionAction.APPROVE,
+    expectedDigest: cs.aggregateDigest,
+    decidedAt: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
+    reason: AUTO_KEEP_REASON,
+    origin: FileDecisionOrigin.POLICY_APPROVED_COMMAND,
+  });
+  decision.id = `${cs.id}:${decisionScopeId(decision)}`;
+  return decision;
+}
+
+/**
+ * Checks the runner's consent claims against the records only the server
+ * writes. Every cited tool call must exist and carry a
+ * SubmitApproval-authored APPROVE or APPROVE_ALL; the auto_approve_all
+ * claim must match the spec-owned flag. At least one consent source is
+ * required — an empty claim authorizes nothing.
+ */
+function verifyCommandConsent(
+  status: AgentExecutionStatus,
+  provenance: TurnCommandProvenance,
+  autoApproveAll: boolean,
+): boolean {
+  if (provenance.authorizedByAutoApproveAll && !autoApproveAll) {
+    return false;
+  }
+  const ids = provenance.consentToolCallIds;
+  if (ids.length === 0 && !provenance.authorizedByAutoApproveAll) {
+    return false;
+  }
+  for (const id of ids) {
+    const tc = findToolCall(status, id);
+    if (tc === undefined) {
+      return false;
+    }
+    switch (tc.approvalAction) {
+      case ApprovalAction.APPROVE:
+      case ApprovalAction.APPROVE_ALL:
+        // Server-authored consent — verified.
+        break;
+      default:
+        return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Locates a tool call by id across the transcript and sub-agent
+ * transcripts (a lease-granting APPROVE_ALL row may live in either).
+ */
+function findToolCall(
+  status: AgentExecutionStatus,
+  id: string,
+): ToolCall | undefined {
+  for (const msg of status.messages) {
+    for (const tc of msg.toolCalls) {
+      if (tc.id === id) {
+        return tc;
+      }
+    }
+  }
+  for (const sa of status.subAgentExecutions) {
+    for (const msg of sa.messages) {
+      for (const tc of msg.toolCalls) {
+        if (tc.id === id) {
+          return tc;
+        }
+      }
+    }
+  }
+  return undefined;
+}

package/src/domain/agentexecution/filereview/cas-blob.ts

@@ -0,0 +1,52 @@
+/**
+ * CAS-blob content-integrity verification — ports filereview/cas_blob.go.
+ * The runner content-addresses gitignored/non-git before/after bytes
+ * under artifacts/{execution_id}/filereview/cas/blobs/{sha256}; the
+ * trailing 64-char lowercase-hex segment IS the SHA-256 of the stored
+ * bytes, making the key self-verifying.
+ */
+import { sha256HexBytes } from "./digest.js";
+
+/**
+ * Strict lowercase hex to match the producer; an off-convention key is
+ * treated as non-CAS (skipped), never as a failure.
+ */
+const CAS_BLOB_KEY_PATTERN =
+  /^artifacts\/[^/]+\/filereview\/cas\/blobs\/([0-9a-f]{64})$/;
+
+/**
+ * The single, static, user-facing reason when a CAS blob's served bytes
+ * do not match the content address in its key — intentionally free of
+ * interpolated hashes or keys (safe to surface; diagnostics go to the
+ * caller's structured log; a static string lets the edition mirror
+ * tables assert exact equality).
+ */
+export const CAS_BLOB_CONTENT_MISMATCH_REASON =
+  "artifact content failed integrity verification: the stored bytes do not match the content address in the storage key";
+
+/**
+ * Why served bytes fail the content-address integrity check embedded in a
+ * CAS blob storage key, or "" when the read may be served. A pure,
+ * transport-free predicate whose non-empty reason the caller maps to a
+ * DATA_LOSS status.
+ *
+ * Fail-open on anything that is not a CAS blob key: git-substrate
+ * offloads, tool-call outputs, attachments, the CAS manifest, or any
+ * future convention all return "" and are served untouched. The caller
+ * MUST pass the COMPLETE object bytes (a truncated read cannot be
+ * full-hash-verified, so the caller skips verification in that case).
+ * Enforcement only, never a correlation key.
+ */
+export function casBlobContentMismatch(
+  storageKey: string,
+  content: Uint8Array,
+): string {
+  const m = CAS_BLOB_KEY_PATTERN.exec(storageKey);
+  if (m === null) {
+    return "";
+  }
+  if (sha256HexBytes(content) === m[1]) {
+    return "";
+  }
+  return CAS_BLOB_CONTENT_MISMATCH_REASON;
+}

package/src/domain/agentexecution/filereview/digest.ts

@@ -0,0 +1,58 @@
+/**
+ * The canonical file-change digests — ports filereview/digest.go. The
+ * filereview module is the backend half of the apply-then-review
+ * file-change subsystem: it owns the canonical change digests, authors
+ * FILE_DECIDED events on the append-only file_review ledger, and projects
+ * FileChangeSet from that ledger — the approval package's append-only
+ * discipline instantiated for a second lifecycle.
+ *
+ * FileDigest is the enforcement key the runner's reconcile checks before
+ * applying a decision ("what you approve is what gets applied"); NEVER a
+ * correlation key (correlation is by CapturedFileChange.id). The
+ * canonical form digests the content HASHES, not raw bytes, so the string
+ * is pure ASCII with no encoding ambiguity across editions. kind renders
+ * as the proto enum value name (Go .String() / Java name()). The format
+ * is locked by apis/testdata/hitl/file-digest/vectors.json.
+ */
+import { createHash } from "node:crypto";
+
+import { enumToJson } from "@bufbuild/protobuf";
+
+import { FileChangeKindSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { CapturedFileChange } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+
+export function fileDigest(c: CapturedFileChange): string {
+  const canonical = [
+    c.pathBefore,
+    c.pathAfter,
+    enumToJson(FileChangeKindSchema, c.kind) as string,
+    c.beforeSha256,
+    c.afterSha256,
+  ].join("\n");
+  return sha256Hex(canonical);
+}
+
+/**
+ * The canonical digest over a change set's whole manifest. Per-file
+ * digests are sorted so the result is independent of input order (a
+ * change set is an unordered set of files for identity). The empty set
+ * hashes the empty string. Enforcement only, never a correlation key.
+ */
+export function aggregateDigest(changes: CapturedFileChange[]): string {
+  const digests = changes.map(fileDigest);
+  digests.sort();
+  return sha256Hex(digests.join("\n"));
+}
+
+function sha256Hex(s: string): string {
+  return createHash("sha256").update(s, "utf-8").digest("hex");
+}
+
+/**
+ * The raw-bytes content address CAS blobs are keyed by (Node
+ * createHash("sha256").digest("hex") — lowercase hex, exactly Go's
+ * hex.EncodeToString).
+ */
+export function sha256HexBytes(b: Uint8Array): string {
+  return createHash("sha256").update(b).digest("hex");
+}

package/src/domain/agentexecution/filereview/gate.ts

@@ -0,0 +1,68 @@
+/**
+ * The unified HITL resume gate — ports filereview/gate.go. Two lifecycles
+ * can block a single turn: tool approvals (pending_approvals) and file
+ * review (file_change_sets awaiting a human decision); a turn is
+ * unblocked only when BOTH are clear. These helpers are the one place
+ * that truth is computed, so the workflow's wake condition,
+ * SubmitApproval's signal, and SubmitFileDecision's signal can never
+ * disagree about whether the turn may resume.
+ */
+import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { FileChangeSetStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { FileChangeSet } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+
+/**
+ * How many change sets still wait on a human decision (AWAITING_REVIEW).
+ * A CAPTURING set is mid-turn (the runner has not returned yet) and a
+ * DECIDED/RECONCILED/FAILED set no longer blocks the gate, so neither
+ * counts.
+ */
+export function countAwaitingReview(changeSets: FileChangeSet[]): number {
+  let n = 0;
+  for (const cs of changeSets) {
+    if (cs.status === FileChangeSetStatus.AWAITING_REVIEW) {
+      n++;
+    }
+  }
+  return n;
+}
+
+/** Whether the file-review sub-gate is clear. */
+export function noChangeSetAwaitingReview(
+  status: AgentExecutionStatus,
+): boolean {
+  return countAwaitingReview(status.fileChangeSets) === 0;
+}
+
+/**
+ * The size of the combined HITL gate: tool calls still awaiting approval
+ * plus change sets still awaiting review. The workflow waits while this
+ * is > 0 and re-invokes the runner once it reaches 0.
+ */
+export function unresolvedGateCount(status: AgentExecutionStatus): number {
+  return (
+    status.pendingApprovals.length +
+    countAwaitingReview(status.fileChangeSets)
+  );
+}
+
+/** Whether the combined HITL gate is fully clear — the turn may resume. */
+export function gateResolved(status: AgentExecutionStatus): boolean {
+  return unresolvedGateCount(status) === 0;
+}
+
+/**
+ * Whether some change set is DECIDED — verdicts recorded, runner
+ * reconcile still owed. The workflow's wait loop uses this to tell a
+ * LEGITIMATE empty gate from a broken one (a set decided before the gate
+ * check — the DD-28 auto-keep or a fast human — leaves phase
+ * WAITING_FOR_APPROVAL with a zero gate count; the correct response is an
+ * immediate re-invoke to reconcile, never the empty-gate anomaly path).
+ */
+export function hasDecidedAwaitingReconcile(
+  status: AgentExecutionStatus,
+): boolean {
+  return status.fileChangeSets.some(
+    (cs) => cs.status === FileChangeSetStatus.DECIDED,
+  );
+}

package/src/domain/agentexecution/filereview/progress.ts

@@ -0,0 +1,51 @@
+/**
+ * ReconcileFileChangeProgress — ports filereview/progress.go: the
+ * defense-in-depth clear for the transient
+ * AgentExecutionStatus.file_change_progress field (mid-run live capture,
+ * DD-32).
+ *
+ * Progress is a runner-owned, latest-snapshot DISPLAY field (the
+ * file-review analogue of setup_progress), NOT part of the append-only
+ * ledger. The runner overwrites it on each mid-run persist while its
+ * change set is CAPTURING; this seam clears it once that set leaves
+ * CAPTURING, so a stale mid-run delta never outlives the turn.
+ *
+ * It runs AFTER projectFileChangeSets so it reads the just-folded
+ * projection: progress is KEPT only while a CAPTURING change set with the
+ * matching change_set_id exists. A terminal execution is subsumed — the
+ * projection is empty there. Keying on change_set_id (not merely "any
+ * CAPTURING set") is what makes resume correct: a new turn's new set id
+ * no longer matches the stale prior-turn progress, which clears.
+ */
+import { FileChangeSetStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type {
+  FileChangeProgress,
+  FileChangeSet,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+
+export function reconcileFileChangeProgress(
+  sets: FileChangeSet[],
+  progress: FileChangeProgress | undefined,
+): FileChangeProgress | undefined {
+  if (progress === undefined) {
+    return undefined;
+  }
+  if (hasCapturingSet(sets, progress.changeSetId)) {
+    return progress;
+  }
+  return undefined;
+}
+
+function hasCapturingSet(
+  sets: FileChangeSet[],
+  changeSetId: string,
+): boolean {
+  if (changeSetId === "") {
+    return false;
+  }
+  return sets.some(
+    (cs) =>
+      cs.id === changeSetId &&
+      cs.status === FileChangeSetStatus.CAPTURING,
+  );
+}

package/src/domain/agentexecution/filereview/project.ts

@@ -0,0 +1,171 @@
+/**
+ * The file-change-set projection SEAM — ports filereview/project.go.
+ *
+ * projectFileChangeSets is the single entry point every status writer
+ * uses to recompute AgentExecutionStatus.file_change_sets from the
+ * append-only file_review ledger — exactly as projectPendingApprovals is
+ * for approvals. A PURE read: authoring is the capture/reconcile
+ * activities' and recordFileDecisionEvent's job, run before this
+ * projection.
+ *
+ * Unlike the approval seam there is NO scan cross-check and NO divergence
+ * counter: file review is a greenfield, single-source ledger (no legacy
+ * second representation exists to disagree with). The cross-edition
+ * parity guard is the shared corpus.
+ *
+ * "Actionable" is execution-phase-aware: a terminal execution has no
+ * actionable review (the workflow that would reconcile is gone), so the
+ * seam returns empty for a terminal phase. The durable audit trail lives
+ * in the ledger, always preserved regardless of phase.
+ */
+import { create } from "@bufbuild/protobuf";
+
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  FileChangeSetStatus,
+  FileDecisionScope,
+  FileReviewEventType,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type {
+  FileChangeSet,
+  FileReviewEvent,
+  FileReviewEventStream,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import { FileChangeSetSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+
+export function projectFileChangeSets(
+  phase: ExecutionPhase,
+  stream: FileReviewEventStream | undefined,
+): FileChangeSet[] {
+  if (isTerminalExecution(phase)) {
+    return [];
+  }
+  if (stream === undefined || stream.events.length === 0) {
+    return [];
+  }
+
+  const order: string[] = [];
+  const byId = new Map<string, FileChangeSet>();
+  for (const ev of stream.events) {
+    const csId = ev.changeSetId;
+    if (csId === "") {
+      continue;
+    }
+    let cs = byId.get(csId);
+    if (cs === undefined) {
+      cs = create(FileChangeSetSchema, { id: csId });
+      byId.set(csId, cs);
+      order.push(csId);
+    }
+    applyEvent(cs, ev);
+  }
+
+  return order.map((id) => byId.get(id) as FileChangeSet);
+}
+
+/**
+ * Folds a single ledger event into the change set being built. Event
+ * order is the ledger order; terminal events (RECONCILED / FAILED) set a
+ * terminal status that later non-terminal recomputation does not
+ * override.
+ */
+function applyEvent(cs: FileChangeSet, ev: FileReviewEvent): void {
+  switch (ev.eventType) {
+    case FileReviewEventType.BASELINE_CAPTURED: {
+      if (ev.payload.case === "baselineCaptured") {
+        const b = ev.payload.value;
+        cs.turnId = b.turnId;
+        cs.harnessId = b.harnessId;
+        cs.baselineSnapshot = b.baselineSnapshot;
+      }
+      cs.status = FileChangeSetStatus.CAPTURING;
+      break;
+    }
+    case FileReviewEventType.CANDIDATE_CAPTURED: {
+      if (ev.payload.case === "candidateCaptured") {
+        const c = ev.payload.value;
+        cs.candidateSnapshot = c.candidateSnapshot;
+        cs.changes = c.changes;
+        cs.aggregateDigest = c.aggregateDigest;
+        cs.diffCompleteness = c.diffCompleteness;
+      }
+      cs.status = deriveStatusAfterCandidate(cs);
+      break;
+    }
+    case FileReviewEventType.FILE_DECIDED: {
+      if (ev.payload.case === "fileDecided") {
+        cs.decisions.push(ev.payload.value);
+      }
+      cs.status = deriveStatusAfterCandidate(cs);
+      break;
+    }
+    case FileReviewEventType.RECONCILED: {
+      if (ev.payload.case === "reconciled") {
+        cs.approvedSnapshot = ev.payload.value.approvedSnapshot;
+      }
+      cs.status = FileChangeSetStatus.RECONCILED;
+      break;
+    }
+    case FileReviewEventType.FAILED: {
+      cs.status = FileChangeSetStatus.FAILED;
+      break;
+    }
+    default:
+      break;
+  }
+}
+
+/**
+ * The non-terminal status once a candidate exists: DECIDED when every
+ * change is decided, otherwise AWAITING_REVIEW (partially-decided sets
+ * stay actionable). Never downgrades a terminal status.
+ */
+function deriveStatusAfterCandidate(cs: FileChangeSet): FileChangeSetStatus {
+  switch (cs.status) {
+    case FileChangeSetStatus.RECONCILED:
+    case FileChangeSetStatus.FAILED:
+      return cs.status;
+    default:
+      break;
+  }
+  if (isFullyDecided(cs)) {
+    return FileChangeSetStatus.DECIDED;
+  }
+  return FileChangeSetStatus.AWAITING_REVIEW;
+}
+
+/**
+ * Whether every change in the set has a verdict: either a
+ * CHANGE_SET-scoped decision (covers all), or a FILE decision per change.
+ */
+function isFullyDecided(cs: FileChangeSet): boolean {
+  if (cs.changes.length === 0) {
+    return false;
+  }
+  const decidedFiles = new Set<string>();
+  for (const d of cs.decisions) {
+    if (d.scope === FileDecisionScope.CHANGE_SET) {
+      return true;
+    }
+    if (d.scope === FileDecisionScope.FILE) {
+      decidedFiles.add(d.fileChangeId);
+    }
+  }
+  return cs.changes.every((c) => decidedFiles.has(c.id));
+}
+
+/**
+ * Mirrors the approval package's terminal-phase set exactly, so the two
+ * projections collapse identically on a dead execution.
+ */
+export function isTerminalExecution(phase: ExecutionPhase): boolean {
+  switch (phase) {
+    case ExecutionPhase.EXECUTION_COMPLETED:
+    case ExecutionPhase.EXECUTION_FAILED:
+    case ExecutionPhase.EXECUTION_CANCELLED:
+    case ExecutionPhase.EXECUTION_TERMINATED:
+      return true;
+    default:
+      return false;
+  }
+}