knowledge-shell-process-and-worktree

name

knowledge-shell-process-and-worktree

description

Covers Bash 前后台执行、stdin/终止、输出有界化、进程树与持久租约、Workspace 写沙箱，以及托管 Git worktree 的隔离和交付。 Navigate when: 排查命令超时/取消/残留进程、后台 Shell、输出截断、ACP terminal、审计沙箱、worktree 创建/恢复/应用/清理。 Excludes: 通用工具权限和 scheduler（见 ../tool-execution-pipeline/）、文件补丁事务（见 ../filesystem-search-and-atomic-patching/）。 Keywords: Bash, WriteStdin, KillShell, BackgroundShellManager, DurableProcessLeaseStore, OwnedProcessTree, WorkspaceWriteSandbox, WorktreeManager, foreground handoff.

Module Structure

该节点连接命令执行与 workspace 隔离。Bash 可走本地、ACP 或沙箱路径，并把长前台 命令原进程移交为后台任务；worktree 管理器则将 Session 映射到独立 Git 工作目录并 在交付前验证源工作区没有漂移。

Directory Layout

• packages/cli/src/tools/builtin/shell/ — Bash、后台管理、stdin、终止与输出捕获
• packages/cli/src/context/storage/DurableForegroundProcess.ts — 前台命令租约与 handoff
• packages/cli/src/context/storage/DurableProcessLeaseStore.ts — 可恢复的进程身份租约
• packages/cli/src/utils/process/ — 启动闸门、进程组拥有权和跨平台终止
• packages/cli/src/utils/shell/ — 命令归一化、只读审计和验证命令识别
• packages/cli/src/worktree/WorktreeManager.ts — worktree 生命周期、diff 制品和变更交付
• packages/cli/src/tools/builtin/worktree/worktreeTools.ts — Agent 可调用的进入/退出适配器

Key Entry Points

• bashTool in packages/cli/src/tools/builtin/shell/bash.ts — 本地、ACP、后台与自动 handoff 分流
• BackgroundShellManager in packages/cli/src/tools/builtin/shell/BackgroundShellManager.ts — Session-owned Shell 生命周期
• prepareForegroundProcess() in packages/cli/src/context/storage/DurableForegroundProcess.ts — 先持久登记再释放命令启动闸门
• WorktreeManager.enter() / apply() / exit() in packages/cli/src/worktree/WorktreeManager.ts — 隔离、交付和离开工作树

Gotchas

• Bash 明确是 isRetrySafe=false；即使抛出 EBUSY/EAGAIN 也不能自动重放，因为命令可能已经产生外部副作用 (packages/cli/src/tools/builtin/shell/bash.ts, packages/cli/tests/unit/tooling/tools/builtin/bash.test.ts)
• Bash 的 isConcurrencySafe=false 但显式 parallelism='shared'：独立命令可同批进入，仍受 execute bucket 限流；由于没有 file_path，通用 FileLockManager 不会替 Shell 串行工作区写入 (packages/cli/src/tools/builtin/shell/bash.ts, packages/cli/src/tools/execution/ToolExecutor.ts)
• ACP terminal 执行设置 allowLocalFallback=false；远端终端失败必须原样失败，不能在宿主机悄悄重跑同一命令 (packages/cli/src/tools/builtin/shell/bash.ts, git:27f9df37)
• WriteStdin 会产生外部可见输入且默认不可重放，最多接受 64 KiB；ACP 后台终端当前不支持 stdin 写入 (packages/cli/src/tools/builtin/shell/writeStdin.ts, packages/cli/tests/unit/tooling/tools/builtin/write-stdin.test.ts)
• 前台自动转后台复用原进程，不重启命令；只有存在 Session、超时大于 handoff budget、非只读审计代理且首个命令不是 sleep 时才有资格 (packages/cli/src/tools/builtin/shell/ForegroundCommandHandoff.ts, packages/cli/src/tools/builtin/shell/bash.ts)
• foreground → background 租约提交失败时，前台 owner 仍保持权威并继续等待；不能同时把两个 lease 当作有效所有者 (packages/cli/src/context/storage/DurableForegroundProcess.ts, packages/cli/src/tools/builtin/shell/bash.ts)
• 后台 Shell ID 绑定 Session；TaskOutput、WriteStdin、KillShell 用其他 Session ID 查询时都按不存在处理，不能跨会话接管 (packages/cli/src/tools/builtin/shell/BackgroundShellManager.ts, packages/cli/src/tools/builtin/task/taskOutput.ts)
• 本地前后台输出各流只保留最后 1 MiB，随后还会按命令类型二次投影；stdout_total_bytes/omitted_bytes 才能区分“命令没输出”和“早期输出已丢弃” (packages/cli/src/tools/builtin/shell/BoundedOutputBuffer.ts, packages/cli/src/tools/builtin/shell/ShellOutputProjection.ts)
• worktree 从 committed HEAD 创建，原工作区未提交改动不会复制；返回的 sourceHadChanges 是警告，不代表新 worktree 包含这些内容 (packages/cli/src/worktree/WorktreeManager.ts, packages/cli/src/tools/builtin/worktree/worktreeTools.ts)
• worktree 交付要求源仓库 HEAD 和创建时工作状态指纹都未变化；只检查 patch 可应用而忽略源状态会覆盖任务期间的用户改动 (packages/cli/src/worktree/WorktreeManager.ts)
• ExitWorktree(action='remove') 在无法验证状态或存在未提交文件/未合并 commit 时拒绝，只有用户明确允许 才强制删除 (, )

