@telorun/runner-core 0.8.1 → 0.9.0

package/src/config.ts

@@ -15,6 +15,33 @@ export interface RunnerCoreConfig {
   exitTtlMs: number;
   replayBufferBytes: number;
   corsOrigins: string[] | "*";
+  watch: WatchSessionConfig;
+}
+
+/**
+ * Watch-session policy. Off by default and separately ceilinged, because a watch
+ * session is a materially different resource shape from a run: a pod that
+ * outlives its runs, whose concurrency is bounded by simultaneous EDITORS rather
+ * than simultaneous runs. Inheriting a run session's ceilings would size it for
+ * the opposite assumption.
+ */
+export interface WatchSessionConfig {
+  /** Server-side gate. Watch sessions are never client-requestable when off. */
+  enabled: boolean;
+  /** No SSE/WS subscriber for this long → suspend (pod deleted, checkpoint held). */
+  idleMs: number;
+  /** Pod deadline for a watch session. The agent and app containers share one
+   *  pod, so one deadline covers both: take the longer (agent) ceiling and let
+   *  idleness do the real work, or the conversation dies at an hour mid-turn. */
+  maxTtlSeconds: number;
+  maxSessions: number;
+  reloadLimitPerMinute: number;
+  /** How long a SUSPENDED record is retained before eviction. Deliberately not
+   *  the pod deadline: that bounds a pod, so on its own nothing would ever evict
+   *  a suspended record. */
+  suspendedTtlMs: number;
+  /** How often the runner pulls a whole-tree workspace snapshot. */
+  checkpointMs: number;
 }
 
 export class RunnerConfigError extends Error {}
@@ -233,5 +260,37 @@ export function loadCoreConfig(
       "RUNNER_REPLAY_BUFFER_BYTES",
     ),
     corsOrigins: parseCorsOrigins(env.RUNNER_CORS_ORIGINS),
+    watch: loadWatchConfig(env),
+  };
+}
+
+export function loadWatchConfig(env: NodeJS.ProcessEnv): WatchSessionConfig {
+  return {
+    enabled: parseBool(env.RUNNER_WATCH_SESSIONS, false, "RUNNER_WATCH_SESSIONS"),
+    idleMs:
+      parsePositiveInt(env.RUNNER_WATCH_IDLE_SECONDS, 300, "RUNNER_WATCH_IDLE_SECONDS") * 1000,
+    maxTtlSeconds: parsePositiveInt(
+      env.RUNNER_WATCH_MAX_TTL_SECONDS,
+      21600,
+      "RUNNER_WATCH_MAX_TTL_SECONDS",
+    ),
+    maxSessions: parsePositiveInt(env.RUNNER_WATCH_MAX_SESSIONS, 8, "RUNNER_WATCH_MAX_SESSIONS"),
+    reloadLimitPerMinute: parsePositiveInt(
+      env.RUNNER_WATCH_RELOAD_LIMIT,
+      30,
+      "RUNNER_WATCH_RELOAD_LIMIT",
+    ),
+    suspendedTtlMs:
+      parsePositiveInt(
+        env.RUNNER_WATCH_SUSPENDED_TTL_SECONDS,
+        86400,
+        "RUNNER_WATCH_SUSPENDED_TTL_SECONDS",
+      ) * 1000,
+    checkpointMs:
+      parsePositiveInt(
+        env.RUNNER_WORKSPACE_CHECKPOINT_SECONDS,
+        30,
+        "RUNNER_WORKSPACE_CHECKPOINT_SECONDS",
+      ) * 1000,
   };
 }

package/src/contract.ts

