@fitlab-ai/agent-infra 0.5.9 → 0.6.0

package/README.md

@@ -16,7 +16,7 @@
   <a href="https://www.npmjs.com/package/@fitlab-ai/agent-infra"><img src="https://img.shields.io/npm/v/@fitlab-ai/agent-infra" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/@fitlab-ai/agent-infra"><img src="https://img.shields.io/npm/dm/@fitlab-ai/agent-infra" alt="npm downloads"></a>
   <a href="License.txt"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
-  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D18-brightgreen?logo=node.js" alt="Node.js >= 18"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D22-brightgreen?logo=node.js" alt="Node.js >= 22"></a>
   <a href="https://github.com/fitlab-ai/agent-infra/releases"><img src="https://img.shields.io/github/v/release/fitlab-ai/agent-infra" alt="GitHub release"></a>
   <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
 </p>
@@ -201,6 +201,101 @@ The sandbox image also preinstalls `gh`. When `gh auth token` succeeds on the ho
 
 `ai sandbox exec` also forwards a small terminal-detection whitelist (`TERM_PROGRAM`, `TERM_PROGRAM_VERSION`, `LC_TERMINAL`, `LC_TERMINAL_VERSION`) into the container. This keeps interactive TUIs aligned with the host terminal for behaviors such as Claude Code's Shift+Enter newline support, without passing through the full host environment.
 
+`ai sandbox exec` and `ai sandbox refresh` reconcile Claude Code credentials in both directions across the host credential store and every sandbox project copy under `~/.agent-infra/credentials/*`. When a long-running sandbox refreshes OAuth tokens first, the next entry or refresh command writes the freshest valid copy back to the host Keychain or `~/.claude/.credentials.json`; when the host is fresher, it updates the project copies. If every copy is stale, `ai sandbox refresh` probes `claude /status` and asks you to log in only when the probe cannot recover credentials.
+
+### Host-sandbox file exchange
+
+`ai sandbox create` mounts two writable directories for dropping files between
+the host and the sandbox without polluting the git worktree:
+
+- `/share/common` <- `~/.agent-infra/share/<project>/common/` - visible to every
+  sandbox of the same project, regardless of branch.
+- `/share/branch` <- `~/.agent-infra/share/<project>/branches/<branch>/` -
+  exclusive to the current branch sandbox.
+
+These paths are intentionally hardcoded; there is no `.airc.json` knob. Both
+host directories are created automatically on first `create`. When you
+`ai sandbox rm <branch>` or `ai sandbox rm --all`, you will be prompted (default
+yes) to clean up the corresponding share dirs alongside the worktrees.
+Existing sandboxes pick up these mounts after `ai sandbox rm <branch>` and
+`ai sandbox create <branch>`.
+
+### User-level dotfiles channel
+
+`ai sandbox create` also mounts an optional read-only channel for host user preferences:
+
+- `/dotfiles` <- `~/.agent-infra/dotfiles/` - read-only, host-owned source.
+
+The host tree mirrors the expected paths under the container `$HOME`, in the
+same style as GNU stow or chezmoi:
+
+```text
+~/.agent-infra/dotfiles/
+├── .tmux.conf
+└── .config/
+    ├── lazygit/config.yml
+    └── yazi/yazi.toml
+```
+
+On each sandbox entry, `sandbox-dotfiles-link` links every file to
+`$HOME/<relative-path>` with `ln -sfn`, overriding image defaults. If the host
+directory does not exist, the mount and link step are skipped.
+
+To add future preferences such as `starship.toml` or `.gitconfig.local`, put
+files in `~/.agent-infra/dotfiles/`; no Dockerfile or `ai sandbox create`
+changes are needed.
+
+#### Symlinks as pointers to host files
+
+You can place symlinks inside `~/.agent-infra/dotfiles/` to point at real files
+on your host:
+
+```bash
+ln -s ~/.tmux.conf ~/.agent-infra/dotfiles/.tmux.conf
+ln -s ~/.config/lazygit ~/.agent-infra/dotfiles/.config/lazygit
+```
+
+Before each `ai sandbox create` and `ai sandbox enter`, agent-infra
+dereferences the dotfiles tree into
+`~/.agent-infra/.cache/dotfiles-resolved/<project>/` and mounts that snapshot
+into the container. Editing the host source file, then re-entering the sandbox,
+is enough to pick up the latest content.
+
+Dangling symlinks are skipped with a stderr warning. Symlink cycles and deeply
+nested directories beyond 32 levels are also skipped with a warning. Symlinks
+pointing outside `$HOME` are accepted as long as the host user can read the
+target.
+
+> **Do not put secrets in `~/.agent-infra/dotfiles/`.** The mount is read-only
+> inside the container, but the full preference tree is linked into every
+> project sandbox. Do not place `.ssh/`, `.aws/credentials`, `.netrc`,
+> `.gnupg/`, `.npmrc` files containing `_authToken`, AI tool OAuth/access token
+> files, or `.gitconfig` there. Use the dedicated SSH and credential channels,
+> and prefer `.gitconfig.local` with `[include]` for local Git preferences.
+
+**Protected paths** are ignored by the hook even if they appear under
+`~/.agent-infra/dotfiles/`:
+
+| Path pattern | Reason |
+|---|---|
+| `.ssh/*` | Host SSH credentials are managed by the read-only SSH mount. |
+| `.gnupg/*` | GPG private material is managed by `gpg-agent`. |
+| `.claude/*`, `.codex/*`, `.gemini/*` | AI tool credentials use dedicated bind mounts. |
+| `.config/opencode/*`, `.local/share/opencode/*` | OpenCode credentials and data use dedicated bind mounts. |
+| `.host-shell-config/*` | agent-infra managed shell and Git configuration. |
+| `.gitconfig`, `.gitignore_global`, `.stCommitMsg`, `.bash_aliases` | agent-infra symlinks these to `.host-shell-config/`, including `safe.directory` and GPG sync state. |
+
+Other existing real directories, such as `~/.config/` or `~/.cache/`, are not
+replaced by top-level dotfiles. If a file conflicts with one of those
+directories, the hook prints a warning and skips it:
+
+```text
+sandbox-dotfiles-link: skipping /home/devuser/.config (existing directory; use nested path like .config/<file> instead)
+```
+
+Use nested paths such as `~/.agent-infra/dotfiles/.config/lazygit/config.yml`
+instead of treating `.config` as a top-level file.
+
 <a id="architecture-overview"></a>
 
 ## Architecture Overview
