@stigmer/react 3.5.2 → 3.6.0

package/src/channel/__tests__/useChannelTemplateReadiness.test.tsx

@@ -0,0 +1,124 @@
+import { describe, it, expect } from "vitest";
+import { renderHook } from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { AgentChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
+import { AgentChannelInstallState } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/status_pb";
+import { DeploymentModeContext } from "../../deployment-mode";
+import { useChannelTemplateReadiness } from "../useChannelTemplateReadiness";
+
+function makeChannel(overrides?: {
+  installState?: AgentChannelInstallState;
+  enabled?: boolean;
+  proactiveMessagingEnabled?: boolean;
+}): AgentChannel {
+  return {
+    metadata: { id: "ach_1", org: "acme", slug: "wa-main" },
+    spec: {
+      enabled: overrides?.enabled ?? true,
+      proactiveMessagingEnabled: overrides?.proactiveMessagingEnabled ?? true,
+    },
+    status: {
+      installState:
+        overrides?.installState ?? AgentChannelInstallState.installed,
+    },
+  } as unknown as AgentChannel;
+}
+
+function wrapper(mode: "cloud" | "local" = "cloud") {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <DeploymentModeContext.Provider value={mode}>
+        {children}
+      </DeploymentModeContext.Provider>
+    );
+  };
+}
+
+function readinessOf(
+  channel: AgentChannel,
+  mode: "cloud" | "local" = "cloud",
+) {
+  const { result } = renderHook(() => useChannelTemplateReadiness(channel), {
+    wrapper: wrapper(mode),
+  });
+  return result.current;
+}
+
+describe("useChannelTemplateReadiness", () => {
+  it("is ready for an installed, enabled, proactive channel on cloud", () => {
+    expect(readinessOf(makeChannel())).toEqual({ status: "ready" });
+  });
+
+  it("is cloud-only on a local deployment — the template registry is cloud runtime", () => {
+    expect(readinessOf(makeChannel(), "local")).toEqual({
+      status: "cloud-only",
+    });
+  });
+
+  it("is not-installed for a pending install", () => {
+    expect(
+      readinessOf(
+        makeChannel({
+          installState: AgentChannelInstallState.pending_install,
+        }),
+      ),
+    ).toEqual({ status: "not-installed" });
+  });
+
+  it("is not-installed for a revoked install — coarse on purpose, describeChannel carries the distinction", () => {
+    expect(
+      readinessOf(
+        makeChannel({ installState: AgentChannelInstallState.revoked }),
+      ),
+    ).toEqual({ status: "not-installed" });
+  });
+
+  it("is channel-off when the serving switch is off", () => {
+    expect(readinessOf(makeChannel({ enabled: false }))).toEqual({
+      status: "channel-off",
+    });
+  });
+
+  it("is not-proactive when the grant is missing", () => {
+    expect(
+      readinessOf(makeChannel({ proactiveMessagingEnabled: false })),
+    ).toEqual({ status: "not-proactive" });
+  });
+
+  // The gate order is the server's (ChannelMessagingReach.resolveDirect:
+  // installed → enabled → proactive). A channel failing several gates
+  // must report the FIRST, so the teaching state names the next fix.
+  it("resolves gates in the server's order — first failure wins", () => {
+    expect(
+      readinessOf(
+        makeChannel({
+          installState: AgentChannelInstallState.pending_install,
+          enabled: false,
+          proactiveMessagingEnabled: false,
+        }),
+        "local",
+      ),
+    ).toEqual({ status: "cloud-only" });
+
+    expect(
+      readinessOf(
+        makeChannel({
+          installState: AgentChannelInstallState.pending_install,
+          enabled: false,
+          proactiveMessagingEnabled: false,
+        }),
+      ),
+    ).toEqual({ status: "not-installed" });
+
+    expect(
+      readinessOf(
+        makeChannel({ enabled: false, proactiveMessagingEnabled: false }),
+      ),
+    ).toEqual({ status: "channel-off" });
+  });
+
+  it("treats a channel with no status/spec as not yet installed", () => {
+    const bare = { metadata: { id: "ach_2" } } as unknown as AgentChannel;
+    expect(readinessOf(bare)).toEqual({ status: "not-installed" });
+  });
+});

package/src/channel/index.ts