Architecture

• 命令启动经过独立 Node admission gate：目标子进程仅在 lease 持久化后收到启动字节，owner 消失时 gate 负责终止进程组，关闭了“进程已启动但尚未登记”的崩溃窗口 (packages/cli/src/utils/process/CommandAdmissionGate.ts, packages/cli/src/context/storage/DurableForegroundProcess.ts)
• DurableProcessLeaseStore 同时记录 owner 与 root PID 的平台指纹；恢复时先识别活 owner，再验证 PID 未复用，POSIX leader 已退出但进程组仍活跃时单独清理 leaderless group (packages/cli/src/context/storage/DurableProcessLeaseStore.ts, packages/cli/src/utils/process/ProcessIdentity.ts)
• BackgroundShellManager 统一管理本地后台、自动 handoff 和 ACP 外部前台候选，默认最多 16 个全局活动进程、每 Session 4 个 (packages/cli/src/tools/builtin/shell/BackgroundShellManager.ts)
• worktree manager 以 Session keyed mutex 串行生命周期操作，目录位于按仓库路径哈希隔离的 managed root，分支名同时包含逻辑名称和 Session 哈希 (packages/cli/src/worktree/WorktreeManager.ts)
• 任务交付使用临时 Git index 收集 tracked/untracked 变更，生成 binary patch，先 git apply --check 再应用到源工作区，不通过 merge 或复制目录 (packages/cli/src/worktree/WorktreeManager.ts)

Decisions

• managed worktree 同时服务显式 Enter/Exit 工具和子代理任务隔离；工具层只负责用户交互，实际恢复、差异和交付语义集中在 WorktreeManager (packages/cli/src/tools/builtin/worktree/worktreeTools.ts, packages/cli/src/agent/subagents/SubagentWorktreeLifecycle.ts, git:c80db2c1)
• 后台与前台命令都升级为持久 lease 和 owned process tree，以便 Session 恢复时回收 orphan，而不是只依赖当前 Node 子进程句柄 (packages/cli/src/context/storage/DurableProcessLeaseStore.ts, git:c012135e, git:cbe0e8ed)
• 输出限制分为 capture 上限和模型/UI projection 上限，既限制常驻内存又保留完整计数事实，避免单纯截断字符串后无法判断损失量 (packages/cli/src/tools/builtin/shell/ShellOutputCapture.ts, packages/cli/src/tools/builtin/shell/OutputTruncator.ts, git:81a9acc9)

Patterns

• 本地 POSIX 子进程作为 detached group leader 启动，终止先发 SIGTERM 再在 grace period 后发 SIGKILL；Windows 使用 taskkill /T 并保留直接 child fallback (packages/cli/src/utils/process/OwnedProcessTree.ts)
• workspace-required 或只读审计 Bash 会先生成沙箱命令；cwd 在 lexical 与 realpath 两层都必须位于 workspace，沙箱启动失败按 permission denied fail closed (packages/cli/src/tools/builtin/shell/WorkspaceWriteSandbox.ts, packages/cli/src/tools/builtin/shell/bash.ts)
• 只读审计沙箱不继承任意进程环境、禁止网络和 workspace 写入，只允许专用临时目录写入及受信任 PATH 中的运行时；普通 worktree 沙箱允许 workspace 写入 (packages/cli/src/tools/builtin/shell/WorkspaceWriteSandbox.ts)
• SessionRuntime 启动时先回收 foreground/background orphan，关闭时主动 kill 本 Session 后台进程并释放 worktree 内存绑定 (packages/cli/src/agent/runtime/SessionRuntime.ts)

Resource Bounds

• 后台与前台 capture 分别为 stdout/stderr 各 1 MiB，并最多保留 32 个 chunk；超大 chunk 从 UTF-8 边界保留尾部 (packages/cli/src/tools/builtin/shell/BoundedOutputBuffer.ts)
• worktree diff 最多 100 个文件、单文件 1 MiB、总计 2 MiB；真正交付的 binary patch 上限为 50 MiB，展示截断不改变交付内容 (packages/cli/src/worktree/WorktreeManager.ts)
• 后台容量耗尽返回 RESOURCE_EXHAUSTED/background_shell_busy 且可稍后重试，不会排队等待并额外占用内存 (packages/cli/src/tools/builtin/shell/BackgroundShellManager.ts, packages/cli/src/tools/builtin/shell/bash.ts)