@workerdeck/server 0.16.0 → 0.17.0

package/README.md

@@ -208,6 +208,16 @@ OAuth, never reads or forwards tokens — see the repo README's
   VFS only when *not* restoring, and dispose per-session resources via `onClose`. Every one is a
   runtime-only failure. `createProviderRunner()` does all four; reach for the raw hook only when it
   genuinely doesn't fit.
+- **`parking.persistLive` is how a *provider* session survives a restart, and it needs a durable
+  store to mean anything.** Claude and codex go dormant — remembered by engine session id and
+  resumed from the engine's own store — which a provider session cannot do, so its record carries
+  the state itself, written through after every turn. With the default in-memory store the option
+  does nothing and says nothing. It is off by default: a library must not start writing sessions'
+  transcripts to disk because someone upgraded, and the record holds the whole transcript in
+  plaintext.
+- **A restored session is refreshed in place, not consumed.** A park's record *is* the session and
+  is deleted on wake; a live or dormant one is a way back the session still needs next time. If you
+  implement a `SessionStore`, do not "tidy up" a record on read.
 - **One origin is not a convenience.** A browser cannot put an `Authorization` header on a
   WebSocket upgrade, so a cookie is the only credential a tab can present on an attach, and a
   cookie is per-origin. That is what `fallback` is for — an app served from the gateway's own port.

package/build/index.d.mts

@@ -48,6 +48,11 @@ type SessionNotificationOptions = {
   onNotification?: (notification: SessionNotification) => void; /** Delivery attempts per notification (exponential backoff). Default 3. */
   attempts?: number; /** Initial backoff between attempts. Default 500ms. */
   retryDelayMs?: number;
+  /** Gateway wiring, not a host option: the serve-time `SessionInfo` decoration
+   * (project identity today), so a webhook or push consumer reads the same
+   * record every REST caller does. The assembly supplies it; identity when
+   * absent. */
+  decorateInfo?: (info: SessionInfo) => SessionInfo;
 };
 /**
  * Turns session events into the handful of notifications a human away from the
@@ -111,20 +116,41 @@ declare class SessionRegistry {
 //#endregion
 //#region src/services/session-store.d.ts
 /**
- * A session with its live runner torn down, waiting on deferred executions.
+ * A session captured whole: its wire-visible info, the config to rebuild the
+ * runner, the engine's snapshot, and what it is waiting for.
  *
- * Everything needed to bring it back: the wire-visible info (so it still lists and
- * reads over REST while parked), the config to rebuild the runner, the engine's
- * snapshot, and what it is waiting for.
+ * Two things are stored in this one shape, and the discriminator is `kind`:
+ *
+ * - **`parked`** — the live runner is torn down and the session is waiting on
+ *   deferred executions. The record *is* the session, so waking consumes it.
+ * - **`live`** — the runner is up and this is a copy taken after a turn, so the
+ *   session survives a restart (`persistLive`). It is a way back that the
+ *   session still needs the *next* time the process dies, so waking **refreshes
+ *   it in place** and only `session_closed` removes it.
+ *
+ * That difference is the whole reason these are two kinds rather than one, and
+ * it is a correctness difference, not bookkeeping: consuming a live record on
+ * wake opens a window from the attach to the next turn in which the session
+ * exists nowhere durable. A user who opens a session, reads it and types nothing
+ * would lose it to a redeploy — silently, which is the failure class worth
+ * spending a discriminator on.
+ *
+ * They share the shape so a store, and an older server, need no new code: every
+ * other branch (rebuild from `config` + `snapshot`, serve `snapshot.vfs`, arm
+ * `executions`, subscribe past `snapshot.seq`) is already right for both.
  */
 type ParkedSessionRecord = {
-  /** Absent on records written before dormant sessions existed — those are all parked. */kind?: 'parked';
-  id: string; /** Session info as of the park, with `status: 'parked'`. */
+  /** Absent on records written before dormant sessions existed — those are all parked. */kind?: 'parked' | 'live';
+  id: string;
+  /** Session info as of the write: `parked` for a park, `idle` for a live copy —
+   * never `running`, which would come back as a spinner over no process. */
   info: SessionInfo;
   profile?: string; /** The config the session was created with (profile defaults already applied). */
   config: SessionRunnerConfig;
   snapshot: RunnerSnapshot;
-  executions: ParkedExecution[];
+  /** Empty for a live record: an idle session is waiting on nothing, so there is
+   * nothing for `hydrate` to arm a watchdog for. */
+  executions: ParkedExecution[]; /** When it was written. Named for the park that came first. */
   parkedAt: number;
 };
 /**
@@ -246,6 +272,24 @@ type SessionParkOptions = {
   /** Wait this long after the last client detaches before parking, so a reconnect
    * (a wifi blip, a page reload) doesn't cost a teardown. Default 2000. */
   parkDelayMs?: number;
