@exagone313/dsh-podman 0.2.0-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Elouan Martinet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+<!--
+SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+
+SPDX-License-Identifier: MIT
+-->
+
+# dsh-podman
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/@exagone313/dsh-podman)](https://www.npmjs.com/package/@exagone313/dsh-podman)
+[![GitHub release](https://img.shields.io/github/v/release/Exagone313/dsh-podman)](https://github.com/Exagone313/dsh-podman/releases)
+[![orchestrator](https://img.shields.io/badge/orchestrator-GHCR-blue)](https://github.com/Exagone313/dsh-podman/pkgs/container/dsh-podman%2Forchestrator)
+[![guest-agent](https://img.shields.io/badge/guest--agent-GHCR-blue)](https://github.com/Exagone313/dsh-podman/pkgs/container/dsh-podman%2Fguest-agent)
+
+English | [中文](README.zh.md)
+
+[Podman](https://podman.io/)-backed execution for
+[DeepSeek Harness](https://deepseek.com/harness) (`dsh`).
+
+dsh-podman routes all shell execution and file access through disposable and
+per-project Podman containers.
+
+## Documentation
+
+- **[Install DeepSeek Harness & dsh-podman with rootless Podman](docs/install-dsh-and-dsh-podman.md)**
+- [Architecture](docs/architecture.md)
+- [Configuration](docs/configuration.md)
+- [Usage](docs/usage.md)
+- [Development](docs/development.md)
+
+## AI-usage disclosure
+
+This repository was written in major parts using AI models:
+
+- early commits using OpenAI GPT-5.6 Luna
+- DeepSeek V4 Flash
+- source code weakness fixes by Anthropic Claude Opus 5
+
+## License
+
+[MIT](./LICENSE)

package/README.zh.md

@@ -0,0 +1,41 @@
+<!--
+SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+
+SPDX-License-Identifier: MIT
+-->
+
+# dsh-podman
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/@exagone313/dsh-podman)](https://www.npmjs.com/package/@exagone313/dsh-podman)
+[![GitHub release](https://img.shields.io/github/v/release/Exagone313/dsh-podman)](https://github.com/Exagone313/dsh-podman/releases)
+[![orchestrator](https://img.shields.io/badge/orchestrator-GHCR-blue)](https://github.com/Exagone313/dsh-podman/pkgs/container/dsh-podman%2Forchestrator)
+[![guest-agent](https://img.shields.io/badge/guest--agent-GHCR-blue)](https://github.com/Exagone313/dsh-podman/pkgs/container/dsh-podman%2Fguest-agent)
+
+[English](README.md) | 中文
+
+基于 [Podman](https://podman.io/) 的
+[DeepSeek Harness](https://deepseek.com/harness)（`dsh`）执行后端。
+
+dsh-podman 将所有的 shell 执行与文件访问都路由到一次性、按项目隔离的 Podman
+容器中。
+
+## 文档
+
+- **[使用 rootless Podman 安装 DeepSeek Harness 与 dsh-podman](docs/install-dsh-and-dsh-podman.zh.md)**
+- [架构](docs/architecture.zh.md)
+- [配置](docs/configuration.zh.md)
+- [使用](docs/usage.zh.md)
+- [开发](docs/development.zh.md)
+
+## AI 使用声明
+
+本仓库的大部分代码由 AI 模型编写：
+
+- 早期提交使用 OpenAI GPT-5.6 Luna
+- DeepSeek V4 Flash
+- 源代码弱点修复由 Anthropic Claude Opus 5 完成
+
+## 许可证
+
+[MIT](./LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+#
+# SPDX-License-Identifier: MIT
+
+# dsh bundle patch: mounts the dsh-podman plugin into a profile's layer
+# stack. The subprocess/fs-sandbox/spill-local rows are disabled because this
+# plugin provides the ctx.subprocess, ctx.fs and ctx.spillStore providers backed
+# by workspace Podman containers instead.
+- id: subprocess
+  disabled: true
+- id: fs-sandbox
+  disabled: true
+- id: spill-local
+  disabled: true
+- insert:
+    - id: podman
+      name: '@exagone313/dsh-podman'

package/dist/approval-reasons.d.ts

@@ -0,0 +1,129 @@
+export type ReasonLocale = "en" | "zh";
+export interface MountFact {
+    kind: "project" | "volume" | "tmpfs" | "secret";
+    source: string;
+    destination?: string;
+    readOnly?: boolean;
+}
+export type ReasonFact = {
+    kind: "image_build";
+    image: string;
+    parent?: string;
+    packages?: readonly string[];
+} | {
+    kind: "image_rebuild";
+    image: string;
+} | {
+    kind: "image_rebuild_all";
+} | {
+    kind: "image_remove";
+    image: string;
+} | {
+    kind: "container_start" | "container_recreate";
+    container: string;
+    image?: string;
+    mounts?: readonly MountFact[];
+    env?: readonly string[];
+    paths?: readonly string[];
+} | {
+    kind: "container_remove";
+    container: string;
+} | {
+    kind: "container_mount_add";
+    container: string;
+    mount: MountFact;
+} | {
+    kind: "container_mount_remove";
+    container: string;
+    mount: MountFact;
+} | {
+    kind: "container_mount_update";
+    container: string;
+    mount: MountFact;
+} | {
+    kind: "container_path_set";
+    container: string;
+    paths: readonly string[];
+} | {
+    kind: "container_path_add";
+    container: string;
+    path: string;
+} | {
+    kind: "container_path_remove";
+    container: string;
+    path: string;
+} | {
+    kind: "read_only_remount";
+    tool: string;
+    remount: readonly MountFact[];
+    keep: readonly MountFact[];
+} | {
+    kind: "volume_remove";
+    name: string;
+} | {
+    kind: "secret_remove";
+    name: string;
+} | {
+    kind: "container_secret_add";
+    container: string;
+    secret: string;
+    env: string;
+} | {
+    kind: "container_secret_remove";
+    container: string;
+    env: string;
+} | {
+    kind: "container_bash";
+    container: string;
+    command: string;
+    cwd?: string;
+    uid?: number;
+    gid?: number;
+    groups?: readonly number[];
+} | {
+    kind: "container_exec";
+    container: string;
+    argv: readonly string[];
+    cwd?: string;
+    uid?: number;
+    gid?: number;
+    groups?: readonly number[];
+} | {
+    kind: "container_write";
+    container: string;
+    path: string;
+} | {
+    kind: "container_edit";
+    container: string;
+    path: string;
+} | {
+    kind: "daemon_start";
+    container: string;
+    argv: readonly string[];
+    name?: string;
+    uid?: number;
+    gid?: number;
+    groups?: readonly number[];
+};
+export type DenialFact = {
+    kind: "read_only";
+    tool: string;
+} | {
+    kind: "read_only_builtin";
+    tool: string;
+} | {
+    kind: "read_only_remount_declined";
+    tool: string;
+} | {
+    kind: "project_destination";
+    source?: string;
+    mirror?: string;
+};
+export interface SettingsReader {
+    get(ns: string): unknown;
+}
+export declare function resolveReasonLocale(settings: SettingsReader | undefined): ReasonLocale;
+export declare function reasonLocale(value: unknown): ReasonLocale;
+export declare function renderReason(locale: ReasonLocale, fact: ReasonFact): string;
+export declare function renderCacheCleanNotice(locale: ReasonLocale, files: number): string;
+export declare function renderDenial(locale: ReasonLocale, fact: DenialFact): string;

package/dist/approval-reasons.js

@@ -0,0 +1,253 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import { CONTAINER_NS } from "./settings-schema.js";
+// Settings namespace owned by the browser locale plugin; only read here.
+const LOCALE_NS = "locale";
+const LOCALE_PREFERENCE_FIELD = "preference";
+// The locale to render approval text in: the client-observed active locale
+// first (it also captures the browser default), then the durable user
+// preference, then English.
+export function resolveReasonLocale(settings) {
+    if (settings === undefined)
+        return "en";
+    const observed = field(settings.get(CONTAINER_NS), "uiLocale");
+    if (typeof observed === "string" && observed !== "")
+        return reasonLocale(observed);
+    return reasonLocale(field(settings.get(LOCALE_NS), LOCALE_PREFERENCE_FIELD));
+}
+// Normalize a BCP 47-style locale id to a shipped language; `zh-Hans`, `zh_CN`
+// and friends all map to `zh`, everything else to English.
+export function reasonLocale(value) {
+    if (typeof value !== "string")
+        return "en";
+    const primary = value.toLowerCase().split(/[-_]/, 1)[0];
+    return primary === "zh" ? "zh" : "en";
+}
+function field(value, key) {
+    return typeof value === "object" && value !== null
+        ? value[key]
+        : undefined;
+}
+// Pick the locale's variant of one string.
+function pick(locale, en, zh) {
+    return locale === "zh" ? zh : en;
+}
+// Quote one identifier with the locale's quote marks.
+function quoted(locale, value) {
+    return pick(locale, `"${value}"`, `“${value}”`);
+}
+// Join list elements, capping at 8 with a localized "more" tail.
+const LIST_CAP = 8;
+function joinList(locale, items) {
+    if (items.length === 0)
+        return "";
+    const separator = pick(locale, ", ", "、");
+    const shown = items.slice(0, LIST_CAP).join(separator);
+    const extra = items.length - LIST_CAP;
+    return extra > 0
+        ? pick(locale, `${shown}, +${extra} more`, `${shown}，另有 ${extra} 项`)
+        : shown;
+}
+// Render a mount's source name: `volume "data"`, `project "team/src"`,
+// `secret "valkey-tls"`, or `tmpfs`.
+function mountLabel(locale, mount) {
+    const name = quoted(locale, mount.source);
+    switch (mount.kind) {
+        case "tmpfs":
+            return "tmpfs";
+        case "volume":
+            return pick(locale, `volume ${name}`, `卷 ${name}`);
+        case "secret":
+            return pick(locale, `secret ${name}`, `机密 ${name}`);
+        default:
+            return pick(locale, `project ${name}`, `项目 ${name}`);
+    }
+}
+// Render a mount's destination clause (`at "/data"` / `挂载到 “/data”`), or
+// undefined when it has none. The caller supplies the surrounding punctuation,
+// since the locales wrap it differently.
+function mountDestinationText(locale, mount) {
+    return mount.destination === undefined
+        ? undefined
+        : pick(locale, `at ${quoted(locale, mount.destination)}`, `挂载到 ${quoted(locale, mount.destination)}`);
+}
+// Render a mount's source and destination: `volume "data" at "/data"`.
+function mountSourceText(locale, mount) {
+    const destination = mountDestinationText(locale, mount);
+    const label = mountLabel(locale, mount);
+    return destination === undefined ? label : `${label} ${destination}`;
+}
+// A mount's mode as a bare word (`read-only` / `read-write`), or undefined when
+// the call carries no mode or the kind has none (tmpfs is always read-write and
+// secrets take none).
+function mountModeName(locale, mount) {
+    if (mount.readOnly === undefined ||
+        mount.kind === "tmpfs" ||
+        mount.kind === "secret") {
+        return undefined;
+    }
+    return mount.readOnly
+        ? pick(locale, "read-only", "只读")
+        : pick(locale, "read-write", "读写");
+}
+// Render one mount as `volume "data" at "/data" (read-only)`.
+function mountText(locale, mount) {
+    const mode = mountModeName(locale, mount);
+    const suffix = mode === undefined ? "" : pick(locale, ` (${mode})`, `（${mode}）`);
+    return `${mountSourceText(locale, mount)}${suffix}`;
+}
+// Render a command word list, capped at 8 words with an ellipsis tail.
+function argvText(argv) {
+    const shown = argv.slice(0, 8).join(" ");
+    return argv.length > 8 ? `${shown} …` : shown;
+}
+// identityText renders the process identity a call requests as a parenthesized
+// suffix, or "" when it requests none. Shared by every tool that can run a
+// process as another user.
+function identityText(locale, fact) {
+    const ids = [];
+    if (fact.uid !== undefined)
+        ids.push(`uid ${fact.uid}`);
+    if (fact.gid !== undefined)
+        ids.push(`gid ${fact.gid}`);
+    if (fact.groups !== undefined && fact.groups.length > 0) {
+        ids.push(`groups ${joinList(locale, fact.groups.map((group) => String(group)))}`);
+    }
+    return ids.length === 0 ? "" : pick(locale, ` (${ids.join(", ")})`, `（${ids.join("、")}）`);
+}
+// Start/recreate share one shape; only the verb differs.
+function containerRun(locale, fact) {
+    const image = fact.image === undefined
+        ? ""
+        : pick(locale, ` from image ${quoted(locale, fact.image)}`, `（镜像 ${quoted(locale, fact.image)}）`);
+    const mounts = fact.mounts === undefined || fact.mounts.length === 0
+        ? ""
+        : pick(locale, ` with mounts: ${joinList(locale, fact.mounts.map((mount) => mountText(locale, mount)))}`, `，挂载：${joinList(locale, fact.mounts.map((mount) => mountText(locale, mount)))}`);
+    const env = fact.env === undefined || fact.env.length === 0
+        ? ""
+        : pick(locale, ` with env: ${joinList(locale, fact.env)}`, `，环境变量：${joinList(locale, fact.env)}`);
+    const paths = fact.paths === undefined || fact.paths.length === 0
+        ? ""
+        : pick(locale, ` with PATH additions: ${joinList(locale, fact.paths.map((path) => quoted(locale, path)))}`, `，PATH 附加项：${joinList(locale, fact.paths.map((path) => quoted(locale, path)))}`);
+    const verb = fact.kind === "container_start"
+        ? pick(locale, "Start", "启动")
+        : pick(locale, "Recreate", "重建");
+    return pick(locale, `${verb} container ${quoted(locale, fact.container)}${image}${mounts}${env}${paths}.`, `${verb}容器 ${quoted(locale, fact.container)}${image}${mounts}${env}${paths}。`);
+}
+// Render one reason as the single-line headline shown in the approval prompt.
+// Reasons that end in a raw command keep no trailing period, so the command
+// reads as typed.
+export function renderReason(locale, fact) {
+    switch (fact.kind) {
+        case "image_build": {
+            const parent = fact.parent === undefined
+                ? ""
+                : pick(locale, ` from ${quoted(locale, fact.parent)}`, `（基于 ${quoted(locale, fact.parent)}）`);
+            const packages = fact.packages === undefined
+                ? ""
+                : pick(locale, ` with packages: ${joinList(locale, fact.packages)}`, `，软件包：${joinList(locale, fact.packages)}`);
+            return pick(locale, `Build image ${quoted(locale, fact.image)}${parent}${packages}.`, `构建镜像 ${quoted(locale, fact.image)}${parent}${packages}。`);
+        }
+        case "image_rebuild":
+            return pick(locale, `Rebuild image ${quoted(locale, fact.image)}.`, `重建镜像 ${quoted(locale, fact.image)}。`);
+        case "image_rebuild_all":
+            return pick(locale, "Rebuild all images.", "重建全部镜像。");
+        case "image_remove":
+            return pick(locale, `Remove image ${quoted(locale, fact.image)}.`, `移除镜像 ${quoted(locale, fact.image)}。`);
+        case "container_start":
+        case "container_recreate":
+            return containerRun(locale, fact);
+        case "container_remove":
+            return pick(locale, `Remove container ${quoted(locale, fact.container)}.`, `移除容器 ${quoted(locale, fact.container)}。`);
+        case "container_mount_add":
+            return pick(locale, `Add mount to container ${quoted(locale, fact.container)}: ${mountText(locale, fact.mount)}.`, `在容器 ${quoted(locale, fact.container)} 中添加挂载：${mountText(locale, fact.mount)}。`);
+        case "container_mount_remove":
+            return pick(locale, `Remove mount from container ${quoted(locale, fact.container)}: ${mountText(locale, fact.mount)}.`, `从容器 ${quoted(locale, fact.container)} 中移除挂载：${mountText(locale, fact.mount)}。`);
+        case "container_mount_update": {
+            const destination = mountDestinationText(locale, fact.mount);
+            const mode = mountModeName(locale, fact.mount) ?? "";
+            // The zh sentence separates the mount from the verb with a space after a
+            // quoted name, but a full-width parenthetical needs none.
+            const target = destination === undefined
+                ? `${mountLabel(locale, fact.mount)} `
+                : `${mountLabel(locale, fact.mount)}（${destination}）`;
+            return pick(locale, `Update mount in container ${quoted(locale, fact.container)}: remount ${mountSourceText(locale, fact.mount)} to ${mode}.`, `更新容器 ${quoted(locale, fact.container)} 中的挂载：将${target}重新挂载为${mode}。`);
+        }
+        case "container_path_set": {
+            const list = fact.paths.length === 0
+                ? pick(locale, "(none)", "（无）")
+                : joinList(locale, fact.paths.map((path) => quoted(locale, path)));
+            return pick(locale, `Set the PATH additions of container ${quoted(locale, fact.container)}: ${list}.`, `设置容器 ${quoted(locale, fact.container)} 的 PATH 附加项：${list}。`);
+        }
+        case "container_path_add":
+            return pick(locale, `Add ${quoted(locale, fact.path)} to the PATH of container ${quoted(locale, fact.container)}.`, `将 ${quoted(locale, fact.path)} 添加到容器 ${quoted(locale, fact.container)} 的 PATH 中。`);
+        case "container_path_remove":
+            return pick(locale, `Remove ${quoted(locale, fact.path)} from the PATH of container ${quoted(locale, fact.container)}.`, `从容器 ${quoted(locale, fact.container)} 的 PATH 中移除 ${quoted(locale, fact.path)}。`);
+        case "read_only_remount": {
+            const remount = fact.remount
+                .map((mount) => `- ${mountText(locale, mount)}`)
+                .join("\n");
+            const keep = fact.keep.length === 0
+                ? ""
+                : pick(locale, `\n\nKept as-is: ${joinList(locale, fact.keep.map((mount) => mountText(locale, mount)))}.`, `\n\n保持不变：${joinList(locale, fact.keep.map((mount) => mountText(locale, mount)))}。`);
+            return pick(locale, `Read-only mode blocks ${quoted(locale, fact.tool)} while a mount is read-write. Remount these mounts read-only to run it:\n\n${remount}${keep}`, `只读模式在存在读写挂载时会阻止 ${quoted(locale, fact.tool)}。将这些挂载重新挂载为只读即可运行：\n\n${remount}${keep}`);
+        }
+        case "volume_remove":
+            return pick(locale, `Remove volume ${quoted(locale, fact.name)}.`, `移除卷 ${quoted(locale, fact.name)}。`);
+        case "secret_remove":
+            return pick(locale, `Remove secret ${quoted(locale, fact.name)}.`, `移除机密 ${quoted(locale, fact.name)}。`);
+        case "container_secret_add":
+            return pick(locale, `Attach secret ${quoted(locale, fact.secret)} to container ${quoted(locale, fact.container)} as ${quoted(locale, fact.env)}.`, `将机密 ${quoted(locale, fact.secret)} 作为 ${quoted(locale, fact.env)} 注入容器 ${quoted(locale, fact.container)}。`);
+        case "container_secret_remove":
+            return pick(locale, `Detach secret env var ${quoted(locale, fact.env)} from container ${quoted(locale, fact.container)}.`, `从容器 ${quoted(locale, fact.container)} 中移除机密环境变量 ${quoted(locale, fact.env)}。`);
+        case "container_bash": {
+            const cwd = fact.cwd === undefined
+                ? ""
+                : pick(locale, ` (cwd ${quoted(locale, fact.cwd)})`, `（工作目录 ${quoted(locale, fact.cwd)}）`);
+            const identity = identityText(locale, fact);
+            return pick(locale, `Run a shell command in container ${quoted(locale, fact.container)}${cwd}: ${fact.command}${identity}`, `在容器 ${quoted(locale, fact.container)}${cwd} 中运行 shell 命令：${fact.command}${identity}`);
+        }
+        case "container_exec": {
+            const cwd = fact.cwd === undefined
+                ? ""
+                : pick(locale, ` (cwd ${quoted(locale, fact.cwd)})`, `（工作目录 ${quoted(locale, fact.cwd)}）`);
+            const identity = identityText(locale, fact);
+            return pick(locale, `Run a command in container ${quoted(locale, fact.container)}${cwd}: ${argvText(fact.argv)}${identity}`, `在容器 ${quoted(locale, fact.container)}${cwd} 中运行命令：${argvText(fact.argv)}${identity}`);
+        }
+        case "container_write":
+            return pick(locale, `Write ${quoted(locale, fact.path)} in container ${quoted(locale, fact.container)}.`, `在容器 ${quoted(locale, fact.container)} 中写入 ${quoted(locale, fact.path)}。`);
+        case "container_edit":
+            return pick(locale, `Edit ${quoted(locale, fact.path)} in container ${quoted(locale, fact.container)}.`, `在容器 ${quoted(locale, fact.container)} 中编辑 ${quoted(locale, fact.path)}。`);
+        case "daemon_start": {
+            const named = fact.name === undefined ? "" : ` ${quoted(locale, fact.name)}`;
+            const suffix = identityText(locale, fact);
+            return pick(locale, `Start daemon${named} in container ${quoted(locale, fact.container)}: ${argvText(fact.argv)}${suffix}`, `在容器 ${quoted(locale, fact.container)} 中启动守护进程${named}：${argvText(fact.argv)}${suffix}`);
+        }
+    }
+}
+// Render the settings notice shown after a cache cleanup. The card already
+// shows the resulting sizes, so the notice only names how many files went.
+export function renderCacheCleanNotice(locale, files) {
+    return pick(locale, `removed ${files} cached ${files === 1 ? "file" : "files"}`, `已移除 ${files} 个缓存文件`);
+}
+// Render one policy denial.
+export function renderDenial(locale, fact) {
+    switch (fact.kind) {
+        case "read_only":
+            return pick(locale, `Denied: the session is read-only, but ${quoted(locale, fact.tool)} needs write access.`, `已拒绝：当前会话为只读，而 ${quoted(locale, fact.tool)} 需要写入权限。`);
+        case "read_only_builtin":
+            return pick(locale, `Denied: the session is read-only, but ${quoted(locale, fact.tool)} can modify files.`, `已拒绝：当前会话为只读，而 ${quoted(locale, fact.tool)} 可能修改文件。`);
+        case "read_only_remount_declined":
+            return pick(locale, `Denied: read-only mode blocks ${quoted(locale, fact.tool)} and the mounts were not remounted.`, `已拒绝：只读模式阻止 ${quoted(locale, fact.tool)}，且挂载未被重新挂载。`);
+        case "project_destination": {
+            if (fact.mirror === undefined || fact.mirror === "") {
+                return pick(locale, "Project mounts cannot set a destination.", "项目挂载不能指定目标路径。");
+            }
+            const source = fact.source === undefined || fact.source === ""
+                ? pick(locale, "the project", "该项目")
+                : quoted(locale, fact.source);
+            return pick(locale, `Project mounts cannot set a destination; ${source} always mounts at ${quoted(locale, fact.mirror)}.`, `项目挂载不能指定目标路径；${source} 始终挂载到 ${quoted(locale, fact.mirror)}。`);
+        }
+    }
+}

package/dist/approval-reasons.test.d.ts

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

package/dist/approval-reasons.test.js

@@ -0,0 +1,115 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import test from "node:test";
+import assert from "node:assert/strict";
+import { reasonLocale, renderCacheCleanNotice, renderDenial, renderReason, resolveReasonLocale, } from "./approval-reasons.js";
+import { preExecutePolicy, summarizeArgs } from "./index.js";
+import { testReadSession } from "./test-support.js";
+test("reasonLocale normalizes a locale id to a shipped language", () => {
+    assert.equal(reasonLocale("zh"), "zh");
+    assert.equal(reasonLocale("zh-Hans"), "zh");
+    assert.equal(reasonLocale("zh_CN"), "zh");
+    assert.equal(reasonLocale("ZH"), "zh");
+    assert.equal(reasonLocale("en-US"), "en");
+    assert.equal(reasonLocale("fr"), "en");
+    assert.equal(reasonLocale(undefined), "en");
+    assert.equal(reasonLocale(42), "en");
+});
+test("resolveReasonLocale prefers the client-observed locale over the preference", () => {
+    const settings = (container, locale) => ({
+        get: (ns) => (ns === "podman" ? container : ns === "locale" ? locale : undefined),
+    });
+    assert.equal(resolveReasonLocale(undefined), "en");
+    assert.equal(resolveReasonLocale(settings({ uiLocale: "zh" }, { preference: "en" })), "zh");
+    assert.equal(resolveReasonLocale(settings({ uiLocale: "" }, { preference: "zh" })), "zh");
+    assert.equal(resolveReasonLocale(settings({}, { preference: "zh" })), "zh");
+    assert.equal(resolveReasonLocale(settings({ uiLocale: "en" }, { preference: "zh" })), "en");
+    assert.equal(resolveReasonLocale(settings({}, {})), "en");
+});
+test("summarizeArgs renders reasons in Chinese when asked", () => {
+    assert.equal(summarizeArgs("container_mount_add", {
+        container: "web",
+        kind: "volume",
+        volume: "valkey-data",
+        destination: "/data",
+        mode: "read_only",
+    }, undefined, "zh"), "在容器 “web” 中添加挂载：卷 “valkey-data” 挂载到 “/data”（只读）。");
+    assert.equal(summarizeArgs("container_start", {
+        container: "web",
+        image: "img",
+        mounts: [{ project: "team", mode: "read_only" }],
+        env: { A: "1" },
+    }, undefined, "zh"), "启动容器 “web”（镜像 “img”），挂载：项目 “team”（只读），环境变量：A。");
+});
+test("renderDenial renders both languages", () => {
+    assert.equal(renderDenial("en", { kind: "read_only", tool: "container_start" }), 'Denied: the session is read-only, but "container_start" needs write access.');
+    assert.equal(renderDenial("zh", { kind: "read_only", tool: "container_start" }), "已拒绝：当前会话为只读，而 “container_start” 需要写入权限。");
+    assert.equal(renderDenial("zh", {
+        kind: "project_destination",
+        source: "team/src",
+        mirror: "/projects/team/src",
+    }), "项目挂载不能指定目标路径；“team/src” 始终挂载到 “/projects/team/src”。");
+    assert.equal(renderDenial("zh", { kind: "project_destination" }), "项目挂载不能指定目标路径。");
+    assert.equal(renderDenial("en", { kind: "project_destination", mirror: "/projects" }), 'Project mounts cannot set a destination; the project always mounts at "/projects".');
+    assert.equal(renderDenial("zh", { kind: "project_destination", mirror: "/projects" }), "项目挂载不能指定目标路径；该项目 始终挂载到 “/projects”。");
+});
+test("renderReason covers the remaining reason kinds in both languages", () => {
+    assert.equal(renderReason("en", { kind: "image_rebuild_all" }), "Rebuild all images.");
+    assert.equal(renderReason("zh", { kind: "image_rebuild_all" }), "重建全部镜像。");
+    assert.equal(renderReason("zh", { kind: "daemon_start", container: "c", argv: ["x"], uid: 1 }), "在容器 “c” 中启动守护进程：x（uid 1）");
+    assert.equal(renderReason("zh", {
+        kind: "container_bash",
+        container: "c",
+        command: "id",
+        uid: 1,
+        groups: [3, 4],
+    }), "在容器 “c” 中运行 shell 命令：id（uid 1、groups 3、4）");
+    assert.equal(renderReason("zh", { kind: "container_secret_add", container: "c", secret: "s", env: "E" }), "将机密 “s” 作为 “E” 注入容器 “c”。");
+    assert.equal(renderReason("zh", {
+        kind: "container_mount_update",
+        container: "valkey-ctr",
+        mount: { kind: "volume", source: "valkey-data", destination: "/data", readOnly: false },
+    }), "更新容器 “valkey-ctr” 中的挂载：将卷 “valkey-data”（挂载到 “/data”）重新挂载为读写。");
+    assert.equal(renderReason("zh", {
+        kind: "container_mount_update",
+        container: "web",
+        mount: { kind: "project", source: "team", readOnly: true },
+    }), "更新容器 “web” 中的挂载：将项目 “team” 重新挂载为只读。");
+});
+test("renderCacheCleanNotice reports the removed file count", () => {
+    assert.equal(renderCacheCleanNotice("en", 1), "removed 1 cached file");
+    assert.equal(renderCacheCleanNotice("en", 3), "removed 3 cached files");
+    assert.equal(renderCacheCleanNotice("zh", 3), "已移除 3 个缓存文件");
+});
+test("renderReason renders the read-only remount plan", () => {
+    assert.equal(renderReason("en", {
+        kind: "read_only_remount",
+        tool: "bash",
+        remount: [
+            { kind: "project", source: "team", readOnly: false },
+            { kind: "volume", source: "data", destination: "/data", readOnly: false },
+        ],
+        keep: [{ kind: "tmpfs", source: "", destination: "/scratch" }],
+    }), 'Read-only mode blocks "bash" while a mount is read-write. Remount these mounts read-only to run it:\n\n- project "team" (read-write)\n- volume "data" at "/data" (read-write)\n\nKept as-is: tmpfs at "/scratch".');
+    assert.equal(renderReason("zh", {
+        kind: "read_only_remount",
+        tool: "bash",
+        remount: [{ kind: "project", source: "team", readOnly: false }],
+        keep: [],
+    }), "只读模式在存在读写挂载时会阻止 “bash”。将这些挂载重新挂载为只读即可运行：\n\n- 项目 “team”（读写）");
+});
+test("renderDenial renders the declined remount", () => {
+    assert.equal(renderDenial("en", { kind: "read_only_remount_declined", tool: "bash" }), 'Denied: read-only mode blocks "bash" and the mounts were not remounted.');
+    assert.equal(renderDenial("zh", { kind: "read_only_remount_declined", tool: "bash" }), "已拒绝：只读模式阻止 “bash”，且挂载未被重新挂载。");
+});
+test("preExecutePolicy renders a localized deny reason", async () => {
+    const denied = (await preExecutePolicy({ name: "container_start", agent: { session: { facts: { mode: "read-only" } } } }, () => Promise.resolve({ kind: "allow" }), undefined, () => "zh", testReadSession));
+    assert.equal(denied.kind, "deny");
+    assert.equal(denied.reason, "已拒绝：当前会话为只读，而 “container_start” 需要写入权限。");
+});
+test("preExecutePolicy renders a localized deny reason for a built-in tool", async () => {
+    const denied = (await preExecutePolicy({ name: "bash", agent: { session: { facts: { mode: "read-only" } } } }, () => Promise.resolve({ kind: "allow" }), undefined, () => "zh", testReadSession));
+    assert.equal(denied.kind, "deny");
+    assert.equal(denied.reason, "已拒绝：当前会话为只读，而 “bash” 可能修改文件。");
+});

package/dist/approval.d.ts

@@ -0,0 +1,29 @@
+import { type ReadOnlyShellDecision } from "./read-only-shell.js";
+import { type ReasonFact, type ReasonLocale } from "./approval-reasons.js";
+export declare function reasonFact(name: string, args: Record<string, unknown>, sessionCwd?: unknown): ReasonFact | undefined;
+export declare function summarizeArgs(name: string, args: Record<string, unknown>, sessionCwd?: unknown, locale?: ReasonLocale): string;
+export declare function approvalDecision(name: string, args?: Record<string, unknown>, sessionCwd?: unknown, locale?: ReasonLocale): {
+    kind: "ask";
+    reason?: string;
+} | undefined;
+export declare const READ_ONLY_TOOLS: ReadonlySet<string>;
+export declare const PODMAN_OPS_PRESET = "podman-ops";
+export declare const PODMAN_OPS_APPROVAL_TOOLS: ReadonlySet<string>;
+export interface SessionFacts {
+    /** Effective sandbox mode ("read-only", "workspace-write", …). */
+    mode?: string;
+    /** Effective approval policy ("ask", "never", …). */
+    policy?: string;
+    /** The preset the session currently runs. */
+    preset?: string;
+}
+export declare function preExecutePolicy(exec: {
+    name: string;
+    arguments?: unknown;
+    agent?: {
+        session?: unknown;
+    };
+}, next: () => Promise<unknown>, getProjectsRoot?: () => string, getLocale?: () => ReasonLocale, readSession?: (session: unknown) => SessionFacts, readOnlyShell?: (exec: unknown, locale: ReasonLocale) => Promise<ReadOnlyShellDecision>): Promise<unknown>;
+export declare function mountDestinationsReason(name: string, args: Record<string, unknown> | undefined, projectsRoot: string | undefined, locale?: ReasonLocale): string | undefined;
+export declare const SANDBOX_ESCALATION_REASON_PREFIX = "escalate sandbox to ";
+export declare function isSandboxEscalation(request: unknown): boolean;