@telorun/runner-core 0.8.2 → 0.10.0

package/src/backend.ts

@@ -1,14 +1,22 @@
 import type { DebugFrame } from "@telorun/debug-wire";
 
+import type { ResolvedRunnerApp } from "./config.js";
 import type {
   AvailabilityReport,
+  ByteStreamTag,
+  IoMode,
   PortMapping,
   ProbeConfig,
   ReachabilityState,
   RunBundle,
+  RunnerEndpoint,
   RunPhase,
   RunStatus,
   SessionConfig,
+  SessionMode,
+  WorkspaceChangeSet,
+  WorkspaceCheckpointFile,
+  WorkspaceTree,
 } from "./contract.js";
 
 /**
@@ -40,59 +48,140 @@ export interface RunnerBackend {
   reapOrphans?(): Promise<void>;
 }
 
-export interface BackendStartSpec {
-  sessionId: string;
-  bundle: RunBundle;
-  /** Bundle-relative entry path, already traversal-normalized by core. */
+/** One application container the backend must stand up. */
+export interface BackendAppSpec {
+  name: string;
+  /** Bundle-relative entry path, already traversal-normalized by core. Empty for
+   *  a self-contained app session, where the image's own entrypoint runs. */
   entryRelativePath: string;
-  env: Record<string, string>;
   ports: PortMapping[];
+  io: IoMode;
+}
+
+/**
+ * The DATA half of a workload launch — everything a start needs that is not a
+ * callback. Retained on the session entry so `resume` can build a fresh pod
+ * under the same session id from the same description, rather than a second,
+ * drifting copy of it.
+ */
+export interface WorkloadLaunch {
+  bundle: RunBundle;
+  env: Record<string, string>;
   config: SessionConfig;
   /** True for an operator-predefined app session (`POST /v1/apps/:name/sessions`):
    *  `config.image` is self-contained (app + controllers baked in), so the
    *  backend runs the image's own entrypoint and stages no bundle — `bundle`
    *  is an empty placeholder. */
   selfContained: boolean;
-  /** When true, launch the workload with `--inspect` and relay its kernel debug
+  /** When true, launch each app with `--inspect` and relay its kernel debug
    *  stream via `onDebug`. The inspect endpoint stays reachable only by the
-   *  runner — never published outward. */
+   *  runner — never published outward. Always true for a watch session: that
+   *  stream is where `run` events are projected from. */
   inspect: boolean;
+  /** `run` (one pod, terminal on exit, today's shape) or `watch` (a workspace
+   *  volume, `telo run --watch` per app, the pod outliving its runs). */
+  mode: SessionMode;
+  /** The applications to run, one container each. Never empty — core defaults a
+   *  request with no `apps` to a single entry. */
+  apps: BackendAppSpec[];
+  /** The resolved catalog entry for a co-resident agent container, when one was
+   *  requested. Its operator env goes on THAT container and nowhere else — the
+   *  credential boundary used to be structural (two pods) and is now a code
+   *  invariant (containers in one pod). */
+  agent?: ResolvedRunnerApp;
+}
+
+export interface BackendStartSpec extends WorkloadLaunch {
+  sessionId: string;
 
   /** Emit a lifecycle status. The backend drives `starting` → `running` →
-   *  terminal (`exited`/`failed`/`stopped`). */
+   *  terminal (`exited`/`failed`/`stopped`), or `suspended` on an idle reap. */
   onStatus(status: RunStatus): void;
   /** Emit a progress message for a coming-up phase (build / provision / boot).
    *  Additive to status — surfaces what's happening while the session is still
-   *  `starting`, driving the editor's spinner + step feed. */
-  onProgress(phase: RunPhase, message: string, done?: boolean): void;
-  /** Raw merged stdout/stderr (PTY) bytes from the workload. */
-  onOutput(chunk: Buffer): void;
-  /** A frame relayed from the workload's kernel debug stream. Only called when
-   *  `inspect` is true and the backend has connected to the inspect endpoint. */
-  onDebug(frame: DebugFrame): void;
+   *  `starting`. `app` is omitted for session-scoped provisioning. */
+  onProgress(phase: RunPhase, message: string, done?: boolean, app?: string): void;
+  /** Bytes from one app's terminal. `stream` is `tty` under a terminal attach
+   *  and `stdout`/`stderr` only where the transport genuinely separated them. */
+  onOutput(app: string, chunk: Buffer, stream: ByteStreamTag): void;
+  /** A frame relayed from one app's kernel debug stream. Only called when
+   *  `inspect` is true and the backend has connected to that app's endpoint. */
+  onDebug(app: string, frame: DebugFrame): void;
   /** Report a declared port's reachability from the runner network — `checking`
    *  while the workload comes up, then `reachable`, or `unreachable` after a
    *  timeout. Surfaced on the editor's endpoint badge, not the log stream. */
-  onReachability(port: number, state: ReachabilityState): void;
+  onReachability(app: string, port: number, state: ReachabilityState): void;
+  /** One app's workload ended on its own. A run session's workload ending IS the
+   *  session ending, so this is a watch-session concern: under `--watch` a
+   *  finished run leaves the container up, and a container that goes away has
+   *  died. Reported through the contract rather than by synthesizing a kernel
+   *  frame — that stream's contract is "frames relayed from the workload", and a
+   *  backend writing into it puts an event on the wire no kernel emitted. */
+  onRunEnded(app: string, outcome: { code?: number; reason?: string }): void;
+  /** An app's routable endpoint set changed after a reload re-read its declared
+   *  ports. */
+  onEndpoints(
+    app: string,
+    change: {
+      added?: RunnerEndpoint[];
+      removed?: RunnerEndpoint[];
+      rejected?: Array<{ port: number; reason: string }>;
+    },
+  ): void;
   /** True once a user stop / shutdown has been requested — lets the backend
    *  classify a kill as `stopped` rather than `failed`. */
   isUserStopped(): boolean;
 }
 
 export interface BackendSession {
-  /** Write bytes to the workload's stdin (PTY). A no-op once the workload has
-   *  terminated, so callers need not track liveness. */
-  writeStdin(bytes: Uint8Array): void;
+  /** Write bytes to one app's stdin. A no-op once that workload has terminated,
+   *  so callers need not track liveness. */
+  writeStdin(app: string, bytes: Uint8Array): void;
 
-  /** Resize the workload's PTY. */
-  resize(cols: number, rows: number): void;
+  /** Resize one app's PTY. A no-op for an app running under `io: "streams"` —
+   *  the route rejects such a resize before it reaches here. */
+  resize(app: string, cols: number, rows: number): void;
 
   /** Resolves after the workload terminates and its terminal status has been
    *  emitted via `onStatus`. Never rejects — terminal failures surface as a
-   *  `failed` status. */
+   *  `failed` status. A watch session's workload outlives its runs, so this
+   *  settles only on stop, suspend, or the pod deadline. */
   readonly done: Promise<void>;
 
   /** Force-stop the workload. Idempotent and safe to call after natural exit
    *  (a backend should treat an already-gone workload as a no-op). */
   stop(): Promise<void>;
+
+  /** The workspace surface, present only on a watch session. Everything outside
+   *  the pod writes through here; the agent (inside it) writes the volume with
+   *  its own filesystem tools. */
+  readonly workspace?: WorkspaceAccess;
+
+  /** Re-run one app with no file change (`POST /v1/sessions/:id/reload`), by
+   *  touching its entry manifest through the same path every other write takes.
+   *  No signalling into the container, no shared PID namespace, no `exec` — RBAC
+   *  is unchanged. Watch sessions only. */
+  reload?(app: string): Promise<void>;
+
+  /** Replace the running app set. A pod's container list is fixed at creation,
+   *  so this checkpoints, deletes the pod and creates one with the new set —
+   *  the suspend/resume path, reused because it has to be. */
+  setApps?(apps: BackendAppSpec[]): Promise<void>;
+
+  /** Delete the workload, keeping nothing but what the caller already
+   *  checkpointed. `resume` builds a fresh one from that checkpoint. */
+  suspend?(): Promise<void>;
+}
+
+/** The `workspace` container's routes, proxied by the runner. Reading and
+ *  applying a change set are the only two shapes: a single-file write route
+ *  would be a second set of concurrency rules over the same directory. */
+export interface WorkspaceAccess {
+  tree(): Promise<WorkspaceTree>;
+  readFile(path: string): Promise<{ content: string; size: number }>;
+  apply(changes: WorkspaceChangeSet): Promise<{ written: number; deleted: number }>;
+  /** Whole-tree pull for the checkpoint timer and for suspend. Whole tree rather
+   *  than a delta log: a manifest workspace is small, and one shape is easier to
+   *  reason about than a replay that has to be correct. */
+  snapshot(): Promise<WorkspaceCheckpointFile[]>;
 }

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 {}
@@ -110,6 +137,15 @@ export interface RunnerAppConfig {
   /** Workload image pull policy (default `missing`); `always` keeps a moving
    *  tag like `latest-slim` fresh. */
   pullPolicy?: PullPolicy;
+  /** The tcp port this image listens on, published by the runner when the entry
+   *  is used as a session's co-resident `agent` — a client cannot supply it,
+   *  because what gets published is the operator's decision, not the caller's.
+   *  There is deliberately NO default: the catalog is pure operator
+   *  configuration and the runner has no built-in knowledge of any specific
+   *  app, so guessing 8080 would be exactly that knowledge. An entry without it
+   *  still works as a standalone app session (where the client declares the
+   *  ports it wants published); only `agent` use requires it. */
+  port?: number;
   title?: string;
   description?: string;
 }