+  /**
+   * Keep a live session's snapshot written through to the store, so it survives
+   * a gateway restart. **Off by default**: a library must not start writing a
+   * session's whole transcript to disk because someone upgraded.
+   *
+   * This is the restart story for the engine that cannot go dormant. Dormancy
+   * works by remembering an *engine* session id to resume from, which the
+   * provider engine does not have — there is no store behind it, the history
+   * lives in the runner. What it has instead is `snapshot()`, so the record
+   * carries the state itself and rehydration is the ordinary `restore` path.
+   * Between the two, every engine survives a restart.
+   *
+   * Written at the end of a turn, never on a shutdown hook — a `kill -9`, an OOM
+   * or a pulled power cable run no hook, and that is precisely the case this
+   * exists for. Turn-end is also a natural rate limit: one write per turn, not
+   * one per token.
+   */
+  persistLive?: boolean;
   /** Grace given at {@link SessionParkManager.hydrate} to an execution whose
    * deadline passed while the server was down. Its result could not have been
    * delivered during the outage, so failing it the instant the process is back
@@ -676,6 +720,22 @@ type WorkerServerOptions = {
     /** Grace given on boot to an execution whose deadline passed while the server
      * was down (durable stores only — nothing else survives a restart). Default 60000. */
     expiredGraceMs?: number;
+    /**
+     * Keep live `provider` sessions written through to the store after each
+     * turn, so they survive a gateway restart. **Off by default** — this writes
+     * a session's whole transcript to `store` and a library must not start doing
+     * that because someone upgraded.
+     *
+     * It is the restart story for the one engine dormancy cannot cover: claude
+     * and codex are remembered by *engine session id* and resumed from their own
+     * on-disk store, which a provider session does not have. Pair it with a
+     * durable `store` — with the default in-memory one it does nothing a park
+     * did not already do.
+     *
+     * The record is rebuilt lazily, on first attach, exactly like a dormant one;
+     * a boot with fifty remembered sessions spawns nothing.
+     */
+    persistLive?: boolean;
     /** Park/remember/resume failures — storage or engine-assembly problems, not
      * session errors. 'remember' is the write that lets a live session survive a
      * restart; losing one costs that session its way back and nothing else. */

package/build/index.mjs

@@ -2,7 +2,7 @@ import { createServer } from "node:http";
 import { WebSocketServer } from "ws";
 import { BrowserBridgeExecutor, SessionRunner, attachmentKind, checkClaudeAuth, createEngineSession, getEngineAdapter, normalizeMediaType } from "@workerdeck/core";
 import { JobQueue } from "@workerdeck/queue";