@@ -240,13 +335,65 @@ agent-infra is intentionally simple: a bootstrap CLI creates the seed configurat
 
 ## Platform Support
 
-agent-infra runs on macOS and Linux. The CLI itself only needs Node.js (>=18); container-related features (`ai sandbox *`) additionally need Docker.
+agent-infra runs on macOS, Linux, and Windows. The CLI itself only needs Node.js (>=22); container-related features (`ai sandbox *`) additionally need Docker.
+
+### Sandbox engine selection
+
+`sandbox.engine` in `.agents/.airc.json` selects the container engine. When it is `null` or omitted, agent-infra uses the platform default:
+
+- Linux: `native`
+- macOS: `colima`
+- Windows: `wsl2`
+
+You can override the engine in `.agents/.airc.json`. Valid engines are platform-specific:
+
+- Linux: `native`, `docker-desktop`
+- macOS: `colima`, `orbstack`, `docker-desktop`
+- Windows: `wsl2`, `native`, `docker-desktop`
 
 ### macOS
 
 - `ai init`, `ai sync`, etc.: works out of the box after `npm install -g @fitlab-ai/agent-infra` (or Homebrew).
 - `ai sandbox *`: requires Colima, OrbStack, or Docker Desktop. Colima is the default engine on macOS — when it is selected and the `colima` command is missing, agent-infra auto-installs and starts Colima via Homebrew on first run. To use OrbStack or Docker Desktop instead, set `sandbox.engine` in `.agents/.airc.json`.
 
+#### Engine resource configuration
+
+| Engine | `vm.cpu` | `vm.memory` | `vm.disk` | Apply mode | Notes |
+|--------|----------|-------------|-----------|------------|-------|
+| Colima | applied | applied | applied | on-start | VM must be restarted (`ai sandbox vm stop && ai sandbox vm start`) for changes to take effect. |
+| OrbStack | applied | applied | warned | hot | Applied via `orb config set` on every invocation. OrbStack manages disk via thin provisioning. |
+| Docker Desktop | warned | warned | warned | manual | Resources must be set in Docker Desktop GUI (Settings -> Resources). |
+
+`vm.memory` and `--memory` values are expressed in GiB.
+
+#### SSH / locked keychain
+
+On macOS over SSH, the login keychain may be locked and reject non-interactive reads or writes with `errSecInteractionNotAllowed`. You can unlock it on the host and re-run `ai sandbox refresh`:
+
+```bash
+security unlock-keychain ~/Library/Keychains/login.keychain-db
+ai sandbox refresh
+```
+
+For long-lived SSH sessions or CI, bypass the keychain with `AGENT_INFRA_CLAUDE_CREDENTIALS_FILE`. macOS stores Claude Code credentials in the keychain by default, so seed the override file once from a session where the keychain is unlocked:
+
+```bash
+security unlock-keychain ~/Library/Keychains/login.keychain-db
+umask 077 && mkdir -p "$HOME/.agent-infra" && \
+  security find-generic-password -s "Claude Code-credentials" -w \
+  > "$HOME/.agent-infra/claude-credentials.json"
+chmod 600 "$HOME/.agent-infra/claude-credentials.json"
+```
+
+Then on the SSH / CI side:
+
+```bash
+export AGENT_INFRA_CLAUDE_CREDENTIALS_FILE="$HOME/.agent-infra/claude-credentials.json"
+ai sandbox refresh
+```
+
+After that, sandbox create, exec, and refresh use the file instead of the keychain for Claude Code credential reads and writes.
+
 ### Linux
 
 - `ai init`, `ai sync`, etc.: works out of the box after `npm install -g @fitlab-ai/agent-infra`.
