dsh-workspace-envrc

> English version: docs/README.en.md

DSH 树外 bundle：把本机原生 direnv 环境应用到显式归属于 Agent/workspace 的 Bash 执行（foreground 与 background）和本地 stdio workspace MCP 行。插件把 .envrc 发现、求值、授权 hash、allow/deny、stdlib 与环境变更全部委托给已安装的 direnv 可执行文件；它不解析或 source .envrc，不维护授权数据库，不调用 direnv allow/permit/grant/edit，不使用 direnv export，不 watch 或缓存 .envrc，不修改 Harness 的 process.env，也不向模型暴露 allow/deny 工具。

目标 DSH 为 0.1.0-rc.6。本 bundle 依赖 dsh-workspace-overlay 提供 canonical workspace scope、workspace-aware MCP manager 与可逆 method wrapper。

安装

先安装 overlay，再安装本 bundle；系统必须已经安装 direnv：

dsh plugin --profile web add /path/to/dsh-workspace-overlay
dsh plugin --profile web add /path/to/dsh-workspace-envrc
dsh --profile web --dump-config

本 bundle 的 cordis.patch.yml 只增加 workspace-envrc provider 和 workspace-envrc-integration 两行，不修改 overlay 或官方 DSH 行。激活 preflight 会运行 direnv version 和一个受限 shim 探针，但不会读取 workspace .envrc。

卸载：

dsh plugin --profile web remove dsh-workspace-envrc

原生 direnv 语义

• workspace 只来自发起 Agent 的 scope ancestry：从 scopeOf(agent.ctx) 沿 scopeParentOf 上行，取 workspaceCordis.workspaceForScope 的首个命中；不从 command workdir 或 session.header.cwd 猜测。
• direnv exec <canonical-workspace> 只选择环境，原程序 cwd 保持调用方解析值。
• 无 .envrc 时原生 direnv 透传继承环境；未 allow、deny 或内容变化导致 hash 失效时，原生 direnv 拒绝执行，原程序不会运行。
• 授权只能由用户在 DSH 外执行 direnv allow <exact .envrc>；本插件没有授权入口。
• .envrc 允许后导出的普通变量遵循原生 direnv 语义。Harness 管理的 DSH_* 在 direnv 后按执行路径的显式 snapshot 恢复，workspace MCP 使用空 snapshot 并清除可能伪造的 DSH_*。
• BASH_ENV 和 ENV 从受管理 shim 与原程序环境中移除，避免允许后的环境改变恢复步骤。

Bash

集成插件可逆装饰 ctx.shell.resolve。仅当调用存在当前 initiator Agent，并且该 Agent 映射到 canonical workspace 时，插件才把 request.command 替换为：

exec direnv exec <canonical-workspace> <managed-env-shim> <original-command>

workdir、timeout、stdout cap、signal、stdin、普通 env、dshEnv 和 sandbox policy 保持原值。Foreground 与 run_in_background 都在各自新进程启动时冻结环境；agentless 或未映射调用原样透传。

Workspace MCP

集成插件可逆装饰 ctx.workspaceMcp.activate。只有映射到 canonical workspace 的本地 stdio MCP 行会被包装；global、HTTP、foreign scope 和格式错误的行原样交给 manager。包装只改写 command/args，不改变 cwd、显式 env、重连、启动失败策略或 tool timeout。

当前 overlay MCP stdio transport 没有 sandbox/confine seam，因此 MCP 子进程和 .envrc 求值使用 transport 的宿主进程权限。这是已知边界，不宣称与 Bash sandbox 等价。

不支持 persistent shell

本 bundle 不支持 persistent shell 或 terminal creation。DSH 把 terminals 挂载在 preset 私有 isolated realm 中，而本 bundle 是 Host profile layer；为此引入 preset augmentation 会依赖尚未稳定的内部挂载 API，当前使用场景也不需要该能力。决策与重新考虑条件见 [ADR 0001](docs/adr/0001-no-persistent-shell.md)。

配置

interface WorkspaceEnvrcConfig {
  executable: string
  shimShell: string
  enableBash: boolean
  enableWorkspaceMcp: boolean
  versionCheckTimeoutMs: number
}

默认值：

executable: direnv
shimShell: /bin/bash
enableBash: true
enableWorkspaceMcp: true
versionCheckTimeoutMs: 5000

安全边界

• 不读取、记录或打印完整 env snapshot、.envrc 内容、stdout/stderr 或 secret。
• 不修改 Host process.env；不同 workspace 的执行按 Agent scope 解析，不共享 mutable workspace 状态。
• 所有命令通过 argv/spawn/现有 DSH service seam 执行，不使用 shell: true 拼接 workspace 路径。
• fiber dispose 会按 MCP → Bash 的逆安装顺序恢复 method descriptor；失败的 MCP 安装会回滚已安装的 Bash adapter。

许可证

MIT，见 [LICENSE](LICENSE)。