@@ -120,6 +156,9 @@ export interface ResolvedRunnerApp {
   image: string;
   env: Record<string, string>;
   pullPolicy: PullPolicy;
+  /** See {@link RunnerAppConfig.port} — undefined when the operator declared
+   *  none, which is what makes the entry unusable as an `agent`. */
+  port?: number;
   title?: string;
   description?: string;
 }
@@ -179,6 +218,12 @@ function validateAppEntry(name: string, value: unknown): RunnerAppConfig {
   if (entry.pullPolicy !== undefined && !PULL_POLICIES.includes(entry.pullPolicy as string)) {
     fail(`has an invalid 'pullPolicy' — expected one of ${PULL_POLICIES.join(", ")}.`);
   }
+  if (
+    entry.port !== undefined &&
+    (typeof entry.port !== "number" || !Number.isInteger(entry.port) || entry.port < 1 || entry.port > 65535)
+  ) {
+    fail("has an invalid 'port' — expected an integer in 1..65535.");
+  }
   for (const key of ["title", "description"] as const) {
     if (entry[key] !== undefined && typeof entry[key] !== "string") {
       fail(`has an invalid '${key}' — expected a string.`);
@@ -187,6 +232,26 @@ function validateAppEntry(name: string, value: unknown): RunnerAppConfig {
   return entry as unknown as RunnerAppConfig;
 }
 
+/**
+ * Which catalog entries may be a session's co-resident `agent` — the ones that
+ * declare a `port`, because the session route refuses the rest and a runner
+ * must not advertise what it will reject.
+ *
+ * Derived here rather than in each runner's capabilities call because this IS
+ * the acceptance condition: the two used to be one list by construction
+ * (`Object.keys`), and adding a second condition to the route without adding it
+ * here is exactly how they drift. An operator upgrading with an existing
+ * catalog has no `port` anywhere — the field is new — so an unfiltered
+ * advertisement makes the editor attach an agent to every run and every run is
+ * refused.
+ *
+ * Per entry, not per catalog: declaring a port opts an app into co-resident
+ * use, omitting one leaves it launchable on its own.
+ */
+export function coResidentAgentNames(apps: Record<string, ResolvedRunnerApp>): string[] {
+  return Object.keys(apps).filter((name) => apps[name]?.port !== undefined);
+}
+
 /** The catalog runners pass to `buildServer`: `RUNNER_APPS` validated with
  *  defaults applied; empty when unset. The catalog is pure operator
  *  configuration — runner-core knows nothing about any specific app. */
@@ -199,6 +264,7 @@ export function loadResolvedApps(env: NodeJS.ProcessEnv): Record<string, Resolve
       image: entry.image,
       env: entry.env ?? {},
       pullPolicy: entry.pullPolicy ?? "missing",
+      port: entry.port,
       title: entry.title,
       description: entry.description,
     };
@@ -233,5 +299,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,60 @@ 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. */
-  | { kind: "running"; endpoints?: RunnerEndpoint[]; inspectUrl?: string }
+  /** 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.
+   *
+   *  `agent` is where this session's co-resident agent answers, present only on
+   *  a session that requested one AND that this runner could route. An ENDPOINT
+   *  rather than a URL string because the no-proxy case is real — a docker
+   *  runner publishing to the host knows the port and not the hostname the
+   *  client reached it by, exactly as for an app's endpoint, so the client
+   *  fills an empty `host` from its own base URL. Carried here and not in
+   *  `endpoints` because the agent is session infrastructure: `endpoints` are
+   *  the ports the APPLICATIONS declared, and merging the two would make an
+   *  operator-run container look like part of the user's manifest. */
+  | {
+      kind: "running";
+      endpoints?: RunnerEndpoint[];
+      inspectUrl?: string;
+      agent?: RunnerEndpoint;
+    }
   | { 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 +257,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