@spunto/design-system 0.26.0 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/design-system",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",

package/src/components/workers/index.ts

@@ -27,6 +27,9 @@ export type { SetupProgressProps, StepState } from "./setup-progress"
 export { WorkerSetupTimeline } from "./worker-setup-timeline"
 export { SetupWaterfall } from "./setup-waterfall"
 
+export { WorkerStatusHistory, statusHistorySpans } from "./worker-status-history"
+export type { WorkerStatusHistoryProps, WorkerStatusSpan } from "./worker-status-history"
+
 export { ResourceBars } from "./resource-bars"
 export type { ResourceBarsProps, WorkerStats } from "./resource-bars"
 
@@ -40,8 +43,8 @@ export type { TagPalette } from "./tag-color"
 
 export { CreatorAvatar } from "./creator-avatar"
 
-export type { WorkerCardWorker, WorkerCockpitWorker, WorkerCreator, WorkerSetupStatus } from "./types"
+export type { WorkerCardWorker, WorkerCockpitWorker, WorkerCreator, WorkerSetupStatus, WorkerStatusEvent } from "./types"
 
 // Re-exported here too so a consumer of the worker surface doesn't have to
 // import the root entry just to format the timestamps it feeds these components.
-export { cn, formatDuration, formatRelativeTime } from "../../utils"
+export { cn, formatDuration, formatElapsed, formatRelativeTime } from "../../utils"

package/src/components/workers/types.ts

