@telorun/runner-core 0.8.2 → 0.10.0

package/src/session/registry.ts

@@ -1,17 +1,53 @@
 import { EventEmitter } from "node:events";
 
-import type { BackendSession } from "../backend.js";
-import { isTerminal, type RunEvent, type RunStatus } from "../contract.js";
+import type { DebugFrame } from "@telorun/debug-wire";
+
+import type { BackendSession, WorkloadLaunch } from "../backend.js";
+import {
+  DEFAULT_APP_NAME,
+  isTerminal,
+  type ByteStreamTag,
+  type IoMode,
+  type PortMapping,
+  type RunEvent,
+  type RunStatus,
+  type RunTrigger,
+  type SessionMode,
+  type WorkspaceCheckpointFile,
+} from "../contract.js";
 import { ByteRingBuffer, type BufferedBytes } from "./byte-ring-buffer.js";
 import { EventRingBuffer, type BufferedEvent } from "./ring-buffer.js";
 
+/**
+ * One application's terminal and run bookkeeping. The byte channel is keyed
+ * `(session, app)` rather than labelled on a merged stream: each app container
+ * has its OWN terminal, and merging them would make `/io` unattachable to one.
+ */
+export interface AppChannel {
+  readonly name: string;
+  readonly io: IoMode;
+  readonly byteBuffer: ByteRingBuffer;
+  readonly byteEmitter: EventEmitter;
+  /** Monotonic per app, starting at 1. Counted here from the kernel lifecycle
+   *  events the debug stream already carries — the kernel is asked for nothing. */
+  generation: number;
+  /** Epoch ms the current generation started, for `durationMs` on completion.
+   *  Null between generations. */
+  startedAt: number | null;
+  /** The port set this app currently declares. Re-read on every reload, so a
+   *  `ports:` edit patches the Service and Ingress instead of silently binding
+   *  a port nothing routes. */
+  ports: PortMapping[];
+}
+
 export interface SessionEntry {
   readonly sessionId: string;
   readonly createdAt: Date;
+  readonly mode: SessionMode;
   readonly buffer: EventRingBuffer;
-  readonly byteBuffer: ByteRingBuffer;
   readonly emitter: EventEmitter;
-  readonly byteEmitter: EventEmitter;
+  /** One channel per application container, insertion-ordered. */
+  readonly apps: Map<string, AppChannel>;
 
   /** The live backend workload. Null until `start` resolves; the route writes
    *  stdin / resize / stop through it. A backend's `writeStdin` is a no-op once
@@ -21,12 +57,70 @@ export interface SessionEntry {
   exitedAt: Date | null;
   userStopped: boolean;
   evictionTimer: NodeJS.Timeout | null;
+
+  /** Catalog name of the co-resident agent, when one was requested. */
+  agent?: string;
+  /** Last whole-tree workspace snapshot, pulled on the checkpoint timer and
+   *  again on suspend. A CACHE, never the only copy: the editor holds the
+   *  authoritative workspace, so a runner restart losing this costs an upload,
+   *  not user work. */
+  checkpoint: WorkspaceCheckpoint | null;
+  /** How the NEXT generation of an app should be attributed. Structural rather
+   *  than the projection type itself, so the registry stays free of the debug
+   *  stream it knows nothing about. */
+  attribution: RunAttribution | null;
+  /** The description this session was launched from, retained so `resume` can
+   *  build a fresh pod under the same id without a second copy of it. */
+  launch: WorkloadLaunch | null;
+  /** Live SSE/WS subscriber count. Zero for longer than the idle window is what
+   *  suspends a watch session. */
+  subscribers: number;
+  /** Epoch ms the subscriber count last fell to zero; null while someone is
+   *  attached. */
+  idleSince: number | null;
+  /** Epoch ms of recent reloads, for the per-session reload rate limit. A watch
+   *  session reloads on every save, so an unbounded one is a way to keep a pod
+   *  permanently rebuilding. */
+  reloads: number[];
+  /** Epoch ms the last workspace checkpoint was pulled. */
+  checkpointedAt: number | null;
+}
+
+/**
+ * The run projection as the registry sees it — structural, so the registry stays
+ * free of the debug stream it knows nothing about. `expect` is how a route tells
+ * it about a generation it is ABOUT to cause: without that, a manual reload
+ * would be reported as a watch reload, and the runner would be guessing at the
+ * one fact it actually knows.
+ */
+export interface RunAttribution {
+  expect(app: string, trigger: RunTrigger): void;
+  expectAll(trigger: RunTrigger): void;
+  frame(app: string, frame: DebugFrame): void;
+  /** Close the open generation because its workload ended — a container that
+   *  goes away emits no `Kernel.Stopped`, so the backend reports the ending. */
+  endGeneration(app: string, outcome: { code?: number; reason?: string }): void;
+}
+
+/** A whole-tree snapshot plus the contents needed to re-seed a fresh pod. Whole
+ *  tree rather than a delta log from the write path: a manifest workspace is
+ *  small, and one shape is easier to reason about than a replay that has to be
+ *  correct. */
+export interface WorkspaceCheckpoint {
+  takenAt: Date;
+  files: WorkspaceCheckpointFile[];
 }
 
 export interface RegistryDeps {
   maxSessions: number;
   exitTtlMs: number;
+  /** Per APP, not per session — each application container has its own terminal
+   *  and its own replay buffer. */
   replayBufferBytes: number;
+  /** How long a suspended session record is retained before eviction. Bounds
+   *  accumulation, and is deliberately not the pod deadline: that bounds a POD,
+   *  so on its own nothing would ever evict a suspended record. */
+  suspendedTtlMs?: number;
 }
 
 const EVENT_EMITTED = "event";