@@ -264,18 +411,63 @@ agent-infra runs on macOS and Linux. The CLI itself only needs Node.js (>=18); c
 
   GPG signing works when the host `gpg-agent` and signing key are available; if key sync fails, `ai sandbox create` falls back to a sanitized Git config so commits still work without host signing state.
 
+#### Engine resource configuration
+
+Linux uses native Docker on the host kernel, so there is no managed VM. `sandbox.vm.*` and the `--cpu / --memory` flags do not apply. To cap container resources, use `docker run --cpus / --memory` per container or configure host cgroups.
+
+#### Rootless Docker (optional)
+
+**Skip this section if you followed the Quick setup above.** The Quick setup installs the default rootful Docker, which works out of the box with `ai sandbox` — no extra configuration is required.
+
+Rootless Docker is a separate Docker installation where the daemon runs as your normal user instead of `root`. It is typically chosen on shared hosts, multi-tenant servers, or when a security policy forbids a root-owned daemon. If you have intentionally installed rootless Docker (or plan to), follow the steps below; otherwise stay with rootful.
+
+To install and verify rootless Docker:
+
+```bash
+sudo apt install -y uidmap slirp4netns dbus-user-session
+dockerd-rootless-setuptool.sh install
+systemctl --user enable --now docker
+export DOCKER_HOST="unix:///run/user/$(id -u)/docker.sock"
+docker info
+```
+
+Add the `DOCKER_HOST` export to your shell startup file after validation.
+
+When rootless Docker is detected, agent-infra builds the sandbox image with `HOST_UID=0` and `HOST_GID=0`. Inside the container the sandbox user can read bind mounts such as `~/.ssh` without relaxing host file permissions. On the host, the daemon and container processes still run under the current user, so this does not grant host root privileges.
+
+Known rootless differences:
+
+- Networking uses slirp4netns by default and can be slower than rootful bridge networking.
+- Processes run as UID 0 inside the container, unlike rootful Docker where agent-infra mirrors the host UID.
+- The CI rootless matrix is initially allowed to fail while runner stability is observed.
+
+Troubleshooting:
+
+- If `docker info` fails, check `systemctl --user status docker` and confirm `DOCKER_HOST` points at `$XDG_RUNTIME_DIR/docker.sock`.
+- If SSH files are still unreadable inside the sandbox, confirm the shell has not overridden `DOCKER_HOST` or Docker build arguments.
+
 #### Known limitations on Linux
 
 These configurations are not actively tested in this release:
 
