@exagone313/dsh-podman 0.2.0-rc.3 → 0.2.0

package/dist/workspace-binding.test.js

@@ -10,9 +10,22 @@ import { dirname, resolve } from "node:path";
 import { tmpdir } from "node:os";
 import { mkdirSync } from "node:fs";
 import { controlClient, guestClient } from "./grpc/runtime-client.js";
-import { workspaceSlug, metadata, WorkspaceResolver, containerRowFor, containerNotFound, normalizeToolError, } from "./workspace-binding.js";
+import { containerNotFound, metadata, normalizeToolError, WorkspaceResolver, workspaceSlug, } from "./workspace-binding.js";
+import { VERSION } from "./generated/version.js";
 const SLUG = "2c573001-4171-4900-904b-12a5cc02737a";
 const SLUG_SUB = "3d684112-5282-4a11-a15c-23b6dd13848b";
+test("normalizeToolError strips the prefix only for a gRPC status", () => {
+    const statusError = Object.assign(new Error("5 NOT_FOUND: missing"), {
+        code: 5,
+    });
+    const normalized = normalizeToolError(statusError);
+    assert.equal(normalized.message, "missing");
+    assert.equal(normalized.code, "NOT_FOUND");
+    // A plain message that merely looks like a status keeps its text.
+    const plain = normalizeToolError(new Error("5 NOT_FOUND: missing"));
+    assert.equal(plain.message, "5 NOT_FOUND: missing");
+    assert.equal(plain.code, undefined);
+});
 test("workspaceSlug accepts a UUID workspace id", () => {
     assert.equal(workspaceSlug(SLUG), SLUG);
     assert.equal(workspaceSlug(SLUG.toUpperCase()), SLUG);
@@ -44,6 +57,12 @@ test("metadata omits the header when the token is empty", () => {
     assert.ok(result instanceof grpc.Metadata);
     assert.equal(result.get("authorization").length, 0);
 });
+test("metadata carries the plugin version only when one is given", () => {
+    const withVersion = metadata("token-1", "1.2.3");
+    assert.equal(withVersion.get("x-dsh-podman-plugin-version")[0], "1.2.3");
+    // Guest calls pass no version, and the guest agent does not check it.
+    assert.equal(metadata("token-1").get("x-dsh-podman-plugin-version").length, 0);
+});
 test("normalizeToolError strips the grpc prefix and names the code", () => {
     const prefixed = Object.assign(new Error("5 NOT_FOUND: container not found"), { code: 5 });
     const normalized = normalizeToolError(prefixed);
@@ -52,7 +71,9 @@ test("normalizeToolError strips the grpc prefix and names the code", () => {
     const plain = normalizeToolError(new Error("boom"));
     assert.equal(plain.message, "boom");
     assert.equal(plain.code, undefined);
-    const named = Object.assign(new Error("bad input"), { code: "INVALID_ARGUMENT" });
+    const named = Object.assign(new Error("bad input"), {
+        code: "INVALID_ARGUMENT",
+    });
     assert.equal(normalizeToolError(named).code, "INVALID_ARGUMENT");
 });
 test("containerNotFound reports one stable shape", () => {
@@ -60,25 +81,6 @@ test("containerNotFound reports one stable shape", () => {
     assert.equal(containerNotFound("db").code, "NOT_FOUND");
     assert.equal(containerNotFound("db").message, 'container "db" not found');
 });
-test("containerRowFor finds rows by workspace and name", () => {
-    const containers = [
-        { workspaceSlug: "team-app", containerName: "default", status: "running" },
-        { workspaceSlug: "team-app", containerName: "db", status: "stopped" },
-        { workspaceSlug: "other", containerName: "db", status: "running" },
-    ];
-    assert.deepEqual(containerRowFor(containers, "team-app", "db"), {
-        workspaceSlug: "team-app",
-        containerName: "db",
-        status: "stopped",
-    });
-    assert.deepEqual(containerRowFor(containers, "team-app", "default"), {
-        workspaceSlug: "team-app",
-        containerName: "default",
-        status: "running",
-    });
-    assert.equal(containerRowFor(containers, "team-app", "missing"), undefined);
-    assert.equal(containerRowFor([], "team-app", "default"), undefined);
-});
 test("control and guest proto files resolve next to the runtime", () => {
     const control = controlClient("/tmp/dsh-proto-control.sock");
     const guest = guestClient("/tmp/dsh-proto-guest.sock");
@@ -93,20 +95,60 @@ async function startControlServer(containers = [], options = {}) {
         defaults: true,
     });
     const loaded = grpc.loadPackageDefinition(definition);
+    const guestDefinition = loader.loadSync(resolve(dirname(fileURLToPath(import.meta.url)), "grpc/proto/dshguest/v1/guest.proto"), { longs: String, enums: String, defaults: true });
+    const guestLoaded = grpc.loadPackageDefinition(guestDefinition);
     const server = new grpc.Server();
+    // With staleToken, the first container row carries a credential the agent
+    // rejects, so the caller must refresh before it can proceed.
+    let ensureCalls = 0;
+    server.addService(guestLoaded.dshguest.v1.WorkspaceGuestAgent.service, {
+        ping: (call, callback) => {
+            const bearer = String(call.metadata.get("authorization")[0] ?? "");
+            if (bearer === "bearer stale") {
+                callback({
+                    code: grpc.status.UNAUTHENTICATED,
+                    details: "invalid agent token",
+                });
+                return;
+            }
+            callback(null, { version: "test", commit: "test" });
+        },
+    });
     const received = [];
+    const versions = [];
     const createRequests = [];
     const recreateRequests = [];
     server.addService(loaded.dshctl.v1.OrchestratorControl.service, {
         listWorkspaces: (call, callback) => {
             received.push(call.metadata.get("authorization")[0]);
+            versions.push(call.metadata.get("x-dsh-podman-plugin-version")[0]);
             callback(null, { workspaces: [] });
         },
         describeWorkspace: (_call, callback) => {
             callback({ code: grpc.status.NOT_FOUND, details: "workspace not found" });
         },
-        listContainers: (_call, callback) => {
-            callback(null, { containers });
+        ensureContainer: (call, callback) => {
+            const agentToken = options.staleToken === true && ensureCalls++ === 0
+                ? "stale"
+                : "tok";
+            const row = containers.find((candidate) => candidate.workspaceSlug === call.request.workspaceSlug &&
+                candidate.containerName === call.request.container);
+            if (row !== undefined) {
+                callback(null, { ...row, agentToken });
+                return;
+            }
+            if (call.request.container === "default") {
+                // The default container createWorkspace just made.
+                callback(null, {
+                    workspaceSlug: call.request.workspaceSlug,
+                    containerName: "default",
+                    agentSocketPath: resolve(socketsRoot, "guest.sock"),
+                    agentToken,
+                    mounts: [],
+                });
+                return;
+            }
+            callback({ code: grpc.status.NOT_FOUND, details: "container not found" });
         },
         createWorkspace: (call, callback) => {
             createRequests.push(call.request);
@@ -120,6 +162,12 @@ async function startControlServer(containers = [], options = {}) {
             recreateRequests.push(call.request);
             callback(null, { workspaceSlug: call.request.workspaceSlug });
         },
+        addContainerMount: (_call, callback) => {
+            callback(null, {});
+        },
+        removeWorkspace: (_call, callback) => {
+            callback(null, {});
+        },
     });
     const socketsRoot = resolve(tmpdir(), `dsh-control-test-${process.pid}-${Date.now()}-${Math.random()}`);
     mkdirSync(socketsRoot, { recursive: true });
@@ -139,13 +187,14 @@ async function startControlServer(containers = [], options = {}) {
     return {
         socketsRoot,
         received,
+        versions,
         createRequests,
         recreateRequests,
         stop: () => server.forceShutdown(),
     };
 }
 test("control calls carry the bearer token", async () => {
-    const { socketsRoot, received, stop } = await startControlServer();
+    const { socketsRoot, received, versions, stop } = await startControlServer();
     try {
         const resolver = new WorkspaceResolver({
             socketsRoot,
@@ -155,13 +204,14 @@ test("control calls carry the bearer token", async () => {
         }, undefined);
         await resolver.control("listWorkspaces", {});
         assert.equal(received[0], "bearer tok-1");
+        assert.equal(versions[0], VERSION, "control calls report the plugin version");
     }
     finally {
         stop();
     }
 });
 test("control calls omit the token when unset", async () => {
-    const { socketsRoot, received, stop } = await startControlServer();
+    const { socketsRoot, received, versions, stop } = await startControlServer();
     try {
         const resolver = new WorkspaceResolver({
             socketsRoot,
@@ -215,6 +265,60 @@ test("resolve exposes the session directory as the default cwd", async () => {
         stop();
     }
 });
+test("resolve refreshes a binding whose token the agent rejects", async () => {
+    // The first row carries a credential the guest agent rejects; resolving must
+    // re-run the orchestrator's ensure and end with the usable token.
+    const { socketsRoot, stop } = await startControlServer([], {
+        staleToken: true,
+    });
+    try {
+        const resolver = new WorkspaceResolver({
+            socketsRoot,
+            defaultImage: "arch",
+            projectsRoot: "/projects",
+            controlToken: "",
+        }, { resolveByPath: () => ({ id: SLUG, path: "/projects/team" }) });
+        const binding = await resolver.resolve("/projects/team");
+        assert.equal(binding.token, "tok");
+    }
+    finally {
+        stop();
+    }
+});
+test("the auto-created workspace seeds the default environment", async () => {
+    const { socketsRoot, createRequests, stop } = await startControlServer();
+    try {
+        const resolver = new WorkspaceResolver({
+            socketsRoot,
+            defaultImage: "arch",
+            projectsRoot: "/projects",
+            controlToken: "",
+            containerEnv: { GIT_AUTHOR_NAME: "John Doe" },
+        }, { resolveByPath: () => ({ id: SLUG, path: "/projects/team" }) });
+        await resolver.resolve("/projects/team");
+        assert.equal(createRequests.length, 1);
+        assert.deepEqual(createRequests[0].env, { GIT_AUTHOR_NAME: "John Doe" });
+    }
+    finally {
+        stop();
+    }
+});
+test("the auto-created workspace omits env without defaults", async () => {
+    const { socketsRoot, createRequests, stop } = await startControlServer();
+    try {
+        const resolver = new WorkspaceResolver({
+            socketsRoot,
+            defaultImage: "arch",
+            projectsRoot: "/projects",
+            controlToken: "",
+        }, { resolveByPath: () => ({ id: SLUG, path: "/projects/team" }) });
+        await resolver.resolve("/projects/team");
+        assert.deepEqual(createRequests[0].env, {});
+    }
+    finally {
+        stop();
+    }
+});
 test("containerBinding exposes the session directory only when a project mount covers it", async () => {
     const mounted = await startControlServer([{
             workspaceSlug: SLUG,
@@ -241,7 +345,11 @@ test("containerBinding exposes the session directory only when a project mount c
             containerName: "db",
             agentSocketPath: "/run/x.sock",
             agentToken: "tok",
-            mounts: [{ kind: "MOUNT_KIND_VOLUME", volume: "data", destination: "/data" }],
+            mounts: [{
+                    kind: "MOUNT_KIND_VOLUME",
+                    volume: "data",
+                    destination: "/data",
+                }],
         }]);
     try {
         const resolver = new WorkspaceResolver({
@@ -257,6 +365,72 @@ test("containerBinding exposes the session directory only when a project mount c
         unmounted.stop();
     }
 });
+test("containerBinding re-resolves the mount set after a container mutation", async () => {
+    const rows = [
+        {
+            workspaceSlug: SLUG,
+            containerName: "db",
+            agentSocketPath: "/run/x.sock",
+            agentToken: "tok",
+            mounts: [{ kind: "MOUNT_KIND_PROJECT", projectName: "team" }],
+        },
+    ];
+    const control = await startControlServer(rows);
+    try {
+        const resolver = new WorkspaceResolver({
+            socketsRoot: control.socketsRoot,
+            defaultImage: "arch",
+            projectsRoot: "/projects",
+            controlToken: "",
+        }, { resolveByPath: () => ({ id: SLUG, path: "/projects/team" }) });
+        const first = await resolver.containerBinding("/projects/team", "db");
+        assert.equal(first.defaultCwd, "/projects/team");
+        // The container no longer mounts the session directory, but the cached
+        // entry still describes the row it was built from.
+        rows[0].mounts = [
+            { kind: "MOUNT_KIND_VOLUME", volume: "data", destination: "/data" },
+        ];
+        const stale = await resolver.containerBinding("/projects/team", "db");
+        assert.equal(stale.defaultCwd, "/projects/team", "the cache is served until it is invalidated");
+        await resolver.control("addContainerMount", {
+            workspaceSlug: SLUG,
+            container: "db",
+        });
+        const fresh = await resolver.containerBinding("/projects/team", "db");
+        assert.equal(fresh.defaultCwd, undefined, "a mutation re-resolves the mount set");
+    }
+    finally {
+        control.stop();
+    }
+});
+test("removing a workspace drops every cached container binding", async () => {
+    const rows = [
+        {
+            workspaceSlug: SLUG,
+            containerName: "db",
+            agentSocketPath: "/run/x.sock",
+            agentToken: "tok",
+            mounts: [{ kind: "MOUNT_KIND_PROJECT", projectName: "team" }],
+        },
+    ];
+    const control = await startControlServer(rows);
+    try {
+        const resolver = new WorkspaceResolver({
+            socketsRoot: control.socketsRoot,
+            defaultImage: "arch",
+            projectsRoot: "/projects",
+            controlToken: "",
+        }, { resolveByPath: () => ({ id: SLUG, path: "/projects/team" }) });
+        await resolver.containerBinding("/projects/team", "db");
+        rows[0].mounts = [];
+        await resolver.control("removeWorkspace", { workspaceSlug: SLUG });
+        const fresh = await resolver.containerBinding("/projects/team", "db");
+        assert.equal(fresh.defaultCwd, undefined);
+    }
+    finally {
+        control.stop();
+    }
+});
 test("containerBinding recreates a container whose agent never answers", async () => {
     const control = await startControlServer([{
             workspaceSlug: SLUG,
@@ -320,7 +494,8 @@ test("resolveForPath rejects paths it cannot map to a workspace", async () => {
     // A path outside every workspace is not in any container's filesystem: it is
     // reported with the harness's missing-path code so callers treat it as absent
     // (agent-instructions walks ancestors above the workspace this way).
-    await assert.rejects(() => resolver.resolveForPath("/elsewhere/file", undefined), (error) => error instanceof Error && error.code === "FS_NOT_FOUND");
+    await assert.rejects(() => resolver.resolveForPath("/elsewhere/file", undefined), (error) => error instanceof Error &&
+        error.code === "FS_NOT_FOUND");
 });
 test("resolve rejects a missing cwd without stringifying it", async () => {
     const resolver = new WorkspaceResolver({

package/docs/architecture.md

@@ -24,9 +24,22 @@ The plugin connects to the orchestrator over a Unix socket at
 `<socketsRoot>/orchestrator.sock` and talks gRPC. Requests carry the shared
 token (`DSH_PODMAN_ORCHESTRATOR_TOKEN`) as an `authorization: bearer` header.
 
+Requests also carry the plugin's version in an `x-dsh-podman-plugin-version`
+header. The plugin and the orchestrator are deployed separately (an npm package
+inside the dsh image, and this binary), so the orchestrator refuses a control
+call from a plugin whose **major** version differs, naming both versions and
+which side is behind — an out-of-sync deployment fails loudly instead of being
+misread. A missing or unparseable version is refused as well. A minor or patch
+difference is compatible: the call proceeds, the orchestrator logs it once per
+plugin version, and the Podman page shows it. `GetVersion` is exempt from the
+check, so a plugin can always learn the orchestrator's version.
+
 The orchestrator service exposes these gRPC methods (backing both the UI and the
 tools): `ListContainers` (returns only the guest containers the orchestrator
 created — containers it does not own are never exposed),
+`EnsureContainer{workspace_slug, container}` (the single attach path: returns
+the named container, recreating it first when it is missing, stopped, or running
+an outdated guest agent),
 `StartContainer{workspace_slug, container, image_id, mounts, env, secret_env,
 paths}`
 (creates or replaces a container in the workspace's pod; an empty `container`
@@ -35,8 +48,11 @@ targets the default container and other names are validated),
 (stops, removes, and recreates a container, optionally with a new image, project
 mounts, environment, or PATH additions; an empty `image_id` keeps the
 workspace's current image), `RemoveContainer`, `AddContainerMount`,
-`RemoveContainerMount`, `SetContainerPaths`, `AddContainerSecret`, and
-`RemoveContainerSecret`.
+`UpdateContainerMount`, `RemoveContainerMount`, `SetContainerPaths`,
+`AddContainerSecret`, and `RemoveContainerSecret`. The service also exposes the
+workspace, volume, secret, image (build, rebuild, remove and base-image pull),
+and cache (list and clean) operations that back the Podman page, plus
+`GetVersion`.
 
 ## Workspaces and pods
 
@@ -55,10 +71,10 @@ model reads the artifact back with the container file tools instead of a host
 path the container cannot reach.
 
 A workspace's pod is torn down when its last container is removed, or directly
-through `RemoveWorkspace` (the settings card's **Remove pod** action), which
-stops the containers' daemons, removes the pod and its containers, cleans their
-socket directories, and drops the stored workspace. Volumes, secrets, and
-project data are left untouched.
+through `RemoveWorkspace` (the Podman page's **Remove pod** action), which stops
+the containers' daemons, removes the pod and its containers, cleans their socket
+directories, and drops the stored workspace. Volumes, secrets, and project data
+are left untouched.
 
 Beyond project mounts, a container can mount named volumes (prefixed
 `DSH_PODMAN_VOLUME_PREFIX`, default `dsh-podman-`, and auto-created by podman on
@@ -101,6 +117,13 @@ and writes files. Each guest container gets exactly one socket directory
 bind-mounted into it, so a guest never sees the orchestrator's control socket
 nor any other workspace's socket directory.
 
+The guest API exposes no watcher, so the plugin's `ctx.fs` provider reports
+`FS_IO_ERROR` (`Filesystem watching is not supported by this provider.`) for
+`watch`. The harness's workspace-file change stream therefore answers
+`workspace-file/watch-unsupported`, and the browser's file tree refreshes on
+demand instead of live — the same stance the harness's SSH filesystem provider
+takes for a remote path.
+
 Commands and daemons inherit the guest agent's environment, minus the reserved
 `DSH_PODMAN` namespace: the agent's own token stays with the agent instead of
 being copied into everything it starts. A daemon started with `inheritEnv=false`
@@ -145,20 +168,22 @@ Containerfile, so a build writes nothing to the orchestrator's state directory.
 from a public registry per `DSH_PODMAN_BASE_IMAGE_PREFIX`), then rebuilds the
 stored custom images **in dependency order** — each parent before the images
 derived from it. An image whose rebuild fails, and every image that depends on
-it, is reported in `skipped` while the rest continue.
+it, is reported in `skipped` while the rest continue. A base image the call
+could not build or pull is reported there too, by its short name; `rebuilt`
+lists only the custom images, so it never names a base the call had to ensure.
 
 When a host cache is configured (`DSH_PODMAN_HOST_*_CACHE`, mounted into both
 the build container and the orchestrator), builds reuse downloaded packages. The
-settings card reports each cache's size and can clean it — keep the newest
-version of every package, or empty the cache. The builder serializes a cleanup
-against builds with a read/write lock, so a cleanup never deletes a package out
-from under a running build.
+Podman page reports each cache's size and can clean it — keep the newest version
+of every package, or empty the cache. The builder serializes a cleanup against
+builds with a read/write lock, so a cleanup never deletes a package out from
+under a running build.
 
-## Settings card transport
+## Podman page transport
 
-The card talks to the host over one authenticated fetch route below the harness
-API path (`/api/podman/card`), registered on the connection service so the
-carrier applies its Host/Origin fence and browser authentication first:
+The Podman page talks to the host over one authenticated fetch route below the
+harness API path (`/api/podman/card`), registered on the connection service so
+the carrier applies its Host/Origin fence and browser authentication first:
 
 - `GET` returns the live orchestrator snapshot (containers, images, workspaces,
   volumes, secrets, caches), built fresh on every request.
@@ -166,8 +191,34 @@ carrier applies its Host/Origin fence and browser authentication first:
   `image_rebuild` / `image_rebuild_all` / volume / secret / secret-env / mount
   ops) against the orchestrator and returns the notice to show.
 
-The settings namespace therefore holds **only real preferences**: the default
-image, the sockets root, and the card's active locale (`uiLocale`, so the host
-can render approval text in the session language — see
-[Approval](usage.md#approval)). Nothing derived from the orchestrator is
-persisted, and no command round-trips through the settings document.
+The plugin's own config therefore holds **only real preferences**: the default
+image, the default environment, and the page's active locale (`uiLocale`, so the
+host can render approval text in the session language — see
+[Approval](usage.md#approval)). They are volatile fields, so an edit applies
+without reloading the plugin. Nothing derived from the orchestrator is
+persisted, and no command round-trips through the config document.
+
+## Podman terminal transport
+
+The Podman terminal tab talks to guest ptys through its own authenticated routes
+on the same connection service (`/api/podman/terminal`,
+`/api/podman/terminal/shells`, `/api/podman/terminal/retained`). The open route
+streams newline-delimited JSON frames (ready, snapshot, base64 output, title,
+exit, error, detached) and takes control requests (input, resize, rename, close)
+over a POST; the carrier applies the same Host/Origin fence and browser
+authentication as the card route.
+
+Each terminal is keyed by `(sessionId, tabId)` and retained by the host: the
+guest pty stays alive while no browser is attached, and every chunk is also fed
+to a headless terminal emulator whose serialized screen is replayed on reattach,
+so a reload keeps the shell and its scrollback. Shell discovery runs inside the
+target container: candidate names are resolved with POSIX `command -v` on the
+container's PATH (including the deployment's PATH additions) and merged with
+`/etc/shells` and `$SHELL`, so only shells the container really provides are
+offered, most capable first — the order mirrors the harness's own candidate
+preference and ends with the minimal POSIX shells, and the first entry is the
+client's default. The tab's workspace is resolved by the host from the session's
+own working directory — never chosen, shown or defaulted in the browser: a
+session outside every workspace is reported, and the client only uses the
+project name and workspace slug it is given. The selected path is re-verified
+before the shell starts.

package/docs/architecture.zh.md

@@ -23,14 +23,24 @@ dsh-podman 由三个组件组成：
 orchestrator（编排器）并通信 gRPC。请求携带共享
 token（`DSH_PODMAN_ORCHESTRATOR_TOKEN`）作为 `authorization: bearer` 标头。
 
+请求还会在 `x-dsh-podman-plugin-version` 标头中携带插件版本。插件与 orchestrator
+分别部署（前者是 dsh 镜像中的 npm 包，后者是此二进制文件），因此 orchestrator
+会拒绝来自**主版本**不同的插件的控制调用，并指出两者的版本以及哪一方更旧——不同步的部署会明确失败，而不会被误读。缺失或无法解析的版本同样会被拒绝。次版本或修订版本不同是兼容的：调用照常进行，orchestrator
+会按插件版本记录一次警告，Podman 页面也会显示。`GetVersion`
+不受该检查约束，因此插件始终可以获知 orchestrator 的版本。
+
 orchestrator 服务公开以下 gRPC 方法（同时支撑 UI
 和工具）：`ListContainers`（仅返回 orchestrator 创建的 guest
-容器——它不拥有的容器永远不会被暴露）、`StartContainer{workspace_slug, container, image_id, mounts, env, secret_env, paths}`（在工作区的
+容器——它不拥有的容器永远不会被暴露）、`EnsureContainer{workspace_slug, container}`（唯一的接入路径：返回指定容器，若其缺失、已停止或运行过期的
+guest
+agent，则先重建它）、`StartContainer{workspace_slug, container, image_id, mounts, env, secret_env, paths}`（在工作区的
 pod 中创建或替换容器；空的 `container`
 指向默认容器，其他名称会被校验）、`RecreateContainer{workspace_slug, container, image_id, mounts, env, paths}`（停止、删除并重新创建容器，可选择使用新镜像、项目挂载、环境或
 PATH 附加项；空的 `image_id`
-保留工作区当前的镜像）、`RemoveContainer`、`AddContainerMount`、`RemoveContainerMount`、`SetContainerPaths`、`AddContainerSecret`
-和 `RemoveContainerSecret`。
+保留工作区当前的镜像）、`RemoveContainer`、`AddContainerMount`、`UpdateContainerMount`、`RemoveContainerMount`、`SetContainerPaths`、`AddContainerSecret`
+和 `RemoveContainerSecret`。该服务还公开支撑 Podman
+页面的工作区、卷、机密、镜像（构建、重建、删除以及拉取基础镜像）和缓存（列出与清理）操作，以及
+`GetVersion`。
 
 ## 工作区与 pod
 
@@ -41,10 +51,12 @@ UUID），因此其容器共享一个网络命名空间。每个工作区都有
 和 `/run` 上是 podman 的可写 tmpfs（`/dev` 和 `/dev/shm`
 保持可写）。所有其他可写状态都存在于项目绑定挂载、命名卷或 tmpfs 挂载中。guest
 文件 API 可以访问 `/tmp`，而 guest agent 会把超出上限的命令输出写入
-`/tmp/dsh-podman` 下的溢出文件。
+`/tmp/dsh-podman` 下的溢出文件。过大的工具结果也会由插件的 `ctx.spillStore`
+溢出写入同一位置下的
+`/tmp/dsh-podman/spill/<session>/`——因此模型会用容器文件工具读回该产物，而不是使用容器无法访问的主机路径。
 
 工作区的 Pod 会在其最后一个容器被移除时拆除，也可直接通过
-`RemoveWorkspace`（设置卡片中的 **移除 Pod**
+`RemoveWorkspace`（Podman 页面中的 **移除 Pod**
 操作）拆除：它会停止各容器的守护进程、移除 Pod 及其容器、清理它们的 socket
 目录，并删除存储的工作区记录。卷、机密和项目数据保持不变。
 
@@ -60,6 +72,16 @@ UUID），因此其容器共享一个网络命名空间。每个工作区都有
 
 包含保留路径的目标会被拒绝，位于其内部的目标同样会被拒绝，因为它会隐藏其下的所有内容。
 
+通过 guest exec API 运行的命令，除非调用方明确要求管道，否则它们的 stdin 是
+`/dev/null`，因此读取 stdin 的命令会看到 EOF 而不会阻塞（因此不带路径的裸
+`rg`/`grep` 会搜索工作目录，而不是读取空管道）。`container_glob` 和
+`container_grep` 还会把解析后的路径作为搜索目录传给 ripgrep，而绝不会作为
+`--glob` 模式（包含 `/` 的路径永远无法匹配这种模式），并且 ripgrep 失败（退出码
+2）会被报告为工具错误，而不是返回空结果。ripgrep 会把包含 `/` 的 `--glob`
+模式锚定到进程工作目录，因此当 harness
+启动的目录列举以绝对搜索根目录运行时，它会从该根目录运行：此时 `glob` 的
+`pattern` 锚定到其 `path`，而打印出的路径保持绝对。
+
 项目挂载会解析符号链接并被限制在 projects root
 内，因此可写项目中的符号链接不能将绑定挂载重定向到其外部的路径。带有绝对目标的符号链接永远不会被跟随；请直接命名另一个项目。
 
@@ -71,6 +93,12 @@ API，运行并监督后台**守护进程**，并读取和写入文件。每个
 容器恰好获得一个绑定挂载到其中的套接字目录，因此 guest 永远不会看到 orchestrator
 的 control socket，也不会看到任何其他工作区的套接字目录。
 
+Guest API 不提供监视器，因此插件的 `ctx.fs` 提供者对 `watch` 返回
+`FS_IO_ERROR`（`Filesystem watching is not supported by this provider.`）。harness
+的工作区文件变更流因此返回
+`workspace-file/watch-unsupported`，浏览器的文件树改为按需刷新，而非实时刷新——与
+harness 自带的 SSH 文件系统提供者对远程路径采取的做法一致。
+
 命令和守护进程继承 guest agent 的环境，减去保留的 `DSH_PODMAN` 命名空间：agent
 自身的 token 保留在 agent 中，而不会被复制到它所启动的每个东西中。以
 `inheritEnv=false` 启动的守护进程则只接收 `PATH`/`HOME` 基线以及自身的 `env`。
@@ -107,14 +135,17 @@ API，因此构建不会向 orchestrator 的状态目录写入任何内容。
 
 `image_rebuild_all` 首先确保每个基础镜像（根据 `DSH_PODMAN_BASE_IMAGE_PREFIX`
 在本地构建或从公共注册表拉取），然后**按依赖顺序**重建存储的自定义镜像——每个父镜像都在从它派生的镜像之前。重建失败的镜像以及依赖它的每个镜像都会被报告在
-`skipped` 中，其余镜像继续。
+`skipped`
+中，其余镜像继续。本次调用无法构建或拉取的基础镜像也会以短名称报告在那里；`rebuilt`
+只列出自定义镜像，因此不会包含本次调用所确保的基础镜像。
 
 配置了主机缓存时（`DSH_PODMAN_HOST_*_CACHE`，同时挂载到构建容器和 orchestrator
-中），构建会复用已下载的软件包。设置卡片会报告每个缓存的大小并可清理它——保留每个软件包的最新版本，或清空缓存。构建器用读写锁将清理与构建串行化，因此清理绝不会在构建进行时删除其正在使用的软件包。
+中），构建会复用已下载的软件包。Podman
+页面会报告每个缓存的大小并可清理它——保留每个软件包的最新版本，或清空缓存。构建器用读写锁将清理与构建串行化，因此清理绝不会在构建进行时删除其正在使用的软件包。
 
-## 设置卡片传输
+## Podman 页面传输
 
-卡片通过 harness API 路径（`/api/podman/card`）之下的一个已认证 fetch
+Podman 页面通过 harness API 路径（`/api/podman/card`）之下的一个已认证 fetch
 路由与主机通信；该路由注册在 connection 服务上，因此承载层会先应用其 Host/Origin
 校验和浏览器认证：
 
@@ -124,6 +155,25 @@ API，因此构建不会向 orchestrator 的状态目录写入任何内容。
   `image_rebuild` / `image_rebuild_all` / volume / secret / secret-env / mount
   操作），并返回要显示的提示。
 
-因此设置命名空间中**只保留真正的偏好**：默认镜像、sockets
-根目录，以及卡片的当前语言（`uiLocale`，以便主机以会话语言呈现审批文本——参见[审批](usage.zh.md#审批)）。orchestrator
-派生的任何内容都不会被持久化，也不会有命令经由设置文档往返。
+因此插件自身的配置中**只保留真正的偏好**：默认镜像、默认环境变量，以及 Podman
+页面的当前语言（`uiLocale`，以便主机以会话语言呈现审批文本——参见[审批](usage.zh.md#审批)）。它们是
+volatile 字段，修改后无需重新加载插件即可生效。orchestrator
+派生的任何内容都不会被持久化，也不会有命令经由配置文档往返。
+
+## Podman 终端传输
+
+Podman 终端标签页通过自身在同一 connection
+服务上的已认证路由（`/api/podman/terminal`、`/api/podman/terminal/shells`、`/api/podman/terminal/retained`）与
+guest pty 通信。打开路由以换行分隔的 JSON 帧（ready、snapshot、base64
+输出、title、exit、error、detached）进行流式传输，并通过 POST
+接收控制请求（input、resize、rename、close）；承载层会像卡片路由一样应用
+Host/Origin 校验和浏览器认证。
+
+每个终端以 `(sessionId, tabId)` 为键并由主机保留：没有浏览器接入时 guest pty
+仍然存活，同时每个输出块都会写入一个无头终端模拟器，重新接入时回放其序列化屏幕，因此刷新页面不会丢失
+shell 及其回滚缓冲。shell 探测在目标容器内进行：以 POSIX `command -v` 在该容器的
+PATH（含部署的 PATH 追加项）中解析候选名称，并与 `/etc/shells` 和 `$SHELL`
+合并，因此只提供容器确实拥有的 shell；顺序按能力从强到弱（与 harness
+自身的候选顺序一致，最精简的 POSIX shell
+排在最后），第一项即客户端的默认值。标签页的工作区由主机根据会话自身的工作目录解析，浏览器既不可选择、不会显示，也不会回退：会话不在任何工作区内时会直接提示，客户端只使用主机给出的项目名与工作区
+slug。所选路径在启动前会再次校验。