@@ -26,8 +26,23 @@ export interface WorkerCardWorker {
   name?: string | null
   /** Fallback identity when `name` is empty — renders as "Workspace #3". */
   index?: number | null
-  /** Lifecycle state: `provisioning` | `building` | `pulling` | `starting` | `setup` | `ready` | `stopping` | `stopped` | `deleting` | `error`. */
+  /** Lifecycle state: `provisioning` | `building` | `pulling` | `starting` | `setup` | `ready` | `stopping` | `stopped` | `deleting` | `exited` | `unknown` | `error`. */
   state?: string | null
+  /**
+   * Why the worker is in that state, when there is a why: an exit code, a reason, and the status
+   * it came from. Read laxly on purpose — every field optional, an unrecognised `reason` yields no
+   * detail instead of an invented one. The strict version of this shape lives in
+   * `@spunto/build` (`WorkerStatusMeta`), which is where a control plane *writing* it should look.
+   */
+  statusMeta?: {
+    reason?: string | null
+    message?: string | null
+    exitCode?: number | null
+    oomKilled?: boolean | null
+    /** What the worker was before it became `unknown` — the buttons to offer depend on it. */
+    previousStatus?: string | null
+    at?: string | null
+  } | null
   /** Docker-level state: `running` | `stopped` | `exited` | `created` | `not_found` | `error`. */
   dockerState?: string | null
   createdAt?: string | null
@@ -53,3 +68,25 @@ export interface WorkerCockpitWorker extends WorkerCardWorker {
   branch?: string | null
   containerId?: string | null
 }
+
+/**
+ * One row of a worker's status history — a transition, as the control plane journaled it.
+ *
+ * Mirrors a `worker_status_events` row of the dashboard (`from`, `to`, `source`, `meta`, `at`),
+ * laxly: `to` and `at` are the only fields the history can't draw without. `source` is a free
+ * string on purpose — the package phrases the ones it knows and shows the others as they come.
+ */
+export interface WorkerStatusEvent {
+  /** Order within the worker. Falls back to `at` when absent. */
+  seq?: number | null
+  /** ISO 8601 — when the worker *entered* `to`. */
+  at: string
+  /** `null` for the very first transition (the worker's creation). */
+  from?: string | null
+  /** Lifecycle state entered — same vocabulary as `WorkerCardWorker.state`. */
+  to: string
+  /** Who wrote it: `spawn` | `agent-event` | `reconciliation` | `command` | `setup-monitor` | `boot-recovery` | `node-disconnect`. */
+  source?: string | null
+  /** The why, same shape as `WorkerCardWorker.statusMeta`. */
+  meta?: WorkerCardWorker["statusMeta"]
+}

package/src/components/workers/worker-cockpit.tsx

@@ -1,7 +1,7 @@
 "use client"
 
 // The full worker page, as one component. Top bar, logs/terminal tabs, and a
-// control panel (setup, resources, repos, ports, tags, actions, info) that
+// control panel (setup, resources, repos, ports, tags, actions, history, info) that
 // lives in a sidebar on desktop and a bottom sheet on mobile — same content,
 // because a phone doesn't need less of it, just a different place to put it.
 //
@@ -44,10 +44,11 @@ import { type GitRepoStatus, repoName } from "./git-branch-chips"
 import { ResourceBars, type WorkerStats } from "./resource-bars"
 import { SetupWaterfall } from "./setup-waterfall"
 import { TagChips } from "./tag-chips"
-import type { WorkerCockpitWorker, WorkerCreator } from "./types"
+import type { WorkerCockpitWorker, WorkerCreator, WorkerStatusEvent } from "./types"
 import { type LinkRender } from "./worker-card"
 import { WorkerSetupTimeline } from "./worker-setup-timeline"
 import { WorkerStatusDot, WorkerStatusPill, resolveWorkerStatus } from "./worker-status"
+import { WorkerStatusHistory } from "./worker-status-history"
 
 type CockpitTab = "logs" | "terminal"
 
@@ -104,6 +105,12 @@ export interface WorkerCockpitProps {
   /** Fetches the one-shot SSH command; the cockpit copies it to the clipboard and owns the button's own idle/loading/copied state. */
   onCopySsh?: () => Promise<string>
 
+  /**
+   * The worker's status transitions, as journaled by the control plane. Omitted or empty → no
+   * History section. The current stay is measured up to `now` at render time.
+   */
+  statusHistory?: WorkerStatusEvent[]
+
   /** A failed mutation, typically. */
   error?: string | null
   onDismissError?: () => void
@@ -180,6 +187,7 @@ export function WorkerCockpit({
   onDelete,
   deleting = false,
   onCopySsh,
+  statusHistory,
   error,
   onDismissError,
   activeTab,
@@ -394,6 +402,13 @@ export function WorkerCockpit({
         </div>
       )}
 
+      {!!statusHistory?.length && (
+        <div>
+          <SectionLabel>History</SectionLabel>
+          <WorkerStatusHistory events={statusHistory} />
+        </div>
+      )}
+
       <div>
         <SectionLabel>Info</SectionLabel>
         <div className="divide-y divide-border/40 rounded-lg border border-border/50 bg-muted/20">

package/src/components/workers/worker-status-history.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from "vitest"
+import { formatElapsed } from "../../utils"
+import { statusHistorySpans } from "./worker-status-history"
+
+const T0 = Date.parse("2026-09-22T10:00:00Z")
+const at = (ms: number) => new Date(T0 + ms).toISOString()
+
+describe("statusHistorySpans", () => {
+  it("un séjour dure jusqu'à la transition suivante, le dernier jusqu'à now", () => {
+    const spans = statusHistorySpans(
+      [
+        { seq: 1, at: at(0), from: null, to: "provisioning", source: "spawn" },
+        { seq: 2, at: at(800), from: "provisioning", to: "building", source: "spawn" },
+        { seq: 3, at: at(660_800), from: "building", to: "ready", source: "agent-event" },
+      ],
+      T0 + 3_600_000
+    )
+    expect(spans.map((s) => s.duration)).toEqual([800, 660_000, 3_600_000 - 660_800])
+    expect(spans.map((s) => s.current)).toEqual([false, false, true])
+  })
+
+  it("remet dans l'ordre un journal qui arrive dans le désordre", () => {
+    const spans = statusHistorySpans(
+      [
+        { seq: 2, at: at(1000), to: "ready" },
+        { seq: 1, at: at(0), to: "starting" },
+      ],
+      T0 + 2000
+    )
+    expect(spans.map((s) => s.event.to)).toEqual(["starting", "ready"])
+  })
+
+  it("ignore une date illisible et ne produit jamais de durée négative", () => {
+    const spans = statusHistorySpans(
+      [
+        { seq: 1, at: "pas une date", to: "starting" },
+        { seq: 2, at: at(5000), to: "ready" },
+      ],
+      T0 // horloge en retard sur le journal
+    )
+    expect(spans).toHaveLength(1)
+    expect(spans[0].duration).toBe(0)
+  })
+
+  it("ne fait battre que le séjour en cours", () => {
+    const spans = statusHistorySpans(
+      [
+        { seq: 1, at: at(0), to: "ready" },
+        { seq: 2, at: at(1000), to: "stopping" },
+        { seq: 3, at: at(2000), to: "stopped" },
+        { seq: 4, at: at(3000), to: "ready" },
+      ],
+      T0 + 4000
+    )
+    expect(spans.map((s) => s.status.running)).toEqual([false, false, false, true])
+  })
+
+  it("dit pourquoi à partir du meta, et retire les points de suspension d'un séjour fini", () => {
+    const spans = statusHistorySpans(
+      [
+        { seq: 1, at: at(0), to: "provisioning" },
+        { seq: 2, at: at(1000), to: "starting" },
+        { seq: 3, at: at(2000), to: "exited", meta: { reason: "oom-killed", exitCode: 137, oomKilled: true } },
+      ],
+      T0 + 3000
+    )
+    expect(spans.map((s) => s.label)).toEqual(["Provisioning", "Setting up", "Exited"])
+    expect(spans[2].status.detail).toBe("Ran out of memory (exit 137)")
+  })
+})
+
+describe("formatElapsed", () => {
+  it.each([
+    [800, "800ms"],
+    [40_000, "40s"],
+    [252_000, "4m 12s"],
+    [660_000, "11m"],
+    [11_520_000, "3h 12m"],
+    [7_200_000, "2h"],
+    [59_800, "1m"],
+    [273_600_000, "3d 4h"],
+  ])("%d ms → %s", (ms, out) => {
+    expect(formatElapsed(ms)).toBe(out)
+  })
+})

package/src/components/workers/worker-status-history.tsx

@@ -0,0 +1,166 @@
+"use client"
+
+// The life of a worker, as its status history tells it (RFC 0027, step 8).
+//
+// Two readings of the same journal, stacked:
+//
+// - a **strip** — one segment per stay, width proportional to how long it lasted. It answers
+//   "what did this worker mostly do" at a glance: a strip that is all green is a healthy worker, a
+//   strip with a grey tail is one that died, a strip striped yellow/grey is a node that flaps.
+// - a **list**, newest first — what each stay was, how long it lasted, who wrote it, and why when
+//   the control plane said why ("Ran out of memory (exit 137)"). This is the "why did it die on
+//   Tuesday" answer, without the logs of a container that no longer exists.
+//
+// Durations are *derived*, never sent: a stay lasts until the next transition, and the current one
+// lasts until `now`. Same rule as `SetupWaterfall` ("the next milestone minus this one"), for the
+// whole lifecycle instead of the setup.
+//
+// Colours and labels come from `workerStatusConfig`/`resolveWorkerStatus` — the history does not
+// get its own palette, so a stay in the strip is the colour the pill was while it lasted.
+
+import { useState } from "react"
+import { ChevronDownIcon } from "lucide-react"
+
+import { cn, formatElapsed, formatShortDate } from "../../utils"
+import type { WorkerStatusEvent } from "./types"
+import { WorkerStatusDot, resolveWorkerStatus, type WorkerStatus } from "./worker-status"
+
+/** Who wrote a transition, phrased. An unknown source is shown as sent rather than dropped. */
+const SOURCE_LABELS: Record<string, string> = {
+  spawn: "spawn",
+  "agent-event": "agent",
+  reconciliation: "reconciliation",
+  command: "user action",
+  "setup-monitor": "setup monitor",
+  "boot-recovery": "API restart",
+  "node-disconnect": "node disconnect",
+}
+
+/**
+ * Labels the status table can't give. In a pill, `provisioning` and `starting` both read
+ * "Setting up…" because a pill only says *that* something is in flight; in a history they are two
+ * consecutive rows, and two identical labels in a row read like a duplicate.
+ */
+const HISTORY_LABELS: Record<string, string> = {
+  provisioning: "Provisioning",
+}
+
+export interface WorkerStatusSpan {
+  event: WorkerStatusEvent
+  status: WorkerStatus
+  /** Label for a stay — the pill's, minus the trailing "…" once the stay is over. */
+  label: string
+  start: number
+  end: number
+  duration: number
+  /** The last span: the worker is still in it, and `end` is `now`. */
+  current: boolean
+}
+
+/**
+ * Journal → stays, oldest first. Pure, so the dashboard can derive the same numbers without
+ * drawing anything (a "time to ready" metric, a test).
+ *
+ * Tolerant like the rest of the package: rows are ordered by `seq` then `at` whatever order they
+ * arrive in, a row with an unparsable `at` is skipped rather than producing `NaN` widths, and a
+ * clock that went backwards yields a zero-length stay, not a negative one.
+ */
+export function statusHistorySpans(events: WorkerStatusEvent[], now: number = Date.now()): WorkerStatusSpan[] {
+  const rows = events
+    .map((event) => ({ event, start: Date.parse(event.at) }))
+    .filter((r) => Number.isFinite(r.start))
+    .sort((a, b) => (a.event.seq ?? 0) - (b.event.seq ?? 0) || a.start - b.start)
+
+  return rows.map(({ event, start }, i) => {
+    const current = i === rows.length - 1
+    const end = current ? Math.max(start, now) : rows[i + 1].start
+    const resolved = resolveWorkerStatus({ id: "", state: event.to, statusMeta: event.meta })
+    // Only the stay the worker is *still* in may pulse — a green dot that pings on a row from last
+    // Tuesday would claim a liveness nobody observed.
+    const status = current ? resolved : { ...resolved, running: false }
+    const label = HISTORY_LABELS[event.to] ?? (current ? status.label : status.label.replace(/…$/, ""))
+    return { event, status, label, start, end, duration: Math.max(0, end - start), current }
+  })
+}
+
+export interface WorkerStatusHistoryProps {
+  /** The journal, in any order. Empty → nothing is drawn. */
+  events: WorkerStatusEvent[]
+  /** Where the current stay ends. The component doesn't tick: the app re-renders on its poll. */
+  now?: number | Date
+  /** Rows shown before "Show N earlier". The strip always covers everything. */
+  limit?: number
+  className?: string
+}
+
+export function WorkerStatusHistory({ events, now, limit = 5, className }: WorkerStatusHistoryProps) {
+  const [expanded, setExpanded] = useState(false)
+  const nowMs = now instanceof Date ? now.getTime() : (now ?? Date.now())
+  const spans = statusHistorySpans(events, nowMs)
+  if (!spans.length) return null
+
+  const total = spans.reduce((sum, s) => sum + s.duration, 0)
+  const newestFirst = [...spans].reverse()
+  const hidden = expanded ? 0 : Math.max(0, newestFirst.length - limit)
+  const rows = hidden ? newestFirst.slice(0, limit) : newestFirst
+
+  return (
+    <div data-slot="worker-status-history" className={cn("rounded-lg border border-border/40 bg-muted/20 text-xs", className)}>
+      <div className="space-y-1.5 border-b border-border/40 px-3 py-2.5">
+        <div className="flex items-center justify-between">
+          <span className="font-mono text-[11px] font-medium text-muted-foreground">
+            {spans.length} {spans.length === 1 ? "state" : "states"}
+          </span>
+          <span className="font-mono text-[11px] tabular-nums text-foreground/80">{formatElapsed(total)}</span>
+        </div>
+        {/* flex-grow by duration, with a floor: a 0.8 s provisioning next to three days of Running
+            must still be a visible notch, or the strip would lie about what happened. */}
+        <div className="flex h-2.5 gap-px overflow-hidden rounded-sm" role="img" aria-label="Time spent in each state">
+          {spans.map((s, i) => (
+            <span
+              key={i}
+              className={cn("min-w-[3px] basis-0", s.status.dotClass)}
+              style={{ flexGrow: total > 0 ? s.duration : 1 }}
+              title={`${s.label}: ${formatElapsed(s.duration)}`}
+            />
+          ))}
+        </div>
+      </div>
+
+      <ol className="px-3 py-2.5">
+        {rows.map((s, i) => {
+          const source = s.event.source ? (SOURCE_LABELS[s.event.source] ?? s.event.source) : null
+          const last = i === rows.length - 1 && !hidden
+          return (
+            <li key={`${s.event.seq ?? ""}-${s.event.at}`} className="relative pb-2.5 pl-4 last:pb-0">
+              {/* The thread between two dots. Absent under the oldest row shown: nothing before it. */}
+              {!last && <span aria-hidden className="absolute top-3 bottom-0 left-[3px] w-px bg-border" />}
+              <WorkerStatusDot status={s.status} className="absolute top-[5px] left-0" />
+              <div className="flex items-baseline justify-between gap-2">
+                <span className={cn("truncate font-medium", s.current ? "text-foreground" : "text-foreground/80")}>{s.label}</span>
+                <span className="shrink-0 font-mono text-[11px] tabular-nums text-muted-foreground/80">{formatElapsed(s.duration)}</span>
+              </div>
+              {s.status.detail && <p className="mt-0.5 text-[11px] leading-snug text-foreground/70">{s.status.detail}</p>}
+              <p className="mt-0.5 truncate text-[10px] text-muted-foreground/60">
+                {s.current ? "since " : ""}
+                {formatShortDate(s.start, { time: true })}
+                {source && <> · {source}</>}
+              </p>
+            </li>
+          )
+        })}
+      </ol>
+
+      {hidden > 0 && (
+        <button
+          type="button"
+          onClick={() => setExpanded(true)}
+          className="flex w-full cursor-pointer items-center justify-center gap-1 border-t border-border/40 py-1.5 text-[11px] text-muted-foreground transition-colors hover:text-foreground"
+        >
+          <ChevronDownIcon className="h-3 w-3" />
+          Show {hidden} earlier
+        </button>
+      )}
+    </div>
+  )
+}

package/src/components/workers/worker-status.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect } from "vitest"
+import { resolveWorkerStatus, workerStatusConfig } from "./worker-status"
+
+describe("resolveWorkerStatus — le node injoignable", () => {
+  it("ne prétend rien, et ne prétend surtout pas qu'un setup est en cours", () => {
+    const status = resolveWorkerStatus({ id: "w", state: "unknown" })
+    expect(status.key).toBe("unknown")
+    expect(status.label).toBe("Unknown")
+    expect(status.settingUp).toBe(false)
+    expect(status.running).toBe(false)
+  })
+
+  it("prime sur un dockerState périmé", () => {
+    // Le cas réel : le dernier `inspect` réussi disait « running », puis le node est parti. La
+    // pastille doit dire qu'on ne sait pas, pas répéter une observation qu'on ne peut plus refaire.
+    const status = resolveWorkerStatus({ id: "w", state: "unknown", dockerState: "running" })
+    expect(status.key).toBe("unknown")
+  })
+
+  it("dit pourquoi, quand le plan de contrôle l'a dit", () => {
+    const status = resolveWorkerStatus({
+      id: "w",
+      state: "unknown",
+      statusMeta: { reason: "node-disconnected", previousStatus: "ready" },
+    })
+    expect(status.detail).toBe("The node is unreachable")
+  })
+})
+
+describe("resolveWorkerStatus — le conteneur mort tout seul", () => {
+  it("se résout sans dockerState, pour un produit qui n'a qu'un champ", () => {
+    // Spunto Lite n'a pas de second axe : avant, `exited` n'était atteignable que par la branche
+    // docker et un worker mort retombait sur le repli `pending`.
+    const status = resolveWorkerStatus({ id: "w", state: "exited" })
+    expect(status.key).toBe("exited")
+    expect(status.label).toBe("Exited")
+    expect(status.running).toBe(false)
+  })
+
+  it("porte le code de sortie quand il y en a un", () => {
+    const status = resolveWorkerStatus({
+      id: "w",
+      state: "exited",
+      statusMeta: { reason: "oom-killed", exitCode: 137 },
+    })
+    expect(status.detail).toBe("Ran out of memory (exit 137)")
+  })
+
+  it("garde un code de sortie nul, qui est une valeur et pas une absence", () => {
+    const status = resolveWorkerStatus({
+      id: "w",
+      state: "exited",
+      statusMeta: { reason: "completed", exitCode: 0 },
+    })
+    expect(status.detail).toBe("The container finished and exited cleanly (exit 0)")
+  })
+
+  it("préfère toujours le message du plan de contrôle à sa propre formulation", () => {
+    const status = resolveWorkerStatus({
+      id: "w",
+      state: "exited",
+      statusMeta: { reason: "oom-killed", message: "Killed while compiling the kernel" },
+    })
+    expect(status.detail).toBe("Killed while compiling the kernel")
+  })
+})
+
+describe("resolveWorkerStatus — la tolérance qui fait vivre la table", () => {
+  it("n'invente pas de détail pour une raison qu'elle ne connaît pas", () => {
+    const status = resolveWorkerStatus({ id: "w", state: "ready", statusMeta: { reason: "sonar-storm" } })
+    expect(status.detail).toBeUndefined()
+    expect(status.key).toBe("running")
+  })
+
+  it("laisse les statuts connus intacts", () => {
+    expect(resolveWorkerStatus({ id: "w", state: "building" }).settingUp).toBe(true)
+    expect(resolveWorkerStatus({ id: "w", state: "ready", dockerState: "running" }).key).toBe("running")
+    expect(resolveWorkerStatus({ id: "w", state: "wat" }).key).toBe("pending")
+  })
+
+  it("donne une pastille à chaque clé, sans exception", () => {
+    for (const [key, config] of Object.entries(workerStatusConfig)) {
+      expect(config.label, `"${key}" has no label`).toBeTruthy()
+      expect(config.dotClass, `"${key}" has no dot`).toBeTruthy()
+    }
+  })
+})

package/src/components/workers/worker-status.tsx

@@ -6,13 +6,18 @@
 // This module is the union of both, plus the transient states (`pulling`,
 // `stopping`, `deleting`) that only ever existed as ad-hoc `if`s above the table.
 //
-// `building` is the odd one out: it is the state a *control plane* reports, and
-// the only one here that Spunto Lite names and the dashboard does not. Both wait
-// for a project image before a container exists — Cloud does it inside
-// `provisioning` and rebuilds the fact client-side by joining the project's image
-// builds, Lite says it in the field. It is deliberately not folded into
-// `pulling`: building an image and pulling one are different waits, and only one
-// of them has a log worth opening.
+// Three keys here are *control plane* states rather than docker ones, and they
+// are the reason this table is not just a mapping of `docker inspect`:
+//
+// - `building` — waiting for the project image, before any container exists. Not
+//   folded into `pulling`: building an image and pulling one are different waits,
+//   and only one of them has a log worth opening.
+// - `exited` — the container died without being asked to. It already existed as a
+//   *docker* state; it is now also a lifecycle one, so a product with a single
+//   `state` field resolves it without falling through to the fallback.
+// - `unknown` — the node is unreachable, so we do not know. It claims nothing on
+//   purpose: showing the last known status as though it were current is the lie
+//   this key exists to avoid. `statusMeta.previousStatus` keeps what it was.
 //
 // No "use client": pure functions and hookless components, so a React Server
 // Component can call them.
@@ -30,6 +35,7 @@ export type WorkerStatusKey =
   | "pending"
   | "setup"
   | "building"
+  | "unknown"
   | "pulling"
   | "stopping"
   | "deleting"
@@ -89,6 +95,9 @@ export const workerStatusConfig: Record<WorkerStatusKey, WorkerStatusConfig> = {
   pending: BUSY,
   setup: { ...BUSY, label: "Setting up…" },
   building: { ...BUSY, label: "Building image…" },
+  // Volontairement neutre : ni jaune (rien n'est en cours, on ne sait pas), ni rouge
+  // (rien n'a échoué). C'est l'absence d'information, et elle a le droit de se voir.
+  unknown: { ...IDLE, label: "Unknown" },
   pulling: { ...BUSY, label: "Pulling image…" },
   stopping: { ...BUSY, label: "Stopping…" },
   deleting: { ...BUSY, label: "Deleting…" },
@@ -100,16 +109,51 @@ export interface WorkerStatus extends WorkerStatusConfig {
   settingUp: boolean
   /** Container up and past its setup — stats, git chips and the pulsing dot apply. */
   running: boolean
+  /**
+   * One sentence for what `statusMeta` carries — "Container ran out of memory", "was ready" —
+   * or `undefined` when there is nothing to add. The pill says *what*; this says *why*, and a
+   * consumer renders it beside the pill or not at all.
+   */
+  detail?: string
 }
 
 /** Lifecycle states that mean "not usable yet, a setup is in flight". */
 const SETUP_STATES = new Set(["provisioning", "starting", "setup"])
 
+/**
+ * Fallback phrasing per reason, used only when the control plane sent no `message`.
+ *
+ * Deliberately short and deliberately incomplete: a reason this table has never heard of yields
+ * no detail rather than an invented one — same rule as the status table itself.
+ */
+const REASON_PHRASES: Record<string, string> = {
+  "oom-killed": "Ran out of memory",
+  exited: "The container exited on its own",
+  completed: "The container finished and exited cleanly",
+  "removed-externally": "The container is gone from the node",
+  "setup-failed": "Setup failed inside the container",
+  "build-failed": "The project image could not be built",
+  "spawn-orphaned": "Startup was interrupted and cannot resume",
+  "node-lost": "The node disconnected before the container existed",
+  "node-disconnected": "The node is unreachable",
+}
+
+/** What `statusMeta` has to say, if anything: the message it carried, else its reason. */
+function detailOf(meta: WorkerCardWorker["statusMeta"]): string | undefined {
+  if (!meta) return undefined
+  if (meta.message) return meta.message
+  const phrase = meta.reason ? REASON_PHRASES[meta.reason] : undefined
+  if (!phrase) return undefined
+  // `exitCode` is worth showing when it is there — `0` included, which is why this is not `||`.
+  return meta.exitCode != null ? `${phrase} (exit ${meta.exitCode})` : phrase
+}
+
 /**
  * Worker snapshot → one status, tolerant of shapes it has never seen.
  *
  * Order matters: the *lifecycle* state wins whenever it describes an action in
- * flight (deleting, stopping, building, pulling, setting up), because docker still reports
+ * flight or already settled (deleting, stopping, unknown, exited, building, pulling, setting up),
+ * because docker still reports
  * the container as `running` throughout — showing "Running" while a worker is
  * being deleted is the bug this ordering exists to prevent. Past that, the
  * docker state is the truth. Apps with a single `state` field (Spunto Lite) fall
@@ -120,16 +164,24 @@ export function resolveWorkerStatus(worker: WorkerCardWorker): WorkerStatus {
   const state = worker.state ?? null
   const docker = worker.dockerState ?? null
 
+  const detail = detailOf(worker.statusMeta)
   const of = (key: WorkerStatusKey, flags?: Partial<Pick<WorkerStatus, "settingUp" | "running">>): WorkerStatus => ({
     key,
     ...workerStatusConfig[key],
     settingUp: false,
     running: key === "running",
+    ...(detail ? { detail } : {}),
     ...flags,
   })
 
   if (state === "deleting") return of("deleting")
   if (state === "stopping") return of("stopping")
+  // Le node est injoignable : on ne sait pas. Surtout pas `settingUp` — annoncer une progression
+  // pour une machine qu'on ne voit plus est exactement ce que ce statut existe pour éviter.
+  if (state === "unknown") return of("unknown")
+  // Mort tout seul. Le statut de cycle de vie prime sur `dockerState`, qui dirait la même chose
+  // quand il est là — et ne dirait rien du tout chez un produit qui n'a qu'un champ.
+  if (state === "exited") return of("exited")
   if (state === "building") return of("building", { settingUp: true })
   if (state === "pulling") return of("pulling", { settingUp: true })
   if (state && SETUP_STATES.has(state)) return of("setup", { settingUp: true })

package/src/index.ts

@@ -1,7 +1,7 @@
 // @spunto/design-system — shared UI primitives, helpers, and color constants.
 // Tokens ship as a CSS file: `import "@spunto/design-system/styles.css"`.
 
-export { cn, formatDuration, formatRelativeTime } from "./utils"
+export { cn, formatDuration, formatElapsed, formatRelativeTime } from "./utils"
 export * from "./colors"
 
 // Domain (Spunto-specific) components live behind their own entry point —

package/src/utils.ts

@@ -50,3 +50,26 @@ export function formatDuration(ms: number): string {
   if (ms >= 1000) return `${(ms / 1000).toFixed(ms >= 10_000 ? 0 : 1)}s`
   return `${Math.max(0, Math.round(ms))}ms`
 }
+
+/**
+ * A span that may last days: "40s", "4m 12s", "11m", "3h 12m", "3d 4h".
+ *
+ * `formatDuration` is for a setup phase and stops at seconds ("11520s"); this one is for how long
+ * a worker *stayed* somewhere, where the range is a second to a week. Two units at most, and the
+ * second is dropped once it stops carrying information (the seconds of an 11-minute build).
+ */
+export function formatElapsed(ms: number): string {
+  if (ms < 10_000) return formatDuration(ms)
+  // Rounded once, to the second, before splitting: 59.8 s is "1m", not "0m 59s" nor "60s".
+  const totalSeconds = Math.round(ms / 1000)
+  if (totalSeconds < 60) return `${totalSeconds}s`
+  const minutes = Math.floor(totalSeconds / 60)
+  if (minutes < 60) {
+    const seconds = totalSeconds % 60
+    return minutes < 10 && seconds ? `${minutes}m ${seconds}s` : `${minutes}m`
+  }
+  const hours = Math.floor(minutes / 60)
+  if (hours < 24) return minutes % 60 ? `${hours}h ${minutes % 60}m` : `${hours}h`
+  const days = Math.floor(hours / 24)
+  return hours % 24 ? `${days}d ${hours % 24}h` : `${days}d`
+}