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

package/README.md

@@ -32,9 +32,9 @@ per-project Podman containers.
 
 This repository was written in major parts using AI models:
 
+- DeepSeek Flash
 - early commits using OpenAI GPT-5.6 Luna
-- DeepSeek V4 Flash
-- source code weakness fixes by Anthropic Claude Opus 5
+- a few fixes using Anthropic Claude Opus 5
 
 ## License
 

package/dist/card-route.js

@@ -11,6 +11,19 @@ import { defaultMountMode, mountKindToProto, mountModeToProto } from "./mount-en
 import { unaryGuest } from "./guest-rpc.js";
 import { workspaceSlug } from "./workspace-binding.js";
 import { GIT_COMMIT, VERSION } from "./generated/version.js";
+import { versionState as pluginVersionState } from "./version-compat.js";
+import { dshVersion } from "./dsh-version.js";
+// readOrchestratorVersion asks the orchestrator for its version, or returns ""
+// when the call fails (an orchestrator predating the handshake).
+async function readOrchestratorVersion(resolver) {
+    try {
+        const response = await resolver.control("getVersion", {});
+        return String(response?.version ?? "");
+    }
+    catch {
+        return "";
+    }
+}
 // The cache clean modes the settings card can request, mapped to the control
 // plane's enum names.
 const CACHE_CLEAN_MODES = {
@@ -99,17 +112,48 @@ function dshWorkspaceCwd(registry, slug) {
 }
 /** Build the live snapshot the card renders. */
 export async function cardSnapshot(resolver, workspaceRegistry) {
-    const [containers, images, workspaces, volumes, secrets, caches] = await Promise.all([
-        resolver.control("listContainers", {}),
-        resolver.control("listImages", {}),
-        resolver.control("listWorkspaces", {}),
-        resolver.control("listVolumes", {}),
-        resolver.control("listSecrets", {}),
-        resolver.control("listCaches", {}),
-    ]);
+    // The handshake RPC is exempt from the orchestrator's version check, so it
+    // succeeds even when the rest is refused; an older orchestrator that has no
+    // GetVersion yet leaves the version unknown.
+    const orchestratorVersion = await readOrchestratorVersion(resolver);
+    let listings;
+    try {
+        listings = await Promise.all([
+            resolver.control("listContainers", {}),
+            resolver.control("listImages", {}),
+            resolver.control("listWorkspaces", {}),
+            resolver.control("listVolumes", {}),
+            resolver.control("listSecrets", {}),
+            resolver.control("listCaches", {}),
+        ]);
+    }
+    catch (error) {
+        // An incompatible plugin is refused before any handler runs, so the card
+        // reports the mismatch instead of an unexplained empty snapshot.
+        if (error?.code !== "FailedPrecondition")
+            throw error;
+        return {
+            version: VERSION,
+            commit: GIT_COMMIT,
+            dshVersion: dshVersion(),
+            orchestratorVersion,
+            versionState: "major-mismatch",
+            projectsRoot: resolver.getConfig().projectsRoot,
+            workspaces: [],
+            containers: [],
+            images: [],
+            volumes: [],
+            secrets: [],
+            caches: [],
+        };
+    }
+    const [containers, images, workspaces, volumes, secrets, caches] = listings;
     return {
         version: VERSION,
         commit: GIT_COMMIT,
+        dshVersion: dshVersion(),
+        orchestratorVersion,
+        versionState: pluginVersionState(VERSION, orchestratorVersion),
         projectsRoot: resolver.getConfig().projectsRoot,
         workspaces: mergeWorkspaceViews(dshWorkspaceViews(workspaceRegistry, resolver.getConfig().projectsRoot), orchestratorWorkspaceViews(workspaces.workspaces)),
         containers: (containers.containers ?? []).map((container) => ({

package/dist/card-route.test.js

@@ -17,6 +17,8 @@ function fakeResolver() {
         setConfig: () => { },
         async control(method, request) {
             calls.push([method, request]);
+            if (method === "getVersion")
+                return { version: "9.9.9", commit: "abc" };
             if (method === "listContainers")
                 return { containers: [{ containerName: "c1" }] };
             if (method === "listImages")
@@ -92,7 +94,30 @@ test("the card route serves the live snapshot on GET", async () => {
     assert.deepEqual(snapshot.volumes, [{ name: "data" }]);
     assert.deepEqual(snapshot.secrets, [{ name: "s1" }]);
     assert.equal(snapshot.caches[0].bytes, 1024);
-    assert.deepEqual(calls.map(([method]) => method), ["listContainers", "listImages", "listWorkspaces", "listVolumes", "listSecrets", "listCaches"]);
+    assert.deepEqual(calls.map(([method]) => method), ["getVersion", "listContainers", "listImages", "listWorkspaces", "listVolumes", "listSecrets", "listCaches"]);
+    assert.equal(typeof snapshot.dshVersion, "string");
+    assert.equal(snapshot.orchestratorVersion, "9.9.9");
+    assert.equal(snapshot.versionState, "major-mismatch", "a differing major is surfaced on the card");
+});
+test("a refused control call reports the version mismatch instead of an empty snapshot", async () => {
+    const { resolver } = fakeResolver();
+    const refusal = new Error("plugin is incompatible");
+    refusal.code = "FailedPrecondition";
+    resolver.control = async (method) => {
+        if (method === "getVersion")
+            return { version: "9.9.9", commit: "abc" };
+        throw refusal;
+    };
+    const { ctx, routes } = fakeRouteContext();
+    registerCardRoute(ctx, resolver);
+    const response = await routes[0].fetch(cardRequest());
+    assert.equal(response.status, 200);
+    const snapshot = (await response.json());
+    assert.equal(typeof snapshot.dshVersion, "string");
+    assert.equal(snapshot.orchestratorVersion, "9.9.9");
+    assert.equal(snapshot.versionState, "major-mismatch");
+    assert.deepEqual(snapshot.containers, []);
+    assert.deepEqual(snapshot.workspaces, []);
 });
 test("the card route runs one command per POST and returns its notice", async () => {
     const { resolver, calls } = fakeResolver();

package/dist/client/ContainerCard.js

@@ -9,8 +9,10 @@ import { CardChevron, ConfigField, ConfirmButton } from "./container-card-shared
 import { banner, cardBodyStyle, cardDescriptionStyle, cardHeadTextStyle, cardHeaderStyle, cardHoverStyle, cardNameStyle, cardOpenStyle, cardStyle, footerRow, hint, imageSelect, sectionTitle, } from "./container-card-styles.js";
 import { VolumesSection } from "./container-card-volumes.js";
 import { WorkspaceSection } from "./container-card-workspace.js";
-import { Button, Input, Modal } from "@deepseek-ai/dsh-client-ui-primitives";
-import { useEffect, useId, useState } from "react";
+import { Button, Input, Modal, writeClipboard, } from "@deepseek-ai/dsh-client-ui-primitives";
+import { useEffect, useId, useRef, useState, } from "react";
+// The labels of the version lines, emphasised against their values.
+const versionLabel = { fontWeight: 600 };
 export function ContainerCard(props) {
     const { t } = props;
     const state = props.useContainerCard((snapshot) => snapshot);
@@ -22,7 +24,22 @@ export function ContainerCard(props) {
     const [packages, setPackages] = useState([]);
     const [defaultOpen, setDefaultOpen] = useState(false);
     const [defaultImage, setDefaultImage] = useState(state.defaultImage);
+    const [copyState, setCopyState] = useState("idle");
+    const copyResetTimer = useRef();
     const projectsRootId = useId();
+    // Copies the version lines as displayed, so a user can paste them into a bug
+    // report without transcribing anything.
+    const copyVersions = async () => {
+        const lines = [
+            `${t("dsh")} ${state.dshVersion || t("versionUnknown")}`,
+            `${t("cardTitle")} ${state.version}${state.commit ? ` · ${state.commit}` : ""}`,
+            `${t("orchestrator")} ${state.orchestratorVersion || t("versionUnknown")}`,
+        ];
+        setCopyState((await writeClipboard(lines.join("\n"))) ? "copied" : "failed");
+        if (copyResetTimer.current !== undefined)
+            clearTimeout(copyResetTimer.current);
+        copyResetTimer.current = setTimeout(() => setCopyState("idle"), 1500);
+    };
     // The card mounts with the settings panel, so this re-reads the live state
     // every time the Plugins section is opened: a workspace created since the
     // last read shows up without pressing Reload this view.
@@ -43,7 +60,11 @@ export function ContainerCard(props) {
             ...cardStyle,
             ...(open ? cardOpenStyle : {}),
             ...(hovered && !open ? cardHoverStyle : {}),
-        }, onPointerEnter: () => setHovered(true), onPointerLeave: () => setHovered(false), children: [_jsxs("button", { type: "button", style: cardHeaderStyle, "aria-expanded": open, onClick: () => setOpen(!open), children: [_jsxs("span", { style: cardHeadTextStyle, children: [_jsxs("span", { style: cardNameStyle, children: [t("cardTitle"), state.version ? ` ${state.version}` : "", state.commit ? ` · ${state.commit}` : ""] }), _jsx("span", { style: cardDescriptionStyle, children: t("cardDescription") })] }), _jsx(CardChevron, { open: open })] }), open ? (_jsxs("div", { style: cardBodyStyle, children: [state.notice === "" ? null : (_jsxs("div", { style: banner, role: "status", children: [t("notice"), ": ", state.notice] })), _jsx("div", { style: sectionTitle, children: t("workspacesTitle") }), state.workspaces.length === 0 ? (_jsx("p", { style: hint, children: t("none") })) : (state.workspaces.map((workspace) => (_jsx(WorkspaceSection, { t: t, workspace: workspace, containers: state.containers.filter((container) => container.workspaceSlug === workspace.workspaceSlug), images: state.images, volumes: state.volumes, secrets: state.secrets, busy: state.busy, defaultImage: state.defaultImage, projectsRoot: state.projectsRoot, directoryPicker: state.directoryPicker, onRemove: props.remove, onRemoveWorkspace: props.removeWorkspace, onRecreate: props.recreate, onCreate: props.createContainer, onStartContainer: props.startContainer, onAddContainerMount: props.addContainerMount, onRemoveContainerMount: props.removeContainerMount, onUpdateContainerMount: props.updateContainerMount, onSetContainerPaths: props.setContainerPaths, onAddContainerSecret: props.addContainerSecret, onRemoveContainerSecret: props.removeContainerSecret }, workspace.workspaceSlug)))), _jsxs("div", { style: {
+        }, onPointerEnter: () => setHovered(true), onPointerLeave: () => setHovered(false), children: [_jsxs("button", { type: "button", style: cardHeaderStyle, "aria-expanded": open, onClick: () => setOpen(!open), children: [_jsxs("span", { style: cardHeadTextStyle, children: [_jsx("span", { style: cardNameStyle, children: t("cardTitle") }), _jsx("span", { style: cardDescriptionStyle, children: t("cardDescription") })] }), _jsx(CardChevron, { open: open })] }), open ? (_jsxs("div", { style: cardBodyStyle, children: [state.notice === "" ? null : (_jsxs("div", { style: banner, role: "status", children: [t("notice"), ": ", state.notice] })), state.versionState === "ok" ? null : (_jsx("div", { style: state.versionState === "major-mismatch"
+                            ? { ...banner, borderColor: "var(--dsw-alias-state-error-primary)" }
+                            : banner, role: state.versionState === "major-mismatch" ? "alert" : "status", children: t(state.versionState === "major-mismatch"
+                            ? "versionMismatchMajor"
+                            : "versionMismatchMinor") })), _jsx("div", { style: sectionTitle, children: t("workspacesTitle") }), state.workspaces.length === 0 ? (_jsx("p", { style: hint, children: t("none") })) : (state.workspaces.map((workspace) => (_jsx(WorkspaceSection, { t: t, workspace: workspace, containers: state.containers.filter((container) => container.workspaceSlug === workspace.workspaceSlug), images: state.images, volumes: state.volumes, secrets: state.secrets, busy: state.busy, defaultImage: state.defaultImage, projectsRoot: state.projectsRoot, directoryPicker: state.directoryPicker, onRemove: props.remove, onRemoveWorkspace: props.removeWorkspace, onRecreate: props.recreate, onCreate: props.createContainer, onStartContainer: props.startContainer, onAddContainerMount: props.addContainerMount, onRemoveContainerMount: props.removeContainerMount, onUpdateContainerMount: props.updateContainerMount, onSetContainerPaths: props.setContainerPaths, onAddContainerSecret: props.addContainerSecret, onRemoveContainerSecret: props.removeContainerSecret }, workspace.workspaceSlug)))), _jsxs("div", { style: {
                             display: "flex",
                             flexWrap: "wrap",
                             alignItems: "center",
@@ -75,5 +96,20 @@ export function ContainerCard(props) {
                                     fontSize: "13px",
                                     color: "var(--dsw-alias-label-secondary)",
                                     minWidth: "110px",
-                                }, children: t("projectsRoot") }), _jsx(Input, { id: projectsRootId, value: state.projectsRoot, disabled: true, style: { width: "200px" } })] }), _jsx(ConfigField, { t: t, label: t("socketsRoot"), value: state.socketsRootDraft, current: state.socketsRoot, writable: state.writable, onChange: props.editSocketsRoot, onSave: props.saveSocketsRoot, onDiscard: props.discardSocketsRoot }), _jsx("div", { style: footerRow, children: _jsx(Button, { variant: "outline", size: "sm", disabled: state.busy, onClick: props.reload, children: state.busy ? t("busy") : t("reload") }) })] })) : null] }));
+                                }, children: t("projectsRoot") }), _jsx(Input, { id: projectsRootId, value: state.projectsRoot, disabled: true, style: { width: "200px" } })] }), _jsx(ConfigField, { t: t, label: t("socketsRoot"), value: state.socketsRootDraft, current: state.socketsRoot, writable: state.writable, onChange: props.editSocketsRoot, onSave: props.saveSocketsRoot, onDiscard: props.discardSocketsRoot }), _jsxs("div", { style: {
+                            display: "flex",
+                            flexWrap: "wrap",
+                            alignItems: "center",
+                            gap: "8px",
+                        }, children: [_jsx("div", { style: { ...sectionTitle, flex: 1 }, children: t("versionsTitle") }), _jsx(Button, { variant: "outline", size: "sm", onClick: () => void copyVersions(), children: copyState === "copied"
+                                    ? t("copied")
+                                    : copyState === "failed"
+                                        ? t("copyFailed")
+                                        : t("copyVersions") })] }), _jsxs("div", { style: {
+                            ...hint,
+                            display: "flex",
+                            flexDirection: "column",
+                            gap: "2px",
+                            margin: 0,
+                        }, children: [_jsxs("span", { children: [_jsx("span", { style: versionLabel, children: t("dsh") }), state.dshVersion ? (` ${state.dshVersion}`) : (_jsxs(_Fragment, { children: [" ", _jsx("span", { style: { color: "var(--dsw-alias-state-error-primary)" }, children: t("versionUnknown") })] }))] }), _jsxs("span", { children: [_jsx("span", { style: versionLabel, children: t("cardTitle") }), state.version ? ` ${state.version}` : "", state.commit ? ` · ${state.commit}` : ""] }), _jsxs("span", { children: [_jsx("span", { style: versionLabel, children: t("orchestrator") }), state.orchestratorVersion ? (` ${state.orchestratorVersion}`) : (_jsxs(_Fragment, { children: [" ", _jsx("span", { style: { color: "var(--dsw-alias-state-error-primary)" }, children: t("versionUnknown") })] }))] })] }), _jsx("div", { style: footerRow, children: _jsx(Button, { variant: "outline", size: "sm", disabled: state.busy, onClick: props.reload, children: state.busy ? t("busy") : t("reload") }) })] })) : null] }));
 }

