feat(web): a dispatch timeline lens on the fleet rail

web/src/components/FleetRail.tsx

@@ -15,6 +15,7 @@ import { Component, For, Show, createMemo, createSignal, onCleanup, onMount } fr
 
 import { formatCostUsd, formatTokens } from "../lib/format";
 import { costShare, fleetEconomics, type FleetEconomics } from "../lib/fleet-economics";
+import { buildTimeline, groupByDay, type TimelineDay, type TimelineEntry, type TimelineKind } from "../lib/fleet-timeline";
 import {
   groupIntoLanes,
   needsYouCount,
@@ -83,6 +84,15 @@ const FleetRail: Component = () => {
   // ABOVE a single session). Collapsed by default — it answers a question you
   // ask occasionally, and the lanes answer the one you ask constantly.
   const [showSpend, setShowSpend] = createSignal(false);
+
+  // Which lens is showing. Lanes answer "what needs me now"; the timeline
+  // answers "what happened" (§4). They are different questions, and the second
+  // is badly served by a list that re-sorts itself by urgency.
+  const [lens, setLens] = createSignal<"lanes" | "timeline">("lanes");
+  const timeline = createMemo(() => {
+    const b = board();
+    return groupByDay(buildTimeline(b.tasks, b.events, (t) => taskSession(b, t)));
+  });
   const econ = createMemo<FleetEconomics>(() => {
     const b = board();
     return fleetEconomics(b.conductor ? [b.conductor, ...b.workers] : b.workers);
@@ -125,6 +135,10 @@ const FleetRail: Component = () => {
         <Show when={showSpend()}>
           <BackendSpendTable econ={econ()} />
         </Show>
+        <div class="flex items-center gap-0.5 pt-0.5" role="group" aria-label="Fleet lens">
+          <LensButton lens="lanes" label="Lanes" active={lens()} onPick={setLens} title="What needs you now, grouped by state" />
+          <LensButton lens="timeline" label="Timeline" active={lens()} onPick={setLens} title="What was dispatched when, and what came back" />
+        </div>
       </header>
 
       <Show when={board().error}>
@@ -135,22 +149,118 @@ const FleetRail: Component = () => {
         )}
       </Show>
 
-      <Show
-        when={lanes().length > 0}
-        fallback={
-          <p class="px-3 py-4 text-xs text-fg-faint">
-            {board().fetchedAt === 0
-              ? "Connecting to the board…"
-              : "Nothing dispatched yet. Ask the conductor to send or spawn work."}
-          </p>
-        }
-      >
-        <For each={lanes()}>{(lane) => <Lane group={lane} />}</For>
+      <Show when={lens() === "lanes"} fallback={<TimelineView days={timeline()} />}>
+        <Show
+          when={lanes().length > 0}
+          fallback={
+            <p class="px-3 py-4 text-xs text-fg-faint">
+              {board().fetchedAt === 0
+                ? "Connecting to the board…"
+                : "Nothing dispatched yet. Ask the conductor to send or spawn work."}
+            </p>
+          }
+        >
+          <For each={lanes()}>{(lane) => <Lane group={lane} />}</For>
+        </Show>
       </Show>
     </aside>
   );
 };
 
+const LensButton: Component<{
+  lens: "lanes" | "timeline";
+  label: string;
+  active: "lanes" | "timeline";
+  title: string;
+  onPick: (l: "lanes" | "timeline") => void;
+}> = (props) => (
+  <button
+    type="button"
+    onClick={() => props.onPick(props.lens)}
+    aria-pressed={props.active === props.lens}
+    title={props.title}
+    class={`rounded px-1.5 py-0.5 text-[10px] font-medium transition ${
+      props.active === props.lens
+        ? "bg-accent/15 text-accent"
+        : "text-fg-faint hover:text-fg-muted"
+    }`}
+  >
+    {props.label}
+  </button>
+);
+
+/**
+ * Colour by outcome, reusing the lane vocabulary so a `blocked` row reads the
+ * same in both lenses. A `dispatched` row is intentionally quiet: it is the
+ * question, not the answer, and colouring every request would leave nothing
+ * for the outcomes to stand out against.
+ */
+const TIMELINE_STYLE: Record<TimelineKind, string> = {
+  dispatched: "border-border bg-bg text-fg-muted",
+  done: "border-success/40 bg-success/10 text-success",
+  blocked: "border-danger/60 bg-danger/15 text-danger",
+  failed: "border-danger/40 bg-danger/10 text-danger",
+  event: "border-border bg-bg text-fg-faint",
+};
+
+/** What was dispatched when, and what came back (§4's retrospection lens). */
+const TimelineView: Component<{ days: TimelineDay[] }> = (props) => (
+  <Show
+    when={props.days.length > 0}
+    fallback={
+      <p class="px-3 py-4 text-xs text-fg-faint">
+        Nothing has been dispatched yet, so there is no history to replay.
+      </p>
+    }
+  >
+    <For each={props.days}>
+      {(day) => (
+        <section class="flex flex-col">
+          <h4 class="px-3 pb-1 pt-3 text-[10px] font-semibold uppercase tracking-wider text-fg-muted">
+            {new Date(day.day).toLocaleDateString(undefined, {
+              weekday: "short",
+              month: "short",
+              day: "numeric",
+            })}
+          </h4>
+          <ul class="flex flex-col">
+            <For each={day.entries}>{(e) => <TimelineRow entry={e} />}</For>
+          </ul>
+        </section>
+      )}
+    </For>
+  </Show>
+);
+
+const TimelineRow: Component<{ entry: TimelineEntry }> = (props) => (
+  <li class="flex flex-col gap-0.5 border-b border-border/40 px-3 py-1.5 last:border-b-0">
+    <div class="flex items-center gap-2 font-mono text-[10px]">
+      <span class="shrink-0 tabular-nums text-fg-faint">
+        {new Date(props.entry.at).toLocaleTimeString(undefined, {
+          hour: "2-digit",
+          minute: "2-digit",
+        })}
+      </span>
+      <span
+        class={`shrink-0 rounded border px-1 uppercase tracking-wider ${TIMELINE_STYLE[props.entry.kind]}`}
+      >
+        {props.entry.kind}
+      </span>
+      <span class="min-w-0 flex-1 truncate text-fg">{props.entry.label}</span>
+      {/* The task id is how a row is correlated by eye with fleet_tasks and
+          with an event whose task has aged off the board. */}
+      <span class="shrink-0 text-fg-faint" title={props.entry.taskId}>
+        {props.entry.taskId.slice(0, 8)}
+      </span>
+    </div>
+    <Show when={props.entry.detail}>
+      {(d) => (
+        <p class="line-clamp-2 pl-1 text-[11px] leading-snug text-fg-muted">{d()}</p>
+      )}
+    </Show>
+  </li>
+);
+
 /**
  * Per-backend spend — the metaharness view no single-vendor tool needs (§7).
  *

web/src/lib/fleet-timeline.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect } from "vitest";
+
+import { buildTimeline, groupByDay } from "./fleet-timeline";
+import type { FleetEventWire, FleetTaskWire, SessionInfo } from "../protocol/types";
+
+const T = 1_700_000_000_000;
+
+const task = (id: string, over: Partial<FleetTaskWire> = {}): FleetTaskWire => ({
+  id,
+  kind: "spawn",
+  shape: "scout",
+  status: "done",
+  attempts: 0,
+  createdAt: T,
+  createdBy: "conductor:acct/proj",
+  ...over,
+});
+
+const event = (id: number, over: Partial<FleetEventWire> = {}): FleetEventWire => ({
+  id,
+  taskId: "t1",
+  type: "task_done",
+  digest: "finished",
+  createdAt: T,
+  ...over,
+});
+
+describe("buildTimeline", () => {
+  it("interleaves dispatches and outcomes, newest first", () => {
+    const out = buildTimeline(
+      [task("t1", { createdAt: T }), task("t2", { createdAt: T + 2_000 })],
+      [event(1, { taskId: "t1", createdAt: T + 1_000 })],
+    );
+    expect(out.map((e) => e.key)).toEqual(["dispatch:t2", "event:1", "dispatch:t1"]);
+  });
+
+  it("keeps a dispatch reading as FIRST when it shares a millisecond with its outcome", () => {
+    // A fast task settles in the same tick it was dispatched. Newest-first
+    // means the dispatch must render SECOND, or the row order implies the
+    // result preceded the request.
+    const out = buildTimeline([task("t1")], [event(1, { taskId: "t1", createdAt: T })]);
+    expect(out.map((e) => e.kind)).toEqual(["done", "dispatched"]);
+  });
+
+  it("maps event types onto the timeline vocabulary", () => {
+    const out = buildTimeline(
+      [],
+      [
+        event(1, { type: "task_done" }),
+        event(2, { type: "task_blocked" }),
+        event(3, { type: "task_failed" }),
+      ],
+    );
+    expect(out.map((e) => e.kind).sort()).toEqual(["blocked", "done", "failed"]);
+  });
+
+  it("keeps an event type it has never heard of rather than dropping history", () => {
+    // A newer daemon naming something differently must not silently erase rows
+    // from a retrospective view.
+    const out = buildTimeline([], [event(1, { type: "task_reassigned" })]);
+    expect(out).toHaveLength(1);
+    expect(out[0]!.kind).toBe("event");
+    expect(out[0]!.label).toBe("task_reassigned");
+  });
+
+  it("keeps an event whose task has aged off the capped board", () => {
+    // The board is bounded; a long fleet run ages tasks out while their events
+    // remain, and the digest is the most useful thing left.
+    const out = buildTimeline([], [event(1, { taskId: "long-gone", digest: "the answer" })]);
+    expect(out[0]!.taskId).toBe("long-gone");
+    expect(out[0]!.detail).toBe("the answer");
+  });
+
+  it("labels a dispatch with its target so rows are distinguishable", () => {
+    const named = { id: "w9", name: "worker-scout-abc" } as SessionInfo;
+    const spawn = buildTimeline([task("t1", { workerSessionId: "w9" })], [], () => named);
+    expect(spawn[0]!.label).toBe("spawn scout");
+    // The NAME, not the id — a raw UUID is noise in a narrow rail.
+    expect(spawn[0]!.detail).toBe("worker-scout-abc");
+  });
+
+  it("degrades an unresolvable target to a short id, not a full UUID", () => {
+    // A finished task has no session at all: the dispatcher tears its worker
+    // down after the digest. The id prefix still correlates by eye.
+    const out = buildTimeline(
+      [task("t1", { workerSessionId: "7bdbd557-656a-4b0c-bab1-6a7894ab3efe" })],
+      [],
+    );
+    expect(out[0]!.detail).toBe("7bdbd557");
+  });
+
+  it("leaves the detail null when a dispatch has no target yet", () => {
+    // A queued spawn has neither a worker nor a target; inventing one would be
+    // worse than an empty cell.
+    expect(buildTimeline([task("t1")], [])[0]!.detail).toBeNull();
+  });
+
+  it("orders equal rows totally and stably", () => {
+    const a = buildTimeline([task("aaa"), task("bbb")], []);
+    const b = buildTimeline([task("bbb"), task("aaa")], []);
+    expect(a.map((e) => e.key)).toEqual(b.map((e) => e.key));
+  });
+
+  it("returns nothing for an empty board", () => {
+    expect(buildTimeline([], [])).toEqual([]);
+  });
+});
+
+describe("groupByDay", () => {
+  it("splits on LOCAL midnight, not UTC", () => {
+    // A UTC split puts an evening dispatch on "tomorrow" for anyone east of the
+    // meridian — the user is reading their own day boundaries.
+    const late = new Date(2026, 4, 10, 23, 30).getTime();
+    const next = new Date(2026, 4, 11, 0, 30).getTime();
+    const days = groupByDay(buildTimeline([task("a", { createdAt: next }), task("b", { createdAt: late })], []));
+    expect(days).toHaveLength(2);
+    expect(days[0]!.day).toBe(new Date(2026, 4, 11).getTime());
+    expect(days[1]!.day).toBe(new Date(2026, 4, 10).getTime());
+  });
+
+  it("keeps same-day entries together in order", () => {
+    const days = groupByDay(
+      buildTimeline([task("a", { createdAt: T }), task("b", { createdAt: T + 1_000 })], []),
+    );
+    expect(days).toHaveLength(1);
+    expect(days[0]!.entries.map((e) => e.key)).toEqual(["dispatch:b", "dispatch:a"]);
+  });
+
+  it("returns nothing for an empty timeline", () => {
+    expect(groupByDay([])).toEqual([]);
+  });
+});