@stigmer/server 3.14.0-dev.20260910084630

package/src/domain/workflowexecution/subscribe.ts

@@ -0,0 +1,172 @@
+/**
+ * Subscribe — ports controller/subscribe.go: the real-time
+ * workflow-execution stream (ADR 011 read path), streaming full
+ * WorkflowExecution snapshots. The generator shape follows the sibling
+ * agentexecution subscribe (itself derived from transport/health.ts
+ * watch); every delivery rule ports verbatim:
+ *
+ *   - REGISTER-BEFORE-SNAPSHOT (the gap fix): the broker registration
+ *     happens before the snapshot read. Store writes serialize under the
+ *     per-resource write lock and UpdateStatus/lifecycle broadcast only
+ *     after their persist commits, so any commit the snapshot missed
+ *     broadcasts after our registration — nothing lands in the old lossy
+ *     window (Go keeps registration and the loop in ONE step for the same
+ *     reason; here the generator's finally owns the unsubscribe).
+ *   - The overlap frame (a commit the snapshot DID observe) arrives
+ *     value-equal to the snapshot; the consecutive-duplicate guard drops
+ *     it (Go sameFrame/proto.Equal) so clients never re-render an
+ *     identical state.
+ *   - The stream ends on a terminal BROADCAST frame; a terminal SNAPSHOT
+ *     leaves the stream open (Go sends the snapshot and parks in the
+ *     loop). Faithful port.
+ *   - The terminal set is COMPLETED/FAILED/CANCELLED — it OMITS
+ *     TERMINATED, so a stream over a terminated execution never
+ *     self-closes. Known Go quirk (isWorkflowTerminalPhase,
+ *     subscribe.go:216), ported byte-faithfully; disclosed as a
+ *     both-editions issue candidate, the same finding #17 made on
+ *     agentexecution.
+ */
+import { equals } from "@bufbuild/protobuf";
+import type { HandlerContext } from "@connectrpc/connect";
+
+import { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import type { WorkflowExecution } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import type { SubscribeWorkflowExecutionRequest } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import { WorkflowExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/query_pb";
+
+import type { Logger } from "../../boot/logger.js";
+import type { Authorizer } from "../../extensions/authorizer.js";
+import { callerIdentityOf } from "../../pipeline/interceptors/auth.js";
+import { invalidArgumentError, notFoundError } from "../../pipeline/errors.js";
+import { authorizeDirect } from "../../pipeline/steps/authorize.js";
+import type { Store } from "../../store/interface.js";
+
+import type { StreamBroker } from "./stream-broker.js";
+
+export interface SubscribeDeps {
+  readonly store: Store;
+  readonly logger: Logger;
+  readonly broker: StreamBroker;
+  /** The composed authorization seam — the pre-stream check below (C2 Stage 4). */
+  readonly authorizer: Authorizer;
+}
+
+/**
+ * Go isWorkflowTerminalPhase (subscribe.go): the stream-closing set.
+ * Deliberately narrower than "the execution can never run again" —
+ * TERMINATED and PAUSED are absent (TERMINATED being the disclosed
+ * quirk).
+ */
+export function isWorkflowTerminalPhase(phase: ExecutionPhase): boolean {
+  return (
+    phase === ExecutionPhase.EXECUTION_COMPLETED ||
+    phase === ExecutionPhase.EXECUTION_FAILED ||
+    phase === ExecutionPhase.EXECUTION_CANCELLED
+  );
+}
+
+export async function* subscribeExecution(
+  deps: SubscribeDeps,
+  request: SubscribeWorkflowExecutionRequest,
+  context: HandlerContext,
+): AsyncGenerator<WorkflowExecution> {
+  // Go ValidateSubscribeInputStep.
+  if (request.executionId === "") {
+    throw invalidArgumentError("execution_id is required");
+  }
+  // The annotation's can_view check, once at subscription start — the
+  // stream cannot run inside the pipeline executor, so the Authorize
+  // evaluation runs here directly (the Java subscribe handlers' validate →
+  // authorize order; C2 Stage 4).
+  await authorizeDirect(
+    WorkflowExecutionQueryController.method.subscribe,
+    deps.authorizer,
+    callerIdentityOf(context),
+    request,
+  );
+  const id = request.executionId;
+  deps.logger.info("Starting workflow execution subscription", {
+    executionId: id,
+  });
+
+  // Register FIRST so no broadcast can slip through the window before the
+  // snapshot read (the happens-before argument in the module header).
+  const subscription = deps.broker.subscribe(id);
+  try {
+    let snapshot: WorkflowExecution;
+    try {
+      snapshot = await deps.store.getResource(
+        ApiResourceKind.workflow_execution,
+        id,
+        WorkflowExecutionSchema,
+      );
+    } catch {
+      // Go converts every load failure here to the same NotFound.
+      throw notFoundError("WorkflowExecution", id);
+    }
+
+    yield snapshot;
+    deps.logger.debug(
+      "Sent initial workflow execution state, streaming live updates",
+      { executionId: id },
+    );
+
+    // The consecutive-duplicate anchor (Go lastSent).
+    let lastSent = snapshot;
+
+    const abort = new Promise<void>((resolve) => {
+      context.signal.addEventListener("abort", () => resolve(), {
+        once: true,
+      });
+    });
+
+    while (!context.signal.aborted) {
+      if (subscription.closed) {
+        // Go's closed-channel arm: end quietly.
+        deps.logger.warn("Updates channel closed unexpectedly", {
+          executionId: id,
+        });
+        return;
+      }
+      if (subscription.queue.length === 0) {
+        await Promise.race([
+          abort,
+          new Promise<void>((resolve) => (subscription.notify = resolve)),
+        ]);
+        subscription.notify = undefined;
+        continue;
+      }
+
+      const updated = subscription.queue.shift();
+      if (updated === undefined) {
+        continue;
+      }
+      // Suppress the at-or-before-snapshot overlap frame (and any other
+      // exact repeat) so the client never re-renders an identical state.
+      if (equals(WorkflowExecutionSchema, updated, lastSent)) {
+        continue;
+      }
+
+      yield updated;
+      lastSent = updated;
+
+      const phase =
+        updated.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+      if (isWorkflowTerminalPhase(phase)) {
+        deps.logger.info(
+          "Workflow execution reached terminal state, ending subscription",
+          { executionId: id, phase: ExecutionPhase[phase] },
+        );
+        return;
+      }
+    }
+    deps.logger.info("Workflow execution subscription cancelled by client", {
+      executionId: id,
+    });
+  } finally {
+    deps.broker.unsubscribe(id, subscription);
+  }
+}

package/src/domain/workflowexecution/temporal/config.ts

@@ -0,0 +1,129 @@
+/**
+ * Workflow-execution Temporal config — ports
+ * pkg/domain/workflowexecution/temporal/config.go: the queue names,
+ * routing mode, and default execution target for workflow-execution
+ * dispatch.
+ *
+ * The tree corresponds to Go's (config lives with the domain, like
+ * src/domain/agentexecution/temporal/config.ts); the Temporal-importing
+ * slice (worker, workflow, engine client) lives in
+ * src/temporal/workflowexecution/.
+ *
+ * resolveWorkflowExecutionTarget is the single definition of the
+ * UNSPECIFIED-resolution rule for WORKFLOW executions (Go
+ * resolveWorkflowExecutionTarget) — dispatch resolution (#21's engine)
+ * is its one consumer today; a future policy consumer must use it rather
+ * than re-derive the default, the same one-definition discipline the
+ * agentexecution config records (oss#397).
+ */
+import { ExecutionTarget } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
+
+/**
+ * Routes all child workflows to the shared global runner queue
+ * (runnerQueue, default stigmer_runner) — the default for OSS local
+ * development where a single runner polls one queue (Go RoutingGlobal).
+ */
+export const WORKFLOW_ROUTING_GLOBAL = "global";
+
+/**
+ * Derives a per-execution task queue (wfexec:{execution_id}) for each
+ * workflow execution — for deployments where each execution gets a
+ * dedicated runner (cloud sandboxes, or the desktop runner-manager's
+ * per-execution workers; Go RoutingExecution).
+ */
+export const WORKFLOW_ROUTING_EXECUTION = "execution";
+
+/**
+ * Resolves UNSPECIFIED to LOCAL — OSS/self-hosted deployments (Go
+ * DefaultExecutionTargetLocal).
+ */
+export const WORKFLOW_DEFAULT_EXECUTION_TARGET_LOCAL = "local";
+
+/**
+ * Resolves UNSPECIFIED to CLOUD — the managed cloud service (Go
+ * DefaultExecutionTargetCloud).
+ */
+export const WORKFLOW_DEFAULT_EXECUTION_TARGET_CLOUD = "cloud";
+
+/**
+ * Configuration for workflow-execution Temporal workers (Go
+ * temporal.Config).
+ *
+ * Queue architecture (worker_config.go's contract):
+ *   - stigmerQueue: this server's orchestrator workflows on
+ *     workflow_execution_stigmer
+ *   - runnerQueue: the TS unified runner's child workflows on
+ *     stigmer_runner (global) or wfexec:{id} (per-execution)
+ */
+export class WorkflowExecutionTemporalConfig {
+  constructor(
+    /**
+     * Task queue for the orchestrator workflows this server registers.
+     * Default: workflow_execution_stigmer.
+     */
+    readonly stigmerQueue: string,
+    /**
+     * Default task queue for the runner's child workflows
+     * (stigmer_runner). In global routing mode all children route here;
+     * in execution routing mode it is unused (every execution derives
+     * wfexec:{id}) but kept as the memo fallback Go keeps.
+     */
+    readonly runnerQueue: string,
+    /** WORKFLOW_ROUTING_GLOBAL or WORKFLOW_ROUTING_EXECUTION. */
+    readonly workflowActivityRouting: string,
+    /**
+     * Resolves EXECUTION_TARGET_UNSPECIFIED on workflow executions:
+     * LOCAL (the operator's runner polls the queue) or CLOUD (the server
+     * provisions a per-execution sandbox).
+     */
+    readonly defaultExecutionTarget: string,
+  ) {}
+
+  /**
+   * Resolves a workflow execution's execution_target to its effective
+   * target: UNSPECIFIED becomes the configured default; explicit values
+   * pass through unchanged (Go resolveWorkflowExecutionTarget).
+   */
+  resolveWorkflowExecutionTarget(target: ExecutionTarget): ExecutionTarget {
+    if (target !== ExecutionTarget.UNSPECIFIED) {
+      return target;
+    }
+    if (
+      this.defaultExecutionTarget === WORKFLOW_DEFAULT_EXECUTION_TARGET_CLOUD
+    ) {
+      return ExecutionTarget.CLOUD;
+    }
+    return ExecutionTarget.LOCAL;
+  }
+}
+
+/**
+ * Builds the config from environment variables with Go LoadConfig's
+ * defaults. Env-derived strings only — no Temporal connection is made
+ * here (the manager owns connections).
+ */
+export function newWorkflowExecutionConfigFromEnv(): WorkflowExecutionTemporalConfig {
+  return new WorkflowExecutionTemporalConfig(
+    valueOrDefault(
+      process.env.TEMPORAL_WORKFLOW_EXECUTION_STIGMER_TASK_QUEUE,
+      "workflow_execution_stigmer",
+    ),
+    valueOrDefault(
+      process.env.TEMPORAL_WORKFLOW_EXECUTION_RUNNER_TASK_QUEUE,
+      "stigmer_runner",
+    ),
+    valueOrDefault(
+      process.env.STIGMER_WORKFLOW_ACTIVITY_ROUTING,
+      WORKFLOW_ROUTING_GLOBAL,
+    ),
+    valueOrDefault(
+      process.env.STIGMER_WORKFLOW_DEFAULT_EXECUTION_TARGET,
+      WORKFLOW_DEFAULT_EXECUTION_TARGET_LOCAL,
+    ),
+  );
+}
+
+/** Go's `if v == "" { v = default }` idiom for env reads. */
+function valueOrDefault(value: string | undefined, fallback: string): string {
+  return value === undefined || value === "" ? fallback : value;
+}

package/src/domain/workflowexecution/update-status.ts

@@ -0,0 +1,396 @@
+/**
+ * UpdateStatus — ports controller/update_status.go: the runner's
+ * progressive status-update RPC (merge + persist + event append + stream
+ * broadcast — the OSS replacement for cloud's Redis write path).
+ *
+ * Chain per Go: ValidateUpdateStatusInput → merge+persist → PersistEvents
+ * → BroadcastToStreams. Go still does the merge as a separate
+ * LoadExisting step followed by a plain SaveResource — a lost-update
+ * window under concurrent updates. This port runs the SAME merge body
+ * inside the store's atomic `updateResource` instead (sub-project DD-001,
+ * owner-ratified): Go's own agentexecution domain already calls that
+ * discipline load-bearing, and this domain's per-child pending-gate merge
+ * is exactly the concurrent-children write that the window can corrupt.
+ * Wire-identical in sequential flows; strictly safer under concurrency;
+ * the Go-side race is filed as an OSS issue.
+ *
+ * applyUpdateStatusMerge is the merge body run inside the updateResource
+ * closure (and exercised directly by the guard tests), mirroring the
+ * cloud handler's strategy: presence-guarded field merges (tasks replaced
+ * wholesale, counters only when > 0), the flag-gated per-child
+ * pending_approvals / pending_file_reviews merge, and the
+ * phase-transition-only statusAudit bump (heartbeats must not perpetually
+ * re-sort long-running executions above new ones in the recents sidebar).
+ *
+ * Versus Stigmer Cloud, OSS excludes the Authorize, PublishToRedis, and
+ * Publish steps (broadcast rides in-memory channels per ADR 011).
+ */
+import { create, toBinary } from "@bufbuild/protobuf";
+import { timestampNow } from "@bufbuild/protobuf/wkt";
+
+import type { WorkflowExecution } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import {
+  WorkflowExecutionSchema,
+  WorkflowExecutionStatusSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { WorkflowExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/command_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import { WorkflowEventType } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/event_pb";
+import { WorkflowExecutionEventSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/event_pb";
+import type { WorkflowExecutionUpdateStatusInput } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import {
+  ApiResourceAuditInfoSchema,
+  ApiResourceAuditSchema,
+} from "@stigmer/protos/ai/stigmer/commons/apiresource/status_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import type { Logger } from "../../boot/logger.js";
+import {
+  internalError,
+  invalidArgumentError,
+  notFoundError,
+} from "../../pipeline/errors.js";
+import { newPipeline } from "../../pipeline/pipeline.js";
+import type { Authorizer } from "../../extensions/authorizer.js";
+import { newAuthorizeStep } from "../../pipeline/steps/authorize.js";
+import type { CallerIdentity } from "../../extensions/identity.js";
+import { RequestContext } from "../../pipeline/request-context.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
+import type {
+  Store,
+  WorkflowExecutionEventRecord,
+} from "../../store/interface.js";
+import type { WorkflowSandboxTerminalObserver } from "../../sandbox/steps.js";
+
+import type { StreamBroker } from "./stream-broker.js";
+
+export interface UpdateStatusDeps {
+  readonly store: Store;
+  readonly logger: Logger;
+  /** The composed authorization seam — the Authorize step at position 1 of every chain calls it (O2, DD-007 §3). */
+  readonly authorizer: Authorizer;
+  readonly broker: StreamBroker;
+  /** Fires the workflow-sandbox teardown on terminal transitions (§6d, O6). */
+  readonly sandboxTerminalObserver: WorkflowSandboxTerminalObserver;
+}
+
+type UpdateStatusDesc =
+  typeof WorkflowExecutionCommandController.method.updateStatus.input;
+
+const EXECUTION_KEY = "execution";
+
+export async function updateStatus(
+  deps: UpdateStatusDeps,
+  input: WorkflowExecutionUpdateStatusInput,
+  identity: CallerIdentity,
+): Promise<WorkflowExecution> {
+  const reqCtx = new RequestContext(
+    WorkflowExecutionCommandController.method.updateStatus.input,
+    input,
+    identity,
+    ApiResourceKind.workflow_execution,
+  );
+  await newPipeline<UpdateStatusDesc>(
+    "workflowexecution-update-status",
+    deps.logger,
+  )
+    .addStep(
+      newAuthorizeStep(
+        WorkflowExecutionCommandController.method.updateStatus,
+        deps.authorizer,
+      ),
+    )
+    .addStep({
+      name: "ValidateUpdateStatusInput",
+      execute(ctx) {
+        if (ctx.input.executionId === "") {
+          throw invalidArgumentError("execution_id is required");
+        }
+        if (ctx.input.status === undefined) {
+          throw invalidArgumentError("status is required");
+        }
+      },
+    })
+    .addStep({
+      name: "MergeAndPersistExecution",
+      async execute(ctx) {
+        let updated: WorkflowExecution;
+        // Captured inside the modify closure — the phase BEFORE this
+        // merge, read under the same write lock that persists it (the
+        // sandbox observer below keys on the transition, §6d/O6).
+        let previousPhase = ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+        try {
+          updated = await deps.store.updateResource(
+            ApiResourceKind.workflow_execution,
+            ctx.input.executionId,
+            WorkflowExecutionSchema,
+            (execution) => {
+              previousPhase =
+                execution.status?.phase ??
+                ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
+              applyUpdateStatusMerge(execution, ctx.input);
+            },
+          );
+        } catch (error) {
+          if (error instanceof ResourceNotFoundError) {
+            // Go's LoadExistingExecution answers this exact NotFound.
+            throw notFoundError("WorkflowExecution", ctx.input.executionId);
+          }
+          throw internalError(error, "failed to update execution status");
+        }
+        ctx.set(EXECUTION_KEY, updated);
+        // AFTER the persist commits: a terminal transition tears the
+        // per-execution sandbox down, fire-and-forget.
+        deps.sandboxTerminalObserver(
+          ctx.input.executionId,
+          previousPhase,
+          updated.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED,
+        );
+        deps.logger.info("Successfully updated execution status", {
+          executionId: ctx.input.executionId,
+          phase:
+            ExecutionPhase[
+              updated.status?.phase ??
+                ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED
+            ],
+        });
+      },
+    })
+    .addStep({
+      name: "PersistEvents",
+      async execute(ctx) {
+        await persistEvents(deps, ctx.input);
+      },
+    })
+    .addStep({
+      name: "BroadcastToStreams",
+      execute(ctx) {
+        const execution = ctx.get(EXECUTION_KEY);
+        if (execution === undefined) {
+          throw internalError(
+            new Error("execution not found in context"),
+            "execution not found in context",
+          );
+        }
+        // Push to active subscribers AFTER the persist commits (ADR 011
+        // write path) — the ordering subscribe's register-before-snapshot
+        // guarantee builds on.
+        deps.broker.broadcast(execution as WorkflowExecution);
+      },
+    })
+    .build()
+    .execute(reqCtx);
+
+  const merged = reqCtx.get(EXECUTION_KEY);
+  if (merged === undefined) {
+    throw internalError(
+      new Error("execution not found in context after pipeline"),
+      "execution not found in context after pipeline",
+    );
+  }
+  return merged as WorkflowExecution;
+}
+
+/**
+ * mergePendingByChild — a per-child upsert of a workflow status list
+ * (pending_approvals or pending_file_reviews): drops the existing entries
+ * that belong to scopeChildId and appends the incoming entries (which
+ * must all belong to scopeChildId). Every other child's entries are
+ * preserved untouched, so parallel child agents surfacing/clearing their
+ * own gates never clobber each other. An empty incoming list therefore
+ * clears just scopeChildId's entries.
+ *
+ * childOf extracts an entry's owning child_agent_execution_id. Kept
+ * generic so the approval and file-review lists share exactly one merge
+ * semantic (Go's mergePendingByChild).
+ */
+export function mergePendingByChild<T>(
+  existing: readonly T[],
+  incoming: readonly T[],
+  childOf: (entry: T) => string,
+  scopeChildId: string,
+): T[] {
+  const merged: T[] = [];
+  for (const entry of existing) {
+    if (childOf(entry) !== scopeChildId) {
+      merged.push(entry);
+    }
+  }
+  merged.push(...incoming);
+  return merged;
+}
+
+/**
+ * The merge body run inside the updateResource closure — Go
+ * BuildNewStateWithStatusStep field-for-field. Mutates `execution` in
+ * place over the freshly-loaded, write-locked state. Synchronous by
+ * contract (the store's modify callback), which is also what makes it
+ * directly unit-testable.
+ */
+export function applyUpdateStatusMerge(
+  execution: WorkflowExecution,
+  input: WorkflowExecutionUpdateStatusInput,
+): void {
+  if (execution.status === undefined) {
+    execution.status = create(WorkflowExecutionStatusSchema);
+  }
+  const status = execution.status;
+  const requestStatus = input.status;
+  if (requestStatus === undefined) {
+    return;
+  }
+
+  // The phase-transition check compares against the phase BEFORE this
+  // merge writes it (Go compares to `existing`, its pre-clone snapshot).
+  const previousPhase = status.phase;
+
+  // Tasks: replaced wholesale with the runner's latest complete set.
+  if (requestStatus.tasks.length > 0) {
+    status.tasks = requestStatus.tasks;
+  }
+
+  if (requestStatus.phase !== ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED) {
+    status.phase = requestStatus.phase;
+  }
+  if (requestStatus.output !== undefined) {
+    status.output = requestStatus.output;
+  }
+  if (requestStatus.error !== "") {
+    status.error = requestStatus.error;
+  }
+  if (requestStatus.startedAt !== "") {
+    status.startedAt = requestStatus.startedAt;
+  }
+  if (requestStatus.completedAt !== "") {
+    status.completedAt = requestStatus.completedAt;
+  }
+  if (requestStatus.temporalWorkflowId !== "") {
+    status.temporalWorkflowId = requestStatus.temporalWorkflowId;
+  }
+
+  // Cost/token totals: the runner sends accumulated totals; zero means
+  // "no update", never "reset".
+  if (requestStatus.totalCostMicros > 0n) {
+    status.totalCostMicros = requestStatus.totalCostMicros;
+  }
+  if (requestStatus.totalInputTokens > 0n) {
+    status.totalInputTokens = requestStatus.totalInputTokens;
+  }
+  if (requestStatus.totalOutputTokens > 0n) {
+    status.totalOutputTokens = requestStatus.totalOutputTokens;
+  }
+
+  // Guarded, per-child merge: only touch pending_approvals /
+  // pending_file_reviews when explicitly requested, and even then replace
+  // only the scoped child's entries. This both prevents event emissions
+  // (which don't include these lists) from clobbering active gates set by
+  // call-agent-status, and prevents parallel child agents from clobbering
+  // each other's gates.
+  const scopeChildId = input.pendingUpdateChildAgentExecutionId;
+  if (input.updatePendingApprovals) {
+    status.pendingApprovals = mergePendingByChild(
+      status.pendingApprovals,
+      requestStatus.pendingApprovals,
+      (entry) => entry.childAgentExecutionId,
+      scopeChildId,
+    );
+  }
+  if (input.updatePendingFileReviews) {
+    status.pendingFileReviews = mergePendingByChild(
+      status.pendingFileReviews,
+      requestStatus.pendingFileReviews,
+      (entry) => entry.childAgentExecutionId,
+      scopeChildId,
+    );
+  }
+
+  // Only bump statusAudit.updatedAt on phase transitions — not on every
+  // task-progress heartbeat from the runner. This prevents long-running
+  // executions from perpetually sorting above freshly created ones in the
+  // recents sidebar (ActivityQueryController orders by this field).
+  // Mirrors the cloud's WorkflowExecutionUpdateStatusHandler exactly.
+  const isPhaseTransition =
+    requestStatus.phase !== ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED &&
+    requestStatus.phase !== previousPhase;
+  if (isPhaseTransition) {
+    const audit = status.audit ?? create(ApiResourceAuditSchema);
+    status.audit = audit;
+    const statusAudit = audit.statusAudit ?? create(ApiResourceAuditInfoSchema);
+    audit.statusAudit = statusAudit;
+    statusAudit.updatedAt = timestampNow();
+    statusAudit.event = "updated";
+  }
+}
+
+/**
+ * PersistEvents — appends the input's events to the event log. Events are
+ * supplementary: a failure here does NOT fail the pipeline because status
+ * persistence already succeeded. A real append failure means timeline
+ * data loss, so it logs at error level; skipped duplicates are the
+ * expected result of the runner's idempotent batch retries and only log
+ * at debug (the store's INSERT OR IGNORE first-writer-wins, oss#308).
+ */
+async function persistEvents(
+  deps: UpdateStatusDeps,
+  input: WorkflowExecutionUpdateStatusInput,
+): Promise<void> {
+  if (input.events.length === 0) {
+    return;
+  }
+  const executionId = input.executionId;
+
+  const records: WorkflowExecutionEventRecord[] = [];
+  for (const event of input.events) {
+    let data: Uint8Array;
+    try {
+      data = toBinary(WorkflowExecutionEventSchema, event);
+    } catch (error) {
+      deps.logger.error(
+        "Failed to marshal event — dropping batch (non-fatal, timeline data lost)",
+        {
+          executionId,
+          sequenceNumber: event.sequenceNumber,
+          eventCount: input.events.length,
+          error: error instanceof Error ? error.message : String(error),
+        },
+      );
+      return;
+    }
+    records.push({
+      executionId,
+      sequenceNumber: Number(event.sequenceNumber),
+      eventType: WorkflowEventType[event.eventType] ?? "",
+      taskName: event.taskName,
+      data,
+      createdAt: "",
+    });
+  }
+
+  let appended: number;
+  try {
+    appended = await deps.store.appendWorkflowExecutionEvents(
+      executionId,
+      records,
+    );
+  } catch (error) {
+    deps.logger.error(
+      "Failed to persist execution events (non-fatal, timeline data lost)",
+      {
+        executionId,
+        submitted: records.length,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    );
+    return;
+  }
+
+  const skipped = records.length - appended;
+  if (skipped > 0) {
+    deps.logger.debug(
+      "Persisted execution events (idempotent retry skipped already-persisted sequences)",
+      { executionId, appended, skippedDuplicates: skipped },
+    );
+  } else {
+    deps.logger.debug("Persisted execution events", { executionId, appended });
+  }
+}