-import { ENGINE_CAPABILITIES, PROTOCOL_VERSION, supportsPermissionMode } from "@workerdeck/protocol";
+import { ENGINE_CAPABILITIES, PROTOCOL_VERSION, imagePartRef, supportsPermissionMode } from "@workerdeck/protocol";
 import { createHash, randomUUID } from "node:crypto";
 import { closeSync, constants, createReadStream, existsSync, fstatSync, ftruncateSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -214,6 +214,18 @@ function parseSessionRoute(basePath, url) {
 		produced: true,
 		producedFileId: parts[2] === void 0 ? void 0 : decodeURIComponent(parts[2])
 	};
+	if (parts.length === 3 && parts[1] === "project" && parts[2] === "icon") return {
+		id: decodeURIComponent(parts[0]),
+		projectIcon: true
+	};
+	if (parts.length === 4 && parts[1] === "events" && parts[3] === "result") {
+		const seq = Number(parts[2]);
+		if (!Number.isInteger(seq) || seq < 0) return null;
+		return {
+			id: decodeURIComponent(parts[0]),
+			resultSeq: seq
+		};
+	}
 	if (parts.length <= 3 && parts[1] === "mcp") return {
 		id: decodeURIComponent(parts[0]),
 		mcp: true,
@@ -335,7 +347,9 @@ function invalidRequest(requested) {
 /** Both sides are realpath output, so this is a pure lexical question — but a
 * bare prefix check gets the boundary wrong (`/x/app` would swallow
 * `/x/application`). `relative` answers it exactly: inside iff the walk from
-* root to candidate is empty or never has to leave through `..`. */
+* root to candidate is empty or never has to leave through `..`. Exported for
+* the project-icon resolver (`project-info.ts`), which makes the same claim
+* against a project root; both callers must hand it realpath output only. */
 function contained(rootCanonical, candidate) {
 	const rel = relative(rootCanonical, candidate);
 	return rel === "" || rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
@@ -1116,6 +1130,8 @@ function withinRoots(sessions, roots, limit, offset = 0) {
 }
 //#endregion
 //#region src/services/session-store.ts
+/** A live record is refreshed in place on wake; a park is consumed by it. */
+const isLiveRecord = (record) => record.kind === "live";
 const isDormant = (record) => record.kind === "dormant";
 /** Single-process, no persistence: parks survive a client disconnect, not a restart. */
 var MemorySessionStore = class {
@@ -1462,12 +1478,295 @@ async function handleProducedFiles(ctx, req, res, sessionId, fileId) {
 	});
 }
 //#endregion
+//#region src/services/project-info.ts
+/**
+* Project identity discovery: the `.workerdeck.json` ancestor walk behind
+* `SessionInfo.project`, and the read side of `GET /sessions/:id/project/icon`.
+*
+* The gateway resolves this — not each client — because the file lives on the
+* gateway's filesystem, which a phone or a remote browser cannot see. It is
+* stamped onto `SessionInfo` at **serve time** (`withProject`), never persisted:
+* a copy captured into a parking record would replay a stale name forever,
+* where a serve-time read picks up an edited file on every session at once
+* within the TTL. That is the profile tracker's 0%-after-reset placement
+* argument, applied to a filesystem fact instead of a clock.
+*
+* Every failure degrades to "no project" and never to an error: a session must
+* not fail, or even warn, because of a display declaration. A malformed,
+* oversized, or symlinked `.workerdeck.json` is *skipped and the walk
+* continues* — a broken file in `packages/ui` must not shadow the repo root's
+* valid one — and inside a valid file each field degrades on its own (junk
+* name → the root's basename, junk icon → no icon).
+*
+* The icon is the security surface, because its path comes out of a config
+* file the *agent* can write (the session cwd is the agent's working tree).
+* The rules are `host-files.ts`'s, not `cwdAllowed`'s (docs/GOTCHAS.md §Host
+* filesystem): the declared path is resolved against the project root and then
+* realpath'd **whole**, containment is decided on the canonical result only
+* (so `"icon": "../../../../etc/key.png"` and a planted `icon.png → ~/.ssh/…`
+* symlink both fail the same check), the open goes through `readContained`
+* (O_NOFOLLOW, fstat-before-io), and the media type comes from the *declared*
+* extension — png and svg only, by decision. A refused icon is
+* indistinguishable on the wire and on the route from a never-declared one:
+* `icon` absent, the route 404s. The one disclosure this feature accepts is
+* inherent to it: the walk reads ancestors of a vetted cwd, so a project file
+* an operator placed *above* their roots (`~/.workerdeck.json`) applies to
+* everything under it — nearest-wins from the cwd, exactly git's own
+* discovery, and the file is a display declaration by definition.
+*
+* Cache: per exact cwd string, TTL'd, with negative results cached at the same
+* price — `GET /sessions` polls at 1.2s while anything is working and the hit
+* path must be a Map lookup, never a walk. Keyed by cwd rather than by root
+* because the root is not known until the walk has run. Bounded by sweeping
+* expired entries once the map outgrows any plausible live session count.
+*/
+const PROJECT_FILE = ".workerdeck.json";
+/** A config file, not a document — anything bigger is skipped as malformed. */
+const MAX_PROJECT_FILE_BYTES = 64 * 1024;
+/** Display name clip — a list row's width, not a document's. */
+const MAX_NAME_CHARS = 80;
+/** lucide's naming: lowercase kebab-case. Shape-only — the gateway has no icon
+* catalog and must not grow one; an unknown-but-well-formed name ships and the
+* client falls back (a stale row, never withheld state). */
+const GLYPH_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const DEFAULT_TTL_MS = 3e4;
+/** Sweep threshold: above this many cached cwds, expired entries are evicted
+* on the next resolve so dead sessions' keys do not accumulate forever. */
+const SWEEP_ABOVE = 256;
+var ProjectInfoService = class {
+	#ttlMs;
+	#byCwd = /* @__PURE__ */ new Map();
+	constructor(options = {}) {
+		this.#ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+	}
+	/**
+	* The serve-time decoration: `info` with `project` stamped on, or the same
+	* object untouched when there is nothing to add — the common case on a list
+	* poll, so no allocation for it (replaySlice's same-object rule).
+	*/
+	withProject(info) {
+		if (!info.cwd) return info;
+		const project = this.#resolve(info.cwd).project;
+		return project ? {
+			...info,
+			project
+		} : info;
+	}
+	/** The icon route's read side: the canonical, contained icon file for this
+	* session's cwd — resolved from the gateway's own cache, never from anything
+	* the client named. Undefined = no project, no icon, or an icon refused. */
+	iconFor(cwd) {
+		if (!cwd) return void 0;
+		return this.#resolve(cwd).icon;
+	}
+	#resolve(cwd) {
+		const now = Date.now();
+		const held = this.#byCwd.get(cwd);
+		if (held && held.expiresAt > now) return held;
+		if (this.#byCwd.size > SWEEP_ABOVE) {
+			for (const [key, entry] of this.#byCwd) if (entry.expiresAt <= now) this.#byCwd.delete(key);
+		}
+		const fresh = {
+			...discover(cwd),
+			expiresAt: now + this.#ttlMs
+		};
+		this.#byCwd.set(cwd, fresh);
+		return fresh;
+	}
+};
+/** The ancestor walk: realpath the cwd (a lexical walk over `/tmp/x` would
+* miss the file at `/private/tmp/x`, and canonicalizing here is what makes
+* `root` — the grouping key — spell identically for every cwd inside one
+* project), then nearest `.workerdeck.json` wins, to the filesystem root. */
+function discover(cwd) {
+	if (!isAbsolute(cwd) || cwd.includes("\0")) return {};
+	let dir;
+	try {
+		dir = realpathSync(cwd);
+	} catch {
+		return {};
+	}
+	for (;;) {
+		const found = tryLoad(join(dir, PROJECT_FILE), dir);
+		if (found) return found;
+		const parent = dirname(dir);
+		if (parent === dir) return {};
+		dir = parent;
+	}
+}
+/** One directory's verdict: a project record, or undefined to keep walking —
+* which is the same answer for "absent" and for every malformed shape. */
+function tryLoad(file, root) {
+	let stat;
+	try {
+		stat = lstatSync(file);
+	} catch {
+		return;
+	}
+	if (!stat.isFile() || stat.size > MAX_PROJECT_FILE_BYTES) return void 0;
+	const read = readContained(file);
+	if (!read.ok) return void 0;
+	let parsed;
+	try {
+		parsed = JSON.parse(read.data.toString("utf8"));
+	} catch {
+		return;
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return void 0;
+	const raw = parsed;
+	const name = typeof raw.name === "string" && raw.name.trim() ? raw.name.trim().slice(0, MAX_NAME_CHARS) : basename(root);
+	const icon = classifyIcon(raw.icon, root);
+	return {
+		project: {
+			name,
+			root,
+			...icon ? { icon: icon.wire } : {}
+		},
+		...icon?.resolved ? { icon: icon.resolved } : {}
+	};
+}
+/**
+* The one-string icon rule (documented on protocol's `ProjectInfo`): ends in
+* `.png`/`.svg` → repo-relative image path, else lucide-shaped glyph name,
+* else ignored. Total and collision-free — a glyph name contains no dot.
+*/
+function classifyIcon(value, root) {
+	if (typeof value !== "string") return void 0;
+	const declared = value.trim();
+	if (!declared || declared.includes("\0") || declared.length > 512) return void 0;
+	const lower = declared.toLowerCase();
+	const mediaType = lower.endsWith(".png") ? "image/png" : lower.endsWith(".svg") ? "image/svg+xml" : void 0;
+	if (!mediaType) {
+		if (!GLYPH_RE.test(declared) || declared.length > 64) return void 0;
+		return { wire: {
+			type: "glyph",
+			name: declared
+		} };
+	}
+	if (isAbsolute(declared) || declared.includes("\\")) return void 0;
+	let canonical;
+	try {
+		canonical = realpathSync(resolve(root, declared));
+	} catch {
+		return;
+	}
+	if (!contained(root, canonical)) return void 0;
+	let stat;
+	try {
+		stat = lstatSync(canonical);
+	} catch {
+		return;
+	}
+	if (!stat.isFile() || stat.size === 0 || stat.size > 524288) return void 0;
+	const read = readContained(canonical);
+	if (!read.ok || read.data.length > 524288) return void 0;
+	const hash = createHash("sha256").update(read.data).digest("hex");
+	return {
+		wire: {
+			type: "image",
+			mediaType,
+			hash
+		},
+		resolved: {
+			path: canonical,
+			mediaType,
+			hash
+		}
+	};
+}
+//#endregion
+//#region src/routes/project-icon.ts
+function handleProjectIcon(projects, req, res, cwd) {
+	if (req.method !== "GET") {
+		json(res, 405, { error: "method not allowed" });
+		return;
+	}
+	const icon = projects.iconFor(cwd);
+	if (!icon) {
+		json(res, 404, { error: "no project icon" });
+		return;
+	}
+	const etag = `"${icon.hash}"`;
+	if (req.headers["if-none-match"] === etag) {
+		res.writeHead(304, { etag });
+		res.end();
+		return;
+	}
+	const read = readContained(icon.path);
+	if (!read.ok || read.data.length > 524288) {
+		json(res, 404, { error: "no project icon" });
+		return;
+	}
+	res.writeHead(200, {
+		"content-type": icon.mediaType,
+		"content-length": read.data.length,
+		etag,
+		"cache-control": "private, max-age=300",
+		"content-disposition": "attachment; filename=\"project-icon\"",
+		"x-content-type-options": "nosniff"
+	});
+	res.end(read.data);
+}
+//#endregion
+//#region src/routes/tool-results.ts
+function handleToolResult(req, res, lookup, seq) {
+	if (req.method !== "GET") {
+		json(res, 405, { error: "method not allowed" });
+		return;
+	}
+	const url = new URL(req.url ?? "/", "http://internal");
+	const toolUseId = url.searchParams.get("toolUseId");
+	if (!toolUseId) {
+		json(res, 400, { error: "toolUseId is required" });
+		return;
+	}
+	if (!lookup) {
+		json(res, 501, { error: "engine does not serve stored events" });
+		return;
+	}
+	const event = lookup(seq);
+	if (!event || event.type !== "user_message" || !Array.isArray(event.message.content)) {
+		json(res, 404, { error: "no such event" });
+		return;
+	}
+	const block = event.message.content.find((candidate) => candidate.type === "tool_result" && candidate.tool_use_id === toolUseId);
+	if (!block) {
+		json(res, 404, { error: "no such tool result in that event" });
+		return;
+	}
+	const partParam = url.searchParams.get("part");
+	if (partParam !== null) {
+		const index = Number(partParam);
+		const parts = block.content;
+		const part = Number.isInteger(index) && Array.isArray(parts) ? parts[index] : void 0;
+		const ref = part ? imagePartRef(part, index) : void 0;
+		if (!ref) {
+			json(res, 404, { error: "no such image part in that tool result" });
+			return;
+		}
+		const source = part.source;
+		const bytes = Buffer.from(source?.data ?? "", "base64");
+		res.writeHead(200, {
+			"content-type": ref.media_type,
+			"content-length": String(bytes.length)
+		});
+		res.end(bytes);
+		return;
+	}
+	json(res, 200, {
+		seq,
+		toolUseId,
+		content: url.searchParams.get("imageRefs") === "1" && Array.isArray(block.content) ? block.content.map((part, index) => imagePartRef(part, index) ?? part) : block.content ?? "",
+		isError: block.is_error === true
+	});
+}
+//#endregion
 //#region src/routes/sessions.ts
 async function handleSessions(ctx, req, res, route, auth) {
-	const { attachmentStore, auth: authSvc, availability, bridge, factory, parking, producedFiles, registry } = ctx;
+	const { attachmentStore, auth: authSvc, availability, bridge, factory, parking, producedFiles, projects, registry } = ctx;
 	if (!route.id) {
 		if (req.method === "GET") {
-			json(res, 200, { sessions: [...registry.list(), ...await parking.listInfo()].filter((session) => authSvc.canSee(auth, session)) });
+			json(res, 200, { sessions: [...registry.list(), ...await parking.listInfo()].filter((session) => authSvc.canSee(auth, session)).map((session) => projects.withProject(session)) });
 			return;
 		}
 		if (req.method === "POST") {
@@ -1506,7 +1805,7 @@ async function handleSessions(ctx, req, res, route, auth) {
 			body.profile = resolved.profile?.name;
 			const runner = await factory.createRunner(factory.buildRunnerConfig(body));
 			factory.watchAuthSource(runner);
-			json(res, 201, { session: runner.info() });
+			json(res, 201, { session: projects.withProject(runner.info()) });
 			return;
 		}
 		json(res, 405, { error: "method not allowed" });
@@ -1574,6 +1873,15 @@ async function handleSessions(ctx, req, res, route, auth) {
 		await handleProducedFiles(ctx, req, res, route.id, route.producedFileId);
 		return;
 	}
+	if (route.projectIcon) {
+		handleProjectIcon(projects, req, res, (runner?.info() ?? parked.info).cwd);
+		return;
+	}
+	if (route.resultSeq !== void 0) {
+		const snapshot = parked && !isDormant(parked) ? parked.snapshot.events : void 0;
+		handleToolResult(req, res, runner?.eventAt?.bind(runner) ?? (snapshot && ((seq) => snapshot.find((event) => event.seq === seq))), route.resultSeq);
+		return;
+	}
 	if (route.permissionId) {
 		if (req.method !== "POST") {
 			json(res, 405, { error: "method not allowed" });
@@ -1596,7 +1904,7 @@ async function handleSessions(ctx, req, res, route, auth) {
 		return;
 	}
 	if (req.method === "GET") {
-		json(res, 200, { session: runner?.info() ?? parked.info });
+		json(res, 200, { session: projects.withProject(runner?.info() ?? parked.info) });
 		return;
 	}
 	if (req.method === "PATCH") {
@@ -1614,7 +1922,7 @@ async function handleSessions(ctx, req, res, route, auth) {
 			runner.setTitle(title || void 0);
 			parking.touch(runner);
 		}
-		json(res, 200, { session: runner.info() });
+		json(res, 200, { session: projects.withProject(runner.info()) });
 		return;
 	}
 	if (req.method === "DELETE") {
@@ -1623,10 +1931,10 @@ async function handleSessions(ctx, req, res, route, auth) {
 		await parking.discard(route.id);
 		attachmentStore.drop(route.id);
 		producedFiles.drop(route.id);
-		json(res, 200, { session: runner?.info() ?? {
+		json(res, 200, { session: projects.withProject(runner?.info() ?? {
 			...parked.info,
 			status: "closed"
-		} });
+		}) });
 		return;
 	}
 	json(res, 405, { error: "method not allowed" });
@@ -1637,19 +1945,25 @@ function attachClient(ctx, ws, runner, req) {
 	const { bridge, parking } = ctx;
 	const url = new URL(req.url ?? "/", "http://internal");
 	const afterSeq = Number(url.searchParams.get("afterSeq") ?? "0") || 0;
+	const truncateResults = url.searchParams.get("truncateResults") === "1";
+	const imageRefs = url.searchParams.get("imageRefs") === "1";
 	const send = (frame) => {
 		if (ws.readyState === ws.OPEN) ws.send(JSON.stringify(frame));
 	};
 	send({
 		type: "attached",
 		protocolVersion: PROTOCOL_VERSION,
-		session: runner.info(),
+		session: ctx.projects.withProject(runner.info()),
 		replayingFrom: afterSeq
 	});
 	const unsubscribe = runner.subscribe((event) => send({
 		type: "event",
 		event
-	}), afterSeq, { coalesceReplay: true });
+	}), afterSeq, {
+		coalesceReplay: true,
+		truncateResults,
+		imageRefs
+	});
 	const detachBridge = bridge.attach(runner.id, send);
 	ws.on("message", (data) => {
 		let frame;
@@ -2241,7 +2555,7 @@ var SessionNotifier = class {
 		const notification = {
 			...body,
 			sessionId: runner.id,
-			session: runner.info(),
+			session: (this.#options.decorateInfo ?? ((info) => info))(runner.info()),
 			seq,
 			ts
 		};
@@ -2353,6 +2667,7 @@ var SessionParkManager = class {
 	*/
 	touch(runner) {
 		this.#rememberDormant(runner);
+		this.#persistLive(runner);
 	}
 	/**
 	* Adopt the store's contents (a durable store after a restart): re-index the
@@ -2396,6 +2711,13 @@ var SessionParkManager = class {
 					if (event.status === "parked") this.#park(runner);
 					else this.#rememberDormant(runner);
 					return;
+				case "turn_result":
+					this.#persistLive(runner);
+					return;
+				case "permission_mode_changed":
+				case "model_changed":
+					this.#persistLive(runner);
+					return;
 				case "system_init":
 					this.#rememberDormant(runner);
 					return;
@@ -2534,6 +2856,62 @@ var SessionParkManager = class {
 			});
 		}
 	}
+	/**
+	* Write a live session's snapshot through to the store, so a restart can
+	* rebuild it. The counterpart to {@link #rememberDormant} for the engine that
+	* has no engine-side session to resume from — same discipline, different
+	* mechanism: that one remembers *where the transcript is*, this one carries it.
+	*
+	* The gates are the same four, plus the option and the engine's ability. The
+	* `registry.get(runner.id) !== runner` check is doing the same work it does
+	* there: a runner that has been evicted (parked, or replaced by a rebuild)
+	* finds itself a stranger here and writes nothing, so a late event cannot
+	* overwrite a park with a stale live record.
+	*
+	* **This must not run synchronously inside the event listener**, and that is
+	* easy to lose. `turn_result` is emitted from inside the turn, *before* the
+	* `finally` that clears the runner's abort controller — so a `snapshot()`
+	* called straight from the listener would see a turn in flight and refuse,
+	* every single time, silently. `#queue`'s microtask hop is what puts the call
+	* after it. A refactor that "simplifies" this into a direct call produces a
+	* write-through that never writes and nothing that says so.
+	*/
+	async #persistLive(runner) {
+		if (this.#closed || !this.#options.persistLive || !runner.snapshot) return;
+		const config = this.#configs.get(runner.id);
+		if (!config) return;
+		if (this.#options.registry.get(runner.id) !== runner) return;
+		try {
+			await this.#queue(runner.id, async () => {
+				if (this.#closed || this.#options.registry.get(runner.id) !== runner) return;
+				const snapshot = runner.snapshot?.();
+				if (!snapshot) return;
+				const info = runner.info();
+				const record = {
+					kind: "live",
+					id: runner.id,
+					info: {
+						...info,
+						status: "idle"
+					},
+					profile: info.profile,
+					config: {
+						...config,
+						meta: info.meta
+					},
+					snapshot,
+					executions: snapshot.parked,
+					parkedAt: Date.now()
+				};
+				await this.#options.store.save(record);
+			});
+		} catch (error) {
+			this.#options.onError?.(error, {
+				sessionId: runner.id,
+				phase: "remember"
+			});
+		}
+	}
 	async #park(runner) {
 		if (this.#closed || !runner.park) return;
 		const id = runner.id;
@@ -2609,7 +2987,7 @@ var SessionParkManager = class {
 		this.remember(id, record.config);
 		this.watch(runner, isDormant(record) ? 0 : record.snapshot.seq);
 		this.#options.onResumed?.(id, runner);
-		if (!isDormant(record)) await this.#queue(id, () => this.#options.store.delete(id));
+		if (!isDormant(record) && !isLiveRecord(record)) await this.#queue(id, () => this.#options.store.delete(id));
 		runner.start();
 		return runner;
 	}
@@ -3348,7 +3726,11 @@ function createWorkerServer(options = {}) {
 		adapterFor,
 		sessionEnvFor: factory.sessionEnvFor
 	});
-	const notifier = new SessionNotifier(options.notifications ?? {});
+	const projects = new ProjectInfoService();
+	const notifier = new SessionNotifier({
+		...options.notifications,
+		decorateInfo: (info) => projects.withProject(info)
+	});
 	const producedFiles = new ProducedFileStore();
 	const registry = new SessionRegistry({ onRegister: (runner) => {
 		notifier.watch(runner);
@@ -3374,6 +3756,7 @@ function createWorkerServer(options = {}) {
 		store: options.parking?.store ?? new MemorySessionStore(),
 		parkDelayMs: options.parking?.parkDelayMs,
 		expiredGraceMs: options.parking?.expiredGraceMs,
+		persistLive: options.parking?.persistLive,
 		onError: options.parking?.onError,
 		rebuild: (record) => isDormant(record) ? factory.buildRunner(factory.buildRunnerConfig({
 			...record.config,
@@ -3445,6 +3828,7 @@ function createWorkerServer(options = {}) {
 		registry,
 		parking,
 		bridge,
+		projects,
 		queue,
 		attachmentStore,
 		producedFiles,