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 service 包 0.1.7-rc.2、Agent/preset-registry 0.1.7-rc.2-fork1、Cordis 4.0.4、Schemastery 3.18.4 和 overlay 0.2.0。本 bundle 依赖 overlay 提供 canonical workspace scope、workspace-aware MCP manager 与可逆 method wrapper；共享包以 peer 声明并复用 Host 的模块实例。依赖来源与准备方式见「发布验证」。
发布验证
Validate and release 与本地共用 pnpm prepare:release。依赖合同 固定 Agent/preset-registry fork1 和 overlay 0.2.0；registry 由 overlay 消费，不新增 envrc 服务 peer。缺少正式资产 URL 时准备立即失败；先发布核心资产和 overlay，再把精确不可变 URL 写入合同/workspace overrides，由 pnpm 生成 source 锁文件。llm 保持官方 0.1.7-rc.2。
node .github/scripts/prepare-local.mjs <inputs.json> 检查输入 JSON 中包名对应的本地 tarball，在 .artifacts/local-source 准备仅供诊断的副本。pnpm verify:consumer 在插件专属 profile（autoInstallPeers: false）与 Host 共享 peers 组合下，使用正式解析器检查打包入口和真实 Loader 激活，并检查 fork-only peers 无豁免拒绝及自身隔离版本组合的精确豁免。原生 direnv 测试只操作临时 fixture；不启动 Host。
集成
overlay 与 envrc 由解析这些共用插件的 profile 普通 dependencies 安装（autoInstallPeers: false），在 $DSH_HOME/cordis.patch.yml 中依次声明 overlay 的 workspace-registry、workspace-mcp-manager、workspace-agent-integration，以及本包的 workspace-envrc、workspace-envrc-integration 两行。日用 bundles 只保留官方 base／Web app，不自动追加两个独立 bundle 造成重复插入；系统须安装 direnv，激活 preflight 检查其版本及 shim，但不读取 workspace .envrc。隔离安装后检查模块解析和最终组合；不要修改运行中的 Host。
原生 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、onExpiry、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。
配置
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。
