@dxos/plugin-assistant 0.10.0 → 0.11.0

package/src/containers/SpaceHomeSuggestions/SpaceHomeSuggestions.tsx

@@ -4,7 +4,7 @@
 
 import React, { useCallback } from 'react';
 
-import { useOperationInvoker } from '@dxos/app-framework/ui';
+import { HomeSection, useOperationInvoker } from '@dxos/app-framework/ui';
 import { RoutineOperation } from '@dxos/plugin-routine/types';
 import { type Space } from '@dxos/react-client/echo';
 import { Card, IconButton, useTranslation } from '@dxos/react-ui';
@@ -14,6 +14,7 @@ import { meta } from '#meta';
 
 type SpaceScopedProps = {
   space?: Space;
+  onClose?: () => void;
 };
 
 /**
@@ -21,7 +22,7 @@ type SpaceScopedProps = {
  * assistant operation. Always renders (below the recent-objects masonry) so the Home page offers
  * quick entry points regardless of whether recent objects exist.
  */
-export const SpaceHomeSuggestions = ({ space }: SpaceScopedProps) => {
+export const SpaceHomeSuggestions = ({ space, onClose }: SpaceScopedProps) => {
   const { t } = useTranslation(meta.profile.key);
   const { invokePromise } = useOperationInvoker();
   const suggestions = useHomeSuggestions(space);
@@ -41,43 +42,43 @@ export const SpaceHomeSuggestions = ({ space }: SpaceScopedProps) => {
   }
 
   return (
-    <div className='flex justify-center w-full'>
-      <div className='flex flex-col gap-trim-sm w-full max-w-[40rem]'>
-        <h2 className='text-sm font-medium text-description'>{t('space-home.suggestions.heading')}</h2>
-        <div className='flex flex-col gap-3'>
-          {suggestions.map((prompt, index) => (
-            <div
-              key={`${index}:${prompt}`}
-              role='button'
-              tabIndex={0}
-              className='cursor-pointer w-full'
-              onClick={() => handleRunPrompt(prompt)}
-              onKeyDown={(e) => {
-                if (e.key === 'Enter' || e.key === ' ') {
-                  e.preventDefault();
-                  handleRunPrompt(prompt);
-                }
-              }}
-            >
-              <Card.Root fullWidth>
-                <Card.Header>
-                  <Card.Block>
-                    <IconButton
-                      variant='ghost'
-                      label={prompt}
-                      icon='ph--sparkle--regular'
-                      iconOnly
-                      tabIndex={-1}
-                      aria-hidden
-                    />
-                  </Card.Block>
-                  <Card.Title>{prompt}</Card.Title>
-                </Card.Header>
-              </Card.Root>
-            </div>
-          ))}
-        </div>
+    <HomeSection.Root>
+      <HomeSection.Header title={t('space-home.suggestions.heading')} onClose={onClose} />
+      <div className='flex flex-col gap-3'>
+        {suggestions.map((prompt, index) => (
+          <div
+            key={`${index}:${prompt}`}
+            role='button'
+            tabIndex={0}
+            className='cursor-pointer w-full'
+            onClick={() => handleRunPrompt(prompt)}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter' || e.key === ' ') {
+                e.preventDefault();
+                handleRunPrompt(prompt);
+              }
+            }}
+          >
+            <Card.Root fullWidth>
+              <Card.Header>
+                <Card.Block>
+                  <IconButton
+                    variant='ghost'
+                    label={prompt}
+                    icon='ph--sparkle--regular'
+                    iconOnly
+                    tabIndex={-1}
+                    aria-hidden
+                  />
+                </Card.Block>
+                <Card.Title>{prompt}</Card.Title>
+              </Card.Header>
+            </Card.Root>
+          </div>
+        ))}
       </div>
-    </div>
+    </HomeSection.Root>
   );
 };
+
+SpaceHomeSuggestions.displayName = 'SpaceHomeSuggestions';

package/src/containers/TracePanel/TracePanel.stories.tsx

