@stigmer/server 3.14.0-dev.20260910084630

package/src/domain/agentexecution/phases.ts

@@ -0,0 +1,39 @@
+/**
+ * The domain's TWO deliberately-distinct terminal-phase predicates —
+ * package-level functions in Go (subscribe.go / tool_call_settle.go),
+ * shared here so every consumer names the same sets.
+ *
+ * isTerminalExecutionPhase answers "will this execution ever run again?"
+ * — COMPLETED / FAILED / CANCELLED / TERMINATED. TERMINATED executions
+ * will not run, so their in-flight tool calls must settle and their
+ * phase latches.
+ *
+ * isTranscriptTerminalPhase (Go subscribe.go isTerminalPhase) OMITS
+ * TERMINATED: the transcript regression guard uses it so a terminated
+ * execution's committed transcript stays protected from free rewrites,
+ * and the subscribe stream uses it as its close set (the disclosed
+ * never-closes-on-TERMINATED quirk, ported faithfully). Do NOT
+ * "harmonize" the two — the difference is deliberate and documented in
+ * Go.
+ */
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+export function isTerminalExecutionPhase(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;
+  }
+}
+
+export function isTranscriptTerminalPhase(phase: ExecutionPhase): boolean {
+  return (
+    phase === ExecutionPhase.EXECUTION_COMPLETED ||
+    phase === ExecutionPhase.EXECUTION_FAILED ||
+    phase === ExecutionPhase.EXECUTION_CANCELLED
+  );
+}

package/src/domain/agentexecution/record-runner-lineage-labels.ts

