@telorun/runner-core 0.8.2 → 0.9.0

package/dist/session/registry.d.ts

@@ -1,15 +1,38 @@
 import { EventEmitter } from "node:events";
-import type { BackendSession } from "../backend.js";
-import { type RunEvent, type RunStatus } from "../contract.js";
+import type { DebugFrame } from "@telorun/debug-wire";
+import type { BackendSession, WorkloadLaunch } from "../backend.js";
+import { 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
      *  the workload has terminated, so callers need not null it on exit. */
@@ -18,16 +41,88 @@ 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;
 }
 export declare class SessionLimitError extends Error {
 }
 export declare class SessionEvictedError extends Error {
 }
+export declare 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 declare class SessionRegistry {
     private readonly deps;
     private readonly sessions;
@@ -40,18 +135,54 @@ export declare 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;
-    pushBytes(sessionId: string, bytes: Buffer): BufferedBytes | undefined;
-    subscribeBytes(sessionId: string, listener: (b: BufferedBytes) => void): () => void;
+    register(args: RegisterArgs): SessionEntry;
+    /** 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;
+    /** 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;
+    pushBytes(sessionId: string, appName: string, bytes: Buffer, stream?: ByteStreamTag): BufferedBytes | undefined;
+    subscribeBytes(sessionId: string, appName: string, listener: (b: BufferedBytes) => void): () => void;
     emit(sessionId: string, event: RunEvent): BufferedEvent | undefined;
+    /** 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;
+    /** 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;
     subscribe(sessionId: string, listener: (e: BufferedEvent) => void): () => void;
-    /** 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;
+    /**
+     * 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;
+    private cancelEviction;
     private scheduleEviction;
     /**
      * Remove an entry immediately (used by shutdown sweeps and startup cleanup).

package/dist/session/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/session/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAc,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEvE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC;IAEnC;;4EAEwE;IACxE,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,SAAS,CAAC;IAClB,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAaD,qBAAa,iBAAkB,SAAQ,KAAK;CAAG;AAC/C,qBAAa,mBAAoB,SAAQ,KAAK;CAAG;AAEjD,qBAAa,eAAe;IAGd,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;gBAE/B,IAAI,EAAE,YAAY;IAE/C,IAAI,IAAI,MAAM;IAId,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAI/B,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAIhD,IAAI,IAAI,YAAY,EAAE;IAItB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,YAAY;IA6BnD,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAqBtE,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,aAAa,KAAK,IAAI,GAAG,MAAM,IAAI;IAOnF,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,aAAa,GAAG,SAAS;IAenE,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,aAAa,KAAK,IAAI,GAAG,MAAM,IAAI;IAO9E;;;mEAG+D;IAC/D,OAAO,CAAC,mBAAmB;IAU3B,OAAO,CAAC,gBAAgB;IAUxB;;;OAGG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;CAOnC"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/session/registry.ts"],"names":[],"mappings":"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"}

package/dist/session/registry.js

@@ -1,5 +1,5 @@
 import { EventEmitter } from "node:events";
-import { isTerminal } from "../contract.js";
+import { DEFAULT_APP_NAME, isTerminal, } from "../contract.js";
 import { ByteRingBuffer } from "./byte-ring-buffer.js";
 import { EventRingBuffer } from "./ring-buffer.js";
 const EVENT_EMITTED = "event";
@@ -15,6 +15,8 @@ export class SessionLimitError extends Error {
 }
 export class SessionEvictedError extends Error {
 }
+export class UnknownAppError extends Error {
+}
 export class SessionRegistry {
     deps;
     sessions = new Map();
@@ -44,32 +46,64 @@ export class SessionRegistry {
         const entry = {
             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, bytes) {
-        const entry = this.sessions.get(sessionId);
-        if (!entry)
+    /** 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, app) {
+        const channel = {
+            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) {
+        return entry.apps.size === 1 ? entry.apps.values().next().value : undefined;
+    }
+    pushBytes(sessionId, appName, bytes, stream = "tty") {
+        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
@@ -79,17 +113,21 @@ 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, listener) {
+    subscribeBytes(sessionId, appName, listener) {
         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, event) {
         const entry = this.sessions.get(sessionId);
@@ -100,12 +138,65 @@ 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, appName, trigger) {
+        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, appName, outcome) {
+        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, listener) {
         const entry = this.sessions.get(sessionId);
         if (!entry)
@@ -113,28 +204,68 @@ export class SessionRegistry {
         entry.emitter.on(EVENT_EMITTED, listener);
         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) {
+        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.
+     */
     evictOldestTerminal() {
         let oldest;
+        let oldestAt = Number.POSITIVE_INFINITY;
         for (const entry of this.sessions.values()) {
-            if (entry.exitedAt === null)
+            const since = reclaimableSince(entry);
+            if (since === null || since >= oldestAt)
                 continue;
-            if (!oldest || entry.exitedAt < oldest.exitedAt)
-                oldest = entry;
+            oldest = entry;
+            oldestAt = since;
         }
         if (!oldest)
             return false;
         return this.remove(oldest.sessionId);
     }
-    scheduleEviction(entry) {
-        if (entry.evictionTimer)
+    cancelEviction(entry) {
+        if (!entry.evictionTimer)
             return;
+        clearTimeout(entry.evictionTimer);
+        entry.evictionTimer = null;
+    }
+    scheduleEviction(entry, ttlMs) {
+        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?.();
@@ -153,4 +284,14 @@ 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) {
+    if (entry.exitedAt !== null)
+        return entry.exitedAt.getTime();
+    if (entry.status.kind === "suspended")
+        return entry.idleSince ?? 0;
+    return null;
+}
 //# sourceMappingURL=registry.js.map

package/dist/session/registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/session/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,EAAE,UAAU,EAAiC,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAsB,MAAM,uBAAuB,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAsB,MAAM,kBAAkB,CAAC;AA0BvE,MAAM,aAAa,GAAG,OAAO,CAAC;AAC9B,MAAM,aAAa,GAAG,OAAO,CAAC;AAE9B;;;;;sCAKsC;AACtC,MAAM,cAAc,GAAG,EAAE,GAAG,IAAI,CAAC;AAEjC,MAAM,OAAO,iBAAkB,SAAQ,KAAK;CAAG;AAC/C,MAAM,OAAO,mBAAoB,SAAQ,KAAK;CAAG;AAEjD,MAAM,OAAO,eAAe;IAGG;IAFZ,QAAQ,GAAG,IAAI,GAAG,EAAwB,CAAC;IAE5D,YAA6B,IAAkB;QAAlB,SAAI,GAAJ,IAAI,CAAc;IAAG,CAAC;IAEnD,IAAI;QACF,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;IAC5B,CAAC;IAED,GAAG,CAAC,SAAiB;QACnB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACtC,CAAC;IAED,GAAG,CAAC,SAAiB;QACnB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACtC,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACrC,CAAC;IAED;;;OAGG;IACH,QAAQ,CAAC,IAA2B;QAClC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,CAAC;YAC/E,MAAM,IAAI,iBAAiB,CACzB,sCAAsC,IAAI,CAAC,IAAI,CAAC,WAAW,sBAAsB,CAClF,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,GAAiB;YAC1B,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,SAAS,EAAE,IAAI,IAAI,EAAE;YACrB,MAAM,EAAE,IAAI,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC;YACxD,UAAU,EAAE,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC;YAC3D,OAAO,EAAE,IAAI,YAAY,EAAE;YAC3B,WAAW,EAAE,IAAI,YAAY,EAAE;YAC/B,OAAO,EAAE,IAAI;YACb,MAAM,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE;YAC5B,QAAQ,EAAE,IAAI;YACd,WAAW,EAAE,KAAK;YAClB,aAAa,EAAE,IAAI;SACpB,CAAC;QACF,uEAAuE;QACvE,qEAAqE;QACrE,wEAAwE;QACxE,8CAA8C;QAC9C,KAAK,CAAC,OAAO,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;QACnC,KAAK,CAAC,WAAW,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QACzC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,SAAS,CAAC,SAAiB,EAAE,KAAa;QACxC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAC7B,IAAI,KAAK,CAAC,UAAU,IAAI,cAAc,EAAE,CAAC;YACvC,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC9C,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;YAChD,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,qEAAqE;QACrE,yEAAyE;QACzE,IAAI,IAA+B,CAAC;QACpC,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,KAAK,CAAC,UAAU,EAAE,GAAG,IAAI,cAAc,EAAE,CAAC;YAChE,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,cAAc,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;YACpF,oEAAoE;YACpE,2DAA2D;YAC3D,IAAI,GAAG,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;YACjD,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;QAC9C,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,cAAc,CAAC,SAAiB,EAAE,QAAoC;QACpE,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,mBAAmB,CAAC,YAAY,SAAS,mBAAmB,CAAC,CAAC;QACpF,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;QAC9C,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;IAC9D,CAAC;IAED,IAAI,CAAC,SAAiB,EAAE,KAAe;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAC7B,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC5B,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;YAC5B,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC7B,KAAK,CAAC,QAAQ,GAAG,IAAI,IAAI,EAAE,CAAC;gBAC5B,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;QAC5C,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,SAAS,CAAC,SAAiB,EAAE,QAAoC;QAC/D,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,mBAAmB,CAAC,YAAY,SAAS,mBAAmB,CAAC,CAAC;QACpF,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;QAC1C,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;IAC1D,CAAC;IAED;;;mEAG+D;IACvD,mBAAmB;QACzB,IAAI,MAAgC,CAAC;QACrC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;YAC3C,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI;gBAAE,SAAS;YACtC,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAS;gBAAE,MAAM,GAAG,KAAK,CAAC;QACnE,CAAC;QACD,IAAI,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QAC1B,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;IAEO,gBAAgB,CAAC,KAAmB;QAC1C,IAAI,KAAK,CAAC,aAAa;YAAE,OAAO;QAChC,KAAK,CAAC,aAAa,GAAG,UAAU,CAAC,GAAG,EAAE;YACpC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACxC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACxB,0EAA0E;QAC1E,YAAY;QACZ,KAAK,CAAC,aAAa,CAAC,KAAK,EAAE,EAAE,CAAC;IAChC,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,SAAiB;QACtB,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACzB,IAAI,KAAK,CAAC,aAAa;YAAE,YAAY,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QAC3D,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/session/registry.ts"],"names":[],"mappings":"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"}

package/dist/session/watch-supervisor.d.ts

@@ -0,0 +1,42 @@
+import type { SessionRegistry } from "./registry.js";
+export interface WatchSupervisorDeps {
+    registry: SessionRegistry;
+    /** No SSE/WS subscriber for this long → suspend. */
+    idleMs: number;
+    /** How often to pull a whole-tree workspace snapshot. */
+    checkpointMs: number;
+    log?: {
+        warn(obj: unknown, msg: string): void;
+    };
+}
+/**
+ * The two background jobs that make a watch session affordable, and they only
+ * work as a pair: a periodic workspace checkpoint, and an idle reap that deletes
+ * the pod while keeping the session record and that checkpoint.
+ *
+ * Aggressive reaping is what makes per-visitor watch sessions affordable, and
+ * the checkpoint is what makes aggressive reaping safe to do.
+ *
+ * The checkpoint is a CACHE, never the only copy. The runner is a single replica
+ * with an in-memory registry, so a redeploy or crash drops every suspended
+ * session — the editor holds the authoritative workspace, already diffs its own
+ * files against `GET /workspace`, and on a `404` at resume creates a new session
+ * and re-seeds from its own copy in one change set. What the checkpoint saves is
+ * that upload.
+ */
+export declare class WatchSupervisor {
+    private readonly deps;
+    private timer;
+    /** Sessions with a checkpoint or suspend in flight, so a slow snapshot cannot
+     *  have a second one started on top of it every tick. */
+    private readonly busy;
+    constructor(deps: WatchSupervisorDeps);
+    start(): void;
+    stop(): void;
+    /** Exposed for tests, which drive the clock rather than waiting on it. */
+    tick(): Promise<void>;
+    private run;
+    private checkpoint;
+    private suspend;
+}
+//# sourceMappingURL=watch-supervisor.d.ts.map

package/dist/session/watch-supervisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-supervisor.d.ts","sourceRoot":"","sources":["../../src/session/watch-supervisor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,eAAe,EAAE,MAAM,eAAe,CAAC;AAEnE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,eAAe,CAAC;IAC1B,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CACjD;AAOD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,eAAe;IAMd,OAAO,CAAC,QAAQ,CAAC,IAAI;IALjC,OAAO,CAAC,KAAK,CAA+B;IAC5C;6DACyD;IACzD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;gBAEb,IAAI,EAAE,mBAAmB;IAEtD,KAAK,IAAI,IAAI;IAMb,IAAI,IAAI,IAAI;IAMZ,0EAA0E;IACpE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAuBb,GAAG;YAiBH,UAAU;YAQV,OAAO;CAWtB"}