@@ -17,6 +17,9 @@ export {
 } from "./providerPresentation.js";
 export type { ChannelProviderPresentation } from "./providerPresentation.js";
 
+export { templateStatusPhase, splitTemplateBody } from "./templatePresentation.js";
+export type { TemplateBodySegment } from "./templatePresentation.js";
+
 export { useAgentChannel } from "./useAgentChannel.js";
 export type { UseAgentChannelReturn } from "./useAgentChannel.js";
 
@@ -43,9 +46,18 @@ export type {
 
 export { useChannelToolReadiness } from "./useChannelToolReadiness.js";
 
+export { useChannelTemplateReadiness } from "./useChannelTemplateReadiness.js";
+export type { ChannelTemplateReadiness } from "./useChannelTemplateReadiness.js";
+
 export { useChannelSessions } from "./useChannelSessions.js";
 export type { UseChannelSessionsReturn } from "./useChannelSessions.js";
 
+export { useChannelTemplateList } from "./useChannelTemplateList.js";
+export type {
+  UseChannelTemplateListOptions,
+  UseChannelTemplateListReturn,
+} from "./useChannelTemplateList.js";
+
 export { AgentChannelsPanel } from "./AgentChannelsPanel.js";
 export type { AgentChannelsPanelProps } from "./AgentChannelsPanel.js";
 
@@ -63,3 +75,6 @@ export type { ChannelToolCredentialsProps } from "./ChannelToolCredentials.js";
 
 export { ChannelConversationsDialog } from "./ChannelConversationsDialog.js";
 export type { ChannelConversationsDialogProps } from "./ChannelConversationsDialog.js";
+
+export { ChannelTemplatesDialog } from "./ChannelTemplatesDialog.js";
+export type { ChannelTemplatesDialogProps } from "./ChannelTemplatesDialog.js";

package/src/channel/providers.ts

@@ -43,6 +43,18 @@ export interface ChannelProviderDescriptor {
   readonly Icon: ComponentType<{ readonly className?: string }>;
   /** How this provider's install flow runs. */
   readonly installStyle: ChannelInstallStyle;
+  /**
+   * Whether this provider has a message-template registry the console
+   * can list (`listTemplates`). Mirrors the server's proactive-sender
+   * registry, which is the de-facto provider filter behind that RPC —
+   * a provider with no registered sender answers `PROVIDER_UNSUPPORTED`.
+   *
+   * `false` for Slack is not a gap: Slack has no template concept at
+   * all, so consumers hide the Templates affordance entirely rather
+   * than disable it — a disabled item would falsely imply it may work
+   * there one day.
+   */
+  readonly supportsMessageTemplates: boolean;
 }
 
 /**
@@ -55,8 +67,20 @@ export interface ChannelProviderDescriptor {
  * demos. A third entry is the signal to fold these into a provider menu.
  */
 export const CHANNEL_PROVIDERS: readonly ChannelProviderDescriptor[] = [
-  { id: "slack", label: "Slack", Icon: SlackMarkIcon, installStyle: "redirect" },
-  { id: "whatsapp", label: "WhatsApp", Icon: WhatsAppMarkIcon, installStyle: "direct" },
+  {
+    id: "slack",
+    label: "Slack",
+    Icon: SlackMarkIcon,
+    installStyle: "redirect",
+    supportsMessageTemplates: false,
+  },
+  {
+    id: "whatsapp",
+    label: "WhatsApp",
+    Icon: WhatsAppMarkIcon,
+    installStyle: "direct",
+    supportsMessageTemplates: true,
+  },
 ];
 
 /**

package/src/channel/templatePresentation.ts

@@ -0,0 +1,82 @@
+import type { StatusPhase } from "../resource-workbench/types.js";
+
+/**
+ * Display helpers for provider message templates — the template
+ * counterpart of {@link ChannelProviderPresentation}'s module split:
+ * `ChannelTemplatesDialog` renders, this module decides how a
+ * provider-verbatim template projects onto the SDK's display
+ * vocabulary. Pure functions, one writer each.
+ */
+
+/**
+ * Map a provider-verbatim template status onto a {@link StatusPhase}
+ * for `StatusBadge` coloring.
+ *
+ * The wire carries the provider's own vocabulary, never a Stigmer enum
+ * (DD-003 D6) — so the caller renders the verbatim status string as the
+ * badge label and uses this phase only for the color. WhatsApp's
+ * observed set exceeds the documented five (IN_APPEAL, LIMIT_EXCEEDED,
+ * PENDING_DELETION, DELETED occur, and Meta can add more), so unknown
+ * statuses deliberately land on `draft` — a neutral tone that renders
+ * the provider's word without claiming to understand it.
+ */
+export function templateStatusPhase(status: string): StatusPhase {
+  switch (status) {
+    case "APPROVED":
+      return "ready";
+    case "PENDING":
+    case "IN_APPEAL":
+      return "pending";
+    case "PAUSED":
+    case "LIMIT_EXCEEDED":
+      return "degraded";
+    case "REJECTED":
+    case "DISABLED":
+      return "failed";
+    case "PENDING_DELETION":
+    case "DELETED":
+      return "disabled";
+    default:
+      return "draft";
+  }
+}
+
+/** One segment of a template body: literal text or a `{{...}}` placeholder. */
+export interface TemplateBodySegment {
+  readonly kind: "text" | "placeholder";
+  /** The verbatim slice, braces included for placeholders (`"{{1}}"`). */
+  readonly value: string;
+}
+
+/**
+ * The provider's placeholder shape: `{{1}}` (positional) or
+ * `{{customer_name}}` (named). Single braces and unbalanced braces are
+ * literal text — the provider would not have accepted them either.
+ */
+const PLACEHOLDER = /\{\{\s*[A-Za-z0-9_]+\s*\}\}/g;
+
+/**
+ * Split a template body into text and placeholder segments so the
+ * placeholders — the parts the agent fills at send time — can render
+ * visually distinct from the literal copy.
+ *
+ * The concatenation of all segment values is always the input,
+ * verbatim: this function classifies, it never rewrites.
+ */
+export function splitTemplateBody(
+  body: string,
+): readonly TemplateBodySegment[] {
+  const segments: TemplateBodySegment[] = [];
+  let lastIndex = 0;
+  for (const match of body.matchAll(PLACEHOLDER)) {
+    if (match.index > lastIndex) {
+      segments.push({ kind: "text", value: body.slice(lastIndex, match.index) });
+    }
+    segments.push({ kind: "placeholder", value: match[0] });
+    lastIndex = match.index + match[0].length;
+  }
+  if (lastIndex < body.length) {
+    segments.push({ kind: "text", value: body.slice(lastIndex) });
+  }
+  return segments;
+}

package/src/channel/useChannelTemplateList.ts

@@ -0,0 +1,123 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import type { ChannelTemplate } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
+import { ListChannelTemplatesInputSchema } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+
+/** Options for {@link useChannelTemplateList}. */
+export interface UseChannelTemplateListOptions {
+  /**
+   * When `true`, only templates the provider will accept for sending
+   * are returned (WhatsApp: status APPROVED). The console leaves it
+   * unset to render every status with its badge; agent-composition
+   * surfaces set it so a model never drafts against a paused or
+   * pending template.
+   */
+  readonly approvedOnly?: boolean;
+}
+
+/** Return value of {@link useChannelTemplateList}. */
+export interface UseChannelTemplateListReturn {
+  /**
+   * The channel provider's templates, verbatim, in provider order.
+   * Empty while loading, on error, and when the registry answered with
+   * no templates — `templates.length === 0 && !isLoading && !error`
+   * means the provider reported none, which callers should phrase as
+   * "none found" rather than "none exist" (an empty success is
+   * indistinguishable from a filtered or truncated one).
+   */
+  readonly templates: readonly ChannelTemplate[];
+  /** `true` while the initial fetch is in flight and no data is shown. */
+  readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Re-fetch the templates from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * How often to re-read the registry while any template is PENDING.
+ * Matches the server's template-cache TTL (60s) — polling faster only
+ * re-reads a cached answer.
+ */
+const PENDING_POLL_INTERVAL_MS = 60_000;
+
+/**
+ * Data hook that lists a channel's message templates as the channel's
+ * provider registry reports them (`listTemplates`) — every field
+ * provider-verbatim, including approval `status`, the provider's
+ * `rejectionReason`, and Stigmer's own `unsupportedReason` (why this
+ * platform version cannot send an otherwise-approved template).
+ *
+ * The channel is addressed by `slug` + `org` (not id), because that is
+ * the RPC's key — the provider registry is derived from the channel's
+ * phone number, not stored on any Stigmer resource. Pass an empty
+ * `channelSlug` or `org` to skip fetching (stable no-op).
+ *
+ * While any entry is PENDING the hook polls every 60 seconds — the
+ * server's registry-cache TTL, so a faster interval would only re-read
+ * a cached answer. There is deliberately no `refetchInterval` option:
+ * the pending-only conditional poll is the hook's policy, and
+ * `approvedOnly` (a wire field) is the only knob exposed.
+ *
+ * Results are never cached across mounts: a template's approval status
+ * can change on the provider's side at any time, and rendering a stale
+ * "APPROVED" is exactly what this surface must not do.
+ *
+ * @example
+ * ```tsx
+ * const { templates, isLoading, error } = useChannelTemplateList(
+ *   channel.metadata?.slug ?? "",
+ *   channel.metadata?.org ?? "",
+ * );
+ * ```
+ */
+export function useChannelTemplateList(
+  channelSlug: string,
+  org: string,
+  options?: UseChannelTemplateListOptions,
+): UseChannelTemplateListReturn {
+  const stigmer = useStigmer();
+  const approvedOnly = options?.approvedOnly ?? false;
+
+  // The pending-only poll rides useFetch's own guarded interval (the
+  // ONE polling implementation) rather than a second setInterval here.
+  // The interval cannot be derived inline — it depends on the data the
+  // same useFetch call returns — so it round-trips through state: data
+  // arrives, the effect below flips the interval, useFetch re-arms.
+  const [pollInterval, setPollInterval] = useState<number | false>(false);
+
+  const fetchFn =
+    channelSlug && org
+      ? async () => {
+          const result = await stigmer.agentChannel.listTemplates(
+            create(ListChannelTemplatesInputSchema, {
+              channel: channelSlug,
+              org,
+              approvedOnly,
+            }),
+          );
+          return result.entries;
+        }
+      : null;
+
+  const { data: templates, isLoading, isRefetching, error, refetch } =
+    useFetch(
+      fetchFn,
+      [channelSlug, org, approvedOnly, stigmer],
+      [] as ChannelTemplate[],
+      { refetchInterval: pollInterval },
+    );
+
+  const hasPending = templates.some((t) => t.status === "PENDING");
+  useEffect(() => {
+    setPollInterval(hasPending ? PENDING_POLL_INTERVAL_MS : false);
+  }, [hasPending]);
+
+  return { templates, isLoading, isRefetching, error, refetch };
+}

package/src/channel/useChannelTemplateReadiness.ts

@@ -0,0 +1,69 @@
+"use client";
+
+import type { AgentChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
+import { AgentChannelInstallState } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/status_pb";
+import { useDeploymentMode } from "../deployment-mode.js";
+
+/**
+ * Whether a channel can answer a template-registry read
+ * (`listTemplates`), and if not, which precondition fails first.
+ *
+ * - `cloud-only` — the deployment is not cloud; the template registry
+ *   is part of the cloud channel runtime.
+ * - `not-installed` — the provider install has not completed (covers
+ *   both pending and revoked; render the per-provider
+ *   `describeChannel` sentence, which already distinguishes them).
+ * - `channel-off` — the owner's serving switch (`spec.enabled`) is off.
+ * - `not-proactive` — `spec.proactive_messaging_enabled` is not set;
+ *   business-initiated messaging (and with it the template surface)
+ *   is not granted on this channel.
+ * - `ready` — the read can be made.
+ */
+export type ChannelTemplateReadiness =
+  | { readonly status: "cloud-only" }
+  | { readonly status: "not-installed" }
+  | { readonly status: "channel-off" }
+  | { readonly status: "not-proactive" }
+  | { readonly status: "ready" };
+
+/**
+ * Resolve whether a channel's template registry can be read, without a
+ * network call — the courtesy pre-check for the Templates surface.
+ *
+ * Mirrors the server's own gate order for `listTemplates`
+ * (`ChannelMessagingReach.resolveDirect`: installed → enabled →
+ * proactive grant), answering from fields already on the fetched
+ * {@link AgentChannel}. The server stays authoritative: a `ready`
+ * verdict here only means the call is worth making, and whatever the
+ * server then says wins.
+ *
+ * Two shape choices are deliberate. `channel-off` and `not-proactive`
+ * are split although the server collapses them into one refusal —
+ * their fixes differ (flip the card's serving switch vs. grant
+ * `proactive_messaging_enabled`). And `not-installed` stays coarse
+ * across pending/revoked, because `providerPresentation`'s
+ * `describeChannel` already renders the right sentence for each.
+ *
+ * @example
+ * ```tsx
+ * const readiness = useChannelTemplateReadiness(channel);
+ * if (readiness.status !== "ready") return <TeachingState ... />;
+ * ```
+ */
+export function useChannelTemplateReadiness(
+  channel: AgentChannel,
+): ChannelTemplateReadiness {
+  const deploymentMode = useDeploymentMode();
+
+  if (deploymentMode !== "cloud") return { status: "cloud-only" };
+  if (
+    channel.status?.installState !== AgentChannelInstallState.installed
+  ) {
+    return { status: "not-installed" };
+  }
+  if (!channel.spec?.enabled) return { status: "channel-off" };
+  if (!channel.spec.proactiveMessagingEnabled) {
+    return { status: "not-proactive" };
+  }
+  return { status: "ready" };
+}

package/src/dashboard/__tests__/useDashboardFailedRuns.test.tsx

@@ -0,0 +1,106 @@
+import { describe, it, expect, vi } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { ExecutionPhase as AgentPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ExecutionPhase as WorkflowPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import { StigmerContext } from "../../context";
+import { FetchCacheContext } from "../../internal/FetchCacheProvider";
+import { useDashboardFailedRuns } from "../useDashboardFailedRuns";
+
+function createMockStigmer(overrides: {
+  agentList?: (...args: unknown[]) => Promise<unknown>;
+  workflowList?: (...args: unknown[]) => Promise<unknown>;
+} = {}) {
+  return {
+    agentExecution: {
+      list: overrides.agentList ?? vi.fn().mockResolvedValue({ entries: [] }),
+    },
+    workflowExecution: {
+      list: overrides.workflowList ?? vi.fn().mockResolvedValue({ entries: [] }),
+    },
+  } as never;
+}
+
+function wrapper(client: unknown) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <FetchCacheContext.Provider value={null}>
+        <StigmerContext.Provider value={client as never}>
+          {children}
+        </StigmerContext.Provider>
+      </FetchCacheContext.Provider>
+    );
+  };
+}
+
+describe("useDashboardFailedRuns", () => {
+  it("scopes both list requests to the active org and the FAILED phase", async () => {
+    const agentList = vi.fn().mockResolvedValue({ entries: [] });
+    const workflowList = vi.fn().mockResolvedValue({ entries: [] });
+    const client = createMockStigmer({ agentList, workflowList });
+
+    const { result } = renderHook(() => useDashboardFailedRuns("acme"), {
+      wrapper: wrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    // Regression guard: the pre-fix hook used org only as a fetch gate and
+    // sent no org on the wire, so a brand-new org's dashboard showed other
+    // orgs' failures.
+    const agentRequest = agentList.mock.calls[0][0];
+    expect(agentRequest.org).toBe("acme");
+    expect(agentRequest.phase).toBe(AgentPhase.EXECUTION_FAILED);
+
+    const workflowRequest = workflowList.mock.calls[0][0];
+    expect(workflowRequest.org).toBe("acme");
+    expect(workflowRequest.phase).toBe(WorkflowPhase.EXECUTION_FAILED);
+  });
+
+  it("does not fetch until an org is available", async () => {
+    const agentList = vi.fn().mockResolvedValue({ entries: [] });
+    const workflowList = vi.fn().mockResolvedValue({ entries: [] });
+    const client = createMockStigmer({ agentList, workflowList });
+
+    renderHook(() => useDashboardFailedRuns(null), {
+      wrapper: wrapper(client),
+    });
+
+    // Give any wrongly-armed fetch a tick to fire.
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(agentList).not.toHaveBeenCalled();
+    expect(workflowList).not.toHaveBeenCalled();
+  });
+
+  it("interleaves agent and workflow failures newest-first, capped at 5", async () => {
+    const ts = (secs: number) => ({ seconds: BigInt(secs), nanos: 0 });
+    const agentEntries = [1, 3, 5].map((n) => ({
+      metadata: { id: `aex_${n}`, name: `agent ${n}` },
+      spec: { agentId: `agt_${n}` },
+      status: { error: "boom", audit: { specAudit: { createdAt: ts(n) } } },
+    }));
+    const workflowEntries = [2, 4, 6].map((n) => ({
+      metadata: { id: `wex_${n}`, name: `workflow ${n}`, slug: `wf-${n}` },
+      status: { error: "boom", audit: { specAudit: { createdAt: ts(n) } } },
+    }));
+    const client = createMockStigmer({
+      agentList: vi.fn().mockResolvedValue({ entries: agentEntries }),
+      workflowList: vi.fn().mockResolvedValue({ entries: workflowEntries }),
+    });
+
+    const { result } = renderHook(() => useDashboardFailedRuns("acme"), {
+      wrapper: wrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.failedRuns).toHaveLength(5));
+
+    expect(result.current.failedRuns.map((run) => run.id)).toEqual([
+      "wex_6",
+      "aex_5",
+      "wex_4",
+      "aex_3",
+      "wex_2",
+    ]);
+  });
+});

package/src/dashboard/useDashboardFailedRuns.ts

@@ -48,6 +48,7 @@ export function useDashboardFailedRuns(
               create(ListAgentExecutionsRequestSchema, {
                 pageSize: PAGE_SIZE,
                 phase: AgentPhase.EXECUTION_FAILED,
+                org: orgVal,
               }),
             );
             return [...resp.entries] as readonly AgentExecution[];
@@ -64,6 +65,7 @@ export function useDashboardFailedRuns(
               create(ListWorkflowExecutionsRequestSchema, {
                 pageSize: PAGE_SIZE,
                 phase: WorkflowPhase.EXECUTION_FAILED,
+                org: orgVal,
               }),
             );
             return [...resp.entries] as readonly WorkflowExecution[];

package/src/execution/__tests__/PlanArtifactCard.test.tsx

@@ -1,5 +1,11 @@
-import { describe, it, expect, vi, afterEach } from "vitest";
-import { render, screen, fireEvent, cleanup } from "@testing-library/react";
+import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
+import {
+  render,
+  screen,
+  fireEvent,
+  cleanup,
+  waitFor,
+} from "@testing-library/react";
 import type { ReactNode } from "react";
 import { create } from "@bufbuild/protobuf";
 import type { Stigmer } from "@stigmer/sdk";
@@ -47,6 +53,17 @@ function renderCard(ui: ReactNode) {
 
 afterEach(cleanup);
 
+// The download flow ends in a transient-anchor click with target="_blank".
+// Left unstubbed, happy-dom treats that click as a real popup navigation and
+// fetches the fixture URL over the actual network — after this test has
+// already returned, so the DNS failure gets attributed to whichever test the
+// worker is running by then (the flake in issue #334).
+beforeEach(() => {
+  vi.spyOn(HTMLAnchorElement.prototype, "click")
+    .mockImplementation(() => {})
+    .mockClear();
+});
+
 describe("PlanArtifactCard — compact document card", () => {
   it("is an accessible region with the plan's title, filename, and size", () => {
     renderCard(
@@ -178,6 +195,7 @@ describe("PlanArtifactCard — compact document card", () => {
 
   it("downloads the artifact on demand via a freshly minted URL", async () => {
     const { stigmer, getArtifactDownloadUrl } = createStigmerMock();
+    const anchorClick = vi.spyOn(HTMLAnchorElement.prototype, "click");
     render(
       withStigmer(
         <PlanArtifactCard executionId="aex_1" artifact={planArtifact} org="acme" />,
@@ -191,6 +209,9 @@ describe("PlanArtifactCard — compact document card", () => {
     const req = getArtifactDownloadUrl.mock.calls[0][0];
     expect(req.executionId).toBe("aex_1");
     expect(req.storageKey).toBe("artifacts/aex_1/plan.md");
+    // Wait for the mint-URL → anchor-click continuation INSIDE the test body;
+    // returning while it is still in flight is what let it escape.
+    await waitFor(() => expect(anchorClick).toHaveBeenCalledTimes(1));
   });
 });