-- **Rootless Docker**: Track [#256](https://github.com/fitlab-ai/agent-infra/issues/256).
-- **Podman** instead of Docker: Track [#257](https://github.com/fitlab-ai/agent-infra/issues/257).
-- **SELinux-enforcing** hosts (Fedora / RHEL) may need manual mount labels: Track [#258](https://github.com/fitlab-ai/agent-infra/issues/258).
-- `ai sandbox vm` is a no-op on Linux. Linux uses native Docker directly with no VM to manage; use `ai sandbox create`, `ai sandbox exec`, `ai sandbox ls`, `ai sandbox rebuild`, `ai sandbox rm` directly.
+- **Podman** instead of Docker: Works on Fedora 40+ and other `dnf`-based RHEL family distros (RHEL, CentOS Stream, Rocky, Alma) via the `podman-docker` shim (`sudo dnf install podman podman-docker`; optionally `sudo touch /etc/containers/nodocker` to silence its per-command notice).
+- **SELinux-enforcing** hosts (Fedora / RHEL): `ai sandbox create` automatically labels bind mounts with Docker's shared `:z` flag — no setup required. Set `AGENT_INFRA_SELINUX_DISABLE=1` to opt out for debugging.
+- `ai sandbox vm` is a no-op on Linux. Linux uses native Docker directly with no VM to manage; use `ai sandbox create`, `ai sandbox exec`, `ai sandbox refresh`, `ai sandbox ls`, `ai sandbox rebuild`, `ai sandbox rm` directly.
 
 ### Windows
 
-WSL2 support is tracked in [#184](https://github.com/fitlab-ai/agent-infra/issues/184).
+- `ai init`, `ai sync`, etc.: should work after `npm install -g @fitlab-ai/agent-infra` (Node.js >= 22). Not actively tested in this release.
+- `ai sandbox *`: supported on Windows via WSL2 + Docker Desktop.
+
+Before running `ai sandbox create`, install Windows 11 with WSL2, configure a default Linux distribution, install Docker Desktop, and enable Docker Desktop's WSL integration for that distribution.
+
+You can run the CLI from PowerShell or Git Bash, but the project path must be visible from WSL, such as `C:\Users\you\project` or another drive mounted under `/mnt/<drive>`. UNC paths are not supported for sandbox mounts. If the Windows entrypoint cannot reach Docker through WSL2, run the same command from inside the WSL distribution as a fallback.
+
+`ai sandbox vm` manages only the macOS Colima VM. On Windows, manage Docker Desktop and WSL2 with their native tools.
+
+#### Engine resource configuration
+
+WSL2 is the default sandbox engine on Windows. `sandbox.vm.cpu`, `sandbox.vm.memory`, and `--cpu / --memory` flags are not applied automatically when using WSL2 — configure CPU and memory limits in Docker Desktop (Settings → Resources) instead. `sandbox.vm.disk` is not applicable to WSL2. `vm.memory` and `--memory` values are expressed in GiB.
 
 <a id="what-you-get"></a>
 
@@ -585,7 +777,7 @@ The generated `.agents/.airc.json` file is the central contract between the boot
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.5.9",
+  "templateVersion": "v0.6.0",
   "templates": {
     "sources": [
       { "type": "local", "path": "~/private-templates" }

package/README.zh-CN.md

@@ -16,7 +16,7 @@
   <a href="https://www.npmjs.com/package/@fitlab-ai/agent-infra"><img src="https://img.shields.io/npm/v/@fitlab-ai/agent-infra" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/@fitlab-ai/agent-infra"><img src="https://img.shields.io/npm/dm/@fitlab-ai/agent-infra" alt="npm downloads"></a>
   <a href="License.txt"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
-  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D18-brightgreen?logo=node.js" alt="Node.js >= 18"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D22-brightgreen?logo=node.js" alt="Node.js >= 22"></a>
   <a href="https://github.com/fitlab-ai/agent-infra/releases"><img src="https://img.shields.io/github/v/release/fitlab-ai/agent-infra" alt="GitHub release"></a>
   <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
 </p>
@@ -201,6 +201,77 @@ CLI 会收集项目元数据，向所有支持的 AI TUI 安装 `update-agent-in
 
 `ai sandbox exec` 也会向容器透传一小组终端检测白名单变量（`TERM_PROGRAM`、`TERM_PROGRAM_VERSION`、`LC_TERMINAL`、`LC_TERMINAL_VERSION`）。这样可以让交互式 TUI 保持与宿主终端一致的行为，例如 Claude Code 的 `Shift+Enter` 换行支持，同时避免把整个宿主环境灌入容器。
 
+`ai sandbox exec` 和 `ai sandbox refresh` 会在宿主机凭证存储与 `~/.agent-infra/credentials/*` 下的所有沙箱项目副本之间做双向 reconcile。长时间运行的沙箱如果先刷新了 OAuth token，下一次进入或刷新命令会把最新有效副本回写到宿主 Keychain 或 `~/.claude/.credentials.json`；宿主机更新时也会继续覆盖项目副本。如果所有副本都已失效，`ai sandbox refresh` 会尝试 `claude /status` 探活，只有探活无法恢复时才提示重新登录。
+
+### 宿主-沙箱文件交换
+
+`ai sandbox create` 会自动挂载两个可读写目录，方便宿主与容器之间互相 drop 文件，不污染 git 工作树：
+
+- `/share/common` <- `~/.agent-infra/share/<project>/common/`：项目级共享，跨分支可见。
+- `/share/branch` <- `~/.agent-infra/share/<project>/branches/<branch>/`：分支独占。
+
+这两条路径硬编码，不暴露 `.airc.json` 配置项。首次 `create` 时会自动创建宿主目录；`ai sandbox rm <branch>` 与 `ai sandbox rm --all` 删除时会附带询问是否清理（默认 yes）。
+已有沙箱需要执行 `ai sandbox rm <branch>` 后再执行 `ai sandbox create <branch>`，才能加载新的挂载点。
+
+#### 用户级 dotfiles 通道
+
+`ai sandbox create` 还会自动挂载一条可选的只读通道，用于把宿主机用户级偏好带进沙箱：
+
+- `/dotfiles` <- `~/.agent-infra/dotfiles/`：只读，host 作为单向源。
+
+host 端目录树镜像容器 `$HOME` 下的预期路径，风格类似 GNU stow 或 chezmoi：
+
+```text
+~/.agent-infra/dotfiles/
+├── .tmux.conf
+└── .config/
+    ├── lazygit/config.yml
+    └── yazi/yazi.toml
+```
+
+每次进入沙箱时，`sandbox-dotfiles-link` 会用 `ln -sfn` 把每个文件链接到
+`$HOME/<相对路径>`，覆盖镜像默认。host 端目录不存在时，会跳过挂载和链接步骤。
+
+未来要加 `starship.toml`、`.gitconfig.local` 等偏好，只需把文件放进
+`~/.agent-infra/dotfiles/`，无需修改 Dockerfile 或 `ai sandbox create`。
+
+##### 符号链接作为指向 host 文件的指针
+
+你可以在 `~/.agent-infra/dotfiles/` 里放符号链接，让它们指向 host 上的真实文件：
+
+```bash
+ln -s ~/.tmux.conf ~/.agent-infra/dotfiles/.tmux.conf
+ln -s ~/.config/lazygit ~/.agent-infra/dotfiles/.config/lazygit
+```
+
+每次执行 `ai sandbox create` 和 `ai sandbox enter` 前，agent-infra 会先把
+dotfiles 树解引用到
+`~/.agent-infra/.cache/dotfiles-resolved/<project>/`，再把这份快照挂载进容器。
+因此修改 host 源文件后，重新进入沙箱即可看到最新内容。
+
+悬空符号链接会被跳过并在 stderr 输出警告。符号链接循环以及超过 32 层的深层目录也会被跳过并输出警告。指向 `$HOME` 之外的符号链接可以使用，只要 host 用户能读取目标。
+
+> **不要往 `~/.agent-infra/dotfiles/` 放任何凭证。** 容器内是只读挂载，但整棵偏好树会链入所有项目沙箱。不要放 `.ssh/`、`.aws/credentials`、`.netrc`、`.gnupg/`、包含 `_authToken` 的 `.npmrc`、任何 AI 工具 OAuth/access token 文件，也不要放 `.gitconfig`。SSH 和工具凭证请使用专用通道；本地 Git 偏好建议用 `.gitconfig.local` 配合 `[include]`。
+
+**受保护路径**即使出现在 `~/.agent-infra/dotfiles/` 下，也会被钩子忽略：
+
+| 路径模式 | 原因 |
+|---|---|
+| `.ssh/*` | host SSH 凭证由只读 SSH 挂载管理。 |
+| `.gnupg/*` | GPG 私钥由 `gpg-agent` 管理。 |
+| `.claude/*`, `.codex/*`, `.gemini/*` | AI 工具凭证使用专用 bind mount。 |
+| `.config/opencode/*`, `.local/share/opencode/*` | OpenCode 凭证和数据使用专用 bind mount。 |
+| `.host-shell-config/*` | agent-infra 管理的 shell 和 Git 配置。 |
+| `.gitconfig`, `.gitignore_global`, `.stCommitMsg`, `.bash_aliases` | agent-infra 将这些路径软链到 `.host-shell-config/`，包含 `safe.directory` 和 GPG 同步状态。 |
+
+其他已经存在的真实目录（如 `~/.config/`、`~/.cache/`）不会被顶层 dotfile 替换。如果某个文件与这类目录冲突，钩子会打印警告并跳过：
+
+```text
+sandbox-dotfiles-link: skipping /home/devuser/.config (existing directory; use nested path like .config/<file> instead)
+```
+
+正确用法是嵌套路径，例如 `~/.agent-infra/dotfiles/.config/lazygit/config.yml`，不要把 `.config` 当成顶层文件。
+
 <a id="architecture-overview"></a>
 
 ## 架构概览
@@ -240,13 +311,65 @@ agent-infra 的结构刻意保持简单：引导 CLI 负责生成种子配置，
 
 ## 平台支持
 
-agent-infra 支持 macOS 和 Linux。CLI 本身只需要 Node.js (>=18)；容器相关功能（`ai sandbox *`）额外需要 Docker。
+agent-infra 支持 macOS、Linux 和 Windows。CLI 本身只需要 Node.js (>=22)；容器相关功能（`ai sandbox *`）额外需要 Docker。
+
+### 沙箱引擎选择
+
+`.agents/.airc.json` 中的 `sandbox.engine` 用来选择容器引擎。该字段为 `null` 或省略时，agent-infra 使用平台默认值：
+
+- Linux：`native`
+- macOS：`colima`
+- Windows：`wsl2`
+
+你可以在 `.agents/.airc.json` 中覆盖该引擎。合法值按平台区分：
+
+- Linux：`native`、`docker-desktop`
+- macOS：`colima`、`orbstack`、`docker-desktop`
+- Windows：`wsl2`、`native`、`docker-desktop`
 
 ### macOS
 
 - `ai init`、`ai sync` 等：执行 `npm install -g @fitlab-ai/agent-infra`（或 Homebrew 安装）后开箱即用。
 - `ai sandbox *`：需要 Colima、OrbStack 或 Docker Desktop。macOS 默认引擎是 Colima —— 当选用 Colima 且宿主机没有 `colima` 命令时，agent-infra 会在首次运行时通过 Homebrew 自动安装并启动。如需使用 OrbStack 或 Docker Desktop，请在 `.agents/.airc.json` 中设置 `sandbox.engine`。
 
+#### 引擎资源配置
+
+| 引擎 | `vm.cpu` | `vm.memory` | `vm.disk` | 应用方式 | 说明 |
+|------|----------|-------------|-----------|----------|------|
+| Colima | 生效 | 生效 | 生效 | 启动时 | 变更需重启 VM（`ai sandbox vm stop && ai sandbox vm start`）后生效。 |
+| OrbStack | 生效 | 生效 | 警告 | 热应用 | 每次调用都会通过 `orb config set` 应用。OrbStack 通过 thin provisioning 管理磁盘。 |
+| Docker Desktop | 警告 | 警告 | 警告 | 手动 | 资源必须在 Docker Desktop GUI（Settings -> Resources）中设置。 |
+
+`vm.memory` 和 `--memory` 的单位是 GiB。
+
+#### SSH / 锁定的 keychain
+
+在 macOS 上通过 SSH 使用时，login keychain 可能处于锁定状态，并以 `errSecInteractionNotAllowed` 拒绝非交互式读写。你可以在宿主机上解锁后重新运行 `ai sandbox refresh`：
+
+```bash
+security unlock-keychain ~/Library/Keychains/login.keychain-db
+ai sandbox refresh
+```
+
+对于长期 SSH 会话或 CI，可以通过 `AGENT_INFRA_CLAUDE_CREDENTIALS_FILE` 绕过 keychain。macOS 默认把 Claude Code 凭据存进 keychain，所以需要先在 keychain 已解锁的会话中 seed 一次 override 文件：
+
+```bash
+security unlock-keychain ~/Library/Keychains/login.keychain-db
+umask 077 && mkdir -p "$HOME/.agent-infra" && \
+  security find-generic-password -s "Claude Code-credentials" -w \
+  > "$HOME/.agent-infra/claude-credentials.json"
+chmod 600 "$HOME/.agent-infra/claude-credentials.json"
+```
+
+之后在 SSH / CI 侧设置：
+
+```bash
+export AGENT_INFRA_CLAUDE_CREDENTIALS_FILE="$HOME/.agent-infra/claude-credentials.json"
+ai sandbox refresh
+```
+
+此后 sandbox create、exec、refresh 读取和写入 Claude Code 凭据时都会使用该文件，而不是 keychain。
+
 ### Linux
 
 - `ai init`、`ai sync` 等：执行 `npm install -g @fitlab-ai/agent-infra` 后开箱即用。
@@ -264,18 +387,63 @@ agent-infra 支持 macOS 和 Linux。CLI 本身只需要 Node.js (>=18)；容器
 
   当宿主机 `gpg-agent` 和签名 key 可用时，GPG signing 可正常工作；如果 key 同步失败，`ai sandbox create` 会回退到清理后的 Git config，让提交仍可在没有宿主签名状态的情况下继续。
 
+#### 引擎资源配置
+
+Linux 直接使用宿主内核上的原生 Docker，没有受管 VM。`sandbox.vm.*` 与 `--cpu / --memory` 标志均不生效。如需限制容器资源，请用 `docker run --cpus / --memory` 设置单容器限制，或配置宿主 cgroups。
+
+#### Rootless Docker（可选）
+
+**如果你已按上面的 Quick setup 装好 rootful Docker，跳过本节即可。** Quick setup 装的就是默认的 rootful Docker，`ai sandbox` 开箱可用，不需要任何额外配置。
+
+Rootless Docker 是一种另起一套的 Docker 安装方式：daemon 以你的普通用户身份运行，而不是 root。它通常用在共享主机、多租户服务器，或安全策略禁止 root 守护进程的场景。如果你**主动选择**安装了 rootless Docker（或打算这么做），按下面的步骤配置；否则继续用 rootful 就好。
+
+安装并验证 rootless Docker：
+
+```bash
+sudo apt install -y uidmap slirp4netns dbus-user-session
+dockerd-rootless-setuptool.sh install
+systemctl --user enable --now docker
+export DOCKER_HOST="unix:///run/user/$(id -u)/docker.sock"
+docker info
+```
+
+验证通过后，请把 `DOCKER_HOST` export 写入 shell 启动文件。
+
+agent-infra 检测到 rootless Docker 后，会用 `HOST_UID=0` 和 `HOST_GID=0` 构建 sandbox 镜像。这样容器内 sandbox 用户可以读取 `~/.ssh` 等 bind mount，无需放宽宿主文件权限。在宿主侧，daemon 和容器进程仍以当前用户身份运行，不会获得宿主 root 权限。
+
+Rootless 模式的已知差异：
+
+- 网络默认使用 slirp4netns，可能比 rootful bridge 网络慢。
+- 容器内进程以 UID 0 运行；rootful Docker 下 agent-infra 仍会镜像宿主 UID。
+- CI rootless matrix 初期允许失败，用于观察 GitHub runner 稳定性。
+
+排障：
+
+- 如果 `docker info` 失败，请检查 `systemctl --user status docker`，并确认 `DOCKER_HOST` 指向 `$XDG_RUNTIME_DIR/docker.sock`。
+- 如果 sandbox 内仍无法读取 SSH 文件，请确认 shell 没有覆盖 `DOCKER_HOST` 或 Docker build args。
+
 #### Linux 已知限制
 
 下列场景在本期未做主动验证：
 
-- **Rootless Docker**：后续跟踪 [#256](https://github.com/fitlab-ai/agent-infra/issues/256)。
-- 用 **Podman** 替代 Docker：后续跟踪 [#257](https://github.com/fitlab-ai/agent-infra/issues/257)。
-- **SELinux enforcing** 宿主机（Fedora / RHEL）可能需要手动加挂载标签：后续跟踪 [#258](https://github.com/fitlab-ai/agent-infra/issues/258)。
-- `ai sandbox vm` 在 Linux 上是空操作。Linux 直接使用 native Docker，没有 VM 需要管理；请直接使用 `ai sandbox create`、`ai sandbox exec`、`ai sandbox ls`、`ai sandbox rebuild`、`ai sandbox rm`。
+- 用 **Podman** 替代 Docker：Fedora 40+ 及其他 `dnf` 系 RHEL 发行版（RHEL、CentOS Stream、Rocky、Alma）上通过 `podman-docker` shim 已可使用（`sudo dnf install podman podman-docker`；可选 `sudo touch /etc/containers/nodocker` 抑制 podman 在每条命令前打印的提示）。
+- **SELinux enforcing** 宿主机（Fedora / RHEL）：`ai sandbox create` 会自动给 bind mount 加 Docker 共享 `:z` 标签，无需手动准备。如需排障可设 `AGENT_INFRA_SELINUX_DISABLE=1` 关闭。
+- `ai sandbox vm` 在 Linux 上是空操作。Linux 直接使用 native Docker，没有 VM 需要管理；请直接使用 `ai sandbox create`、`ai sandbox exec`、`ai sandbox refresh`、`ai sandbox ls`、`ai sandbox rebuild`、`ai sandbox rm`。
 
 ### Windows
 
-WSL2 支持在 [#184](https://github.com/fitlab-ai/agent-infra/issues/184) 跟踪。
+- `ai init`、`ai sync` 等：执行 `npm install -g @fitlab-ai/agent-infra` 后理论上可用（需 Node.js >= 22）。本期未做主动验证。
+- `ai sandbox *`：Windows 通过 WSL2 + Docker Desktop 支持。
+
+运行 `ai sandbox create` 前，请先准备 Windows 11、WSL2、默认 Linux distribution、Docker Desktop，并在 Docker Desktop 中为该 distribution 启用 WSL integration。
+
+你可以从 PowerShell 或 Git Bash 运行 CLI，但项目路径必须能被 WSL 访问，例如 `C:\Users\you\project`，或其他会挂载到 `/mnt/<drive>` 的磁盘路径。UNC 路径不支持作为沙箱挂载路径。如果 Windows 入口无法通过 WSL2 访问 Docker，可以进入对应 WSL distribution 后运行同一命令作为回退方案。
+
+`ai sandbox vm` 只管理 macOS 的 Colima VM。在 Windows 上，请使用 Docker Desktop 和 WSL2 自带工具管理后端。
+
+#### 引擎资源配置
+
+WSL2 是 Windows 上的默认 sandbox 引擎。使用 WSL2 时，`sandbox.vm.cpu`、`sandbox.vm.memory` 以及 `--cpu / --memory` 标志不会自动生效——请在 Docker Desktop（Settings → Resources）中配置 CPU 和内存限制。`sandbox.vm.disk` 不适用于 WSL2。`vm.memory` 和 `--memory` 的单位是 GiB。
 
 <a id="what-you-get"></a>
 
@@ -585,7 +753,7 @@ import-issue #42                    从 GitHub Issue 导入任务
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.5.9",
+  "templateVersion": "v0.6.0",
   "templates": {
     "sources": [
       { "type": "local", "path": "~/private-templates" }

package/bin/{cli.js → cli.ts}

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-import { VERSION } from '../lib/version.js';
+import { VERSION } from '../lib/version.ts';
 
 // Node.js version check
-const major = parseInt(process.versions.node.split('.')[0], 10);
-if (major < 18) {
+const [major = 0] = process.versions.node.split('.').map((part) => parseInt(part, 10));
+if (major < 22) {
   process.stderr.write(
-    `agent-infra requires Node.js >= 18 (current: ${process.version})\n`
+    `agent-infra requires Node.js >= 22 (current: ${process.version})\n`
   );
   process.exit(1);
 }
@@ -35,15 +35,19 @@ Examples:
 
 const command = process.argv[2] || '';
 
-async function importCommand(importPath) {
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+async function importCommand(importPath: string) {
   try {
     return await import(importPath);
   } catch (error) {
-    if (error?.code === 'ERR_MODULE_NOT_FOUND') {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ERR_MODULE_NOT_FOUND') {
       process.stderr.write(
         'Error: Missing npm dependency. Run npm install before using agent-infra from a development checkout.\n'
       );
-      process.stderr.write(`${error.message}\n`);
+      process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
       process.exitCode = 1;
       return null;
     }
@@ -53,41 +57,41 @@ async function importCommand(importPath) {
 
 switch (command) {
   case 'init': {
-    const imported = await importCommand('../lib/init.js');
+    const imported = await importCommand('../lib/init.ts');
     if (!imported) break;
     const { cmdInit } = imported;
-    await cmdInit().catch((e) => {
-      process.stderr.write(`Error: ${e.message}\n`);
+    await cmdInit().catch((e: unknown) => {
+      process.stderr.write(`Error: ${errorMessage(e)}\n`);
       process.exitCode = 1;
     });
     break;
   }
   case 'update': {
-    const imported = await importCommand('../lib/update.js');
+    const imported = await importCommand('../lib/update.ts');
     if (!imported) break;
     const { cmdUpdate } = imported;
-    await cmdUpdate().catch((e) => {
-      process.stderr.write(`Error: ${e.message}\n`);
+    await cmdUpdate().catch((e: unknown) => {
+      process.stderr.write(`Error: ${errorMessage(e)}\n`);
       process.exitCode = 1;
     });
     break;
   }
   case 'merge': {
-    const imported = await importCommand('../lib/merge.js');
+    const imported = await importCommand('../lib/merge.ts');
     if (!imported) break;
     const { cmdMerge } = imported;
-    await cmdMerge(process.argv.slice(3)).catch((e) => {
-      process.stderr.write(`Error: ${e.message}\n`);
+    await cmdMerge(process.argv.slice(3)).catch((e: unknown) => {
+      process.stderr.write(`Error: ${errorMessage(e)}\n`);
       process.exitCode = 1;
     });
     break;
   }
   case 'sandbox': {
-    const imported = await importCommand('../lib/sandbox/index.js');
+    const imported = await importCommand('../lib/sandbox/index.ts');
     if (!imported) break;
     const { runSandbox } = imported;
-    await runSandbox(process.argv.slice(3)).catch((e) => {
-      process.stderr.write(`Error: ${e.message}\n`);
+    await runSandbox(process.argv.slice(3)).catch((e: unknown) => {
+      process.stderr.write(`Error: ${errorMessage(e)}\n`);
       process.exitCode = 1;
     });
     break;