@circuitwall/jarela 0.9.3 → 0.10.0

package/app/api/v1/threads/[thread_id]/run/route.ts

@@ -88,28 +88,60 @@ export async function POST(req: NextRequest, { params }: Params) {
   // Drive the agent to completion regardless of client connection. Events
   // go to the registry; the GET subscriber (and any reattaching clients)
   // receive them via subscribe().
+  //
+  // CRITICAL: finishRun() MUST run no matter what — if it doesn't, the
+  // run is pinned as "running" forever, every subsequent POST returns
+  // 409 run_in_flight, and the user sees a silently-dead chat. The TTL
+  // eviction is scheduled inside finishRun(), so a leaked entry never
+  // self-heals. Wrap the whole body in try/finally.
   void (async () => {
-    const collected = await collectStream(prepared.stream as AsyncIterable<StreamChunk>, {
-      onChunk: (chunk) => broadcast(active, chunk),
-    });
-    // If the stream threw mid-iteration, collectStream returns terminal="error"
-    // but no `error` chunk was broadcast — surface one to subscribers.
-    if (collected.terminal === "error" && collected.errorMessage) {
+    let terminal: "done" | "error" = "error";
+    let assistantContent = "";
+    try {
+      const collected = await collectStream(prepared.stream as AsyncIterable<StreamChunk>, {
+        onChunk: (chunk) => broadcast(active, chunk),
+      });
+      assistantContent = collected.assistantContent;
+      terminal = collected.terminal;
+      // If the stream threw mid-iteration, collectStream returns terminal="error"
+      // but no `error` chunk was broadcast — surface one to subscribers.
+      if (collected.terminal === "error" && collected.errorMessage) {
+        broadcast(active, {
+          type: "error",
+          data: { message: collected.errorMessage, code: "stream_error" },
+        });
+      }
+      try {
+        persistAssistantMessage(thread_id, collected.assistantContent, collected.usedTools, collected.toolEvents, null, collected.usage ?? null, prepared.context_snapshot ?? null);
+      } catch (persistErr) {
+        // Persistence failure must not strand the run — surface and continue
+        // to finishRun in the finally block.
+        terminal = "error";
+        broadcast(active, {
+          type: "error",
+          data: { message: `persist failed: ${(persistErr as Error).message}`, code: "persist_error" },
+        });
+      }
+    } catch (err) {
+      // Unhandled throw from collectStream / the underlying stream. Without
+      // this catch, finishRun would never run and the registry entry would
+      // stick as "running" indefinitely (see CRITICAL note above).
+      terminal = "error";
       broadcast(active, {
         type: "error",
-        data: { message: collected.errorMessage, code: "stream_error" },
+        data: { message: (err as Error).message ?? String(err), code: "run_crashed" },
+      });
+    } finally {
+      finishRun(active, terminal);
+      publishNotification({
+        type: "run_completed",
+        thread_id,
+        agent_id: thread?.agent_id ?? null,
+        status: terminal,
+        preview: assistantContent.replace(/\s+/g, " ").trim().slice(0, 120),
+        ts: Date.now(),
       });
     }
-    persistAssistantMessage(thread_id, collected.assistantContent, collected.usedTools, collected.toolEvents, null, collected.usage ?? null, prepared.context_snapshot ?? null);
-    finishRun(active, collected.terminal);
-    publishNotification({
-      type: "run_completed",
-      thread_id,
-      agent_id: thread?.agent_id ?? null,
-      status: collected.terminal,
-      preview: collected.assistantContent.replace(/\s+/g, " ").trim().slice(0, 120),
-      ts: Date.now(),
-    });
   })();
 
   return new Response(
@@ -124,8 +156,14 @@ export async function POST(req: NextRequest, { params }: Params) {
 // `EventSource` — never `fetch().body.getReader()`, which is unreliable on
 // iOS Safari for long-lived streaming responses.
 //
-// Returns 404 with no body if there's no run to attach to (run never
-// existed, or it finished + TTL-evicted before the GET arrived).
+// Emits a single synthetic `done` event and closes when there's no run to
+// attach to (run never existed, or it finished + TTL-evicted before the GET
+// arrived). We deliberately do NOT return 404 here: browsers map a 404 SSE
+// response onto `EventSource.onerror` with no terminal event, which trips
+// EventSource's auto-reconnect logic and leaves the client in a "stream
+// open but silent" state — UIs gating on a `done` event hang forever
+// showing the Stop/Reconnecting affordances. A 200 with `data: {"type":
+// "done"}\n\n` makes the iterator drain cleanly on every transport.
 //
 // `show_tools` / `show_thinking` query params let the caller suppress
 // chunk types it doesn't want to render. Defaults: both on. The full
@@ -133,14 +171,23 @@ export async function POST(req: NextRequest, { params }: Params) {
 // agent run config are run-wide settings, not per-subscriber filters).
 export async function GET(req: NextRequest, { params }: Params) {
   const { thread_id } = await params;
-  const run = getRun(thread_id);
-  if (!run) return new Response(null, { status: 404 });
-
   const showTools = req.nextUrl.searchParams.get("show_tools") !== "false";
   const showThinking = req.nextUrl.searchParams.get("show_thinking") !== "false";
   const stream_options: StreamOptions = {
     filters: { include_tools: showTools, include_thinking: showThinking },
   };
+
+  const run = getRun(thread_id);
+  if (!run) {
+    const stream = new ReadableStream({
+      start(controller) {
+        controller.enqueue(sse({ type: "done" }));
+        controller.close();
+      },
+    });
+    return sseResponse(stream);
+  }
+
   return attachStream(thread_id, stream_options);
 }
 

package/components/agents/AgentEditor.tsx

@@ -807,7 +807,9 @@ function ToolGroupBlock({
   const selectedInGroup = allTools.filter((t) => selected.includes(t.name)).length;
   const allOn = selectedInGroup === allTools.length;
   const someOn = selectedInGroup > 0 && !allOn;
-  const [open, setOpen] = useState(selectedInGroup > 0);
+  // Collapsed by default to keep the editor compact on small / PWA viewports;
+  // the header still surfaces the selected/total count.
+  const [open, setOpen] = useState(false);
   const headerRef = useRef<HTMLInputElement>(null);
 
   useEffect(() => {
@@ -844,8 +846,8 @@ function ToolGroupBlock({
 
 // Collapsible per-category block with a tri-state header checkbox. The
 // header toggle flips the entire category on/off; individual tool checkboxes
-// stay available for fine-grained control. Collapsed-by-default when no tool
-// in the category is selected, to keep the editor compact.
+// stay available for fine-grained control. Collapsed by default to keep the
+// editor short on mobile / PWA viewports.
 function ToolCategoryBlock({
   category,
   tools,
@@ -866,7 +868,8 @@ function ToolCategoryBlock({
   const selectedInCat = tools.filter((t) => selected.includes(t.name)).length;
   const allOn = selectedInCat === tools.length;
   const someOn = selectedInCat > 0 && !allOn;
-  const [open, setOpen] = useState(selectedInCat > 0);
+  // Collapsed by default — see ToolGroupBlock comment.
+  const [open, setOpen] = useState(false);
   const headerRef = useRef<HTMLInputElement>(null);
 
   // Render the tri-state indeterminate dash via the DOM property (React

package/components/chat/MessageBubble.tsx

@@ -7,7 +7,7 @@ import rehypeRaw from "rehype-raw";
 import rehypeHighlight from "rehype-highlight";
 import rehypeSanitize, { defaultSchema } from "rehype-sanitize";
 import "highlight.js/styles/github-dark.css";
-import { Bot, Check, ChevronRight, Copy, Link as LinkIcon, Link2, Loader2, MessageCircle, Paperclip, Pause, Play, User, Users, X } from "lucide-react";
+import { Bot, Check, ChevronRight, Clock, Copy, Eye, EyeOff, Link as LinkIcon, Link2, Loader2, MessageCircle, Paperclip, Pause, Play, User, Users, X } from "lucide-react";
 import type { AgentConfig, Message, UserProfile } from "@/api/types";
 import type { ContentPart } from "@/api/types";
 import { ToolList } from "@/components/chat/ToolList";
@@ -409,6 +409,110 @@ function UserAvatar({ profile }: { profile?: UserProfile | null }) {
 // side changes, update both.
 const parseBridgeContext = parseBridgePrompt;
 
+const SILENT_TRIGGER_RE = /\n+\[SILENT_TRIGGER\][^\n]*(?:\n(?!\n).*)*$/;
+
+interface ScheduledTaskCardData {
+  kind: "scheduled_task";
+  prompt: string;
+  silent: boolean;
+}
+
+interface WatcherCardData {
+  kind: "watcher";
+  label: string;
+  tool: string;
+  args: string;
+  diff: string;
+  directive: string;
+  silent: boolean;
+}
+
+type TriggerCardData = ScheduledTaskCardData | WatcherCardData;
+
+// Strip the `[SILENT_TRIGGER] …` envelope that runTriggerAgent appends
+// in silent mode so the card can render the user's original prompt and
+// surface a separate "Silent" pill instead of leaking framework prose.
+function stripSilentEnvelope(text: string): { text: string; silent: boolean } {
+  const m = SILENT_TRIGGER_RE.exec(text);
+  if (!m) return { text, silent: false };
+  return { text: text.slice(0, m.index).trimEnd(), silent: true };
+}
+
+function parseTriggerMessage(category: string | null | undefined, raw: string): TriggerCardData | null {
+  if (category === "scheduled_task") {
+    const { text, silent } = stripSilentEnvelope(raw);
+    return { kind: "scheduled_task", prompt: text, silent };
+  }
+  if (category === "watcher") {
+    const { text, silent } = stripSilentEnvelope(raw);
+    const headerRe = /^Watcher\s+"([^"]*)"\s+detected a change\.\s*\n+Tool:\s*([^\n]+)\s*\nArgs:\s*([\s\S]*?)\n+---\s*Diff[^\n]*---\s*\n([\s\S]*?)\n\n([\s\S]*)$/;
+    const m = headerRe.exec(text);
+    if (!m) return null;
+    return {
+      kind: "watcher",
+      label: m[1],
+      tool: m[2].trim(),
+      args: m[3].trim(),
+      diff: m[4].trim(),
+      directive: m[5].trim(),
+      silent,
+    };
+  }
+  return null;
+}
+
+// Compact header card for trigger-originated user messages (scheduled
+// tasks + watchers, ADR-0027/ADR-0032). Surfaces the trigger type with
+// an icon + label so the operator can tell at a glance that the prompt
+// came from automation and not from them. Watchers additionally expose
+// the diff context in a collapsed section to keep large diffs out of
+// the main bubble height.
+function TriggerMessageCard({ data }: { data: TriggerCardData }) {
+  const [diffOpen, setDiffOpen] = useState(false);
+  const Icon = data.kind === "scheduled_task" ? Clock : Eye;
+  const label = data.kind === "scheduled_task" ? "Scheduled task" : `Watcher: ${data.label || "(unnamed)"}`;
+  return (
+    <div className="flex flex-col gap-1.5 min-w-0">
+      <div className="flex items-center gap-1.5 text-[11px] text-white/85 min-w-0">
+        <Icon size={11} className="shrink-0" />
+        <span className="font-medium truncate">{label}</span>
+        {data.kind === "watcher" && (
+          <span className="px-1.5 py-0.5 rounded-full bg-white/15 text-[9.5px] uppercase tracking-wide shrink-0">
+            {data.tool}
+          </span>
+        )}
+        {data.silent && (
+          <span className="flex items-center gap-1 px-1.5 py-0.5 rounded-full bg-white/15 text-[9.5px] uppercase tracking-wide shrink-0" title="Silent trigger: reply only if material">
+            <EyeOff size={9} />
+            silent
+          </span>
+        )}
+      </div>
+      {data.kind === "watcher" && (
+        <button
+          type="button"
+          onClick={() => setDiffOpen((v) => !v)}
+          className="flex items-center gap-1 text-left text-[11px] text-white/75 hover:text-white/95"
+          aria-expanded={diffOpen}
+          title={diffOpen ? "Hide diff" : "Show diff"}
+        >
+          <ChevronRight size={11} className={`shrink-0 transition-transform ${diffOpen ? "rotate-90" : ""}`} />
+          <span>Change context</span>
+        </button>
+      )}
+      {data.kind === "watcher" && diffOpen && (
+        <div className="ml-4 flex flex-col gap-1">
+          <pre className="m-0 px-2 py-1.5 rounded bg-black/25 text-[11px] leading-snug whitespace-pre-wrap break-words text-white/90 max-h-72 overflow-auto">{data.args}</pre>
+          <pre className="m-0 px-2 py-1.5 rounded bg-black/25 text-[11px] leading-snug whitespace-pre-wrap break-words text-white/90 max-h-96 overflow-auto">{data.diff}</pre>
+        </div>
+      )}
+      <p className="whitespace-pre-wrap text-[13.5px] leading-relaxed">
+        {data.kind === "scheduled_task" ? data.prompt : data.directive}
+      </p>
+    </div>
+  );
+}
+
 // Compact header card for inbound bridge messages. Shows sender + chat
 // context as a single line of metadata above the actual message text, so a
 // WhatsApp DM looks like "Alice • DM\n<text>" and a group message looks
@@ -1099,6 +1203,9 @@ export const MessageBubble = memo(function MessageBubble({ message, agentConfig,
           {typeof parsed === "string" ? (
             isUser ? (
               (() => {
+                const category = "category" in message ? message.category : null;
+                const trigger = parseTriggerMessage(category, parsed);
+                if (trigger) return <TriggerMessageCard data={trigger} />;
                 const bridge = parseBridgeContext(parsed);
                 if (bridge) return <BridgeMessageCard ctx={bridge} />;
                 const ctx = parseCapturedContext(parsed);

package/components/dashboard/DashboardPanel.tsx

@@ -388,18 +388,9 @@ export function DashboardPanel() {
               : "Currency defaults to USD because no location-based currency is available."}
           </p>
 
-          <section className="rounded-2xl border border-[var(--border)] bg-[var(--bg-secondary)]/90 p-4 shadow-sm">
-            <h3 className="text-sm font-medium text-[var(--text-primary)] mb-3">Token usage over time</h3>
-            <InteractiveTokenChart
-              series={series}
-              selectedDay={selectedDay}
-              onSelectDay={(day) => setSelectedDay((prev) => (prev === day ? null : day))}
-            />
-          </section>
-
           <section className="rounded-2xl border border-[var(--border)] bg-[var(--bg-secondary)]/90 p-4 shadow-sm">
             <div className="mb-3 flex flex-wrap items-center justify-between gap-2">
-              <h3 className="text-sm font-medium text-[var(--text-primary)]">Estimated cost over time</h3>
+              <h3 className="text-sm font-medium text-[var(--text-primary)]">Tokens &amp; cost over time</h3>
               {selectedDay ? (
                 <button
                   type="button"
@@ -414,12 +405,19 @@ export function DashboardPanel() {
                 <span className="text-[11px] text-[var(--text-secondary)]">Click a day to narrow the breakdown</span>
               )}
             </div>
-            <InteractiveCostChart
+            <InteractiveTokenChart
               series={series}
-              currencyInfo={currencyInfo}
               selectedDay={selectedDay}
               onSelectDay={(day) => setSelectedDay((prev) => (prev === day ? null : day))}
             />
+            <div className="mt-3 border-t border-[var(--border)]/60 pt-3">
+              <InteractiveCostChart
+                series={series}
+                currencyInfo={currencyInfo}
+                selectedDay={selectedDay}
+                onSelectDay={(day) => setSelectedDay((prev) => (prev === day ? null : day))}
+              />
+            </div>
           </section>
 
           <div className="grid md:grid-cols-2 gap-4">
@@ -670,6 +668,14 @@ function InsightChip({ label, value, hint }: { label: string; value: string; hin
   );
 }
 
+// Per-tier breakdown colors shared by the stacked token chart legend.
+const TIER_COLORS: Record<"hot" | "warm" | "facts" | "overhead", string> = {
+  hot: "#22d3ee",
+  warm: "#f59e0b",
+  facts: "#a78bfa",
+  overhead: "#94a3b8",
+};
+
 type DonutSlice = {
   id: string;
   label: string;
@@ -1033,6 +1039,15 @@ function InteractiveTokenChart({
             const totalHeight = hasData && maxTotal > 0 ? Math.max(4, Math.round((total / maxTotal) * 150)) : 0;
             const inputHeight = hasData ? Math.round((point.input_tokens_est / total) * totalHeight) : 0;
             const outputHeight = hasData ? Math.max(0, totalHeight - inputHeight) : 0;
+            // Subdivide the input portion by measured tier breakdown when the
+            // day has at least one snapshotted assistant turn. Legacy days
+            // (measured_input_tokens === 0) fall back to a solid violet block.
+            const tier = point.tier_tokens;
+            const tierTotal = tier?.measured_input_tokens ?? 0;
+            const hotPx = tierTotal > 0 ? Math.round((tier.hot_tokens / tierTotal) * inputHeight) : 0;
+            const warmPx = tierTotal > 0 ? Math.round((tier.warm_tokens / tierTotal) * inputHeight) : 0;
+            const factsPx = tierTotal > 0 ? Math.round((tier.facts_tokens / tierTotal) * inputHeight) : 0;
+            const overheadPx = tierTotal > 0 ? Math.max(0, inputHeight - hotPx - warmPx - factsPx) : 0;
             const isActive = idx === hovered;
             const isSelected = selectedDay === point.day;
             const clickable = !!onSelectDay && hasData;
@@ -1070,13 +1085,50 @@ function InteractiveTokenChart({
                           transition: `height 420ms cubic-bezier(0.2, 0.8, 0.2, 1) ${idx * 18}ms`,
                         }}
                       />
-                      <div
-                        className="w-full bg-gradient-to-t from-indigo-500 to-violet-400"
-                        style={{
-                          height: barsReady ? `${inputHeight}px` : "0px",
-                          transition: `height 420ms cubic-bezier(0.2, 0.8, 0.2, 1) ${idx * 18 + 30}ms`,
-                        }}
-                      />
+                      {tierTotal > 0 ? (
+                        <>
+                          <div
+                            className="w-full"
+                            style={{
+                              background: TIER_COLORS.hot,
+                              height: barsReady ? `${hotPx}px` : "0px",
+                              transition: `height 420ms cubic-bezier(0.2, 0.8, 0.2, 1) ${idx * 18 + 30}ms`,
+                            }}
+                          />
+                          <div
+                            className="w-full"
+                            style={{
+                              background: TIER_COLORS.warm,
+                              height: barsReady ? `${warmPx}px` : "0px",
+                              transition: `height 420ms cubic-bezier(0.2, 0.8, 0.2, 1) ${idx * 18 + 42}ms`,
+                            }}
+                          />
+                          <div
+                            className="w-full"
+                            style={{
+                              background: TIER_COLORS.facts,
+                              height: barsReady ? `${factsPx}px` : "0px",
+                              transition: `height 420ms cubic-bezier(0.2, 0.8, 0.2, 1) ${idx * 18 + 54}ms`,
+                            }}
+                          />
+                          <div
+                            className="w-full"
+                            style={{
+                              background: TIER_COLORS.overhead,
+                              height: barsReady ? `${overheadPx}px` : "0px",
+                              transition: `height 420ms cubic-bezier(0.2, 0.8, 0.2, 1) ${idx * 18 + 66}ms`,
+                            }}
+                          />
+                        </>
+                      ) : (
+                        <div
+                          className="w-full bg-gradient-to-t from-indigo-500 to-violet-400"
+                          style={{
+                            height: barsReady ? `${inputHeight}px` : "0px",
+                            transition: `height 420ms cubic-bezier(0.2, 0.8, 0.2, 1) ${idx * 18 + 30}ms`,
+                          }}
+                        />
+                      )}
                     </>
                   ) : null}
                 </div>
@@ -1089,11 +1141,17 @@ function InteractiveTokenChart({
         </div>
       </div>
       <div className="mt-2 flex flex-wrap items-center gap-3 text-[11px] text-[var(--text-secondary)]">
-        <span className="inline-flex items-center gap-1"><span className="w-2 h-2 rounded-full bg-violet-400" />input</span>
+        <span className="inline-flex items-center gap-1"><span className="w-2 h-2 rounded-sm" style={{ background: TIER_COLORS.hot }} />hot</span>
+        <span className="inline-flex items-center gap-1"><span className="w-2 h-2 rounded-sm" style={{ background: TIER_COLORS.warm }} />warm</span>
+        <span className="inline-flex items-center gap-1"><span className="w-2 h-2 rounded-sm" style={{ background: TIER_COLORS.facts }} />facts</span>
+        <span className="inline-flex items-center gap-1"><span className="w-2 h-2 rounded-sm" style={{ background: TIER_COLORS.overhead }} />overhead</span>
+        <span className="inline-flex items-center gap-1"><span className="w-2 h-2 rounded-full bg-violet-400" />input (est)</span>
         <span className="inline-flex items-center gap-1"><span className="w-2 h-2 rounded-full bg-amber-400" />output</span>
         {active && (
           <span className="ml-auto text-[var(--text-primary)]">
-            in {formatInt(active.input_tokens_est)} · out {formatInt(active.output_tokens_est)}
+            {active.tier_tokens.measured_input_tokens > 0
+              ? `hot ${formatInt(active.tier_tokens.hot_tokens)} · warm ${formatInt(active.tier_tokens.warm_tokens)} · facts ${formatInt(active.tier_tokens.facts_tokens)} · overhead ${formatInt(active.tier_tokens.overhead_tokens)} · out ${formatInt(active.output_tokens_est)}`
+              : `in ${formatInt(active.input_tokens_est)} · out ${formatInt(active.output_tokens_est)}`}
           </span>
         )}
       </div>

package/hooks/useSSE.ts

@@ -126,11 +126,21 @@ export function useSSE(onDone?: () => void) {
       if ((err as Error).name !== "AbortError") {
         setError(String(err));
       }
+      return { accepted: false };
+    } finally {
+      // Always release the gate when the stream ends — defends against the
+      // consume() loop returning without ever observing a terminal `done`
+      // event (e.g. the EventSource closed cleanly with zero events). If
+      // we relied solely on the `done` branch inside consume(), the chat
+      // would stay locked behind the Stop button forever.
+      //
+      // We intentionally do NOT clear streamingContent / thinkingContent
+      // here — the consumer (ChatView) swaps them for the persisted
+      // assistant bubble once the refetch lands; clearing now would yank
+      // the text out from under the user. The next start()/attach() resets
+      // them.
       setStreaming(false);
-      setStreamingContent("");
-      setThinkingContent("");
       closeActivity();
-      return { accepted: false };
     }
   }, [consume, openActivity, closeActivity]);
 
@@ -179,15 +189,18 @@ export function useSSE(onDone?: () => void) {
     try {
       await consume(subscribeRun(threadId, ctrl.signal));
     } catch (err) {
-      // Attach failures are non-fatal — clear the gate and let the consumer
-      // drain anything queued during session load. The common case is
-      // "no run to attach to" (server returns 404, EventSource fails to
-      // open) — completely normal when navigating into an idle session.
-      setStreaming(false);
-      closeActivity();
       if ((err as Error).name !== "AbortError") {
         onDone?.();
       }
+    } finally {
+      // Always release the optimistic gate when the stream ends — whether
+      // via terminal `done`/`error` event, a thrown failure, or a clean
+      // EventSource close with no events (idle thread, server returned 404
+      // so the iterator exited without yielding). Without this, navigating
+      // into an idle thread leaves streaming=true forever: the Stop button
+      // hangs in the composer and the "Reconnecting…" badge never clears.
+      setStreaming(false);
+      closeActivity();
     }
   }, [consume, onDone, openActivity, closeActivity]);
 

package/lib/agents/prepare/system-prompt.ts

@@ -10,6 +10,7 @@ import os from "node:os";
 import type { AgentConfigRow } from "@/lib/stores/agent-configs";
 import { getUserProfile } from "@/lib/stores/user-profile";
 import { listIntegrations } from "@/lib/stores/integrations";
+import { listEnabledDocumentSources, getDocumentSourceStats } from "@/lib/stores/document-sources";
 import { buildAdaptivePersonaContext } from "@/lib/agents/adaptive-persona";
 import { resolveHarness } from "@/lib/agents/harness/resolve";
 import {
@@ -49,6 +50,7 @@ export function buildSystemPrompt(ctx: SystemPromptContext): string {
     adaptivePersonaCtx,
     buildUserContext(),
     buildIntegrationsContext(),
+    buildDocumentsContext(),
     harnessParts.capabilities,
     harnessParts.plan_first,
     harnessParts.presentation,
@@ -203,3 +205,31 @@ function buildDelegatesContext(lines: string[]): string {
     ...lines,
   ].join("\n");
 }
+
+// Surface indexed Documents so the model knows the RAG corpus exists.
+// Without this nudge agents almost never call `documents_search` — they have
+// no signal that any local content is searchable. Gated on actually-indexed
+// chunks (not just configured sources) so an empty/erroring source doesn't
+// produce false advertising.
+function buildDocumentsContext(): string {
+  const sources = listEnabledDocumentSources();
+  if (sources.length === 0) return "";
+
+  let totalChunks = 0;
+  const lines: string[] = [];
+  for (const s of sources) {
+    const stats = getDocumentSourceStats(s.id);
+    if (stats.chunk_count === 0) continue;
+    totalChunks += stats.chunk_count;
+    const label = s.label ?? s.path;
+    lines.push(`- ${label} (${s.kind}, ${stats.chunk_count} chunks)`);
+  }
+  if (totalChunks === 0) return "";
+
+  return [
+    "--- Indexed documents ---",
+    `The user has ${totalChunks} indexed chunks across ${lines.length} document source(s) available to you:`,
+    ...lines,
+    "Call `documents_search` whenever the user asks about local files, notes, project docs, or any content that sounds like it lives in one of these sources. Prefer it over guessing from training data. Use `documents_list_sources` to enumerate, and pass `source_id` to scope a search.",
+  ].join("\n");
+}

package/lib/agents/run-registry.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { startRun, finishRun, getRun, broadcast } from "./run-registry";
+import type { StreamChunk } from "./base";
+
+const delta = (s: string): StreamChunk => ({ type: "text_delta", data: { delta: s } } as StreamChunk);
+
+describe("run-registry watchdog", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("force-evicts a leaked 'running' entry after JARELA_RUN_MAX_MS", () => {
+    const prev = process.env.JARELA_RUN_MAX_MS;
+    process.env.JARELA_RUN_MAX_MS = "60000";
+    try {
+      const tid = `t-leak-${Date.now()}`;
+      const run = startRun(tid, null);
+      expect(getRun(tid)).toBe(run);
+      expect(run.status).toBe("running");
+
+      // Driver never calls finishRun(). Without the watchdog the entry
+      // would sit as "running" forever, 409'ing every subsequent submit.
+      vi.advanceTimersByTime(60_000 + 10);
+
+      expect(run.status).toBe("error");
+      // Still in the map briefly (TTL-evicted 5 min after finishRun),
+      // but no longer blocks new runs because status is no longer "running".
+      const stillThere = getRun(tid);
+      expect(stillThere === null || stillThere.status === "error").toBe(true);
+
+      // A fresh startRun for the same thread must now succeed.
+      expect(() => startRun(tid, null)).not.toThrow();
+    } finally {
+      if (prev === undefined) delete process.env.JARELA_RUN_MAX_MS;
+      else process.env.JARELA_RUN_MAX_MS = prev;
+    }
+  });
+
+  it("does not clobber a run that finishes normally before the watchdog", () => {
+    const prev = process.env.JARELA_RUN_MAX_MS;
+    process.env.JARELA_RUN_MAX_MS = "60000";
+    try {
+      const tid = `t-ok-${Date.now()}`;
+      const run = startRun(tid, null);
+      finishRun(run, "done");
+      expect(run.status).toBe("done");
+      vi.advanceTimersByTime(60_000 + 10);
+      // Watchdog must not have flipped a "done" run to "error".
+      expect(run.status).toBe("done");
+    } finally {
+      if (prev === undefined) delete process.env.JARELA_RUN_MAX_MS;
+      else process.env.JARELA_RUN_MAX_MS = prev;
+    }
+  });
+
+  it("force-finishes a stalled run after JARELA_RUN_IDLE_MS of no progress", () => {
+    const prev = process.env.JARELA_RUN_IDLE_MS;
+    process.env.JARELA_RUN_IDLE_MS = "5000";
+    try {
+      const tid = `t-idle-${Date.now()}`;
+      const run = startRun(tid, null);
+      vi.advanceTimersByTime(5_000 + 10);
+      expect(run.status).toBe("error");
+    } finally {
+      if (prev === undefined) delete process.env.JARELA_RUN_IDLE_MS;
+      else process.env.JARELA_RUN_IDLE_MS = prev;
+    }
+  });
+
+  it("does not fire idle watchdog while broadcast keeps streaming", () => {
+    const prev = process.env.JARELA_RUN_IDLE_MS;
+    process.env.JARELA_RUN_IDLE_MS = "5000";
+    try {
+      const tid = `t-stream-${Date.now()}`;
+      const run = startRun(tid, null);
+      // Stream a chunk every 2s for 12s — total elapsed > idleMs but
+      // never idle for >5s in a row.
+      for (let i = 0; i < 6; i++) {
+        vi.advanceTimersByTime(2_000);
+        broadcast(run, delta("x"));
+      }
+      expect(run.status).toBe("running");
+      // Now go quiet and confirm it fires.
+      vi.advanceTimersByTime(5_000 + 10);
+      expect(run.status).toBe("error");
+    } finally {
+      if (prev === undefined) delete process.env.JARELA_RUN_IDLE_MS;
+      else process.env.JARELA_RUN_IDLE_MS = prev;
+    }
+  });
+});