@@ -8,17 +8,19 @@ import React, { PropsWithChildren, type ReactNode, useCallback, useEffect, useMe
 
 import { withPluginManager } from '@dxos/app-framework/testing';
 import { useProcessManagerRuntime } from '@dxos/app-framework/ui';
+import { AppActivationEvents } from '@dxos/app-toolkit';
 import { addEventListener } from '@dxos/async';
 import { Process, Trace } from '@dxos/compute';
 import { ProcessManager } from '@dxos/compute-runtime';
+import { FeedTraceSink } from '@dxos/compute-runtime';
 import { Feed, Filter, Query } from '@dxos/echo';
-import { FeedTraceSink } from '@dxos/functions-runtime';
+import { useQuery } from '@dxos/echo-react';
 import { log } from '@dxos/log';
 import { ClientPlugin } from '@dxos/plugin-client/testing';
 import { initializeIdentity } from '@dxos/plugin-client/testing';
 import { RoutinePlugin } from '@dxos/plugin-routine/testing';
 import { corePlugins } from '@dxos/plugin-testing';
-import { useQuery, useSpaces } from '@dxos/react-client/echo';
+import { useSpaces } from '@dxos/react-client/echo';
 import { IconButton, Panel, ScrollContainer, Toolbar } from '@dxos/react-ui';
 import { type Commit, Timeline } from '@dxos/react-ui-components';
 import { Syntax } from '@dxos/react-ui-syntax-highlighter';
@@ -56,7 +58,7 @@ const JsonInspectorPanel = ({ data }: { data: unknown }) => (
           <Syntax.Root data={data}>
             <Syntax.Content>
               <Syntax.Viewport>
-                <Syntax.Code className='text-xs' />
+                <Syntax.Code classNames='text-xs' />
               </Syntax.Viewport>
             </Syntax.Content>
           </Syntax.Root>
@@ -262,7 +264,7 @@ const TimelinePlayback = ({
           />
           <IconButton iconOnly icon='ph--caret-right--regular' label='Step forward (→ / L)' onClick={handleNext} />
           <IconButton iconOnly icon='ph--skip-forward--regular' label='Show all (E / End)' onClick={handleShowAll} />
-          <Toolbar.Text className='text-right text-sm tabular-nums opacity-70'>
+          <Toolbar.Text classNames='text-right text-sm tabular-nums opacity-70'>
             {step} / {total}
           </Toolbar.Text>
         </Toolbar.Root>
@@ -307,6 +309,9 @@ export const Default: Story = {
     withTheme(),
     withLayout({ layout: 'column', classNames: 'w-(--dx-complementary-sidebar-size) overflow-hidden' }),
     withPluginManager({
+      // Fire SetupSettings so the assistant settings module activates and contributes
+      // `AssistantCapabilities.Settings`, which `TracePanel` reads via `useAtomCapability`.
+      setupEvents: [AppActivationEvents.SetupSettings],
       plugins: [
         ...corePlugins(),
         ClientPlugin({

package/src/containers/TracePanel/TracePanel.tsx

@@ -105,7 +105,7 @@ export const TracePanel = composable<HTMLDivElement, TracePanelProps>(
         {...composableProps(props, {
           ...attentionAttrs,
           classNames: mx(
-            'h-full grid divide-y divide-separator',
+            'h-full grid divide-y divide-subdued-separator',
             !tracePanelDebug && selectedCommit
               ? 'grid-rows-[minmax(0,160px)_1fr_minmax(0,206px)]'
               : 'grid-rows-[minmax(0,160px)_1fr]',
@@ -123,7 +123,7 @@ export const TracePanel = composable<HTMLDivElement, TracePanelProps>(
                 <Syntax.Root data={spanTree}>
                   <Syntax.Content>
                     <Syntax.Viewport>
-                      <Syntax.Code className='text-xs' />
+                      <Syntax.Code classNames='text-xs' />
                     </Syntax.Viewport>
                   </Syntax.Content>
                 </Syntax.Root>
@@ -145,7 +145,7 @@ export const TracePanel = composable<HTMLDivElement, TracePanelProps>(
           <Syntax.Root data={details[selectedCommit.id] ?? selectedCommit}>
             <Syntax.Content>
               <Syntax.Viewport>
-                <Syntax.Code className='text-xs' />
+                <Syntax.Code classNames='text-xs' />
               </Syntax.Viewport>
             </Syntax.Content>
           </Syntax.Root>
@@ -158,6 +158,11 @@ export const TracePanel = composable<HTMLDivElement, TracePanelProps>(
 // Stable ref.
 const atomEmpty = Atom.make(() => [] as const);
 
+// How often the graph re-checks for spans that timed out with no closing event.
+// Coarse-grained on purpose: `spanTimeoutMs` operates on a 20-minute scale, so there is no
+// benefit to re-deriving the graph more often than this just to catch the timeout crossing.
+const SPAN_TIMEOUT_CHECK_INTERVAL_MS = 60_000;
+
 type UseExecutionGraphOptions = {
   collapseCompletedSpans?: boolean;
   eventLimit?: number;
@@ -170,9 +175,19 @@ const useExecutionGraph = (
   const monitor = useCapability(Capabilities.ProcessMonitor);
   const processesAtom = monitor?.processTreeAtom ?? atomEmpty;
 
+  // Ticks periodically so spans that are still open purely because no new trace event has
+  // arrived (e.g. the runtime crashed before writing its `operationEnd`) eventually get
+  // force-closed by `buildExecutionGraph`'s `spanTimeoutMs` check, instead of staying stuck
+  // until unrelated trace activity happens to trigger a recompute.
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    const id = setInterval(() => setNow(Date.now()), SPAN_TIMEOUT_CHECK_INTERVAL_MS);
+    return () => clearInterval(id);
+  }, []);
+
   const atom = useMemo(
-    () => getExecutionGraph(space, processesAtom, { collapseCompletedSpans, eventLimit }),
-    [space, processesAtom, collapseCompletedSpans, eventLimit],
+    () => getExecutionGraph(space, processesAtom, { collapseCompletedSpans, eventLimit, now }),
+    [space, processesAtom, collapseCompletedSpans, eventLimit, now],
   );
 
   return useAtomValue(atom);
@@ -181,7 +196,7 @@ const useExecutionGraph = (
 const getExecutionGraph = (
   space: Space,
   processesAtom: Atom.Atom<readonly Process.Info[]>,
-  { collapseCompletedSpans = true, eventLimit = 100 }: UseExecutionGraphOptions = {},
+  { collapseCompletedSpans = true, eventLimit = 100, now }: UseExecutionGraphOptions & { now: number },
 ): Atom.Atom<ExecutionGraph> => {
   const traceMessages = getTraceMessagesAtom(space);
 
@@ -204,6 +219,7 @@ const getExecutionGraph = (
       activeProcesses: get(activeProcesses),
       collapseCompletedSpans,
       eventLimit,
+      now,
     }),
   );
 };

package/src/containers/TriggerStatus/TriggerStatus.tsx

@@ -5,16 +5,14 @@
 import React, { useMemo } from 'react';
 
 import { AppSurface } from '@dxos/app-toolkit/ui';
-import { type InvocationsState } from '@dxos/functions-runtime';
+import { type InvocationsState } from '@dxos/compute-runtime';
 import { useTriggerRuntimeControls } from '@dxos/plugin-routine/hooks';
 import { StatusBar } from '@dxos/plugin-status-bar/components';
-import { useMulticastObservable } from '@dxos/react-client';
-import { SpaceState, useObject } from '@dxos/react-client/echo';
 import { IconButton, Popover, useTranslation } from '@dxos/react-ui';
 
 import { meta } from '#meta';
 
-type TriggerStatusState = 'disabled' | 'idle' | 'running' | 'edge' | 'error';
+type TriggerStatusState = 'disabled' | 'idle' | 'running' | 'error';
 
 const getIcon = (state: TriggerStatusState): string => {
   switch (state) {
@@ -22,8 +20,6 @@ const getIcon = (state: TriggerStatusState): string => {
       return 'ph--lightning-slash--regular';
     case 'idle':
       return 'ph--lightning--regular';
-    case 'edge':
-      return 'ph--lightning--regular';
     case 'running':
       return 'ph--lightning--fill';
     case 'error':
@@ -47,19 +43,12 @@ export type SpaceStatusProps = AppSurface.SpaceArticleProps;
 export const SpaceStatus = ({ space }: SpaceStatusProps) => {
   const { t } = useTranslation(meta.profile.key);
   const { state } = useTriggerRuntimeControls(space.db);
+  // The dispatcher is stopped for the space when `triggersDisabled` is set, so `enabled` already
+  // reflects the space-wide kill-switch; per-trigger edge routing does not affect this indicator.
   const isEnabled = state?.enabled ?? false;
-  // `space.properties` throws until the space finishes initializing (e.g. right after joining);
-  // gate on `space.state` so this component doesn't crash for a freshly-joined space.
-  const spaceState = useMulticastObservable(space.state);
-  const [properties] = useObject(spaceState === SpaceState.SPACE_READY ? space.properties : undefined);
-  const computeEnvironment = properties?.computeEnvironment ?? 'local';
 
   // Determine the current trigger status state.
   const triggerState: TriggerStatusState = useMemo(() => {
-    if (computeEnvironment === 'edge') {
-      return 'edge';
-    }
-
     if (!isEnabled) {
       return 'disabled';
     }
@@ -77,7 +66,7 @@ export const SpaceStatus = ({ space }: SpaceStatusProps) => {
     }
 
     return 'idle';
-  }, [computeEnvironment, isEnabled, state?.invocations]);
+  }, [isEnabled, state?.invocations]);
 
   return (
     <Popover.Root>
@@ -132,3 +121,7 @@ const TriggerStatusPopover = ({
     </div>
   );
 };
+
+SpaceStatus.displayName = 'SpaceStatus';
+
+TriggerStatusPopover.displayName = 'TriggerStatusPopover';

package/src/containers/index.ts

@@ -11,7 +11,6 @@ export const ChatCompanion: ComponentType<any> = lazy(() => import('./ChatCompan
 export const ChatArticle: ComponentType<any> = lazy(() => import('./ChatArticle'));
 export const ChatDialog: ComponentType<any> = lazy(() => import('./ChatDialog'));
 export const IntegrationPrompt: ComponentType<any> = lazy(() => import('./IntegrationPrompt'));
-export const PlanArticle: ComponentType<any> = lazy(() => import('./PlanArticle'));
 export const SpaceHomePrompt: ComponentType<any> = lazy(() => import('./SpaceHomePrompt'));
 export const SpaceHomeSuggestions: ComponentType<any> = lazy(() => import('./SpaceHomeSuggestions'));
 export const TracePanel: ComponentType<any> = lazy(() => import('./TracePanel'));

package/src/execution-graph/SPEC.md

@@ -25,7 +25,8 @@ Out of scope:
 - Filtering / search of commits.
 - Mutating, ack-ing, or replaying trace events.
 
-Inputs: `traceMessages: Trace.Message[]`, `activeProcesses?: Process.Info[]`, `eventLimit?: number`.
+Inputs: `traceMessages: Trace.Message[]`, `activeProcesses?: Process.Info[]`, `eventLimit?: number`,
+`spanTimeoutMs?: number`, `now?: number`.
 Output: `ExecutionGraph = { branches, commits, spanTree, details }`.
 
 ## 2. Inputs
@@ -77,6 +78,8 @@ Optional input via `activeProcesses` (defaults to `[]`). Fields the builder read
 - `TracePanel`'s `getExecutionGraph` defaults `eventLimit = 300`
   (`TracePanel.tsx#L153`).
 - The cap targets `Timeline` rendering cost, not memory; see §11 for what it bounds.
+- `buildSpanTree` defaults `spanTimeoutMs = DEFAULT_SPAN_TIMEOUT_MS` (20 minutes); `now` has
+  no default and force-closing is skipped unless a caller passes it. See §5.4.
 
 ## 3. Outputs
 
@@ -227,6 +230,48 @@ retains span boundaries') and `#L159` (regression for parent-child preservation)
 Sibling spans are sorted by `firstTimestamp` ascending so output is deterministic
 across runs that share inputs. Test: `span-tree.test.ts#L120`.
 
+### 5.4 Timeout-based force-close
+
+Runs after the linear scan, before children are sorted, over `allSpans` — every span ever
+opened, not just the ones still in `openSpans`. This matters because a span superseded by a
+later same-pid begin event (§15 "interleaved same-pid begin/end pairs") is removed from
+`openSpans` but never receives an end event either; walking `allSpans` and checking each
+span's own last event (rather than map membership) reaches it too.
+
+Skipped entirely when `options.now` is omitted (see below). Otherwise, any span whose **last**
+event is not itself an end event (`isSpanEndEvent`) and is older than `now - spanTimeoutMs` is
+force-closed with a synthetic end event appended to `span.events`:
+
+- Span opened by `AgentRequestBegin` → synthetic `AgentRequestEnd` with
+  `{ status: 'interrupted', error: SPAN_TIMEOUT_MESSAGE }`.
+- Span opened by `Trace.OperationStart` → synthetic `Trace.OperationEnd` with
+  `{ key, name, icon, outcome: 'failure', error: SPAN_TIMEOUT_MESSAGE }` (fields copied
+  from the begin event's payload).
+
+The synthetic event's `timestamp` is `lastEvent.timestamp + spanTimeoutMs` (the exact
+moment the span crossed the threshold), not `now` — this keeps the emitted commit's
+position stable across repeated `buildSpanTree` calls with an advancing `now`, rather
+than jumping forward on every recompute.
+
+Rationale: the runtime may fail to write the closing event (crash, dropped connection,
+process killed) — see DX-1080. Without this, `isCompletedSpan` never returns `true` for
+that span (§7), so it never collapses and keeps rendering with the "in progress" shimmer
+forever. Appending a synthetic end event makes it indistinguishable downstream from a
+span that completed normally, except for the `outcome: 'failure'` / `status: 'interrupted'`
+result and the `SPAN_TIMEOUT_MESSAGE` text surfaced by `presentEvent` (§4.1).
+
+`spanTimeoutMs` defaults to `DEFAULT_SPAN_TIMEOUT_MS` (20 minutes) when `now` is provided.
+`now` has **no default** — force-closing only runs when a caller explicitly passes it, so
+deterministic callers (tests, `TracePanel.stories.tsx`'s fixture snapshot) that pass fixture
+timestamps unrelated to wall-clock time are unaffected unless they opt in. `TracePanel` opts
+in by ticking a `now` state every 60s (`TracePanel.tsx`); `span-tree.test.ts`'s "force-closed"
+tests pass an explicit `now` for determinism.
+
+Only spans with **zero** events never happen (a span always has at least its begin
+event), so `span.events[span.events.length - 1]` is always defined when force-closing.
+Nested children of a force-closed span are evaluated independently — a still-active
+child is not force-closed just because its parent timed out.
+
 ## 6. Span branch assignment (`branchOf`)
 
 `execution-graph.ts#L263`. Pure function on a span:
@@ -582,6 +627,16 @@ Each entry: **scenario → expected output → rationale**.
     - Logged via `log('invalid trace event', …)` and dropped. The event still
       occupies a position in `spanTree.events`.
 
+18. **Span open longer than `spanTimeoutMs` with no end event** (DX-1080)
+    - Force-closed with a synthetic failure/interrupted end event (§5.4); becomes
+      `isCompletedSpan` and collapses/renders like a normal completed span instead of
+      hanging with the shimmer effect forever. Test: `span-tree.test.ts`
+      ("an open operation span past the timeout is force-closed…").
+
+19. **Span open but still within `spanTimeoutMs`**
+    - Left untouched — stays open and continues to render as in-progress. Test:
+      `span-tree.test.ts` ("an open span within the timeout window stays open").
+
 ## 14. Performance & complexity
 
 - `buildSpanTree`: O(E log E) for the chronological sort, O(E) for the linear
@@ -605,7 +660,9 @@ Each entry: **scenario → expected output → rationale**.
   spans per pid. If a process emits `B1 B2 E1 E2` interleaved, the second `B2`
   orphans the still-open `B1` (no `E1` ever closes the first span). The first
   span receives only its begin event; the second receives `B2 E1 E2`.
-  Outcome: incorrect. Not currently supported.
+  Outcome: incorrect. Not currently supported. `B1` is at least reachable by the
+  §5.4 timeout sweep (via `allSpans`) so it eventually force-closes rather than
+  hanging forever — but the interleaving itself is still not modeled correctly.
 - **Event types beyond `presentEvent`**: silently dropped from the commit
   stream but retained in `spanTree.events`. Consumers wanting the full event
   stream must read `spanTree`. Examples: `OperationInput`, `OperationOutput`,
@@ -625,6 +682,7 @@ Each entry: **scenario → expected output → rationale**.
 | ------------------------------------------------------- | ---------------------------------------------------------------------------- | ----------- |
 | `buildSpanTree`                                         | `packages/plugins/plugin-assistant/src/execution-graph/span-tree.ts`         | L112        |
 | `applyEventLimit`                                       | same                                                                         | L211        |
+| `makeTimeoutEndEvent` / `DEFAULT_SPAN_TIMEOUT_MS`       | same                                                                         | L252 / L13  |
 | `ROOT_SPAN_ID`                                          | same                                                                         | L12         |
 | `BEGIN_EVENT_TYPES`/`END_EVENT_TYPES`                   | same                                                                         | L47         |
 | `walkSpanTree`/`flattenSpanTree`                        | same                                                                         | L245        |

package/src/execution-graph/execution-graph.ts

@@ -10,10 +10,10 @@ import * as Pipeable from 'effect/Pipeable';
 import * as Schema from 'effect/Schema';
 import * as Struct from 'effect/Struct';
 
+import { AGENT_PROCESS_KEY } from '@dxos/agent-runtime';
 import { AgentRequestBegin, AgentRequestEnd, CompleteBlock } from '@dxos/assistant';
 import { Process, Trace } from '@dxos/compute';
 import { Annotation } from '@dxos/echo';
-import { AGENT_PROCESS_KEY } from '@dxos/functions-runtime';
 import { EID } from '@dxos/keys';
 import { LogLevel, log } from '@dxos/log';
 import { type Commit } from '@dxos/react-ui-components';
@@ -93,6 +93,17 @@ export interface BuildExecutionGraphParams {
   activeProcesses?: readonly Process.Info[];
   collapseCompletedSpans?: boolean;
   eventLimit?: number;
+  /**
+   * Duration a span may sit open with no new events before it's force-closed with a synthetic
+   * end event. Only takes effect when `now` is also provided. Defaults to
+   * `DEFAULT_SPAN_TIMEOUT_MS`.
+   */
+  spanTimeoutMs?: number;
+  /**
+   * Reference time used to detect abandoned spans. Force-closing is skipped entirely when this
+   * is omitted.
+   */
+  now?: number;
 }
 
 /**
@@ -121,8 +132,10 @@ export const buildExecutionGraph = ({
   activeProcesses = [],
   collapseCompletedSpans = false,
   eventLimit = 500,
+  spanTimeoutMs,
+  now,
 }: BuildExecutionGraphParams): ExecutionGraph => {
-  const spanTree = buildSpanTree(traceMessages, { eventLimit });
+  const spanTree = buildSpanTree(traceMessages, { eventLimit, spanTimeoutMs, now });
   const toolCallContext = buildToolCallContext(traceMessages);
   const built = spanTreeToCommits(spanTree, activeProcesses, toolCallContext, collapseCompletedSpans);
   log('trace execution graph', {

package/src/execution-graph/index.ts

@@ -22,6 +22,7 @@ export {
 export {
   BEGIN_EVENT_TYPES,
   type BuildSpanTreeOptions,
+  DEFAULT_SPAN_TIMEOUT_MS,
   END_EVENT_TYPES,
   ROOT_SPAN_ID,
   type Span,

package/src/execution-graph/pending-block-status.ts

@@ -60,11 +60,12 @@ export const pendingStatusFromEphemeralMessage = (message: Trace.Message): strin
     }
 
     if (Trace.isOfType(Trace.StatusUpdate, event)) {
+      const message = event.data.message?.trim();
       // Suppress opaque routine ULID lines so descriptive partial-block / operation-input lines win.
-      if (ROUTINE_ULID_STATUS.test(event.data.message.trim())) {
+      if (!message || ROUTINE_ULID_STATUS.test(message)) {
         continue;
       }
-      return event.data.message;
+      return message;
     }
   }
   return undefined;

package/src/execution-graph/span-tree.test.ts

@@ -9,7 +9,13 @@ import { describe, test } from 'vitest';
 import { AgentRequestBegin, AgentRequestEnd } from '@dxos/assistant';
 import { Trace } from '@dxos/compute';
 
-import { ROOT_SPAN_ID, buildSpanTree, collectSpanTreeEventsCategorically, flattenSpanTree } from './span-tree';
+import {
+  DEFAULT_SPAN_TIMEOUT_MS,
+  ROOT_SPAN_ID,
+  buildSpanTree,
+  collectSpanTreeEventsCategorically,
+  flattenSpanTree,
+} from './span-tree';
 import { collectTraceEvents, withMeta } from './testing';
 
 const NoteEvent = Trace.EventType('note', {
@@ -247,6 +253,86 @@ describe('buildSpanTree', () => {
     expect(order).toHaveLength(3);
   });
 
+  test('an open operation span past the timeout is force-closed with a synthetic failure end', ({ expect }) => {
+    const messages = collectTraceEvents(
+      withMeta({ pid: 'op-1' }, Trace.write(Trace.OperationStart, { key: 'reply', name: 'Reply' })),
+    );
+    // The single event lands at timestamp 1; `now` is well past the default timeout.
+    const tree = buildSpanTree(messages, { now: 1 + DEFAULT_SPAN_TIMEOUT_MS });
+    expect(tree.children).toHaveLength(1);
+    const span = tree.children[0];
+    expect(span.events).toHaveLength(2);
+    expect(span.events[1].type).toBe(Trace.OperationEnd.key);
+    expect(span.events[1].data).toMatchObject({ key: 'reply', name: 'Reply', outcome: 'failure' });
+  });
+
+  test('an open agent request span past the timeout is force-closed as interrupted', ({ expect }) => {
+    const messages = collectTraceEvents(withMeta({ pid: 'agent-1' }, Trace.write(AgentRequestBegin, {})));
+    const tree = buildSpanTree(messages, { now: 1 + DEFAULT_SPAN_TIMEOUT_MS });
+    const span = tree.children[0];
+    expect(span.events).toHaveLength(2);
+    expect(span.events[1].type).toBe(AgentRequestEnd.key);
+    expect(span.events[1].data).toMatchObject({ status: 'interrupted' });
+  });
+
+  test('an open span within the timeout window stays open', ({ expect }) => {
+    const messages = collectTraceEvents(
+      withMeta({ pid: 'op-1' }, Trace.write(Trace.OperationStart, { key: 'reply', name: 'Reply' })),
+    );
+    const tree = buildSpanTree(messages, { now: 1 + DEFAULT_SPAN_TIMEOUT_MS - 1 });
+    const span = tree.children[0];
+    expect(span.events).toHaveLength(1);
+  });
+
+  test('spanTimeoutMs is configurable', ({ expect }) => {
+    const messages = collectTraceEvents(
+      withMeta({ pid: 'op-1' }, Trace.write(Trace.OperationStart, { key: 'reply', name: 'Reply' })),
+    );
+    const closed = buildSpanTree(messages, { now: 100, spanTimeoutMs: 10 });
+    expect(closed.children[0].events).toHaveLength(2);
+
+    const stillOpen = buildSpanTree(messages, { now: 100, spanTimeoutMs: 1_000 });
+    expect(stillOpen.children[0].events).toHaveLength(1);
+  });
+
+  test('a span superseded by a later same-pid begin event is force-closed too', ({ expect }) => {
+    // The first begin never gets an end (interleaved B1 B2 E1 pattern, §15) — `openSpans` only
+    // tracks the second span once it supersedes the first, so the sweep must reach both.
+    const messages = collectTraceEvents(
+      withMeta(
+        { pid: 'agent-1' },
+        Effect.gen(function* () {
+          yield* Trace.write(AgentRequestBegin, {});
+          yield* Trace.write(AgentRequestBegin, {});
+          yield* Trace.write(AgentRequestEnd, { status: 'success' });
+        }),
+      ),
+    );
+    const tree = buildSpanTree(messages, { now: 1 + DEFAULT_SPAN_TIMEOUT_MS });
+    expect(tree.children).toHaveLength(2);
+    const [superseded, current] = tree.children;
+    expect(superseded.events).toHaveLength(2);
+    expect(superseded.events[1].type).toBe(AgentRequestEnd.key);
+    expect(superseded.events[1].data).toMatchObject({ status: 'interrupted' });
+    expect(current.events).toHaveLength(2);
+    expect(current.events[1].data).toMatchObject({ status: 'success' });
+  });
+
+  test('a completed span is unaffected by the timeout', ({ expect }) => {
+    const messages = collectTraceEvents(
+      withMeta(
+        { pid: 'op-1' },
+        Effect.gen(function* () {
+          yield* Trace.write(Trace.OperationStart, { key: 'reply', name: 'Reply' });
+          yield* Trace.write(Trace.OperationEnd, { key: 'reply', name: 'Reply', outcome: 'success' });
+        }),
+      ),
+    );
+    const tree = buildSpanTree(messages, { now: 1 + DEFAULT_SPAN_TIMEOUT_MS });
+    expect(tree.children[0].events).toHaveLength(2);
+    expect(tree.children[0].events[1].data).toMatchObject({ outcome: 'success' });
+  });
+
   test('collectSpanTreeEventsCategorically emits begin, child subtrees, then remaining events', ({ expect }) => {
     const messages = collectTraceEvents(
       Effect.gen(function* () {