@stigmer/react 3.1.17 → 3.2.0

package/src/execution/__tests__/artifact-row-item.test.ts

@@ -0,0 +1,128 @@
+import { describe, it, expect } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { ExecutionArtifactSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
+import { ExecutionArtifactKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ArtifactSchema } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/api_pb";
+import {
+  fromExecutionArtifact,
+  fromArtifact,
+  parentDirectory,
+} from "../artifact-row-item";
+
+// ---------------------------------------------------------------------------
+// fromExecutionArtifact — the session model adapter
+// ---------------------------------------------------------------------------
+
+describe("fromExecutionArtifact", () => {
+  it("maps name, size, and sandbox-path tooltip", () => {
+    const artifact = create(ExecutionArtifactSchema, {
+      name: "notes.md",
+      kind: ExecutionArtifactKind.FILE,
+      sizeBytes: 2048n,
+      sandboxPath: "/workspace/docs/notes.md",
+    });
+    const item = fromExecutionArtifact(artifact);
+    expect(item.name).toBe("notes.md");
+    expect(item.tooltip).toBe("/workspace/docs/notes.md");
+    expect(item.sizeBytes).toBe(2048n);
+    expect(item.isDirectory).toBe(false);
+    expect(item.subtitlePath).toBeNull();
+  });
+
+  it("falls back to the name as tooltip when there is no sandbox path", () => {
+    const artifact = create(ExecutionArtifactSchema, { name: "out.txt" });
+    expect(fromExecutionArtifact(artifact).tooltip).toBe("out.txt");
+  });
+
+  it("marks DIRECTORY artifacts as directories", () => {
+    const artifact = create(ExecutionArtifactSchema, {
+      name: "skill-pack",
+      kind: ExecutionArtifactKind.DIRECTORY,
+    });
+    expect(fromExecutionArtifact(artifact).isDirectory).toBe(true);
+  });
+
+  it("carries the parent directory as subtitle only on a name collision", () => {
+    const artifact = create(ExecutionArtifactSchema, {
+      name: "agent.yaml",
+      sandboxPath: "/workspace/configs/agent.yaml",
+    });
+    expect(fromExecutionArtifact(artifact, true).subtitlePath).toBe("configs/");
+    expect(fromExecutionArtifact(artifact, false).subtitlePath).toBeNull();
+  });
+
+  it("omits the subtitle on collision when there is no sandbox path to derive from", () => {
+    const artifact = create(ExecutionArtifactSchema, { name: "agent.yaml" });
+    expect(fromExecutionArtifact(artifact, true).subtitlePath).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// fromArtifact — the workflow Artifact-resource adapter
+// ---------------------------------------------------------------------------
+
+describe("fromArtifact", () => {
+  it("maps displayName, status size, and is never a directory", () => {
+    const artifact = create(ArtifactSchema, {
+      metadata: { id: "art_1", name: "fallback" },
+      spec: { displayName: "report.json", contentType: "application/json" },
+      status: { sizeBytes: 4096n },
+    });
+    const item = fromArtifact(artifact);
+    expect(item.name).toBe("report.json");
+    expect(item.tooltip).toBe("report.json");
+    expect(item.sizeBytes).toBe(4096n);
+    // The Artifact resource model has no directory concept.
+    expect(item.isDirectory).toBe(false);
+  });
+
+  it("falls back to metadata name, then 'Unnamed'", () => {
+    const withMeta = create(ArtifactSchema, {
+      metadata: { id: "art_2", name: "meta-name" },
+    });
+    expect(fromArtifact(withMeta).name).toBe("meta-name");
+    expect(fromArtifact(create(ArtifactSchema, {})).name).toBe("Unnamed");
+  });
+
+  it("defaults size to zero when status is absent", () => {
+    const artifact = create(ArtifactSchema, {
+      spec: { displayName: "x.txt" },
+    });
+    expect(fromArtifact(artifact).sizeBytes).toBe(0n);
+  });
+
+  it("carries the producing task as subtitle only on a name collision", () => {
+    const artifact = create(ArtifactSchema, {
+      spec: {
+        displayName: "output.json",
+        source: { workflowExecutionId: "wex_1", taskName: "analyze_code" },
+      },
+    });
+    expect(fromArtifact(artifact, true).subtitlePath).toBe("analyze_code");
+    expect(fromArtifact(artifact, false).subtitlePath).toBeNull();
+  });
+
+  it("omits the subtitle on collision when the artifact has no source task", () => {
+    const artifact = create(ArtifactSchema, {
+      spec: { displayName: "output.json" },
+    });
+    expect(fromArtifact(artifact, true).subtitlePath).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// parentDirectory
+// ---------------------------------------------------------------------------
+
+describe("parentDirectory", () => {
+  it("returns the immediate parent segment with a trailing slash", () => {
+    expect(parentDirectory("/workspace/configs/agent.yaml")).toBe("configs/");
+    expect(parentDirectory("a/b/c.txt")).toBe("b/");
+  });
+
+  it("returns null for paths without a meaningful parent", () => {
+    expect(parentDirectory("agent.yaml")).toBeNull();
+    expect(parentDirectory("/agent.yaml")).toBeNull();
+    expect(parentDirectory("")).toBeNull();
+  });
+});

package/src/execution/__tests__/deriveExecutionFileChanges.test.ts

@@ -0,0 +1,270 @@
+import { describe, it, expect } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import {
+  AgentExecutionSchema,
+  AgentExecutionStatusSchema,
+  type AgentExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import {
+  FileChangeSchema,
+  FileContentSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  CapturedFileChangeSchema,
+  FileChangeSetSchema,
+  FileReviewBaselineCapturedSchema,
+  FileReviewCandidateCapturedSchema,
+  FileReviewEventSchema,
+  FileReviewEventStreamSchema,
+  type CapturedFileChange,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/filereview_pb";
+import {
+  ExecutionPhase,
+  FileChangeCaptureLevel,
+  FileChangeKind,
+  FileChangeSetStatus,
+  FileChangeType,
+  FileReviewEventType,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  deriveExecutionFileChanges,
+  toFileDiffEntry,
+} from "../deriveExecutionFileChanges";
+
+// ---------------------------------------------------------------------------
+// Fixtures — CapturedFileChange only (apply-then-review ledger; see the
+// sibling useSessionFileChanges suite, which covers the session-wrapper
+// behavior over the same core).
+// ---------------------------------------------------------------------------
+
+function inlineSide(value: string) {
+  return create(FileContentSchema, { body: { case: "inline", value } });
+}
+
+function captured(opts: {
+  id: string;
+  pathBefore?: string;
+  pathAfter?: string;
+  before?: string;
+  after?: string;
+  kind?: FileChangeKind;
+}): CapturedFileChange {
+  const pathBefore = opts.pathBefore ?? opts.pathAfter ?? "";
+  const pathAfter = opts.pathAfter ?? opts.pathBefore ?? "";
+  return create(CapturedFileChangeSchema, {
+    id: opts.id,
+    pathBefore,
+    pathAfter,
+    kind: opts.kind ?? FileChangeKind.MODIFY,
+    before: opts.before !== undefined ? inlineSide(opts.before) : undefined,
+    after: opts.after !== undefined ? inlineSide(opts.after) : undefined,
+    diffComplete: true,
+  });
+}
+
+function execWith(id: string): AgentExecution {
+  const exec = create(AgentExecutionSchema);
+  exec.metadata = create(ApiResourceMetadataSchema, { id });
+  exec.status = create(AgentExecutionStatusSchema);
+  return exec;
+}
+
+/** An execution carrying a live server projection of one change set. */
+function execWithProjection(
+  id: string,
+  changes: CapturedFileChange[],
+): AgentExecution {
+  const exec = execWith(id);
+  exec.status!.fileChangeSets = [
+    create(FileChangeSetSchema, {
+      id: `${id}:0`,
+      status: FileChangeSetStatus.AWAITING_REVIEW,
+      changes,
+    }),
+  ];
+  return exec;
+}
+
+/** A terminal execution: empty projection, changes only in the durable ledger. */
+function execWithLedger(
+  id: string,
+  changes: CapturedFileChange[],
+): AgentExecution {
+  const exec = execWith(id);
+  exec.status!.phase = ExecutionPhase.EXECUTION_COMPLETED;
+  exec.status!.fileChangeSets = [];
+  const changeSetId = `${id}:0`;
+  exec.status!.fileReviewEventStream = create(FileReviewEventStreamSchema, {
+    executionId: id,
+    events: [
+      create(FileReviewEventSchema, {
+        changeSetId,
+        eventType: FileReviewEventType.BASELINE_CAPTURED,
+        payload: {
+          case: "baselineCaptured",
+          value: create(FileReviewBaselineCapturedSchema, { changeSetId }),
+        },
+      }),
+      create(FileReviewEventSchema, {
+        changeSetId,
+        eventType: FileReviewEventType.CANDIDATE_CAPTURED,
+        payload: {
+          case: "candidateCaptured",
+          value: create(FileReviewCandidateCapturedSchema, {
+            changeSetId,
+            changes,
+          }),
+        },
+      }),
+    ],
+  });
+  return exec;
+}
+
+function inlineText(side: { body: { case?: string; value?: unknown } } | undefined) {
+  return side?.body.case === "inline" ? side.body.value : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// deriveExecutionFileChanges — the cross-EXECUTION semantics. Same-execution
+// net-collapse cases (create-then-delete, rename, sorting, …) are covered by
+// the useSessionFileChanges suite, which delegates to this core.
+// ---------------------------------------------------------------------------
+
+describe("deriveExecutionFileChanges", () => {
+  it("returns empty for no executions", () => {
+    expect(deriveExecutionFileChanges([])).toEqual([]);
+  });
+
+  it("net-diffs the same path ACROSS executions: first execution's before -> last execution's after", () => {
+    // The workflow case: two agent-call children touching one file.
+    const r = deriveExecutionFileChanges([
+      execWithLedger("aex_1", [
+        captured({ id: "fc1", pathAfter: "src/shared.ts", before: "v0", after: "v1" }),
+      ]),
+      execWithLedger("aex_2", [
+        captured({ id: "fc2", pathAfter: "src/shared.ts", before: "v1", after: "v2" }),
+      ]),
+    ]);
+    expect(r).toHaveLength(1);
+    expect(inlineText(r[0].before)).toBe("v0");
+    expect(inlineText(r[0].after)).toBe("v2");
+    expect(r[0].changeType).toBe(FileChangeType.MODIFY);
+  });
+
+  it("anchors the net diff on INPUT order — reversed executions produce the reversed anchors (chronology is a correctness input)", () => {
+    const first = execWithLedger("aex_1", [
+      captured({ id: "fc1", pathAfter: "src/shared.ts", before: "v0", after: "v1" }),
+    ]);
+    const second = execWithLedger("aex_2", [
+      captured({ id: "fc2", pathAfter: "src/shared.ts", before: "v1", after: "v2" }),
+    ]);
+
+    const reversed = deriveExecutionFileChanges([second, first]);
+    expect(inlineText(reversed[0].before)).toBe("v1");
+    expect(inlineText(reversed[0].after)).toBe("v1");
+  });
+
+  it("reconciles create (execution 1) then delete (execution 2) to DELETE across the span", () => {
+    const r = deriveExecutionFileChanges([
+      execWithLedger("aex_1", [
+        captured({ id: "fc1", pathAfter: "src/tmp.ts", after: "scratch", kind: FileChangeKind.ADD }),
+      ]),
+      execWithLedger("aex_2", [
+        captured({ id: "fc2", pathBefore: "src/tmp.ts", pathAfter: "src/tmp.ts", before: "scratch", kind: FileChangeKind.DELETE }),
+      ]),
+    ]);
+    expect(r).toHaveLength(1);
+    expect(r[0].changeType).toBe(FileChangeType.DELETE);
+  });
+
+  it("mixes projection (live child) and ledger (terminal child) sources in one rollup", () => {
+    const r = deriveExecutionFileChanges([
+      execWithLedger("aex_done", [
+        captured({ id: "fc1", pathAfter: "src/a.ts", before: "a", after: "b" }),
+      ]),
+      execWithProjection("aex_live", [
+        captured({ id: "fc2", pathAfter: "src/b.ts", before: "x", after: "y" }),
+      ]),
+    ]);
+    expect(r.map((c) => c.path)).toEqual(["src/a.ts", "src/b.ts"]);
+  });
+
+  it("keeps distinct paths from distinct executions distinct", () => {
+    const r = deriveExecutionFileChanges([
+      execWithLedger("aex_1", [
+        captured({ id: "fc1", pathAfter: "src/one.ts", before: "a", after: "b" }),
+      ]),
+      execWithLedger("aex_2", [
+        captured({ id: "fc2", pathAfter: "src/two.ts", before: "c", after: "d" }),
+      ]),
+    ]);
+    expect(r).toHaveLength(2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// toFileDiffEntry — the FileChange → FileDiffEntry projection
+// ---------------------------------------------------------------------------
+
+describe("toFileDiffEntry", () => {
+  it("maps change types to the file-list vocabulary", () => {
+    const of = (changeType: FileChangeType) =>
+      toFileDiffEntry(create(FileChangeSchema, { path: "p", changeType }));
+    expect(of(FileChangeType.CREATE).changeType).toBe("added");
+    expect(of(FileChangeType.DELETE).changeType).toBe("removed");
+    expect(of(FileChangeType.MODIFY).changeType).toBe("modified");
+    expect(of(FileChangeType.RENAME).changeType).toBe("modified");
+  });
+
+  it("uses the runner's authoritative counts for hunk-only captures", () => {
+    const entry = toFileDiffEntry(
+      create(FileChangeSchema, {
+        path: "src/a.ts",
+        changeType: FileChangeType.MODIFY,
+        captureLevel: FileChangeCaptureLevel.HUNK_ONLY,
+        unifiedDiff: "@@ -1 +1 @@\n-a\n+b",
+        linesAdded: 3,
+        linesRemoved: 2,
+      }),
+    );
+    expect(entry.additions).toBe(3);
+    expect(entry.deletions).toBe(2);
+  });
+
+  it("derives counts from inline whole-file content", () => {
+    const entry = toFileDiffEntry(
+      create(FileChangeSchema, {
+        path: "src/a.ts",
+        changeType: FileChangeType.MODIFY,
+        captureLevel: FileChangeCaptureLevel.WHOLE_FILE,
+        before: inlineSide("line1\nline2\n"),
+        after: inlineSide("line1\nline2 changed\nline3\n"),
+      }),
+    );
+    expect(entry.additions).toBe(2);
+    expect(entry.deletions).toBe(1);
+  });
+
+  it("falls back to capture-time counts when a whole-file side is offloaded", () => {
+    const entry = toFileDiffEntry(
+      create(FileChangeSchema, {
+        path: "src/big.ts",
+        changeType: FileChangeType.MODIFY,
+        captureLevel: FileChangeCaptureLevel.WHOLE_FILE,
+        before: create(FileContentSchema, {
+          body: {
+            case: "ref",
+            value: { storageKey: "artifacts/aex_1/before", contentHash: "h1" },
+          },
+        }),
+        after: inlineSide("new"),
+        linesAdded: 10,
+        linesRemoved: 4,
+      }),
+    );
+    expect(entry.additions).toBe(10);
+    expect(entry.deletions).toBe(4);
+  });
+});

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

@@ -0,0 +1,85 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { Stigmer } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { useArtifactContentById } from "../useArtifactContentById";
+
+function wrapperFor(stigmer: Stigmer) {
+  return ({ children }: { children: ReactNode }) => (
+    <StigmerContext.Provider value={stigmer}>{children}</StigmerContext.Provider>
+  );
+}
+
+function makeStigmer(getContent = vi.fn()) {
+  return { artifact: { getContent } } as unknown as Stigmer;
+}
+
+function contentResponse(text: string, overrides: Record<string, unknown> = {}) {
+  return {
+    content: new TextEncoder().encode(text),
+    contentType: "application/json",
+    totalSizeBytes: BigInt(text.length),
+    truncated: false,
+    ...overrides,
+  };
+}
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("useArtifactContentById", () => {
+  it("fetches by artifact id and decodes the content as UTF-8", async () => {
+    const getContent = vi.fn().mockResolvedValue(contentResponse('{"a":1}'));
+    const { result } = renderHook(() => useArtifactContentById("art_1"), {
+      wrapper: wrapperFor(makeStigmer(getContent)),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(getContent).toHaveBeenCalledTimes(1);
+    expect(getContent.mock.calls[0][0]).toMatchObject({ artifactId: "art_1" });
+    expect(result.current.content).toBe('{"a":1}');
+    expect(result.current.contentType).toBe("application/json");
+    expect(result.current.error).toBeNull();
+  });
+
+  it("surfaces the server's truncation contract", async () => {
+    const getContent = vi.fn().mockResolvedValue(
+      contentResponse("partial", {
+        truncated: true,
+        totalSizeBytes: BigInt(2_000_000),
+      }),
+    );
+    const { result } = renderHook(() => useArtifactContentById("art_1"), {
+      wrapper: wrapperFor(makeStigmer(getContent)),
+    });
+
+    await waitFor(() => expect(result.current.isTruncated).toBe(true));
+    expect(result.current.totalSizeBytes).toBe(BigInt(2_000_000));
+    expect(result.current.content).toBe("partial");
+  });
+
+  it("returns the error state when the fetch fails", async () => {
+    const getContent = vi.fn().mockRejectedValue(new Error("blob deleted"));
+    const { result } = renderHook(() => useArtifactContentById("art_1"), {
+      wrapper: wrapperFor(makeStigmer(getContent)),
+    });
+
+    await waitFor(() => expect(result.current.error).not.toBeNull());
+    expect(result.current.error?.message).toBe("blob deleted");
+    expect(result.current.content).toBeNull();
+  });
+
+  it("skips fetching entirely when artifactId is null", async () => {
+    const getContent = vi.fn();
+    const { result } = renderHook(() => useArtifactContentById(null), {
+      wrapper: wrapperFor(makeStigmer(getContent)),
+    });
+
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.content).toBeNull();
+    expect(getContent).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,202 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import { create } from "@bufbuild/protobuf";
+
+vi.mock("../../hooks", () => ({
+  useStigmer: vi.fn(),
+}));
+vi.mock("../useExecutionStream", () => ({
+  useExecutionStream: vi.fn(),
+}));
+
+import {
+  AgentExecutionSchema,
+  AgentExecutionStatusSchema,
+  type AgentExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { StigmerError } from "@stigmer/sdk";
+import { useStigmer } from "../../hooks";
+import { useExecutionStream } from "../useExecutionStream";
+import { useLiveAgentExecution } from "../useLiveAgentExecution";
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+function executionFixture(id: string, phase: ExecutionPhase): AgentExecution {
+  const exec = create(AgentExecutionSchema);
+  exec.metadata = create(ApiResourceMetadataSchema, { id });
+  exec.status = create(AgentExecutionStatusSchema, { phase });
+  return exec;
+}
+
+/** The stream hook's healthy-idle shape (not subscribed / nothing yet). */
+function idleStream() {
+  return {
+    execution: null,
+    phase: ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED,
+    isStreaming: false,
+    isConnecting: false,
+    isReconnecting: false,
+    reconnectAttempt: 0,
+    error: null,
+    connectTimedOut: false,
+    isSlow: false,
+    reconnect: vi.fn(),
+  };
+}
+
+const mockUseStigmer = vi.mocked(useStigmer);
+const mockUseExecutionStream = vi.mocked(useExecutionStream);
+
+function mockGet(impl: (id: string) => Promise<AgentExecution>) {
+  mockUseStigmer.mockReturnValue({
+    agentExecution: { get: vi.fn(impl) },
+  } as unknown as ReturnType<typeof useStigmer>);
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mockUseExecutionStream.mockReturnValue(idleStream());
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("useLiveAgentExecution", () => {
+  it("serves a terminal execution from get() alone and never subscribes", async () => {
+    const terminal = executionFixture("aex_1", ExecutionPhase.EXECUTION_COMPLETED);
+    mockGet(async () => terminal);
+
+    const { result } = renderHook(() => useLiveAgentExecution("aex_1"));
+
+    expect(result.current.isLoading).toBe(true);
+    await waitFor(() => expect(result.current.execution).toBe(terminal));
+
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.phase).toBe(ExecutionPhase.EXECUTION_COMPLETED);
+    expect(result.current.isStreaming).toBe(false);
+    // The stream gate must stay closed for a terminal phase — every call
+    // (pre-fetch and post-fetch renders alike) passes null.
+    for (const call of mockUseExecutionStream.mock.calls) {
+      expect(call[0]).toBeNull();
+    }
+  });
+
+  it("layers the stream once the fetched phase is non-terminal", async () => {
+    const running = executionFixture("aex_2", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    mockGet(async () => running);
+
+    const { result } = renderHook(() => useLiveAgentExecution("aex_2"));
+    await waitFor(() => expect(result.current.execution).not.toBeNull());
+
+    const lastCall =
+      mockUseExecutionStream.mock.calls[mockUseExecutionStream.mock.calls.length - 1];
+    expect(lastCall[0]).toBe("aex_2");
+  });
+
+  it("prefers the streamed snapshot over the fetched one once streaming", async () => {
+    const fetched = executionFixture("aex_3", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    const streamed = executionFixture("aex_3", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    mockGet(async () => fetched);
+    mockUseExecutionStream.mockReturnValue({
+      ...idleStream(),
+      execution: streamed,
+      isStreaming: true,
+    });
+
+    const { result } = renderHook(() => useLiveAgentExecution("aex_3"));
+    await waitFor(() => expect(result.current.execution).toBe(streamed));
+    expect(result.current.isStreaming).toBe(true);
+  });
+
+  it("treats not-found as execution: null with no error", async () => {
+    mockGet(async () => {
+      // The SDK client wraps every failure in StigmerError; not-found is the
+      // code isNotFound() checks (a raw ConnectError would not match).
+      throw new StigmerError("not-found", "execution not found", 5);
+    });
+
+    const { result } = renderHook(() => useLiveAgentExecution("aex_missing"));
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.execution).toBeNull();
+    expect(result.current.error).toBeNull();
+    // A not-found fetch must not open a stream (fetched === null).
+    for (const call of mockUseExecutionStream.mock.calls) {
+      expect(call[0]).toBeNull();
+    }
+  });
+
+  it("surfaces a non-not-found fetch error", async () => {
+    mockGet(async () => {
+      throw new StigmerError("internal", "boom", 13);
+    });
+
+    const { result } = renderHook(() => useLiveAgentExecution("aex_err"));
+    await waitFor(() => expect(result.current.error).not.toBeNull());
+    expect(result.current.error?.message).toContain("boom");
+    expect(result.current.execution).toBeNull();
+  });
+
+  it("surfaces the stream's terminal error when the fetch is healthy", async () => {
+    const running = executionFixture("aex_4", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    const streamError = new Error("stream exhausted retries");
+    mockGet(async () => running);
+    mockUseExecutionStream.mockReturnValue({
+      ...idleStream(),
+      error: streamError,
+    });
+
+    const { result } = renderHook(() => useLiveAgentExecution("aex_4"));
+    // The stream error surfaces synchronously, but the fetched snapshot
+    // arrives asynchronously — wait for both so the assertion cannot race
+    // the in-flight fetch (the snapshot stays visible alongside the error).
+    await waitFor(() => {
+      expect(result.current.error).toBe(streamError);
+      expect(result.current.execution).toBe(running);
+    });
+  });
+
+  it("reconnect() retries both the fetch and the stream", async () => {
+    const running = executionFixture("aex_5", ExecutionPhase.EXECUTION_IN_PROGRESS);
+    const getFn = vi.fn(async () => running);
+    mockUseStigmer.mockReturnValue({
+      agentExecution: { get: getFn },
+    } as unknown as ReturnType<typeof useStigmer>);
+    const streamReconnect = vi.fn();
+    mockUseExecutionStream.mockReturnValue({
+      ...idleStream(),
+      reconnect: streamReconnect,
+    });
+
+    const { result } = renderHook(() => useLiveAgentExecution("aex_5"));
+    await waitFor(() => expect(result.current.execution).toBe(running));
+
+    const callsBefore = getFn.mock.calls.length;
+    result.current.reconnect();
+    await waitFor(() =>
+      expect(getFn.mock.calls.length).toBeGreaterThan(callsBefore),
+    );
+    expect(streamReconnect).toHaveBeenCalled();
+  });
+
+  it("is a stable no-op for a null id", () => {
+    const getFn = vi.fn();
+    mockUseStigmer.mockReturnValue({
+      agentExecution: { get: getFn },
+    } as unknown as ReturnType<typeof useStigmer>);
+
+    const { result } = renderHook(() => useLiveAgentExecution(null));
+
+    expect(result.current.execution).toBeNull();
+    expect(result.current.isLoading).toBe(false);
+    expect(getFn).not.toHaveBeenCalled();
+    for (const call of mockUseExecutionStream.mock.calls) {
+      expect(call[0]).toBeNull();
+    }
+  });
+});