@deepseek-insight/dsi 0.5.5

package/build/server/chunks/chunks/dsh-connection.js-DwihVtk_.js

@@ -0,0 +1,1957 @@
+import { p as dshBaseUrl } from './config.js-BBYogCe7.js';
+import { r as readDshPresetEnglishConfig, a as readDshAuthConfig, b as readServerConfig } from './insight-config.js-CfMPTA6Z.js';
+
+//#region src/lib/server/dsh-rpc.ts
+/**
+* dsh-rpc — the single choke point for DSH wire bytes (BC-6).
+*
+* Every RPC fact below is pinned by the gateway guide
+* (dev/gateways/dsh-gateway-live-streaming.md) and the harness sources it
+* cites (packages/client/connection/src/client/rpc.ts — envelope;
+* packages/host/apiproxy/src/api/rpc-map.ts — POST /api/{method} paths;
+* api/rpc.ts — RpcResult ok/false error union; api/sessions.ts — payloads).
+*
+* Live-verified 2026-08-21: session.list and session.history round-trip,
+* events.mux open → session/subscribed baseline with lastSeq.
+*/
+/**
+* Wire endpoints this app calls (0.1.2-alpha.1 wire: slash paths, args
+* envelopes). The closed set grows only by spec change (BC-6). Arg names are
+* each endpoint's declared parameter name — exact-match validated by the
+* host descriptor (extra/missing keys → arguments-invalid).
+*
+* Live-verified 2026-08-29 against dsh-0.1.2-alpha.1 (cd5ef81481):
+* session/list, session/create, session/prompt, session/rename,
+* session/selectModel, session/modelCatalog, session/page, session/cancel,
+* session/attachment, agentPresets/list, workspace/create, commands/list
+* (verified on the wire, never called by DSI — no DSH_METHODS entry),
+* commands/execute, directoryPicker/pick. DSH_METHODS below is the canonical
+* set this app calls.
+*
+* Grown by spec 2026-08-30 (BC-6): the Slash Menu ADR
+* (dev/architectural-decission/2026-08-30 - The Slash Menu — The Composer
+* Reads the Host's Own Directory.md) adds commandsList + skillsList — DSI
+* becomes a reader of the host's command/skill catalogs. Both endpoints
+* live-pinned 2026-08-30 against dsh web 0.1.2 (see tests/unit/dsh-rpc.test.ts
+* — the recorded round-trip: envelope payload:{args}, skills 10 rows,
+* commands 5 rows).
+*/
+var DSH_METHODS = {
+	/** args `{}` — `_request` is reserved-empty (acceptsUndefined). */
+	list: "session/list",
+	/** args `{request:{address,throughSeq,beforeSeq?,maxMessages?}}` → `{records,hasMore}`. */
+	page: "session/page",
+	prompt: "session/prompt",
+	cancel: "session/cancel",
+	create: "session/create",
+	/**
+	* args `{request:{sessionId,atSeq?}}` → `{sessionId}` (the fork child).
+	* Host contract (harness packages/api/session-controller/src/types.ts
+	* SessionForkRequest/Value): `atSeq` omitted cuts at the source's last
+	* completed turn; a given `atSeq` anchors to the first `turn/end` at or
+	* after it — an anchor inside an open turn refuses `session/fork-unavailable`,
+	* never clips. Refusals: `session/not-found`, `session/fork-unavailable`,
+	* `session/workspace-attach-failed`. Live-pinned 2026-09-01 against
+	* dsh-0.1.2-alpha.3: the args descriptor exact-matches `{request:{sessionId}}`
+	* (a bare sessionId → gateway/arguments-invalid: missing "request") and a
+	* turn-less source refuses fork-unavailable ("has no completed turn to
+	* fork from"). The success path (child id) is pinned by the harness
+	* client fixture (connection/src/client/fixture.ts case 'session/fork').
+	*/
+	fork: "session/fork",
+	presets: "agentPresets/list",
+	rename: "session/rename",
+	/** args `{}` → ModelCatalog {default,routableProviders,groups,failures}. */
+	modelCatalog: "session/modelCatalog",
+	selectModel: "session/selectModel",
+	workspaceCreate: "workspace/create",
+	/**
+	* args `{request:{workspaceId,title}}` → Workspace view. Refusals:
+	* `workspace/not-found`, `workspace/name-conflict` (details carry the
+	* conflicting name). A no-op title (trimmed-equal) succeeds silently and
+	* emits NO follow frame — semantics pinned against the harness client
+	* fixture (connection fixture.client.spec.ts:1187-1216). Chip Menu ADR D3.
+	*/
+	workspaceRename: "workspace/rename",
+	/**
+	* args `{request:{workspaceId}}` → removed workspaceId. Removes ONLY the
+	* registry row (sessions survive, ungrouped) and emits a remove frame on
+	* workspace/follow — pinned at connection fixture.client.spec.ts:1292-1303.
+	* Chip Menu ADR D3.
+	*/
+	workspaceDelete: "workspace/delete",
+	listDirectory: "directoryPicker/list",
+	pickDirectory: "directoryPicker/pick",
+	/**
+	* args `{agentId,line,submittedAttachments}` → CommandExecution | null
+	* (agentId = sessionId). 0.1.3-alpha.1 renamed the wire arg — the Typert
+	* descriptor binds the implementation's parameter name, and
+	* CommandRuntime.execute's third parameter became `submittedAttachments`
+	* (mixed image/file submissions); the old `images` envelope now rejects
+	* `gateway/arguments-invalid` (probed live 2026-09-05).
+	*/
+	commandExecute: "commands/execute",
+	/** args `{agentId}` → DshCommandRow[] name-sorted (Slash Menu ADR §2; live-pinned 2026-08-30). */
+	commandsList: "commands/list",
+	/** args `{request:{sessionId}}` → DshSkillList (user-invocable only; Slash Menu ADR §2; live-pinned 2026-08-30). */
+	skillsList: "skills/list",
+	attachment: "session/attachment",
+	/**
+	* args `{workspaceFileScopeId, path, range?}` - WorkspaceFileText
+	* {offset,text,lines,eof,absolutePath,version,bytes?} (Workspace Explorer
+	* W2 task 2.1). The scope wire key was `agentId` until the host's
+	* 2026-09-09 session-roots fix (7214a97723, first shipped 0.1.5-alpha.2)
+	* registered the `workspaceFileScope` lookup with
+	* `wire: 'workspaceFileScopeId'` (packages/api/workspace-files/src/index.ts:204
+	* at 0.1.5-rc.1) — sending `agentId` now rejects gateway/arguments-invalid
+	* (observed live 2026-09-10). Refusals (RemoteErrorDetailsMap, types.ts):
+	* workspace-file/not-found, outside-workspace, too-large, not-text,
+	* not-regular-file.
+	*/
+	workspaceFileRead: "workspaceFiles/read",
+	/**
+	* args `{workspaceFileScopeId, path, range}` → WorkspaceFileBytes —
+	* readBytes(workspaceFileScope, path, range) on the same descriptor: raw
+	* bytes (base64 on the wire),
+	* no text decoding and no binary refusal. Binary previews (images)
+	* read through this (2026-09-10): `read` refuses non-text with
+	* workspace-file/not-text. Same refusals as read.
+	*/
+	workspaceFileReadBytes: "workspaceFiles/readBytes",
+	workspaceFileList: "workspaceFiles/list"
+};
+/** Args builders — one per endpoint, pinned to the live-probed shapes. */
+var DSH_ARGS = {
+	list: () => ({ _request: {} }),
+	page: (request) => ({ request }),
+	prompt: (request) => ({ request }),
+	cancel: (request) => ({ request }),
+	create: (request) => ({ request }),
+	fork: (request) => ({ request }),
+	presets: () => ({}),
+	rename: (request) => ({ request }),
+	modelCatalog: () => ({}),
+	selectModel: (request) => ({ request }),
+	workspaceCreate: (request) => ({ request }),
+	workspaceRename: (workspaceId, title) => ({ request: {
+		workspaceId,
+		title
+	} }),
+	workspaceDelete: (workspaceId) => ({ request: { workspaceId } }),
+	listDirectory: (path) => path === void 0 ? {} : { path },
+	pickDirectory: () => ({}),
+	commandExecute: (agentId, line, submittedAttachments) => ({
+		agentId,
+		line,
+		submittedAttachments
+	}),
+	commandsList: (agentId) => ({ agentId }),
+	skillsList: (sessionId) => ({ request: { sessionId } }),
+	attachment: (request) => ({ request }),
+	/** Flat args — the descriptor has NO request wrapper: scope wire
+	*  workspaceFileScopeId (2026-09-09 rename, was agentId), json path/range. */
+	workspaceFileRead: (sessionId, path, range) => ({
+		workspaceFileScopeId: sessionId,
+		path,
+		range: range ?? {}
+	}),
+	/** Flat args like the read — the descriptor scopes workspaceFileScopeId on the wire. */
+	workspaceFileList: (sessionId, path) => ({
+		workspaceFileScopeId: sessionId,
+		path
+	}),
+	/** Flat args like the read — WorkspaceByteRange {offset, length}, 0-based
+	*  bytes; `{}` = the host's window defaults. */
+	workspaceFileReadBytes: (sessionId, path, range) => ({
+		workspaceFileScopeId: sessionId,
+		path,
+		range: range ?? {}
+	})
+};
+/**
+* The ONE stream carrier (0.1.2): `/api/remote.mux` WebSocket multiplexing
+* logical streams — `{type:'open',streamId,endpoint,payload}` opens one,
+* `{type:'item'|'end'|'error',streamId,…}` frames carry it (stream-protocol.ts).
+* Cookie-authenticated like every /api surface. The old events.mux/events.host
+* pair is gone (404).
+*/
+var DSH_REMOTE_MUX_WS_PATH = "/api/remote.mux";
+/** Forwarded-event logical stream endpoint ($events — approvals/questions ride it). */
+var REMOTE_EVENT_STREAM_ENDPOINT = "$events";
+/** Empty standard payload that opens the $events stream (stream-protocol.ts). */
+var REMOTE_EVENT_STREAM_PAYLOAD = { args: {} };
+/** Waterfall-result unary endpoint answering a forwarded event ($events/result). */
+var REMOTE_EVENT_RESULT_ENDPOINT = "$events/result";
+/** Error carrying the DSH RpcError (ok:false result). */
+var DshRpcError = class extends Error {
+	code;
+	details;
+	constructor(code, message, details) {
+		super(`DSH RPC ${code}: ${message}`);
+		this.name = "DshRpcError";
+		this.code = code;
+		this.details = details;
+	}
+};
+/**
+* api-dsh error mapping (Module Map: dsh-rpc owns error mapping; routes stay DRY
+* with no cross-route imports). DshRpcError → 502 with the host's code; anything
+* else (transport down) → 503 host-unreachable.
+*/
+function statusFor(err) {
+	return err instanceof DshRpcError ? 502 : 503;
+}
+/**
+* Host codes for the subagent-ownership family (session-controller
+* validateAddress + apiSessionSubagentOwnershipError): the request reached the
+* host and was REJECTED by session policy — the host is fine, the address form
+* or ownership is the problem. Never surfaces as "cannot reach the host".
+* 0.1.2-alpha.2+ wire vocabulary: `<domain>/<reason>` codes (the 2026-08-28
+* RemoteError note in the harness repo renamed them wholesale).
+*/
+var SUBAGENT_REJECTION_CODES = /* @__PURE__ */ new Set([
+	"session/agent-busy",
+	"subagent/unauthorized",
+	"subagent/not-found",
+	"subagent/catalog-diagnostic"
+]);
+/** True when the error is a host subagent-ownership rejection (see the code set). */
+function isSubagentRejection(err) {
+	return err instanceof DshRpcError && SUBAGENT_REJECTION_CODES.has(err.code);
+}
+/** Error body for api-dsh routes: machine code + user-facing message.
+*  DshRpcError details ride along when the host sent them — the native
+*  picker fallback branches on details.capability. */
+function mapRpcFailure(err) {
+	if (err instanceof DshRpcError) return {
+		ok: false,
+		error: {
+			code: err.code,
+			message: err.message,
+			...err.details !== void 0 ? { details: err.details } : {}
+		}
+	};
+	return {
+		ok: false,
+		error: {
+			code: "host-unreachable",
+			message: err instanceof Error ? err.message : String(err)
+		}
+	};
+}
+/**
+* Wave 2 (task 2.1) — the typed prompt-image surface. Raster media types
+* the version-one wire accepts, pinned to the host schema
+* (imageMediaTypeSchema); the server lane owns its own whitelist — client
+* admission (attachment-service) is a different trust boundary and is
+* never imported here.
+*/
+var PROMPT_IMAGE_MEDIA_TYPES = [
+	"image/png",
+	"image/jpeg",
+	"image/webp",
+	"image/gif"
+];
+/** Type guard for the wire's raster whitelist (route validation entry). */
+function isPromptImageMediaType(value) {
+	return PROMPT_IMAGE_MEDIA_TYPES.includes(value);
+}
+/**
+* Build ordered session.prompt content — images first, text last (the
+* host composer's own order); the text part is omitted when empty, so an
+* attachments-only send is exactly the image parts (DSH sendSession: the
+* text part appears only for non-empty text).
+*
+* @param text - prompt text, sent verbatim as one text block when non-empty.
+* @param images - validated image parts, in draft order.
+* @returns the content array for the session.prompt payload.
+*/
+function buildPromptContent(text, images) {
+	return [...images, ...text === "" ? [] : [{
+		type: "text",
+		text
+	}]];
+}
+/**
+* Parse + validate a server-response envelope against the expected rpcId.
+* Throws: DshRpcError when the result is ok:false; Error on envelope/rpcId mismatch.
+*/
+function parseResponse(raw, expectedRpcId) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (cause) {
+		throw new Error(`dsh-rpc: response is not JSON: ${String(cause)}`);
+	}
+	if (parsed?.type !== "server-response") throw new Error(`dsh-rpc: expected server-response, got ${JSON.stringify(parsed?.type)}`);
+	if (parsed.rpcId !== expectedRpcId) throw new Error(`dsh-rpc: rpcId mismatch — sent ${expectedRpcId}, got ${parsed.rpcId}`);
+	const result = parsed.result;
+	if (!result || typeof result !== "object" || !("ok" in result)) throw new Error("dsh-rpc: response result is not an RpcResult");
+	if (result.ok) return result.value;
+	const err = result.error;
+	throw new DshRpcError(err.code, err.message, err.details);
+}
+/** Build the RPC endpoint URL: POST {base}/api/{method} (rpc-map.ts key = wire path). */
+function rpcUrl(base, method) {
+	return `${(base ?? dshBaseUrl()).replace(/\/+$/, "")}/api/${method}`;
+}
+/**
+* DshAuth — the 0.1.2 cookie carrier (server-side singleton state).
+*
+* The upgraded host requires a signed session cookie (30d, HttpOnly,
+* SameSite=Strict, authority-bound) on every /api call and stream; the cookie
+* is minted by ONE GET / with the launch token (the `?token=*** URL `dsh web`
+* prints). The token is per-process; the minted cookie survives host
+* restarts, so the exchange runs once and again only on a 401 (fresh host
+* process). Single-flight: concurrent 401s share one mint.
+*/
+var DshAuth = class {
+	cookie = null;
+	minting;
+	baseUrl;
+	fetchFn;
+	log;
+	constructor(opts = {}) {
+		this.baseUrl = opts.baseUrl ?? dshBaseUrl();
+		this.fetchFn = opts.fetchFn ?? fetch;
+		this.log = opts.log ?? (() => {});
+	}
+	/** Current cookie pair, or null before the first successful mint. */
+	current() {
+		return this.cookie;
+	}
+	/**
+	* Ensure a cookie exists: reuse the minted one, else exchange the operator
+	* token from readDshAuthConfig. No token configured → null (hosts without
+	* the 0.1.2 fence never send 401 and never reach here).
+	*/
+	async ensureCookie() {
+		if (this.cookie !== null) return this.cookie;
+		this.minting ??= this.mint();
+		try {
+			return await this.minting;
+		} finally {
+			this.minting = void 0;
+		}
+	}
+	/** Forget the cookie (next call re-mints — a 401 means a new host process). */
+	invalidate() {
+		this.cookie = null;
+	}
+	/** Cookie header value for fetch/WS calls; undefined before any mint. */
+	cookieHeader() {
+		return this.cookie ?? void 0;
+	}
+	async mint() {
+		const { authToken } = readDshAuthConfig();
+		if (authToken === null) {
+			this.log("dsh-auth: no token configured — calling the host unauthenticated");
+			return null;
+		}
+		const url = new URL(this.baseUrl);
+		url.pathname = "/";
+		url.search = "";
+		const exchange = `${url.origin}${url.pathname}?token=${encodeURIComponent(authToken)}`;
+		try {
+			const response = await this.fetchFn(exchange, { redirect: "manual" });
+			const setCookie = response.headers.get("set-cookie");
+			if (response.status === 303 && setCookie !== null) {
+				this.cookie = setCookie.split(";")[0] ?? null;
+				this.log("dsh-auth: cookie minted");
+				return this.cookie;
+			}
+			this.log(`dsh-auth: exchange failed (HTTP ${String(response.status)}) — stale token?`);
+			return null;
+		} catch (err) {
+			this.log("dsh-auth: exchange transport failure", err);
+			return null;
+		}
+	}
+};
+//#endregion
+//#region src/lib/server/dsh-connection.ts
+/**
+* dsh-connection — the transport singleton (BC-5) owning every wire byte to
+* the DSH Host (BC-6: it speaks only through dsh-rpc helpers and the two
+* downlink WebSocket paths).
+*
+* State model (PRD §3.5):
+*   mux  frames (session/subscribed, session/event) → per-session ring buffer
+*   host frames (host/session-status)               → per-session running map
+*   running map re-baselines from session.list at every generation open
+*   (2026-08-26): the host pushes status only on TRANSITIONS and sends no
+*   initial snapshot, so a downlink rebuilt mid-turn would otherwise never
+*   learn the session was already running.
+*   ring buffer = freshness only; the ledger (session.history) is the truth —
+*   cold loads and every resync re-read the ledger (BC-4).
+*
+* Generation semantics (guide Part 1): the two downlinks form one generation;
+* if either dies, both are rebuilt after backoff.
+*/
+/** Live capacity from ~/.dsi/settings.yaml (no cache — runtime edits
+*  apply, same contract as every other config section). */
+function ringCapacity() {
+	return readServerConfig().ringCapacity;
+}
+var singleton;
+/** The process-wide transport (BC-5). Creates lazily on first use. */
+function getDshConnection(opts = {}) {
+	singleton ??= new DshConnection(opts);
+	return singleton;
+}
+var DshConnection = class {
+	baseUrl;
+	fetchFn;
+	wsFactory;
+	auth;
+	rpcIdFactory;
+	backoff;
+	log;
+	buffers = /* @__PURE__ */ new Map();
+	running = /* @__PURE__ */ new Map();
+	/**
+	* Live assistant-stream tails (0.1.3-alpha.1): the one in-flight model
+	* attempt per session, folded from the follow's seq-less assistant-stream
+	* frames. Presentation state only — never part of the durable cursor
+	* algebra (lastSeq/gap/coverage), because the frames carry no seq.
+	*/
+	liveTails = /* @__PURE__ */ new Map();
+	/**
+	* Session-ids that received a host/session-status push since the running
+	* re-baseline RPC was ISSUED (2026-08-26). A push is a strictly newer
+	* transition than an in-flight snapshot — the seed must never overwrite
+	* one. Swapped for a fresh set every time a seed is issued; read at
+	* apply time so pushes landing mid-flight are counted.
+	*/
+	runningSeedRaces = /* @__PURE__ */ new Set();
+	wsMux;
+	generation = 0;
+	/** Logical streams by streamId → owning socket (0.1.2 remote.mux). */
+	streamSockets = /* @__PURE__ */ new Map();
+	/** Generation-scoped counter keeping stream ids unique across rebuilds. */
+	streamSeq = 0;
+	/** $events generation clientId (RemoteEventReadyFrame; binds $events/result). */
+	eventClientId = null;
+	/** True once the carrier's OPEN event fired (sends are legal). */
+	opened = false;
+	/** Per-session projection baselines (follow snapshot + control frames; W2). */
+	projections = /* @__PURE__ */ new Map();
+	/** Workspace registry cache from workspace/follow (W2; authority = host). */
+	workspaces = [];
+	/** Waiters resolved by the first workspace/follow baseline (one-shot). */
+	workspaceBaselineWaiters = /* @__PURE__ */ new Set();
+	/** Subscribes parked while the carrier is CONNECTING (flushed on open). */
+	pendingSubscribes = /* @__PURE__ */ new Set();
+	/**
+	* Parent-address hints for subagent-origin sessions (SubagentAddressHint),
+	* folded from session.list rows by rawListSessions.
+	*/
+	subagentHints = /* @__PURE__ */ new Map();
+	/** Session-ids whose hint absence was already probed with a list pass
+	*  (one probe per session lifetime — ordinary sessions never re-probe). */
+	hintProbed = /* @__PURE__ */ new Set();
+	reconnectTimer;
+	disposed = false;
+	/** Wave 4.2 — consecutive failed generations; drives the backoff ladder. */
+	reconnectAttempt = 0;
+	/** Reap grace (see DshConnectionOptions.answerReapGraceMs). */
+	answerReapGraceMs;
+	answerReapTimer;
+	/** Stale-generation retry deadline (see DshConnectionOptions.staleGenerationRetryMs). */
+	staleGenerationRetryMs;
+	constructor(opts = {}) {
+		this.baseUrl = opts.baseUrl ?? dshBaseUrl();
+		this.fetchFn = opts.fetchFn ?? fetch;
+		this.wsFactory = opts.wsFactory ?? ((url, headers) => new WebSocket(url, headers === void 0 ? void 0 : { headers }));
+		this.auth = opts.auth ?? new DshAuth({
+			baseUrl: this.baseUrl,
+			log: opts.log
+		});
+		this.rpcIdFactory = opts.rpcIdFactory ?? (() => crypto.randomUUID());
+		this.backoff = opts.backoffScheduleMs ?? [
+			1e3,
+			2e3,
+			5e3,
+			1e4,
+			3e4
+		];
+		this.answerReapGraceMs = opts.answerReapGraceMs ?? 3e3;
+		this.staleGenerationRetryMs = opts.staleGenerationRetryMs ?? 5e3;
+		this.log = opts.log ?? (() => {});
+	}
+	/**
+	* Open the stream generation (idempotent): ONE cookie-authenticated
+	* remote.mux socket (0.1.2 — events.mux/events.host are gone), with every
+	* subscribed session's `session/follow` reopened as a logical stream plus
+	* the $events forwarded-event stream (approvals/questions).
+	*/
+	ensureDownlinks() {
+		if (this.disposed || this.wsMux) return;
+		++this.generation;
+		this.log(`dsh-connection: opening remote.mux generation ${this.generation}`);
+		this.wsMux = this.openDownlink((socket) => this.onMuxOpen(socket));
+		this.seedRunning();
+	}
+	openDownlink(attach) {
+		const url = this.baseUrl.replace(/^http/, "ws") + DSH_REMOTE_MUX_WS_PATH;
+		const headers = this.auth.cookieHeader();
+		const socket = this.wsFactory(url, headers === void 0 ? void 0 : { cookie: headers });
+		this.auth.ensureCookie().catch(() => null);
+		socket.addEventListener("message", (e) => {
+			try {
+				this.onStreamFrame(JSON.parse(String(e.data)));
+			} catch (err) {
+				this.log("dsh-connection: dropping malformed frame", err);
+			}
+		});
+		socket.addEventListener("open", () => {
+			this.opened = true;
+			attach(socket);
+		});
+		socket.addEventListener("close", () => this.onDownlinkClosed());
+		socket.addEventListener("error", () => this.onDownlinkClosed());
+		return socket;
+	}
+	/** mux open: (re)open every subscribed session's follow stream + $events. */
+	onMuxOpen(socket) {
+		this.streamSeq += 1;
+		this.pendingSubscribes.clear();
+		for (const sessionId of this.buffers.keys()) this.openFollowWithProbe(socket, sessionId);
+		this.openEventStream(socket);
+		this.openStateStream(socket, `workspaces-${String(this.streamSeq)}`, "workspace/follow");
+		this.openStateStream(socket, `control-${String(this.streamSeq)}`, "session/control");
+	}
+	/** Open one state stream (workspace/follow | session/control) with empty args. */
+	openStateStream(socket, streamId, endpoint) {
+		this.sendStreamOpen(socket, streamId, endpoint, { args: {} });
+	}
+	openFollowStream(socket, sessionId) {
+		this.sendStreamOpen(socket, followStreamId(sessionId, this.streamSeq), "session/follow", { args: { request: {
+			address: this.addressFor(sessionId),
+			maxMessages: 200,
+			assistantStream: true
+		} } });
+	}
+	openEventStream(socket) {
+		this.sendStreamOpen(socket, `events-${String(this.streamSeq)}`, REMOTE_EVENT_STREAM_ENDPOINT, REMOTE_EVENT_STREAM_PAYLOAD);
+	}
+	sendStreamOpen(socket, streamId, endpoint, payload) {
+		const send = (msg) => socket.send?.(msg);
+		this.streamSockets.set(streamId, socket);
+		send(JSON.stringify({
+			type: "open",
+			streamId,
+			endpoint,
+			payload
+		}));
+	}
+	/** Either socket dying rebuilds the whole generation (guide Part 1). */
+	onDownlinkClosed() {
+		if (this.disposed) return;
+		if (!this.wsMux) return;
+		this.log("dsh-connection: remote.mux died — rebuilding generation");
+		this.fireCatalogInvalidated("all");
+		this.teardownSockets();
+		this.scheduleReconnect();
+	}
+	scheduleReconnect() {
+		if (this.disposed) return;
+		const rung = Math.min(this.reconnectAttempt, this.backoff.length - 1);
+		const delay = this.backoff[rung];
+		if (this.reconnectTimer !== void 0) clearTimeout(this.reconnectTimer);
+		this.reconnectTimer = setTimeout(() => {
+			if (this.disposed) return;
+			this.reconnectAttempt += 1;
+			this.ensureDownlinks();
+		}, delay);
+	}
+	teardownSockets() {
+		const sockets = [this.wsMux];
+		this.wsMux = void 0;
+		this.opened = false;
+		this.streamSockets.clear();
+		this.projections.clear();
+		this.workspaces = [];
+		for (const waiter of this.workspaceBaselineWaiters) waiter.resolve();
+		this.workspaceBaselineWaiters.clear();
+		if (this.reconnectTimer !== void 0) {
+			clearTimeout(this.reconnectTimer);
+			this.reconnectTimer = void 0;
+		}
+		for (const socket of sockets) socket?.close();
+	}
+	/**
+	* 0.1.2 remote.mux demux: `{item,end,error,streamId}` frames. Follow
+	* streams deliver a `snapshot` opening (seeds the baseline) then event
+	* entries (ring buffer appends); the $events stream delivers forwarded
+	* Cordis events (approval/question waterfalls → answerer registry).
+	*/
+	onStreamFrame(payload) {
+		const frame = payload;
+		if (typeof frame?.streamId !== "string") return;
+		if (frame.type === "item" && frame.value !== void 0) {
+			this.reconnectAttempt = 0;
+			const value = frame.value;
+			if (frame.streamId.startsWith("follow-")) this.onFollowItem(frame.streamId, value);
+			else if (frame.streamId.startsWith("events-")) this.onEventItem(value);
+			else if (frame.streamId.startsWith("workspaces-")) this.onWorkspaceItem(value);
+			else if (frame.streamId.startsWith("control-")) this.onControlItem(value);
+			return;
+		}
+		if (frame.type === "error") this.log(`dsh-connection: stream ${frame.streamId} failed`, frame.error?.code, frame.error?.message);
+		this.streamSockets.delete(frame.streamId);
+	}
+	/** session/follow item: snapshot seeds the baseline; events append; the
+	*  opted-in assistant-stream frames update the live tail (seq-less —
+	*  they never touch the durable cursor bookkeeping below). */
+	onFollowItem(streamId, value) {
+		if (value.type === "snapshot") {
+			const sessionId = this.sessionIdOfStream(streamId);
+			if (sessionId === null) return;
+			const snapshot = value;
+			const events = expandRecords(snapshot.records ?? []);
+			for (const event of events) this.appendEvent(sessionId, event);
+			this.seedSnapshotCursor(sessionId, snapshot.cursor);
+			if (snapshot.projections !== null && typeof snapshot.projections === "object") this.projections.set(sessionId, snapshot.projections);
+			this.seedLiveTailFromBaseline(sessionId, snapshot.assistantStream);
+			return;
+		}
+		if (value.type === "assistant-stream") {
+			const sessionId = this.sessionIdOfStream(streamId);
+			const frame = value.frame;
+			if (sessionId !== null && frame !== void 0) this.onAssistantStreamFrame(sessionId, frame);
+			return;
+		}
+		if (value.type === "event") {
+			const sessionId = this.sessionIdOfStream(streamId);
+			const entry = value;
+			if (sessionId !== null && entry.event !== void 0) for (const event of expandEntry(entry.event)) this.appendEvent(sessionId, event);
+		}
+	}
+	/** $events item: forwarded Cordis event frames (waterfall = answerable). */
+	onEventItem(value) {
+		if (value.type === "ready") {
+			if (typeof value.clientId === "string") this.eventClientId = value.clientId;
+			this.log("dsh-connection: $events stream ready");
+			this.armAnswerReap();
+			return;
+		}
+		if (value.type === "waterfall") {
+			const event = typeof value.event === "string" ? value.event : "";
+			const eventId = typeof value.eventId === "string" ? value.eventId : void 0;
+			const sessionId = typeof value.agentId === "string" ? value.agentId : void 0;
+			const request = value.request !== null && typeof value.request === "object" ? value.request : {};
+			if (eventId === void 0) return;
+			if (event === "approval/request") {
+				this.registerPending({
+					type: "approval/requested",
+					sessionId: sessionId ?? "",
+					...request
+				}, eventId);
+				return;
+			}
+			if (event === "user-questions/request") {
+				this.registerPending({
+					type: "question/requested",
+					sessionId: sessionId ?? "",
+					...request
+				}, eventId);
+				return;
+			}
+			this.log("dsh-connection: forwarded waterfall ignored", event);
+			return;
+		}
+		if (value.type === "cancel") {
+			const eventId = typeof value.eventId === "string" ? value.eventId : void 0;
+			if (eventId !== void 0) this.withdrawPending(eventId);
+			this.log("dsh-connection: forwarded waterfall cancelled");
+			return;
+		}
+		if (value.type === "settle") {
+			const eventId = typeof value.eventId === "string" ? value.eventId : void 0;
+			const outcome = typeof value.outcome === "string" ? value.outcome : "unknown";
+			if (eventId !== void 0) this.withdrawPending(eventId, outcome);
+			return;
+		}
+		if (value.type === "emit") {
+			if (value.event === "api-session/status" && Array.isArray(value.args)) {
+				const [sessionId, running] = value.args;
+				if (typeof sessionId === "string") this.running.set(sessionId, running === true);
+				return;
+			}
+			if (value.event === "commands/change") {
+				this.fireCatalogInvalidated("all");
+				return;
+			}
+			if (value.event === "agent-preset/selected" && typeof value.agentId === "string") {
+				this.fireCatalogInvalidated(value.agentId);
+				return;
+			}
+			this.log("dsh-connection: forwarded emit ignored", value.event);
+			return;
+		}
+	}
+	/**
+	* workspace/follow item (W2): baseline replaces the cache; increments
+	* apply in order (upsert/remove/order/archived — archived sessions are
+	* hidden from DSI's surfaces the same way the 0.1.1 registry did).
+	*/
+	onWorkspaceItem(value) {
+		if (value.type === "baseline") {
+			const baseline = value.value ?? {};
+			const rows = Array.isArray(baseline.items) ? baseline.items : [];
+			this.workspaces = rows.flatMap((row) => {
+				const w = row;
+				if (typeof w?.workspaceId !== "string" || typeof w?.path !== "string") return [];
+				return [{
+					workspaceId: w.workspaceId,
+					title: typeof w.title === "string" && w.title.length > 0 ? w.title : w.path,
+					path: w.path,
+					sessionIds: Array.isArray(w.sessionIds) ? w.sessionIds.filter((id) => typeof id === "string") : []
+				}];
+			});
+			for (const waiter of this.workspaceBaselineWaiters) waiter.resolve();
+			this.workspaceBaselineWaiters.clear();
+			this.log(`dsh-connection: workspace baseline (${this.workspaces.length} rows)`);
+			return;
+		}
+		if (value.type === "upsert") {
+			const w = value.workspace;
+			if (typeof w?.workspaceId !== "string" || typeof w?.path !== "string") return;
+			const row = {
+				workspaceId: w.workspaceId,
+				title: typeof w.title === "string" && w.title.length > 0 ? w.title : w.path,
+				path: w.path,
+				sessionIds: Array.isArray(w.sessionIds) ? w.sessionIds.filter((id) => typeof id === "string") : []
+			};
+			const idx = this.workspaces.findIndex((x) => x.workspaceId === row.workspaceId);
+			if (idx >= 0) this.workspaces.splice(idx, 1, row);
+			else this.workspaces.push(row);
+			return;
+		}
+		if (value.type === "remove" && typeof value.workspaceId === "string") {
+			this.workspaces = this.workspaces.filter((x) => x.workspaceId !== value.workspaceId);
+			return;
+		}
+	}
+	/**
+	* session/control item (W2): the baseline's per-session projections seed
+	* the store (permissions for the access chip); later projection frames
+	* update single keys. queue/job frames are not DSI state (ignored).
+	*/
+	onControlItem(value) {
+		if (value.type === "baseline") {
+			const baseline = value.value ?? {};
+			for (const [sessionId, block] of Object.entries(baseline.projections ?? {})) if (block !== null && typeof block === "object") this.projections.set(sessionId, block);
+			this.log(`dsh-connection: control baseline (${this.projections.size} sessions)`);
+			return;
+		}
+		if (value.type === "projection" && typeof value.sessionId === "string" && typeof value.key === "string") {
+			const block = this.projections.get(value.sessionId) ?? {
+				asOfSeq: 0,
+				values: {}
+			};
+			this.projections.set(value.sessionId, {
+				asOfSeq: typeof value.seq === "number" ? value.seq : block.asOfSeq,
+				values: {
+					...block.values,
+					[value.key]: value.value
+				}
+			});
+		}
+	}
+	/** Extract the sessionId from a follow-<sessionId>-<seq> stream id. */
+	sessionIdOfStream(streamId) {
+		const rest = streamId.slice(7);
+		const cut = rest.lastIndexOf("-");
+		return cut > 0 ? rest.slice(0, cut) : null;
+	}
+	pendingAnswers = /* @__PURE__ */ new Map();
+	/** Settlement ring: last outcome per rpcId, delivered-then-pruned. */
+	settledAnswers = /* @__PURE__ */ new Map();
+	/** Catalog-invalidation registry (Slash Menu W1) — listeners see every arm. */
+	catalogInvalidated = /* @__PURE__ */ new Set();
+	/** Subscribe to catalog invalidations ($events arms + socket reset). */
+	onCatalogInvalidated(listener) {
+		this.catalogInvalidated.add(listener);
+		return () => this.catalogInvalidated.delete(listener);
+	}
+	fireCatalogInvalidated(scope) {
+		for (const listener of this.catalogInvalidated) listener(scope);
+	}
+	onMuxFrame(payload, rpcId) {
+		this.reconnectAttempt = 0;
+		const frame = payload;
+		switch (frame?.type) {
+			case "session/subscribed":
+				if (typeof frame.sessionId === "string") this.seedBaseline(frame.sessionId, frame.lastSeq ?? -1);
+				return;
+			case "session/event":
+				if (frame.sessionId && frame.event) this.appendEvent(frame.sessionId, frame.event);
+				return;
+			case "approval/requested":
+			case "question/requested":
+				this.registerPending(frame, rpcId);
+				return;
+			case "approval/resolved":
+			case "question/resolved":
+				this.registerSettlement(frame);
+				return;
+			default: this.log("dsh-connection: mux frame ignored", frame?.type);
+		}
+	}
+	onHostFrame(payload) {
+		const frame = payload;
+		if (frame?.type === "host/session-status" && typeof frame.sessionId === "string") {
+			this.runningSeedRaces.add(frame.sessionId);
+			this.running.set(frame.sessionId, Boolean(frame.running));
+		}
+	}
+	/**
+	* 2026-08-26 running re-baseline: DSH pushes host/session-status only on
+	* transitions and the host stream sends no initial snapshot on (re)open —
+	* a downlink rebuilt mid-turn never sees the running:true flip that
+	* happened before it existed (the live bug: events kept flowing on the
+	* mux while the streaming indicator said idle). session.list is the host's
+	* documented reconnect baseline, so every generation opens with ONE list
+	* RPC seeding the whole map — which also prunes entries for sessions that
+	* died while disconnected. Pushes that land while the RPC is in flight win
+	* over the snapshot (they are strictly newer transitions); a seed from a
+	* superseded generation is dropped entirely.
+	*/
+	async seedRunning() {
+		const generation = this.generation;
+		this.runningSeedRaces = /* @__PURE__ */ new Set();
+		try {
+			const { items } = await this.listSessions();
+			if (this.disposed || generation !== this.generation) return;
+			const races = this.runningSeedRaces;
+			const next = /* @__PURE__ */ new Map();
+			for (const [id, running] of this.running) if (races.has(id)) next.set(id, running);
+			for (const row of items) if (!races.has(row.sessionId)) next.set(row.sessionId, row.running);
+			this.running = next;
+			this.log(`dsh-connection: running map re-baselined (${items.length} sessions)`);
+		} catch (err) {
+			this.log("dsh-connection: running re-baseline failed — pushes stay authoritative", err);
+		}
+	}
+	bufferFor(sessionId) {
+		let buf = this.buffers.get(sessionId);
+		if (!buf) {
+			buf = {
+				entries: [],
+				lastSeq: -1,
+				coverageFloor: -1
+			};
+			this.buffers.set(sessionId, buf);
+		}
+		return buf;
+	}
+	seedBaseline(sessionId, lastSeq) {
+		const buf = this.bufferFor(sessionId);
+		if (lastSeq > buf.lastSeq && buf.entries.length === 0) {
+			buf.lastSeq = lastSeq;
+			buf.coverageFloor = lastSeq;
+			return;
+		}
+		if (buf.lastSeq >= 0 && lastSeq < buf.lastSeq) {
+			buf.entries.length = 0;
+			buf.lastSeq = lastSeq;
+			buf.coverageFloor = lastSeq;
+		}
+	}
+	/**
+	* Snapshot cursor seed (0.1.2). A snapshot BELOW the buffered high-water
+	* mark means the upstream was rebuilt (stream restart): stale entries
+	* belong to the dead instance — reset the buffer to the snapshot truth
+	* (Wave 2 parity with the 0.1.1 rewound-baseline semantics).
+	*/
+	seedSnapshotCursor(sessionId, cursor) {
+		const buf = this.bufferFor(sessionId);
+		if (cursor > buf.lastSeq) {
+			buf.lastSeq = cursor;
+			buf.coverageFloor = cursor;
+			return;
+		}
+		if (buf.lastSeq >= 0 && cursor < buf.lastSeq) {
+			buf.entries.length = 0;
+			buf.lastSeq = cursor;
+			buf.coverageFloor = cursor;
+		}
+	}
+	appendEvent(sessionId, event) {
+		const buf = this.bufferFor(sessionId);
+		if (event.seq > buf.lastSeq) {
+			if (buf.lastSeq >= 0 && event.seq > buf.lastSeq + 1) {
+				buf.coverageFloor = Math.max(buf.coverageFloor, buf.lastSeq);
+				this.log(`dsh-connection: seq gap for ${sessionId} (${buf.lastSeq} → ${event.seq}) — resync required below ${event.seq}`);
+			}
+			buf.lastSeq = event.seq;
+			buf.entries.push(event);
+			const cap = ringCapacity();
+			if (buf.entries.length > cap) buf.entries.splice(0, buf.entries.length - cap);
+		}
+	}
+	/**
+	* Fold one assistant-stream frame into the session's live tail. Seq-less
+	* presentation state: never touches lastSeq/coverage — the durable
+	* cursor algebra stays event-entry-only. The host keeps ONE active
+	* attempt per session and drops its own accumulator on any continuity
+	* break (foreign attemptId, dense-index gap), so mirrors do the same.
+	*/
+	onAssistantStreamFrame(sessionId, frame) {
+		if (frame.type === "start") {
+			this.liveTails.set(sessionId, {
+				attemptId: frame.attemptId,
+				turn: frame.turn,
+				step: frame.step,
+				startedAfterSeq: frame.startedAfterSeq,
+				startedAt: Date.now(),
+				lastTime: Date.now(),
+				text: "",
+				reasoning: "",
+				nextIndex: 0
+			});
+			return;
+		}
+		const tail = this.liveTails.get(sessionId);
+		if (tail === void 0) return;
+		if (frame.type === "chunk") {
+			if (frame.attemptId !== tail.attemptId || frame.index !== tail.nextIndex) {
+				this.liveTails.delete(sessionId);
+				return;
+			}
+			const kind = frame.chunk?.type;
+			if (kind === "text-delta" && typeof frame.chunk?.text === "string") tail.text += frame.chunk.text;
+			else if (kind === "reasoning-delta" && typeof frame.chunk?.text === "string") tail.reasoning += frame.chunk.text;
+			tail.nextIndex += 1;
+			if (typeof frame.time === "number") tail.lastTime = frame.time;
+			return;
+		}
+		this.liveTails.delete(sessionId);
+	}
+	/**
+	* Seed the live tail from a follow-opening snapshot's assistantStream
+	* baseline (mux-drop reopen mid-attempt): expand the compact stream
+	* records' text/reasoning runs into the tail. No activeAttempt → clear
+	* any remembered tail — the fresh opening is authoritative for what is
+	* still in flight.
+	*/
+	seedLiveTailFromBaseline(sessionId, baseline) {
+		const active = baseline?.activeAttempt;
+		if (active === void 0) {
+			this.liveTails.delete(sessionId);
+			return;
+		}
+		const tail = {
+			attemptId: active.attemptId,
+			turn: active.turn,
+			step: active.step,
+			startedAfterSeq: active.startedAfterSeq,
+			startedAt: Date.now(),
+			lastTime: Date.now(),
+			text: "",
+			reasoning: "",
+			nextIndex: active.nextIndex
+		};
+		for (const record of active.stream ?? []) {
+			if (record.type === "text-chunks" || record.type === "reasoning-chunks") {
+				const texts = record.texts;
+				const joined = Array.isArray(texts) ? texts.filter((t) => typeof t === "string").join("") : "";
+				if (record.type === "text-chunks") tail.text += joined;
+				else tail.reasoning += joined;
+			}
+			const times = compactRecordTailTime(record);
+			if (times !== void 0) tail.lastTime = times;
+		}
+		this.liveTails.set(sessionId, tail);
+	}
+	/**
+	* The session's live tail for the events poll, or null when no attempt
+	* is in flight. Served with the FULL accumulated text each poll — the
+	* client replaces its streaming bubble wholesale (no cross-poll fragment
+	* bookkeeping, so reconnects/retries converge from the served truth).
+	*/
+	liveAssistantStream(sessionId) {
+		const tail = this.liveTails.get(sessionId);
+		if (tail === void 0) return null;
+		return {
+			id: `a:${String(tail.turn)}:${String(tail.step)}`,
+			turn: tail.turn,
+			step: tail.step,
+			seq: tail.startedAfterSeq,
+			time: tail.lastTime,
+			text: tail.text,
+			reasoning: tail.reasoning
+		};
+	}
+	/**
+	* Delta slice: events with seq > n, plus current lastSeq/running.
+	* Wave 4.2: `gap` is true when the caller's `since` mark fell into a hole
+	* the buffer no longer covers (mux drop). The response then carries the
+	* resync flag so the client re-reads from the ledger instead of trusting
+	* a partial delta (BC-4).
+	*/
+	eventsSince(sessionId, n) {
+		const buf = this.bufferFor(sessionId);
+		const events = buf.entries.filter((e) => e.seq > n);
+		const firstDelta = events[0]?.seq;
+		const gap = firstDelta !== void 0 && firstDelta > n + 1;
+		return {
+			events,
+			lastSeq: buf.lastSeq,
+			running: this.running.get(sessionId) ?? false,
+			gap
+		};
+	}
+	/**
+	* Subscribe one session (0.1.2): create its buffer and open a
+	* session/follow logical stream on the live carrier (or mark it for the
+	* next generation). Idempotent; the snapshot frame seeds the baseline.
+	* A repeat call while THIS generation already holds the session's follow
+	* stream is a no-op — the api-dsh events route calls subscribe on every
+	* poll, and reopening would replace the stream (same streamId → fresh
+	* snapshot) on every tick. A stream 'end'/'error' frame drops the
+	* tracking entry so the next poll reopens and self-heals.
+	*/
+	subscribe(sessionId) {
+		this.bufferFor(sessionId);
+		const socket = this.wsMux;
+		if (socket === void 0) return;
+		if (this.opened === false) {
+			this.pendingSubscribes.add(sessionId);
+			return;
+		}
+		if (this.streamSockets.has(followStreamId(sessionId, this.streamSeq))) return;
+		this.openFollowWithProbe(socket, sessionId);
+	}
+	/**
+	* Open the follow stream with the best-known address NOW (sync, the
+	* historical contract), then — when this turns out to be a subagent child
+	* nobody has folded yet — probe and REOPEN with the parent address (the
+	* mux replaces a stream id; the fresh snapshot reseeds the baseline).
+	*/
+	openFollowWithProbe(socket, sessionId) {
+		this.openFollowStream(socket, sessionId);
+		if (!this.subagentHints.has(sessionId) && !this.hintProbed.has(sessionId)) {
+			this.hintProbed.add(sessionId);
+			this.probeHintThenSubscribe(sessionId, socket);
+		}
+	}
+	/** Resolve one session's address hint after a plain-form follow went out;
+	*  on a folded hint REOPEN the follow with the parent address (a plain
+	*  form on a subagent child is rejected by the host and the stream would
+	*  stay dead for the whole generation). Skipped when the carrier moved on
+	*  (generation rebuilt / disposed) during the list RPC — onMuxOpen
+	*  reopens every buffer with the then-current addresses. */
+	async probeHintThenSubscribe(sessionId, socket) {
+		try {
+			if (!this.subagentHints.has(sessionId)) await this.rawListSessions();
+		} catch {}
+		if (this.disposed || this.wsMux !== socket || this.opened === false) return;
+		if (this.subagentHints.has(sessionId)) this.openFollowStream(socket, sessionId);
+	}
+	/**
+	* Per-session projection value (W2): follow-snapshot + control-baseline
+	* + control projection frames, newest wins. permissions (access chip),
+	* modelSelection, todos, plan … — null when never seen.
+	*/
+	projectionValue(sessionId, key) {
+		return this.projections.get(sessionId)?.values?.[key];
+	}
+	/** The whole stored block for one session (null when absent). */
+	projectionBlock(sessionId) {
+		return this.projections.get(sessionId) ?? null;
+	}
+	/**
+	* Bounded wait for the session's FIRST projection baseline (0.1.2 cold
+	* loads seed the access mode + admission numbers from the follow/control
+	* store — session/page carries no projections block). Resolves
+	* immediately when a block exists; null after timeoutMs (an unfenced or
+	* slow host degrades to the documented defaults, never a hang).
+	*/
+	async waitForProjections(sessionId, timeoutMs = 2500) {
+		this.ensureDownlinks();
+		this.subscribe(sessionId);
+		const deadline = Date.now() + timeoutMs;
+		for (;;) {
+			const block = this.projectionBlock(sessionId);
+			if (block !== null) return block;
+			if (Date.now() >= deadline) return null;
+			await new Promise((resolve) => setTimeout(resolve, 50));
+		}
+	}
+	/**
+	* True once the workspace/follow baseline landed. Registers the waiter
+	* even while the carrier is CONNECTING (the first RPC often races the
+	* handshake); bounded by 3s — an honest empty after that, never a hang.
+	*/
+	async awaitWorkspaceBaseline() {
+		if (this.workspaces.length > 0) return true;
+		this.ensureDownlinks();
+		if (this.wsMux === void 0) return false;
+		const waiter = Promise.withResolvers();
+		this.workspaceBaselineWaiters.add(waiter);
+		await Promise.race([waiter.promise, new Promise((r) => setTimeout(r, 3e3))]);
+		this.workspaceBaselineWaiters.delete(waiter);
+		return this.workspaces.length > 0;
+	}
+	/** True when the session has a live baseline (subscribed at least once). */
+	hasBaseline(sessionId) {
+		return this.buffers.has(sessionId) && this.bufferFor(sessionId).lastSeq >= 0;
+	}
+	isRunning(sessionId) {
+		return this.running.get(sessionId) ?? false;
+	}
+	/** approval/requested | question/requested → registry (idempotent by rpcId). */
+	registerPending(frame, rpcId) {
+		const sessionId = typeof frame.sessionId === "string" ? frame.sessionId : "";
+		if (!sessionId) {
+			this.log("dsh-connection: answerable frame without sessionId — ignored", frame?.type);
+			return;
+		}
+		if (typeof rpcId !== "string" || rpcId.length === 0) {
+			this.log("dsh-connection: answerable frame without rpcId — ignored", frame?.type);
+			return;
+		}
+		const kind = frame.type === "approval/requested" ? "approval" : "question";
+		this.pendingAnswers.set(rpcId, {
+			rpcId,
+			sessionId,
+			kind,
+			body: frame,
+			receivedAt: Date.now(),
+			deliveredGen: this.generation
+		});
+		this.log(`dsh-connection: pending ${kind} registered (${rpcId}) for ${sessionId}`);
+	}
+	/**
+	* Withdraw one pending answer (0.1.2 $events settle/cancel): remove the
+	* registry entry and record the outcome in the settlement ring. Unknown
+	* ids settle nothing (answered before we subscribed — honest no-op).
+	*/
+	withdrawPending(eventId, outcome) {
+		const pending = this.pendingAnswers.get(eventId);
+		if (pending === void 0) {
+			this.log(`dsh-connection: settlement with no matching pending (${eventId}) — ignored`);
+			return;
+		}
+		this.pendingAnswers.delete(eventId);
+		this.settledAnswers.set(eventId, {
+			rpcId: eventId,
+			sessionId: pending.sessionId,
+			kind: pending.kind,
+			outcome: outcome ?? "cancelled",
+			settledAt: Date.now()
+		});
+		this.log(`dsh-connection: ${pending.kind} settled (${eventId}) outcome=${outcome ?? "cancelled"}`);
+	}
+	/**
+	* Schedule the still-pending replay reap for this generation (ready
+	* frame just arrived). The host replays every still-pending waterfall
+	* into the new generation, but the ready frame can hit the wire before
+	* the replayed frames drain, so the check runs after a short grace —
+	* entries an older generation registered and the replay did NOT
+	* re-confirm finished while we were disconnected (answered, cancelled,
+	* or aborted); keeping them pending resurrects zombie answer cards the
+	* user can answer forever with no effect.
+	*/
+	armAnswerReap() {
+		clearTimeout(this.answerReapTimer);
+		this.answerReapTimer = setTimeout(() => this.reapUnconfirmedPending(), this.answerReapGraceMs);
+	}
+	/** Withdraw every pending answer not re-delivered by the current generation. */
+	reapUnconfirmedPending() {
+		for (const [eventId, pending] of [...this.pendingAnswers]) {
+			if (pending.deliveredGen >= this.generation) continue;
+			this.log(`dsh-connection: reap unconfirmed pending (${eventId}) from generation ${pending.deliveredGen} — not in generation ${this.generation} replay`);
+			this.withdrawPending(eventId);
+		}
+	}
+	/**
+	* After OUR answer was accepted the question is done — withdraw the
+	* registry entry with the outcome we sent instead of waiting for the
+	* host's settle broadcast, which races generation rebuilds and can be
+	* lost entirely (the answered card would resurrect on the next page
+	* load from a stale pendingAnswers).
+	*/
+	forgetAnswered(rpcId, value) {
+		this.withdrawPending(rpcId, typeof value === "string" ? value : "answered");
+	}
+	/** approval/resolved | question/resolved → pending removed, settlement recorded. */
+	registerSettlement(frame) {
+		const sessionId = typeof frame.sessionId === "string" ? frame.sessionId : "";
+		if (!sessionId) {
+			this.log("dsh-connection: settlement frame without sessionId — ignored", frame?.type);
+			return;
+		}
+		const kind = frame.type === "approval/resolved" ? "approval" : "question";
+		const outcome = typeof frame.outcome === "string" ? frame.outcome : "unknown";
+		let rpcId;
+		if (kind === "approval" && typeof frame.approvalId === "string") rpcId = [...this.pendingAnswers.values()].find((p) => p.sessionId === sessionId && p.body.approvalId === frame.approvalId)?.rpcId;
+		else if (kind === "question" && typeof frame.questionRpcId === "string") rpcId = frame.questionRpcId;
+		if (rpcId) {
+			this.pendingAnswers.delete(rpcId);
+			this.settledAnswers.set(rpcId, {
+				rpcId,
+				sessionId,
+				kind,
+				outcome,
+				settledAt: Date.now()
+			});
+			this.log(`dsh-connection: ${kind} settled (${rpcId}) outcome=${outcome}`);
+		} else this.log(`dsh-connection: settlement with no matching pending (${frame?.type}) — ignored`);
+	}
+	/** Pending answers for a session (for the PollResponse extension). */
+	pendingFor(sessionId) {
+		return [...this.pendingAnswers.values()].filter((p) => p.sessionId === sessionId);
+	}
+	/** Recent settlements for a session (ring: delivered-then-pruned). */
+	settlementsFor(sessionId) {
+		return [...this.settledAnswers.values()].filter((s) => s.sessionId === sessionId);
+	}
+	/** Delivery hook: drop settlements the client has already seen (ring prune). */
+	pruneSettlements(sessionId, seenRpcIds) {
+		for (const id of seenRpcIds) {
+			const s = this.settledAnswers.get(id);
+			if (s && s.sessionId === sessionId) this.settledAnswers.delete(id);
+		}
+	}
+	/** session.list → normalized rows (DsiSessionSummary + raw projections). */
+	async listSessions() {
+		return { items: (await this.rawListSessions()).map(normalizeSessionRow) };
+	}
+	/**
+	* The workspace-RPC OWNER for a session (2026-09-10): the host keys
+	* workspaceFiles by the OWNING agent session and refuses sub-agent ids
+	* (session/not-found / agent-busy — a sub-agent session is not an RPC
+	* address). A sub-agent's workspace IS its root ancestor's, so walk the
+	* parentSessionId chain (session.list) to the root; a root session
+	* resolves to itself. Cycles guard themselves.
+	*/
+	async workspaceOwnerSessionId(sessionId) {
+		const { items } = await this.listSessions();
+		const parentOf = new Map(items.map((s) => [s.sessionId, s.parentSessionId ?? null]));
+		let cursor = sessionId;
+		const seen = /* @__PURE__ */ new Set();
+		while (!seen.has(cursor)) {
+			seen.add(cursor);
+			const parent = parentOf.get(cursor);
+			if (!parent || parent === cursor) break;
+			cursor = parent;
+		}
+		return cursor;
+	}
+	/** Raw session/list rows (0.1.2) — projections.asOfSeq drives page calls. */
+	async rawListSessions() {
+		const raw = await this.rpc(DSH_METHODS.list, DSH_ARGS.list());
+		const rows = Array.isArray(raw?.items) ? raw.items : [];
+		for (const row of rows) this.foldSubagentHint(row);
+		return rows;
+	}
+	/**
+	* Fold one list row's subagent identity into the hint cache. Only rows
+	* the host stamps `origin:'subagent'` with a readable parent and a
+	* descriptor lifecycle mode land here; a half-readable row keeps no hint
+	* so the host's own rejection (surfaced honestly downstream) names the
+	* truth instead of DSI guessing a mode.
+	*/
+	foldSubagentHint(row) {
+		if (row.origin !== "subagent") return;
+		if (typeof row.parentSessionId !== "string" || row.parentSessionId === "") return;
+		const identity = row.projections?.values?.["subagent"];
+		const mode = identity !== null && typeof identity === "object" ? identity.mode : void 0;
+		if (mode !== "one-shot" && mode !== "continuable") return;
+		this.subagentHints.set(row.sessionId, {
+			parentSessionId: row.parentSessionId,
+			mode
+		});
+	}
+	/**
+	* The session/page + session/follow address for one session id: the
+	* parent-addressed subagent form when a hint is folded, else the plain
+	* session form. Subagent child ids are bare UUIDs (the spawner mints
+	* `SessionId(randomUUID())`) — the id's SHAPE is never a discriminator;
+	* only the host row's origin is.
+	*/
+	addressFor(sessionId) {
+		const hint = this.subagentHints.get(sessionId);
+		if (hint === void 0) return {
+			kind: "session",
+			sessionId
+		};
+		return {
+			kind: "subagent",
+			parentSessionId: hint.parentSessionId,
+			childSessionId: sessionId,
+			mode: hint.mode
+		};
+	}
+	/**
+	* The tail-page through-cursor (0.1.2 session/page `throughSeq`). The
+	* list projection's watermark (asOfSeq) is the LOWEST served-projection
+	* row seq (session-projection-cache cachedSnapshot) and FREEZES while no
+	* projection updates — mid-turn it sat at the last projection-relevant
+	* event while the follow stream ran dozens of seqs ahead, so a page cut
+	* there ended below the live truth, rewound the client's mark, and
+	* pinned every later poll into a gap→resync loop. The follow buffer's
+	* cursor IS the host's stream truth (seeded by the host's own snapshot
+	* cursor, advanced only by host events), so a subscribed session pages
+	* through it; the watermark stays the fallback for sessions without a
+	* buffer (never subscribed — the pre-2026-09 behavior).
+	*
+	* A session the list does not name at all, and a listed row whose served
+	* projection carries no cursor, both page with `throughSeq: -1` — the
+	* 0.1.3 wire's unconstrained tail-page form (validated ≥ −1; the page is
+	* bounded by its own cursor, never by ours). The HOST still owns every
+	* refusal: a missing session rejects session/not-found before the cursor
+	* is read (the cold load's 404 branch), never a client-invented error.
+	*
+	* 0.1.3-alpha.1: cold fork children serve `asOfSeq: -1` (the host's cold
+	* blank-probe left with the v2 list projection) — a negative watermark is
+	* "no served cursor", not "below the ledger head".
+	*/
+	async pageCursorFor(sessionId) {
+		const live = this.bufferFor(sessionId).lastSeq;
+		if (live >= 0) return live;
+		const throughSeq = (await this.rawListSessions()).find((r) => r.sessionId === sessionId)?.projections?.asOfSeq;
+		if (typeof throughSeq === "number" && throughSeq >= 0) return throughSeq;
+		return -1;
+	}
+	/**
+	* session.history successor (0.1.2): the tail page via `session/page`.
+	* throughSeq comes from pageCursorFor: the follow buffer's cursor when
+	* the session has one, else the session/list projections (asOfSeq) of
+	* the same session, else −1 — the 0.1.3 unconstrained tail-page form.
+	*/
+	async history(sessionId) {
+		const throughSeq = await this.pageCursorFor(sessionId);
+		return this.pageAsHistory(await this.rpc(DSH_METHODS.page, DSH_ARGS.page({
+			address: this.addressFor(sessionId),
+			throughSeq
+		})));
+	}
+	/** Workspace registry adoption (2026-08-23, DSH parity): the Add
+	*  workspace button's host call. Raw view passthrough — DSI renders
+	*  only title/path; ordering and session membership stay host-owned. */
+	async createWorkspace(path) {
+		return await this.rpc(DSH_METHODS.workspaceCreate, DSH_ARGS.workspaceCreate({ path }));
+	}
+	/** Workspace rename (Chip Menu ADR D3): {request:{workspaceId,title}}
+	*  → the updated Workspace view. Refusals throw DshRpcError
+	*  (workspace/not-found, workspace/name-conflict). No cache mutation —
+	*  the workspace/follow upsert frame owns the registry (ADR D6). */
+	async renameWorkspace(workspaceId, title) {
+		return await this.rpc(DSH_METHODS.workspaceRename, DSH_ARGS.workspaceRename(workspaceId, title));
+	}
+	/** Workspace delete (Chip Menu ADR D3): {request:{workspaceId}} → the
+	*  removed id. The host removes ONLY the registry row (sessions survive,
+	*  ungrouped); the workspace/follow remove frame owns the registry
+	*  (ADR D6) — no local mutation here. */
+	async deleteWorkspace(workspaceId) {
+		return await this.rpc(DSH_METHODS.workspaceDelete, DSH_ARGS.workspaceDelete(workspaceId));
+	}
+	/** Goal Bar (2026-09-08, ADR amendment): one goal mutation through the
+	*  host's Goal Remotes — goals/pause | goals/resume | goals/clear |
+	*  goals/edit with the CAS ref {id, revision} (a stale revision loses
+	*  host-side). goals/edit additionally carries the changed-fields
+	*  request {objective?, maxGoalRounds?} (Goal Editor, 2026-09-09). The
+	*  raw RemoteResult passes through; the route maps refusals. */
+	async goalVerb(verb, sessionId, ref, request) {
+		return this.rpc(`goals/${verb}`, request === void 0 ? {
+			agentId: sessionId,
+			ref
+		} : {
+			agentId: sessionId,
+			ref,
+			request
+		});
+	}
+	/**
+	* workspaceFiles/read — one page of a UTF-8 text file inside the
+	* session's workspace (Workspace Explorer W2 task 2.1). Flat args
+	* {workspaceFileScopeId, path, range} per the descriptor — NO request
+	* wrapper (scope wire renamed from agentId, host 2026-09-09).
+	* Host refusals (not-found, outside-workspace, too-large, not-text,
+	* not-regular-file) reject as DshRpcError; the route maps the codes.
+	*
+	* @param sessionId - owning session; the host confines the read to its
+	*                    workspace root by containment, never prefix match.
+	* @param path - workspace path, absolute or root-relative.
+	* @param range - line window; omitted fields take the host's page defaults.
+	*/
+	async readWorkspaceFile(sessionId, path, range) {
+		return await this.rpc(DSH_METHODS.workspaceFileRead, DSH_ARGS.workspaceFileRead(sessionId, path, range));
+	}
+	/**
+	* workspaceFiles/readBytes — one byte window of a workspace file, raw
+	* bytes (base64 receipt), no text decoding and no binary refusal
+	* (2026-09-10: binary previews such as images read through this; `read`
+	* refuses them workspace-file/not-text).
+	*
+	* @param sessionId - owning session; the host confines the read to its
+	workspace root by containment.
+	* @param path - workspace path, absolute or root-relative.
+	* @param range - byte window {offset, length}; omitted fields take the
+	host's window defaults.
+	*/
+	async readWorkspaceFileBytes(sessionId, path, range) {
+		return await this.rpc(DSH_METHODS.workspaceFileReadBytes, DSH_ARGS.workspaceFileReadBytes(sessionId, path, range));
+	}
+	/**
+	* workspaceFiles/list — one directory level inside the session's
+	* workspace (Workspace Explorer bugfix 2026-09-09: the picker's
+	* directoryPicker/list is native-only on real hosts — the LIVE tree
+	* lists through this session-authorized namespace instead). Flat args
+	* {workspaceFileScopeId, path}; path is workspace-relative, '' = the root.
+	*/
+	async listWorkspaceDirectory(sessionId, path) {
+		return await this.rpc(DSH_METHODS.workspaceFileList, DSH_ARGS.workspaceFileList(sessionId, path));
+	}
+	/** The workspace registry (2026-08-23 registry parity) — the AUTHORITY
+	*  for DSI's workspace pills/chips: a deleted workspace disappears, and
+	*  sessions outside every registry entry render cue-less (DSH's
+	*  Ungrouped). Membership is sessionIds, not cwd matching. */
+	async listWorkspaces() {
+		if (!await this.awaitWorkspaceBaseline()) this.log("dsh-connection: workspace baseline did not land in time — honest empty");
+		return { items: [...this.workspaces] };
+	}
+	/**
+	* host.listDirectory — one browsed directory level for the Add-workspace
+	* folder picker (DSH parity: the directory-picker browse capability).
+	* Absent path lists the host home directory. Conservative normalize:
+	* garbage rows drop out, never throw, never invent data.
+	*/
+	async listDirectory(path) {
+		const raw = await this.rpc(DSH_METHODS.listDirectory, DSH_ARGS.listDirectory(path));
+		const entry = (v) => {
+			if (v === null || typeof v !== "object") return null;
+			const e = v;
+			if (typeof e.name !== "string" || typeof e.path !== "string") return null;
+			return {
+				name: e.name,
+				path: e.path,
+				hidden: e.hidden === true
+			};
+		};
+		const rows = (v) => Array.isArray(v) ? v.flatMap((x) => {
+			const e = entry(x);
+			return e ? [e] : [];
+		}) : [];
+		return {
+			path: typeof raw?.path === "string" ? raw.path : "",
+			home: typeof raw?.home === "string" ? raw.home : "",
+			crumbs: rows(raw?.crumbs),
+			entries: rows(raw?.entries),
+			truncated: raw?.truncated === true
+		};
+	}
+	/**
+	* host.pickDirectory — the NATIVE interaction: the host opens one OS
+	* chooser on its own display and resolves the picked absolute path
+	* (null = operator cancelled). The signal follows the caller — a
+	* disconnected browser closes the host's dialog mid-choice
+	* (api-proxy pickDirectory's carrier contract).
+	*/
+	/**
+	* Wave 3 (task 3.2) — session.attachment: the session-authorized durable
+	* image read. Returns the ref plus canonical base64 data; host refusals
+	* (unknown id, foreign session) reject as DshRpcError → 502 upstream.
+	*
+	* @param sessionId - owning session (authorization scope).
+	* @param attachmentId - durable content-addressed id from an ImageBlock.
+	*/
+	async readAttachment(sessionId, attachmentId) {
+		return await this.rpc(DSH_METHODS.attachment, DSH_ARGS.attachment({
+			sessionId,
+			attachmentId
+		}));
+	}
+	async pickDirectory(signal) {
+		const raw = await this.rpc(DSH_METHODS.pickDirectory, DSH_ARGS.pickDirectory(), signal);
+		return { path: typeof raw?.path === "string" ? raw.path : null };
+	}
+	/**
+	* POC-2 W3 — session.history PAGE ending at beforeSeq−1 (ledger truth, BC-4).
+	* Live-probed semantics (PRD §1.2): the page covers events with seq <
+	* beforeSeq; hasMore=false at the ledger head. Drives load-older paging —
+	* the ring buffer is freshness-only and never consulted here.
+	*/
+	async historyPage(sessionId, beforeSeq) {
+		const throughSeq = await this.pageCursorFor(sessionId);
+		return this.pageAsHistory(await this.rpc(DSH_METHODS.page, DSH_ARGS.page({
+			address: this.addressFor(sessionId),
+			throughSeq,
+			beforeSeq
+		})));
+	}
+	/** Adapt a 0.1.2 SessionPage {records,hasMore} to the DshHistoryPage shape. */
+	pageAsHistory(raw) {
+		const page = raw;
+		return {
+			events: expandRecords(Array.isArray(page?.records) ? page.records : []).map((event) => ({ event })),
+			hasMore: page?.hasMore === true
+		};
+	}
+	/**
+	* POC-2 W3 — session.create {cwd?, agentPreset?} → {sessionId, …}.
+	* Live-probed round-trip 2026-08-21 (probe7 → real session id).
+	*/
+	async createSession(cwd, agentPreset) {
+		return await this.rpc(DSH_METHODS.create, DSH_ARGS.create({
+			...cwd === void 0 ? {} : { cwd },
+			...agentPreset === void 0 ? {} : { agentPreset }
+		}));
+	}
+	/**
+	* session/fork {request:{sessionId,atSeq?}} → {sessionId} — the fork child
+	* (The Fork Button ADR, 2026-09-01). An undefined atSeq is OMITTED from the
+	* args, never sent as null: the host then cuts at the source's last
+	* completed turn (host-enforced; see DSH_METHODS.fork for the pinned
+	* contract and refusals).
+	*/
+	async forkSession(sessionId, atSeq) {
+		return await this.rpc(DSH_METHODS.fork, DSH_ARGS.fork({
+			sessionId,
+			...atSeq === void 0 ? {} : { atSeq }
+		}));
+	}
+	/**
+	* POC-2 W3 — agentPreset.list → {presets:[…]} (live-probed 2026-08-21,
+	* rpc-map.ts line 54). Presets are the picker's only source of truth.
+	* The shipped-preset English overlay honors ~/.dsi/settings.yaml
+	* `dsh.presetEnglish` (default true; read live per call — no cache, so
+	* an operator edit applies on the next fetch without a restart).
+	*/
+	async listPresets() {
+		const overlayEnglish = readDshPresetEnglishConfig().presetEnglish;
+		const raw = await this.rpc(DSH_METHODS.presets, DSH_ARGS.presets());
+		return { presets: (Array.isArray(raw?.presets) ? raw.presets : []).map((row) => normalizePreset(row, overlayEnglish)) };
+	}
+	/**
+	* session.prompt — returns after the receipt only (BC-3 boundary lives
+	* upstream). Wave 2: a string payload still maps to exactly one text
+	* part (byte-identical for every pre-existing caller); a content array
+	* passes through verbatim — the route owns validation and ordering
+	* (buildPromptContent, images first, text last).
+	*/
+	async prompt(sessionId, payload, mode = "queue") {
+		const content = typeof payload === "string" ? [{
+			type: "text",
+			text: payload
+		}] : payload;
+		return await this.rpc(DSH_METHODS.prompt, DSH_ARGS.prompt({
+			requestId: this.rpcIdFactory(),
+			sessionId,
+			mode,
+			content,
+			clientTimeZone: Intl.DateTimeFormat().resolvedOptions().timeZone
+		}));
+	}
+	/**
+	* commands/execute (2026-08-25 fix) — the NATIVE slash-command surface the
+	* host's own web GUI uses (Typert Gateway remote; session.prompt has no
+	* slash interception — the 2026-08-25 RCA). Executes one line on the
+	* session's agent; the host durably logs command/run + command/done (and
+	* the permission command appends its knob events — the poll fold's
+	* confirmation). Returns null on an admission miss (the line named no
+	* registered command): ok:true, the command never ran — the honest
+	* receipt callers must distinguish from a success.
+	*/
+	async executeCommand(sessionId, line) {
+		return await this.rpc(DSH_METHODS.commandExecute, DSH_ARGS.commandExecute(sessionId, line, [])) ?? null;
+	}
+	/**
+	* commands/list (Slash Menu W1, task 1.2) — the host's command catalog,
+	* name-sorted rows {name, description, input?{hint, images?}}. Live-pinned
+	* 2026-08-30 (see tests/unit/dsh-rpc.test.ts): agentId IS the sessionId.
+	* May resume a cold session on the host — callers fetch on first menu
+	* open, never on panel mount (ADR §3.3).
+	*/
+	async listCommands(sessionId) {
+		return await this.rpc(DSH_METHODS.commandsList, DSH_ARGS.commandsList(sessionId));
+	}
+	/**
+	* skills/list (Slash Menu W1, task 1.2) — the session's user-invocable
+	* skill catalog {skills:[{name, description, whenToUse?, modelInvocable}]}.
+	* Live-pinned 2026-08-30. Never activates a cold session — the menu may
+	* read it freely on first open.
+	*/
+	async listSkills(sessionId) {
+		return await this.rpc(DSH_METHODS.skillsList, DSH_ARGS.skillsList(sessionId));
+	}
+	/** session.cancel */
+	async cancel(sessionId) {
+		return await this.rpc(DSH_METHODS.cancel, DSH_ARGS.cancel({ sessionId }));
+	}
+	/**
+	* POC-3 W3 (3.1) — session.rename {sessionId, title}.
+	*
+	* Appends a session/title event with the `user` source — pins the title
+	* against automatic regeneration (sessions.ts rename doc). The host
+	* normalizes; a title that normalizes to empty fails `title-invalid` (an
+	* RpcError → 502 upstream). Session-backed subagents reject `agent-busy`.
+	*/
+	async renameSession(sessionId, title) {
+		return await this.rpc(DSH_METHODS.rename, DSH_ARGS.rename({
+			sessionId,
+			title
+		}));
+	}
+	/**
+	* POC-3 W3 (3.2) — session.models {sessionId} → the model directory.
+	*
+	* Provider lookups run independently on the host (sessions.ts): `groups`
+	* are successfully-loaded catalogs, `failures` are provider-local
+	* diagnostics — successful groups remain usable. Garbage-safe normalize
+	* below never throws (task 3.2-T: garbage catalog → empty, not an error).
+	*/
+	async listModels(_sessionId) {
+		return normalizeModelDirectory(await this.rpc(DSH_METHODS.modelCatalog, DSH_ARGS.modelCatalog()));
+	}
+	/**
+	* POC-3 W3 (3.2) — session.selectModel {sessionId, provider, model,
+	* reasoningEffort?} → {selected: ModelSelection}. Catalog membership is
+	* advisory on the host — an exact-route selection still validates the
+	* effort. Subagents reject `session/agent-busy` (RpcError → 502 upstream).
+	*/
+	async selectModel(sessionId, provider, model, reasoningEffort) {
+		return normalizeModelSelection((await this.rpc(DSH_METHODS.selectModel, DSH_ARGS.selectModel({
+			sessionId,
+			provider,
+			model,
+			...reasoningEffort !== void 0 ? { reasoningEffort } : {}
+		})))?.selected);
+	}
+	/**
+	* POC-3 W1 — answer a pending approval/question via the dedicated
+	* client-response carrier (POST /api/respond). NOT a unary method: no
+	* DSH_METHODS entry, no rpcId minted here — the rpcId is the REQUEST's
+	* stable id (registry key), echoed in the envelope. Receipt is a union,
+	* not ok/error: {accepted:false, reason} is a SUCCESSFUL exchange (BC-B
+	* upstream maps it to 200 + settle-elsewhere). Transport failure still
+	* throws (route maps to 503 — card stays answerable, lock released).
+	*/
+	/**
+	* POC-3 W1 → 0.1.2: an answer is a `$events/result` unary RPC
+	* {clientId, eventId, outcome} returning to the SAME generation whose
+	* $events stream delivered the waterfall (rpcId = the eventId DSI
+	* registered the card under). The outcome's `value` is the waterfall
+	* listener's RETURN VALUE, and the host consumes it verbatim — a
+	* question's value must BE the AskUserQuestionAnswer `{answers:[…]}`
+	* (the live host crashes the tool on any other shape, losing the
+	* answer); an approval's value is the outcome string. The panel's
+	* legacy `{sessionId, answer:{answers}}` wrapper is unwrapped here so
+	* the wire carries the host's contract, not the panel's convenience.
+	*/
+	async respond(rpcId, payload) {
+		if (this.eventClientId === null) throw new Error("dsh-connection: no $events generation to answer through yet");
+		const { sessionId, ...rest } = payload;
+		const value = rest.outcome !== void 0 ? rest.outcome : rest.answer !== void 0 ? rest.answer : rest.answers !== void 0 ? { answers: rest.answers } : rest;
+		try {
+			await this.sendEventResult(rpcId, value);
+			this.forgetAnswered(rpcId, value);
+		} catch (err) {
+			if (err instanceof DshRpcError && err.code === "not-pending") return {
+				accepted: false,
+				reason: "not-pending"
+			};
+			if (err instanceof DshRpcError && err.code === "gateway/internal" && err.message.includes("no active event stream")) {
+				const previous = this.eventClientId;
+				if (previous !== null && await this.refreshEventGeneration(previous)) {
+					await this.sendEventResult(rpcId, value);
+					this.forgetAnswered(rpcId, value);
+					return { accepted: true };
+				}
+			}
+			throw err;
+		}
+		return { accepted: true };
+	}
+	/** One $events/result answer under the CURRENT generation's clientId. */
+	sendEventResult(rpcId, value) {
+		return this.rpc(REMOTE_EVENT_RESULT_ENDPOINT, {
+			clientId: this.eventClientId,
+			eventId: rpcId,
+			outcome: {
+				kind: "result",
+				value
+			}
+		}).then(() => void 0);
+	}
+	/**
+	* Rebuild the mux generation immediately (bypassing the reconnect
+	* ladder) and wait until a NEW $events ready frame lands or the deadline
+	* expires. Returns true only when a fresh clientId was observed — the
+	* caller may retry an answer against it.
+	*/
+	async refreshEventGeneration(previousClientId) {
+		this.log("dsh-connection: $events generation stale — rebuilding for the answer retry");
+		if (this.reconnectTimer !== void 0) {
+			clearTimeout(this.reconnectTimer);
+			this.reconnectTimer = void 0;
+		}
+		this.teardownSockets();
+		this.ensureDownlinks();
+		const deadline = Date.now() + this.staleGenerationRetryMs;
+		while (!this.disposed && this.eventClientId === previousClientId && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 25));
+		return this.eventClientId !== previousClientId && this.eventClientId !== null;
+	}
+	/**
+	* Resync: replace the ring buffer with the ledger's tail page (BC-4).
+	* Returns the fresh entries so callers can hand them to the store.
+	*/
+	async resyncFromLedger(sessionId) {
+		const events = ((await this.history(sessionId)).events ?? []).map((h) => h.event);
+		const buf = this.bufferFor(sessionId);
+		buf.entries = [...events].slice(-ringCapacity());
+		buf.lastSeq = events.length > 0 ? events[events.length - 1].seq : -1;
+		buf.coverageFloor = buf.entries[0]?.seq ?? buf.lastSeq;
+		return buf.entries;
+	}
+	async rpc(method, payload, signal) {
+		const body = JSON.stringify({
+			type: "client-request",
+			rpcId: this.rpcIdFactory(),
+			method,
+			payload: { args: payload }
+		});
+		const attempt = async () => {
+			const cookie = await this.auth.ensureCookie();
+			return this.fetchFn(rpcUrl(this.baseUrl, method), {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+					...cookie === null ? {} : { cookie }
+				},
+				body,
+				...signal !== void 0 ? { signal } : {}
+			});
+		};
+		let response = await attempt();
+		if (response.status === 401) {
+			this.auth.invalidate();
+			const { authToken } = readDshAuthConfig();
+			response = await attempt();
+		}
+		if (!response.ok) throw new Error(`dsh-connection: transport failure for ${method}: HTTP ${response.status}`);
+		const rpcId = JSON.parse(body).rpcId;
+		return parseResponse(await response.text(), rpcId);
+	}
+	dispose() {
+		this.disposed = true;
+		clearTimeout(this.answerReapTimer);
+		this.teardownSockets();
+		this.pendingAnswers.clear();
+		this.settledAnswers.clear();
+		this.buffers.clear();
+		this.liveTails.clear();
+		this.running.clear();
+	}
+};
+/** The follow-<sessionId>-<streamSeq> logical stream id (one per generation). */
+function followStreamId(sessionId, streamSeq) {
+	return `follow-${sessionId}-${String(streamSeq)}`;
+}
+/**
+* Expand ONE follow/page event payload into its ring-buffer form
+* (single-element list — ledger v2 serves every record as a plain event).
+*/
+function expandEntry(e) {
+	return [{
+		type: e.type,
+		seq: typeof e.seq === "number" ? e.seq : -1,
+		time: typeof e.time === "number" ? e.time : 0,
+		data: e.data
+	}];
+}
+/** Expand one page/snapshot record ({type:'event', event}) into its member
+*  events; a record without an event payload contributes nothing. */
+function expandRecord(record) {
+	if (record === void 0 || record.event === void 0) return [];
+	return expandEntry(record.event);
+}
+/** Expand a records array into a flat event list. */
+function expandRecords(records) {
+	return records.flatMap((record) => expandRecord(record));
+}
+/** The last member time of one compact stream record, or undefined when
+*  the record carries no readable time (malformed members stay silent —
+*  the baseline is presentation seed data, never re-validated truth). */
+function compactRecordTailTime(record) {
+	if (record.type === "chunk") return typeof record.time === "number" ? record.time : void 0;
+	if (record.type === "text-chunks" || record.type === "reasoning-chunks" || record.type === "tool-call-chunks") {
+		const time0 = typeof record.time0 === "number" ? record.time0 : void 0;
+		const dt = Array.isArray(record.dt) ? record.dt : [];
+		if (time0 === void 0 || dt.some((g) => typeof g !== "number")) return void 0;
+		return dt.reduce((t, g) => t + g, time0);
+	}
+}
+function normalizeModelSelection(v) {
+	if (v === null || typeof v !== "object") return null;
+	const sel = v;
+	if (typeof sel.provider !== "string" || typeof sel.model !== "string") return null;
+	return {
+		provider: sel.provider,
+		model: sel.model,
+		...typeof sel.reasoningEffort === "string" ? { reasoningEffort: sel.reasoningEffort } : {}
+	};
+}
+/**
+* Conservative normalize of a SessionModels value: structural reads only,
+* never throws, never invents data (task 3.2-T: a garbage catalog → empty
+* groups + empty failures, honest `routable`/`current` — the selector can
+* still show the current selection and say nothing is listed). Reasoning
+* efforts are flattened to opaque ids (the adapter owns their meaning).
+*/
+function normalizeModelDirectory(raw) {
+	const empty = {
+		current: null,
+		routable: false,
+		groups: [],
+		failures: []
+	};
+	if (raw === null || typeof raw !== "object") return empty;
+	const dir = raw;
+	const groups = Array.isArray(dir.groups) ? modelGroupsOf(dir.groups) : [];
+	const failures = Array.isArray(dir.failures) ? modelFailuresOf(dir.failures) : [];
+	if (dir.current === void 0 && dir.default !== void 0) return {
+		current: normalizeModelSelection(dir.default),
+		routable: Array.isArray(dir.routableProviders) ? dir.routableProviders.length > 0 || groups.length > 0 : true,
+		groups,
+		failures
+	};
+	return {
+		current: normalizeModelSelection(dir.current),
+		routable: dir.routable === true,
+		groups,
+		failures
+	};
+}
+/** ModelCatalog provider groups → DsiModelGroup rows (conservative). */
+function modelGroupsOf(groups) {
+	return groups.flatMap((g) => {
+		if (g === null || typeof g !== "object") return [];
+		const grp = g;
+		if (typeof grp.id !== "string" || grp.id.length === 0) return [];
+		const models = Array.isArray(grp.models) ? grp.models.flatMap((m) => {
+			if (m === null || typeof m !== "object") return [];
+			const mod = m;
+			if (typeof mod.id !== "string" || mod.id.length === 0) return [];
+			return [{
+				id: mod.id,
+				name: typeof mod.name === "string" ? mod.name : null,
+				...Array.isArray(mod.reasoning?.efforts) ? { reasoningEfforts: mod.reasoning.efforts.flatMap((e) => typeof e?.id === "string" ? [e.id] : []) } : {}
+			}];
+		}) : [];
+		return [{
+			id: grp.id,
+			name: typeof grp.name === "string" ? grp.name : null,
+			models
+		}];
+	});
+}
+/** ModelCatalog provider failures → diagnostic rows (conservative). */
+function modelFailuresOf(failures) {
+	return failures.flatMap((f) => {
+		if (f === null || typeof f !== "object") return [];
+		const fail = f;
+		if (typeof fail.id !== "string" || fail.id.length === 0) return [];
+		return [{
+			id: fail.id,
+			name: typeof fail.name === "string" ? fail.name : null,
+			message: typeof fail.message === "string" ? fail.message : null
+		}];
+	});
+}
+function normalizeSessionRow(row) {
+	return {
+		sessionId: row.sessionId,
+		title: row.origin === "subagent" ? readSubagentLabel(row) ?? readTitle(row) : readTitle(row),
+		agentPreset: readAgentPreset(row) ?? row.agentPreset ?? null,
+		running: Boolean(row.running),
+		blank: Boolean(row.blank),
+		updatedAt: row.updatedAt ?? 0,
+		workspace: typeof row.cwd === "string" && row.cwd.length > 0 ? row.cwd : null,
+		turns: readTurns(row),
+		parentSessionId: row.parentSessionId ?? null,
+		origin: row.origin ?? null
+	};
+}
+function readTitle(row) {
+	const title = row.projections?.values?.["title"];
+	return typeof title === "string" && title.length > 0 ? title : null;
+}
+/** projections.values.subagent.label (the child descriptor's creation label;
+*  one-shot children may omit it — structural read, null when unreadable). */
+function readSubagentLabel(row) {
+	const identity = row.projections?.values?.["subagent"];
+	const label = identity !== null && typeof identity === "object" ? identity.label : void 0;
+	return typeof label === "string" && label.length > 0 ? label : null;
+}
+/** projections.values.agentPreset (0.1.2 home of the preset id on list rows). */
+function readAgentPreset(row) {
+	const preset = row.projections?.values?.["agentPreset"];
+	return typeof preset === "string" && preset.length > 0 ? preset : null;
+}
+/** `sessionStats.turns` (0.1.2: projections.values.sessionStats) — integer-strict, null on absent/junk. */
+function readTurns(row) {
+	const stats = row.projections?.values?.["sessionStats"];
+	const turns = stats !== null && typeof stats === "object" ? stats.turns : row.sessionStats?.turns;
+	if (typeof turns !== "number" || !Number.isInteger(turns) || turns < 0) return null;
+	return turns;
+}
+/**
+* English display copy for the host's SHIPPED presets, keyed by the stable
+* preset id. The wire's `name`/`description` are the UNLOCALIZED metadata a
+* preset publishes (DSH `PresetDisplaySource`), and the four built-ins ship
+* Simplified Chinese there — DSH localizes them only inside its own web UI
+* (`packages/preset/agent-presets/src/display.ts` folds trust:'system' + id →
+* locale dictionary keys). This app has no host locale seat, so the overlay
+* mirrors that fold in English: trust:'system' + a known id → the English
+* copy; every other row (user presets, unknown future ids) keeps the host's
+* name verbatim — user metadata is never translated, and an unknown id falls
+* back honestly. Operator-tunable off via ~/.dsi/settings.yaml
+* `dsh.presetEnglish: false` (readDshPresetEnglishConfig — no cache, so the
+* next listPresets fetch picks an edit up). Keep the strings in step with DSH
+* `packages/client/ui-agent-preset/src/client/locales.ts` (the `en` bundle).
+*/
+var SHIPPED_PRESET_ENGLISH = {
+	standard: {
+		name: "Standard mode",
+		description: "Full coding agent with file editing, shell, file and web search, skills, planning, goals, subagents, and workflows."
+	},
+	ptc: {
+		name: "PTC mode",
+		description: "Full coding agent without the workflow tool; other tools are exposed through the PTC mode SDK so the model can combine multi-step operations in one TypeScript program."
+	},
+	minimal: {
+		name: "Minimal mode",
+		description: "Two-tool coding agent with persistent bash and str_replace_editor."
+	},
+	cordis: {
+		name: "Creator mode",
+		description: "Built for creating custom agent presets, with all Standard mode capabilities plus runtime inspection, plugin experiments, and preset-authoring guidance."
+	}
+};
+/**
+* Conservative normalize: unknown shapes keep their id but never invent data.
+* The one English overlay seat (SHIPPED_PRESET_ENGLISH) applies before the
+* host fallbacks — a shipped preset's label is locale-resolved here, never
+* the wire's unlocalized text. Operator-tunable via
+* ~/.dsi/settings.yaml `dsh.presetEnglish` (read live per listPresets
+* call, passed through here): false hands the wire name through untouched.
+*/
+function normalizePreset(row, overlayEnglish = true) {
+	const id = typeof row.id === "string" ? row.id : String(row.id ?? "");
+	const shipped = overlayEnglish && row.trust === "system" ? SHIPPED_PRESET_ENGLISH[id] : void 0;
+	return {
+		id,
+		name: shipped?.name ?? (typeof row.name === "string" ? row.name : null),
+		description: shipped?.description ?? (typeof row.description === "string" ? row.description : null),
+		isDefault: row.isDefault === true
+	};
+}
+
+export { DshRpcError as D, isPromptImageMediaType as a, buildPromptContent as b, getDshConnection as g, isSubagentRejection as i, mapRpcFailure as m, statusFor as s };
+//# sourceMappingURL=dsh-connection.js-DwihVtk_.js.map