@@ -46,11 +46,30 @@ export interface RunnerTerms {
 /** HTTP header carrying the accepted terms version on `POST /v1/sessions`. */
 export const ACCEPTED_TERMS_HEADER = "x-telo-accepted-terms";
 
+/**
+ * How an application container's byte channel is attached.
+ *  - `tty`     — one merged stream, as a terminal produces. Resize works;
+ *                `CLICOLOR_FORCE` is injected.
+ *  - `streams` — stdout and stderr separated at the source. Resize is rejected
+ *                (meaningless with no PTY) and no colour is forced, so the app
+ *                sees the environment it would see in production.
+ * Nothing is invented at the transport layer: docker's non-TTY attach is already
+ * a multiplexed stream carrying a per-frame stream id, and the kubernetes attach
+ * subresource without a TTY already gives separate stdout/stderr channels.
+ */
+export type IoMode = "tty" | "streams";
+
 export interface RunnerFeatures {
-  /** Runner exposes a live PTY byte channel (`/v1/sessions/:id/io`). */
-  io: boolean;
+  /** Byte-channel attach modes this runner offers (`/v1/sessions/:id/io`). */
+  io: IoMode[];
   /** Runner can publish workload ports back to the client. */
   ports: boolean;
+  /** Watch sessions (`mode: "watch"`) are requestable. Server-gated: a runner
+   *  with watch disabled advertises `false` and rejects the field. */
+  watch: boolean;
+  /** Catalog names admissible as a session's co-resident `agent`. Empty/absent
+   *  when the operator configured none. */
+  agents?: string[];
 }
 
 /** An operator-predefined application the runner can launch by name. Only the
@@ -92,7 +111,14 @@ export type AvailabilityReport =
 
 export interface RunBundle {
   entryRelativePath: string;
-  files: Array<{ relativePath: string; contents: string }>;
+  files: Array<{
+    relativePath: string;
+    contents: string;
+    /** `utf8` when omitted. A checkpoint re-seeds a resumed session through this
+     *  same shape, and a workspace may hold a binary asset, so dropping anything
+     *  that is not text would silently lose a file across a suspend. */
+    encoding?: "utf8" | "base64";
+  }>;
 }
 
 export type PortProtocol = "tcp" | "udp";
@@ -118,6 +144,42 @@ export interface RunnerEndpoint {
   url?: string;
 }
 