package/dist/client/card-protocol.d.ts

@@ -85,6 +85,9 @@ export interface WorkspaceView {
 export interface CardSnapshot {
     version: string;
     commit: string;
+    dshVersion: string;
+    orchestratorVersion: string;
+    versionState: "ok" | "minor-mismatch" | "major-mismatch";
     projectsRoot: string;
     workspaces: readonly WorkspaceView[];
     containers: readonly ContainerView[];

package/dist/client/container-card-controller.d.ts

@@ -32,6 +32,9 @@ export interface CardState {
     notice: string;
     version: string;
     commit: string;
+    dshVersion: string;
+    orchestratorVersion: string;
+    versionState: "ok" | "minor-mismatch" | "major-mismatch";
     defaultImage: string;
     defaultImageDraft: string;
     socketsRoot: string;

package/dist/client/container-card-controller.js

@@ -7,6 +7,9 @@ export const CONTAINER_NS = "podman";
 const EMPTY_SNAPSHOT = {
     version: "",
     commit: "",
+    dshVersion: "",
+    orchestratorVersion: "",
+    versionState: "ok",
     projectsRoot: "",
     workspaces: [],
     containers: [],
@@ -49,6 +52,9 @@ export class ContainerCardController {
             notice: this.notice,
             version: this.snapshot.version,
             commit: this.snapshot.commit,
+            dshVersion: this.snapshot.dshVersion,
+            orchestratorVersion: this.snapshot.orchestratorVersion,
+            versionState: this.snapshot.versionState,
             defaultImage: value?.defaultImage ?? "",
             defaultImageDraft: this.draft("defaultImage", value?.defaultImage ?? ""),
             socketsRoot: value?.socketsRoot ?? "",

package/dist/client/index.js

@@ -3010,6 +3010,7 @@ function WorkspaceSection(props) {
 var import_dsh_client_ui_primitives11 = require("@deepseek-ai/dsh-client-ui-primitives");
 var import_react11 = require("react");
 var import_jsx_runtime12 = require("react/jsx-runtime");
+var versionLabel = { fontWeight: 600 };
 function ContainerCard(props) {
   const { t } = props;
   const state = props.useContainerCard((snapshot) => snapshot);
@@ -3021,7 +3022,21 @@ function ContainerCard(props) {
   const [packages, setPackages] = (0, import_react11.useState)([]);
   const [defaultOpen, setDefaultOpen] = (0, import_react11.useState)(false);
   const [defaultImage, setDefaultImage] = (0, import_react11.useState)(state.defaultImage);
+  const [copyState, setCopyState] = (0, import_react11.useState)(
+    "idle"
+  );
+  const copyResetTimer = (0, import_react11.useRef)();
   const projectsRootId = (0, import_react11.useId)();
+  const copyVersions = async () => {
+    const lines = [
+      `${t("dsh")} ${state.dshVersion || t("versionUnknown")}`,
+      `${t("cardTitle")} ${state.version}${state.commit ? ` \xB7 ${state.commit}` : ""}`,
+      `${t("orchestrator")} ${state.orchestratorVersion || t("versionUnknown")}`
+    ];
+    setCopyState(await (0, import_dsh_client_ui_primitives11.writeClipboard)(lines.join("\n")) ? "copied" : "failed");
+    if (copyResetTimer.current !== void 0) clearTimeout(copyResetTimer.current);
+    copyResetTimer.current = setTimeout(() => setCopyState("idle"), 1500);
+  };
   (0, import_react11.useEffect)(() => {
     props.reload();
   }, []);
@@ -3054,11 +3069,7 @@ function ContainerCard(props) {
             onClick: () => setOpen(!open),
             children: [
               /* @__PURE__ */ (0, import_jsx_runtime12.jsxs)("span", { style: cardHeadTextStyle, children: [
-                /* @__PURE__ */ (0, import_jsx_runtime12.jsxs)("span", { style: cardNameStyle, children: [
-                  t("cardTitle"),
-                  state.version ? ` ${state.version}` : "",
-                  state.commit ? ` \xB7 ${state.commit}` : ""
-                ] }),
+                /* @__PURE__ */ (0, import_jsx_runtime12.jsx)("span", { style: cardNameStyle, children: t("cardTitle") }),
                 /* @__PURE__ */ (0, import_jsx_runtime12.jsx)("span", { style: cardDescriptionStyle, children: t("cardDescription") })
               ] }),
               /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(CardChevron, { open })
@@ -3071,6 +3082,16 @@ function ContainerCard(props) {
             ": ",
             state.notice
           ] }),
+          state.versionState === "ok" ? null : /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(
+            "div",
+            {
+              style: state.versionState === "major-mismatch" ? { ...banner, borderColor: "var(--dsw-alias-state-error-primary)" } : banner,
+              role: state.versionState === "major-mismatch" ? "alert" : "status",
+              children: t(
+                state.versionState === "major-mismatch" ? "versionMismatchMajor" : "versionMismatchMinor"
+              )
+            }
+          ),
           /* @__PURE__ */ (0, import_jsx_runtime12.jsx)("div", { style: sectionTitle, children: t("workspacesTitle") }),
           state.workspaces.length === 0 ? /* @__PURE__ */ (0, import_jsx_runtime12.jsx)("p", { style: hint, children: t("none") }) : state.workspaces.map((workspace) => /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(
             WorkspaceSection,
@@ -3330,6 +3351,74 @@ function ContainerCard(props) {
               onDiscard: props.discardSocketsRoot
             }
           ),
+          /* @__PURE__ */ (0, import_jsx_runtime12.jsxs)(
+            "div",
+            {
+              style: {
+                display: "flex",
+                flexWrap: "wrap",
+                alignItems: "center",
+                gap: "8px"
+              },
+              children: [
+                /* @__PURE__ */ (0, import_jsx_runtime12.jsx)("div", { style: { ...sectionTitle, flex: 1 }, children: t("versionsTitle") }),
+                /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(
+                  import_dsh_client_ui_primitives11.Button,
+                  {
+                    variant: "outline",
+                    size: "sm",
+                    onClick: () => void copyVersions(),
+                    children: copyState === "copied" ? t("copied") : copyState === "failed" ? t("copyFailed") : t("copyVersions")
+                  }
+                )
+              ]
+            }
+          ),
+          /* @__PURE__ */ (0, import_jsx_runtime12.jsxs)(
+            "div",
+            {
+              style: {
+                ...hint,
+                display: "flex",
+                flexDirection: "column",
+                gap: "2px",
+                margin: 0
+              },
+              children: [
+                /* @__PURE__ */ (0, import_jsx_runtime12.jsxs)("span", { children: [
+                  /* @__PURE__ */ (0, import_jsx_runtime12.jsx)("span", { style: versionLabel, children: t("dsh") }),
+                  state.dshVersion ? ` ${state.dshVersion}` : /* @__PURE__ */ (0, import_jsx_runtime12.jsxs)(import_jsx_runtime12.Fragment, { children: [
+                    " ",
+                    /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(
+                      "span",
+                      {
+                        style: { color: "var(--dsw-alias-state-error-primary)" },
+                        children: t("versionUnknown")
+                      }
+                    )
+                  ] })
+                ] }),
+                /* @__PURE__ */ (0, import_jsx_runtime12.jsxs)("span", { children: [
+                  /* @__PURE__ */ (0, import_jsx_runtime12.jsx)("span", { style: versionLabel, children: t("cardTitle") }),
+                  state.version ? ` ${state.version}` : "",
+                  state.commit ? ` \xB7 ${state.commit}` : ""
+                ] }),
+                /* @__PURE__ */ (0, import_jsx_runtime12.jsxs)("span", { children: [
+                  /* @__PURE__ */ (0, import_jsx_runtime12.jsx)("span", { style: versionLabel, children: t("orchestrator") }),
+                  state.orchestratorVersion ? ` ${state.orchestratorVersion}` : /* @__PURE__ */ (0, import_jsx_runtime12.jsxs)(import_jsx_runtime12.Fragment, { children: [
+                    " ",
+                    /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(
+                      "span",
+                      {
+                        style: { color: "var(--dsw-alias-state-error-primary)" },
+                        children: t("versionUnknown")
+                      }
+                    )
+                  ] })
+                ] })
+              ]
+            }
+          ),
           /* @__PURE__ */ (0, import_jsx_runtime12.jsx)("div", { style: footerRow, children: /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(
             import_dsh_client_ui_primitives11.Button,
             {
@@ -3781,6 +3870,9 @@ var CONTAINER_NS = "podman";
 var EMPTY_SNAPSHOT = {
   version: "",
   commit: "",
+  dshVersion: "",
+  orchestratorVersion: "",
+  versionState: "ok",
   projectsRoot: "",
   workspaces: [],
   containers: [],
@@ -3819,6 +3911,9 @@ var ContainerCardController = class {
       notice: this.notice,
       version: this.snapshot.version,
       commit: this.snapshot.commit,
+      dshVersion: this.snapshot.dshVersion,
+      orchestratorVersion: this.snapshot.orchestratorVersion,
+      versionState: this.snapshot.versionState,
       defaultImage: value?.defaultImage ?? "",
       defaultImageDraft: this.draft("defaultImage", value?.defaultImage ?? ""),
       socketsRoot: value?.socketsRoot ?? "",
@@ -3983,6 +4078,15 @@ var NS = "podman";
 var en = {
   cardTitle: "dsh-podman",
   cardDescription: "Manage the guest containers and their images.",
+  versionMismatchMajor: "This plugin's major version differs from the orchestrator's; update the dsh image or the orchestrator image so both match.",
+  versionMismatchMinor: "This plugin and the orchestrator have compatible but different versions; consider updating both images.",
+  versionsTitle: "Versions",
+  orchestrator: "dsh-podman-orchestrator",
+  versionUnknown: "unknown",
+  dsh: "dsh",
+  copyVersions: "Copy versions",
+  copied: "Copied",
+  copyFailed: "Copy failed",
   reload: "Reload this view",
   reloading: "Reloading\u2026",
   notice: "Notice",
@@ -4166,6 +4270,15 @@ var en = {
 var zh = {
   cardTitle: "dsh-podman",
   cardDescription: "\u7BA1\u7406\u5DE5\u4F5C\u533A\u5BB9\u5668\u53CA\u5176\u955C\u50CF\u3002",
+  versionMismatchMajor: "\u6B64\u63D2\u4EF6\u4E0E orchestrator \u7684\u4E3B\u7248\u672C\u4E0D\u540C\uFF1B\u8BF7\u66F4\u65B0 dsh \u955C\u50CF\u6216 orchestrator \u955C\u50CF\uFF0C\u4F7F\u4E24\u8005\u4E00\u81F4\u3002",
+  versionMismatchMinor: "\u6B64\u63D2\u4EF6\u4E0E orchestrator \u7684\u7248\u672C\u4E0D\u540C\u4F46\u517C\u5BB9\uFF1B\u5EFA\u8BAE\u540C\u65F6\u66F4\u65B0\u4E24\u4E2A\u955C\u50CF\u3002",
+  versionsTitle: "\u7248\u672C",
+  orchestrator: "dsh-podman-orchestrator",
+  versionUnknown: "\u672A\u77E5",
+  dsh: "dsh",
+  copyVersions: "\u590D\u5236\u7248\u672C",
+  copied: "\u5DF2\u590D\u5236",
+  copyFailed: "\u590D\u5236\u5931\u8D25",
   reload: "\u5237\u65B0\u6B64\u89C6\u56FE",
   reloading: "\u5237\u65B0\u4E2D\u2026",
   notice: "\u63D0\u793A",

package/dist/client/locales.d.ts

@@ -1,5 +1,5 @@
 export declare const NS = "podman";
-export type ContainerPluginKey = "cardTitle" | "cardDescription" | "reload" | "reloading" | "notice" | "configTitle" | "defaultImage" | "socketsRoot" | "projectsRoot" | "defaultImageHint" | "save" | "discard" | "workspacesTitle" | "noContainers" | "createContainer" | "containersTitle" | "containerName" | "workspace" | "image" | "status" | "created" | "projects" | "remove" | "removePod" | "confirmRemovePod" | "recreate" | "recreateWithImage" | "imagesTitle" | "imageId" | "baseImage" | "imageTag" | "builtAt" | "packages" | "volumesTitle" | "createVolume" | "removeVolume" | "volumeName" | "secretsTitle" | "createSecret" | "secretName" | "secretCharset" | "selectImage" | "setSecret" | "removeSecret" | "removeImage" | "rebuildImage" | "rebuildAllImages" | "buildImage" | "build" | "buildImageTitle" | "pullImage" | "setDefaultImage" | "setDefaultImageTitle" | "baseImagesTitle" | "customImagesTitle" | "primitive" | "packageManager" | "parent" | "cancel" | "removeTag" | "env" | "secretEnv" | "envTitle" | "envKey" | "envValue" | "addEnv" | "removeEnv" | "secretLength" | "containerSecretsTitle" | "attachSecret" | "secretEnvName" | "detachSecret" | "none" | "unavailable" | "busy" | "confirmTitle" | "confirm" | "confirmRemoveContainer" | "confirmRecreate" | "confirmRemoveImage" | "confirmRebuildImage" | "confirmRebuildAllImages" | "confirmRemoveVolume" | "confirmSetSecret" | "confirmRemoveSecret" | "confirmDetachSecret" | "mountsTitle" | "addMount" | "mountKind" | "mountProject" | "mountProjectPath" | "browse" | "browseTitle" | "browseSelect" | "browseLoading" | "browseError" | "browseUnavailable" | "browseHidden" | "browseTruncated" | "browseOutsideRoot" | "mountDestination" | "pathsTitle" | "noPaths" | "editPaths" | "addPath" | "add" | "moveUp" | "moveDown" | "apply" | "dragToReorder" | "remountWaiting" | "remountApprove" | "remountReject" | "mountVolume" | "mountSecret" | "mountMode" | "readOnly" | "readWrite" | "remountReadOnly" | "remountReadWrite" | "confirmRemountReadOnly" | "confirmRemountReadWrite" | "confirmRemoveMount" | "cachesTitle" | "noCaches" | "cacheUsage" | "cacheKeepLatest" | "confirmCacheKeepLatest" | "cacheRemoveAll" | "confirmCacheRemoveAll" | "addContainer" | "invalidContainerName" | "containerNameTaken" | "invalidName" | "invalidImageId" | "terminalSignal" | "terminalExitCode" | "terminalRunning" | "terminalFailed" | "terminalDone" | "terminalNoOutput" | "terminalCollapseAria" | "terminalExpandAria" | "terminalExpandRest" | "toolTitle_container_bash" | "toolTitle_container_exec" | "toolTitle_container_read" | "toolTitle_container_write" | "toolTitle_container_edit" | "toolTitle_container_glob" | "toolTitle_container_grep" | "toolTitle_container_list" | "toolTitle_container_start" | "toolTitle_container_recreate" | "toolTitle_container_remove" | "toolTitle_container_mount_list" | "toolTitle_container_mount_add" | "toolTitle_container_mount_remove" | "toolTitle_container_mount_update" | "toolTitle_container_path_set" | "toolTitle_container_path_add" | "toolTitle_container_path_remove" | "toolTitle_container_secret_add" | "toolTitle_container_secret_remove" | "toolTitle_image_list" | "toolTitle_image_get" | "toolTitle_image_build" | "toolTitle_image_rebuild" | "toolTitle_image_rebuild_all" | "toolTitle_image_remove" | "toolTitle_volume_list" | "toolTitle_volume_create" | "toolTitle_volume_remove" | "toolTitle_secret_list" | "toolTitle_secret_create" | "toolTitle_secret_remove" | "toolTitle_daemon_start" | "toolTitle_daemon_list" | "toolTitle_daemon_logs" | "toolTitle_daemon_restart" | "toolTitle_daemon_stop";
+export type ContainerPluginKey = "cardTitle" | "cardDescription" | "versionMismatchMajor" | "versionMismatchMinor" | "versionsTitle" | "orchestrator" | "versionUnknown" | "dsh" | "copyVersions" | "copied" | "copyFailed" | "reload" | "reloading" | "notice" | "configTitle" | "defaultImage" | "socketsRoot" | "projectsRoot" | "defaultImageHint" | "save" | "discard" | "workspacesTitle" | "noContainers" | "createContainer" | "containersTitle" | "containerName" | "workspace" | "image" | "status" | "created" | "projects" | "remove" | "removePod" | "confirmRemovePod" | "recreate" | "recreateWithImage" | "imagesTitle" | "imageId" | "baseImage" | "imageTag" | "builtAt" | "packages" | "volumesTitle" | "createVolume" | "removeVolume" | "volumeName" | "secretsTitle" | "createSecret" | "secretName" | "secretCharset" | "selectImage" | "setSecret" | "removeSecret" | "removeImage" | "rebuildImage" | "rebuildAllImages" | "buildImage" | "build" | "buildImageTitle" | "pullImage" | "setDefaultImage" | "setDefaultImageTitle" | "baseImagesTitle" | "customImagesTitle" | "primitive" | "packageManager" | "parent" | "cancel" | "removeTag" | "env" | "secretEnv" | "envTitle" | "envKey" | "envValue" | "addEnv" | "removeEnv" | "secretLength" | "containerSecretsTitle" | "attachSecret" | "secretEnvName" | "detachSecret" | "none" | "unavailable" | "busy" | "confirmTitle" | "confirm" | "confirmRemoveContainer" | "confirmRecreate" | "confirmRemoveImage" | "confirmRebuildImage" | "confirmRebuildAllImages" | "confirmRemoveVolume" | "confirmSetSecret" | "confirmRemoveSecret" | "confirmDetachSecret" | "mountsTitle" | "addMount" | "mountKind" | "mountProject" | "mountProjectPath" | "browse" | "browseTitle" | "browseSelect" | "browseLoading" | "browseError" | "browseUnavailable" | "browseHidden" | "browseTruncated" | "browseOutsideRoot" | "mountDestination" | "pathsTitle" | "noPaths" | "editPaths" | "addPath" | "add" | "moveUp" | "moveDown" | "apply" | "dragToReorder" | "remountWaiting" | "remountApprove" | "remountReject" | "mountVolume" | "mountSecret" | "mountMode" | "readOnly" | "readWrite" | "remountReadOnly" | "remountReadWrite" | "confirmRemountReadOnly" | "confirmRemountReadWrite" | "confirmRemoveMount" | "cachesTitle" | "noCaches" | "cacheUsage" | "cacheKeepLatest" | "confirmCacheKeepLatest" | "cacheRemoveAll" | "confirmCacheRemoveAll" | "addContainer" | "invalidContainerName" | "containerNameTaken" | "invalidName" | "invalidImageId" | "terminalSignal" | "terminalExitCode" | "terminalRunning" | "terminalFailed" | "terminalDone" | "terminalNoOutput" | "terminalCollapseAria" | "terminalExpandAria" | "terminalExpandRest" | "toolTitle_container_bash" | "toolTitle_container_exec" | "toolTitle_container_read" | "toolTitle_container_write" | "toolTitle_container_edit" | "toolTitle_container_glob" | "toolTitle_container_grep" | "toolTitle_container_list" | "toolTitle_container_start" | "toolTitle_container_recreate" | "toolTitle_container_remove" | "toolTitle_container_mount_list" | "toolTitle_container_mount_add" | "toolTitle_container_mount_remove" | "toolTitle_container_mount_update" | "toolTitle_container_path_set" | "toolTitle_container_path_add" | "toolTitle_container_path_remove" | "toolTitle_container_secret_add" | "toolTitle_container_secret_remove" | "toolTitle_image_list" | "toolTitle_image_get" | "toolTitle_image_build" | "toolTitle_image_rebuild" | "toolTitle_image_rebuild_all" | "toolTitle_image_remove" | "toolTitle_volume_list" | "toolTitle_volume_create" | "toolTitle_volume_remove" | "toolTitle_secret_list" | "toolTitle_secret_create" | "toolTitle_secret_remove" | "toolTitle_daemon_start" | "toolTitle_daemon_list" | "toolTitle_daemon_logs" | "toolTitle_daemon_restart" | "toolTitle_daemon_stop";
 export declare const en: Record<ContainerPluginKey, string>;
 export declare const zh: Record<ContainerPluginKey, string>;
 declare module "@deepseek-ai/dsh-client-ui-slots" {

package/dist/client/locales.js

@@ -5,6 +5,15 @@ export const NS = "podman";
 export const en = {
     cardTitle: "dsh-podman",
     cardDescription: "Manage the guest containers and their images.",
+    versionMismatchMajor: "This plugin's major version differs from the orchestrator's; update the dsh image or the orchestrator image so both match.",
+    versionMismatchMinor: "This plugin and the orchestrator have compatible but different versions; consider updating both images.",
+    versionsTitle: "Versions",
+    orchestrator: "dsh-podman-orchestrator",
+    versionUnknown: "unknown",
+    dsh: "dsh",
+    copyVersions: "Copy versions",
+    copied: "Copied",
+    copyFailed: "Copy failed",
     reload: "Reload this view",
     reloading: "Reloading…",
     notice: "Notice",
@@ -188,6 +197,15 @@ export const en = {
 export const zh = {
     cardTitle: "dsh-podman",
     cardDescription: "管理工作区容器及其镜像。",
+    versionMismatchMajor: "此插件与 orchestrator 的主版本不同；请更新 dsh 镜像或 orchestrator 镜像，使两者一致。",
+    versionMismatchMinor: "此插件与 orchestrator 的版本不同但兼容；建议同时更新两个镜像。",
+    versionsTitle: "版本",
+    orchestrator: "dsh-podman-orchestrator",
+    versionUnknown: "未知",
+    dsh: "dsh",
+    copyVersions: "复制版本",
+    copied: "已复制",
+    copyFailed: "复制失败",
     reload: "刷新此视图",
     reloading: "刷新中…",
     notice: "提示",

package/dist/dsh-version.d.ts

@@ -0,0 +1 @@
+export declare function dshVersion(): string;

package/dist/dsh-version.js

@@ -0,0 +1,45 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import { createRequire } from "node:module";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+// The harness version this plugin runs inside. Every `@deepseek-ai/dsh-*`
+// package carries the release version, and the dsh app package is linked into
+// the profile's healed node_modules, so it is resolvable from the plugin even
+// though it is not a dependency of it. "" when it cannot be resolved, which the
+// card renders as unknown.
+let cached;
+export function dshVersion() {
+    cached ??= resolveDshVersion() ?? "";
+    return cached;
+}
+// resolveDshVersion walks the module search paths the way the harness resolves
+// its own bundles, so a package that does not export ./package.json still
+// resolves.
+function resolveDshVersion() {
+    let searchPaths;
+    try {
+        searchPaths = createRequire(import.meta.url).resolve.paths("@deepseek-ai/dsh") ?? [];
+    }
+    catch {
+        return undefined;
+    }
+    for (const searchPath of searchPaths) {
+        if (searchPath === null)
+            continue;
+        const manifest = join(searchPath, "@deepseek-ai/dsh", "package.json");
+        if (!existsSync(manifest))
+            continue;
+        try {
+            const parsed = JSON.parse(readFileSync(manifest, "utf8"));
+            if (typeof parsed.version === "string" && parsed.version !== "") {
+                return parsed.version;
+            }
+        }
+        catch {
+            // A malformed manifest is not a version source; keep looking.
+        }
+    }
+    return undefined;
+}

package/dist/generated/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.2.0-rc.3";
-export declare const GIT_COMMIT = "f61b296";
+export declare const VERSION = "0.2.0-rc.4";
+export declare const GIT_COMMIT = "fce200f";

package/dist/generated/version.js

@@ -2,5 +2,5 @@
 //
 // SPDX-License-Identifier: MIT
 // Generated by scripts/generate-version.mjs; do not edit.
-export const VERSION = "0.2.0-rc.3";
-export const GIT_COMMIT = "f61b296";
+export const VERSION = "0.2.0-rc.4";
+export const GIT_COMMIT = "fce200f";

package/dist/grpc/proto/dshctl/v1/control.proto

@@ -7,6 +7,7 @@ package dshctl.v1;
 option go_package = "github.com/Exagone313/dsh-podman/internal/genproto/dshctl/v1;dshctlv1";
 
 service OrchestratorControl {
+  rpc GetVersion(GetVersionRequest) returns (GetVersionResponse);
   rpc ListProjects(ListProjectsRequest) returns (ListProjectsResponse);
   rpc CreateWorkspace(CreateWorkspaceRequest) returns (Workspace);
   rpc DescribeWorkspace(DescribeWorkspaceRequest) returns (Workspace);
@@ -41,6 +42,8 @@ service OrchestratorControl {
   rpc RemoveContainerSecret(RemoveContainerSecretRequest) returns (Container);
 }
 
+message GetVersionRequest {}
+message GetVersionResponse { string version = 1; string commit = 2; }
 message ListProjectsRequest {}
 message ListProjectsResponse { repeated Project projects = 1; }
 message Project { string name = 1; string host_path = 2; }

package/dist/settings-workspaces.test.js

@@ -18,6 +18,8 @@ test("refresh on install publishes containers, images and workspaces", async ()
         setConfig: () => { },
         async control(method, request) {
             calls.push([method, request]);
+            if (method === "getVersion")
+                return { version: "0.2.0", commit: "abc" };
             if (method === "listContainers") {
                 return { containers: [{ containerName: "c1", workspaceSlug: "w1" }] };
             }
@@ -38,7 +40,7 @@ test("refresh on install publishes containers, images and workspaces", async ()
     };
     await installCardCommandDriver(fakeContext(scope), resolver);
     await scope.update({}); // settle the queued async refresh
-    assert.deepEqual(calls.map(([method]) => method), ["listContainers", "listImages", "listWorkspaces", "listVolumes", "listSecrets", "listCaches"]);
+    assert.deepEqual(calls.map(([method]) => method), ["getVersion", "listContainers", "listImages", "listWorkspaces", "listVolumes", "listSecrets", "listCaches"]);
     assert.equal(scope.value.containers.length, 1);
     assert.equal(scope.value.images.length, 1);
     const workspaces = scope.value.workspaces;

package/dist/version-compat.d.ts

@@ -0,0 +1,4 @@
+export type VersionState = "ok" | "minor-mismatch" | "major-mismatch";
+export declare function core(value: string): string;
+export declare function major(value: string): number;
+export declare function versionState(plugin: string, orchestrator: string): VersionState;

package/dist/version-compat.js

@@ -0,0 +1,29 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+// core returns the leading x.y.z of a version string, or "" when there is
+// none. A release build is exactly the tag; a build from a later commit carries
+// a git-describe suffix (`1.2.3-4-gabc123`), and a local build may be `dev`.
+export function core(value) {
+    const match = /^(\d+)\.(\d+)\.(\d+)/.exec(String(value ?? ""));
+    return match === null ? "" : `${match[1]}.${match[2]}.${match[3]}`;
+}
+// major returns the major component of a version's core, or -1 when the value
+// has no parseable core.
+export function major(value) {
+    const parsed = core(value);
+    return parsed === "" ? -1 : Number(parsed.slice(0, parsed.indexOf(".")));
+}
+// versionState mirrors the orchestrator's own compatibility rule, so the card
+// reports exactly what the control plane enforces.
+export function versionState(plugin, orchestrator) {
+    const orchestratorCore = core(orchestrator);
+    if (orchestratorCore === "")
+        return "ok";
+    const pluginCore = core(plugin);
+    if (pluginCore === "")
+        return "major-mismatch";
+    if (major(plugin) !== major(orchestrator))
+        return "major-mismatch";
+    return pluginCore === orchestratorCore ? "ok" : "minor-mismatch";
+}

package/dist/version-compat.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/version-compat.test.js

@@ -0,0 +1,27 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import test from "node:test";
+import assert from "node:assert/strict";
+import { core, major, versionState } from "./version-compat.js";
+test("core keeps the leading x.y.z", () => {
+    assert.equal(core("1.2.3"), "1.2.3");
+    assert.equal(core("0.2.0-rc.3"), "0.2.0");
+    assert.equal(core("1.2.3-4-gabc123"), "1.2.3");
+    assert.equal(core("dev"), "");
+    assert.equal(core(""), "");
+});
+test("major reports the leading component", () => {
+    assert.equal(major("1.2.3"), 1);
+    assert.equal(major("0.2.0-rc.3"), 0);
+    assert.equal(major("dev"), -1);
+});
+test("versionState mirrors the orchestrator's compatibility rule", () => {
+    assert.equal(versionState("1.2.3", "1.2.3"), "ok");
+    assert.equal(versionState("1.2.3-4-gabc", "1.2.3"), "ok");
+    assert.equal(versionState("1.3.0", "1.2.3"), "minor-mismatch");
+    assert.equal(versionState("1.2.4", "1.2.3"), "minor-mismatch");
+    assert.equal(versionState("2.0.0", "1.9.0"), "major-mismatch");
+    assert.equal(versionState("1.9.0", "2.0.0"), "major-mismatch");
+    assert.equal(versionState("1.2.3", "dev"), "ok", "an orchestrator with no comparable version accepts any plugin");
+});

package/dist/workspace-binding.d.ts

@@ -37,4 +37,4 @@ export declare function containerNotFound(container: string, slug?: string): Err
 export declare function normalizeToolError(error: unknown): Error;
 export declare function workspaceSlug(id: unknown): string;
 export declare function containerRowFor(containers: any[], slug: string, container: string): any | undefined;
-export declare function metadata(token: string): grpc.Metadata;
+export declare function metadata(token: string, pluginVersion?: string): grpc.Metadata;

package/dist/workspace-binding.js

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: MIT
 import { guestClient, controlClient, grpc, unary, } from "./grpc/runtime-client.js";
 import { isAbsolute, join } from "node:path";
+import { VERSION } from "./generated/version.js";
 export class WorkspaceResolver {
     config;
     registry;
@@ -162,7 +163,7 @@ export class WorkspaceResolver {
     }
     async create(slug, projectName) {
         const control = controlClient(join(this.config.socketsRoot, "orchestrator.sock"));
-        const controlMetadata = metadata(this.config.controlToken);
+        const controlMetadata = metadata(this.config.controlToken, VERSION);
         let workspace;
         try {
             workspace = await unary(control, "describeWorkspace", {
@@ -187,7 +188,7 @@ export class WorkspaceResolver {
         };
     }
     async control(method, request) {
-        return unary(controlClient(join(this.config.socketsRoot, "orchestrator.sock")), method, request, metadata(this.config.controlToken));
+        return unary(controlClient(join(this.config.socketsRoot, "orchestrator.sock")), method, request, metadata(this.config.controlToken, VERSION));
     }
 }
 // notFoundError builds the harness's missing-path error (`FsErrorCode`
@@ -244,11 +245,17 @@ const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{
 export function containerRowFor(containers, slug, container) {
     return containers.find((row) => row.workspaceSlug === slug && row.containerName === container);
 }
-export function metadata(token) {
+// metadata builds the call metadata. The plugin version is sent on control
+// calls so the orchestrator can refuse an incompatible plugin; guest calls omit
+// it, since the guest agent does not check it.
+export function metadata(token, pluginVersion) {
     const result = new grpc.Metadata();
     if (token !== "") {
         result.set("authorization", `bearer ${token}`);
     }
+    if (pluginVersion !== undefined && pluginVersion !== "") {
+        result.set("x-dsh-podman-plugin-version", pluginVersion);
+    }
     return result;
 }
 // defaultCwdOf returns the session working directory as a usable container

package/dist/workspace-binding.test.js

@@ -11,6 +11,7 @@ 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 { VERSION } from "./generated/version.js";
 const SLUG = "2c573001-4171-4900-904b-12a5cc02737a";
 const SLUG_SUB = "3d684112-5282-4a11-a15c-23b6dd13848b";
 test("workspaceSlug accepts a UUID workspace id", () => {
@@ -44,6 +45,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);
@@ -95,11 +102,13 @@ async function startControlServer(containers = [], options = {}) {
     const loaded = grpc.loadPackageDefinition(definition);
     const server = new grpc.Server();
     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) => {
@@ -139,13 +148,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 +165,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,

package/docs/architecture.md

@@ -24,6 +24,16 @@ 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 settings card 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),

package/docs/architecture.zh.md

@@ -23,6 +23,12 @@ dsh-podman 由三个组件组成：
 orchestrator（编排器）并通信 gRPC。请求携带共享
 token（`DSH_PODMAN_ORCHESTRATOR_TOKEN`）作为 `authorization: bearer` 标头。
 
+请求还会在 `x-dsh-podman-plugin-version` 标头中携带插件版本。插件与 orchestrator
+分别部署（前者是 dsh 镜像中的 npm 包，后者是此二进制文件），因此 orchestrator
+会拒绝来自**主版本**不同的插件的控制调用，并指出两者的版本以及哪一方更旧——不同步的部署会明确失败，而不会被误读。缺失或无法解析的版本同样会被拒绝。次版本或修订版本不同是兼容的：调用照常进行，orchestrator
+会按插件版本记录一次警告，设置卡片也会显示。`GetVersion`
+不受该检查约束，因此插件始终可以获知 orchestrator 的版本。
+
 orchestrator 服务公开以下 gRPC 方法（同时支撑 UI
 和工具）：`ListContainers`（仅返回 orchestrator 创建的 guest
 容器——它不拥有的容器永远不会被暴露）、`StartContainer{workspace_slug, container, image_id, mounts, env, secret_env, paths}`（在工作区的

package/docs/development.md

@@ -81,27 +81,54 @@ make image  # build images
 systemctl --user restart dsh dsh-podman-orchestrator
 ```
 
-### Update plugin
+### Install a local plugin build
+
+The dsh image installs the plugin itself at container start, so a development
+build is served by pointing that install at a bind-mounted package. Build the
+plugin and pack it:
 
 ```bash
-npm pack
-v="$(jq -r .version package.json)"
-podman cp ./exagone313-dsh-podman-"${v}".tgz dsh:/tmp/
-podman exec -it dsh dsh plugin --profile web remove @exagone313/dsh-podman  # necessary, to force reinstall if the same version
-podman exec -it dsh dsh plugin --profile web add /tmp/exagone313-dsh-podman-"${v}".tgz --allow-build=protobufjs
-systemctl --user restart dsh
+pnpm build
+npm pack          # writes exagone313-dsh-podman-<version>.tgz
+```
+
+Then add one of these to the dsh container unit and restart it:
+
+```
+# the repository directory, which must contain the packed archive
+Volume=/path/to/repo:/mnt/dsh-podman:ro
+Environment=DSH_PODMAN_PLUGIN_SOURCE=/mnt/dsh-podman
 ```
 
+```
+# or the archive itself
+Volume=/path/to/exagone313-dsh-podman-0.2.0-rc.3.tgz:/mnt/dsh-podman.tgz:ro
+Environment=DSH_PODMAN_PLUGIN_SOURCE=/mnt/dsh-podman.tgz
+```
+
+The entrypoint installs that package on every start and never falls back to the
+registry — a missing package is an error. Re-run `pnpm build && npm pack` and
+restart dsh to pick up changes.
+
+Without `DSH_PODMAN_PLUGIN_SOURCE`, the entrypoint installs
+`@exagone313/dsh-podman@$DSH_PODMAN_PLUGIN_VERSION` (the version baked into the
+image) exactly, upgrading or downgrading the profile's copy to match.
+
 ## Continuous integration
 
-CI (`.github/workflows/ci.yml`) runs on every branch push and pull request:
+CI runs on every **branch** push and pull request, split across
+`.github/workflows/ci-common.yml` (REUSE lint and zizmor), `ci-code.yml` (Go,
+JS, images, Trivy), `ci-docs.yml` (Deno fmt) and `ci-dsh-image.yml`. A **tag**
+push runs only `release.yml`, which repeats the build, vet and tests itself:
 
 - **actions-lint** — zizmor scans the workflows for insecure practices.
+- **reuse** — REUSE license compliance.
 - **go** — build, vet, tests, and govulncheck (Go vulnerabilities). Unfixed
   findings don't fail the job; fixable ones do.
 - **js** — install, typecheck, build, tests, and `pnpm audit`.
+- **docs** — `deno fmt --check` on the Markdown.
 - **images** — builds the orchestrator and guest-agent images (runs only after
-  the test jobs pass).
+  the test jobs pass); **dsh image** builds `Containerfile.dsh`.
 - **trivy** — filesystem vulnerability scan (unfixed ignored) and container
   misconfiguration scan (DS-0002 excluded via `.trivyignore.yaml`).
 
@@ -115,9 +142,12 @@ pre-releases like `1.0.0-rc.1` also work). The release workflow
 
 1. Runs the tests, then builds both binaries for `linux/amd64` and
    `linux/arm64`.
-2. Pushes the **orchestrator** and **guest-agent** images to GHCR
-   (`ghcr.io/exagone313/dsh-podman/{orchestrator,guest-agent}`), tagged with the
-   version plus `latest` for stable releases (pre-releases never get `latest`).
+2. Pushes the **dsh**, **orchestrator** and **guest-agent** images to GHCR
+   (`ghcr.io/exagone313/dsh-podman/{dsh,orchestrator,guest-agent}`). Every
+   release is tagged with its version; a **stable** release — `1.0.0` or above
+   with no pre-release suffix — is also tagged with its major version (`1`) and
+   `latest`. A `0.x` release and any hyphenated tag are pre-releases: they get
+   the version tag only.
 3. Publishes the plugin to **npm** (`@exagone313/dsh-podman`) with provenance;
    pre-releases are published under the `next` dist-tag.
 4. Creates a **GitHub release** with auto-generated notes and attaches the
@@ -139,4 +169,9 @@ built plugin and binaries report, since `scripts/generate-version.mjs` derives
 the embedded version from `git describe --tags`. Pre-releases (`1.0.0-rc.1`) are
 bumped the same way.
 
+A release can also be triggered, or a failed one re-run, from the Actions tab
+with `workflow_dispatch`, which takes the version as input. Already-published
+steps are skipped (npm skips a version it already has, and an existing GitHub
+release is left alone), so a retry never republishes.
+
 The `NPM_TOKEN` secret must be configured on the repository for the npm step.

package/docs/development.zh.md

@@ -79,26 +79,52 @@ make image  # build images
 systemctl --user restart dsh dsh-podman-orchestrator
 ```
 
-### 更新插件
+### 安装本地插件构建
+
+dsh 镜像会在容器启动时自行安装插件，因此本地开发构建通过将安装源指向 bind mount
+的包来使用。先构建并打包插件：
 
 ```bash
-npm pack
-v="$(jq -r .version package.json)"
-podman cp ./exagone313-dsh-podman-"${v}".tgz dsh:/tmp/
-podman exec -it dsh dsh plugin --profile web remove @exagone313/dsh-podman  # necessary, to force reinstall if the same version
-podman exec -it dsh dsh plugin --profile web add /tmp/exagone313-dsh-podman-"${v}".tgz --allow-build=protobufjs
-systemctl --user restart dsh
+pnpm build
+npm pack          # 生成 exagone313-dsh-podman-<version>.tgz
+```
+
+然后在 dsh 容器单元中加入以下之一并重启：
+
+```
+# 仓库目录，其中必须包含已打包的归档
+Volume=/path/to/repo:/mnt/dsh-podman:ro
+Environment=DSH_PODMAN_PLUGIN_SOURCE=/mnt/dsh-podman
 ```
 
+```
+# 或者归档本身
+Volume=/path/to/exagone313-dsh-podman-0.2.0-rc.3.tgz:/mnt/dsh-podman.tgz:ro
+Environment=DSH_PODMAN_PLUGIN_SOURCE=/mnt/dsh-podman.tgz
+```
+
+入口脚本会在每次启动时安装该包，且绝不会回退到注册表——找不到包即为错误。重新运行
+`pnpm build && npm pack` 并重启 dsh 即可生效。
+
+未设置 `DSH_PODMAN_PLUGIN_SOURCE` 时，入口脚本会精确安装
+`@exagone313/dsh-podman@$DSH_PODMAN_PLUGIN_VERSION`（镜像构建时写入的版本），并相应升级或降级配置中的副本。
+
 ## 持续集成
 
-CI（`.github/workflows/ci.yml`）在每次分支推送和拉取请求时运行：
+CI 在每次**分支**推送和拉取请求时运行，分散在
+`.github/workflows/ci-common.yml`（REUSE lint 与
+zizmor）、`ci-code.yml`（Go、JS、镜像、Trivy）、`ci-docs.yml`（Deno fmt）和
+`ci-dsh-image.yml` 中。推送**标签**时只运行 `release.yml`，它自身会重复构建、vet
+和测试：
 
 - **actions-lint** — zizmor 扫描工作流是否存在不安全实践。
+- **reuse** — REUSE 许可证合规检查。
 - **go** — 构建、vet、测试和 govulncheck（Go 漏洞）。未修复的
   发现不会导致任务失败；可修复的会导致失败。
 - **js** — 安装、类型检查、构建、测试和 `pnpm audit`。
-- **images** — 构建 orchestrator 和 guest-agent 镜像（仅在测试任务通过后运行）。
+- **docs** — 对 Markdown 运行 `deno fmt --check`。
+- **images** — 构建 orchestrator 和 guest-agent
+  镜像（仅在测试任务通过后运行）；**dsh image** 构建 `Containerfile.dsh`。
 - **trivy** — 文件系统漏洞扫描（未修复的被忽略）和容器 错误配置扫描（DS-0002
   通过 `.trivyignore.yaml` 排除）。
 
@@ -110,9 +136,10 @@ CI（`.github/workflows/ci.yml`）在每次分支推送和拉取请求时运行
 这样的预发布同样有效）触发。发布工作流 （`.github/workflows/release.yml`）：
 
 1. 运行测试，然后为 `linux/amd64` 和 `linux/arm64` 构建两个二进制文件。
-2. 将 **orchestrator** 和 **guest-agent** 镜像推送到 GHCR
-   （`ghcr.io/exagone313/dsh-podman/{orchestrator,guest-agent}`），并打上
-   版本号以及稳定版的 `latest` 标签（预发布永远不会获得 `latest`）。
+2. 将 **dsh**、**orchestrator** 和 **guest-agent** 镜像推送到 GHCR
+   （`ghcr.io/exagone313/dsh-podman/{dsh,orchestrator,guest-agent}`）。每个发布都打上其版本标签；**稳定**发布——`1.0.0`
+   及以上且不带预发布后缀——还会打上其主版本号（`1`）和 `latest`。`0.x`
+   发布以及任何带连字符的标签都属于预发布：只打版本标签。
 3. 将插件发布到 **npm**（`@exagone313/dsh-podman`），附带来源证明； 预发布在
    `next` dist-tag 下发布。
 4. 创建带有自动生成说明的 **GitHub release**，并附上 二进制文件和 npm tarball。
@@ -132,4 +159,8 @@ git push origin master 0.1.1
 `scripts/generate-version.mjs` 从 `git describe --tags`
 推导嵌入的版本。预发布版（`1.0.0-rc.1`）也用同样的方式递增。
 
+也可以在 Actions 页面通过 `workflow_dispatch`
+触发发布，或重新运行失败的发布，版本作为输入传入。已完成的步骤会被跳过（npm
+会跳过已存在的版本，已有的 GitHub release 不会被改动），因此重试不会重复发布。
+
 npm 步骤要求仓库配置 `NPM_TOKEN` 密钥。

package/docs/install-dsh-and-dsh-podman.md

@@ -95,12 +95,13 @@ could be added in the future.
 
 ## Installation
 
-### dsh setup
-
 This installation uses
 [Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html),
 which adds Podman integration into systemd.
 
+Note that the dsh-podman plugin will be installed at dsh container startup,
+which requires online access.
+
 1. Create the Quadlet directory for your user:
    ```bash
    mkdir -p ~/.config/containers/systemd
@@ -137,17 +138,6 @@ which adds Podman integration into systemd.
 9. Once your web browser has saved this token, you'll be able to access dsh with
    the URL [http://127.0.0.1:3080/](http://127.0.0.1:3080/).
 
-### dsh-podman plugin installation
-
-1. Run this command to install the dsh-podman plugin:
-   ```bash
-   podman exec dsh dsh plugin --profile web add @exagone313/dsh-podman --allow-build=protobufjs
-   ```
-2. Restart dsh to complete the installation:
-   ```bash
-   systemctl --user restart dsh
-   ```
-
 ## Verification
 
 - Open **Settings → Plugins → dsh-podman**: the card should list the base images

package/docs/install-dsh-and-dsh-podman.zh.md

@@ -77,12 +77,12 @@ SPDX-License-Identifier: MIT
 
 ## 安装
 
-### dsh 配置
-
 本次安装使用
 [Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html)，
 它为 systemd 增加了 Podman 集成。
 
+注意，dsh-podman 插件会在 dsh 容器启动时安装，这需要联网。
+
 1. 为你的用户创建 Quadlet 目录：
    ```bash
    mkdir -p ~/.config/containers/systemd
@@ -118,17 +118,6 @@ SPDX-License-Identifier: MIT
 9. 浏览器保存该令牌后，即可通过 [http://127.0.0.1:3080/](http://127.0.0.1:3080/)
    访问 dsh。
 
-### dsh-podman 插件安装
-
-1. 运行以下命令安装 dsh-podman 插件：
-   ```bash
-   podman exec dsh dsh plugin --profile web add @exagone313/dsh-podman --allow-build=protobufjs
-   ```
-2. 重启 dsh 以完成安装：
-   ```bash
-   systemctl --user restart dsh
-   ```
-
 ## 验证
 
 - 打开 **Settings → Plugins →

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exagone313/dsh-podman",
-  "version": "0.2.0-rc.3",
+  "version": "0.2.0-rc.4",
   "license": "MIT",
   "repository": {
     "type": "git",