@@ -0,0 +1,76 @@
+/**
+ * RecordRunnerLineageLabels — the agent-execution create chain's
+ * lineage-label vouching step (the Java
+ * AgentExecutionCreateHandler.RecordRunnerLineageLabelsStep port,
+ * cloud#386; parity entry 20260830.05, C5 readout finding F3).
+ *
+ * The workflow runner's CallAgent activity
+ * (backend/services/runner/src/activities/call-agent.ts) stamps
+ * `stigmer.ai/workflow-execution-id` and `stigmer.ai/workflow-task` on
+ * every child execution it creates — the lineage the agent_call
+ * environment resolution keys on. GuardReservedLabels would reject that
+ * create outright (the guard predates the runner sender and never got
+ * the matching exemption — in OSS the permissive default Authorizer
+ * masks this; a composition with a real Authorizer refuses).
+ *
+ * The step records EXACTLY the two lineage keys through
+ * server-stamped-reserved-labels.ts, and only when the composed
+ * RunnerCredentialProvider's vouchRunnerLineageLabels capability vouches
+ * for the caller — the capability owns both caller classification (its
+ * own token-type vocabulary; no caller class expresses "runner" and OSS
+ * must not learn another edition's lane names) and the binding rule (a
+ * workflow-bound credential may only stamp its own workflow execution;
+ * the capability REFUSES a mismatch by throwing). With no capability
+ * composed nothing is vouched, which is byte-identical OSS behavior.
+ *
+ * Placement: after BuildNewState (the labels inspected are the ones the
+ * guard will diff), immediately before GuardReservedLabels. Non-runner
+ * callers vouch nothing and stay fully subject to the guard — a client
+ * sending these same keys itself is still rejected.
+ */
+import type { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+
+import type { PipelineStep } from "../../pipeline/pipeline.js";
+import type { RequestContext } from "../../pipeline/request-context.js";
+import { recordServerStampedReservedLabels } from "../../pipeline/steps/server-stamped-reserved-labels.js";
+import { metadataOf } from "../../pipeline/steps/shapes.js";
+import type { RunnerCredentialProvider } from "../../runnerauth/runner-credential-provider.js";
+
+/**
+ * The lineage label keys, byte-pinned on three sides: the runner's
+ * CallAgent stamp, the Java ExecutionEnvironmentComposer's resolution
+ * read, and this vouching step.
+ */
+export const WORKFLOW_EXECUTION_ID_LABEL = "stigmer.ai/workflow-execution-id";
+export const WORKFLOW_TASK_LABEL = "stigmer.ai/workflow-task";
+
+export function newRecordRunnerLineageLabelsStep(
+  provider: RunnerCredentialProvider,
+): PipelineStep<typeof AgentExecutionSchema> {
+  return {
+    name: "RecordRunnerLineageLabels",
+    execute(ctx: RequestContext<typeof AgentExecutionSchema>): void {
+      const vouch = provider.vouchRunnerLineageLabels;
+      if (vouch === undefined) {
+        return;
+      }
+      const labels = metadataOf(ctx.newState)?.labels ?? {};
+      const workflowExecutionId = labels[WORKFLOW_EXECUTION_ID_LABEL] ?? "";
+      const taskName = labels[WORKFLOW_TASK_LABEL] ?? "";
+      if (workflowExecutionId === "" && taskName === "") {
+        return;
+      }
+      // The capability throws its own byte-pinned refusal on a binding
+      // violation; false means "not a runner credential" — vouch nothing.
+      if (!vouch.call(provider, ctx.callerIdentity, workflowExecutionId)) {
+        return;
+      }
+      if (workflowExecutionId !== "") {
+        recordServerStampedReservedLabels(ctx, WORKFLOW_EXECUTION_ID_LABEL);
+      }
+      if (taskName !== "") {
+        recordServerStampedReservedLabels(ctx, WORKFLOW_TASK_LABEL);
+      }
+    },
+  };
+}

package/src/domain/agentexecution/search-extractor.ts

@@ -0,0 +1,70 @@
+/**
+ * AgentExecution search extractor — ports pkg/query/search/extractor/
+ * agent_execution_extractor.go (both sides: the #4 index side, the #14
+ * query side). Agent executions are individual invocation records with no
+ * description field. Go's GetSearchSummary returns metadata.name, but BOTH
+ * projections deliberately ignore it: ToSearchResult pins Description ""
+ * (extractor line 59) and GetSearchIndexEntry leaves the FTS description
+ * at its zero value — the name is already the top-weighted indexed column.
+ * That asymmetry is Go's, ported as-is.
+ */
+import type { Message } from "@bufbuild/protobuf";
+
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import type { SearchResult } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+
+import type { SearchIndexEntry } from "../../store/interface.js";
+import { buildSearchResult } from "../../query/search/extractor.js";
+import type { SearchableExtractor } from "../../query/search/extractor.js";
+
+export const agentExecutionSearchExtractor: SearchableExtractor = {
+  kind: ApiResourceKind.agent_execution,
+  schema: AgentExecutionSchema,
+
+  getSearchSummary(resource: Message): string {
+    // Go AgentExecutionExtractor.GetSearchSummary: metadata.name. Neither
+    // projection consumes it (see the header) — the interface contract is
+    // still served for any caller that does.
+    const execution = resource as unknown as AgentExecution;
+    return execution.metadata?.name ?? "";
+  },
+
+  toSearchResult(resource: Message, score: number): SearchResult | undefined {
+    const execution = resource as unknown as AgentExecution;
+    return buildSearchResult({
+      kind: ApiResourceKind.agent_execution,
+      metadata: execution.metadata,
+      // Go pins Description "" here — NOT GetSearchSummary.
+      summary: "",
+      score,
+      createdAt: execution.status?.audit?.specAudit?.createdAt,
+      updatedAt: execution.status?.audit?.specAudit?.updatedAt,
+    });
+  },
+
+  getSearchIndexEntry(resource: Message): SearchIndexEntry | undefined {
+    const execution = resource as unknown as AgentExecution;
+    const metadata = execution.metadata;
+    if (metadata === undefined) {
+      return undefined;
+    }
+    return {
+      name: metadata.name,
+      // No description field on executions (Go leaves entry.Description
+      // at its zero value).
+      description: "",
+      // Tags join space-separated — the index entry carries one tags
+      // string (Go extractor.JoinTags).
+      tags: metadata.tags.join(" "),
+      org: metadata.org,
+      // The enum NAME string, exactly Go's visibility.String().
+      visibility: ApiResourceVisibility[metadata.visibility] ?? "",
+      createdAt: Number(
+        execution.status?.audit?.specAudit?.createdAt?.seconds ?? 0n,
+      ),
+    };
+  },
+};

package/src/domain/agentexecution/status-observers.ts

@@ -0,0 +1,108 @@
+/**
+ * Status-observer notification — the domain-owned consumer of the
+ * extension registry's status-transition hooks (blueprint 03 §7, DD-006
+ * §3; O4 plan-gate ruling Q3, 20260827.07).
+ *
+ * The blueprint drafted the hook "at the updateStatus chokepoint", but
+ * the verified reality is FIVE phase-transition persist sites, and a
+ * finalize observer that misses any of them misses exactly what it
+ * exists to settle (user cancels/terminations, start-failure FAILED,
+ * workflow-gone FAILED). The ruled design: this ONE notifier is invoked
+ * from every site — the site list below is the exhaustive contract,
+ * re-verified whenever a new phase write appears:
+ *   1. update-status.ts       — the runner's merge chokepoint;
+ *   2. lifecycle.ts           — the phase-transition persist step
+ *                               (cancel/terminate/pause/resume/recover);
+ *   3. create-steps.ts        — the StartWorkflow failure arm (FAILED);
+ *   4. submit-approval.ts     — reconcileStaleExecution (FAILED);
+ *   5. submit-file-decision.ts — the file-review reconcile twin (FAILED).
+ * Initial-phase stamping at creation (SetInitialPhase → PENDING) is by
+ * definition not a transition and does not notify.
+ *
+ * Contract rendered here (status-hooks.ts carries the ratified text):
+ *   - fires only when the phase actually changed (ruling Q4 — runner
+ *     progress reports repeat the phase many times per execution; the
+ *     terminal-vs-not filter stays with the observer);
+ *   - observers run in registration order and are awaited, so every
+ *     observer completes before the caller proceeds to broadcast —
+ *     "StreamBroker.broadcast stays last" holds for async observers too;
+ *   - a throwing/rejecting observer is an extension bug logged here,
+ *     NEVER a failed transition (the cloud's expiry sweep remains the
+ *     reconciliation backstop).
+ */
+import { clone } from "@bufbuild/protobuf";
+
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { UpdateStatusResponse } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { UpdateStatusResponseSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+
+import type { Logger } from "../../boot/logger.js";
+import type {
+  AgentExecutionResponseDecorator,
+  AgentExecutionStatusObserver,
+} from "../../extensions/status-hooks.js";
+
+/** The deps every notifying site threads (a slice of its own deps). */
+export interface StatusObserverDeps {
+  readonly statusObservers: ReadonlyArray<AgentExecutionStatusObserver>;
+  readonly logger: Logger;
+}
+
+/**
+ * Notifies the composed observers of one persisted phase transition.
+ * Call AFTER the store write commits and BEFORE any broadcast, with the
+ * persisted snapshot and the phase read from the pre-merge state.
+ */
+export async function notifyStatusObservers(
+  deps: StatusObserverDeps,
+  execution: AgentExecution,
+  oldPhase: ExecutionPhase,
+  newPhase: ExecutionPhase,
+): Promise<void> {
+  if (oldPhase === newPhase) {
+    return;
+  }
+  for (const observer of deps.statusObservers) {
+    try {
+      await observer({ execution, oldPhase, newPhase });
+    } catch (error) {
+      deps.logger.warn("status observer failed (extension bug, ignored)", {
+        executionId: execution.metadata?.id ?? "",
+        oldPhase,
+        newPhase,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+}
+
+/**
+ * Applies the composed response decorators to the UpdateStatus reply
+ * (blueprint 03 §7 — the querySignal seam: after the merge, before the
+ * reply). Each decorator works on a clone and commits only on success, so
+ * a throwing decorator degrades exactly ITS contribution to the defaults
+ * (the verified non-fatal posture) — never a partial write, never the
+ * RPC. Returns the decorated reply.
+ */
+export async function applyResponseDecorators(
+  decorators: ReadonlyArray<AgentExecutionResponseDecorator>,
+  logger: Logger,
+  execution: AgentExecution,
+  response: UpdateStatusResponse,
+): Promise<UpdateStatusResponse> {
+  let decorated = response;
+  for (const decorator of decorators) {
+    const candidate = clone(UpdateStatusResponseSchema, decorated);
+    try {
+      await decorator(execution, candidate);
+      decorated = candidate;
+    } catch (error) {
+      logger.warn("response decorator failed (extension bug, ignored)", {
+        executionId: execution.metadata?.id ?? "",
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+  return decorated;
+}

package/src/domain/agentexecution/steps.ts

@@ -0,0 +1,218 @@
+/**
+ * AgentExecution domain steps — the list-side chains from list.go and
+ * list_by_session.go, plus the full-scan load helper the usage reports
+ * share.
+ *
+ * List semantics ported verbatim: no sorting (unlike the session domain's
+ * newest-first list), no pagination (total_pages pinned to 1 — Go's
+ * placeholder), the request `org` field a deliberate no-op (single-tenant
+ * edition), and phase filtering only when a phase is specified.
+ */
+import { create, fromBinary } from "@bufbuild/protobuf";
+
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { AgentExecutionListSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { AgentExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/query_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+
+import type { Logger } from "../../boot/logger.js";
+import type { ListReadScope } from "../../extensions/list-read-scope.js";
+import { restrictListByReadScope } from "../../extensions/list-read-scope.js";
+import { internalError, invalidArgumentError } from "../../pipeline/errors.js";
+import type { PipelineStep } from "../../pipeline/pipeline.js";
+import type { Store } from "../../store/interface.js";
+
+/**
+ * Inter-step key for the working execution list AND the final
+ * AgentExecutionList — Go reuses one key ("execution_list") for both, and
+ * the controller reads the final response from it.
+ */
+export const EXECUTION_LIST_KEY = "execution_list";
+
+type ListDesc = typeof AgentExecutionQueryController.method.list.input;
+type ListBySessionDesc =
+  typeof AgentExecutionQueryController.method.listBySession.input;
+
+/**
+ * Full-scan agent-execution load shared by the list steps and the usage
+ * reports; malformed rows warn + skip (Go's proto.Unmarshal-continue).
+ */
+export async function loadAllAgentExecutions(
+  store: Store,
+  logger: Logger,
+): Promise<AgentExecution[]> {
+  let rows: Uint8Array[];
+  try {
+    rows = await store.listResources(ApiResourceKind.agent_execution);
+  } catch (error) {
+    throw internalError(error, "failed to list agent executions");
+  }
+
+  const executions: AgentExecution[] = [];
+  for (const data of rows) {
+    let execution: AgentExecution;
+    try {
+      execution = fromBinary(AgentExecutionSchema, data);
+    } catch (error) {
+      logger.warn("Failed to unmarshal execution, skipping", {
+        error: error instanceof Error ? error.message : String(error),
+      });
+      continue;
+    }
+    executions.push(execution);
+  }
+  return executions;
+}
+
+/** ValidateListRequest — list.go: no required fields today (a no-op). */
+export function newValidateListRequestStep(): PipelineStep<ListDesc> {
+  return {
+    name: "ValidateListRequest",
+    execute() {
+      // Go validates nothing here yet; pagination validation would land
+      // in both editions together.
+    },
+  };
+}
+
+/**
+ * QueryAllExecutions — list.go: full scan into the context. With a
+ * composed ListReadScope (20260830.01, census lane 4) the scan narrows
+ * to the caller's authorized executions ∩ the request's org (the Java
+ * AgentExecutionListHandler baseline: org set = one-org view, blank =
+ * permission-bounded across orgs; the guest cookie rule rides the
+ * driver); no scope = the full scan, org a no-op — byte-identical.
+ */
+export function newQueryAllExecutionsStep(
+  store: Store,
+  logger: Logger,
+  listReadScope: ListReadScope | undefined,
+): PipelineStep<ListDesc> {
+  return {
+    name: "QueryAllExecutions",
+    async execute(ctx) {
+      const executions = await restrictListByReadScope(
+        listReadScope,
+        ctx.callerIdentity,
+        ApiResourceKind.agent_execution,
+        await loadAllAgentExecutions(store, logger),
+        ctx.input.org,
+      );
+      logger.debug("Successfully queried executions", {
+        count: executions.length,
+      });
+      ctx.set(EXECUTION_LIST_KEY, executions);
+    },
+  };
+}
+
+/**
+ * ApplyPhaseFilter — list.go: status.phase equality filter, skipped when
+ * the request carries no phase.
+ */
+export function newApplyPhaseFilterStep(
+  logger: Logger,
+): PipelineStep<ListDesc> {
+  return {
+    name: "ApplyPhaseFilter",
+    execute(ctx) {
+      const executions = requireExecutions(ctx.get(EXECUTION_LIST_KEY));
+      if (ctx.input.phase === ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED) {
+        logger.debug("No phase filter specified, skipping");
+        return;
+      }
+      const filtered = executions.filter(
+        (execution) =>
+          (execution.status?.phase ??
+            ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED) === ctx.input.phase,
+      );
+      logger.debug("Phase filter applied", {
+        originalCount: executions.length,
+        filteredCount: filtered.length,
+      });
+      ctx.set(EXECUTION_LIST_KEY, filtered);
+    },
+  };
+}
+
+/**
+ * ValidateListBySessionRequest — list_by_session.go: session_id required.
+ */
+export function newValidateListBySessionRequestStep(): PipelineStep<ListBySessionDesc> {
+  return {
+    name: "ValidateListBySessionRequest",
+    execute(ctx) {
+      if (ctx.input.sessionId === "") {
+        throw invalidArgumentError("session_id is required");
+      }
+    },
+  };
+}
+
+/**
+ * QueryExecutionsBySession — list_by_session.go: full scan +
+ * spec.session_id equality filter.
+ */
+export function newQueryExecutionsBySessionStep(
+  store: Store,
+  logger: Logger,
+  listReadScope: ListReadScope | undefined,
+): PipelineStep<ListBySessionDesc> {
+  return {
+    name: "QueryExecutionsBySession",
+    async execute(ctx) {
+      // Census lane 5: authorized ids ∩ session filter; the Java handler
+      // never consults org on this lane (bounded by the session id).
+      const all = await restrictListByReadScope(
+        listReadScope,
+        ctx.callerIdentity,
+        ApiResourceKind.agent_execution,
+        await loadAllAgentExecutions(store, logger),
+        "",
+      );
+      const executions = all.filter(
+        (execution) =>
+          (execution.spec?.sessionId ?? "") === ctx.input.sessionId,
+      );
+      logger.debug("Successfully queried executions by session", {
+        sessionId: ctx.input.sessionId,
+        count: executions.length,
+      });
+      ctx.set(EXECUTION_LIST_KEY, executions);
+    },
+  };
+}
+
+/**
+ * BuildExecutionListResponse — both list files: wraps the working list
+ * into AgentExecutionList with the total_pages placeholder pinned to 1.
+ */
+export function newBuildExecutionListResponseStep<
+  Desc extends ListDesc | ListBySessionDesc,
+>(): PipelineStep<Desc> {
+  return {
+    name: "BuildExecutionListResponse",
+    execute(ctx) {
+      const executions = requireExecutions(ctx.get(EXECUTION_LIST_KEY));
+      ctx.set(
+        EXECUTION_LIST_KEY,
+        create(AgentExecutionListSchema, {
+          totalPages: 1,
+          entries: executions,
+        }),
+      );
+    },
+  };
+}
+
+function requireExecutions(value: unknown): AgentExecution[] {
+  if (!Array.isArray(value)) {
+    throw internalError(
+      new Error("execution list not found in context"),
+      "execution list not found in context",
+    );
+  }
+  return value as AgentExecution[];
+}

package/src/domain/agentexecution/stream-broker.ts

@@ -0,0 +1,126 @@
+/**
+ * StreamBroker — ports controller/stream_broker.go: the in-memory
+ * broadcast fabric for real-time execution updates (ADR 011's "Stream
+ * Broker" responsibility; the OSS stand-in for cloud's Redis streams).
+ *
+ * Go's shape is a map of executionID → buffered channels (capacity 100)
+ * under an RWMutex: Broadcast is non-blocking — a full buffer drops the
+ * frame for that subscriber (they catch up on the next one) — and
+ * Unsubscribe closes the channel. The TS port keeps the exact delivery
+ * semantics on the queue-plus-notify idiom the transport already proved
+ * for streams (transport/health.ts watch): each subscription owns a
+ * bounded FIFO queue the subscribe generator drains, and a notify hook
+ * wakes the drain loop. Node's single-threaded event loop replaces the
+ * mutex; the bounded queue replaces the channel buffer.
+ *
+ * ONE instance serves both routers (serving + in-process): #18's Temporal
+ * activities update status through the in-process client, and those
+ * broadcasts must reach externally-connected subscribers — the same
+ * reason Go exposes GetStreamBroker to its activities. The composition
+ * root owns the instance.
+ */
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+
+import type { Logger } from "../../boot/logger.js";
+
+/**
+ * Go's channel buffer size: bursts up to this many undelivered frames per
+ * subscriber are absorbed; beyond it, broadcasts drop for that subscriber
+ * (stream_broker.go's `make(chan ..., 100)` + non-blocking send).
+ */
+export const SUBSCRIBER_BUFFER_CAPACITY = 100;
+
+/**
+ * One subscriber's delivery state. The subscribe stream loop drains
+ * `queue` and parks on `notify`; the broker pushes and wakes. `closed`
+ * flips on unsubscribe (Go's close(ch)) so a parked or late consumer
+ * observes the end instead of waiting forever.
+ */
+export interface BrokerSubscription {
+  readonly queue: AgentExecution[];
+  notify: (() => void) | undefined;
+  closed: boolean;
+}
+
+export class StreamBroker {
+  private readonly subscribers = new Map<string, Set<BrokerSubscription>>();
+
+  constructor(private readonly logger: Logger) {}
+
+  /**
+   * Registers a new subscriber for the execution. The caller MUST
+   * unsubscribe when done (the subscribe generator's `finally`) — Go's
+   * "caller MUST call Unsubscribe" contract, enforced there by defer.
+   */
+  subscribe(executionId: string): BrokerSubscription {
+    const subscription: BrokerSubscription = {
+      queue: [],
+      notify: undefined,
+      closed: false,
+    };
+    const set = this.subscribers.get(executionId) ?? new Set();
+    set.add(subscription);
+    this.subscribers.set(executionId, set);
+    this.logger.debug("New subscriber registered", {
+      executionId,
+      totalSubscribers: set.size,
+    });
+    return subscription;
+  }
+
+  /** Removes and closes a subscription; idempotent (Go Unsubscribe). */
+  unsubscribe(executionId: string, subscription: BrokerSubscription): void {
+    const set = this.subscribers.get(executionId);
+    if (set === undefined || !set.has(subscription)) {
+      return;
+    }
+    set.delete(subscription);
+    subscription.closed = true;
+    subscription.notify?.();
+    subscription.notify = undefined;
+    this.logger.debug("Subscriber unregistered", {
+      executionId,
+      remainingSubscribers: set.size,
+    });
+    if (set.size === 0) {
+      this.subscribers.delete(executionId);
+    }
+  }
+
+  /**
+   * Delivers an execution update to every active subscriber of its id.
+   * Non-blocking by construction: a subscriber at buffer capacity drops
+   * THIS frame (it catches up on the next broadcast) — Go's select/default
+   * arm, warn included.
+   */
+  broadcast(execution: AgentExecution): void {
+    const executionId = execution.metadata?.id ?? "";
+    if (executionId === "") {
+      return;
+    }
+    const set = this.subscribers.get(executionId);
+    if (set === undefined || set.size === 0) {
+      return;
+    }
+    this.logger.debug("Broadcasting execution update", {
+      executionId,
+      subscribers: set.size,
+    });
+    for (const subscription of set) {
+      if (subscription.queue.length >= SUBSCRIBER_BUFFER_CAPACITY) {
+        this.logger.warn("Subscriber channel full, dropping update", {
+          executionId,
+        });
+        continue;
+      }
+      subscription.queue.push(execution);
+      subscription.notify?.();
+      subscription.notify = undefined;
+    }
+  }
+
+  /** Active subscriber count for an execution (Go GetSubscriberCount). */
+  getSubscriberCount(executionId: string): number {
+    return this.subscribers.get(executionId)?.size ?? 0;
+  }
+}