@@ -42,6 +136,16 @@ const MAX_PUSH_CHUNK = 64 * 1024;
 
 export class SessionLimitError extends Error {}
 export class SessionEvictedError extends Error {}
+export class UnknownAppError extends Error {}
+
+export interface RegisterArgs {
+  sessionId: string;
+  mode?: SessionMode;
+  agent?: string;
+  /** The applications this session runs. Defaults to one app named `app` with a
+   *  terminal, so a single-app session behaves exactly as before. */
+  apps?: Array<{ name: string; io?: IoMode; ports?: PortMapping[] }>;
+}
 
 export class SessionRegistry {
   private readonly sessions = new Map<string, SessionEntry>();
@@ -68,7 +172,7 @@ export class SessionRegistry {
    * Creates a fresh registry entry. Callers are responsible for guarding against
    * duplicate insertion. Throws SessionLimitError if we're at capacity.
    */
-  register(args: { sessionId: string }): SessionEntry {
+  register(args: RegisterArgs): SessionEntry {
     if (this.sessions.size >= this.deps.maxSessions && !this.evictOldestTerminal()) {
       throw new SessionLimitError(
         `runner is at its configured max of ${this.deps.maxSessions} concurrent sessions`,
@@ -77,32 +181,74 @@ export class SessionRegistry {
     const entry: SessionEntry = {
       sessionId: args.sessionId,
       createdAt: new Date(),
+      mode: args.mode ?? "run",
       buffer: new EventRingBuffer(this.deps.replayBufferBytes),
-      byteBuffer: new ByteRingBuffer(this.deps.replayBufferBytes),
       emitter: new EventEmitter(),
-      byteEmitter: new EventEmitter(),
+      apps: new Map(),
       session: null,
       status: { kind: "starting" },
       exitedAt: null,
       userStopped: false,
       evictionTimer: null,
+      agent: args.agent,
+      checkpoint: null,
+      attribution: null,
+      launch: null,
+      subscribers: 0,
+      idleSince: Date.now(),
+      reloads: [],
+      checkpointedAt: null,
     };
     // Many transient SSE / WS subscribers per session is normal — bump the
     // default 10-listener warning to a high cap so the alarm still fires
     // for a real listener leak. 256 is well above the realistic concurrent-
     // tab count and well below "obviously a bug".
     entry.emitter.setMaxListeners(256);
-    entry.byteEmitter.setMaxListeners(256);
+    for (const app of args.apps ?? [{ name: DEFAULT_APP_NAME }]) {
+      this.addApp(entry, app);
+    }
     this.sessions.set(args.sessionId, entry);
     return entry;
   }
 
-  pushBytes(sessionId: string, bytes: Buffer): BufferedBytes | undefined {
-    const entry = this.sessions.get(sessionId);
-    if (!entry) return undefined;
+  /** Add an application channel to an existing entry. Used at register time and
+   *  when `PUT /v1/sessions/:id/apps` changes the running set. */
+  addApp(
+    entry: SessionEntry,
+    app: { name: string; io?: IoMode; ports?: PortMapping[] },
+  ): AppChannel {
+    const channel: AppChannel = {
+      name: app.name,
+      io: app.io ?? "tty",
+      byteBuffer: new ByteRingBuffer(this.deps.replayBufferBytes),
+      byteEmitter: new EventEmitter(),
+      generation: 0,
+      startedAt: null,
+      ports: app.ports ?? [],
+    };
+    channel.byteEmitter.setMaxListeners(256);
+    entry.apps.set(app.name, channel);
+    return channel;
+  }
+
+  /** The single app of a single-app session — what `/io` and `reload` fall back
+   *  to when no `app` is given. Undefined when the session runs several, where
+   *  there is no defensible default among many terminals. */
+  soleApp(entry: SessionEntry): AppChannel | undefined {
+    return entry.apps.size === 1 ? entry.apps.values().next().value : undefined;
+  }
+
+  pushBytes(
+    sessionId: string,
+    appName: string,
+    bytes: Buffer,
+    stream: ByteStreamTag = "tty",
+  ): BufferedBytes | undefined {
+    const channel = this.sessions.get(sessionId)?.apps.get(appName);
+    if (!channel) return undefined;
     if (bytes.byteLength <= MAX_PUSH_CHUNK) {
-      const buffered = entry.byteBuffer.push(bytes);
-      entry.byteEmitter.emit(BYTES_EMITTED, buffered);
+      const buffered = channel.byteBuffer.push(bytes, stream);
+      channel.byteEmitter.emit(BYTES_EMITTED, buffered);
       return buffered;
     }
     // Split the chunk into MAX_PUSH_CHUNK-sized slices, each getting its
@@ -112,17 +258,25 @@ export class SessionRegistry {
       const slice = bytes.subarray(off, Math.min(off + MAX_PUSH_CHUNK, bytes.byteLength));
       // subarray shares memory with the parent buffer; copy so the ring's
       // entry doesn't pin the original allocation past eviction.
-      last = entry.byteBuffer.push(Buffer.from(slice));
-      entry.byteEmitter.emit(BYTES_EMITTED, last);
+      last = channel.byteBuffer.push(Buffer.from(slice), stream);
+      channel.byteEmitter.emit(BYTES_EMITTED, last);
     }
     return last;
   }
 
-  subscribeBytes(sessionId: string, listener: (b: BufferedBytes) => void): () => void {
+  subscribeBytes(
+    sessionId: string,
+    appName: string,
+    listener: (b: BufferedBytes) => void,
+  ): () => void {
     const entry = this.sessions.get(sessionId);
     if (!entry) throw new SessionEvictedError(`session '${sessionId}' not in registry`);
-    entry.byteEmitter.on(BYTES_EMITTED, listener);
-    return () => entry.byteEmitter.off(BYTES_EMITTED, listener);
+    const channel = entry.apps.get(appName);
+    if (!channel) {
+      throw new UnknownAppError(`session '${sessionId}' runs no app named '${appName}'`);
+    }
+    channel.byteEmitter.on(BYTES_EMITTED, listener);
+    return () => channel.byteEmitter.off(BYTES_EMITTED, listener);
   }
 
   emit(sessionId: string, event: RunEvent): BufferedEvent | undefined {
@@ -133,13 +287,71 @@ export class SessionRegistry {
       entry.status = event.status;
       if (isTerminal(event.status)) {
         entry.exitedAt = new Date();
-        this.scheduleEviction(entry);
+        this.scheduleEviction(entry, this.deps.exitTtlMs);
+      } else if (event.status.kind === "suspended") {
+        // Not terminal — the record and its checkpoint outlive the pod — but it
+        // still needs its own ceiling, or suspended records accumulate forever.
+        this.scheduleEviction(entry, this.deps.suspendedTtlMs);
+      } else {
+        this.cancelEviction(entry);
       }
     }
     entry.emitter.emit(EVENT_EMITTED, buffered);
     return buffered;
   }
 
+  /** Begin a generation for one app and emit its `run.started`. Returns the new
+   *  generation number, or undefined when the app is unknown. */
+  startGeneration(
+    sessionId: string,
+    appName: string,
+    trigger: "initial" | "watch" | "manual" | "resume",
+  ): number | undefined {
+    const channel = this.sessions.get(sessionId)?.apps.get(appName);
+    if (!channel) return undefined;
+    channel.generation += 1;
+    channel.startedAt = Date.now();
+    this.emit(sessionId, {
+      type: "run",
+      app: appName,
+      generation: channel.generation,
+      phase: "started",
+      trigger,
+    });
+    return channel.generation;
+  }
+
+  /** Close the current generation of one app. A completion leaves the SESSION
+   *  status untouched — that is the whole point of the split. */
+  finishGeneration(
+    sessionId: string,
+    appName: string,
+    outcome: { phase: "completed"; code: number } | { phase: "failed"; reason: string },
+  ): void {
+    const channel = this.sessions.get(sessionId)?.apps.get(appName);
+    if (!channel || channel.generation === 0) return;
+    const durationMs = channel.startedAt === null ? undefined : Date.now() - channel.startedAt;
+    channel.startedAt = null;
+    if (outcome.phase === "completed") {
+      this.emit(sessionId, {
+        type: "run",
+        app: appName,
+        generation: channel.generation,
+        phase: "completed",
+        code: outcome.code,
+        durationMs,
+      });
+    } else {
+      this.emit(sessionId, {
+        type: "run",
+        app: appName,
+        generation: channel.generation,
+        phase: "failed",
+        reason: outcome.reason,
+      });
+    }
+  }
+
   subscribe(sessionId: string, listener: (e: BufferedEvent) => void): () => void {
     const entry = this.sessions.get(sessionId);
     if (!entry) throw new SessionEvictedError(`session '${sessionId}' not in registry`);
@@ -147,25 +359,64 @@ export class SessionRegistry {
     return () => entry.emitter.off(EVENT_EMITTED, listener);
   }
 
-  /** Free a slot at capacity by removing the oldest already-terminated session
-   *  (by exit time). Retained exited sessions are history kept for re-attach, so
-   *  they yield to a new run rather than blocking it; live sessions are never
-   *  evicted. Returns false when every session is still live. */
+  /** Count a live client. Idleness — no SSE/WS subscriber for the configured
+   *  window — is what suspends a watch session, and aggressive reaping is what
+   *  makes per-visitor watch sessions affordable; they only work as a pair. */
+  addSubscriber(sessionId: string): () => void {
+    const entry = this.sessions.get(sessionId);
+    if (!entry) return () => {};
+    entry.subscribers += 1;
+    entry.idleSince = null;
+    let released = false;
+    return () => {
+      if (released) return;
+      released = true;
+      entry.subscribers = Math.max(0, entry.subscribers - 1);
+      if (entry.subscribers === 0) entry.idleSince = Date.now();
+    };
+  }
+
+  /**
+   * Free a slot at capacity by removing the oldest RECLAIMABLE session: a
+   * terminated one (history kept for re-attach, which yields to a new run) or a
+   * SUSPENDED one.
+   *
+   * A suspended session is reclaimable because losing it costs exactly what the
+   * design already says a runner restart costs — a checkpoint the editor
+   * re-seeds from its own copy. Excluding it would let a handful of visitors who
+   * each left after five minutes hold every slot for the whole suspended TTL,
+   * which with the shipped defaults is a day.
+   *
+   * Ordered by when the session stopped being live, so the least recently
+   * abandoned goes first. Returns false when every session is still live.
+   */
   private evictOldestTerminal(): boolean {
     let oldest: SessionEntry | undefined;
+    let oldestAt = Number.POSITIVE_INFINITY;
     for (const entry of this.sessions.values()) {
-      if (entry.exitedAt === null) continue;
-      if (!oldest || entry.exitedAt < oldest.exitedAt!) oldest = entry;
+      const since = reclaimableSince(entry);
+      if (since === null || since >= oldestAt) continue;
+      oldest = entry;
+      oldestAt = since;
     }
     if (!oldest) return false;
     return this.remove(oldest.sessionId);
   }
 
-  private scheduleEviction(entry: SessionEntry): void {
-    if (entry.evictionTimer) return;
+  private cancelEviction(entry: SessionEntry): void {
+    if (!entry.evictionTimer) return;
+    clearTimeout(entry.evictionTimer);
+    entry.evictionTimer = null;
+  }
+
+  private scheduleEviction(entry: SessionEntry, ttlMs: number | undefined): void {
+    if (ttlMs === undefined) return;
+    // A resume re-arms from `running`, so an already-armed timer is replaced
+    // rather than kept — the surviving one would evict a live session.
+    this.cancelEviction(entry);
     entry.evictionTimer = setTimeout(() => {
       this.sessions.delete(entry.sessionId);
-    }, this.deps.exitTtlMs);
+    }, ttlMs);
     // Allow process exit even if evictions are pending — they are pure state,
     // not work.
     entry.evictionTimer.unref?.();
@@ -183,3 +434,12 @@ export class SessionRegistry {
     return true;
   }
 }
+
+/** When a session stopped being live, or null while it still is. A terminated
+ *  session is reclaimable from its exit; a suspended one from when it went idle
+ *  (it has no pod and its workspace is a checkpoint the editor can re-seed). */
+function reclaimableSince(entry: SessionEntry): number | null {
+  if (entry.exitedAt !== null) return entry.exitedAt.getTime();
+  if (entry.status.kind === "suspended") return entry.idleSince ?? 0;
+  return null;
+}

package/src/session/ring-buffer.test.ts

@@ -7,8 +7,8 @@ import { normalizeBundlePath, validateSessionId, BundlePathError } from "./bundl
 describe("EventRingBuffer", () => {
   it("assigns monotonic ids starting at 1 and replays after an id", () => {
     const buf = new EventRingBuffer(1_000_000);
-    buf.push({ type: "stdout", chunk: "a" });
-    buf.push({ type: "stdout", chunk: "b" });
+    buf.push({ type: "progress", phase: "boot", message: "a" });
+    buf.push({ type: "progress", phase: "boot", message: "b" });
     const { entries, hasGap } = buf.replay(1);
     expect(entries.map((e) => e.id)).toEqual([2]);
     expect(hasGap).toBe(false);
@@ -16,7 +16,8 @@ describe("EventRingBuffer", () => {
 
   it("evicts oldest entries past the byte cap but always retains the last", () => {
     const buf = new EventRingBuffer(50);
-    for (let i = 0; i < 20; i++) buf.push({ type: "stdout", chunk: "x".repeat(20) });
+    for (let i = 0; i < 20; i++)
+      buf.push({ type: "progress", phase: "boot", message: "x".repeat(20) });
     expect(buf.size).toBeGreaterThanOrEqual(1);
     expect(buf.bytes).toBeLessThanOrEqual(50 + 40);
     const { hasGap } = buf.replay(0);

package/src/session/watch-lifetime.test.ts

@@ -0,0 +1,203 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { SessionRegistry, type SessionEntry } from "./registry.js";
+import { WatchSupervisor } from "./watch-supervisor.js";
+
+function makeRegistry() {
+  return new SessionRegistry({
+    maxSessions: 4,
+    exitTtlMs: 60_000,
+    replayBufferBytes: 100_000,
+    suspendedTtlMs: 3_600_000,
+  });
+}
+
+describe("suspended is not terminal", () => {
+  it("keeps the session and schedules its own eviction, not the exit one", () => {
+    const registry = makeRegistry();
+    const entry = registry.register({ sessionId: "s1", mode: "watch" });
+    registry.emit("s1", { type: "status", status: { kind: "suspended" } });
+
+    expect(registry.has("s1")).toBe(true);
+    // `exitedAt` is what marks a session terminal for capacity eviction — a
+    // suspended session must not be a candidate.
+    expect(entry.exitedAt).toBeNull();
+    expect(entry.evictionTimer).not.toBeNull();
+  });
+
+  it("cancels the suspended eviction when the session resumes", () => {
+    const registry = makeRegistry();
+    const entry = registry.register({ sessionId: "s1", mode: "watch" });
+    registry.emit("s1", { type: "status", status: { kind: "suspended" } });
+    registry.emit("s1", { type: "status", status: { kind: "running" } });
+
+    expect(entry.evictionTimer).toBeNull();
+  });
+});
+
+describe("a suspended session does not hold a slot", () => {
+  it("is evicted to make room rather than blocking a new session", () => {
+    // Losing it costs exactly what a runner restart already costs — a checkpoint
+    // the editor re-seeds. Excluding it would let a handful of visitors who each
+    // left after five minutes hold every slot for the whole suspended TTL.
+    const registry = new SessionRegistry({
+      maxSessions: 1,
+      exitTtlMs: 60_000,
+      replayBufferBytes: 100_000,
+      suspendedTtlMs: 86_400_000,
+    });
+    registry.register({ sessionId: "old", mode: "watch" });
+    registry.emit("old", { type: "status", status: { kind: "suspended" } });
+
+    expect(() => registry.register({ sessionId: "new", mode: "watch" })).not.toThrow();
+    expect(registry.has("old")).toBe(false);
+    expect(registry.has("new")).toBe(true);
+  });
+
+  it("never evicts a live session to make room", () => {
+    const registry = new SessionRegistry({
+      maxSessions: 1,
+      exitTtlMs: 60_000,
+      replayBufferBytes: 100_000,
+    });
+    registry.register({ sessionId: "live", mode: "watch" });
+    registry.emit("live", { type: "status", status: { kind: "running" } });
+
+    expect(() => registry.register({ sessionId: "new", mode: "watch" })).toThrow();
+    expect(registry.has("live")).toBe(true);
+  });
+});
+
+describe("byte channels are per app", () => {
+  it("routes a push to the named app and drops one for an unknown name", () => {
+    const registry = makeRegistry();
+    const entry = registry.register({
+      sessionId: "s1",
+      mode: "watch",
+      apps: [{ name: "web" }, { name: "worker" }],
+    });
+
+    registry.pushBytes("s1", "web", Buffer.from("hello"));
+    expect(entry.apps.get("web")!.byteBuffer.size).toBe(1);
+    expect(entry.apps.get("worker")!.byteBuffer.size).toBe(0);
+
+    expect(registry.pushBytes("s1", "nope", Buffer.from("x"))).toBeUndefined();
+  });
+
+  it("carries the stream tag through the buffer", () => {
+    const registry = makeRegistry();
+    registry.register({ sessionId: "s1", apps: [{ name: "app", io: "streams" }] });
+    registry.pushBytes("s1", "app", Buffer.from("out"), "stdout");
+    registry.pushBytes("s1", "app", Buffer.from("err"), "stderr");
+
+    const entries = registry.get("s1")!.apps.get("app")!.byteBuffer.replay(0).entries;
+    expect(entries.map((e) => e.stream)).toEqual(["stdout", "stderr"]);
+  });
+
+  it("has a sole app only when the session runs exactly one", () => {
+    const registry = makeRegistry();
+    const one = registry.register({ sessionId: "s1" });
+    const two = registry.register({
+      sessionId: "s2",
+      apps: [{ name: "web" }, { name: "worker" }],
+    });
+
+    expect(registry.soleApp(one)?.name).toBe("app");
+    expect(registry.soleApp(two)).toBeUndefined();
+  });
+});
+
+describe("WatchSupervisor", () => {
+  function watchEntry(registry: SessionRegistry, snapshot = vi.fn(async () => [])) {
+    const entry = registry.register({ sessionId: "s1", mode: "watch" });
+    const suspend = vi.fn(async () => {});
+    entry.session = {
+      writeStdin: () => {},
+      resize: () => {},
+      done: Promise.resolve(),
+      stop: async () => {},
+      suspend,
+      workspace: {
+        tree: async () => ({ files: [] }),
+        readFile: async () => ({ content: "", size: 0 }),
+        apply: async () => ({ written: 0, deleted: 0 }),
+        snapshot,
+      },
+    } as unknown as SessionEntry["session"];
+    registry.emit("s1", { type: "status", status: { kind: "running" } });
+    return { entry, suspend, snapshot };
+  }
+
+  it("checkpoints on the timer while a client is attached", async () => {
+    const registry = makeRegistry();
+    const { entry, suspend, snapshot } = watchEntry(registry);
+    registry.addSubscriber("s1");
+    const supervisor = new WatchSupervisor({ registry, idleMs: 0, checkpointMs: 0 });
+
+    await supervisor.tick();
+    await vi.waitFor(() => expect(snapshot).toHaveBeenCalled());
+
+    expect(suspend).not.toHaveBeenCalled();
+    expect(entry.checkpoint).not.toBeNull();
+  });
+
+  it("snapshots before suspending — the volume dies with the pod", async () => {
+    const registry = makeRegistry();
+    const order: string[] = [];
+    const snapshot = vi.fn(async () => {
+      order.push("snapshot");
+      return [];
+    });
+    const { entry, suspend } = watchEntry(registry, snapshot);
+    suspend.mockImplementation(async () => {
+      order.push("suspend");
+    });
+    // No subscriber was ever added, so the entry is idle from registration.
+    const supervisor = new WatchSupervisor({ registry, idleMs: 0, checkpointMs: 60_000 });
+
+    await supervisor.tick();
+    await vi.waitFor(() => expect(entry.status.kind).toBe("suspended"));
+
+    expect(order).toEqual(["snapshot", "suspend"]);
+    expect(entry.session).toBeNull();
+  });
+
+  it("does not suspend while a client is attached", async () => {
+    const registry = makeRegistry();
+    const { suspend } = watchEntry(registry);
+    registry.addSubscriber("s1");
+    const supervisor = new WatchSupervisor({ registry, idleMs: 0, checkpointMs: 60_000 });
+
+    await supervisor.tick();
+    await new Promise((r) => setTimeout(r, 20));
+
+    expect(suspend).not.toHaveBeenCalled();
+  });
+
+  it("becomes idle again once the last subscriber detaches", async () => {
+    const registry = makeRegistry();
+    const { entry, suspend } = watchEntry(registry);
+    const release = registry.addSubscriber("s1");
+    expect(entry.idleSince).toBeNull();
+    release();
+    expect(entry.idleSince).not.toBeNull();
+
+    const supervisor = new WatchSupervisor({ registry, idleMs: 0, checkpointMs: 60_000 });
+    await supervisor.tick();
+    await vi.waitFor(() => expect(suspend).toHaveBeenCalled());
+  });
+
+  it("leaves run sessions alone", async () => {
+    const registry = makeRegistry();
+    const entry = registry.register({ sessionId: "s2", mode: "run" });
+    const suspend = vi.fn(async () => {});
+    entry.session = { suspend } as unknown as SessionEntry["session"];
+    registry.emit("s2", { type: "status", status: { kind: "running" } });
+
+    const supervisor = new WatchSupervisor({ registry, idleMs: 0, checkpointMs: 0 });
+    await supervisor.tick();
+    await new Promise((r) => setTimeout(r, 20));
+
+    expect(suspend).not.toHaveBeenCalled();
+  });
+});