@circuitwall/jarela 2.2.1 → 2.3.0

package/components/chat/ToolList.test.tsx

@@ -1,7 +1,8 @@
 // @vitest-environment jsdom
 import { describe, it, expect, vi } from "vitest";
-import { render, screen, fireEvent, waitFor, within } from "@testing-library/react";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
 import { ToolList, type ToolEvent } from "./ToolList";
+import { WorkflowStepRetryContext, workflowStepRetryMessage } from "./workflow-step-retry";
 
 const { codexJobGet, codexJobCancel } = vi.hoisted(() => ({
   codexJobGet: vi.fn(),
@@ -343,21 +344,96 @@ describe("ToolList — live progress (ADR-0073)", () => {
     render(<ToolList events={events} />);
     fireEvent.click(screen.getByText("workflow_progress"));
 
-    expect(screen.getByText("workflow")).toBeTruthy();
-    expect(screen.getAllByText("Fetching changes").length).toBeGreaterThan(0);
     expect(screen.getAllByText("Fetch changes").length).toBeGreaterThan(0);
     expect(screen.getAllByText("Build todo list").length).toBeGreaterThan(0);
-    expect(screen.getByLabelText("done")).toBeTruthy();
-    expect(screen.getByLabelText("checking")).toBeTruthy();
-    const firstContract = screen.getAllByText("Step contract")[0];
-    fireEvent.click(firstContract);
-    const contract = firstContract.closest("details");
-    expect(contract).toBeTruthy();
-    if (!contract) throw new Error("Workflow step contract details were not rendered");
-    expect(within(contract).getByText("Baseline tag and repository HEAD")).toBeTruthy();
-    expect(within(contract).getByText("Paths changed since baseline")).toBeTruthy();
-    expect(within(contract).getByText("Inspect system-computed git diff result")).toBeTruthy();
-    expect(within(contract).getByText("git diff returned the changed paths")).toBeTruthy();
+    expect(screen.getByRole("img", { name: "verified" })).toBeTruthy();
+    expect(screen.getByRole("img", { name: "checking" })).toBeTruthy();
+    expect(screen.queryByText("Step contract")).toBeNull();
+    expect(screen.queryByText("Baseline tag and repository HEAD")).toBeNull();
+    expect(screen.getByText("Fetch changes").getAttribute("title")).toContain("git diff returned the changed paths");
+    expect(screen.queryByRole("button", { name: /^Retry / })).toBeNull();
+    expect(screen.queryByText("result")).toBeNull();
+  });
+
+  it("shows a rejected workflow update as an error instead of a silent checklist", () => {
+    const events: ToolEvent[] = [
+      {
+        id: "w4",
+        phase: "call",
+        name: "workflow_progress",
+        payload: {
+          workflow_id: "release_review",
+          items: [{ id: "run-tests", label: "Run tests", input: "Diff", output: "Results", validation: "Run suite", status: "done" }],
+        },
+      },
+      {
+        id: "w4",
+        phase: "result",
+        name: "workflow_progress",
+        payload: { ok: false, workflow_id: "release_review", error: "Every completed workflow item requires observed validation_evidence." },
+      },
+    ];
+
+    render(<ToolList events={events} />);
+    fireEvent.click(screen.getByText("workflow_progress"));
+
+    expect(screen.getByText("Update rejected: Every completed workflow item requires observed validation_evidence.")).toBeTruthy();
+  });
+
+  it("shows the attempt count on a workflow step that was retried", () => {
+    const snapshot = (id: string, status: string) => ({
+      workflow_id: "release_review",
+      items: [{ id: "run-tests", label: "Run tests", input: "Diff", output: "Results", validation: "Run suite", status }],
+    });
+    const result = (status: string) => ({
+      ok: true,
+      workflow_id: "release_review",
+      state: { phase: null, summary: "", error: null, checklist: snapshot("", status).items },
+    });
+    const events: ToolEvent[] = (["checking", "needs_attention", "checking"] as const).flatMap((status, i) => [
+      { id: `a${i}`, phase: "call" as const, name: "workflow_progress", payload: snapshot("", status) },
+      { id: `a${i}`, phase: "result" as const, name: "workflow_progress", payload: result(status) },
+    ]);
+
+    render(<ToolList events={events} />);
+    const rows = screen.getAllByText("workflow_progress");
+    fireEvent.click(rows[1]);
+    expect(screen.queryByText("attempt 2")).toBeNull();
+    fireEvent.click(rows[2]);
+    expect(screen.getByText("attempt 2")).toBeTruthy();
+  });
+
+  it("offers a per-step retry that asks the agent to redo that step", () => {
+    const onRetry = vi.fn();
+    const events: ToolEvent[] = [{
+      id: "w3",
+      phase: "call",
+      name: "workflow_progress",
+      payload: {
+        workflow_id: "release_review",
+        items: [
+          { id: "check-changes", label: "Review changes", input: "Diff", output: "Findings", validation: "Inspect files", validation_evidence: "Diff reviewed", status: "done" },
+          { id: "run-tests", label: "Run tests", input: "Findings", output: "Results", validation: "Run suite", status: "needs_attention" },
+          { id: "report-result", label: "Report result", input: "Results", output: "Summary", validation: "Cross-check" },
+        ],
+      },
+    }];
+
+    render(
+      <WorkflowStepRetryContext.Provider value={onRetry}>
+        <ToolList events={events} />
+      </WorkflowStepRetryContext.Provider>,
+    );
+    fireEvent.click(screen.getByText("workflow_progress"));
+
+    expect(screen.getByRole("button", { name: "Retry Review changes" })).toBeTruthy();
+    expect(screen.queryByRole("button", { name: "Retry Report result" })).toBeNull();
+    fireEvent.click(screen.getByRole("button", { name: "Retry Run tests" }));
+    expect(onRetry).toHaveBeenCalledWith({ workflowId: "release_review", itemId: "run-tests", label: "Run tests" });
+    expect(workflowStepRetryMessage({ workflowId: "release_review", itemId: "run-tests", label: "Run tests" }))
+      .toContain("complete items snapshot");
+    expect(workflowStepRetryMessage({ workflowId: "version_adoption", itemId: "adapt-settings", label: "Adapt settings" }))
+      .toContain('item_id: "adapt-settings"');
   });
 
   it("previews agent-created workflow items while the tool call is running", () => {
@@ -403,8 +479,8 @@ describe("ToolList — live progress (ADR-0073)", () => {
     expect(screen.getAllByText("Review changes").length).toBeGreaterThan(0);
     expect(screen.getAllByText("Run tests").length).toBeGreaterThan(0);
     expect(screen.getAllByText("Report result").length).toBeGreaterThan(0);
-    expect(screen.getByLabelText("done")).toBeTruthy();
-    expect(screen.getByLabelText("checking")).toBeTruthy();
+    expect(screen.getByRole("img", { name: "verified" })).toBeTruthy();
+    expect(screen.getByRole("img", { name: "checking" })).toBeTruthy();
   });
 
   it("renders an invoke_tool dispatch under the target tool's name, args and result", () => {

package/components/chat/ToolList.tsx

@@ -29,6 +29,7 @@ import {
 import { Badge } from "@/components/ui/Badge";
 import { CollapseChevron } from "@/components/ui/CollapseChevron";
 import { WorkflowChecklist, type WorkflowChecklistItemView, type WorkflowChecklistStatus } from "@/components/ui/WorkflowChecklist";
+import { useWorkflowStepRetry } from "./workflow-step-retry";
 import { StructuredTurnCard } from "@/components/chat/StructuredTurnCard";
 import { MetaRow } from "@/components/ui/MetaRow";
 import { ProviderLogo, brandSlugForToolName } from "@/components/models/ProviderLogo";
@@ -263,6 +264,9 @@ interface ToolCallGroup {
   result: unknown;
   deadlineMs: number;
   status: "running" | "ok" | "error" | "async";
+  // workflow_progress only: per-step attempt counts so far in this message
+  // (how many times each item has entered `checking`).
+  workflowAttempts?: Readonly<Record<string, number>>;
   // True when this group's `result` arrived via a later tool_result_get
   // call rather than the original tool's direct return. Surfaces a small
   // "read" pill so it's obvious the agent reaped a background handoff.
@@ -386,7 +390,33 @@ function groupByCallId(events: ToolEvent[]): ToolCallGroup[] {
     g.absorbed = true;
   }
 
-  return order.map((id) => map.get(id)!).filter((g) => !g.absorbed);
+  const groups = order.map((id) => map.get(id)!).filter((g) => !g.absorbed);
+  annotateWorkflowAttempts(groups);
+  return groups;
+}
+
+// Counts each workflow step's transitions into `checking` across the
+// message's workflow_progress calls, so auto-retried steps show "attempt N".
+// Rejected updates (ok:false) changed nothing and are not counted.
+function annotateWorkflowAttempts(groups: ToolCallGroup[]): void {
+  const lastStatus = new Map<string, WorkflowChecklistStatus>();
+  const attempts = new Map<string, Record<string, number>>();
+  for (const group of groups) {
+    if (group.name !== "workflow_progress") continue;
+    if (coerceObject(unwrapLangChainSerializable(group.result))?.ok === false) continue;
+    const view = workflowViewFor(group);
+    if (!view) continue;
+    const counts = { ...(attempts.get(view.workflow_id) ?? {}) };
+    for (const item of view.items) {
+      const key = `${view.workflow_id}:${item.id}`;
+      if (item.status === "checking" && lastStatus.get(key) !== "checking") {
+        counts[item.id] = (counts[item.id] ?? 0) + 1;
+      }
+      lastStatus.set(key, item.status);
+    }
+    attempts.set(view.workflow_id, counts);
+    group.workflowAttempts = counts;
+  }
 }
 
 function ToolCallCard({ group, startedAt }: { group: ToolCallGroup; startedAt: number }) {
@@ -498,6 +528,7 @@ function ToolCallCard({ group, startedAt }: { group: ToolCallGroup; startedAt: n
       {open && (
         <div className="mt-0.5 rounded border border-border/40 bg-surface-2/30 px-2 py-1.5 space-y-1.5 text-[10px]">
           <WorkflowProgressDetails group={group} />
+          {!hasWorkflowView(group) && (<>
           {hasVisibleArgs(group.args) ? (
             <DetailSection label="arguments" value={group.args} />
           ) : hasArgs ? (
@@ -523,6 +554,7 @@ function ToolCallCard({ group, startedAt }: { group: ToolCallGroup; startedAt: n
               value={group.result}
             />
           )}
+          </>)}
         </div>
       )}
     </div>
@@ -617,19 +649,42 @@ function ToolResultRefDetails({ value }: { value: unknown }) {
   );
 }
 
-function WorkflowProgressDetails({ group }: { group: ToolCallGroup }) {
+function workflowViewFor(group: ToolCallGroup): WorkflowProgressView | null {
   if (group.name !== "workflow_progress") return null;
-  const workflow = workflowProgressFrom(group.result) ?? workflowProgressPreviewFrom(group.args);
+  const view = workflowProgressFrom(group.result) ?? workflowProgressPreviewFrom(group.args);
+  const result = coerceObject(unwrapLangChainSerializable(group.result));
+  const attempts = group.workflowAttempts;
+  const withAttempts = view && attempts
+    ? { ...view, items: view.items.map((item) => (attempts[item.id] ? { ...item, attempts: attempts[item.id] } : item)) }
+    : view;
+  if (withAttempts && result?.ok === false && typeof result.error === "string") {
+    return { ...withAttempts, error: `Update rejected: ${result.error}` };
+  }
+  return withAttempts;
+}
+
+/** Workflow rows show only their work items; raw payloads stay visible when the call failed. */
+function hasWorkflowView(group: ToolCallGroup): boolean {
+  return group.status !== "error" && workflowViewFor(group) !== null;
+}
+
+function WorkflowProgressDetails({ group }: { group: ToolCallGroup }) {
+  const retryStep = useWorkflowStepRetry();
+  const workflow = workflowViewFor(group);
   if (!workflow) return null;
+  const workflowId = workflow.workflow_id;
   return (
     <WorkflowChecklist
       compact
       eyebrow="workflow"
-      title={workflow.workflow_id.replace(/[_-]/g, " ")}
+      title={workflowId.replace(/[_-]/g, " ")}
       phaseLabel={workflow.phase ?? "in progress"}
       summary={workflow.summary ?? ""}
       items={workflow.items}
       error={workflow.error}
+      onRetryItem={retryStep
+        ? (item) => retryStep({ workflowId, itemId: item.id, label: item.label })
+        : undefined}
     />
   );
 }

package/components/chat/chat-helpers.test.tsx

@@ -1,6 +1,6 @@
 import { describe, it, expect } from "vitest";
 import type { Message } from "@/api/types";
-import { appendUnique, applyThreadMeta, type ThreadMetaApplier } from "./chat-helpers";
+import { appendUnique, applyThreadMeta, compactionOutcomeToast, type ThreadMetaApplier } from "./chat-helpers";
 
 // created_at is display-only after the seq-ordering change — every fixture
 // shares one value to prove ordering doesn't depend on it. `seq` is omitted
@@ -115,10 +115,18 @@ describe("applyThreadMeta", () => {
         setWarmSummarySourceChars: push("warmSummarySourceChars") as (v: number | null) => void,
         setContextWindowTokens: push("contextWindowTokens") as (v: number | null) => void,
         setWarmSummaryPending: push("warmSummaryPending") as (v: boolean) => void,
+        setManualCompactionPending: push("manualCompactionPending") as (v: boolean) => void,
       },
     };
   }
 
+  it("restores a server-side manual /compact so a remounted view stays busy", () => {
+    const { meta, calls } = recorder();
+    applyThreadMeta(meta, { hot_since_seq: null, manual_compaction_pending: true });
+    applyThreadMeta(meta, { hot_since_seq: null });
+    expect(calls.manualCompactionPending).toEqual([true, false]);
+  });
+
   it("marks an observed hot_since as pending until its matching summary arrives", () => {
     const { meta, calls } = recorder();
 
@@ -148,3 +156,18 @@ describe("applyThreadMeta", () => {
     expect(calls.warmSummaryPending).toEqual([false]);
   });
 });
+
+describe("compactionOutcomeToast", () => {
+  it("reports success with the summarised message count", () => {
+    expect(compactionOutcomeToast({ compacted: true, message_count: 2 })).toMatchObject({ kind: "success", body: "Summarised 2 messages into warm context." });
+    expect(compactionOutcomeToast({ compacted: true, message_count: 1 }).body).toBe("Summarised 1 message into warm context.");
+    expect(compactionOutcomeToast({ compacted: true, message_count: 0 }).body).toBe("Started a fresh context window.");
+  });
+
+  it("only says the conversation is empty when the server says so", () => {
+    expect(compactionOutcomeToast({ compacted: false, reason: "nothing to compact" }).title).toBe("Nothing to compact");
+    const declined = compactionOutcomeToast({ compacted: false, reason: "no summary produced" });
+    expect(declined.title).toBe("Nothing was compacted");
+    expect(declined.body).not.toMatch(/send some messages/i);
+  });
+});

package/components/chat/chat-helpers.ts

@@ -1,5 +1,5 @@
 "use client";
-import type { ContentPart, Message, SummaryTopicSegment } from "@/api/types";
+import type { ContentPart, Message, SummaryTopicSegment, WarmChannelSummary } from "@/api/types";
 
 export interface QueuedMessage {
   id: string;
@@ -7,9 +7,46 @@ export interface QueuedMessage {
   attachments: ContentPart[];
 }
 
-export interface SystemNotice {
-  id: string;
-  text: string;
+export interface CompactionOutcome {
+  compacted: boolean;
+  reason?: string;
+  message_count?: number;
+}
+
+export interface CompactionToast {
+  kind: "info" | "success" | "error";
+  title: string;
+  body: string;
+}
+
+// Maps the /compact response to the toast the user sees. The server's reason
+// decides the text: "nothing to compact" means the thread is empty, anything
+// else means there were messages but no summary came out of them.
+export function compactionOutcomeToast(result: CompactionOutcome): CompactionToast {
+  if (result.compacted) {
+    const n = result.message_count ?? 0;
+    return {
+      kind: "success",
+      title: "Context compacted",
+      body: n > 0
+        ? `Summarised ${n} message${n === 1 ? "" : "s"} into warm context.`
+        : "Started a fresh context window.",
+    };
+  }
+  if (result.reason === "nothing to compact") {
+    return { kind: "info", title: "Nothing to compact", body: "This conversation has no messages yet." };
+  }
+  if (result.reason === "already compacting") {
+    return { kind: "info", title: "Already compacting", body: "A compaction for this conversation is still running." };
+  }
+  if (result.reason === "timed out") {
+    return { kind: "error", title: "Compaction timed out", body: "The summary took too long and was discarded. Context is unchanged." };
+  }
+  return {
+    kind: "info",
+    title: "Nothing was compacted",
+    body: "There was too little to summarise, or the model returned no usable summary. Context is unchanged.",
+  };
 }
 
 export interface ThreadMetaApplier {
@@ -22,9 +59,11 @@ export interface ThreadMetaApplier {
   setWarmSummarySourceMessages: (v: number | null) => void;
   setWarmSummarySourceChars: (v: number | null) => void;
   setWarmSummaryTopics?: (v: SummaryTopicSegment[] | null) => void;
+  setWarmChannelSummaries?: (v: WarmChannelSummary[]) => void;
   setContextWindowTokens: (v: number | null) => void;
   setWarmSummaryPending?: (v: boolean) => void;
   setCompactionPending?: (v: boolean) => void;
+  setManualCompactionPending?: (v: boolean) => void;
 }
 
 export interface ThreadGetPayload {
@@ -37,8 +76,10 @@ export interface ThreadGetPayload {
   warm_summary_source_messages?: number | null;
   warm_summary_source_chars?: number | null;
   warm_summary_topics?: SummaryTopicSegment[] | null;
+  warm_channel_summaries?: WarmChannelSummary[];
   pending_hot_since?: string | null;
   pending_hot_since_seq?: number | null;
+  manual_compaction_pending?: boolean;
   context_window_tokens?: number | null;
 }
 
@@ -128,10 +169,12 @@ export function applyThreadMeta(meta: ThreadMetaApplier, payload: ThreadGetPaylo
   meta.setWarmSummarySourceMessages(payload.warm_summary_source_messages ?? null);
   meta.setWarmSummarySourceChars(payload.warm_summary_source_chars ?? null);
   meta.setWarmSummaryTopics?.(payload.warm_summary_topics ?? null);
+  meta.setWarmChannelSummaries?.(payload.warm_channel_summaries ?? []);
   meta.setContextWindowTokens(payload.context_window_tokens ?? null);
   const summaryFresh = hotSinceSeq !== null && summaryBeforeSeq === hotSinceSeq;
   meta.setWarmSummaryPending?.(hotSinceSeq !== null && !summaryFresh);
   meta.setCompactionPending?.(payload.pending_hot_since_seq != null);
+  meta.setManualCompactionPending?.(payload.manual_compaction_pending === true);
 }
 
 export function makeQueuedId(prefix = "q"): string {

package/components/chat/useThreadActivity.test.tsx

@@ -0,0 +1,113 @@
+// @vitest-environment jsdom
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ThreadActivity } from "@/api/types";
+
+const mocks = vi.hoisted(() => ({ activity: vi.fn(), getThread: vi.fn() }));
+
+vi.mock("@/api/client", () => ({
+  api: {
+    threads: {
+      activity: (...args: unknown[]) => mocks.activity(...args),
+      get: (...args: unknown[]) => mocks.getThread(...args),
+    },
+  },
+}));
+
+const { useThreadActivity } = await import("./useThreadActivity");
+
+const idle: ThreadActivity = { run: null, queue_depth: 0, compaction: null, busy: false };
+const running: ThreadActivity = {
+  run: { phase: "thinking", label: "Thinking…", started_at: 1, agent_id: "a" },
+  queue_depth: 1,
+  compaction: null,
+  busy: true,
+};
+const compacting: ThreadActivity = {
+  run: null,
+  queue_depth: 0,
+  compaction: { kind: "manual", boundary_seq: 4, started_at: 1, deadline_at: 2 },
+  busy: true,
+};
+
+function metaApplier() {
+  return {
+    setHotSince: vi.fn(), setHotSinceSeq: vi.fn(), setWarmSummary: vi.fn(), setWarmSummaryBefore: vi.fn(),
+    setWarmSummaryBeforeSeq: vi.fn(), setWarmSummaryComputedAt: vi.fn(), setWarmSummarySourceMessages: vi.fn(),
+    setWarmSummarySourceChars: vi.fn(), setContextWindowTokens: vi.fn(), setWarmSummaryPending: vi.fn(),
+    setCompactionPending: vi.fn(), setManualCompactionPending: vi.fn(), setWarmSummaryTopics: vi.fn(),
+    setWarmChannelSummaries: vi.fn(),
+  };
+}
+
+async function tick(ms: number) {
+  await act(async () => { await vi.advanceTimersByTimeAsync(ms); });
+}
+
+describe("useThreadActivity", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    mocks.activity.mockReset();
+    mocks.getThread.mockReset();
+    mocks.getThread.mockResolvedValue({ messages: [], has_more: false });
+  });
+  afterEach(() => vi.useRealTimers());
+
+  it("attaches to a run started elsewhere when this client is not streaming", async () => {
+    mocks.activity.mockResolvedValue(running);
+    const attach = vi.fn().mockResolvedValue(undefined);
+    renderHook(() => useThreadActivity({
+      threadId: "t1", attach, isLive: () => false, lastSettledAt: () => 0, metaApplier: metaApplier(),
+    }));
+    await tick(1_500);
+    expect(attach).toHaveBeenCalledWith("t1");
+  });
+
+  it("does not attach while it owns a stream or right after one settled", async () => {
+    mocks.activity.mockResolvedValue(running);
+    const attach = vi.fn().mockResolvedValue(undefined);
+    let live = true;
+    renderHook(() => useThreadActivity({
+      threadId: "t1", attach, isLive: () => live, lastSettledAt: () => Date.now(), metaApplier: metaApplier(),
+    }));
+    await tick(1_500);
+    live = false;
+    await tick(1_500);
+    expect(attach).not.toHaveBeenCalled();
+  });
+
+  it("restores compaction flags and refreshes metadata once compaction ends", async () => {
+    mocks.activity.mockResolvedValueOnce(compacting).mockResolvedValue(idle);
+    const meta = metaApplier();
+    const { result } = renderHook(() => useThreadActivity({
+      threadId: "t1", attach: vi.fn(), isLive: () => false, lastSettledAt: () => 0, metaApplier: meta,
+    }));
+    await tick(1_500);
+    expect(result.current?.compaction?.kind).toBe("manual");
+    expect(meta.setCompactionPending).toHaveBeenCalledWith(true);
+    expect(meta.setManualCompactionPending).toHaveBeenCalledWith(true);
+    await tick(1_500);
+    expect(mocks.getThread).toHaveBeenCalledWith("t1", { limit: 1 });
+    expect(meta.setManualCompactionPending).toHaveBeenLastCalledWith(false);
+  });
+
+  it("clears compaction flags even if the metadata refresh fails", async () => {
+    mocks.activity.mockResolvedValueOnce(compacting).mockResolvedValue(idle);
+    mocks.getThread.mockRejectedValue(new Error("offline"));
+    const meta = metaApplier();
+    renderHook(() => useThreadActivity({
+      threadId: "t1", attach: vi.fn(), isLive: () => false, lastSettledAt: () => 0, metaApplier: meta,
+    }));
+    await tick(3_000);
+    expect(meta.setManualCompactionPending).toHaveBeenLastCalledWith(false);
+    expect(meta.setCompactionPending).toHaveBeenLastCalledWith(false);
+  });
+
+  it("does not poll without a thread", async () => {
+    renderHook(() => useThreadActivity({
+      threadId: null, attach: vi.fn(), isLive: () => false, lastSettledAt: () => 0, metaApplier: metaApplier(),
+    }));
+    await tick(10_000);
+    expect(mocks.activity).not.toHaveBeenCalled();
+  });
+});

package/components/chat/useThreadActivity.ts

@@ -0,0 +1,94 @@
+"use client";
+import { useEffect, useRef, useState } from "react";
+import { api } from "@/api/client";
+import type { ThreadActivity } from "@/api/types";
+import { applyThreadMeta, type ThreadMetaApplier } from "./chat-helpers";
+
+const BUSY_POLL_MS = 1_500;
+const IDLE_POLL_MS = 5_000;
+// A run's stream ends a moment before the registry marks it finished; a
+// snapshot inside this window may still report the run that just ended.
+const SETTLE_GRACE_MS = 2_000;
+
+interface Params {
+  threadId: string | null;
+  attach: (threadId: string) => Promise<unknown>;
+  /** Synchronous: does this client already own a live stream? */
+  isLive: () => boolean;
+  /** Epoch ms when this client's last stream settled. */
+  lastSettledAt: () => number;
+  metaApplier: ThreadMetaApplier;
+}
+
+/**
+ * Poll what the thread is doing on the server and keep the chat in step:
+ * re-attach to a turn started elsewhere (scheduler, watcher, bridge, another
+ * device), restore compaction flags after a remount, and refresh the thread
+ * metadata once a compaction finishes.
+ */
+export function useThreadActivity({ threadId, attach, isLive, lastSettledAt, metaApplier }: Params): ThreadActivity | null {
+  const [activity, setActivity] = useState<ThreadActivity | null>(null);
+  const deps = useRef({ attach, isLive, lastSettledAt, metaApplier });
+  deps.current = { attach, isLive, lastSettledAt, metaApplier };
+
+  useEffect(() => {
+    setActivity(null);
+    if (!threadId) return;
+    let cancelled = false;
+    let timer: number | null = null;
+    let hadCompaction = false;
+
+    const schedule = (ms: number) => {
+      if (!cancelled) timer = window.setTimeout(tick, ms);
+    };
+
+    async function tick() {
+      if (cancelled || !threadId) return;
+      if (typeof document !== "undefined" && document.hidden) { schedule(IDLE_POLL_MS); return; }
+      let next: ThreadActivity;
+      try {
+        next = await api.threads.activity(threadId);
+      } catch {
+        schedule(IDLE_POLL_MS);
+        return;
+      }
+      if (cancelled) return;
+      setActivity(next);
+      const d = deps.current;
+
+      const serverRunning = next.run !== null || next.queue_depth > 0;
+      const recentlySettled = Date.now() - d.lastSettledAt() < SETTLE_GRACE_MS;
+      if (serverRunning && !d.isLive() && !recentlySettled) {
+        d.attach(threadId).catch(() => { /* best-effort */ });
+      }
+
+      if (next.compaction) {
+        if (next.compaction.kind !== "refresh") d.metaApplier.setCompactionPending?.(true);
+        if (next.compaction.kind === "manual") d.metaApplier.setManualCompactionPending?.(true);
+        hadCompaction = true;
+      } else if (hadCompaction) {
+        hadCompaction = false;
+        // The compaction just finished. Clear the flags from the snapshot
+        // itself so a failed refresh below can't leave the chat locked, then
+        // pull the new boundary and recap.
+        d.metaApplier.setCompactionPending?.(false);
+        d.metaApplier.setManualCompactionPending?.(false);
+        api.threads.get(threadId, { limit: 1 })
+          .then((meta) => { if (!cancelled) applyThreadMeta(deps.current.metaApplier, meta); })
+          .catch(() => { /* next poll retries */ });
+      }
+
+      schedule(next.busy ? BUSY_POLL_MS : IDLE_POLL_MS);
+    }
+
+    // The thread load attaches to any in-flight run itself; give it a beat
+    // so this poller doesn't race it with a second attach.
+    schedule(BUSY_POLL_MS);
+    return () => {
+      cancelled = true;
+      if (timer !== null) window.clearTimeout(timer);
+    };
+  }, [threadId]);
+
+  return activity;
+}