+/**
+ * How long a session lives relative to its runs.
+ *  - `run`   — one run. The workload exits and the session is terminal. Today's
+ *              behaviour, and the default.
+ *  - `watch` — a workspace that runs continuously. Each application container
+ *              runs `telo run --watch`, an edit costs a kernel reload rather
+ *              than a pod, and a completed one-shot run leaves the session up.
+ */
+export type SessionMode = "run" | "watch";
+
+/** The name a single-app session's one application takes when the request
+ *  declares no `apps` — so every `run` / `debug` / `endpoints` event names an
+ *  app, and no client needs two readings of the same stream. */
+export const DEFAULT_APP_NAME = "app";
+
+/**
+ * One application in a session — one container, one kernel, one watcher. Most
+ * workspaces have exactly one: an Application with several Services in its
+ * `targets:` is still one kernel. The multi-app case is two independent
+ * Applications, which genuinely cannot be merged (importing a `Telo.Application`
+ * is a hard error, so no manifest composes them).
+ */
+export interface SessionAppSpec {
+  /** Unique within the session and usable as a DNS label — it appears in the
+   *  container name and in every run event. */
+  name: string;
+  /** Bundle-relative entry manifest this app runs. */
+  entryRelativePath: string;
+  /** Ports this app declares. Unique across the WHOLE session: session hosts are
+   *  `<port>-<sessionId>.<base-domain>`, a single label, so two apps on one port
+   *  would collide with nothing to tell them apart. */
+  ports?: PortMapping[];
+  /** Terminal or separated streams; defaults to `tty`. */
+  io?: IoMode;
+}
+
 export interface StartSessionRequest {
   bundle: RunBundle;
   env: Record<string, string>;
@@ -126,17 +188,45 @@ export interface StartSessionRequest {
   /** Request the kernel debug stream. When true the runner launches the
    *  workload with `--inspect`, subscribes to the in-workload inspect endpoint
    *  (reachable only by the runner — never published outward), and relays each
-   *  frame to the client as a `debug` {@link RunEvent}. */
+   *  frame to the client as a `debug` {@link RunEvent}. A watch session always
+   *  runs with it on — that stream is where `run` events are projected from. */
   inspect?: boolean;
+  /** Defaults to `run`. */
+  mode?: SessionMode;
+  /** Catalog name of a co-resident agent container. At most one per session,
+   *  never per app: the agent's unit is the workspace, and two agents over one
+   *  workspace would contend on the same files and split one conversation in
+   *  half. Requires `mode: "watch"` — an agent with nothing watching its writes
+   *  is a silent no-op. */
+  agent?: string;
+  /** The applications this session runs, one container each. Omitted, it
+   *  defaults to a single app named `app` on the bundle's own entry with the
+   *  request's `ports` — so a single-app session is written exactly as before. */
+  apps?: SessionAppSpec[];
 }
 
+/**
+ * The SESSION's status — how the session itself is doing, not how any one run
+ * ended. The two are separate nouns on the same stream: a one-shot app finishing
+ * in a watch session emits `run.completed` and leaves the session `running`, so
+ * the next edit starts that app's next generation.
+ *
+ * `exited` belongs to a `run` session only, where the session IS the run.
+ */
 export type RunStatus =
   | { kind: "starting" }
-  /** `inspectUrl` is the kernel debug/inspection UI fronted by a proxy (set only
-   *  when the session ran with `inspect` and the runner has a public base URL);
-   *  absent when the inspect endpoint isn't externally reachable. */
+  /** Every application container is up. `inspectUrl` is the kernel
+   *  debug/inspection UI fronted by a proxy (set only when the session ran with
+   *  `inspect` and the runner has a public base URL); absent when the inspect
+   *  endpoint isn't externally reachable. */
   | { kind: "running"; endpoints?: RunnerEndpoint[]; inspectUrl?: string }
   | { kind: "exited"; code: number }
+  /** Reaped for idleness: the pod is gone, the workspace checkpoint is held, and
+   *  `POST /v1/sessions/:id/resume` brings it back under the same session id.
+   *  NOT terminal — nothing is evicted on it. Best-effort by design: the runner
+   *  holds the checkpoint in memory, so a runner restart loses it and the editor
+   *  (which holds the authoritative workspace) re-seeds from its own copy. */
+  | { kind: "suspended" }
   | { kind: "failed"; message: string }
   | { kind: "stopped" };
 
@@ -152,21 +242,113 @@ export type RunPhase = "build" | "provision" | "boot";
  *  (spinner → ok / error) instead of an app-log line. */
 export type ReachabilityState = "checking" | "reachable" | "unreachable";
 
+/** What started one generation of an application.
+ *  - `initial` — the session came up
+ *  - `watch`   — a file changed under the app's watcher
+ *  - `manual`  — `POST /v1/sessions/:id/reload`
+ *  - `resume`  — a suspended session was brought back, or the app set changed */
+export type RunTrigger = "initial" | "watch" | "manual" | "resume";
+
+/**
+ * A RUN outcome — one per app per reload generation, distinct from the session
+ * status above. `generation` is monotonic per app and starts at 1; it is counted
+ * by the runner from the kernel lifecycle events already on the debug stream, so
+ * it asks the kernel for nothing.
+ */
+export type RunOutcomeEvent =
+  | { type: "run"; app: string; generation: number; phase: "started"; trigger: RunTrigger }
+  | {
+      type: "run";
+      app: string;
+      generation: number;
+      phase: "completed";
+      code: number;
+      durationMs?: number;
+    }
+  | { type: "run"; app: string; generation: number; phase: "failed"; reason: string };
+
+/**
+ * Workload output does NOT travel this channel, in either mode — it goes over the
+ * byte channel (`/io`), which exists precisely because per-chunk events are
+ * wasteful for high-volume output. The `stdout` / `stderr` variants that used to
+ * be declared here were emitted by nothing: a contract in shape only.
+ */
 export type RunEvent =
-  | { type: "stdout"; chunk: string }
-  | { type: "stderr"; chunk: string }
   | { type: "status"; status: RunStatus }
-  | { type: "progress"; phase: RunPhase; message: string; done?: boolean }
-  /** A frame relayed from the workload's kernel debug stream (kernel event or
-   *  log line). Only emitted when the session was started with `inspect`. */
-  | { type: "debug"; frame: DebugFrame }
-  /** A reachability transition for one declared port, keyed by port. */
-  | { type: "reachability"; port: number; state: ReachabilityState };
+  /** `app` is absent for session-scoped provisioning (scheduling, image pull) and
+   *  present once the message belongs to one application. */
+  | { type: "progress"; app?: string; phase: RunPhase; message: string; done?: boolean }
+  /** A frame relayed from one app's kernel debug stream (kernel event or log
+   *  line). Only emitted when the session was started with `inspect`. */
+  | { type: "debug"; app: string; frame: DebugFrame }
+  /** A reachability transition for one declared port of one app. */
+  | { type: "reachability"; app: string; port: number; state: ReachabilityState }
+  | RunOutcomeEvent
+  /** An app's declared port set changed on reload and the runner re-patched the
+   *  Service and Ingress. Without this the app binds the new port inside the pod
+   *  and is simply unreachable: no ingress, no error, no event. */
+  | {
+      type: "endpoints";
+      app: string;
+      added?: RunnerEndpoint[];
+      removed?: RunnerEndpoint[];
+      /** A declared port that could not be routed (it collides with another app
+       *  in this session). Reported, never dropped. */
+      rejected?: Array<{ port: number; reason: string }>;
+    };
 
+/**
+ * Terminal = the session is over and the registry may schedule eviction.
+ * `suspended` is deliberately NOT terminal: the session record and its workspace
+ * checkpoint outlive the pod, and `resume` brings it back under the same id.
+ */
 export function isTerminal(status: RunStatus): boolean {
   return status.kind === "exited" || status.kind === "failed" || status.kind === "stopped";
 }
 
+/**
+ * Which stream a byte-channel chunk came from. Under `io: "tty"` every chunk is
+ * `tty` — the tag never asserts a split that does not exist, which is exactly the
+ * failure the deleted `stdout` / `stderr` run events represented.
+ */
+export type ByteStreamTag = "tty" | "stdout" | "stderr";
+
+/** One file in a workspace snapshot: its path and the sha256 of its bytes.
+ *  Hashing content — rather than comparing sizes or timestamps — is what makes
+ *  two snapshots diff into an exact change set. */
+export interface WorkspaceFileEntry {
+  path: string;
+  hash: string;
+}
+
+export interface WorkspaceTree {
+  files: WorkspaceFileEntry[];
+}
+
+/**
+ * An explicit write/delete list rather than a whole-tree PUT: a deletion has to
+ * be expressible, and a whole-tree PUT can only express it by treating absence as
+ * intent. A one-file save is a change set of one — there is deliberately no
+ * single-file write route, which would be a second set of concurrency rules.
+ */
+export interface WorkspaceChangeSet {
+  write?: Array<{ path: string; content: string; encoding?: "utf8" | "base64" }>;
+  delete?: string[];
+}
+
+export interface WorkspaceApplyResult {
+  written: number;
+  deleted: number;
+}
+
+/** One file of a checkpoint — a tree entry plus the bytes needed to re-seed a
+ *  fresh pod. Text stays `utf8`; anything that is not valid text is carried
+ *  `base64`, so a binary asset survives a suspend/resume round trip. */
+export interface WorkspaceCheckpointFile extends WorkspaceFileEntry {
+  content: string;
+  encoding: "utf8" | "base64";
+}
+
 /**
  * Stages a session start can fail at. The docker/k8s backends share the
  * vocabulary; not every stage applies to every backend (`pull`/`inspect` are

package/src/debug/ports-resolved.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+
+import type { DebugFrame } from "@telorun/debug-wire";
+import { portKey, portsResolvedFrom, PORTS_RESOLVED_EVENT } from "./ports-resolved.js";
+
+const frame = (event: string, payload?: unknown): DebugFrame => ({
+  kind: "event",
+  timestamp: "2026-01-01T00:00:00.000Z",
+  event,
+  payload,
+});
+
+describe("portsResolvedFrom", () => {
+  it("reads the declared port set the kernel resolved", () => {
+    expect(
+      portsResolvedFrom(
+        frame(PORTS_RESOLVED_EVENT, {
+          ports: [
+            { name: "http", port: 3000, protocol: "tcp" },
+            { name: "metrics", port: 9100, protocol: "udp" },
+          ],
+        }),
+      ),
+    ).toEqual([
+      { port: 3000, protocol: "tcp" },
+      { port: 9100, protocol: "udp" },
+    ]);
+  });
+
+  it("reads an empty set as an empty set, not as 'no information'", () => {
+    // An app that dropped its last `ports:` entry has to un-route it, so the
+    // difference between [] and undefined is load-bearing.
+    expect(portsResolvedFrom(frame(PORTS_RESOLVED_EVENT, { ports: [] }))).toEqual([]);
+  });
+
+  it("ignores every other frame", () => {
+    expect(portsResolvedFrom(frame("Kernel.Started"))).toBeUndefined();
+    expect(
+      portsResolvedFrom({ kind: "log", timestamp: "", stream: "stdout", line: "x" }),
+    ).toBeUndefined();
+  });
+
+  it("ignores a payload it cannot make sense of", () => {
+    // The runner reads a stream from a kernel it is not versioned with, so an
+    // unrecognizable frame is one to skip, never one to fail the session on.
+    expect(portsResolvedFrom(frame(PORTS_RESOLVED_EVENT))).toBeUndefined();
+    expect(portsResolvedFrom(frame(PORTS_RESOLVED_EVENT, { ports: "3000" }))).toBeUndefined();
+    expect(
+      portsResolvedFrom(frame(PORTS_RESOLVED_EVENT, { ports: [{ port: "3000" }, { port: 80 }] })),
+    ).toEqual([{ port: 80, protocol: "tcp" }]);
+  });
+
+  it("defaults an unstated protocol to tcp", () => {
+    expect(portsResolvedFrom(frame(PORTS_RESOLVED_EVENT, { ports: [{ port: 80 }] }))).toEqual([
+      { port: 80, protocol: "tcp" },
+    ]);
+  });
+});
+
+describe("portKey", () => {
+  it("separates the two protocols on one number", () => {
+    expect(portKey({ port: 3000, protocol: "tcp" })).not.toBe(
+      portKey({ port: 3000, protocol: "udp" }),
+    );
+  });
+});

package/src/debug/ports-resolved.ts

@@ -0,0 +1,43 @@
+import { isEventFrame, type DebugFrame } from "@telorun/debug-wire";
+
+import type { PortMapping, PortProtocol } from "../contract.js";
+
+/** The kernel says this once per load: the Application's `ports:` block has
+ *  resolved to these integers. It re-fires on every watch reload, which is what
+ *  lets a host re-route without parsing a manifest. */
+export const PORTS_RESOLVED_EVENT = "Kernel.PortsResolved";
+
+/**
+ * The declared port set carried by a `Kernel.PortsResolved` frame, or undefined
+ * for any other frame.
+ *
+ * DECLARED, not bound. A runner routes what the manifest asked for; whether
+ * anything actually bound it is the reachability watcher's question, and it
+ * already answers it per port. Routing what happened to be bound instead would
+ * expose a port the manifest never declared, and would rest on a per-module
+ * convention — a transport whose kind does not emit a listening event would
+ * silently get no routing at all.
+ *
+ * Tolerant of a payload that is not the expected shape: a runner reads this off
+ * a stream produced by a kernel it does not version together with, so a frame it
+ * cannot make sense of is one to ignore, not to fail on.
+ */
+export function portsResolvedFrom(frame: DebugFrame): PortMapping[] | undefined {
+  if (!isEventFrame(frame) || frame.event !== PORTS_RESOLVED_EVENT) return undefined;
+  const raw = (frame.payload as { ports?: unknown } | undefined)?.ports;
+  if (!Array.isArray(raw)) return undefined;
+  const ports: PortMapping[] = [];
+  for (const entry of raw) {
+    const port = (entry as { port?: unknown })?.port;
+    const protocol = (entry as { protocol?: unknown })?.protocol;
+    if (typeof port !== "number" || !Number.isInteger(port)) continue;
+    ports.push({ port, protocol: protocol === "udp" ? "udp" : ("tcp" as PortProtocol) });
+  }
+  return ports;
+}
+
+/** Identity of a port within a session: the pair, since tcp/3000 and udp/3000
+ *  are different endpoints. */
+export function portKey(mapping: PortMapping): string {
+  return `${mapping.protocol}/${mapping.port}`;
+}

package/src/debug/relay.ts

@@ -29,17 +29,27 @@ const RECONNECT_DELAY_MS = 500;
  */
 export async function relayDebugStream(opts: DebugRelayOptions): Promise<void> {
   const { url, onFrame, signal } = opts;
+  // The last id delivered, carried across reconnects. Without it a drop replays
+  // the producer's whole buffer, and a consumer that DERIVES state from the
+  // stream — the run projection counting generations — re-counts every reload
+  // still in that buffer. In a watch session that is one pair per save.
+  let lastEventId = 0;
   while (!signal.aborted) {
     try {
       const res = await fetch(url, {
         signal,
-        headers: { accept: "text/event-stream" },
+        headers: {
+          accept: "text/event-stream",
+          ...(lastEventId > 0 ? { "last-event-id": String(lastEventId) } : {}),
+        },
       });
       if (!res.ok || !res.body) {
         await abortableDelay(RECONNECT_DELAY_MS, signal);
         continue;
       }
-      await pump(res.body, onFrame, signal);
+      await pump(res.body, onFrame, signal, (id) => {
+        lastEventId = id;
+      });
     } catch (err) {
       if (signal.aborted) return;
       opts.onError?.(err instanceof Error ? err : new Error(String(err)));
@@ -52,6 +62,7 @@ async function pump(
   body: ReadableStream<Uint8Array>,
   onFrame: (frame: DebugFrame) => void,
   signal: AbortSignal,
+  onId: (id: number) => void,
 ): Promise<void> {
   const reader = body.getReader();
   const decoder = new TextDecoder();
@@ -64,9 +75,15 @@ async function pump(
       let sep: number;
       // SSE frames are separated by a blank line.
       while ((sep = buf.indexOf("\n\n")) >= 0) {
-        const frame = parseSseData(buf.slice(0, sep));
+        const block = buf.slice(0, sep);
         buf = buf.slice(sep + 2);
-        if (frame) onFrame(frame);
+        const frame = parseSseData(block);
+        if (!frame) continue;
+        onFrame(frame);
+        // Checkpoint AFTER delivery, so a frame the consumer never saw is not
+        // skipped on the next reconnect.
+        const id = parseSseId(block);
+        if (id !== null) onId(id);
       }
     }
   } finally {
@@ -74,6 +91,17 @@ async function pump(
   }
 }
 
+/** The `id:` of one SSE frame, or null when the producer sent none — an older
+ *  kernel, whose stream simply has no resume point. */
+function parseSseId(block: string): number | null {
+  for (const line of block.split("\n")) {
+    if (!line.startsWith("id:")) continue;
+    const parsed = Number.parseInt(line.slice(3).trim(), 10);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+
 /** Extract and parse the `data:` payload of one SSE frame. Ignores comment
  *  lines (`: heartbeat`) and unparseable frames. */
 function parseSseData(block: string): DebugFrame | null {

package/src/debug/run-projection.test.ts

@@ -0,0 +1,155 @@
+import { describe, expect, it } from "vitest";
+
+import type { DebugFrame } from "@telorun/debug-wire";
+import type { RunEvent } from "../contract.js";
+import { SessionRegistry } from "../session/registry.js";
+import { RunProjection } from "./run-projection.js";
+
+function harness(apps = [{ name: "app" }]) {
+  const registry = new SessionRegistry({
+    maxSessions: 4,
+    exitTtlMs: 1000,
+    replayBufferBytes: 100_000,
+  });
+  const entry = registry.register({ sessionId: "s1", mode: "watch", apps });
+  const projection = new RunProjection(registry, "s1");
+  entry.attribution = projection;
+  const runs = (): RunEvent[] =>
+    entry.buffer.replay(0).entries.map((e) => e.event).filter((e) => e.type === "run");
+  return { registry, entry, projection, runs };
+}
+
+const event = (name: string, payload?: unknown): DebugFrame => ({
+  kind: "event",
+  timestamp: "2026-01-01T00:00:00.000Z",
+  event: name,
+  payload,
+});
+
+describe("RunProjection", () => {
+  it("brackets a generation from Kernel.Starting and Kernel.Stopped", () => {
+    const h = harness();
+    h.projection.expectAll("initial");
+    h.projection.frame("app", event("Kernel.Starting"));
+    h.projection.frame("app", event("Kernel.Started"));
+    h.projection.frame("app", event("Kernel.Stopped", { exitCode: 0 }));
+
+    expect(h.runs()).toMatchObject([
+      { type: "run", app: "app", generation: 1, phase: "started", trigger: "initial" },
+      { type: "run", app: "app", generation: 1, phase: "completed", code: 0 },
+    ]);
+  });
+
+  it("leaves the session running when a generation completes", () => {
+    const h = harness();
+    h.projection.expectAll("initial");
+    h.registry.emit("s1", { type: "status", status: { kind: "running" } });
+    h.projection.frame("app", event("Kernel.Starting"));
+    h.projection.frame("app", event("Kernel.Stopped", { exitCode: 0 }));
+
+    // The whole point of the split: a one-shot app finishing is not the session
+    // ending, so nothing is scheduled for eviction.
+    expect(h.entry.status).toEqual({ kind: "running" });
+    expect(h.entry.exitedAt).toBeNull();
+    expect(h.entry.evictionTimer).toBeNull();
+  });
+
+  it("counts a reload as the next generation and attributes it to the watcher", () => {
+    const h = harness();
+    h.projection.expectAll("initial");
+    h.projection.frame("app", event("Kernel.Starting"));
+    h.projection.frame("app", event("Kernel.Stopped", { exitCode: 0 }));
+    h.projection.frame("app", event("Kernel.Starting"));
+
+    expect(h.runs().at(-1)).toMatchObject({
+      generation: 2,
+      phase: "started",
+      trigger: "watch",
+    });
+  });
+
+  it("attributes a generation a route caused, then falls back to watch", () => {
+    const h = harness();
+    h.projection.expectAll("initial");
+    h.projection.frame("app", event("Kernel.Starting"));
+    h.projection.frame("app", event("Kernel.Stopped", { exitCode: 0 }));
+
+    h.projection.expect("app", "manual");
+    h.projection.frame("app", event("Kernel.Starting"));
+    h.projection.frame("app", event("Kernel.Stopped", { exitCode: 0 }));
+    h.projection.frame("app", event("Kernel.Starting"));
+
+    const started = h.runs().filter((e) => e.type === "run" && e.phase === "started");
+    expect(started.map((e) => (e as { trigger: string }).trigger)).toEqual([
+      "initial",
+      "manual",
+      "watch",
+    ]);
+  });
+
+  it("opens a generation for a load failure, which emits no Kernel.Starting", () => {
+    const h = harness();
+    h.projection.expectAll("initial");
+    // A manifest that fails to LOAD never reaches Kernel.Starting; reporting the
+    // failure of a generation the client never saw start would be unreadable.
+    h.projection.frame(
+      "app",
+      event("Kernel.RunFailed", {
+        phase: "load",
+        code: "ERR_MANIFEST_VALIDATION_FAILED",
+        message: "bad manifest",
+      }),
+    );
+
+    expect(h.runs()).toMatchObject([
+      { generation: 1, phase: "started", trigger: "initial" },
+      { generation: 1, phase: "failed", reason: "ERR_MANIFEST_VALIDATION_FAILED" },
+    ]);
+  });
+
+  it("does not double-count a boot failure that follows Kernel.Starting", () => {
+    const h = harness();
+    h.projection.expectAll("initial");
+    h.projection.frame("app", event("Kernel.Starting"));
+    h.projection.frame("app", event("Kernel.RunFailed", { phase: "start", message: "boom" }));
+
+    expect(h.runs()).toMatchObject([
+      { generation: 1, phase: "started" },
+      { generation: 1, phase: "failed", reason: "boom" },
+    ]);
+  });
+
+  it("closes a generation whose WORKLOAD ended, with no Kernel.Stopped", () => {
+    const h = harness();
+    h.projection.expectAll("initial");
+    h.projection.frame("app", event("Kernel.Starting"));
+    // A container that goes away emits nothing — there is nothing left to emit
+    // it — so the backend reports the ending through the contract instead.
+    h.projection.endGeneration("app", { reason: "application container exited" });
+
+    expect(h.runs()).toMatchObject([
+      { generation: 1, phase: "started" },
+      { generation: 1, phase: "failed", reason: "application container exited" },
+    ]);
+  });
+
+  it("ignores a workload ending when no generation is open", () => {
+    const h = harness();
+    h.projection.endGeneration("app", { reason: "gone" });
+    expect(h.runs()).toEqual([]);
+  });
+
+  it("counts generations per app, not per session", () => {
+    const h = harness([{ name: "web" }, { name: "worker" }]);
+    h.projection.expectAll("initial");
+    h.projection.frame("web", event("Kernel.Starting"));
+    h.projection.frame("worker", event("Kernel.Starting"));
+    h.projection.frame("worker", event("Kernel.Stopped", { exitCode: 0 }));
+    h.projection.frame("worker", event("Kernel.Starting"));
+
+    const byApp = (name: string) =>
+      h.runs().filter((e) => (e as { app: string }).app === name);
+    expect(byApp("web").at(-1)).toMatchObject({ generation: 1, phase: "started" });
+    expect(byApp("worker").at(-1)).toMatchObject({ generation: 2, phase: "started" });
+  });
+});