@achasoft/dsh-advanced-sidebar 0.1.0 → 0.3.0

package/lib/host.js

@@ -1,22 +1,100 @@
+import { a as contentTypeOf, c as fileUrl, f as proxyUrlFor, h as resolveWorkspace, i as classifyFile, l as injectBase, m as resolveInside, n as PROXY_ROUTE, o as decodeText, p as validateProxyTarget, r as SCRATCHPAD_ROUTE, s as encodeQuery, t as FILE_ROUTE, u as isTextual } from "./preview-content-BVUQ5oOR.js";
 import z from "@deepseek-ai/schemastery";
-import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
 import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
-import { rm } from "node:fs/promises";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { connect } from "node:net";
+import { request } from "node:http";
+import { request as request$1 } from "node:https";
 import { JobId } from "@deepseek-ai/dsh-jobs";
 
+//#region tsbuild/host/settings-section.js
+/**
+* Attaching this plugin's settings section to the harness settings provider.
+*
+* Harness 0.1.1-rc.2 and earlier exported two free helpers from `@deepseek-ai/dsh-settings` for
+* this, `installSettingsSection` and `settingsNamespace`. Current harnesses removed both: the same
+* wiring is the provider's own `settings.installSection(owner, ns, schema, entry, hooks)`, reached
+* through `ctx.inject(['settings'], …)`. Importing the old helpers by name fails to link on a
+* current install, so the plugin carries these two small equivalents instead of depending on a
+* compatibility shim that only exists on a development machine.
+*
+* Injecting `settings` rather than requiring it keeps the plugin loadable in a deployment that
+* mounts no settings provider: the section simply never attaches, and the composition entry the
+* plugin was configured with stays the source.
+* @module @achasoft/dsh-advanced-sidebar/host/settings-section
+*/
+/** The provider's namespace grammar: a lowercase, hyphenated identifier. */
+const NAMESPACE_PATTERN = /^[a-z][a-z0-9-]*$/u;
+/**
+* Check a settings namespace against the provider's grammar, failing at load rather than at attach.
+* @param value - the namespace.
+* @returns the same namespace.
+* @throws TypeError when it is not a lowercase hyphenated identifier.
+*/
+function settingsNamespace(value) {
+	if (!NAMESPACE_PATTERN.test(value)) throw new TypeError(`settings namespace "${value}" must match ${String(NAMESPACE_PATTERN)}`);
+	return value;
+}
+/**
+* Attach one settings section whenever a settings provider is present.
+* @param ctx - the owning plugin context; its unload detaches the section.
+* @param ns - the plugin's settings namespace.
+* @param schema - schema resolving the section.
+* @param entry - the composition entry, used as the base layer and as the fallback without a provider.
+* @param hooks - source sink, change notification, and optional validation.
+*/
+function installSettingsSection(ctx, ns, schema, entry, hooks) {
+	ctx.inject(["settings"], (settingsCtx) => {
+		settingsCtx.settings.installSection(ctx, ns, schema, entry, hooks);
+	});
+}
+
+//#endregion
 //#region tsbuild/host/deletion.js
 /**
+* Session deletion.
+*
+* No harness capability deletes a session. Delete is therefore the one thing that does exist — the
+* workspace registry's ARCHIVE, which hides a session while keeping its log and its accounting slot —
+* and it is honest that this is all it did.
+*
+* `deleteMode: 'purge'` asked for more: the backend's own per-session artifact removed as well. On
+* the harness this release targets (`0.1.5-rc.2`) that cannot be done correctly, and so it is not
+* attempted:
+*
+* - The published `SessionPersistence` contract is `create`, `open`, `flush`, `stat` and `list`. It
+*   has no removal verb and no way to ask where a session's bytes live; the `supportsRawArtifacts`
+*   flag and `locate()` this module used to read were never part of it, so purging was silently
+*   impossible while the settings still offered it.
+* - The JSONL backend keeps a session as a DIRECTORY — one immutable file per format generation plus
+*   a `session.lock` write lease — behind an in-process cold-log memo, and the workspace registry and
+*   the session projection cache index its header. Unlinking files underneath all of that bypasses the
+*   lease another process may hold, leaves stale caches answering for a log that is gone, and is the
+*   same class of out-of-band edit that produces "torn record" corruption reports.
+*
+* So the capability is reported as unavailable with that reason, the settings card shows the reason
+* and refuses to select `purge`, and a composition that still configures it gets an archive whose
+* result says, every time, why nothing was removed. When the harness grows a supported removal verb,
+* this is the one module to change.
+* @module @achasoft/dsh-advanced-sidebar/host/deletion
+*/
+/**
+* Why `purge` is unavailable, in the words the settings card and the Delete result show.
+*
+* One sentence for both, so the reason a person reads before choosing a mode is the reason they read
+* after pressing Delete.
+*/
+const PURGE_UNAVAILABLE_REASON = "this harness's session persistence has no supported way to remove a session log, so Delete archives the session and keeps its log";
+/**
 * Commits Delete for the sidebar menu. Stateless apart from the context and settings it reads.
 */
 var SessionDeleter = class {
 	ctx;
 	source;
 	/**
-	* @param ctx - Host context carrying the workspace registry and session persistence.
+	* @param ctx - Host context carrying the workspace registry.
 	* @param source - reads the current settings section; called per request.
 	*/
 	constructor(ctx, source) {
@@ -25,27 +103,20 @@ var SessionDeleter = class {
 	}
 	/**
 	* Report whether the durable log can be removed at all.
-	* @returns the capability, with a reason when purging is impossible.
+	* @returns the capability, with the reason purging is impossible.
 	*/
 	describe() {
-		const persistence = this.ctx.get("sessionPersistence");
-		if (persistence === void 0) return {
-			canPurge: false,
-			reason: "no session-persistence backend is mounted; nothing is written to remove"
-		};
-		if (!persistence.supportsRawArtifacts) return {
+		return {
 			canPurge: false,
-			reason: "this session-persistence backend keeps no per-session artifact, so Delete can only archive"
+			reason: PURGE_UNAVAILABLE_REASON
 		};
-		return { canPurge: true };
 	}
 	/**
-	* Hide one session, and remove its durable artifact when the mode and the Host allow it.
+	* Hide one session, and say plainly when a requested purge did not happen.
 	* @param request - the session to delete.
-	* @param signal - cancellation for the persistence listing.
 	* @returns what was actually done, or a classified failure.
 	*/
-	async delete(request, signal) {
+	async delete(request$2) {
 		const settings = this.source();
 		if (!settings.showDelete) return {
 			ok: false,
@@ -58,10 +129,8 @@ var SessionDeleter = class {
 			code: "no-registry",
 			message: "no workspace registry is mounted"
 		};
-		const sessionId = request.sessionId;
-		const artifact = settings.deleteMode === "purge" ? await this.locateArtifact(sessionId, signal) : void 0;
 		try {
-			await registry.archiveSession(sessionId);
+			await registry.archiveSession(request$2.sessionId);
 		} catch (error) {
 			return {
 				ok: false,
@@ -69,168 +138,23 @@ var SessionDeleter = class {
 				message: error instanceof Error ? error.message : String(error)
 			};
 		}
-		if (settings.deleteMode === "archive") return {
-			ok: true,
-			archived: true,
-			purged: false
-		};
-		if (artifact === void 0 || "reason" in artifact) return {
-			ok: true,
-			archived: true,
-			purged: false,
-			purgeSkippedReason: artifact?.reason ?? this.describe().reason ?? "the session has no materialized artifact to remove"
-		};
-		try {
-			await rm(artifact.path, { force: true });
-		} catch (error) {
-			return {
-				ok: false,
-				code: "remove-failed",
-				message: `archived, but ${artifact.path} could not be removed: ${error instanceof Error ? error.message : String(error)}`
+		switch (settings.deleteMode) {
+			case "archive": return {
+				ok: true,
+				archived: true,
+				purged: false
 			};
+			case "purge": return {
+				ok: true,
+				archived: true,
+				purged: false,
+				purgeSkippedReason: PURGE_UNAVAILABLE_REASON
+			};
+			default: throw new TypeError(`advanced-sidebar: unexpected deleteMode ${JSON.stringify(settings.deleteMode)}`);
 		}
-		return {
-			ok: true,
-			archived: true,
-			purged: true,
-			artifactPath: artifact.path
-		};
-	}
-	/**
-	* Find the backend artifact for one session, or say why it will not be removed.
-	* @param sessionId - the session to look up.
-	* @param signal - cancellation for the persistence listing.
-	* @returns the artifact path, or the reason purging is skipped.
-	*/
-	async locateArtifact(sessionId, signal) {
-		const capability = this.describe();
-		if (!capability.canPurge) return { reason: capability.reason ?? "purging is unavailable on this Host" };
-		if (this.ctx.agents.get(sessionId) !== void 0) return { reason: "the session is live, so its log was kept; delete it again after it stops" };
-		const persistence = this.ctx.sessionPersistence;
-		let headers;
-		try {
-			headers = await persistence.list(signal);
-		} catch (error) {
-			return { reason: `the durable session list could not be read: ${error instanceof Error ? error.message : String(error)}` };
-		}
-		const header = headers.find((entry) => entry.id === sessionId);
-		if (header === void 0) return { reason: "the session has no durable log on this Host" };
-		const location = persistence.locate(header);
-		if (location === void 0) return { reason: "this backend keeps no per-session artifact for that session" };
-		return { path: location.path };
 	}
 };
 
-//#endregion
-//#region tsbuild/host/paths.js
-/**
-* Path resolution and containment for every endpoint that takes a path from the browser.
-*
-* A browser-supplied path is untrusted input at a process boundary, so each one is resolved through
-* `ctx.fs` and proved to sit inside the workspace it claims to belong to before any command, read,
-* or launch sees it. `..` and symlinks are handled by the filesystem's own canonicalization rather
-* than by string arithmetic here.
-* @module @achasoft/dsh-advanced-sidebar/host/paths
-*/
-/**
-* Resolve one absolute directory as a workspace root.
-* @param ctx - Host context carrying the optional filesystem capability.
-* @param path - absolute directory path supplied by the browser.
-* @param signal - cancellation for the backend round-trip.
-* @returns the canonical directory, or the reason it was refused.
-*/
-async function resolveWorkspace(ctx, path, signal) {
-	const fs = ctx.get("fs");
-	if (fs === void 0) return {
-		ok: false,
-		rejection: {
-			code: "no-filesystem",
-			message: "no filesystem capability is mounted: this deployment composes no @deepseek-ai/dsh-fs provider"
-		}
-	};
-	let target;
-	try {
-		target = await fs.resolve(path, signal === void 0 ? {} : { signal });
-	} catch (error) {
-		return {
-			ok: false,
-			rejection: {
-				code: "path-denied",
-				message: describe(error, path)
-			}
-		};
-	}
-	const info = await fs.stat(target, signal);
-	if (info === void 0 || info.type !== "directory") return {
-		ok: false,
-		rejection: {
-			code: "path-denied",
-			message: `${path} is not a directory`
-		}
-	};
-	return {
-		ok: true,
-		value: {
-			target,
-			processPath: fs.processPath(target)
-		}
-	};
-}
-/**
-* Resolve one path and prove it sits inside an already-resolved workspace.
-* @param ctx - Host context carrying the optional filesystem capability.
-* @param workspace - the canonical workspace directory the path must stay within.
-* @param path - absolute path supplied by the browser.
-* @param signal - cancellation for the backend round-trip.
-* @returns the canonical path, or the reason it was refused.
-*/
-async function resolveInside(ctx, workspace, path, signal) {
-	const fs = ctx.get("fs");
-	/* v8 ignore next 4 -- the caller resolved `workspace` through the same service moments earlier. */
-	if (fs === void 0) return {
-		ok: false,
-		rejection: {
-			code: "no-filesystem",
-			message: "filesystem capability withdrawn mid-request"
-		}
-	};
-	let target;
-	try {
-		target = await fs.resolve(path, signal === void 0 ? {} : { signal });
-	} catch (error) {
-		return {
-			ok: false,
-			rejection: {
-				code: "path-denied",
-				message: describe(error, path)
-			}
-		};
-	}
-	if (!fs.contains(workspace.target, target)) return {
-		ok: false,
-		rejection: {
-			code: "path-denied",
-			message: `${path} is outside ${workspace.target.displayPath}`
-		}
-	};
-	return {
-		ok: true,
-		value: {
-			target,
-			processPath: fs.processPath(target)
-		}
-	};
-}
-/**
-* Phrase one resolution failure without leaking a stack.
-* @param error - whatever the backend threw.
-* @param path - the path that was being resolved.
-* @returns a single-line operator diagnostic.
-*/
-function describe(error, path) {
-	return `cannot resolve ${path}: ${error instanceof Error ? error.message : String(error)}`;
-}
-
 //#endregion
 //#region tsbuild/host/files.js
 /**
@@ -271,20 +195,20 @@ var FileReader = class {
 	* @param signal - cancellation for the listing.
 	* @returns the level, or a classified failure.
 	*/
-	async list(request, signal) {
+	async list(request$2, signal) {
 		const fs = this.ctx.get("fs");
 		if (fs === void 0) return {
 			ok: false,
 			code: "no-filesystem",
 			message: "no filesystem capability is mounted"
 		};
-		const workspace = await resolveWorkspace(this.ctx, request.workspacePath, signal);
+		const workspace = await resolveWorkspace(this.ctx, request$2.workspacePath, signal);
 		if (!workspace.ok) return {
 			ok: false,
 			code: workspace.rejection.code === "no-filesystem" ? "no-filesystem" : "path-denied",
 			message: workspace.rejection.message
 		};
-		const directory = await resolveInside(this.ctx, workspace.value, request.path, signal);
+		const directory = await resolveInside(this.ctx, workspace.value, request$2.path, signal);
 		if (!directory.ok) return {
 			ok: false,
 			code: directory.rejection.code === "no-filesystem" ? "no-filesystem" : "path-denied",
@@ -294,7 +218,7 @@ var FileReader = class {
 		if (info === void 0 || info.type !== "directory") return {
 			ok: false,
 			code: "not-a-file",
-			message: `${request.path} is not a directory`
+			message: `${request$2.path} is not a directory`
 		};
 		let children;
 		try {
@@ -333,20 +257,20 @@ var FileReader = class {
 	* @param signal - cancellation for the read.
 	* @returns the preview, or a classified failure.
 	*/
-	async read(request, signal) {
+	async read(request$2, signal) {
 		const fs = this.ctx.get("fs");
 		if (fs === void 0) return {
 			ok: false,
 			code: "no-filesystem",
 			message: "no filesystem capability is mounted"
 		};
-		const workspace = await resolveWorkspace(this.ctx, request.workspacePath, signal);
+		const workspace = await resolveWorkspace(this.ctx, request$2.workspacePath, signal);
 		if (!workspace.ok) return {
 			ok: false,
 			code: workspace.rejection.code === "no-filesystem" ? "no-filesystem" : "path-denied",
 			message: workspace.rejection.message
 		};
-		const file = await resolveInside(this.ctx, workspace.value, request.path, signal);
+		const file = await resolveInside(this.ctx, workspace.value, request$2.path, signal);
 		if (!file.ok) return {
 			ok: false,
 			code: file.rejection.code === "no-filesystem" ? "no-filesystem" : "path-denied",
@@ -356,7 +280,7 @@ var FileReader = class {
 		if (info === void 0 || info.type !== "file") return {
 			ok: false,
 			code: "not-a-file",
-			message: `${request.path} is not a regular file`
+			message: `${request$2.path} is not a regular file`
 		};
 		const max = this.source().filesMaxPreviewBytes;
 		let bytes;
@@ -372,7 +296,7 @@ var FileReader = class {
 		const size = info.size ?? bytes.byteLength;
 		if (isBinary(bytes)) return {
 			ok: true,
-			path: request.path,
+			path: request$2.path,
 			text: "",
 			binary: true,
 			truncated: false,
@@ -380,7 +304,7 @@ var FileReader = class {
 		};
 		return {
 			ok: true,
-			path: request.path,
+			path: request$2.path,
 			text: new TextDecoder("utf-8", { fatal: false }).decode(bytes),
 			binary: false,
 			truncated: size > bytes.byteLength,
@@ -688,6 +612,47 @@ const MISSING_BINARY_EXIT = 127;
 /** The remote a branch with no upstream is published to when nothing else names one. */
 const DEFAULT_REMOTE = "origin";
 /**
+* Configuration every invocation carries, ahead of the subcommand.
+*
+* `core.fsmonitor` names an executable git runs whenever it refreshes the index — which `status`,
+* `diff`, `add` and `commit` all do — and it is read from the repository's own `.git/config`. A
+* workspace whose config was written by someone else (an unpacked archive, a shared directory) would
+* otherwise run their program the moment the Changes panel opened. The monitor is only a speed-up, so
+* turning it off costs a slower status on a very large repository and nothing else. `-c` on the command
+* line outranks every config file, and git passes it on to the child gits it starts (submodules).
+*/
+const INVOCATION_CONFIG = ["-c", "core.fsmonitor=false"];
+/**
+* Flags every `git diff` carries, so a patch is git's own rendering and never a configured program's.
+*
+* `--no-ext-diff` refuses `diff.external` and per-attribute `diff.<driver>.command`; `--no-textconv`
+* refuses `diff.<driver>.textconv`. Both name executables from repository config and attributes, and
+* both would otherwise run on a reading nobody asked to be a command.
+*/
+const DIFF_SAFETY_ARGS = ["--no-ext-diff", "--no-textconv"];
+/**
+* Config keys that name a content filter's executable.
+*
+* `filter.<driver>.clean` (and the long-running `process` protocol) run when git hashes a working-tree
+* file — which `git status` does for every file whose stat data changed. A driver is attached by
+* `.gitattributes`, which a repository ships, and defined in config, which is where the executable
+* comes from; `smudge` runs only on checkout, which no reading here performs.
+*/
+const FILTER_EXECUTABLE_KEYS = String.raw`^filter\..*\.(clean|process)$`;
+/** The key shape one filter listing line carries, split into its driver name and its variable. */
+const FILTER_KEY = /^filter\.(.+)\.(clean|process)$/u;
+/**
+* Config scopes whose filter programs a reading may run.
+*
+* `system` and `global` are files the operator (or their administrator) wrote, and they are where
+* `git lfs install` puts its filter, so neutralizing them would turn every LFS file into a phantom
+* change. `local` and `worktree` live inside the repository's own `.git`, which is exactly the
+* config a workspace can arrive with.
+*/
+const TRUSTED_CONFIG_SCOPES = new Set(["system", "global"]);
+/** `git config --get-regexp` exits 1 to mean "no key matched", which is an ordinary answer. */
+const CONFIG_NO_MATCH_EXIT = 1;
+/**
 * What the model is told a commit message is, when the settings section supplies no prompt of its
 * own.
 *
@@ -740,6 +705,36 @@ function stripFence(text) {
 	return (/^```[^\n]*\n([\s\S]*)\n```$/u.exec(trimmed)?.[1] ?? trimmed).trim();
 }
 /**
+* The `-c` overrides that disarm the untrusted filter programs one config listing names.
+*
+* An empty value is git's own "no command" for a filter (`convert.c` runs a driver only when its
+* command is non-empty), so the file is then hashed as its bytes, exactly as with no driver at all.
+* @param listing - `git config --show-scope --name-only --get-regexp` output, one `scope<TAB>key` per
+* line; a line with no scope (an older git) is treated as untrusted.
+* @returns the overrides, or the key git could not be told about safely.
+*/
+function filterOverrides(listing) {
+	const config = [];
+	for (const line of listing.split("\n")) {
+		if (line.trim() === "") continue;
+		const tab = line.indexOf("	");
+		const scope = tab < 0 ? void 0 : line.slice(0, tab);
+		const key = tab < 0 ? line : line.slice(tab + 1);
+		if (scope !== void 0 && TRUSTED_CONFIG_SCOPES.has(scope)) continue;
+		if (key.includes("=") || FILTER_KEY.exec(key) === null) return { unsafeKey: key };
+		config.push("-c", `${key}=`);
+	}
+	return { config };
+}
+/**
+* Whether a name could be read as an option by a git command it is passed to.
+* @param name - a branch or remote name taken from repository state.
+* @returns true when it begins with `-`.
+*/
+function isOptionShaped(name) {
+	return name.startsWith("-");
+}
+/**
 * Reads one workspace's git state. One instance serves every request; the resolved `git` path is
 * cached across calls and dropped whenever a lookup fails, so installing git later needs no restart.
 */
@@ -788,17 +783,17 @@ var GitReader = class {
 	* @param signal - cancellation for the reading.
 	* @returns the reading, or a classified failure.
 	*/
-	async status(request, signal) {
-		const prepared = await this.prepare(request.workspacePath, signal);
+	async status(request$2, signal) {
+		const prepared = await this.prepare(request$2.workspacePath, signal);
 		if ("failure" in prepared) return prepared.failure;
 		const { repository, workspace } = prepared;
-		const outcome = await this.git(workspace.value.processPath, [
+		const outcome = await this.read(repository, [
 			"status",
 			"--porcelain=v2",
 			"--branch",
 			"--untracked-files=all",
 			...NUL_ARGS
-		], signal);
+		], signal, void 0, workspace.value.processPath);
 		if (outcome.exitCode !== 0) return classify(outcome);
 		const parsed = parsePorcelainV2(outcome.stdout);
 		const limit = this.source().gitMaxFiles;
@@ -807,7 +802,7 @@ var GitReader = class {
 		const conflicted = changes.filter((change) => change.conflicted);
 		return {
 			ok: true,
-			write: await this.writeCapability(repository.root, signal),
+			write: await this.writeCapability(repository, signal),
 			repositoryRoot: repository.root,
 			prefix: repository.prefix,
 			...parsed.branch.branch === void 0 ? {} : { branch: parsed.branch.branch },
@@ -829,39 +824,39 @@ var GitReader = class {
 	* @param signal - cancellation for the reading.
 	* @returns the patch, or a classified failure.
 	*/
-	async diff(request, signal) {
-		const prepared = await this.prepare(request.workspacePath, signal);
+	async diff(request$2, signal) {
+		const prepared = await this.prepare(request$2.workspacePath, signal);
 		if ("failure" in prepared) return prepared.failure;
 		const { repository } = prepared;
-		const contained = await this.contain(repository.root, [request.path], signal);
+		const contained = await this.contain(repository.root, [request$2.path], signal);
 		if (contained !== void 0) return contained;
 		const common = [
 			"--no-pager",
 			"diff",
 			"--no-color",
-			"--no-ext-diff"
+			...DIFF_SAFETY_ARGS
 		];
-		const argv = request.untracked ? [
+		const argv = request$2.untracked ? [
 			...common,
 			"--no-index",
 			"--",
 			devNull(),
-			request.path
+			request$2.path
 		] : [
 			...common,
-			...request.staged ? ["--cached"] : [],
+			...request$2.staged ? ["--cached"] : [],
 			"--",
-			request.path
+			request$2.path
 		];
 		const max = this.source().gitDiffMaxBytes;
-		const outcome = await this.git(repository.root, argv, signal, max);
-		const differed = request.untracked && outcome.exitCode === 1 && outcome.stderr.trim() === "";
+		const outcome = await this.read(repository, argv, signal, max);
+		const differed = request$2.untracked && outcome.exitCode === 1 && outcome.stderr.trim() === "";
 		if (outcome.exitCode !== 0 && !differed) return classify(outcome);
 		const patch = outcome.stdout;
 		const truncated = outcome.stdoutLossy || patch.length > max;
 		return {
 			ok: true,
-			path: request.path,
+			path: request$2.path,
 			patch: patch.length > max ? patch.slice(0, max) : patch,
 			binary: /^Binary files .* differ$/mu.test(patch),
 			truncated
@@ -873,9 +868,9 @@ var GitReader = class {
 	* @param signal - cancellation for the write and the reading that follows it.
 	* @returns the reading after the write, or a classified failure.
 	*/
-	stage(request, signal) {
+	stage(request$2, signal) {
 		if (!this.source().allowGitStaging) return Promise.resolve(fail$4("disabled", "staging is switched off in the advanced-sidebar settings"));
-		return this.write(request, signal, (paths) => [
+		return this.write(request$2, signal, (paths) => [
 			"add",
 			"--",
 			...paths
@@ -887,9 +882,9 @@ var GitReader = class {
 	* @param signal - cancellation for the write and the reading that follows it.
 	* @returns the reading after the write, or a classified failure.
 	*/
-	unstage(request, signal) {
+	unstage(request$2, signal) {
 		if (!this.source().allowGitStaging) return Promise.resolve(fail$4("disabled", "staging is switched off in the advanced-sidebar settings"));
-		return this.write(request, signal, (paths) => [
+		return this.write(request$2, signal, (paths) => [
 			"restore",
 			"--staged",
 			"--",
@@ -906,29 +901,29 @@ var GitReader = class {
 	* @param signal - cancellation for the commit and the reading that follows it.
 	* @returns the new commit and the reading after it, or a classified failure.
 	*/
-	async commit(request, signal) {
+	async commit(request$2, signal) {
 		const settings = this.source();
 		if (!settings.allowGitCommit) return fail$4("disabled", "committing is switched off in the advanced-sidebar settings");
-		const message = request.message.trim();
+		const message = request$2.message.trim();
 		if (message === "") return fail$4("empty-message", "a commit needs a message");
-		const prepared = await this.prepare(request.workspacePath, signal);
+		const prepared = await this.prepare(request$2.workspacePath, signal);
 		if ("failure" in prepared) return prepared.failure;
 		const { repository } = prepared;
-		if (await this.author(repository.root, signal) === void 0) return fail$4("no-identity", "git has no user.name and user.email, so it has no author to record; set them with `git config --global user.name` and `git config --global user.email`");
-		if (!request.amend && !await this.hasStaged(repository.root, signal)) return fail$4("nothing-staged", "nothing is staged, so there is nothing to commit");
+		if (await this.author(repository, signal) === void 0) return fail$4("no-identity", "git has no user.name and user.email, so it has no author to record; set them with `git config --global user.name` and `git config --global user.email`");
+		if (!request$2.amend && !await this.hasStaged(repository, signal)) return fail$4("nothing-staged", "nothing is staged, so there is nothing to commit");
 		const outcome = await this.git(repository.root, [
 			"commit",
-			...request.amend ? ["--amend"] : [],
+			...request$2.amend ? ["--amend"] : [],
 			"-m",
 			message
 		], signal, void 0, settings.gitCommitTimeoutMs);
 		if (outcome.exitCode !== 0) return classify(outcome);
-		const [commit, subject] = (await this.git(repository.root, [
+		const [commit, subject] = (await this.read(repository, [
 			"log",
 			"-1",
 			"--format=%h%n%s"
 		], signal)).stdout.split("\n");
-		const status = await this.status({ workspacePath: request.workspacePath }, signal);
+		const status = await this.status({ workspacePath: request$2.workspacePath }, signal);
 		if (!status.ok) return status;
 		return {
 			ok: true,
@@ -949,28 +944,25 @@ var GitReader = class {
 	* @param signal - cancellation; the network wait runs under `gitPushTimeoutMs`.
 	* @returns the push, the reading after it, or a classified failure.
 	*/
-	async push(request, signal) {
+	async push(request$2, signal) {
 		const settings = this.source();
 		if (!settings.allowGitPush) return fail$4("disabled", "pushing is switched off in the advanced-sidebar settings");
-		const prepared = await this.prepare(request.workspacePath, signal);
+		const prepared = await this.prepare(request$2.workspacePath, signal);
 		if ("failure" in prepared) return prepared.failure;
 		const { repository } = prepared;
-		const before = await this.status({ workspacePath: request.workspacePath }, signal);
+		const before = await this.status({ workspacePath: request$2.workspacePath }, signal);
 		if (!before.ok) return before;
 		if (before.detached || before.branch === void 0) return fail$4("detached-head", "HEAD names a commit rather than a branch, so there is nothing to push");
 		const branch = before.branch;
 		const upstream = before.upstream;
-		if (upstream === void 0 && !request.setUpstream) return fail$4("no-upstream", `${branch} has no upstream; publish it to a remote first, or use Publish to record one`);
-		const remote = upstream === void 0 ? await this.defaultRemote(repository.root, signal) : upstream.split("/")[0] ?? DEFAULT_REMOTE;
+		if (upstream === void 0 && !request$2.setUpstream) return fail$4("no-upstream", `${branch} has no upstream; publish it to a remote first, or use Publish to record one`);
+		const remote = upstream === void 0 ? await this.defaultRemote(repository, signal) : upstream.split("/")[0] ?? DEFAULT_REMOTE;
 		if (remote === void 0) return fail$4("no-upstream", "this repository has no remote to push to");
-		const outcome = await this.git(repository.root, upstream === void 0 ? [
-			"push",
-			"--set-upstream",
-			remote,
-			branch
-		] : ["push"], signal, void 0, settings.gitPushTimeoutMs);
+		const argv = upstream === void 0 ? await this.publishArgv(repository, remote, branch, signal) : { argv: ["push"] };
+		if ("failure" in argv) return argv.failure;
+		const outcome = await this.git(repository.root, argv.argv, signal, void 0, settings.gitPushTimeoutMs);
 		if (outcome.exitCode !== 0) return classify(outcome);
-		const status = await this.status({ workspacePath: request.workspacePath }, signal);
+		const status = await this.status({ workspacePath: request$2.workspacePath }, signal);
 		if (!status.ok) return status;
 		return {
 			ok: true,
@@ -982,6 +974,67 @@ var GitReader = class {
 		};
 	}
 	/**
+	* The arguments that publish one branch to one remote and record it as the upstream.
+	*
+	* Both names come from repository state, not from the browser — and repository state is not
+	* trusted either. A HEAD of `refs/heads/--receive-pack=/tmp/x` is a valid ref (`check-ref-format`
+	* accepts it) that `git status` reports as the branch `--receive-pack=/tmp/x`; handed to
+	* `git push` as a bare argument, git parsed it as the option and ran `/tmp/x` as the remote's
+	* receive-pack. So three independent things stand in the way:
+	*
+	* 1. Both names are refused outright when they begin with `-`.
+	* 2. The branch must pass `git check-ref-format --branch`, which is git's own branch-name grammar
+	*    (it rejects a leading `-`, `..`, control characters, `@{`) and must echo back unchanged, so a
+	*    `@{-1}` shorthand cannot be expanded into some other branch. The remote must make a valid
+	*    remote-tracking ref, which is how git itself validates a remote name.
+	* 3. The push names the refs after `--`, where `git push` (parse-options) stops reading options,
+	*    and as a fully qualified `refs/heads/<b>:refs/heads/<b>` refspec, which also cannot be read as
+	*    a shorter ref with the same name on the remote. `--set-upstream` records the same tracking
+	*    branch it records for the short spelling.
+	* @param repository - the resolved repository.
+	* @param remote - the remote to publish to, from `git remote`.
+	* @param branch - the current branch, from `git status`.
+	* @param signal - cancellation for the validation invocations.
+	* @returns the push arguments, or the failure to return.
+	*/
+	async publishArgv(repository, remote, branch, signal) {
+		if (isOptionShaped(branch) || !await this.isValidBranchName(repository, branch, signal)) return { failure: fail$4("git-failed", `refusing to publish: ${JSON.stringify(branch)} is not a valid branch name`) };
+		if (isOptionShaped(remote) || !await this.isValidRemoteName(repository, remote, signal)) return { failure: fail$4("git-failed", `refusing to publish: ${JSON.stringify(remote)} is not a valid remote name`) };
+		const ref = `refs/heads/${branch}`;
+		return { argv: [
+			"push",
+			"--set-upstream",
+			"--",
+			remote,
+			`${ref}:${ref}`
+		] };
+	}
+	/**
+	* Whether git accepts a name as a branch name, spelled exactly as given.
+	* @param repository - the resolved repository.
+	* @param branch - the name, already known not to begin with `-`.
+	* @param signal - cancellation for the invocation.
+	* @returns true when `check-ref-format --branch` accepts it and echoes it back unchanged.
+	*/
+	async isValidBranchName(repository, branch, signal) {
+		const outcome = await this.read(repository, [
+			"check-ref-format",
+			"--branch",
+			branch
+		], signal);
+		return outcome.exitCode === 0 && outcome.stdout.replace(/\n$/u, "") === branch;
+	}
+	/**
+	* Whether git accepts a name as a remote name.
+	* @param repository - the resolved repository.
+	* @param remote - the name, already known not to begin with `-`.
+	* @param signal - cancellation for the invocation.
+	* @returns true when `refs/remotes/<remote>/HEAD` is a well-formed ref, git's own remote-name rule.
+	*/
+	async isValidRemoteName(repository, remote, signal) {
+		return (await this.read(repository, ["check-ref-format", `refs/remotes/${remote}/HEAD`], signal)).exitCode === 0;
+	}
+	/**
 	* Ask the deployment's own model to write a commit message for what is staged.
 	*
 	* The model sees the staged patch and nothing else — not the working tree, not the repository's
@@ -991,16 +1044,16 @@ var GitReader = class {
 	* @param signal - cancellation for the readings and the model call.
 	* @returns the drafted message, or a classified failure.
 	*/
-	async draftCommitMessage(request, signal) {
+	async draftCommitMessage(request$2, signal) {
 		const settings = this.source();
 		if (!settings.allowGitCommit || !settings.allowCommitMessageDraft) return fail$4("disabled", "the drafted commit message is switched off in the advanced-sidebar settings");
 		const llm = this.ctx.get("llm");
 		const models = this.ctx.get("agentDefaultModel");
 		if (llm === void 0 || models === void 0) return fail$4("no-model", "no model is configured for this deployment");
-		const prepared = await this.prepare(request.workspacePath, signal);
+		const prepared = await this.prepare(request$2.workspacePath, signal);
 		if ("failure" in prepared) return prepared.failure;
 		const { repository } = prepared;
-		const patch = await this.stagedPatch(repository.root, request.amend, signal);
+		const patch = await this.stagedPatch(repository, request$2.amend, signal);
 		if ("failure" in patch) return patch.failure;
 		if (patch.text.trim() === "") return fail$4("nothing-staged", "nothing is staged, so there is nothing to describe");
 		const selection = models.currentSelection();
@@ -1038,24 +1091,26 @@ var GitReader = class {
 	}
 	/**
 	* The patch a drafted message describes, bounded so a large change cannot become a large request.
-	* @param root - absolute repository root.
+	* @param repository - the resolved repository.
 	* @param amend - describe the previous commit's content as well as the index.
 	* @param signal - cancellation for the invocations.
 	* @returns the patch and whether it was cut, or the failure to return.
 	*/
-	async stagedPatch(root, amend, signal) {
+	async stagedPatch(repository, amend, signal) {
 		const settings = this.source();
-		const base = amend && await this.hasParent(root, signal) ? ["HEAD~1"] : [];
-		const stat = await this.git(root, [
+		const base = amend && await this.hasParent(repository, signal) ? ["HEAD~1"] : [];
+		const stat = await this.read(repository, [
 			"diff",
+			...DIFF_SAFETY_ARGS,
 			"--cached",
 			"--stat",
 			...base
 		], signal);
 		if (stat.exitCode !== 0) return { failure: classify(stat) };
 		const cap = settings.commitMessageMaxBytes;
-		const patch = await this.git(root, [
+		const patch = await this.read(repository, [
 			"diff",
+			...DIFF_SAFETY_ARGS,
 			"--cached",
 			"--no-color",
 			...base
@@ -1074,12 +1129,12 @@ var GitReader = class {
 	}
 	/**
 	* Whether HEAD has a parent commit.
-	* @param cwd - absolute repository root.
+	* @param repository - the resolved repository.
 	* @param signal - cancellation for the invocation.
 	* @returns true when `HEAD~1` resolves.
 	*/
-	async hasParent(cwd, signal) {
-		return (await this.git(cwd, [
+	async hasParent(repository, signal) {
+		return (await this.read(repository, [
 			"rev-parse",
 			"--verify",
 			"--quiet",
@@ -1088,12 +1143,12 @@ var GitReader = class {
 	}
 	/**
 	* The remote an unpublished branch would be published to.
-	* @param cwd - absolute repository root.
+	* @param repository - the resolved repository.
 	* @param signal - cancellation for the invocation.
 	* @returns `origin` when it exists, else the first remote, else undefined.
 	*/
-	async defaultRemote(cwd, signal) {
-		const outcome = await this.git(cwd, ["remote"], signal);
+	async defaultRemote(repository, signal) {
+		const outcome = await this.read(repository, ["remote"], signal);
 		if (outcome.exitCode !== 0) return void 0;
 		const remotes = outcome.stdout.split("\n").map((line) => line.trim()).filter((line) => line !== "");
 		return remotes.includes(DEFAULT_REMOTE) ? DEFAULT_REMOTE : remotes[0];
@@ -1105,16 +1160,16 @@ var GitReader = class {
 	* @param argv - builds the git arguments from the accepted paths.
 	* @returns the reading after the write, or a classified failure.
 	*/
-	async write(request, signal, argv) {
-		if (request.paths.length === 0) return fail$4("path-denied", "no paths were given");
-		const prepared = await this.prepare(request.workspacePath, signal);
+	async write(request$2, signal, argv) {
+		if (request$2.paths.length === 0) return fail$4("path-denied", "no paths were given");
+		const prepared = await this.prepare(request$2.workspacePath, signal);
 		if ("failure" in prepared) return prepared.failure;
 		const { repository } = prepared;
-		const contained = await this.contain(repository.root, request.paths, signal);
+		const contained = await this.contain(repository.root, request$2.paths, signal);
 		if (contained !== void 0) return contained;
-		const outcome = await this.git(repository.root, argv(request.paths), signal);
+		const outcome = await this.git(repository.root, argv(request$2.paths), signal);
 		if (outcome.exitCode !== 0) return classify(outcome);
-		const status = await this.status({ workspacePath: request.workspacePath }, signal);
+		const status = await this.status({ workspacePath: request$2.workspacePath }, signal);
 		return status.ok ? {
 			ok: true,
 			status
@@ -1142,12 +1197,12 @@ var GitReader = class {
 	}
 	/**
 	* The author `git commit` would record.
-	* @param cwd - the repository root.
+	* @param repository - the resolved repository.
 	* @param signal - cancellation for the invocation.
 	* @returns `Name <email>`, or undefined when git has no identity configured.
 	*/
-	async author(cwd, signal) {
-		const outcome = await this.git(cwd, ["var", "GIT_AUTHOR_IDENT"], signal);
+	async author(repository, signal) {
+		const outcome = await this.read(repository, ["var", "GIT_AUTHOR_IDENT"], signal);
 		if (outcome.exitCode !== 0) return void 0;
 		const ident = outcome.stdout.trim();
 		const at = ident.lastIndexOf(">");
@@ -1155,29 +1210,30 @@ var GitReader = class {
 	}
 	/**
 	* Whether the index differs from HEAD.
-	* @param cwd - the repository root.
+	* @param repository - the resolved repository.
 	* @param signal - cancellation for the invocation.
 	* @returns true when a commit would record something.
 	*/
-	async hasStaged(cwd, signal) {
-		return (await this.git(cwd, [
+	async hasStaged(repository, signal) {
+		return (await this.read(repository, [
 			"diff",
+			...DIFF_SAFETY_ARGS,
 			"--cached",
 			"--quiet"
 		], signal)).exitCode !== 0;
 	}
 	/**
 	* Report what the panel may do to this repository.
-	* @param cwd - the repository root.
+	* @param repository - the resolved repository.
 	* @param signal - cancellation for the identity lookup.
 	* @returns the write capability.
 	*/
-	async writeCapability(cwd, signal) {
+	async writeCapability(repository, signal) {
 		const settings = this.source();
 		const canStage = settings.allowGitStaging;
 		const canCommit = canStage && settings.allowGitCommit;
 		const canDraftMessage = canCommit && settings.allowCommitMessageDraft && this.ctx.get("llm") !== void 0 && this.ctx.get("agentDefaultModel") !== void 0;
-		const author = canCommit ? await this.author(cwd, signal) : void 0;
+		const author = canCommit ? await this.author(repository, signal) : void 0;
 		return {
 			canStage,
 			canCommit,
@@ -1217,16 +1273,70 @@ var GitReader = class {
 		if (outcome.exitCode !== 0) return { failure: classify(outcome) };
 		const [root, prefix] = outcome.stdout.split("\n");
 		if (root === void 0 || root.trim() === "") return { failure: fail$4("not-a-repository", `${cwd} is not inside a git repository`) };
+		const readingConfig = await this.untrustedFilterConfig(root.trim(), signal);
+		if ("failure" in readingConfig) return { failure: readingConfig.failure };
 		return { repository: {
 			root: root.trim(),
-			prefix: (prefix ?? "").trim().replace(/\/$/u, "")
+			prefix: (prefix ?? "").trim().replace(/\/$/u, ""),
+			readingConfig: readingConfig.config
 		} };
 	}
 	/**
-	* Run one git invocation with this plugin's own bounds.
+	* The overrides that switch off the content filters a repository's own config defines.
+	*
+	* Listing config runs nothing — `git config` reads files — so this is safe to ask before any
+	* reading. `--show-scope` arrived in git 2.26; an older git refuses the flag, and the listing is
+	* then repeated without it and every filter it names is treated as untrusted, which can only make
+	* a reading more conservative. A listing that fails both ways fails the reading: a status that
+	* cannot prove its filters are disarmed is not run.
+	* @param root - absolute repository root.
+	* @param signal - cancellation for the listing.
+	* @returns the `-c` pairs, or the failure to return.
+	*/
+	async untrustedFilterConfig(root, signal) {
+		const scoped = await this.git(root, [
+			"config",
+			"--show-scope",
+			"--name-only",
+			"--get-regexp",
+			FILTER_EXECUTABLE_KEYS
+		], signal);
+		const listing = isConfigListing(scoped) ? scoped : await this.git(root, [
+			"config",
+			"--name-only",
+			"--get-regexp",
+			FILTER_EXECUTABLE_KEYS
+		], signal);
+		if (!isConfigListing(listing)) return { failure: classify(listing) };
+		const overrides = filterOverrides(listing.stdout);
+		if ("unsafeKey" in overrides) return { failure: fail$4("git-failed", `refusing to read this repository: its config defines ${JSON.stringify(overrides.unsafeKey)}, a filter program that cannot be switched off from the command line`) };
+		return { config: overrides.config };
+	}
+	/**
+	* Run one READING: an invocation the panel makes on its own, which must run no program the
+	* repository's config names.
+	*
+	* On top of {@link git}'s own `core.fsmonitor` override it disarms the repository's content
+	* filters. Writes (`add`, `restore`, `commit`, `push`) deliberately do not go through here: they are
+	* an operator's explicit action, a filter such as LFS is part of what staging correctly means, and a
+	* commit's hooks are a real answer the panel reports.
+	* @param repository - the resolved repository, carrying its filter overrides.
+	* @param args - arguments after the executable and the overrides.
+	* @param signal - the caller's cancellation.
+	* @param maxBytes - the caller's own output bound, when it has one.
+	* @param cwd - directory to run in; the repository root unless the reading is relative to the workspace.
+	* @returns the finished command.
+	*/
+	read(repository, args, signal, maxBytes, cwd = repository.root) {
+		return this.git(cwd, [...repository.readingConfig, ...args], signal, maxBytes);
+	}
+	/**
+	* Run one git invocation with this plugin's own bounds and {@link INVOCATION_CONFIG}.
 	* @param cwd - directory to run in.
-	* @param args - arguments after the executable.
+	* @param args - arguments after the executable and the invocation config.
 	* @param signal - the caller's cancellation.
+	* @param maxBytes - the caller's own output bound, when it has one.
+	* @param timeoutMs - the caller's own wall-clock bound, when it has one.
 	* @returns the finished command.
 	*/
 	async git(cwd, args, signal, maxBytes, timeoutMs) {
@@ -1242,7 +1352,11 @@ var GitReader = class {
 		};
 		const settings = this.source();
 		return runCommand(this.ctx, {
-			argv: [executable, ...args],
+			argv: [
+				executable,
+				...INVOCATION_CONFIG,
+				...args
+			],
 			cwd,
 			timeoutMs: timeoutMs ?? settings.gitTimeoutMs,
 			maxBytes: maxBytes ?? Math.max(settings.gitDiffMaxBytes, 1 << 20),
@@ -1284,6 +1398,15 @@ var GitReader = class {
 	}
 };
 /**
+* Whether a `git config --get-regexp` finished with a usable answer.
+* @param outcome - the finished listing.
+* @returns true for a listing (exit 0) or for "nothing matched" (exit 1 with a silent stderr).
+*/
+function isConfigListing(outcome) {
+	if (outcome.exitCode === 0) return true;
+	return outcome.exitCode === CONFIG_NO_MATCH_EXIT && outcome.stderr.trim() === "";
+}
+/**
 * The empty left-hand side of an untracked file's synthesized patch.
 * @returns the platform's null device path.
 */
@@ -1360,14 +1483,14 @@ var OpenInLauncher = class {
 	* @param signal - cancellation for the launch.
 	* @returns settlement, or a classified failure.
 	*/
-	async open(request, signal) {
-		const resolvedPath = await resolveWorkspace(this.ctx, request.path, signal);
-		const target = resolvedPath.ok ? resolvedPath.value.processPath : await this.resolveFile(request.path, signal);
-		if (target === void 0) return fail$3("path-denied", `${request.path} does not exist on this Host`);
+	async open(request$2, signal) {
+		const resolvedPath = await resolveWorkspace(this.ctx, request$2.path, signal);
+		const target = resolvedPath.ok ? resolvedPath.value.processPath : await this.resolveFile(request$2.path, signal);
+		if (target === void 0) return fail$3("path-denied", `${request$2.path} does not exist on this Host`);
 		const directory = resolvedPath.ok;
-		if (request.targetId === REVEAL_TARGET_ID) return this.reveal(target, directory, signal);
-		const editor = this.source().editors.find((entry) => entry.id === request.targetId);
-		if (editor === void 0) return fail$3("unknown-target", `no Open in target "${request.targetId}"`);
+		if (request$2.targetId === REVEAL_TARGET_ID) return this.reveal(target, directory, signal);
+		const editor = this.source().editors.find((entry) => entry.id === request$2.targetId);
+		if (editor === void 0) return fail$3("unknown-target", `no Open in target "${request$2.targetId}"`);
 		const executable = await this.locate(editor.command, signal);
 		if (executable === void 0) return fail$3("unavailable", `${editor.label}: "${editor.command}" does not resolve on this Host`);
 		return this.launch([
@@ -1685,8 +1808,8 @@ var PreviewServers = class {
 	* @param signal - cancellation for the file read.
 	* @returns the list, or a classified failure.
 	*/
-	async list(request, signal) {
-		const workspace = await resolveWorkspace(this.ctx, request.workspacePath, signal);
+	async list(request$2, signal) {
+		const workspace = await resolveWorkspace(this.ctx, request$2.workspacePath, signal);
 		if (!workspace.ok) return fail$2(workspace.rejection.code === "no-filesystem" ? "no-filesystem" : "path-denied", workspace.rejection.message);
 		const file = await this.readLaunchFile(workspace, signal);
 		return {
@@ -1702,13 +1825,13 @@ var PreviewServers = class {
 	* @param signal - cancellation of the start itself; a started server owns its later lifetime.
 	* @returns the started row, or a classified failure.
 	*/
-	async start(request, signal) {
+	async start(request$2, signal) {
 		if (this.closing) return fail$2("closed", "the plugin is unloading");
 		if (this.ctx.get("subprocess") === void 0) return fail$2("no-subprocess", "no subprocess capability is mounted");
-		const workspace = await resolveWorkspace(this.ctx, request.workspacePath, signal);
+		const workspace = await resolveWorkspace(this.ctx, request$2.workspacePath, signal);
 		if (!workspace.ok) return fail$2(workspace.rejection.code === "no-filesystem" ? "no-filesystem" : "path-denied", workspace.rejection.message);
-		const resolved = mergeLaunches((await this.readLaunchFile(workspace, signal)).launches, this.settingsLaunches()).find((entry) => entry.launch.name === request.name);
-		if (resolved === void 0) return fail$2("unknown-server", `no launch configuration named "${request.name}"`);
+		const resolved = mergeLaunches((await this.readLaunchFile(workspace, signal)).launches, this.settingsLaunches()).find((entry) => entry.launch.name === request$2.name);
+		if (resolved === void 0) return fail$2("unknown-server", `no launch configuration named "${request$2.name}"`);
 		const launch = resolved.launch;
 		if (launch.runtimeExecutable === void 0 || launch.runtimeExecutable === "") return fail$2("not-startable", `"${launch.name}" names no command; it opens its url and starts nothing`);
 		const key = `${workspace.value.processPath}\u0000${launch.name}`;
@@ -1804,9 +1927,9 @@ var PreviewServers = class {
 	* @param request - the handle.
 	* @returns settlement, or a classified failure.
 	*/
-	async stop(request) {
-		const record = this.records.get(request.serverId);
-		if (record === void 0) return fail$2("unknown-server", `no preview server ${request.serverId}`);
+	async stop(request$2) {
+		const record = this.records.get(request$2.serverId);
+		if (record === void 0) return fail$2("unknown-server", `no preview server ${request$2.serverId}`);
 		this.records.delete(record.serverId);
 		await this.terminate(record);
 		return { ok: true };
@@ -1816,12 +1939,12 @@ var PreviewServers = class {
 	* @param request - the handle and the offset already rendered.
 	* @returns the delta and the state, or a classified failure.
 	*/
-	logs(request) {
-		const record = this.records.get(request.serverId);
-		if (record === void 0) return fail$2("unknown-server", `no preview server ${request.serverId}`);
+	logs(request$2) {
+		const record = this.records.get(request$2.serverId);
+		if (record === void 0) return fail$2("unknown-server", `no preview server ${request$2.serverId}`);
 		this.drain(record);
 		const total = record.base + record.buffer.length;
-		const from = Number.isFinite(request.fromOffset) ? Math.max(0, Math.floor(request.fromOffset)) : 0;
+		const from = Number.isFinite(request$2.fromOffset) ? Math.max(0, Math.floor(request$2.fromOffset)) : 0;
 		const lossy = from < record.base;
 		const text = lossy ? record.buffer : record.buffer.slice(Math.min(from - record.base, record.buffer.length));
 		return {
@@ -2042,34 +2165,101 @@ var PreviewServers = class {
 };
 
 //#endregion
-//#region tsbuild/host/terminals.js
-/** Compose one classified failure. */
-function fail$1(code, message) {
-	return {
-		ok: false,
-		code,
-		message
-	};
-}
-/** Terminal geometry the substrate will accept, whatever the panel measured. */
-function clampGeometry(cols, rows) {
-	const bound = (value, low, high) => Number.isFinite(value) ? Math.min(Math.max(Math.round(value), low), high) : low;
-	return {
-		cols: bound(cols, 20, 500),
-		rows: bound(rows, 5, 200)
-	};
+//#region tsbuild/host/preview-serve.js
+/**
+* Largest scratchpad document the Host will echo back.
+*
+* The scratchpad is a person typing HTML into a text area; a megabyte of it is a mistake or an
+* attempt to make the Host hold memory, and neither is worth serving.
+*/
+const SCRATCHPAD_MAX_BYTES = 1024 * 1024;
+/**
+* How many bytes of a file's head feed the change token.
+*
+* The token is what makes the panel reload when a file changes on disk. Hashing the whole file
+* would read a video twice per poll; hashing the head misses an edit past the first 8 KB, so the
+* token is `version + size + head digest` — the backend's own opaque version already changes on any
+* write, and the head digest is the fallback for a backend that reports a constant version.
+*/
+const TOKEN_PROBE_BYTES = 8192;
+/**
+* Largest byte window this module will ask a filesystem for.
+*
+* `ctx.fs.readBytes` takes a cap rather than a range, so a request for the middle of a file is
+* impossible through it; the window is what the fallback path reads, and it is bounded well below
+* `previewMaxFileBytes` so an over-limit read cannot become an out-of-memory.
+*/
+const FALLBACK_READ_BYTES = 4 * 1024 * 1024;
+/**
+* Whether a filesystem implementation can read one byte window.
+* @param fs - the filesystem, or the value `ctx.get('fs')` returned.
+* @returns true when the ranged read is available.
+*/
+function hasRangeRead(fs) {
+	return "readByteRange" in fs && typeof fs.readByteRange === "function";
 }
+/** Upstream statuses re-sent as-is; everything else keeps its status but loses its body only on HEAD. */
+const HOP_BY_HOP = new Set([
+	"connection",
+	"keep-alive",
+	"proxy-authenticate",
+	"proxy-authorization",
+	"te",
+	"trailer",
+	"transfer-encoding",
+	"upgrade"
+]);
 /**
-* Owns every panel terminal in the process. One instance is created by the service and disposed
-* with it, which is what guarantees no shell outlives the plugin.
+* Headers the proxy decides for itself.
+*
+* `host` is rewritten to the upstream's own authority, because a dev server routes on it and a
+* virtual-hosted one would answer the wrong site; `origin` and `referer` point at the GUI, and
+* forwarding them would make the dev server reject a request it thinks is cross-site; `accept-encoding`
+* is dropped so the upstream's response and the GUI's compression middleware never double-encode.
 */
-var PanelTerminals = class {
+const REWRITTEN_REQUEST_HEADERS = new Set([
+	"host",
+	"origin",
+	"referer",
+	"accept-encoding",
+	"connection"
+]);
+/**
+* Name prefix of the harness's browser-session cookie (`dsh-client-connection`, `COOKIE_PREFIX`).
+*
+* The full name is this prefix plus a digest of the authority, so the prefix is the stable part. A
+* request forwarded to a dev server must not carry it — whatever listens on a loopback port would
+* otherwise hold a credential that authenticates it to the whole harness API — and a dev server's
+* `Set-Cookie` must not be able to replace it on the GUI's origin.
+*/
+const HOST_AUTH_COOKIE_PREFIX = "dsh-auth-";
+/** The hop-by-hop headers a websocket tunnel must still forward, because they are the handshake. */
+const UPGRADE_HANDSHAKE_HEADERS = new Set(["connection", "upgrade"]);
+/**
+* Serves workspace files and proxies loopback dev servers on the GUI's own origin.
+*
+* One instance is created by the service and disposed with it, which is what guarantees no route
+* outlives the plugin: every registration returns a disposer, and `dispose()` runs them all.
+*/
+var PreviewSurface = class {
 	ctx;
 	source;
-	records = /* @__PURE__ */ new Map();
-	closing = false;
 	/**
-	* @param ctx - Host context carrying the subprocess and filesystem capabilities.
+	* The upstream URL each panel last pointed its frame at, keyed by its client id.
+	*
+	* Only a fallback: a proxied document's own URLs all carry their target explicitly, because the
+	* browser rewrites them from the injected `<base>`. What needs this map is a request the base
+	* cannot reach — a `fetch()` from inside the page to a relative path, or a link with no base of
+	* its own — and there is exactly one sensible target for those.
+	*/
+	targets = /* @__PURE__ */ new Map();
+	/** Every request currently in flight, so a dispose does not leave sockets open. */
+	live = /* @__PURE__ */ new Set();
+	closed = false;
+	/** Whether the routes are registered; see {@link RouteState}. */
+	routes = "absent";
+	/**
+	* @param ctx - Host context carrying the optional filesystem capability.
 	* @param source - reads the current settings section; called per request.
 	*/
 	constructor(ctx, source) {
@@ -2077,53 +2267,881 @@ var PanelTerminals = class {
 		this.source = source;
 	}
 	/**
-	* Report whether a panel terminal can be allocated on this Host.
-	* @returns availability plus the shell that would answer.
+	* What this surface is, for `describe()`.
+	* @returns the route paths and whether the routes are actually mounted.
 	*/
-	describe() {
-		if (this.ctx.get("subprocess") === void 0) return {
-			available: false,
-			reason: "no subprocess capability is mounted: this deployment composes no @deepseek-ai/dsh-subprocess provider"
-		};
-		if (this.ctx.get("fs") === void 0) return {
-			available: false,
-			reason: "no filesystem capability is mounted: the terminal has no way to resolve its working directory"
-		};
-		return {
-			available: true,
-			detail: this.shell()
-		};
+	info() {
+		switch (this.routes) {
+			case "mounted": return {
+				fileRoute: FILE_ROUTE,
+				proxyRoute: PROXY_ROUTE,
+				available: true
+			};
+			case "absent": return {
+				fileRoute: FILE_ROUTE,
+				proxyRoute: PROXY_ROUTE,
+				available: false,
+				reason: "no web server capability is mounted: a workspace file has no same-origin URL to be framed from, and a dev server stays cross-origin"
+			};
+			case "ungated": return {
+				fileRoute: FILE_ROUTE,
+				proxyRoute: PROXY_ROUTE,
+				available: false,
+				reason: "this Host's connection exposes no request gate (requestRejection), so the preview routes are not mounted: without it they would serve workspace files to anything that can reach the port"
+			};
+			default: throw new TypeError(`advanced-sidebar: unexpected preview route state ${JSON.stringify(this.routes)}`);
+		}
 	}
 	/**
-	* Allocate one terminal in a workspace.
-	* @param request - the directory and the panel's measured geometry.
-	* @param signal - cancellation of the allocation; a published terminal owns its later lifetime.
-	* @returns the handle, or a classified failure.
+	* The URL one workspace file is framed from, or undefined when this Host serves no routes.
+	* @param workspacePath - absolute Host workspace directory.
+	* @param filePath - absolute Host path inside it.
+	* @returns the same-origin path, query included.
 	*/
-	async open(request, signal) {
-		if (this.closing) return fail$1("closed", "the plugin is unloading");
-		const subprocess = this.ctx.get("subprocess");
-		if (subprocess === void 0) return fail$1("no-subprocess", "no subprocess capability is mounted");
-		const settings = this.source();
-		if ([...this.records.values()].filter((record$1) => record$1.running).length >= settings.maxTerminals) return fail$1("limit-reached", `${String(settings.maxTerminals)} panel terminals are already open`);
-		const workspace = await resolveWorkspace(this.ctx, request.workspacePath, signal);
-		if (!workspace.ok) return fail$1(workspace.rejection.code === "no-filesystem" ? "no-filesystem" : "path-denied", workspace.rejection.message);
-		const shell = this.shell();
-		const { cols, rows } = clampGeometry(request.cols, request.rows);
-		let handle;
-		try {
-			handle = await subprocess.spawnTerminal({
-				argv: [shell],
-				cwd: workspace.value.processPath,
-				rows,
-				cols,
-				graceMs: settings.terminalGraceMs,
-				signal,
-				env: {
-					TERM: "xterm-256color",
-					COLUMNS: String(cols),
-					LINES: String(rows)
-				}
+	fileUrl(workspacePath, filePath) {
+		return this.info().available ? fileUrl(FILE_ROUTE, workspacePath, filePath) : void 0;
+	}
+	/**
+	* The same-origin URL that proxies one loopback URL.
+	* @param target - the loopback URL, already validated by the caller.
+	* @returns the same-origin path, query included.
+	*/
+	proxyUrl(target) {
+		return proxyUrlFor(PROXY_ROUTE, target);
+	}
+	/**
+	* Register every route with the mounted web server, each behind the connection's request gate.
+	*
+	* Registration goes through `ctx.inject(['connection', 'webServer'], …)` rather than a constructor
+	* read: a headless deployment composes neither, and the inject face simply never runs, leaving the
+	* rest of the plugin working. The connection is a hard requirement rather than an optional extra —
+	* it is the only thing that can tell the GUI's own browser from any other client of the port — so a
+	* connection without `requestRejection` mounts nothing and says so through {@link info}.
+	*/
+	install() {
+		this.ctx.inject(["connection", "webServer"], (routeCtx) => {
+			const connection = Reflect.get(routeCtx, "connection");
+			const webServer = Reflect.get(routeCtx, "webServer");
+			const requestRejection = connection?.requestRejection;
+			if (typeof requestRejection !== "function") {
+				this.routes = "ungated";
+				return () => {
+					this.routes = "absent";
+				};
+			}
+			const gate = (req) => requestRejection.call(connection, req);
+			const disposeFile = webServer.register({
+				kind: "exact",
+				path: FILE_ROUTE,
+				handler: (req, res) => refuseHttp(gate, req, res) ? void 0 : this.handleFile(req, res)
+			});
+			const disposeScratch = webServer.register({
+				kind: "exact",
+				path: SCRATCHPAD_ROUTE,
+				handler: (req, res) => refuseHttp(gate, req, res) ? void 0 : this.handleScratchpad(req, res)
+			});
+			const disposeProxy = webServer.register({
+				kind: "prefix",
+				path: PROXY_ROUTE,
+				handler: (req, res) => refuseHttp(gate, req, res) ? void 0 : this.handleProxy(req, res)
+			});
+			const disposeUpgrade = webServer.registerUpgrade({
+				path: PROXY_ROUTE,
+				handler: (req, socket, head) => {
+					if (refuseUpgrade(gate, req, socket)) return;
+					this.handleUpgrade(req, socket, head);
+				}
+			});
+			this.routes = "mounted";
+			return () => {
+				this.routes = "absent";
+				disposeUpgrade();
+				disposeProxy();
+				disposeScratch();
+				disposeFile();
+			};
+		});
+	}
+	/** Forget every target and abort every in-flight request. Called from the plugin's teardown. */
+	dispose() {
+		this.closed = true;
+		this.targets.clear();
+		for (const upstream of [...this.live]) upstream.abort();
+		this.live.clear();
+	}
+	/**
+	* Describe one workspace file for the panel, or refuse it.
+	* @param workspacePath - absolute Host workspace directory.
+	* @param path - absolute Host path, or a path relative to the workspace.
+	* @param signal - cancellation for the resolution and the metadata read.
+	* @returns the file's kind, size, frame URL, and change token.
+	*/
+	async info_(workspacePath, path, signal) {
+		const resolved = await this.resolve(workspacePath, path, signal);
+		if (!resolved.ok) return resolved.failure;
+		return this.describeFile(resolved.workspace, resolved.target, resolved.display, signal);
+	}
+	/**
+	* Serve one workspace file as the frame's document or as one of its subresources.
+	* @param req - the incoming request.
+	* @param res - the response the handler owns.
+	*/
+	async handleFile(req, res) {
+		if (req.method !== "GET" && req.method !== "HEAD") {
+			send(res, 405, "text/plain; charset=utf-8", "only GET and HEAD are served here");
+			return;
+		}
+		const query = new URL(req.url ?? "/", "http://x").searchParams;
+		const resolved = await this.resolve(query.get("workspace") ?? void 0, query.get("path") ?? "", void 0);
+		if (!resolved.ok) {
+			res.setHeader("cache-control", "no-store");
+			send(res, 404, "text/plain; charset=utf-8", resolved.failure.message);
+			return;
+		}
+		const fs = this.ctx.get("fs");
+		/* v8 ignore next -- `resolve` refuses before this point when the capability is absent. */
+		if (fs === void 0) {
+			send(res, 500, "text/plain; charset=utf-8", "filesystem capability withdrawn mid-request");
+			return;
+		}
+		const stat = await fs.stat(resolved.target);
+		if (stat === void 0 || stat.type !== "file") {
+			res.setHeader("cache-control", "no-store");
+			send(res, 404, "text/plain; charset=utf-8", `${resolved.display} is not a regular file`);
+			return;
+		}
+		const size = stat.size ?? 0;
+		const contentType = contentTypeOf(resolved.display);
+		const etag = await this.etag(resolved.target, stat.version, size, stat.size);
+		res.setHeader("cache-control", "no-store");
+		res.setHeader("etag", etag);
+		res.setHeader("last-modified", (/* @__PURE__ */ new Date()).toUTCString());
+		if (req.headers["if-none-match"] === etag) {
+			res.writeHead(304);
+			res.end();
+			return;
+		}
+		if (size > this.source().previewMaxFileBytes) {
+			send(res, 413, "text/plain; charset=utf-8", `${resolved.display} is ${String(size)} bytes, over previewMaxFileBytes`);
+			return;
+		}
+		res.setHeader("content-type", isTextual(contentType) ? `${contentType}; charset=utf-8` : contentType);
+		res.setHeader("x-content-type-options", "nosniff");
+		res.setHeader("content-encoding", "identity");
+		const ranged = hasRangeRead(fs) ? fs : void 0;
+		res.setHeader("accept-ranges", ranged === void 0 ? "none" : "bytes");
+		const asked = ranged === void 0 ? void 0 : parseRange(req.headers.range, size);
+		if (asked === "unsatisfiable") {
+			res.setHeader("content-range", `bytes */${String(size)}`);
+			send(res, 416, "text/plain; charset=utf-8", "the requested range is past the end of the file");
+			return;
+		}
+		const range = typeof asked === "string" ? void 0 : asked;
+		let bytes;
+		try {
+			bytes = range === void 0 ? await fs.readBytes(resolved.target, void 0, size) : await (ranged ?? fs).readByteRange(resolved.target, {
+				offset: range.start,
+				length: range.end - range.start + 1
+			});
+		} catch (error) {
+			send(res, 500, "text/plain; charset=utf-8", error instanceof Error ? error.message : String(error));
+			return;
+		}
+		let body = bytes;
+		if (range === void 0 && contentType === "text/html" && size <= FALLBACK_READ_BYTES) body = new TextEncoder().encode(injectBase(decodeText(bytes), `${FILE_ROUTE}?workspace=${encodeQuery(resolved.workspace.processPath)}&path=`));
+		if (range !== void 0) res.setHeader("content-range", `bytes ${String(range.start)}-${String(range.end)}/${String(size)}`);
+		res.setHeader("content-length", String(body.byteLength));
+		res.writeHead(range === void 0 ? 200 : 206);
+		if (req.method === "HEAD") res.end();
+		else res.end(Buffer.from(body));
+	}
+	/**
+	* Serve text the panel posted, as an HTML document on this origin.
+	*
+	* The scratchpad renders as `text/html` rather than through `srcdoc` so that the frame's document
+	* has a real URL with this origin: `document.baseURI`, relative `fetch`, and `window.location` all
+	* then behave the way the page under test expects, and an agent's `eval` sees them.
+	* @param req - the incoming request.
+	* @param res - the response the handler owns.
+	*/
+	handleScratchpad(req, res) {
+		if (req.method !== "POST" && req.method !== "GET" && req.method !== "HEAD") {
+			send(res, 405, "text/plain; charset=utf-8", "only GET, HEAD and POST are served here");
+			return;
+		}
+		res.setHeader("cache-control", "no-store");
+		res.setHeader("content-type", "text/html; charset=utf-8");
+		res.setHeader("x-content-type-options", "nosniff");
+		res.setHeader("content-encoding", "identity");
+		if (req.method !== "POST") {
+			res.setHeader("content-length", "0");
+			res.writeHead(204);
+			res.end();
+			return;
+		}
+		const chunks = [];
+		let total = 0;
+		let refused = false;
+		req.on("data", (chunk) => {
+			if (refused) return;
+			total += chunk.byteLength;
+			if (total > SCRATCHPAD_MAX_BYTES) {
+				refused = true;
+				send(res, 413, "text/plain; charset=utf-8", "the scratchpad document is over its size limit");
+				req.destroy();
+				return;
+			}
+			chunks.push(chunk);
+		});
+		req.on("end", () => {
+			if (refused) return;
+			const document = Buffer.concat(chunks).toString("utf8");
+			const body = Buffer.from(injectBase(document, "/"), "utf8");
+			res.setHeader("content-length", String(body.byteLength));
+			res.writeHead(200);
+			if (req.method === "HEAD") res.end();
+			else res.end(body);
+		});
+		req.on("error", () => {
+			if (!refused) res.destroy();
+		});
+	}
+	/**
+	* Forward one request to a loopback upstream and stream the answer back.
+	* @param req - the incoming request.
+	* @param res - the response the handler owns.
+	*/
+	async handleProxy(req, res) {
+		if (this.closed) {
+			send(res, 503, "text/plain; charset=utf-8", "the preview surface is unloading");
+			return;
+		}
+		const url = new URL(req.url ?? "/", "http://x");
+		const explicit = url.searchParams.get("url");
+		const suffix = suffixOf(url.pathname);
+		const target = explicit === null ? this.fallbackTarget(req, suffix) : validateProxyTarget(explicit);
+		if (target === void 0) {
+			send(res, 404, "text/plain; charset=utf-8", "this proxied request names no loopback target: the preview proxy forwards only requests that carry `?url=`, or that a bound preview frame could have produced");
+			return;
+		}
+		if (!target.ok) {
+			send(res, 403, "text/plain; charset=utf-8", target.message);
+			return;
+		}
+		const upstreamUrl = new URL(target.url.href);
+		if (explicit === null) {
+			const basePath = upstreamUrl.pathname.replace(/\/$/u, "");
+			if (suffix !== "") upstreamUrl.pathname = `${basePath}/${suffix}`;
+			upstreamUrl.search = url.search;
+		} else if (suffix !== "") {
+			const basePath = upstreamUrl.pathname.replace(/\/$/u, "");
+			upstreamUrl.pathname = suffix.startsWith(basePath.slice(1)) ? `/${suffix}` : `${basePath}/${suffix}`;
+			const forwarded = new URLSearchParams(url.searchParams);
+			forwarded.delete("url");
+			const extra = forwarded.toString();
+			upstreamUrl.search = extra === "" ? "" : `?${extra}`;
+		}
+		this.forward(req, res, upstreamUrl);
+	}
+	/**
+	* Forward one upgraded connection to a loopback upstream.
+	*
+	* A dev server's live-reload socket is an optional convenience, not part of the inspection story:
+	* a websocket carries no DOM and no console, and a page whose socket never opens still renders and
+	* is still drivable. The tunnel is here because it is cheap — a raw `net` pipe with no protocol
+	* knowledge — but a server that negotiates on a path other than the route's own root is not
+	* tunnelled, because the web server's upgrade seat matches exact paths and claiming a wildcard
+	* would collide with the app's own sockets.
+	* @param req - the upgrade request.
+	* @param socket - the client socket the handler owns.
+	* @param head - bytes the parser already read past the request line.
+	*/
+	handleUpgrade(req, socket, head) {
+		const url = new URL(req.url ?? "/", "http://x");
+		const explicit = url.searchParams.get("url");
+		const suffix = suffixOf(url.pathname);
+		const target = explicit === null ? this.fallbackTarget(req, suffix) : validateProxyTarget(explicit);
+		if (target === void 0 || !target.ok) {
+			socket.end("HTTP/1.1 404 Not Found\r\nconnection: close\r\n\r\n");
+			return;
+		}
+		const upstreamUrl = new URL(target.url.href);
+		const rest = explicit === null ? suffix : "";
+		if (rest !== "") upstreamUrl.pathname = `${upstreamUrl.pathname.replace(/\/$/u, "")}/${rest.replace(/^\//u, "")}`;
+		const port = upstreamUrl.port === "" ? upstreamUrl.protocol === "https:" ? 443 : 80 : Number(upstreamUrl.port);
+		const upstream = connect({
+			host: upstreamUrl.hostname.replace(/^\[|\]$/gu, ""),
+			port
+		});
+		const close = () => {
+			upstream.destroy();
+			socket.destroy();
+		};
+		upstream.on("error", close);
+		socket.on("error", close);
+		upstream.on("connect", () => {
+			const headers = {
+				...req.headers,
+				host: upstreamUrl.host
+			};
+			const lines = [`${req.method ?? "GET"} ${upstreamUrl.pathname}${upstreamUrl.search} HTTP/1.1`];
+			for (const [name, value] of Object.entries(headers)) {
+				if (value === void 0) continue;
+				const lowered = name.toLowerCase();
+				if (lowered === "cookie") {
+					const kept = withoutHostAuthCookies(value);
+					if (kept !== void 0) lines.push(`cookie: ${kept}`);
+					continue;
+				}
+				if (HOP_BY_HOP.has(lowered) && !UPGRADE_HANDSHAKE_HEADERS.has(lowered)) continue;
+				if (Array.isArray(value)) for (const one of value) lines.push(`${name}: ${one}`);
+				else lines.push(`${name}: ${value}`);
+			}
+			upstream.write(`${lines.join("\r\n")}\r\n\r\n`);
+			if (head.byteLength > 0) upstream.write(head);
+			upstream.pipe(socket);
+			socket.pipe(upstream);
+		});
+	}
+	/**
+	* One upstream request, with the response streamed straight through.
+	* @param req - the client request.
+	* @param res - the client response.
+	* @param upstreamUrl - the absolute loopback URL to fetch.
+	*/
+	forward(req, res, upstreamUrl) {
+		const headers = {};
+		for (const [name, value] of Object.entries(req.headers)) {
+			if (value === void 0) continue;
+			const lowered = name.toLowerCase();
+			if (HOP_BY_HOP.has(lowered) || REWRITTEN_REQUEST_HEADERS.has(lowered)) continue;
+			if (lowered === "cookie") {
+				const kept = withoutHostAuthCookies(value);
+				if (kept !== void 0) headers[name] = kept;
+				continue;
+			}
+			headers[name] = value;
+		}
+		headers.host = upstreamUrl.host;
+		headers.accept = typeof req.headers.accept === "string" ? req.headers.accept : "*/*";
+		const upstreamReq = (upstreamUrl.protocol === "https:" ? request$1 : request)({
+			protocol: upstreamUrl.protocol,
+			hostname: upstreamUrl.hostname.replace(/^\[|\]$/gu, ""),
+			port: upstreamUrl.port === "" ? void 0 : Number(upstreamUrl.port),
+			path: `${upstreamUrl.pathname}${upstreamUrl.search}`,
+			method: req.method ?? "GET",
+			headers
+		}, (upstreamRes) => {
+			const contentType = String(upstreamRes.headers["content-type"] ?? "");
+			const streaming = contentType.includes("text/event-stream");
+			res.setHeader("cache-control", streaming ? "no-cache" : "no-store");
+			res.setHeader("x-content-type-options", "nosniff");
+			res.setHeader("content-encoding", "identity");
+			let injected;
+			if (contentType.startsWith("text/html") && req.method !== "HEAD") {
+				const chunks = [];
+				upstreamRes.on("data", (chunk) => {
+					chunks.push(chunk);
+				});
+				upstreamRes.on("end", () => {
+					const text = Buffer.concat(chunks).toString("utf8");
+					const base = baseOf(text) ?? `${PROXY_ROUTE}?url=${encodeQuery(upstreamUrl.href)}`;
+					injected = Buffer.from(injectBase(text, base), "utf8");
+					res.setHeader("content-length", String(injected.byteLength));
+					res.writeHead(upstreamRes.statusCode ?? 502, forwardHeaders(upstreamRes));
+					res.end(injected);
+				});
+				upstreamRes.on("error", () => {
+					res.destroy();
+				});
+				upstreamReq.on("error", () => {
+					if (!res.headersSent) send(res, 502, "text/plain; charset=utf-8", "the upstream dev server closed the connection");
+				});
+				return;
+			}
+			for (const [name, value] of Object.entries(upstreamRes.headers)) {
+				if (value === void 0 || HOP_BY_HOP.has(name.toLowerCase())) continue;
+				if (name.toLowerCase() === "set-cookie") {
+					const kept = withoutHostAuthSetCookies(value);
+					if (kept.length > 0) res.setHeader(name, kept);
+					continue;
+				}
+				if (name.toLowerCase() === "content-type" && isTextual(String(value))) {
+					res.setHeader(name, String(value).includes("charset") ? String(value) : `${String(value)}; charset=utf-8`);
+					continue;
+				}
+				res.setHeader(name, value);
+			}
+			res.writeHead(upstreamRes.statusCode ?? 502);
+			upstreamRes.pipe(res);
+			upstreamRes.on("error", () => {
+				res.destroy();
+			});
+		});
+		const timeout = this.source().previewProxyTimeoutMs;
+		upstreamReq.setTimeout(timeout, () => {
+			upstreamReq.destroy(/* @__PURE__ */ new Error(`the upstream dev server did not answer within ${String(timeout)}ms`));
+		});
+		upstreamReq.on("error", (error) => {
+			if (res.headersSent) {
+				res.destroy();
+				return;
+			}
+			send(res, 502, "text/plain; charset=utf-8", `the preview proxy could not reach ${upstreamUrl.origin}: ${error.message}`);
+		});
+		const upstream = { abort: () => {
+			upstreamReq.destroy();
+		} };
+		this.live.add(upstream);
+		res.on("close", () => {
+			this.live.delete(upstream);
+			upstreamReq.destroy();
+		});
+		req.pipe(upstreamReq);
+	}
+	/**
+	* Resolve a workspace and one path inside it.
+	* @param workspacePath - absolute Host workspace directory, absent to treat the path itself as one.
+	* @param path - absolute Host path, or a path relative to the workspace.
+	* @param signal - cancellation for the resolution.
+	* @returns the workspace, the contained target, and the path as it should be displayed.
+	*/
+	async resolve(workspacePath, path, signal) {
+		if (path.trim() === "") return {
+			ok: false,
+			failure: {
+				ok: false,
+				code: "path-denied",
+				message: "no path was given"
+			}
+		};
+		const workspace = await resolveWorkspace(this.ctx, workspacePath ?? path, signal);
+		if (!workspace.ok) return {
+			ok: false,
+			failure: {
+				ok: false,
+				code: workspace.rejection.code === "no-filesystem" ? "no-filesystem" : "path-denied",
+				message: workspace.rejection.message
+			}
+		};
+		if (workspacePath === void 0) {
+			const refused$1 = await this.outsideRegisteredWorkspaces(workspace.value.target, path, signal);
+			if (refused$1 !== void 0) return {
+				ok: false,
+				failure: refused$1
+			};
+			return {
+				ok: true,
+				workspace: workspace.value,
+				target: workspace.value.target,
+				display: path
+			};
+		}
+		const inside = await resolveInside(this.ctx, workspace.value, path, signal);
+		if (!inside.ok) return {
+			ok: false,
+			failure: {
+				ok: false,
+				code: inside.rejection.code === "no-filesystem" ? "no-filesystem" : "path-denied",
+				message: inside.rejection.message
+			}
+		};
+		const refused = await this.outsideRegisteredWorkspaces(inside.value.target, path, signal);
+		if (refused !== void 0) return {
+			ok: false,
+			failure: refused
+		};
+		return {
+			ok: true,
+			workspace: workspace.value,
+			target: inside.value.target,
+			display: inside.value.processPath
+		};
+	}
+	/**
+	* Refuse a target that sits inside none of the harness's registered workspaces.
+	*
+	* The workspace a request names is only the root its relative paths hang from; it is not evidence
+	* that the directory is one the operator opened. `?workspace=/` would otherwise make the whole disk
+	* a workspace, so the canonical target is checked against the registry's own canonical paths — the
+	* list the sidebar shows, and nothing a request can add to. A subdirectory of a registered
+	* workspace passes, because the file is still inside what the operator opened.
+	*
+	* Each registered path is resolved through the same filesystem as the target, so a symlinked
+	* workspace compares as its real directory on both sides. A registered directory that no longer
+	* resolves (deleted, unmounted) simply contains nothing.
+	* @param target - the canonical target the request resolved to.
+	* @param path - the path as asked, for the refusal message.
+	* @param signal - cancellation for the resolutions.
+	* @returns the refusal, or undefined when a registered workspace contains the target.
+	*/
+	async outsideRegisteredWorkspaces(target, path, signal) {
+		const fs = this.ctx.get("fs");
+		/* v8 ignore next 3 -- the caller resolved the target through the same service moments earlier. */
+		if (fs === void 0) return {
+			ok: false,
+			code: "no-filesystem",
+			message: "filesystem capability withdrawn mid-request"
+		};
+		const registry = this.ctx.get("workspaceRegistry");
+		if (registry === void 0) return {
+			ok: false,
+			code: "path-denied",
+			message: "no workspace registry is mounted, so no preview file can be proved to belong to a workspace"
+		};
+		const registered = registry.list().map((workspace) => workspace.path);
+		if ((await Promise.allSettled(registered.map((root) => fs.resolve(root, signal === void 0 ? {} : { signal })))).some((root) => root.status === "fulfilled" && fs.contains(root.value, target))) return void 0;
+		return {
+			ok: false,
+			code: "path-denied",
+			message: `${path} is outside every registered workspace`
+		};
+	}
+	/**
+	* Describe one already-resolved file.
+	* @param workspace - the resolved workspace.
+	* @param target - the resolved target.
+	* @param display - the path to report back and to base the content type on.
+	* @param signal - cancellation for the metadata and token reads.
+	* @returns the description.
+	*/
+	async describeFile(workspace, target, display, signal) {
+		const fs = this.ctx.get("fs");
+		/* v8 ignore next -- the caller resolved the workspace through the same service moments earlier. */
+		if (fs === void 0) return {
+			ok: false,
+			code: "no-filesystem",
+			message: "filesystem capability withdrawn mid-request"
+		};
+		const stat = await fs.stat(target, signal);
+		if (stat === void 0 || stat.type !== "file") return {
+			ok: false,
+			code: "not-a-file",
+			message: `${display} is not a regular file`
+		};
+		const size = stat.size ?? 0;
+		const contentType = contentTypeOf(display);
+		const kind = classifyFile(display, contentType);
+		const name = display.slice(display.lastIndexOf("/") + 1);
+		const url = kind === "other" || !this.info().available ? void 0 : fileUrl(FILE_ROUTE, workspace.processPath, display);
+		return {
+			ok: true,
+			path: display,
+			name,
+			kind,
+			contentType,
+			bytes: size,
+			withinLimit: size <= this.source().previewMaxFileBytes,
+			...url === void 0 ? {} : { url },
+			token: await this.etag(target, stat.version, size, stat.size, signal),
+			regular: true
+		};
+	}
+	/**
+	* A weak validator for one file: the backend's version, its size, and a digest of its head.
+	* @param target - the resolved target.
+	* @param version - the backend's opaque freshness token.
+	* @param size - the byte size; `undefined` asks for no probe read.
+	* @param reportedSize - the size the backend reported, which may be absent.
+	* @param signal - cancellation for the probe read.
+	* @returns the ETag body, quotes included.
+	*/
+	async etag(target, version, size, reportedSize, signal) {
+		const hash = createHash("sha1");
+		hash.update(String(version));
+		hash.update(`:${String(size)}:${String(reportedSize ?? "")}`);
+		const fs = this.ctx.get("fs");
+		if (fs !== void 0 && size > 0) try {
+			const window = Math.min(size, TOKEN_PROBE_BYTES);
+			const head = hasRangeRead(fs) ? await fs.readByteRange(target, {
+				offset: 0,
+				length: window
+			}, signal) : await fs.readBytes(target, signal, window);
+			hash.update(head);
+		} catch {}
+		return `W/"${hash.digest("hex").slice(0, 32)}"`;
+	}
+	/**
+	* The target one subresource request should be forwarded to.
+	* @param req - the subresource request.
+	* @param suffix - the path below the proxy route, without a leading slash.
+	* @returns the validated target, or undefined when this Host holds none for the caller.
+	*/
+	fallbackTarget(req, suffix) {
+		const client = req.headers["x-dsh-preview-client"];
+		const key = typeof client === "string" && client !== "" ? client : void 0;
+		const known = key === void 0 ? void 0 : this.targets.get(key);
+		if (known !== void 0) {
+			const parsed = validateProxyTarget(known);
+			if (parsed.ok) return parsed;
+		}
+		if (this.targets.size === 1) {
+			const only = [...this.targets.values()][0];
+			/* v8 ignore next -- `size === 1` guarantees the element exists. */
+			if (only !== void 0) {
+				const parsed = validateProxyTarget(only);
+				if (parsed.ok) return parsed;
+			}
+		}
+	}
+	/**
+	* Record the target one panel is framing, so its subresources resolve.
+	* @param clientId - the panel's id.
+	* @param target - the upstream URL, or undefined when the panel stopped framing one.
+	*/
+	rememberTarget(clientId, target) {
+		if (target === void 0) this.targets.delete(clientId);
+		else this.targets.set(clientId, target);
+	}
+};
+/**
+* The path below the proxy route, without a leading slash.
+* @param pathname - the request's pathname.
+* @returns the suffix, or the empty string at the route's own root.
+*/
+function suffixOf(pathname) {
+	return pathname.slice(PROXY_ROUTE.length).replace(/^\/+/u, "");
+}
+/**
+* The `<base href>` a proxied document already declares, when it declares one.
+*
+* A dev-server framework frequently injects its own base tag (`vite` does not, `next` does), and a
+* second one would be ignored by the parser in favour of the first. Reading it back means this
+* proxy either keeps the document's own answer or supplies one, never both.
+* @param html - the document text.
+* @returns the declared href, or undefined.
+*/
+function baseOf(html) {
+	const match = /<base\s[^>]*href\s*=\s*("([^"]*)"|'([^']*)')/iu.exec(html);
+	if (match === null) return void 0;
+	return match[2] ?? match[3];
+}
+/**
+* Upstream headers minus the hop-by-hop set, for the buffered HTML branch.
+* @param res - the upstream response.
+* @returns the headers to copy.
+*/
+function forwardHeaders(res) {
+	const headers = {};
+	for (const [name, value] of Object.entries(res.headers)) {
+		if (value === void 0 || HOP_BY_HOP.has(name.toLowerCase()) || name.toLowerCase() === "content-length") continue;
+		if (name.toLowerCase() === "set-cookie") {
+			const kept = withoutHostAuthSetCookies(value);
+			if (kept.length > 0) headers[name] = [...kept];
+			continue;
+		}
+		headers[name] = value;
+	}
+	return headers;
+}
+/**
+* Answer a refused HTTP request, when the gate refuses it.
+*
+* The body is one fixed word: the gate's reasons (which authority, which cookie) are exactly what a
+* probing client wants, and the GUI's own browser never sees this answer.
+* @param gate - the connection's request gate.
+* @param req - the incoming request.
+* @param res - the response the handler owns.
+* @returns true when the request was refused and answered.
+*/
+function refuseHttp(gate, req, res) {
+	const rejection = gate(req);
+	if (rejection === void 0) return false;
+	send(res, rejection, "text/plain; charset=utf-8", rejectionText(rejection));
+	return true;
+}
+/**
+* Close a refused upgrade with a well-formed HTTP answer, when the gate refuses it.
+*
+* Written as a complete response, the way the harness's own Typert websocket refuses one, so a
+* client sees `401`/`403` rather than a reset it would retry.
+* @param gate - the connection's request gate.
+* @param req - the upgrade request.
+* @param socket - the client socket the handler owns.
+* @returns true when the upgrade was refused and the socket closed.
+*/
+function refuseUpgrade(gate, req, socket) {
+	const rejection = gate(req);
+	if (rejection === void 0) return false;
+	const body = rejectionText(rejection);
+	socket.end([
+		`HTTP/1.1 ${String(rejection)} ${rejection === 401 ? "Unauthorized" : "Forbidden"}`,
+		"connection: close",
+		"content-type: text/plain; charset=utf-8",
+		`content-length: ${String(Buffer.byteLength(body))}`,
+		"",
+		body
+	].join("\r\n"));
+	return true;
+}
+/**
+* The body a refusal carries.
+* @param rejection - the gate's status.
+* @returns the word for it.
+*/
+function rejectionText(rejection) {
+	switch (rejection) {
+		case 401: return "unauthorized";
+		case 403: return "forbidden";
+		default: throw new TypeError(`advanced-sidebar: unexpected rejection ${String(rejection)}`);
+	}
+}
+/**
+* A `Cookie` request header minus the harness's own browser-session cookie.
+* @param header - the raw header; Node joins repeated `Cookie` headers into one string.
+* @returns the remaining pairs, or undefined when nothing remains.
+*/
+function withoutHostAuthCookies(header) {
+	const kept = (typeof header === "string" ? header : header.join("; ")).split(";").map((pair) => pair.trim()).filter((pair) => pair !== "" && !pair.startsWith(HOST_AUTH_COOKIE_PREFIX));
+	return kept.length === 0 ? void 0 : kept.join("; ");
+}
+/**
+* Upstream `Set-Cookie` values minus any that would replace the harness's own session cookie.
+* @param header - one value or the list Node collects.
+* @returns the values a dev server may still set on this origin.
+*/
+function withoutHostAuthSetCookies(header) {
+	return (typeof header === "string" ? [header] : header).filter((value) => !value.trimStart().startsWith(HOST_AUTH_COOKIE_PREFIX));
+}
+/**
+* Parse one `Range` header against a known size.
+*
+* Only `bytes=` and only a single range are honoured: a multipart range costs a multipart encoder to
+* serve, and the one caller that matters — a `<video>` scrubber — asks for one range at a time.
+* @param header - the raw header value.
+* @param size - the file's size in bytes.
+* @returns the range, undefined for a full response, or `unsatisfiable`.
+*/
+function parseRange(header, size) {
+	if (header === void 0 || !header.startsWith("bytes=")) return void 0;
+	const parts = (header.slice(6).split(",")[0]?.trim() ?? "").split("-");
+	if (parts.length !== 2) return void 0;
+	const [rawStart, rawEnd] = parts;
+	const start = rawStart === void 0 || rawStart === "" ? void 0 : Number.parseInt(rawStart, 10);
+	const end = rawEnd === void 0 || rawEnd === "" ? void 0 : Number.parseInt(rawEnd, 10);
+	if (start !== void 0 && Number.isNaN(start)) return void 0;
+	if (end !== void 0 && Number.isNaN(end)) return void 0;
+	if (start === void 0 && end === void 0) return void 0;
+	if (size === 0) return "unsatisfiable";
+	if (start === void 0) {
+		const length = end ?? 0;
+		if (length <= 0) return "unsatisfiable";
+		return {
+			start: Math.max(0, size - length),
+			end: size - 1
+		};
+	}
+	if (start >= size) return "unsatisfiable";
+	const last = end === void 0 ? size - 1 : Math.min(end, size - 1);
+	if (last < start) return "unsatisfiable";
+	return {
+		start,
+		end: last
+	};
+}
+/**
+* Answer one request with a short, uncached body.
+* @param res - the response.
+* @param status - the HTTP status.
+* @param contentType - the MIME type.
+* @param body - the text to send.
+*/
+function send(res, status, contentType, body) {
+	if (res.headersSent) {
+		res.end();
+		return;
+	}
+	res.setHeader("content-type", contentType);
+	res.setHeader("cache-control", "no-store");
+	res.setHeader("content-encoding", "identity");
+	res.setHeader("content-length", String(Buffer.byteLength(body)));
+	res.writeHead(status);
+	res.end(body);
+}
+
+//#endregion
+//#region tsbuild/host/terminals.js
+/** Compose one classified failure. */
+function fail$1(code, message) {
+	return {
+		ok: false,
+		code,
+		message
+	};
+}
+/** Terminal geometry the substrate will accept, whatever the panel measured. */
+function clampGeometry(cols, rows) {
+	const bound = (value, low, high) => Number.isFinite(value) ? Math.min(Math.max(Math.round(value), low), high) : low;
+	return {
+		cols: bound(cols, 20, 500),
+		rows: bound(rows, 5, 200)
+	};
+}
+/**
+* Owns every panel terminal in the process. One instance is created by the service and disposed
+* with it, which is what guarantees no shell outlives the plugin.
+*/
+var PanelTerminals = class {
+	ctx;
+	source;
+	records = /* @__PURE__ */ new Map();
+	closing = false;
+	/**
+	* @param ctx - Host context carrying the subprocess and filesystem capabilities.
+	* @param source - reads the current settings section; called per request.
+	*/
+	constructor(ctx, source) {
+		this.ctx = ctx;
+		this.source = source;
+	}
+	/**
+	* Report whether a panel terminal can be allocated on this Host.
+	* @returns availability plus the shell that would answer.
+	*/
+	describe() {
+		if (this.ctx.get("subprocess") === void 0) return {
+			available: false,
+			reason: "no subprocess capability is mounted: this deployment composes no @deepseek-ai/dsh-subprocess provider"
+		};
+		if (this.ctx.get("fs") === void 0) return {
+			available: false,
+			reason: "no filesystem capability is mounted: the terminal has no way to resolve its working directory"
+		};
+		return {
+			available: true,
+			detail: this.shell()
+		};
+	}
+	/**
+	* Allocate one terminal in a workspace.
+	* @param request - the directory and the panel's measured geometry.
+	* @param signal - cancellation of the allocation; a published terminal owns its later lifetime.
+	* @returns the handle, or a classified failure.
+	*/
+	async open(request$2, signal) {
+		if (this.closing) return fail$1("closed", "the plugin is unloading");
+		const subprocess = this.ctx.get("subprocess");
+		if (subprocess === void 0) return fail$1("no-subprocess", "no subprocess capability is mounted");
+		const settings = this.source();
+		if ([...this.records.values()].filter((record$1) => record$1.running).length >= settings.maxTerminals) return fail$1("limit-reached", `${String(settings.maxTerminals)} panel terminals are already open`);
+		const workspace = await resolveWorkspace(this.ctx, request$2.workspacePath, signal);
+		if (!workspace.ok) return fail$1(workspace.rejection.code === "no-filesystem" ? "no-filesystem" : "path-denied", workspace.rejection.message);
+		const shell = this.shell();
+		const { cols, rows } = clampGeometry(request$2.cols, request$2.rows);
+		let handle;
+		try {
+			handle = await subprocess.spawnTerminal({
+				argv: [shell],
+				cwd: workspace.value.processPath,
+				rows,
+				cols,
+				graceMs: settings.terminalGraceMs,
+				signal,
+				env: {
+					TERM: "xterm-256color",
+					COLUMNS: String(cols),
+					LINES: String(rows)
+				}
 			});
 		} catch (error) {
 			return fail$1("spawn-failed", error instanceof Error ? error.message : String(error));
@@ -2154,11 +3172,11 @@ var PanelTerminals = class {
 	* @param request - the handle and the offset already rendered.
 	* @returns the delta and the process state, or a classified failure.
 	*/
-	read(request) {
-		const record = this.records.get(request.terminalId);
-		if (record === void 0) return fail$1("unknown-terminal", `no panel terminal ${request.terminalId}`);
+	read(request$2) {
+		const record = this.records.get(request$2.terminalId);
+		if (record === void 0) return fail$1("unknown-terminal", `no panel terminal ${request$2.terminalId}`);
 		const total = record.base + record.buffer.length;
-		const from = Number.isFinite(request.fromOffset) ? Math.max(0, Math.floor(request.fromOffset)) : 0;
+		const from = Number.isFinite(request$2.fromOffset) ? Math.max(0, Math.floor(request$2.fromOffset)) : 0;
 		const lossy = from < record.base;
 		const text = lossy ? record.buffer : record.buffer.slice(Math.min(from - record.base, record.buffer.length));
 		return {
@@ -2179,12 +3197,12 @@ var PanelTerminals = class {
 	* @param request - the handle and the text to deliver verbatim.
 	* @returns settlement, or a classified failure.
 	*/
-	async write(request) {
-		const record = this.records.get(request.terminalId);
-		if (record === void 0) return fail$1("unknown-terminal", `no panel terminal ${request.terminalId}`);
+	async write(request$2) {
+		const record = this.records.get(request$2.terminalId);
+		if (record === void 0) return fail$1("unknown-terminal", `no panel terminal ${request$2.terminalId}`);
 		if (!record.running) return fail$1("unknown-terminal", `panel terminal ${record.id} has exited`);
 		try {
-			await record.handle.write(request.data);
+			await record.handle.write(request$2.data);
 		} catch (error) {
 			return fail$1("spawn-failed", error instanceof Error ? error.message : String(error));
 		}
@@ -2195,12 +3213,12 @@ var PanelTerminals = class {
 	* @param request - the handle and the signal.
 	* @returns settlement, or a classified failure.
 	*/
-	async signal(request) {
-		const record = this.records.get(request.terminalId);
-		if (record === void 0) return fail$1("unknown-terminal", `no panel terminal ${request.terminalId}`);
+	async signal(request$2) {
+		const record = this.records.get(request$2.terminalId);
+		if (record === void 0) return fail$1("unknown-terminal", `no panel terminal ${request$2.terminalId}`);
 		if (!record.running) return fail$1("unknown-terminal", `panel terminal ${record.id} has exited`);
 		try {
-			await record.handle.signalForeground(request.signal);
+			await record.handle.signalForeground(request$2.signal);
 		} catch {}
 		return { ok: true };
 	}
@@ -2209,9 +3227,9 @@ var PanelTerminals = class {
 	* @param request - the handle.
 	* @returns settlement, or a classified failure.
 	*/
-	async close(request) {
-		const record = this.records.get(request.terminalId);
-		if (record === void 0) return fail$1("unknown-terminal", `no panel terminal ${request.terminalId}`);
+	async close(request$2) {
+		const record = this.records.get(request$2.terminalId);
+		if (record === void 0) return fail$1("unknown-terminal", `no panel terminal ${request$2.terminalId}`);
 		this.records.delete(record.id);
 		await terminateQuietly(record.handle);
 		return { ok: true };
@@ -2346,13 +3364,13 @@ var TaskController = class {
 	* @param request - the owning session and the task id.
 	* @returns what the registry did, or a classified failure.
 	*/
-	async kill(request) {
+	async kill(request$2) {
 		if (!this.source().allowTaskKill) return fail("disabled", "stopping a background task is switched off in the advanced-sidebar settings");
-		const bound = this.bind(request.sessionId, request.taskId);
+		const bound = this.bind(request$2.sessionId, request$2.taskId);
 		if ("failure" in bound) return bound.failure;
 		try {
 			const outcome = bound.jobs.kill(bound.id, bound.agent, "stopped from the DeepSeek Harness sidebar");
-			await this.absorb(request.sessionId, request.taskId);
+			await this.absorb(request$2.sessionId, request$2.taskId);
 			return {
 				ok: true,
 				outcome
@@ -2366,9 +3384,9 @@ var TaskController = class {
 	* @param request - the owning session and the task id.
 	* @returns the accumulated output, or a classified failure.
 	*/
-	async output(request) {
+	async output(request$2) {
 		if (!this.source().showTaskOutput) return fail("disabled", "task output is switched off in the advanced-sidebar settings");
-		const bound = this.bind(request.sessionId, request.taskId);
+		const bound = this.bind(request$2.sessionId, request$2.taskId);
 		if ("failure" in bound) return bound.failure;
 		let snapshot;
 		try {
@@ -2376,20 +3394,20 @@ var TaskController = class {
 		} catch (error) {
 			return fail("unknown-task", error instanceof Error ? error.message : String(error));
 		}
-		const retained = this.collected.get(request.taskId) ?? "";
+		const retained = this.collected.get(request$2.taskId) ?? "";
 		if (isLive(snapshot) || !snapshot.reported) return {
 			ok: true,
-			taskId: request.taskId,
+			taskId: request$2.taskId,
 			readable: retained !== "",
 			text: retained,
 			reason: isLive(snapshot) ? "the task is still running; its output stream belongs to the model until the task settles" : "the task has settled but its completion has not been reported to the model yet"
 		};
-		await this.absorb(request.sessionId, request.taskId);
+		await this.absorb(request$2.sessionId, request$2.taskId);
 		return {
 			ok: true,
-			taskId: request.taskId,
+			taskId: request$2.taskId,
 			readable: true,
-			text: this.collected.get(request.taskId) ?? ""
+			text: this.collected.get(request$2.taskId) ?? ""
 		};
 	}
 	/** Drop retained output. Called from the service's teardown effect. */
@@ -2432,6 +3450,388 @@ var TaskController = class {
 	}
 };
 
+//#endregion
+//#region tsbuild/host/ui-bridge.js
+/**
+* How many commands one panel may have queued without polling.
+*
+* A person presses one button at a time and a model issues one tool call at a time, so a backlog
+* past a handful is a panel that left; the cap is what turns that into a refusal instead of growth.
+*/
+const QUEUE_CAP = 32;
+/**
+* How many console entries are retained per panel.
+*
+* A dev server's client bundle can log per animation frame; the retained window is what a model
+* reads back, and the cursor makes the loss visible rather than silent.
+*/
+const CONSOLE_CAP = 1e3;
+/**
+* How many characters of one console line are kept. */
+const CONSOLE_LINE_CAP = 8192;
+/**
+* The result kind each command kind must answer with.
+*
+* A panel that answered a `dom` command with an `ack` would leave the model reading a sentence where
+* it asked for markup, and nothing else in the chain would notice. The table is what turns that into
+* a reported failure instead of a confusing one, and it is exhaustive over the command union so a
+* new kind cannot be added without deciding what it returns.
+*/
+const EXPECTED_RESULT = {
+	open: "ack",
+	dom: "dom",
+	eval: "eval",
+	console: "console",
+	click: "ack",
+	input: "ack",
+	reload: "ack",
+	resize: "ack",
+	close: "ack"
+};
+/**
+* The command queue, the panel registry, and the console buffer.
+*
+* Held by the Host service and disposed with it, so no timer survives an unload.
+*/
+var PreviewBindings = class {
+	options;
+	panels = /* @__PURE__ */ new Map();
+	/**
+	* Panels that said they were done, so a later bind cannot resurrect them.
+	*
+	* A closed dock's queued work must fail, and "closed" is a fact only the browser knows: without
+	* this, a bind request the Host never asked for would put a dead tab back on the roster and the
+	* model would wait on it. A fresh mount generates a fresh client id, so a reload is unaffected.
+	*/
+	retired = /* @__PURE__ */ new Set();
+	inFlight = /* @__PURE__ */ new Map();
+	closed = false;
+	/**
+	* @param options - reads the current deadlines; called per operation so an edited settings
+	* section reaches the next command with no registration to rebuild.
+	*/
+	constructor(options) {
+		this.options = options;
+	}
+	/** How many panels have polled recently enough to be considered present. */
+	get livePanels() {
+		return [...this.panels.values()].filter((panel) => this.isLive(panel)).length;
+	}
+	/**
+	* Record a panel's state. Called by every poll, so it doubles as the liveness heartbeat.
+	* @param bind - what the panel reported.
+	* @returns the panel's id, for a caller that wants to address it later.
+	*/
+	bind(bind) {
+		const existing = this.panels.get(bind.clientId);
+		if (existing === void 0) {
+			this.panels.set(bind.clientId, {
+				clientId: bind.clientId,
+				sessionId: bind.sessionId,
+				bind,
+				polledAt: this.now(),
+				queue: [],
+				console: [],
+				consoleBase: 0,
+				consoleTotal: 0,
+				controls: []
+			});
+			return bind.clientId;
+		}
+		existing.bind = bind;
+		existing.polledAt = this.now();
+		return bind.clientId;
+	}
+	/**
+	* Take everything queued for one panel.
+	*
+	* The poll is also the heartbeat, so a stale panel is refreshed even when it has no work: what the
+	* tool needs to know is that the tab is alive, not that it is busy.
+	* @param clientId - the panel asking.
+	* @param mounted - whether a preview surface is actually rendered; false leaves the queue alone.
+	* @param console - entries the panel observed since its last report.
+	* @returns the work to execute and the interval after which this poll is stale.
+	*/
+	poll(clientId, mounted, console = []) {
+		const options = this.options();
+		const panel = this.panels.get(clientId);
+		if (panel === void 0) return {
+			message: {
+				commands: [],
+				controls: []
+			},
+			bindTtlMs: options.bindTtlMs
+		};
+		panel.polledAt = this.now();
+		this.appendConsole(panel, console);
+		if (!mounted) {
+			this.dropPanelWork(panel.clientId, "the preview panel is open but shows no preview surface");
+			return {
+				message: {
+					commands: [],
+					controls: []
+				},
+				bindTtlMs: options.bindTtlMs
+			};
+		}
+		const commands = panel.queue.splice(0, panel.queue.length);
+		for (const command of commands) {
+			const record = this.inFlight.get(command.id);
+			if (record !== void 0) record.delivered = true;
+		}
+		return {
+			message: {
+				commands,
+				controls: panel.controls.splice(0, panel.controls.length)
+			},
+			bindTtlMs: options.bindTtlMs
+		};
+	}
+	/**
+	* A panel's state, or the panel itself when it has never reported in.
+	*
+	* This is what lets a tool call wake a dock that has not polled yet — the operator opens the
+	* Preview panel and a model asks for a DOM reading in the same second. Only the FIRST bind is
+	* stored without a poll behind it: once a panel is known, its liveness rules, so a closed tab
+	* cannot be resurrected by a bind request it never sent.
+	* @param bind - what the panel reported.
+	* @returns nothing; the caller polls afterwards.
+	*/
+	bindAt(bind) {
+		if (this.panels.has(bind.clientId) || this.retired.has(bind.clientId)) return;
+		this.bind(bind);
+	}
+	/**
+	* Record what one command did, and append any console lines it carried.
+	*
+	* A result whose command already timed out is accepted and dropped: the deadline fired, the tool
+	* has its answer, and an operator's panel must not be told its report was invalid. A result of the
+	* WRONG KIND is a different matter — it means the two halves disagree about the command, which is
+	* a defect worth reporting rather than a late answer worth ignoring.
+	* @param clientId - the panel reporting.
+	* @param id - the command id.
+	* @param outcome - success with a result, or the reason it failed.
+	* @param console - entries the panel observed alongside the result.
+	* @returns true when the id matched an in-flight command.
+	*/
+	post(clientId, id, outcome, console = []) {
+		const panel = this.panels.get(clientId);
+		if (panel !== void 0) this.appendConsole(panel, console);
+		const record = this.inFlight.get(id);
+		if (record === void 0) return false;
+		if (outcome.ok) {
+			const expected = EXPECTED_RESULT[record.kind];
+			if (outcome.result.kind !== expected) {
+				this.finish(record, {
+					ok: false,
+					error: `the Preview panel answered a ${record.kind} command with a ${outcome.result.kind} result, which this Host cannot read`
+				});
+				return true;
+			}
+		}
+		this.finish(record, outcome);
+		return true;
+	}
+	/**
+	* Forget a panel and fail everything it was holding.
+	* @param clientId - the panel that closed.
+	*/
+	release(clientId) {
+		this.dropPanelWork(clientId, "the preview panel closed before the command finished");
+		if (this.panels.delete(clientId)) this.retired.add(clientId);
+	}
+	/**
+	* Whether one panel is present and able to take a command.
+	* @param clientId - the panel id, or undefined to ask about any panel in a session.
+	* @param sessionId - the session the panel must belong to.
+	* @returns the live panel's id, or undefined.
+	*/
+	active(sessionId, clientId) {
+		return [...this.panels.values()].filter((panel) => this.isLive(panel)).filter((panel) => sessionId === void 0 || panel.sessionId === sessionId).filter((panel) => clientId === void 0 || panel.clientId === clientId).sort((left, right) => right.polledAt - left.polledAt)[0]?.clientId;
+	}
+	/**
+	* The last thing one panel reported about itself.
+	* @param clientId - the panel id.
+	* @returns the bind, or undefined for a panel this Host has not heard from.
+	*/
+	bindOf(clientId) {
+		return this.panels.get(clientId)?.bind;
+	}
+	/**
+	* Queue one command against a live panel and wait for its answer.
+	*
+	* Every path out of here is bounded: a missing panel refuses immediately, a queue that is full
+	* refuses immediately, and a delivered command that is never answered fails on its own deadline.
+	* The one thing this must never do is wait for a browser that is not going to answer.
+	* @param sessionId - the session whose panel should execute it.
+	* @param command - the command body, without its id or its panel.
+	* @returns the result, or the reason there is none.
+	*/
+	async queue(sessionId, command) {
+		if (this.closed) return {
+			ok: false,
+			code: "no-surface",
+			message: "the plugin is unloading"
+		};
+		const clientId = this.active(sessionId);
+		if (clientId === void 0) return {
+			ok: false,
+			code: "no-surface",
+			message: "no Preview panel is open in this session, so there is nothing to inspect. Open the Preview panel first (the session header's Preview entry), then call this tool again."
+		};
+		return this.send(clientId, command);
+	}
+	/**
+	* Queue one command against one known panel, without requiring it to be live.
+	*
+	* Used by `open`, which must be able to hand a mode change to a panel before that panel has had a
+	* chance to poll — the very first call against a freshly opened dock.
+	* @param clientId - the panel id.
+	* @param command - the command body.
+	* @returns the result, or the reason there is none.
+	*/
+	async send(clientId, command) {
+		if (this.closed) return {
+			ok: false,
+			code: "no-surface",
+			message: "the plugin is unloading"
+		};
+		const panel = this.panels.get(clientId);
+		if (panel === void 0) return {
+			ok: false,
+			code: "no-surface",
+			message: "no Preview panel has reported in yet, so there is nothing to inspect"
+		};
+		if (panel.queue.length >= QUEUE_CAP) return {
+			ok: false,
+			code: "no-surface",
+			message: `the Preview panel is not keeping up: ${String(QUEUE_CAP)} commands are already queued and unanswered`
+		};
+		const options = this.options();
+		const timeoutMs = command.timeoutMs ?? options.commandTimeoutMs;
+		const id = randomUUID();
+		const full = {
+			...command,
+			id,
+			clientId,
+			timeoutMs
+		};
+		const outcome = new Promise((resolve$1) => {
+			const timer = setTimeout(() => {
+				const record = this.inFlight.get(id);
+				if (record === void 0) return;
+				this.inFlight.delete(id);
+				resolve$1({
+					ok: false,
+					code: "timeout",
+					message: record.delivered ? `the Preview panel did not answer the ${command.kind} command within ${String(timeoutMs)}ms` : `the Preview panel has not polled for work within ${String(timeoutMs)}ms, so the ${command.kind} command was never delivered`
+				});
+			}, timeoutMs);
+			timer.unref?.();
+			this.inFlight.set(id, {
+				id,
+				kind: command.kind,
+				clientId,
+				sessionId: panel.sessionId,
+				mode: "direct",
+				delivered: false,
+				timer,
+				settle: (result) => {
+					resolve$1(result.ok ? {
+						ok: true,
+						result: result.result
+					} : {
+						ok: false,
+						code: "timeout",
+						message: result.error
+					});
+				}
+			});
+		});
+		panel.queue.push(full);
+		return outcome;
+	}
+	/**
+	* Queue a mode change that needs no answer.
+	* @param clientId - the panel to change.
+	* @param control - what to change.
+	* @returns false when the panel is unknown.
+	*/
+	control(clientId, control) {
+		const panel = this.panels.get(clientId);
+		if (panel === void 0) return false;
+		panel.controls.push(control);
+		return true;
+	}
+	/** Forget every panel and fail everything in flight. Called from the plugin's teardown. */
+	dispose() {
+		this.closed = true;
+		for (const clientId of [...this.panels.keys()]) this.dropPanelWork(clientId, "the plugin is unloading");
+		this.panels.clear();
+		this.retired.clear();
+	}
+	/**
+	* One panel's liveness.
+	* @param panel - the panel.
+	* @returns true when its last poll is inside the trust window.
+	*/
+	isLive(panel) {
+		return this.now() - panel.polledAt <= this.options().bindTtlMs;
+	}
+	/** The configured clock. */
+	now() {
+		return (this.options().now ?? Date.now)();
+	}
+	/**
+	* Append console entries to a panel's window, dropping the oldest past the cap.
+	* @param panel - the panel.
+	* @param entries - entries observed since the last report.
+	*/
+	appendConsole(panel, entries) {
+		for (const entry of entries.slice(0, CONSOLE_CAP)) {
+			panel.console.push({
+				level: entry.level,
+				text: entry.text.length > CONSOLE_LINE_CAP ? `${entry.text.slice(0, CONSOLE_LINE_CAP)}…` : entry.text,
+				at: Number.isFinite(entry.at) ? entry.at : this.now()
+			});
+			panel.consoleTotal += 1;
+		}
+		while (panel.console.length > CONSOLE_CAP) {
+			panel.console.shift();
+			panel.consoleBase += 1;
+		}
+	}
+	/**
+	* Fail every command one panel is holding and drop its queue.
+	* @param clientId - the panel.
+	* @param reason - the sentence the tool reports.
+	*/
+	dropPanelWork(clientId, reason) {
+		const panel = this.panels.get(clientId);
+		if (panel !== void 0) {
+			panel.queue.length = 0;
+			panel.controls.length = 0;
+		}
+		for (const record of [...this.inFlight.values()]) {
+			if (record.clientId !== clientId) continue;
+			this.finish(record, {
+				ok: false,
+				error: reason
+			});
+		}
+	}
+	/**
+	* Resolve one in-flight command and forget it.
+	* @param record - the record.
+	* @param outcome - what to resolve with.
+	*/
+	finish(record, outcome) {
+		this.inFlight.delete(record.id);
+		clearTimeout(record.timer);
+		record.settle(outcome);
+	}
+};
+
 //#endregion
 //#region tsbuild/host/index.js
 /**
@@ -2561,6 +3961,10 @@ let AdvancedSidebarService = (() => {
 	let _previewStart_decorators;
 	let _previewStop_decorators;
 	let _previewLogs_decorators;
+	let _previewFileInfo_decorators;
+	let _previewPoll_decorators;
+	let _previewResult_decorators;
+	let _previewRelease_decorators;
 	let _readFile_decorators;
 	let _openIn_decorators;
 	let _taskKill_decorators;
@@ -2587,6 +3991,10 @@ let AdvancedSidebarService = (() => {
 			_previewStart_decorators = [Remote("previewStart")];
 			_previewStop_decorators = [Remote("previewStop")];
 			_previewLogs_decorators = [Remote("previewLogs")];
+			_previewFileInfo_decorators = [Remote("previewFileInfo")];
+			_previewPoll_decorators = [Remote("previewPoll")];
+			_previewResult_decorators = [Remote("previewResult")];
+			_previewRelease_decorators = [Remote("previewRelease")];
 			_readFile_decorators = [Remote("readFile")];
 			_openIn_decorators = [Remote("openIn")];
 			_taskKill_decorators = [Remote("taskKill")];
@@ -2790,6 +4198,50 @@ let AdvancedSidebarService = (() => {
 				},
 				metadata: _metadata
 			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _previewFileInfo_decorators, {
+				kind: "method",
+				name: "previewFileInfo",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "previewFileInfo" in obj,
+					get: (obj) => obj.previewFileInfo
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _previewPoll_decorators, {
+				kind: "method",
+				name: "previewPoll",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "previewPoll" in obj,
+					get: (obj) => obj.previewPoll
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _previewResult_decorators, {
+				kind: "method",
+				name: "previewResult",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "previewResult" in obj,
+					get: (obj) => obj.previewResult
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
+			__esDecorate(this, null, _previewRelease_decorators, {
+				kind: "method",
+				name: "previewRelease",
+				static: false,
+				private: false,
+				access: {
+					has: (obj) => "previewRelease" in obj,
+					get: (obj) => obj.previewRelease
+				},
+				metadata: _metadata
+			}, null, _instanceExtraInitializers);
 			__esDecorate(this, null, _readFile_decorators, {
 				kind: "method",
 				name: "readFile",
@@ -2863,7 +4315,7 @@ let AdvancedSidebarService = (() => {
 			showArchive: z.boolean().required(),
 			showDelete: z.boolean().required(),
 			showPreview: z.boolean().required(),
-			panelWidth: z.number().step(1).min(280).max(1400).required(),
+			panelWidth: z.number().step(1).min(280).max(960).required(),
 			confirmDelete: z.boolean().required(),
 			deleteMode: z.union(["archive", "purge"]).required(),
 			allowTaskKill: z.boolean().required(),
@@ -2892,7 +4344,11 @@ let AdvancedSidebarService = (() => {
 			maxPreviews: z.number().step(1).min(1).max(16).required(),
 			previewReadyTimeoutMs: z.number().step(1).min(1e3).max(6e5).required(),
 			previewScrollback: z.number().step(1).min(1024).max(4 * 1024 * 1024).required(),
-			previewGraceMs: z.number().step(1).min(100).max(6e4).required()
+			previewGraceMs: z.number().step(1).min(100).max(6e4).required(),
+			previewMaxFileBytes: z.number().step(1).min(1024).max(512 * 1024 * 1024).required(),
+			previewProxyTimeoutMs: z.number().step(1).min(1e3).max(6e5).required(),
+			previewCommandTimeoutMs: z.number().step(1).min(1e3).max(6e5).required(),
+			previewBindTtlMs: z.number().step(1).min(1e3).max(12e4).required()
 		});
 		source = __runInitializers(this, _instanceExtraInitializers);
 		git;
@@ -2902,6 +4358,8 @@ let AdvancedSidebarService = (() => {
 		tasks;
 		deleter;
 		preview;
+		surface;
+		bindings;
 		/**
 		* @param ctx - Host context; every capability this service uses is resolved optionally, so a
 		* deployment missing one still serves a view that explains which panel is dark and why.
@@ -2919,6 +4377,15 @@ let AdvancedSidebarService = (() => {
 			this.tasks = new TaskController(ctx, read);
 			this.deleter = new SessionDeleter(ctx, read);
 			this.preview = new PreviewServers(ctx, read);
+			this.surface = new PreviewSurface(ctx, read);
+			this.bindings = new PreviewBindings(() => {
+				const settings = this.source();
+				return {
+					commandTimeoutMs: settings.previewCommandTimeoutMs,
+					bindTtlMs: settings.previewBindTtlMs
+				};
+			});
+			this.surface.install();
 			installSettingsSection(ctx, ADVANCED_SIDEBAR_SETTINGS_NAMESPACE, AdvancedSidebarService$1.Config, config, {
 				setSource: (current) => {
 					this.source = current;
@@ -2930,6 +4397,8 @@ let AdvancedSidebarService = (() => {
 			});
 			ctx.effect(() => async () => {
 				this.tasks.dispose();
+				this.bindings.dispose();
+				this.surface.dispose();
 				await Promise.all([this.terminals.disposeAll(), this.preview.disposeAll()]);
 			}, "advanced-sidebar: panel terminals, preview servers, retained task output");
 		}
@@ -2946,7 +4415,10 @@ let AdvancedSidebarService = (() => {
 				git: await this.git.describe(signal),
 				terminal: this.terminals.describe(),
 				files: this.files.describe(),
-				preview: this.preview.describe(),
+				preview: {
+					...this.preview.describe(),
+					surface: this.surface.info()
+				},
 				tasks: this.tasks.describe(),
 				openIn: await this.launcher.describe(signal),
 				settings,
@@ -2964,8 +4436,8 @@ let AdvancedSidebarService = (() => {
 		* @param signal - gateway-supplied cancellation for the caller's abandoned request.
 		* @returns the reading, or a classified failure.
 		*/
-		gitStatus(request, signal) {
-			return this.git.status(request, signal);
+		gitStatus(request$2, signal) {
+			return this.git.status(request$2, signal);
 		}
 		/**
 		* Read one path's patch.
@@ -2973,8 +4445,8 @@ let AdvancedSidebarService = (() => {
 		* @param signal - gateway-supplied cancellation for the caller's abandoned request.
 		* @returns the patch, or a classified failure.
 		*/
-		gitDiff(request, signal) {
-			return this.git.diff(request, signal);
+		gitDiff(request$2, signal) {
+			return this.git.diff(request$2, signal);
 		}
 		/**
 		* Stage paths into the index.
@@ -2982,8 +4454,8 @@ let AdvancedSidebarService = (() => {
 		* @param signal - gateway-supplied cancellation for the caller's abandoned request.
 		* @returns the reading after the write, or a classified failure.
 		*/
-		gitStage(request, signal) {
-			return this.git.stage(request, signal);
+		gitStage(request$2, signal) {
+			return this.git.stage(request$2, signal);
 		}
 		/**
 		* Take paths back out of the index, leaving the working tree alone.
@@ -2991,8 +4463,8 @@ let AdvancedSidebarService = (() => {
 		* @param signal - gateway-supplied cancellation for the caller's abandoned request.
 		* @returns the reading after the write, or a classified failure.
 		*/
-		gitUnstage(request, signal) {
-			return this.git.unstage(request, signal);
+		gitUnstage(request$2, signal) {
+			return this.git.unstage(request$2, signal);
 		}
 		/**
 		* Record the staged changes.
@@ -3000,8 +4472,8 @@ let AdvancedSidebarService = (() => {
 		* @param signal - gateway-supplied cancellation; hooks run under `gitCommitTimeoutMs`.
 		* @returns the new commit and the reading after it, or a classified failure.
 		*/
-		gitCommit(request, signal) {
-			return this.git.commit(request, signal);
+		gitCommit(request$2, signal) {
+			return this.git.commit(request$2, signal);
 		}
 		/**
 		* Send the current branch's commits to its remote.
@@ -3009,8 +4481,8 @@ let AdvancedSidebarService = (() => {
 		* @param signal - gateway-supplied cancellation; the network wait runs under `gitPushTimeoutMs`.
 		* @returns the push and the reading after it, or a classified failure.
 		*/
-		gitPush(request, signal) {
-			return this.git.push(request, signal);
+		gitPush(request$2, signal) {
+			return this.git.push(request$2, signal);
 		}
 		/**
 		* Ask the deployment's own model to write a commit message for what is staged.
@@ -3018,8 +4490,8 @@ let AdvancedSidebarService = (() => {
 		* @param signal - gateway-supplied cancellation for the readings and the model call.
 		* @returns the drafted message, or a classified failure.
 		*/
-		gitCommitMessage(request, signal) {
-			return this.git.draftCommitMessage(request, signal);
+		gitCommitMessage(request$2, signal) {
+			return this.git.draftCommitMessage(request$2, signal);
 		}
 		/**
 		* Allocate a panel terminal.
@@ -3027,40 +4499,40 @@ let AdvancedSidebarService = (() => {
 		* @param signal - gateway-supplied cancellation of the allocation.
 		* @returns the handle, or a classified failure.
 		*/
-		terminalOpen(request, signal) {
-			return this.terminals.open(request, signal);
+		terminalOpen(request$2, signal) {
+			return this.terminals.open(request$2, signal);
 		}
 		/**
 		* Read a panel terminal's output from a caller-owned offset.
 		* @param request - the handle and the offset already rendered.
 		* @returns the delta and the process state, or a classified failure.
 		*/
-		terminalRead(request) {
-			return Promise.resolve(this.terminals.read(request));
+		terminalRead(request$2) {
+			return Promise.resolve(this.terminals.read(request$2));
 		}
 		/**
 		* Send keystrokes to a panel terminal.
 		* @param request - the handle and the text to deliver verbatim.
 		* @returns settlement, or a classified failure.
 		*/
-		terminalWrite(request) {
-			return this.terminals.write(request);
+		terminalWrite(request$2) {
+			return this.terminals.write(request$2);
 		}
 		/**
 		* Deliver a signal to a panel terminal's foreground process group.
 		* @param request - the handle and the signal.
 		* @returns settlement, or a classified failure.
 		*/
-		terminalSignal(request) {
-			return this.terminals.signal(request);
+		terminalSignal(request$2) {
+			return this.terminals.signal(request$2);
 		}
 		/**
 		* Close a panel terminal.
 		* @param request - the handle.
 		* @returns settlement, or a classified failure.
 		*/
-		terminalClose(request) {
-			return this.terminals.close(request);
+		terminalClose(request$2) {
+			return this.terminals.close(request$2);
 		}
 		/**
 		* List one directory level for the Files panel.
@@ -3068,8 +4540,8 @@ let AdvancedSidebarService = (() => {
 		* @param signal - gateway-supplied cancellation for the caller's abandoned request.
 		* @returns the level, or a classified failure.
 		*/
-		listEntries(request, signal) {
-			return this.files.list(request, signal);
+		listEntries(request$2, signal) {
+			return this.files.list(request$2, signal);
 		}
 		/**
 		* List one workspace's preview launch configurations, each with its current state.
@@ -3077,8 +4549,8 @@ let AdvancedSidebarService = (() => {
 		* @param signal - gateway-supplied cancellation for the caller's abandoned request.
 		* @returns the list, or a classified failure.
 		*/
-		previewList(request, signal) {
-			return this.preview.list(request, signal);
+		previewList(request$2, signal) {
+			return this.preview.list(request$2, signal);
 		}
 		/**
 		* Start one preview configuration.
@@ -3086,24 +4558,84 @@ let AdvancedSidebarService = (() => {
 		* @param signal - gateway-supplied cancellation of the start.
 		* @returns the started row, or a classified failure.
 		*/
-		previewStart(request, signal) {
-			return this.preview.start(request, signal);
+		previewStart(request$2, signal) {
+			return this.preview.start(request$2, signal);
 		}
 		/**
 		* Stop one running preview server.
 		* @param request - the handle.
 		* @returns settlement, or a classified failure.
 		*/
-		previewStop(request) {
-			return this.preview.stop(request);
+		previewStop(request$2) {
+			return this.preview.stop(request$2);
 		}
 		/**
 		* Read one preview server's output from a caller-owned offset, with its state at read time.
 		* @param request - the handle and the offset already rendered.
 		* @returns the delta and the state, or a classified failure.
 		*/
-		previewLogs(request) {
-			return Promise.resolve(this.preview.logs(request));
+		previewLogs(request$2) {
+			return Promise.resolve(this.preview.logs(request$2));
+		}
+		/**
+		* Describe one workspace file for the Preview panel's Files mode.
+		*
+		* Separate from `readFile`, which returns text for the Files panel's reader: a preview needs the
+		* kind, the size, the same-origin URL, and a change token, and it must not pull a 200 MB video
+		* through the wire to find out what it is.
+		* @param request - the workspace and the file inside it.
+		* @param signal - gateway-supplied cancellation for the resolution and metadata reads.
+		* @returns the file's kind and frame URL, or a classified failure.
+		*/
+		previewFileInfo(request$2, signal) {
+			return this.surface.info_(request$2.workspacePath, request$2.path, signal);
+		}
+		/**
+		* Register one Preview panel and take whatever the agent queued for it.
+		*
+		* This is the polling half of the agent channel: the browser calls it while a preview is mounted,
+		* the call is the panel's liveness heartbeat, and its answer carries the commands to execute.
+		* @param request - which panel, where it is, and whether a preview is actually rendered.
+		* @returns the work to do, or a classified failure.
+		*/
+		previewPoll(request$2) {
+			if (request$2.mounted) this.bindings.bind(request$2.bind);
+			else this.bindings.bindAt(request$2.bind);
+			this.surface.rememberTarget(request$2.clientId, request$2.bind.inspectable ? request$2.bind.url : void 0);
+			const polled = this.bindings.poll(request$2.clientId, request$2.mounted);
+			return Promise.resolve({
+				ok: true,
+				message: polled.message,
+				bindTtlMs: polled.bindTtlMs
+			});
+		}
+		/**
+		* Record what one command did.
+		* @param request - the panel, the command id, and the outcome.
+		* @returns settlement.
+		*/
+		previewResult(request$2) {
+			this.bindings.post(request$2.clientId, request$2.id, request$2.ok ? request$2.result === void 0 ? {
+				ok: false,
+				error: "the panel reported success without a result"
+			} : {
+				ok: true,
+				result: request$2.result
+			} : {
+				ok: false,
+				error: request$2.error ?? "the panel reported a failure with no reason"
+			}, request$2.console ?? []);
+			return Promise.resolve({ ok: true });
+		}
+		/**
+		* Say that one panel is gone, so its queued work is dropped and its waits fail now.
+		* @param request - the panel that closed.
+		* @returns settlement.
+		*/
+		previewRelease(request$2) {
+			this.bindings.release(request$2.clientId);
+			this.surface.rememberTarget(request$2.clientId, void 0);
+			return Promise.resolve({ ok: true });
 		}
 		/**
 		* Read one file for the Files panel preview.
@@ -3111,8 +4643,8 @@ let AdvancedSidebarService = (() => {
 		* @param signal - gateway-supplied cancellation for the caller's abandoned request.
 		* @returns the preview, or a classified failure.
 		*/
-		readFile(request, signal) {
-			return this.files.read(request, signal);
+		readFile(request$2, signal) {
+			return this.files.read(request$2, signal);
 		}
 		/**
 		* Hand one path to an external application or to the operating system's file manager.
@@ -3120,36 +4652,157 @@ let AdvancedSidebarService = (() => {
 		* @param signal - gateway-supplied cancellation for the launch.
 		* @returns settlement, or a classified failure.
 		*/
-		openIn(request, signal) {
-			return this.launcher.open(request, signal);
+		openIn(request$2, signal) {
+			return this.launcher.open(request$2, signal);
 		}
 		/**
 		* Stop one live background task.
 		* @param request - the owning session and the task id.
 		* @returns what the registry did, or a classified failure.
 		*/
-		taskKill(request) {
-			return this.tasks.kill(request);
+		taskKill(request$2) {
+			return this.tasks.kill(request$2);
 		}
 		/**
 		* Read one settled background task's output.
 		* @param request - the owning session and the task id.
 		* @returns the accumulated output, or a classified failure.
 		*/
-		taskOutput(request) {
-			return this.tasks.output(request);
+		taskOutput(request$2) {
+			return this.tasks.output(request$2);
 		}
 		/**
-		* Delete one session: archive it, and remove its durable artifact when the mode and Host allow.
+		* Delete one session: archive it, and report plainly that a configured purge did not happen.
 		* @param request - the session to delete.
-		* @param signal - gateway-supplied cancellation for the persistence listing.
 		* @returns what was actually done, or a classified failure.
 		*/
-		deleteSession(request, signal) {
-			return this.deleter.delete(request, signal);
+		deleteSession(request$2) {
+			return this.deleter.delete(request$2);
+		}
+		/**
+		* Queue one command against the session's Preview panel and wait for its answer.
+		* @param sessionId - the session whose panel should execute it.
+		* @param body - the command, without its id, panel, or deadline.
+		* @returns the result, or a sentence explaining why there is none.
+		*/
+		queueCommand(sessionId, body) {
+			return this.bindings.queue(sessionId, {
+				...body,
+				timeoutMs: this.source().previewCommandTimeoutMs
+			});
+		}
+		/**
+		* Point the session's panel at a URL.
+		*
+		* The panel decides for itself how to frame it — a loopback URL goes through this Host's proxy and
+		* becomes inspectable, anything else is framed cross-origin and is not — so the answer says which
+		* happened rather than the tool guessing.
+		* @param sessionId - the session whose panel should show it.
+		* @param url - the absolute `http(s)` URL, already validated by the caller.
+		* @param waitMs - how long the panel may take to mount and load.
+		* @returns the outcome and what the panel is now framing.
+		*/
+		async openUrl(sessionId, url, waitMs) {
+			const clientId = this.bindings.active(sessionId);
+			if (clientId === void 0) return {
+				ok: false,
+				message: NO_SURFACE
+			};
+			if (!this.bindings.control(clientId, {
+				control: "open",
+				open: {
+					clientId,
+					mode: "url",
+					url
+				}
+			})) return {
+				ok: false,
+				message: NO_SURFACE
+			};
+			const sameOrigin = validateProxyTarget(url).ok;
+			const outcome = await this.bindings.send(clientId, {
+				kind: "open",
+				timeoutMs: waitMs
+			});
+			if (!outcome.ok) return {
+				ok: false,
+				message: outcome.message
+			};
+			return {
+				ok: true,
+				message: sameOrigin ? `The Preview panel is loading ${url} through this Host's same-origin proxy, so its DOM, console and events are all inspectable.` : `The Preview panel is showing ${url}. It is not a loopback URL, so the frame stays cross-origin and cannot be inspected: dom, eval, click and type will refuse it.`,
+				detail: {
+					url,
+					inspectable: sameOrigin,
+					...sameOrigin ? { proxyRoute: PROXY_ROUTE } : {}
+				}
+			};
+		}
+		/**
+		* Point the session's panel at one workspace file.
+		* @param request - the session, the workspace, the file, its kind, and the wait budget.
+		* @returns the outcome and where the panel is now framed from.
+		*/
+		async openFile(request$2) {
+			const clientId = this.bindings.active(request$2.sessionId);
+			if (clientId === void 0) return {
+				ok: false,
+				message: NO_SURFACE
+			};
+			if (!this.bindings.control(clientId, {
+				control: "open",
+				open: {
+					clientId,
+					mode: "file",
+					filePath: request$2.filePath,
+					workspacePath: request$2.workspacePath
+				}
+			})) return {
+				ok: false,
+				message: NO_SURFACE
+			};
+			const framed = this.surface.info().available;
+			if (request$2.kind !== "iframe" && request$2.kind !== "markdown" && !framed) return {
+				ok: false,
+				message: `${request$2.filePath} is a ${request$2.kind} file, and this Host composes no web server, so there is no same-origin URL to frame it from`
+			};
+			const outcome = await this.bindings.send(clientId, {
+				kind: "open",
+				timeoutMs: request$2.waitMs
+			});
+			if (!outcome.ok) return {
+				ok: false,
+				message: outcome.message
+			};
+			const url = this.surface.fileUrl(request$2.workspacePath, request$2.filePath);
+			return {
+				ok: true,
+				message: `The Preview panel is showing ${request$2.filePath} (${request$2.kind})${request$2.kind === "iframe" ? " as a live document" : ""}; its DOM is same-origin and inspectable.`,
+				detail: {
+					path: request$2.filePath,
+					kind: request$2.kind,
+					...url === void 0 ? {} : { url }
+				}
+			};
+		}
+		/**
+		* Read one workspace file's preview description, for the tool's own `open` validation.
+		* @param request - the workspace and the file.
+		* @param signal - cancellation for the reads.
+		* @returns the description, or a classified failure.
+		*/
+		describeFile(request$2, signal) {
+			return this.surface.info_(request$2.workspacePath, request$2.path, signal);
 		}
 	};
 })();
+/**
+* The refusal a tool call gets when no Preview panel is open in its session.
+*
+* A constant rather than a method: it is the same sentence for every action, and a model that reads
+* it twice should read the same thing twice.
+*/
+const NO_SURFACE = "no Preview panel is open in this session, so there is nothing to inspect. Open the Preview panel first (the session header's Preview entry), then call this tool again.";
 var host_default = AdvancedSidebarService;
 
 //#endregion