diff --git a/.gitignore b/.gitignore
index f03bc66b5..2a4224105 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,7 +15,7 @@ src/utils/vendor/
 .claude/
 .codex/
 .omx/
-
+.docs/task/
 # Binary / screenshot files (root only)
 /*.png
 *.bmp
diff --git a/README.md b/README.md
index 83703c018..6a9ba02ee 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,7 @@
 | 特性 | 说明 | 文档 |
 |------|------|------|
 | **Claude 群控技术** | Pipe IPC 多实例协作：同机 main/sub 自动编排 + LAN 跨机器零配置发现与通讯，`/pipes` 选择面板 + `Shift+↓` 交互 + 消息广播路由 | [Pipe IPC](https://ccb.agent-aura.top/docs/features/pipes-and-lan) / [LAN](https://ccb.agent-aura.top/docs/features/lan-pipes) |
+| ACP 协议一等一支持 | 支持接入 Zed、Cursor 等 IDE，支持会话恢复、Skills、权限桥接 | [文档](https://ccb.agent-aura.top/docs/features/acp-zed) |
 | Remote Control 私有部署 | Docker 自托管 RCS + Web UI | [文档](https://ccb.agent-aura.top/docs/features/remote-control-self-hosting) |
 | /dream 记忆整理 | 自动整理和优化记忆文件 | [文档](https://ccb.agent-aura.top/docs/features/auto-dream) |
 | Web Search | 内置网页搜索工具 | [文档](https://ccb.agent-aura.top/docs/features/web-browser-tool) |
diff --git a/build.ts b/build.ts
index 11b859330..0ba7076a7 100644
--- a/build.ts
+++ b/build.ts
@@ -30,6 +30,8 @@ const DEFAULT_BUILD_FEATURES = [
   'ULTRAPLAN',
   // P2: daemon + remote control server
   'DAEMON',
+  // ACP (Agent Client Protocol) agent mode
+  'ACP',
   // PR-package restored features
   'WORKFLOW_SCRIPTS',
   'HISTORY_SNIP',
@@ -40,6 +42,8 @@ const DEFAULT_BUILD_FEATURES = [
   'KAIROS',
   'COORDINATOR_MODE',
   'LAN_PIPES',
+  'BG_SESSIONS',
+  'TEMPLATES',
   // 'REVIEW_ARTIFACT', // API 请求无响应，需进一步排查 schema 兼容性
   // P3: poor mode (disable extract_memories + prompt_suggestion)
   'POOR',
diff --git a/bun.lock b/bun.lock
index 38d490689..b7965930b 100644
--- a/bun.lock
+++ b/bun.lock
@@ -5,6 +5,7 @@
     "": {
       "name": "claude-code-best",
       "dependencies": {
+        "@agentclientprotocol/sdk": "^0.19.0",
         "@claude-code-best/mcp-chrome-bridge": "^2.0.7",
         "ws": "^8.20.0",
       },
@@ -256,6 +257,8 @@
     },
   },
   "packages": {
+    "@agentclientprotocol/sdk": ["@agentclientprotocol/sdk@0.19.0", "https://registry.npmmirror.com/@agentclientprotocol/sdk/-/sdk-0.19.0.tgz", { "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" } }, "sha512-U9I8ws9WTOk6jCBAWpXefGSDgVXn14/kV6HFzwWGcstQ02mOQgClMAROHmoIn9GqZbDBDEOkdIbP4P4TEMQdug=="],
+
     "@alcalzone/ansi-tokenize": ["@alcalzone/ansi-tokenize@0.3.0", "https://registry.npmmirror.com/@alcalzone/ansi-tokenize/-/ansi-tokenize-0.3.0.tgz", { "dependencies": { "ansi-styles": "^6.2.1", "is-fullwidth-code-point": "^5.0.0" } }, "sha512-p+CMKJ93HFmLkjXKlXiVGlMQEuRb6H0MokBSwUsX+S6BRX8eV5naFZpQJFfJHjRZY0Hmnqy1/r6UWl3x+19zYA=="],
 
     "@ant/claude-for-chrome-mcp": ["@ant/claude-for-chrome-mcp@workspace:packages/@ant/claude-for-chrome-mcp"],
diff --git a/docs/features/acp-zed.md b/docs/features/acp-zed.md
new file mode 100644
index 000000000..d83e28be2
--- /dev/null
+++ b/docs/features/acp-zed.md
@@ -0,0 +1,189 @@
+# ACP (Agent Client Protocol) — Zed / IDE 集成
+
+> Feature Flag: `FEATURE_ACP=1`（build 和 dev 模式默认启用）
+> 实现状态：可用（支持 Zed、Cursor 等 ACP 客户端）
+> 源码目录：`src/services/acp/`
+
+## 一、功能概述
+
+ACP (Agent Client Protocol) 是一种标准化的 stdio 协议，允许 IDE 和编辑器通过 stdin/stdout 的 NDJSON 流驱动 AI Agent。CCB 实现了完整的 ACP agent 端，可以被 Zed、Cursor 等支持 ACP 的客户端直接调用。
+
+### 核心特性
+
+- **会话管理**：新建 / 恢复 / 加载 / 分叉 / 关闭会话
+- **历史回放**：恢复会话时自动加载并回放对话历史
+- **权限桥接**：ACP 客户端的权限决策映射到 CCB 的工具权限系统
+- **斜杠命令 & Skills**：加载真实命令列表，支持 `/commit`、`/review` 等 prompt 型 skill
+- **Context Window 跟踪**：精确的 usage_update，含 model prefix matching
+- **Prompt 排队**：支持连续发送多条 prompt，自动排队处理
+- **模式切换**：auto / default / acceptEdits / plan / dontAsk / bypassPermissions
+- **模型切换**：运行时切换 AI 模型
+
+## 二、架构
+
+```
+┌──────────────┐    NDJSON/stdio    ┌──────────────────┐
+│  Zed / IDE   │ ◄────────────────► │  CCB ACP Agent   │
+│  (Client)    │   stdin / stdout   │  (Agent)         │
+└──────────────┘                    │                  │
+                                    │  entry.ts        │ ← stdio → NDJSON stream
+                                    │  agent.ts        │ ← ACP protocol handler
+                                    │  bridge.ts       │ ← SDKMessage → ACP SessionUpdate
+                                    │  permissions.ts  │ ← 权限桥接
+                                    │  utils.ts        │ ← 通用工具
+                                    │                  │
+                                    │  QueryEngine     │ ← 内部查询引擎
+                                    └──────────────────┘
+```
+
+### 文件职责
+
+| 文件 | 职责 |
+|------|------|
+| `entry.ts` | 入口，创建 stdio → NDJSON stream，启动 `AgentSideConnection` |
+| `agent.ts` | 实现 ACP `Agent` 接口：会话 CRUD、prompt、cancel、模式/模型切换 |
+| `bridge.ts` | `SDKMessage` → ACP `SessionUpdate` 转换：文本/思考/工具/用量/编辑 diff |
+| `permissions.ts` | ACP `requestPermission()` → CCB `CanUseToolFn` 桥接 |
+| `utils.ts` | Pushable、流转换、权限模式解析、session fingerprint、路径显示 |
+
+## 三、配置 Zed 编辑器
+
+### 3.1 Zed settings.json 配置
+
+打开 Zed 的 `settings.json`（`Cmd+,` → Open Settings），添加 `agent_servers` 配置：
+
+```json
+{
+  "agent_servers": {
+    "ccb": {
+      "type": "custom",
+      "command": "ccb",
+      "args": ["--acp"]
+    }
+  }
+}
+```
+
+### 3.3 API 认证配置
+
+CCB 的 ACP agent 在启动时会自动加载 `settings.json` 中的环境变量（`ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN` 等）。确保已通过 `/login` 配置好 API 供应商。
+
+也可通过环境变量传入：
+
+```json
+{
+  "agent_servers": {
+    "claude-code": {
+      "command": "ccb",
+      "args": ["--acp"],
+      "env": {
+        "ANTHROPIC_BASE_URL": "https://api.example.com/v1",
+        "ANTHROPIC_AUTH_TOKEN": "sk-xxx"
+      }
+    }
+  }
+}
+```
+
+### 3.4 在 Zed 中使用
+
+1. 配置完成后重启 Zed
+2. 打开任意项目目录
+3. 按 `Cmd+'`（macOS）或 `Ctrl+'`（Linux）打开 Agent Panel
+4. 在 Agent Panel 顶部的下拉菜单中选择 **claude-code**
+5. 开始对话
+
+### 3.5 功能说明
+
+| 功能 | 操作 |
+|------|------|
+| 对话 | 在 Agent Panel 中直接输入消息 |
+| 斜杠命令 | 输入 `/` 查看可用 skills 列表（如 `/commit`、`/review`） |
+| 工具权限 | 弹出权限请求时选择 Allow / Reject / Always Allow |
+| 模式切换 | 通过 Agent Panel 的设置菜单切换 auto/default/plan 等模式 |
+| 模型切换 | 通过 Agent Panel 的设置菜单切换 AI 模型 |
+| 会话恢复 | 关闭重开 Zed 后，之前的会话可自动恢复（含历史消息） |
+
+## 四、配置其他 ACP 客户端
+
+ACP 是开放协议，任何支持 ACP 的客户端都可以连接 CCB。通用配置模式：
+
+```
+命令: ccb --acp
+参数: ["--acp"]
+通信: stdin/stdout NDJSON
+协议版本: ACP v1
+```
+
+### 4.1 Cursor
+
+在 Cursor 的设置中配置 MCP / Agent Server，使用同样的 `ccb --acp` 命令。
+
+### 4.2 自定义客户端
+
+使用 `@agentclientprotocol/sdk` 可以快速构建 ACP 客户端：
+
+```typescript
+import { ClientSideConnection, ndJsonStream } from '@agentclientprotocol/sdk'
+
+// 创建连接（将 ccb --acp 作为子进程启动）
+const child = spawn('ccb', ['--acp'])
+const stream = ndJsonStream(
+  Writable.toWeb(child.stdin),
+  Readable.toWeb(child.stdout),
+)
+
+const client = new ClientSideConnection(stream)
+
+// 初始化
+await client.initialize({ clientCapabilities: {} })
+
+// 创建会话
+const { sessionId } = await client.newSession({
+  cwd: '/path/to/project',
+})
+
+// 发送 prompt
+const response = await client.prompt({
+  sessionId,
+  prompt: [{ type: 'text', text: 'Hello, explain this project' }],
+})
+
+// 监听 session 更新
+client.on('sessionUpdate', (update) => {
+  console.log('Update:', update)
+})
+```
+
+## 五、ACP 协议支持矩阵
+
+| 方法 | 状态 | 说明 |
+|------|------|------|
+| `initialize` | ✅ | 返回 agent 信息和能力 |
+| `authenticate` | ✅ | 无需认证（自托管） |
+| `newSession` | ✅ | 创建新会话 |
+| `resumeSession` | ✅ | 恢复已有会话（含历史回放） |
+| `loadSession` | ✅ | 加载指定会话（含历史回放） |
+| `listSessions` | ✅ | 列出可用会话 |
+| `forkSession` | ✅ | 分叉会话 |
+| `closeSession` | ✅ | 关闭会话 |
+| `prompt` | ✅ | 发送消息，支持排队 |
+| `cancel` | ✅ | 取消当前/排队的 prompt |
+| `setSessionMode` | ✅ | 切换权限模式 |
+| `setSessionModel` | ✅ | 切换 AI 模型 |
+| `setSessionConfigOption` | ✅ | 动态修改配置 |
+
+### SessionUpdate 类型
+
+| 类型 | 状态 | 说明 |
+|------|------|------|
+| `agent_message_chunk` | ✅ | 助手文本消息 |
+| `agent_thought_chunk` | ✅ | 思考/推理内容 |
+| `user_message_chunk` | ✅ | 用户消息（历史回放） |
+| `tool_call` | ✅ | 工具调用开始 |
+| `tool_call_update` | ✅ | 工具调用结果/状态更新 |
+| `usage_update` | ✅ | token 用量 + context window |
+| `plan` | ✅ | TodoWrite → plan entries |
+| `available_commands_update` | ✅ | 斜杠命令 & skills 列表 |
+| `current_mode_update` | ✅ | 模式切换通知 |
+| `config_option_update` | ✅ | 配置更新通知 |
diff --git a/docs/features/daemon-restructure-design.md b/docs/features/daemon-restructure-design.md
new file mode 100644
index 000000000..8d0d3abd8
--- /dev/null
+++ b/docs/features/daemon-restructure-design.md
@@ -0,0 +1,318 @@
+# Daemon 重构设计方案
+
+> 分支: `feat/integrate-5-branches`
+> 基于: `f41745cb` (= main `11bb3f62` 内容)
+> 日期: 2026-04-13
+
+## 一、问题概述
+
+### 1.1 命令结构散乱
+
+当前后台进程相关的命令分布在三个不同的位置，没有统一的命名空间：
+
+| 命令 | 注册位置 | 入口 |
+|------|---------|------|
+| `claude daemon start/status/stop` | `cli.tsx` 快速路径 L203 | `daemon/main.ts` |
+| `claude ps` | `cli.tsx` 快速路径 L220 | `cli/bg.ts` |
+| `claude logs <x>` | `cli.tsx` 快速路径 L232 | `cli/bg.ts` |
+| `claude attach <x>` | `cli.tsx` 快速路径 L236 | `cli/bg.ts` |
+| `claude kill <x>` | `cli.tsx` 快速路径 L238 | `cli/bg.ts` |
+| `claude --bg` | `cli.tsx` 快速路径 L244 | `cli/bg.ts` |
+| `claude new/list/reply` | `cli.tsx` 快速路径 L250 | `cli/handlers/templateJobs.ts` |
+| `claude rollback` | `main.tsx` Commander.js L6525 | `cli/rollback.ts` |
+| `claude up` | `main.tsx` Commander.js L6511 | `cli/up.ts` |
+
+**问题**:
+- `ps/logs/attach/kill` 与 `daemon` 逻辑上都是后台进程管理，但互不关联
+- 这些命令都**只有 CLI 入口**，REPL 里输入 `/daemon` 或 `/ps` 不存在
+- `new/list/reply` 是模板任务系统的顶级命令，容易与其他命令冲突（特别是 `list`）
+
+### 1.2 Windows 不支持
+
+`--bg` 和 `attach` 硬依赖 tmux：
+- `bg.ts:handleBgFlag()` 第一步就检查 tmux，不可用直接报错退出
+- `bg.ts:attachHandler()` 用 `tmux attach-session`，无 tmux 替代方案
+- Windows (包括 VS Code 终端) 完全无法使用后台会话功能
+
+### 1.3 无 REPL 入口
+
+对比 `/mcp` 的双注册模式：
+- **CLI**: `claude mcp serve/add/remove/list` (Commander.js, `main.tsx:5760`)
+- **REPL**: `/mcp enable/disable/reconnect` (slash command, `commands/mcp/index.ts`)
+
+`daemon`/`bg`/`job` 系列只有 CLI 快速路径，REPL 中完全不可用。
+
+## 二、目标
+
+1. **层级化命令结构**: 参照 `/mcp` 模式，将后台管理收归 `/daemon`，模板任务收归 `/job`
+2. **跨平台后台会话**: Windows / macOS / Linux 都能启动、附着、终止后台会话
+3. **双注册**: CLI (`claude daemon ...`) + REPL (`/daemon ...`) 同时可用
+4. **向后兼容**: 旧命令保留但输出 deprecation 提示
+
+## 三、命令结构设计
+
+### 3.1 `/daemon` — 后台进程管理
+
+合并 daemon supervisor + bg sessions 为统一命名空间：
+
+```
+claude daemon <subcommand>     ← CLI 入口 (cli.tsx 快速路径)
+/daemon <subcommand>           ← REPL 入口 (slash command, local-jsx)
+
+子命令:
+  status                       综合状态面板 (daemon + 所有会话)
+  start [--dir <path>]         启动 daemon supervisor
+  stop                         停止 daemon
+  bg [args...]                 启动后台会话
+  attach [target]              附着到后台会话
+  logs [target]                查看会话日志
+  kill [target]                终止会话
+  (无参数)                     等同于 status
+```
+
+**CLI 快速路径路由** (`cli.tsx`):
+```typescript
+// 新: 统一入口
+if (feature('DAEMON') && args[0] === 'daemon') {
+  const sub = args[1] || 'status'
+  switch (sub) {
+    case 'start': case 'stop': case 'status':
+      await daemonMain([sub, ...args.slice(2)])
+      break
+    case 'bg':
+      await bg.handleBgStart(args.slice(2))
+      break
+    case 'attach': case 'logs': case 'kill':
+      await bg[`${sub}Handler`](args[2])
+      break
+  }
+}
+
+// 向后兼容 (deprecated)
+if (feature('BG_SESSIONS') && ['ps','logs','attach','kill'].includes(args[0])) {
+  console.warn(`[deprecated] Use: claude daemon ${args[0] === 'ps' ? 'status' : args[0]}`)
+  // ... delegate to daemon subcommand
+}
+```
+
+**REPL 斜杠命令** (`commands/daemon/index.ts`):
+```typescript
+const daemon = {
+  type: 'local-jsx',
+  name: 'daemon',
+  description: 'Manage background sessions and daemon',
+  argumentHint: '[status|start|stop|bg|attach|logs|kill]',
+  isEnabled: () => feature('DAEMON') || feature('BG_SESSIONS'),
+  load: () => import('./daemon.js'),
+} satisfies Command
+```
+
+### 3.2 `/job` — 模板任务管理
+
+```
+claude job <subcommand>        ← CLI 入口
+/job <subcommand>              ← REPL 入口
+
+子命令:
+  list                         列出模板和活跃任务
+  new <template> [args]        从模板创建任务
+  reply <id> <text>            回复任务
+  status <id>                  查看任务状态
+  (无参数)                     等同于 list
+```
+
+### 3.3 独立命令 (不变)
+
+```
+claude up                      保持顶级 (简短的 bootstrap 命令)
+claude rollback [target]       保持顶级 (低频运维命令)
+```
+
+## 四、跨平台后台引擎
+
+### 4.1 引擎抽象
+
+```typescript
+// src/cli/bg/engine.ts
+export interface BgEngine {
+  readonly name: string
+
+  /** 当前平台是否可用 */
+  available(): Promise<boolean>
+
+  /** 启动后台会话 */
+  start(opts: BgStartOptions): Promise<BgStartResult>
+
+  /** 附着到后台会话（blocking） */
+  attach(session: SessionEntry): Promise<void>
+}
+
+export interface BgStartOptions {
+  sessionName: string
+  args: string[]
+  env: Record<string, string | undefined>
+  logPath: string
+  cwd: string
+}
+
+export interface BgStartResult {
+  pid: number
+  sessionName: string
+  logPath: string
+  engineUsed: string
+}
+```
+
+### 4.2 三种引擎实现
+
+| 引擎 | 平台 | 启动方式 | attach 方式 |
+|------|------|---------|------------|
+| TmuxEngine | macOS/Linux (有 tmux) | `tmux new-session -d` | `tmux attach-session` |
+| DetachedEngine | Windows / 无 tmux 的 macOS/Linux | `spawn({ detached, stdio→logFile })` | `tail -f` 日志文件 |
+
+#### DetachedEngine 详细设计
+
+**启动 (`start`)**:
+```typescript
+// 1. 打开日志文件 fd
+const logFd = fs.openSync(logPath, 'a')
+// 2. detached spawn, stdout/stderr 重定向到日志
+const child = spawn(process.execPath, execArgs, {
+  detached: true,
+  stdio: ['ignore', logFd, logFd],
+  env,
+  cwd,
+})
+child.unref()
+fs.closeSync(logFd)
+// 3. 写 sessions/<PID>.json
+```
+
+**附着 (`attach`)**:
+```typescript
+// 跨平台 tail -f 实现
+// 1. 读取已有日志内容输出到 stdout
+// 2. fs.watch(logPath) 监听变化
+// 3. 每次变化读取新增内容
+// 4. Ctrl+C 退出 tail（不杀后台进程）
+```
+
+#### 引擎选择逻辑
+
+```typescript
+// src/cli/bg/engines/index.ts
+export async function selectEngine(): Promise<BgEngine> {
+  if (process.platform === 'win32') {
+    return new DetachedEngine()
+  }
+
+  const tmux = new TmuxEngine()
+  if (await tmux.available()) {
+    return tmux
+  }
+
+  return new DetachedEngine()
+}
+```
+
+### 4.3 SessionEntry 扩展
+
+```typescript
+interface SessionEntry {
+  // ... 现有字段
+  engine: 'tmux' | 'detached'   // 新增: 记录使用的引擎
+  tmuxSessionName?: string       // tmux 引擎才有
+  logPath?: string               // 两种引擎都有
+}
+```
+
+`attach` 时根据 `session.engine` 选择对应的 attach 策略。
+
+## 五、文件变更清单
+
+### 新增文件 (10 个)
+
+```
+src/cli/bg/engine.ts                   BgEngine 接口定义
+src/cli/bg/engines/tmux.ts             TmuxEngine (从 bg.ts 提取)
+src/cli/bg/engines/detached.ts         DetachedEngine (新实现)
+src/cli/bg/engines/index.ts            引擎选择 + re-export
+src/cli/bg/tail.ts                     跨平台日志 tail (用于 detached attach)
+src/commands/daemon/index.ts           /daemon REPL 斜杠命令注册
+src/commands/daemon/daemon.tsx         /daemon 子命令路由 + status UI
+src/commands/job/index.ts              /job REPL 斜杠命令注册
+src/commands/job/job.tsx               /job 子命令路由 + UI
+docs/features/daemon-restructure-design.md  本设计文档
+```
+
+### 修改文件 (6 个)
+
+```
+src/cli/bg.ts                          重构: handler 函数改为调用 BgEngine
+src/entrypoints/cli.tsx                快速路径: daemon 统一入口 + 向后兼容
+src/commands.ts                        注册 /daemon 和 /job 斜杠命令
+src/daemon/main.ts                     daemonMain() 增加 bg/ps/logs 子命令分发
+src/main.tsx                           Commander.js: 可选注册 daemon/job 子命令
+src/cli/handlers/templateJobs.ts       适配 /job 入口 (可能不需改)
+```
+
+### 不动的文件
+
+```
+src/daemon/state.ts                    daemon PID 状态管理 (无需改)
+src/jobs/state.ts                      job 状态管理 (无需改)
+src/jobs/templates.ts                  模板发现 (无需改)
+src/jobs/classifier.ts                 任务分类器 (无需改)
+src/cli/rollback.ts                    保持顶级命令 (无需改)
+src/cli/up.ts                          保持顶级命令 (无需改)
+```
+
+## 六、可行性分析
+
+### 6.1 风险评估
+
+| 风险 | 级别 | 缓解措施 |
+|------|------|---------|
+| cli.tsx 快速路径修改影响启动性能 | 低 | 仅改路由逻辑，import 仍然 lazy |
+| DetachedEngine 的 attach 在 Windows 上 fs.watch 不可靠 | 中 | 使用轮询 fallback (setInterval + fs.stat) |
+| 向后兼容的 deprecation 可能破坏脚本 | 低 | 旧命令保持可用，仅输出 stderr 警告 |
+| REPL 中 /daemon bg 需要 spawn 子进程 | 中 | 参考 /assistant 的 NewInstallWizard (已有 spawn 先例) |
+| tsc 类型兼容 | 低 | 接口定义清晰，不引入 any |
+
+### 6.2 工作量估计
+
+| Task | 文件数 | 复杂度 |
+|------|--------|--------|
+| Task 013: BgEngine 抽象 + 引擎实现 | 5 新增 + 1 修改 | 中 |
+| Task 014: /daemon 命令层级化 | 3 新增 + 3 修改 | 中 |
+| Task 015: /job 命令层级化 | 2 新增 + 2 修改 | 低 |
+| Task 016: 向后兼容 + 测试 | 0 新增 + 2 修改 | 低 |
+
+### 6.3 依赖关系
+
+```
+Task 013 (BgEngine) ← 无依赖，可独立开发
+Task 014 (/daemon)  ← 依赖 Task 013 (引擎选择)
+Task 015 (/job)     ← 无依赖，可与 013 并行
+Task 016 (兼容)     ← 依赖 Task 014 + 015
+```
+
+## 七、设计决策记录
+
+### D1: 为什么 daemon + bg sessions 合为一个命名空间？
+
+用户视角：都是"后台运行的东西"。分开会导致 `claude daemon status` 看 supervisor + `claude ps` 看会话，割裂感强。合并后 `claude daemon status` 一次性展示 supervisor 状态 + 所有会话列表。
+
+### D2: 为什么 rollback/up 不收入 daemon？
+
+它们本质是**版本管理/环境初始化**，不是后台进程管理。`claude up` 是同步阻塞的 setup 脚本，不涉及 daemon 或后台会话。保持顶级更直观。
+
+### D3: 为什么 DetachedEngine 的 attach 用 tail 而不是 IPC？
+
+1. 日志文件是最简单的跨平台方案，无需额外依赖
+2. UDS Pipe IPC 系统 (usePipeIpc) 设计用于实例间通信，不是终端附着
+3. tmux attach 的体验（完整 PTY）无法在纯 detached 模式下复制，tail 是最诚实的替代
+
+### D4: 为什么不用 Windows Terminal 的 tab/pane API？
+
+Windows Terminal 的 `wt.exe` 新窗口/标签功能不够通用——用户可能在 VS Code、ConEmu、cmder 等终端中。detached + log 是唯一跨终端方案。
diff --git a/docs/features/stub-recovery-design-1-4.md b/docs/features/stub-recovery-design-1-4.md
new file mode 100644
index 000000000..e25afddc3
--- /dev/null
+++ b/docs/features/stub-recovery-design-1-4.md
@@ -0,0 +1,310 @@
+# Stub 恢复设计 1-4
+
+> 日期：2026-04-12
+> 目标：基于当前代码边界，为下一阶段 4 个 stub/半 stub 命令面给出可实施的设计方案。
+> 排序原则：按建议实施顺序排序，不按问题严重性排序。
+
+## 设计原则
+
+- 先做能独立闭环、收益明确、改动边界清晰的项。
+- 大项拆成 `MVP` 和 `Phase 2+`，避免一次性掉进大范围恢复。
+- 优先复用已有状态、传输层、日志与配置能力，不重造协议。
+- 设计以当前仓库实际代码为准，不以旧文档的理想状态为准。
+
+## 1. `claude daemon status` / `claude daemon stop`
+
+### 现状
+
+- `start` 路径已有完整 supervisor + worker 生命周期：
+  [src/daemon/main.ts](</e:/Source_code/Claude-code-bast/src/daemon/main.ts:1>)
+  [src/daemon/workerRegistry.ts](</e:/Source_code/Claude-code-bast/src/daemon/workerRegistry.ts:1>)
+- `status` / `stop` 目前只是占位输出：
+  [src/daemon/main.ts](</e:/Source_code/Claude-code-bast/src/daemon/main.ts:49>)
+- `/remote-control-server` 有自己的命令内 UI 状态，但只维护当前进程内的 `daemonProcess`，并不适合作为跨进程 CLI 管理基础：
+  [src/commands/remoteControlServer/remoteControlServer.tsx](</e:/Source_code/Claude-code-bast/src/commands/remoteControlServer/remoteControlServer.tsx:32>)
+
+### 目标
+
+- 让 `claude daemon status` 和 `claude daemon stop` 在另一个 CLI 进程中也能正确工作。
+- 不依赖 TUI 内存态，不要求当前命令进程就是启动 daemon 的那个进程。
+
+### MVP 方案
+
+- 新增 daemon 状态文件，例如：
+  `~/.claude/daemon/remote-control.json`
+- `start` 时写入：
+  - supervisor pid
+  - cwd
+  - startedAt
+  - worker kinds
+  - 最近状态
+- `status`：
+  - 读取状态文件
+  - 用现有进程探测能力验证 pid 是否存活
+  - 输出 `running / stopped / stale`
+  - stale 时自动清理状态文件
+- `stop`：
+  - 读取 pid
+  - 发送 `SIGTERM`
+  - 等待退出
+  - 超时后 `SIGKILL`
+  - 清理状态文件
+
+### 代码范围
+
+- 新增 `src/daemon/state.ts`
+- 修改 [src/daemon/main.ts](</e:/Source_code/Claude-code-bast/src/daemon/main.ts:1>)
+- 轻量修改 [src/commands/remoteControlServer/remoteControlServer.tsx](</e:/Source_code/Claude-code-bast/src/commands/remoteControlServer/remoteControlServer.tsx:32>)，让 UI 尽量读取同一份状态文件
+
+### 验证
+
+1. `claude daemon start`
+2. 新开终端执行 `claude daemon status`
+3. 执行 `claude daemon stop`
+4. 再次执行 `claude daemon status`，确认返回 `stopped` 或清晰的 `stale cleaned`
+
+### 风险
+
+- Windows 信号模型和 Unix 不同，`stop` 需要超时兜底。
+- 当前设计默认单 supervisor，不处理多实例并发。
+
+### 工作量判断
+
+- 小
+- 适合作为下一步的首选实现项
+
+## 2. `BG_SESSIONS`
+
+### 现状
+
+- fast-path 已接好：
+  [src/entrypoints/cli.tsx](</e:/Source_code/Claude-code-bast/src/entrypoints/cli.tsx:218>)
+- session registry 已有真实实现：
+  [src/utils/concurrentSessions.ts](</e:/Source_code/Claude-code-bast/src/utils/concurrentSessions.ts:1>)
+- `exit` 在 bg session 内已会 `tmux detach-client`：
+  [src/commands/exit/exit.tsx](</e:/Source_code/Claude-code-bast/src/commands/exit/exit.tsx:20>)
+- 但 CLI handler 仍全空：
+  [src/cli/bg.ts](</e:/Source_code/Claude-code-bast/src/cli/bg.ts:1>)
+- task summary 仍然是 stub：
+  [src/utils/taskSummary.ts](</e:/Source_code/Claude-code-bast/src/utils/taskSummary.ts:1>)
+
+### 目标
+
+- 先把 `ps` / `logs` / `kill` 做成真正有用的 session 管理命令。
+- 不在第一阶段就强行补完 `attach` / `--bg`。
+
+### Phase 2A：MVP
+
+- 实现 `ps`
+  - 从 registry 读取 live sessions
+  - 展示 pid、kind、sessionId、cwd、name、startedAt、bridgeSessionId
+  - 如果有 activity/status，则一并展示
+- 实现 `logs`
+  - 支持按 `sessionId / pid / name` 查找
+  - 优先复用本地 transcript/log 读取能力
+  - 如果 registry 里存在 `logPath`，支持 tail 文件
+- 实现 `kill`
+  - 解析目标 session
+  - 发退出信号
+  - 清理 stale registry
+
+### Phase 2B：后续
+
+- 实现 `attach`
+- 实现 `--bg`
+- 实现 `taskSummary` 的中途状态更新
+
+### 为什么要拆
+
+- 现有 registry 记录了 `pid / sessionId / name / logPath`
+- 但没有可靠的 tmux attach target
+- 所以 `attach` 和 `--bg` 不是简单补 handler，而是需要补启动/附着元数据设计
+
+### 代码范围
+
+- 修改 [src/cli/bg.ts](</e:/Source_code/Claude-code-bast/src/cli/bg.ts:1>)
+- 修改 [src/utils/concurrentSessions.ts](</e:/Source_code/Claude-code-bast/src/utils/concurrentSessions.ts:1>) 以便后续 attach/--bg 扩展
+- 修改 [src/utils/taskSummary.ts](</e:/Source_code/Claude-code-bast/src/utils/taskSummary.ts:1>)
+- 复用：
+  [src/utils/sessionStorage.ts](</e:/Source_code/Claude-code-bast/src/utils/sessionStorage.ts:3870>)
+  [src/utils/udsClient.ts](</e:/Source_code/Claude-code-bast/src/utils/udsClient.ts:1>)
+
+### 验证
+
+1. `ps` 能列出 live sessions
+2. `logs <sessionId|pid|name>` 能输出对应日志
+3. `kill <sessionId|pid|name>` 能结束目标 session
+
+### 风险
+
+- `attach` / `--bg` 第二阶段需要 tmux 元数据设计
+- Windows 下 tmux 路径需要明确降级策略
+
+### 工作量判断
+
+- `ps/logs/kill` 中等
+- `attach/--bg` 明显更大，应分阶段
+
+## 3. `TEMPLATES`
+
+### 现状
+
+- 命令入口只有 fast-path：
+  [src/entrypoints/cli.tsx](</e:/Source_code/Claude-code-bast/src/entrypoints/cli.tsx:249>)
+- handler 是空的：
+  [src/cli/handlers/templateJobs.ts](</e:/Source_code/Claude-code-bast/src/cli/handlers/templateJobs.ts:1>)
+- `markdownConfigLoader` 已把 `templates` 纳入配置目录：
+  [src/utils/markdownConfigLoader.ts](</e:/Source_code/Claude-code-bast/src/utils/markdownConfigLoader.ts:29>)
+- `query / stopHooks` 已预留 job classifier 链路：
+  [src/query/stopHooks.ts](</e:/Source_code/Claude-code-bast/src/query/stopHooks.ts:103>)
+- `jobs/classifier.ts` 仍是 stub：
+  [src/jobs/classifier.ts](</e:/Source_code/Claude-code-bast/src/jobs/classifier.ts:1>)
+
+### 目标
+
+- 把 `new / list / reply` 做成可用的模板任务系统。
+- 第一阶段不碰复杂的自动分类与自动执行。
+
+### MVP 方案
+
+- 模板来源：
+  `.claude/templates/*.md`
+- 模板格式：
+  复用现有 markdown + frontmatter 解析，不另外设计 DSL
+- `list`
+  - 列出所有模板
+  - 显示模板名、description、路径
+- `new <template> [args...]`
+  - 解析模板
+  - 在 `~/.claude/jobs/<job-id>/` 下创建 job 目录
+  - 写入 `template.md`、`input.txt`、`state.json`
+  - 返回 job id 与目录
+- `reply <job-id> <text>`
+  - 将回复写入 `replies.jsonl` 或 `input.txt`
+  - 更新 `state.json`
+
+### Phase 2
+
+- 恢复 [src/jobs/classifier.ts](</e:/Source_code/Claude-code-bast/src/jobs/classifier.ts:1>)
+- 让带 `CLAUDE_JOB_DIR` 的 job session 在 turn 完成后自动更新 `state.json`
+- 再决定是否补自动 job runner
+
+### 为什么要拆
+
+- 当前证据表明这是“template job commands”，不是单纯模板列表
+- 但自动 job 运行链路没有足够现成实现，先做文件系统 job lifecycle 更稳
+
+### 代码范围
+
+- 修改 [src/cli/handlers/templateJobs.ts](</e:/Source_code/Claude-code-bast/src/cli/handlers/templateJobs.ts:1>)
+- 新增 `src/jobs/state.ts`
+- 新增 `src/jobs/templates.ts`
+- Phase 2 再改 [src/jobs/classifier.ts](</e:/Source_code/Claude-code-bast/src/jobs/classifier.ts:1>)
+
+### 验证
+
+1. `list` 能列出 `.claude/templates`
+2. `new` 能创建 job 目录和状态文件
+3. `reply` 能更新 job 内容和状态
+4. Phase 2 再验证 classifier 写状态
+
+### 风险
+
+- frontmatter schema 需要先定义最小字段集
+- 一旦扩展到“自动运行 job”，范围会明显膨胀
+
+### 工作量判断
+
+- MVP 中等
+- 完整 job 系统偏大
+
+## 4. `assistant [sessionId]`
+
+### 现状
+
+- attach 主流程其实已经存在：
+  [src/main.tsx](</e:/Source_code/Claude-code-bast/src/main.tsx:4708>)
+- 远端 viewer 所需基础模块已存在：
+  [src/remote/RemoteSessionManager.ts](</e:/Source_code/Claude-code-bast/src/remote/RemoteSessionManager.ts:1>)
+  [src/hooks/useAssistantHistory.ts](</e:/Source_code/Claude-code-bast/src/hooks/useAssistantHistory.ts:1>)
+  [src/assistant/sessionHistory.ts](</e:/Source_code/Claude-code-bast/src/assistant/sessionHistory.ts:1>)
+- 真正 stub 的主要是：
+  [src/assistant/sessionDiscovery.ts](</e:/Source_code/Claude-code-bast/src/assistant/sessionDiscovery.ts:1>)
+  [src/assistant/AssistantSessionChooser.ts](</e:/Source_code/Claude-code-bast/src/assistant/AssistantSessionChooser.ts:1>)
+  [src/commands/assistant/assistant.ts](</e:/Source_code/Claude-code-bast/src/commands/assistant/assistant.ts:7>)
+  [src/assistant/index.ts](</e:/Source_code/Claude-code-bast/src/assistant/index.ts:1>)
+
+### 目标
+
+- 不一次性恢复整个 KAIROS 助手系统。
+- 先做“明确 sessionId 的 viewer attach 可用”，再逐步补 discovery / chooser / install。
+
+### Phase 4A：MVP
+
+- 只支持 `claude assistant <sessionId>`
+- 对 `claude assistant` 无参数模式，先返回明确提示：
+  - 当前版本需要显式 `sessionId`
+  - discovery 尚未启用
+- 这样可以直接复用现有 attach 分支，不必先恢复 chooser/install wizard
+
+### Phase 4B
+
+- 恢复 `discoverAssistantSessions()`
+- 数据来源优先复用现有 sessions / bridge / teleport API，而不是新协议
+- 让 `claude assistant` 无参数时能拿到候选 session 列表
+
+### Phase 4C
+
+- 恢复 `AssistantSessionChooser`
+- 多 session 时可交互选择
+
+### Phase 4D
+
+- 最后考虑 install wizard 辅助函数
+- 这部分属于“没有 session 时如何引导”，不是 attach 核心路径
+
+### 为什么要拆
+
+- attach 渲染层与远端消息通道大部分已经在
+- 真正缺的是“如何发现目标 session”和“如何交互选择”
+- 如果把 `src/assistant/index.ts` 的整套 KAIROS 正常模式也一起拉进来，范围会失控
+
+### 代码范围
+
+- Phase 4A：
+  - [src/main.tsx](</e:/Source_code/Claude-code-bast/src/main.tsx:4708>)
+  - [src/commands/assistant/index.ts](</e:/Source_code/Claude-code-bast/src/commands/assistant/index.ts:1>)
+- Phase 4B：
+  - [src/assistant/sessionDiscovery.ts](</e:/Source_code/Claude-code-bast/src/assistant/sessionDiscovery.ts:1>)
+- Phase 4C：
+  - [src/assistant/AssistantSessionChooser.ts](</e:/Source_code/Claude-code-bast/src/assistant/AssistantSessionChooser.ts:1>)
+- Phase 4D：
+  - [src/commands/assistant/assistant.ts](</e:/Source_code/Claude-code-bast/src/commands/assistant/assistant.ts:7>)
+
+### 验证
+
+1. `claude assistant <sessionId>` 能进入 remote viewer
+2. 历史懒加载工作正常
+3. 无参数模式先给出明确提示
+4. 后续阶段再分别验证 discovery / chooser / install
+
+### 风险
+
+- 这是四项里范围最大的
+- 一旦把 KAIROS 正常模式整体拉入，会从“viewer attach”膨胀成“完整 assistant mode 恢复”
+
+### 工作量判断
+
+- Phase 4A 中等
+- 4A-4D 全做完很大
+
+## 建议执行顺序
+
+1. `claude daemon status` / `claude daemon stop`
+2. `BG_SESSIONS` 先做 `ps/logs/kill`
+3. `TEMPLATES` 先做 job 文件系统 MVP
+4. `assistant [sessionId]` 先做显式 sessionId attach，再补 discovery/chooser/install
+
+## 简短结论
+
+这四项里，最适合立刻实现的是 `daemon status/stop`。`BG_SESSIONS` 和 `TEMPLATES` 适合按 MVP 先补 handler 与文件系统闭环。`assistant [sessionId]` 不能整块硬上，应该按“attach → discovery → chooser → install”拆开恢复。
diff --git a/docs/task/task-001-daemon-status-stop.md b/docs/task/task-001-daemon-status-stop.md
new file mode 100644
index 000000000..472f28f6a
--- /dev/null
+++ b/docs/task/task-001-daemon-status-stop.md
@@ -0,0 +1,77 @@
+# Task 001: daemon status / stop
+
+> 来源: [stub-recovery-design-1-4.md](../features/stub-recovery-design-1-4.md) 第 1 项
+> 优先级: P0 (首选实现项)
+> 工作量: 小
+> 状态: DONE
+
+## 目标
+
+让 `claude daemon status` 和 `claude daemon stop` 在任意 CLI 进程中都能正确工作，不依赖 TUI 内存态。
+
+## 背景
+
+- `start` 路径已有完整 supervisor + worker 生命周期 (`src/daemon/main.ts`, `src/daemon/workerRegistry.ts`)
+- `status` / `stop` 目前只是占位输出 (`src/daemon/main.ts:49`)
+- `/remote-control-server` 有自己的命令内 UI 状态，但只维护当前进程内的 `daemonProcess`，不适合跨进程管理
+
+## 实现方案
+
+### 新增文件
+
+| 文件 | 说明 |
+|------|------|
+| `src/daemon/state.ts` | daemon 状态文件读写模块 |
+
+### 修改文件
+
+| 文件 | 改动 |
+|------|------|
+| `src/daemon/main.ts` | `start` 写入状态文件；`status`/`stop` 调用 state 模块 |
+| `src/commands/remoteControlServer/remoteControlServer.tsx` | 读取同一份状态文件（轻量改动） |
+
+### 状态文件
+
+路径: `~/.claude/daemon/remote-control.json`
+
+```json
+{
+  "pid": 12345,
+  "cwd": "/path/to/project",
+  "startedAt": "2026-04-12T10:00:00Z",
+  "workerKinds": ["bridge", "rcs"],
+  "lastStatus": "running"
+}
+```
+
+### status 逻辑
+
+1. 读取状态文件
+2. 用进程探测验证 pid 是否存活
+3. 输出 `running` / `stopped` / `stale`
+4. stale 时自动清理状态文件
+
+### stop 逻辑
+
+1. 读取 pid
+2. 发送 `SIGTERM`
+3. 等待退出（超时兜底）
+4. 超时后 `SIGKILL`
+5. 清理状态文件
+
+## 验证步骤
+
+- [ ] `claude daemon start` 正常启动并写入状态文件
+- [ ] 新开终端执行 `claude daemon status`，显示 `running`
+- [ ] 执行 `claude daemon stop`，daemon 正常退出
+- [ ] 再次执行 `claude daemon status`，返回 `stopped` 或 `stale cleaned`
+- [ ] Windows 下 stop 超时兜底正常工作
+
+## 风险
+
+- Windows 信号模型和 Unix 不同，`stop` 需要超时兜底
+- 当前设计默认单 supervisor，不处理多实例并发
+
+## 依赖
+
+无外部依赖，可独立实施。
diff --git a/docs/task/task-002-bg-sessions-ps-logs-kill.md b/docs/task/task-002-bg-sessions-ps-logs-kill.md
new file mode 100644
index 000000000..8986394d7
--- /dev/null
+++ b/docs/task/task-002-bg-sessions-ps-logs-kill.md
@@ -0,0 +1,80 @@
+# Task 002: BG_SESSIONS — ps / logs / kill
+
+> 来源: [stub-recovery-design-1-4.md](../features/stub-recovery-design-1-4.md) 第 2 项
+> 优先级: P1
+> 工作量: 中等
+> 状态: DONE
+> 阶段: Phase 2A (MVP)
+
+## 目标
+
+把 `ps` / `logs` / `kill` 做成真正有用的 session 管理命令。不在第一阶段补完 `attach` / `--bg`。
+
+## 背景
+
+- fast-path 已接好 (`src/entrypoints/cli.tsx:218`)
+- session registry 已有真实实现 (`src/utils/concurrentSessions.ts`)
+- `exit` 在 bg session 内已会 `tmux detach-client` (`src/commands/exit/exit.tsx:20`)
+- CLI handler 仍全空 (`src/cli/bg.ts`)
+- task summary 仍然是 stub (`src/utils/taskSummary.ts`)
+
+## 实现方案
+
+### 修改文件
+
+| 文件 | 改动 |
+|------|------|
+| `src/cli/bg.ts` | 实现 `ps` / `logs` / `kill` handler |
+| `src/utils/concurrentSessions.ts` | 扩展以便后续 attach/--bg 使用 |
+| `src/utils/taskSummary.ts` | 补充基础实现 |
+
+### 复用模块
+
+- `src/utils/sessionStorage.ts` — session 存储
+- `src/utils/udsClient.ts` — UDS 通信
+
+### ps 命令
+
+- 从 registry 读取 live sessions
+- 展示: pid, kind, sessionId, cwd, name, startedAt, bridgeSessionId
+- 如果有 activity/status，一并展示
+
+### logs 命令
+
+- 支持按 `sessionId` / `pid` / `name` 查找
+- 优先复用本地 transcript/log 读取能力
+- 如果 registry 里存在 `logPath`，支持 tail 文件
+
+### kill 命令
+
+- 解析目标 session
+- 发退出信号
+- 清理 stale registry
+
+## 验证步骤
+
+- [ ] `ps` 能列出当前 live sessions
+- [ ] `logs <sessionId|pid|name>` 能输出对应日志
+- [ ] `kill <sessionId|pid|name>` 能结束目标 session 并清理 registry
+- [ ] 无 live session 时各命令有明确提示
+
+## Phase 2B (后续)
+
+- [ ] 实现 `attach`
+- [ ] 实现 `--bg`
+- [ ] 实现 `taskSummary` 的中途状态更新
+
+### 为什么拆分
+
+- 现有 registry 记录了 `pid / sessionId / name / logPath`
+- 但没有可靠的 tmux attach target
+- `attach` 和 `--bg` 需要补启动/附着元数据设计，不是简单补 handler
+
+## 风险
+
+- `attach` / `--bg` 第二阶段需要 tmux 元数据设计
+- Windows 下 tmux 路径需要明确降级策略
+
+## 依赖
+
+- Task 001 (daemon 状态管理可复用模式，但非硬性依赖)
diff --git a/docs/task/task-003-templates-job-mvp.md b/docs/task/task-003-templates-job-mvp.md
new file mode 100644
index 000000000..3355dd40c
--- /dev/null
+++ b/docs/task/task-003-templates-job-mvp.md
@@ -0,0 +1,87 @@
+# Task 003: TEMPLATES — job 文件系统 MVP
+
+> 来源: [stub-recovery-design-1-4.md](../features/stub-recovery-design-1-4.md) 第 3 项
+> 优先级: P2
+> 工作量: 中等
+> 状态: DONE
+> 阶段: MVP
+
+## 目标
+
+把 `new` / `list` / `reply` 做成可用的模板任务系统。第一阶段不碰复杂的自动分类与自动执行。
+
+## 背景
+
+- 命令入口只有 fast-path (`src/entrypoints/cli.tsx:249`)
+- handler 是空的 (`src/cli/handlers/templateJobs.ts`)
+- `markdownConfigLoader` 已把 `templates` 纳入配置目录 (`src/utils/markdownConfigLoader.ts:29`)
+- `query/stopHooks` 已预留 job classifier 链路 (`src/query/stopHooks.ts:103`)
+- `jobs/classifier.ts` 仍是 stub (`src/jobs/classifier.ts`)
+
+## 实现方案
+
+### 新增文件
+
+| 文件 | 说明 |
+|------|------|
+| `src/jobs/state.ts` | job 状态管理 |
+| `src/jobs/templates.ts` | 模板解析与列表 |
+
+### 修改文件
+
+| 文件 | 改动 |
+|------|------|
+| `src/cli/handlers/templateJobs.ts` | 实现 `new` / `list` / `reply` handler |
+
+### 模板来源
+
+`.claude/templates/*.md`
+
+### 模板格式
+
+复用现有 markdown + frontmatter 解析，不另外设计 DSL。
+
+### list 命令
+
+- 列出所有模板
+- 显示: 模板名, description, 路径
+
+### new 命令
+
+- 解析模板
+- 在 `~/.claude/jobs/<job-id>/` 下创建 job 目录
+- 写入 `template.md`, `input.txt`, `state.json`
+- 返回 job id 与目录路径
+
+### reply 命令
+
+- 将回复写入 `replies.jsonl` 或 `input.txt`
+- 更新 `state.json`
+
+## 验证步骤
+
+- [ ] `list` 能列出 `.claude/templates` 下的所有模板
+- [ ] `new <template> [args...]` 能创建 job 目录和状态文件
+- [ ] `reply <job-id> <text>` 能更新 job 内容和状态
+- [ ] frontmatter schema 最小字段集已定义
+
+## Phase 2 (后续)
+
+- [ ] 恢复 `src/jobs/classifier.ts`
+- [ ] 让带 `CLAUDE_JOB_DIR` 的 job session 在 turn 完成后自动更新 `state.json`
+- [ ] 再决定是否补自动 job runner
+
+### 为什么拆分
+
+- 当前是 "template job commands"，不是单纯模板列表
+- 自动 job 运行链路没有足够现成实现
+- 先做文件系统 job lifecycle 更稳
+
+## 风险
+
+- frontmatter schema 需要先定义最小字段集
+- 一旦扩展到"自动运行 job"，范围会明显膨胀
+
+## 依赖
+
+无硬性依赖，可独立实施。
diff --git a/docs/task/task-004-assistant-session-attach.md b/docs/task/task-004-assistant-session-attach.md
new file mode 100644
index 000000000..5ae06aee8
--- /dev/null
+++ b/docs/task/task-004-assistant-session-attach.md
@@ -0,0 +1,103 @@
+# Task 004: assistant [sessionId] — 分阶段恢复
+
+> 来源: [stub-recovery-design-1-4.md](../features/stub-recovery-design-1-4.md) 第 4 项
+> 优先级: P3
+> 工作量: Phase 4A 中等，4A-4D 全做完很大
+> 状态: Phase 4A DONE, 4B-4D TODO
+
+## 目标
+
+不一次性恢复整个 KAIROS 助手系统。先做"明确 sessionId 的 viewer attach 可用"，再逐步补 discovery / chooser / install。
+
+## 背景
+
+- attach 主流程已存在 (`src/main.tsx:4708`)
+- 远端 viewer 所需基础模块已存在:
+  - `src/remote/RemoteSessionManager.ts`
+  - `src/hooks/useAssistantHistory.ts`
+  - `src/assistant/sessionHistory.ts`
+- 真正 stub 的主要是:
+  - `src/assistant/sessionDiscovery.ts`
+  - `src/assistant/AssistantSessionChooser.ts`
+  - `src/commands/assistant/assistant.ts:7`
+  - `src/assistant/index.ts`
+
+## 分阶段实现
+
+### Phase 4A: MVP — 显式 sessionId attach
+
+**修改文件:**
+
+| 文件 | 改动 |
+|------|------|
+| `src/main.tsx` | 确保 attach 分支可用 |
+| `src/commands/assistant/index.ts` | 实现显式 sessionId 参数入口 |
+
+**行为:**
+- `claude assistant <sessionId>` — 进入 remote viewer
+- `claude assistant` (无参数) — 返回明确提示: 当前版本需要显式 sessionId，discovery 尚未启用
+
+**验证:**
+- [ ] `claude assistant <sessionId>` 能进入 remote viewer
+- [ ] 历史懒加载工作正常
+- [ ] 无参数模式给出明确提示
+
+### Phase 4B: session discovery
+
+**修改文件:**
+
+| 文件 | 改动 |
+|------|------|
+| `src/assistant/sessionDiscovery.ts` | 恢复 `discoverAssistantSessions()` |
+
+**行为:**
+- 数据来源优先复用现有 sessions / bridge / teleport API，不新增协议
+- `claude assistant` 无参数时能拿到候选 session 列表
+
+**验证:**
+- [ ] 无参数调用能列出可用 sessions
+- [ ] 数据来源复用现有通道
+
+### Phase 4C: session chooser
+
+**修改文件:**
+
+| 文件 | 改动 |
+|------|------|
+| `src/assistant/AssistantSessionChooser.ts` | 恢复交互式选择器 |
+
+**行为:**
+- 多 session 时可交互选择
+
+**验证:**
+- [ ] 多个 session 时弹出选择器
+- [ ] 选择后正确 attach
+
+### Phase 4D: install wizard
+
+**修改文件:**
+
+| 文件 | 改动 |
+|------|------|
+| `src/commands/assistant/assistant.ts` | 恢复 install wizard 辅助函数 |
+
+**行为:**
+- 没有 session 时如何引导用户
+
+**验证:**
+- [ ] 无可用 session 时引导用户创建/连接
+
+## 为什么拆分
+
+- attach 渲染层与远端消息通道大部分已在
+- 真正缺的是"如何发现目标 session"和"如何交互选择"
+- 如果把 `src/assistant/index.ts` 的整套 KAIROS 正常模式也一起拉进来，范围会失控
+
+## 风险
+
+- 这是四项里范围最大的
+- 一旦把 KAIROS 正常模式整体拉入，会从"viewer attach"膨胀成"完整 assistant mode 恢复"
+
+## 依赖
+
+- Task 002 的 session registry 模式可复用
diff --git a/docs/task/task-013-bg-engine-abstraction.md b/docs/task/task-013-bg-engine-abstraction.md
new file mode 100644
index 000000000..256a0c020
--- /dev/null
+++ b/docs/task/task-013-bg-engine-abstraction.md
@@ -0,0 +1,196 @@
+# Task 013: BgEngine 跨平台后台引擎抽象
+
+> 设计文档: [daemon-restructure-design.md](../features/daemon-restructure-design.md) § 四
+> 依赖: 无
+> 分支: `feat/integrate-5-branches`
+
+## 目标
+
+将 `src/cli/bg.ts` 中硬编码的 tmux 逻辑提取为引擎抽象层，实现 TmuxEngine + DetachedEngine，使后台会话功能在 Windows / macOS / Linux 上都能工作。
+
+## 背景
+
+当前 `bg.ts` 中 `handleBgFlag()` 和 `attachHandler()` 直接调用 tmux 命令。Windows 上 `--bg` 直接报错退出。需要一个引擎抽象层，根据平台和可用工具自动选择最佳方案。
+
+## 文件清单
+
+### 新增
+
+| 文件 | 说明 |
+|------|------|
+| `src/cli/bg/engine.ts` | BgEngine 接口 + BgStartOptions/BgStartResult 类型 |
+| `src/cli/bg/engines/tmux.ts` | TmuxEngine: 从 `bg.ts` 提取 tmux 相关逻辑 |
+| `src/cli/bg/engines/detached.ts` | DetachedEngine: spawn({ detached }) + logFile 重定向 |
+| `src/cli/bg/engines/index.ts` | selectEngine() 自动选择 + re-export |
+| `src/cli/bg/tail.ts` | 跨平台日志 tail: fs.watch + 轮询 fallback |
+
+### 修改
+
+| 文件 | 变更 |
+|------|------|
+| `src/cli/bg.ts` | `handleBgFlag()` 改为调用 `selectEngine().start()`；`attachHandler()` 改为调用 `engine.attach()` |
+
+## 实现方案
+
+### 1. BgEngine 接口 (`src/cli/bg/engine.ts`)
+
+```typescript
+export interface BgEngine {
+  readonly name: string
+  available(): Promise<boolean>
+  start(opts: BgStartOptions): Promise<BgStartResult>
+  attach(session: SessionEntry): Promise<void>
+}
+
+export interface BgStartOptions {
+  sessionName: string
+  args: string[]         // CLI args (去除 --bg)
+  env: Record<string, string | undefined>
+  logPath: string
+  cwd: string
+}
+
+export interface BgStartResult {
+  pid: number
+  sessionName: string
+  logPath: string
+  engineUsed: 'tmux' | 'detached'
+}
+```
+
+### 2. TmuxEngine (`src/cli/bg/engines/tmux.ts`)
+
+从 `bg.ts:handleBgFlag()` 和 `bg.ts:attachHandler()` 提取:
+- `available()`: `execFileNoThrow('tmux', ['-V'])` 返回 code === 0
+- `start()`: `tmux new-session -d -s <name> <cmd>`
+- `attach()`: `tmux attach-session -t <session.tmuxSessionName>`
+
+### 3. DetachedEngine (`src/cli/bg/engines/detached.ts`)
+
+```typescript
+export class DetachedEngine implements BgEngine {
+  readonly name = 'detached'
+
+  async available(): Promise<boolean> {
+    return true  // 总是可用
+  }
+
+  async start(opts: BgStartOptions): Promise<BgStartResult> {
+    const logFd = openSync(opts.logPath, 'a')
+    const child = spawn(process.execPath, [process.argv[1]!, ...opts.args], {
+      detached: true,
+      stdio: ['ignore', logFd, logFd],
+      env: opts.env,
+      cwd: opts.cwd,
+    })
+    child.unref()
+    closeSync(logFd)
+
+    return {
+      pid: child.pid!,
+      sessionName: opts.sessionName,
+      logPath: opts.logPath,
+      engineUsed: 'detached',
+    }
+  }
+
+  async attach(session: SessionEntry): Promise<void> {
+    // 委托给 tail.ts
+    await tailLog(session.logPath!)
+  }
+}
+```
+
+### 4. 日志 Tail (`src/cli/bg/tail.ts`)
+
+```typescript
+/**
+ * 跨平台实时日志输出。Ctrl+C 退出，不杀后台进程。
+ *
+ * 策略:
+ * 1. 读取已有内容输出
+ * 2. fs.watch() 监听文件变化 (主方案)
+ * 3. 如果 fs.watch 不可靠 (某些 Windows 网络驱动器)，fallback 到 500ms 轮询
+ */
+export async function tailLog(logPath: string): Promise<void>
+```
+
+### 5. 引擎选择 (`src/cli/bg/engines/index.ts`)
+
+```typescript
+export async function selectEngine(): Promise<BgEngine> {
+  if (process.platform === 'win32') {
+    return new DetachedEngine()
+  }
+  const tmux = new TmuxEngine()
+  if (await tmux.available()) {
+    return tmux
+  }
+  return new DetachedEngine()
+}
+```
+
+### 6. bg.ts 重构
+
+`handleBgFlag()` 改名为 `handleBgStart()`，内部逻辑:
+```typescript
+export async function handleBgStart(args: string[]): Promise<void> {
+  const engine = await selectEngine()
+  const sessionName = `claude-bg-${randomUUID().slice(0, 8)}`
+  const logPath = join(getClaudeConfigHomeDir(), 'sessions', 'logs', `${sessionName}.log`)
+
+  const result = await engine.start({
+    sessionName,
+    args: filteredArgs,
+    env: { ...process.env, CLAUDE_CODE_SESSION_KIND: 'bg', ... },
+    logPath,
+    cwd: process.cwd(),
+  })
+
+  console.log(`Background session started: ${result.sessionName}`)
+  console.log(`  Engine: ${result.engineUsed}`)
+  console.log(`  Log: ${result.logPath}`)
+  console.log(`  Use \`claude daemon attach ${result.sessionName}\` to reconnect.`)
+}
+```
+
+`attachHandler()` 根据 `session.engine` 字段选择引擎:
+```typescript
+export async function attachHandler(target: string | undefined): Promise<void> {
+  // ... 找到 session
+  if (session.engine === 'tmux' && session.tmuxSessionName) {
+    const tmux = new TmuxEngine()
+    await tmux.attach(session)
+  } else {
+    const detached = new DetachedEngine()
+    await detached.attach(session)
+  }
+}
+```
+
+## SessionEntry 扩展
+
+`sessions/<PID>.json` 新增 `engine` 字段:
+
+```json
+{
+  "pid": 12345,
+  "engine": "detached",
+  "logPath": "~/.claude/sessions/logs/claude-bg-a1b2c3d4.log",
+  "sessionId": "...",
+  "cwd": "..."
+}
+```
+
+兼容旧格式: 如果 `engine` 字段缺失，检查 `tmuxSessionName` 存在则为 `tmux`，否则为 `detached`。
+
+## 验证清单
+
+- [ ] Windows: `claude daemon bg` 启动后台会话，无 tmux 依赖
+- [ ] Windows: `claude daemon attach <name>` 以 tail 模式附着，Ctrl+C 退出不杀进程
+- [ ] macOS/Linux (有 tmux): 行为与当前一致
+- [ ] macOS/Linux (无 tmux): 自动 fallback 到 detached 引擎
+- [ ] `claude daemon status` 正确显示 engine 类型
+- [ ] 旧格式 session JSON (无 engine 字段) 兼容
+- [ ] tsc --noEmit 零错误
+- [ ] bun test 通过
diff --git a/docs/task/task-014-daemon-command-hierarchy.md b/docs/task/task-014-daemon-command-hierarchy.md
new file mode 100644
index 000000000..76645cfba
--- /dev/null
+++ b/docs/task/task-014-daemon-command-hierarchy.md
@@ -0,0 +1,275 @@
+# Task 014: /daemon 命令层级化
+
+> 设计文档: [daemon-restructure-design.md](../features/daemon-restructure-design.md) § 三.1
+> 依赖: Task 013 (BgEngine 抽象)
+> 分支: `feat/integrate-5-branches`
+
+## 目标
+
+将散落的 `daemon start/stop/status` + `ps/logs/attach/kill` + `--bg` 统一收归 `/daemon` 命名空间，实现 CLI + REPL 双注册。
+
+## 背景
+
+当前这些命令注册在两个互不关联的位置:
+- `cli.tsx:203-212`: `daemon [start|status|stop]` → `daemon/main.ts`
+- `cli.tsx:217-246`: `ps|logs|attach|kill|--bg` → `cli/bg.ts`
+
+需要合并为统一的 `claude daemon <subcommand>` 入口，并新增 REPL `/daemon` 斜杠命令。
+
+## 文件清单
+
+### 新增
+
+| 文件 | 说明 |
+|------|------|
+| `src/commands/daemon/index.ts` | `/daemon` REPL 斜杠命令注册 (type: local-jsx) |
+| `src/commands/daemon/daemon.tsx` | `/daemon` 子命令路由 + status UI 组件 |
+
+### 修改
+
+| 文件 | 变更 |
+|------|------|
+| `src/entrypoints/cli.tsx` | 统一 daemon 快速路径: `daemon <sub>` 路由到对应 handler。旧命令 `ps/logs/attach/kill` 保留但输出 deprecation 警告后代理 |
+| `src/commands.ts` | 注册 `/daemon` 斜杠命令 (feature-gated: DAEMON \|\| BG_SESSIONS) |
+| `src/daemon/main.ts` | `daemonMain()` 扩展: 支持 `bg/attach/logs/kill/ps` 子命令 (委托给 bg.ts handlers) |
+
+## 实现方案
+
+### 1. CLI 快速路径统一 (`cli.tsx`)
+
+**改前** (两段独立路由):
+```typescript
+// 段 1: daemon
+if (feature('DAEMON') && args[0] === 'daemon') {
+  await daemonMain(args.slice(1))
+}
+// 段 2: bg sessions
+if (feature('BG_SESSIONS') && ['ps','logs','attach','kill'].includes(args[0])) {
+  // ...switch/case
+}
+```
+
+**改后** (统一入口):
+```typescript
+// 统一 daemon 入口 — 合并 daemon supervisor + bg sessions
+if (
+  (feature('DAEMON') || feature('BG_SESSIONS')) &&
+  args[0] === 'daemon'
+) {
+  profileCheckpoint('cli_daemon_path')
+  const { enableConfigs } = await import('../utils/config.js')
+  enableConfigs()
+  const { initSinks } = await import('../utils/sinks.js')
+  initSinks()
+  const { daemonMain } = await import('../daemon/main.js')
+  await daemonMain(args.slice(1))
+  return
+}
+
+// --bg 快捷方式 → daemon bg
+if (
+  feature('BG_SESSIONS') &&
+  (args.includes('--bg') || args.includes('--background'))
+) {
+  profileCheckpoint('cli_daemon_path')
+  const { enableConfigs } = await import('../utils/config.js')
+  enableConfigs()
+  const bg = await import('../cli/bg.js')
+  await bg.handleBgStart(args.filter(a => a !== '--bg' && a !== '--background'))
+  return
+}
+
+// 向后兼容: ps/logs/attach/kill → daemon <sub> (deprecated)
+if (
+  feature('BG_SESSIONS') &&
+  ['ps', 'logs', 'attach', 'kill'].includes(args[0] ?? '')
+) {
+  const mapped = args[0] === 'ps' ? 'status' : args[0]
+  console.error(`[deprecated] Use: claude daemon ${mapped} ${args.slice(1).join(' ')}`.trim())
+  const { enableConfigs } = await import('../utils/config.js')
+  enableConfigs()
+  const { daemonMain } = await import('../daemon/main.js')
+  await daemonMain([args[0]!, ...args.slice(1)])
+  return
+}
+```
+
+### 2. daemonMain 扩展 (`daemon/main.ts`)
+
+```typescript
+export async function daemonMain(args: string[]): Promise<void> {
+  const subcommand = args[0] || 'status'
+
+  switch (subcommand) {
+    // --- Supervisor 管理 ---
+    case 'start':
+      await runSupervisor(args.slice(1))
+      break
+    case 'stop':
+      await handleDaemonStop()
+      break
+
+    // --- 会话管理 (委托给 bg.ts) ---
+    case 'status':
+    case 'ps':
+      await showUnifiedStatus()  // 新: daemon 状态 + 会话列表
+      break
+    case 'bg':
+      const bg = await import('../cli/bg.js')
+      await bg.handleBgStart(args.slice(1))
+      break
+    case 'attach':
+      const bg2 = await import('../cli/bg.js')
+      await bg2.attachHandler(args[1])
+      break
+    case 'logs':
+      const bg3 = await import('../cli/bg.js')
+      await bg3.logsHandler(args[1])
+      break
+    case 'kill':
+      const bg4 = await import('../cli/bg.js')
+      await bg4.killHandler(args[1])
+      break
+
+    case '--help': case '-h': case 'help':
+      printHelp()
+      break
+    default:
+      console.error(`Unknown daemon subcommand: ${subcommand}`)
+      printHelp()
+      process.exitCode = 1
+  }
+}
+```
+
+### 3. 统一状态面板 (`showUnifiedStatus`)
+
+```typescript
+async function showUnifiedStatus(): Promise<void> {
+  // 1. Daemon supervisor 状态
+  const daemonResult = queryDaemonStatus()
+  console.log('=== Daemon Supervisor ===')
+  switch (daemonResult.status) {
+    case 'running':
+      console.log(`  Status: running (PID: ${daemonResult.state!.pid})`)
+      console.log(`  Workers: ${daemonResult.state!.workerKinds.join(', ')}`)
+      break
+    case 'stopped':
+      console.log('  Status: stopped')
+      break
+    case 'stale':
+      console.log('  Status: stale (cleaned up)')
+      break
+  }
+
+  // 2. 后台会话列表
+  console.log('\n=== Background Sessions ===')
+  const bg = await import('../cli/bg.js')
+  await bg.psHandler([])
+}
+```
+
+### 4. REPL 斜杠命令注册
+
+**`src/commands/daemon/index.ts`**:
+```typescript
+import type { Command } from '../../commands.js'
+import { feature } from 'bun:bundle'
+
+const daemon = {
+  type: 'local-jsx',
+  name: 'daemon',
+  description: 'Manage background sessions and daemon',
+  argumentHint: '[status|start|stop|bg|attach|logs|kill]',
+  isEnabled: () => {
+    if (feature('DAEMON')) return true
+    if (feature('BG_SESSIONS')) return true
+    return false
+  },
+  load: () => import('./daemon.js'),
+} satisfies Command
+
+export default daemon
+```
+
+**`src/commands/daemon/daemon.tsx`**:
+```typescript
+export async function call(
+  onDone: LocalJSXCommandOnDone,
+  context: LocalJSXCommandContext,
+  args: string,
+): Promise<React.ReactNode> {
+  const parts = args.trim().split(/\s+/)
+  const sub = parts[0] || 'status'
+
+  switch (sub) {
+    case 'status':
+    case 'ps':
+      // 调用 showUnifiedStatus，捕获输出
+      // 返回文本结果
+      break
+    case 'bg':
+      // REPL 中启动后台会话
+      break
+    case 'start':
+    case 'stop':
+    case 'attach':
+    case 'logs':
+    case 'kill':
+      // 委托给对应 handler
+      break
+    default:
+      onDone(`Unknown: ${sub}. Use: status|start|stop|bg|attach|logs|kill`)
+      return null
+  }
+}
+```
+
+**`src/commands.ts`** 添加:
+```typescript
+// 条件导入
+const daemonCmd =
+  feature('DAEMON') || feature('BG_SESSIONS')
+    ? require('./commands/daemon/index.js').default
+    : null
+
+// COMMANDS 数组中添加
+...(daemonCmd ? [daemonCmd] : []),
+```
+
+### 5. 更新 help 文本 (`daemon/main.ts`)
+
+```
+Claude Code Daemon — background process management
+
+USAGE
+  claude daemon [subcommand]
+
+SUBCOMMANDS
+  status      Show daemon and session status (default)
+  start       Start the daemon supervisor
+  stop        Stop the daemon
+  bg          Start a background session
+  attach      Attach to a background session
+  logs        Show session logs
+  kill        Kill a session
+  help        Show this help
+
+REPL
+  /daemon [subcommand]    Same commands available in interactive mode
+```
+
+## 验证清单
+
+- [ ] `claude daemon` (无参数) 显示统一状态面板
+- [ ] `claude daemon status` 显示 supervisor + 会话列表
+- [ ] `claude daemon start/stop` 与当前行为一致
+- [ ] `claude daemon bg` 启动后台会话 (调用 BgEngine)
+- [ ] `claude daemon attach/logs/kill <target>` 功能正常
+- [ ] `claude ps` 输出 deprecation 警告 + 正常工作
+- [ ] `claude logs/attach/kill` 同上
+- [ ] `claude --bg` 快捷方式正常
+- [ ] REPL 中 `/daemon` 可用，tab 补全显示
+- [ ] REPL 中 `/daemon status` 显示状态信息
+- [ ] tsc --noEmit 零错误
+- [ ] bun test 通过
diff --git a/docs/task/task-015-job-command-hierarchy.md b/docs/task/task-015-job-command-hierarchy.md
new file mode 100644
index 000000000..514114f6d
--- /dev/null
+++ b/docs/task/task-015-job-command-hierarchy.md
@@ -0,0 +1,177 @@
+# Task 015: /job 命令层级化
+
+> 设计文档: [daemon-restructure-design.md](../features/daemon-restructure-design.md) § 三.2
+> 依赖: 无 (可与 Task 013 并行)
+> 分支: `feat/integrate-5-branches`
+
+## 目标
+
+将 `claude new/list/reply` 收归 `/job` 命名空间，实现 CLI + REPL 双注册。
+
+## 背景
+
+当前 `new`, `list`, `reply` 是顶级 CLI 命令 (`cli.tsx:250-261`)，容易与其他命令冲突（特别是 `list` 这种通用词）。需要收归 `claude job <subcommand>` 并新增 REPL `/job` 入口。
+
+## 文件清单
+
+### 新增
+
+| 文件 | 说明 |
+|------|------|
+| `src/commands/job/index.ts` | `/job` REPL 斜杠命令注册 |
+| `src/commands/job/job.tsx` | `/job` 子命令路由 |
+
+### 修改
+
+| 文件 | 变更 |
+|------|------|
+| `src/entrypoints/cli.tsx` | 新增 `job` 快速路径 + 旧 `new/list/reply` deprecation 代理 |
+| `src/commands.ts` | 注册 `/job` 斜杠命令 |
+
+### 不动
+
+| 文件 | 说明 |
+|------|------|
+| `src/cli/handlers/templateJobs.ts` | 内部 handler 不变，只是被调用方式变了 |
+| `src/jobs/state.ts` | job 状态管理不变 |
+| `src/jobs/templates.ts` | 模板发现不变 |
+| `src/jobs/classifier.ts` | 任务分类器不变 |
+
+## 实现方案
+
+### 1. CLI 快速路径 (`cli.tsx`)
+
+**改后**:
+```typescript
+// 新: claude job <subcommand>
+if (
+  feature('TEMPLATES') &&
+  args[0] === 'job'
+) {
+  profileCheckpoint('cli_templates_path')
+  const { templatesMain } = await import('../cli/handlers/templateJobs.js')
+  await templatesMain(args.slice(1))
+  process.exit(0)
+}
+
+// 向后兼容 (deprecated)
+if (
+  feature('TEMPLATES') &&
+  (args[0] === 'new' || args[0] === 'list' || args[0] === 'reply')
+) {
+  console.error(`[deprecated] Use: claude job ${args[0]} ${args.slice(1).join(' ')}`.trim())
+  profileCheckpoint('cli_templates_path')
+  const { templatesMain } = await import('../cli/handlers/templateJobs.js')
+  await templatesMain(args)
+  process.exit(0)
+}
+```
+
+### 2. templateJobs.ts 新增 status 子命令
+
+在现有 `switch` 中增加:
+```typescript
+case 'status':
+  handleStatus(args.slice(1))
+  break
+```
+
+```typescript
+function handleStatus(args: string[]): void {
+  const jobId = args[0]
+  if (!jobId) {
+    console.error('Usage: claude job status <job-id>')
+    process.exitCode = 1
+    return
+  }
+  const state = readJobState(jobId)
+  if (!state) {
+    console.error(`Job not found: ${jobId}`)
+    process.exitCode = 1
+    return
+  }
+  console.log(`Job: ${state.jobId}`)
+  console.log(`  Template: ${state.templateName}`)
+  console.log(`  Status: ${state.status}`)
+  console.log(`  Created: ${state.createdAt}`)
+  console.log(`  Updated: ${state.updatedAt}`)
+}
+```
+
+### 3. REPL 斜杠命令
+
+**`src/commands/job/index.ts`**:
+```typescript
+import type { Command } from '../../commands.js'
+import { feature } from 'bun:bundle'
+
+const job = {
+  type: 'local-jsx',
+  name: 'job',
+  description: 'Manage template jobs',
+  argumentHint: '[list|new|reply|status]',
+  isEnabled: () => {
+    if (feature('TEMPLATES')) return true
+    return false
+  },
+  load: () => import('./job.js'),
+} satisfies Command
+
+export default job
+```
+
+**`src/commands/job/job.tsx`**:
+```typescript
+export async function call(
+  onDone: LocalJSXCommandOnDone,
+  _context: LocalJSXCommandContext,
+  args: string,
+): Promise<React.ReactNode> {
+  const parts = args.trim().split(/\s+/)
+  const sub = parts[0] || 'list'
+
+  // 委托给 templatesMain
+  const { templatesMain } = await import('../../cli/handlers/templateJobs.js')
+
+  // 捕获 console.log 输出作为结果返回给 REPL
+  const lines: string[] = []
+  const origLog = console.log
+  const origError = console.error
+  console.log = (...a: unknown[]) => lines.push(a.join(' '))
+  console.error = (...a: unknown[]) => lines.push(a.join(' '))
+
+  try {
+    await templatesMain([sub, ...parts.slice(1)])
+  } finally {
+    console.log = origLog
+    console.error = origError
+  }
+
+  onDone(lines.join('\n') || 'Done.', { display: 'system' })
+  return null
+}
+```
+
+### 4. commands.ts 注册
+
+```typescript
+const jobCmd = feature('TEMPLATES')
+  ? require('./commands/job/index.js').default
+  : null
+
+// COMMANDS 数组:
+...(jobCmd ? [jobCmd] : []),
+```
+
+## 验证清单
+
+- [ ] `claude job list` 列出模板
+- [ ] `claude job new <template>` 创建任务
+- [ ] `claude job reply <id> <text>` 回复任务
+- [ ] `claude job status <id>` 显示任务状态
+- [ ] `claude job` (无参数) 等同于 `claude job list`
+- [ ] `claude new/list/reply` 输出 deprecation 警告 + 正常工作
+- [ ] REPL 中 `/job` 可用
+- [ ] REPL 中 `/job list` 显示模板列表
+- [ ] tsc --noEmit 零错误
+- [ ] bun test 通过
diff --git a/docs/task/task-016-backward-compat-tests.md b/docs/task/task-016-backward-compat-tests.md
new file mode 100644
index 000000000..56102807e
--- /dev/null
+++ b/docs/task/task-016-backward-compat-tests.md
@@ -0,0 +1,123 @@
+# Task 016: 向后兼容 + 测试
+
+> 设计文档: [daemon-restructure-design.md](../features/daemon-restructure-design.md) § 五
+> 依赖: Task 014, Task 015
+> 分支: `feat/integrate-5-branches`
+
+## 目标
+
+确保旧命令向后兼容 (deprecation 警告 + 正常代理)，并为重构后的命令结构编写测试。
+
+## 文件清单
+
+### 新增
+
+| 文件 | 说明 |
+|------|------|
+| `src/daemon/__tests__/daemonMain.test.ts` | daemonMain 子命令路由测试 |
+| `src/cli/bg/__tests__/engine.test.ts` | BgEngine 选择逻辑测试 |
+| `src/cli/bg/__tests__/detached.test.ts` | DetachedEngine 启动/停止测试 |
+| `src/cli/bg/__tests__/tail.test.ts` | 日志 tail 功能测试 |
+
+### 修改
+
+| 文件 | 变更 |
+|------|------|
+| `src/entrypoints/cli.tsx` | 确认 deprecation 路径正确代理 |
+
+## 实现方案
+
+### 1. 向后兼容矩阵
+
+| 旧命令 | 新命令 | 处理方式 |
+|--------|--------|---------|
+| `claude ps` | `claude daemon status` | stderr 输出 `[deprecated] Use: claude daemon status`，然后执行 |
+| `claude logs <x>` | `claude daemon logs <x>` | 同上 |
+| `claude attach <x>` | `claude daemon attach <x>` | 同上 |
+| `claude kill <x>` | `claude daemon kill <x>` | 同上 |
+| `claude --bg` | `claude daemon bg` | 保留为快捷方式，**不** deprecate (太常用) |
+| `claude new <t>` | `claude job new <t>` | stderr deprecation + 执行 |
+| `claude list` | `claude job list` | stderr deprecation + 执行 |
+| `claude reply <id>` | `claude job reply <id>` | stderr deprecation + 执行 |
+
+**关键**: deprecation 输出到 stderr 而非 stdout，不影响脚本管道。
+
+### 2. 测试计划
+
+#### 2.1 daemonMain 路由测试
+
+```typescript
+describe('daemonMain', () => {
+  test('无参数默认 status', async () => { ... })
+  test('start 调用 runSupervisor', async () => { ... })
+  test('stop 调用 handleDaemonStop', async () => { ... })
+  test('bg 委托给 bg.handleBgStart', async () => { ... })
+  test('attach 委托给 bg.attachHandler', async () => { ... })
+  test('logs 委托给 bg.logsHandler', async () => { ... })
+  test('kill 委托给 bg.killHandler', async () => { ... })
+  test('未知子命令设置 exitCode=1', async () => { ... })
+})
+```
+
+#### 2.2 引擎选择测试
+
+```typescript
+describe('selectEngine', () => {
+  test('win32 返回 DetachedEngine', async () => { ... })
+  test('darwin + tmux 可用返回 TmuxEngine', async () => { ... })
+  test('darwin + tmux 不可用返回 DetachedEngine', async () => { ... })
+  test('linux + tmux 可用返回 TmuxEngine', async () => { ... })
+})
+```
+
+#### 2.3 DetachedEngine 测试
+
+```typescript
+describe('DetachedEngine', () => {
+  test('available 始终返回 true', async () => { ... })
+  test('start 创建 detached 子进程并写入日志', async () => { ... })
+  test('start 返回的 PID 文件存在', async () => { ... })
+})
+```
+
+#### 2.4 Tail 测试
+
+```typescript
+describe('tailLog', () => {
+  test('输出已有日志内容', async () => { ... })
+  test('追加内容时实时输出', async () => { ... })
+  test('SIGINT 退出 tail', async () => { ... })
+})
+```
+
+### 3. 集成验证脚本
+
+可选: 在 `scripts/` 下添加一个手动验证脚本:
+
+```bash
+#!/bin/bash
+# scripts/verify-daemon-restructure.sh
+echo "=== 1. claude daemon status ==="
+bun run dev -- daemon status
+
+echo "=== 2. claude daemon bg (should start) ==="
+bun run dev -- daemon bg --help
+
+echo "=== 3. claude ps (deprecated) ==="
+bun run dev -- ps 2>&1 | head -1
+
+echo "=== 4. claude job list ==="
+bun run dev -- job list
+
+echo "=== 5. claude list (deprecated) ==="
+bun run dev -- list 2>&1 | head -1
+```
+
+## 验证清单
+
+- [ ] 旧命令全部正常工作 (仅多一行 stderr 警告)
+- [ ] `--bg` 保持无警告
+- [ ] 所有新增测试通过
+- [ ] 现有 2695 个测试无回归
+- [ ] tsc --noEmit 零错误
+- [ ] 手动在 Windows + macOS/Linux 上验证关键路径
diff --git a/docs/test-plans/openclaw-autonomy-baseline.md b/docs/test-plans/openclaw-autonomy-baseline.md
new file mode 100644
index 000000000..e4177716a
--- /dev/null
+++ b/docs/test-plans/openclaw-autonomy-baseline.md
@@ -0,0 +1,88 @@
+# OpenClaw Autonomy Baseline Test Spec
+
+## Purpose
+
+This test spec locks the current behavior of the existing trigger and context layers before any formal autonomy-subsystem implementation begins.
+
+At this stage, production code is read-only. Only test files, fixtures, and planning documents may change.
+
+## Goal
+
+Establish a stable baseline around the parts of `Claude-code-bast` that later autonomy work is most likely to touch:
+
+- proactive state handling
+- cron task storage semantics
+- cron scheduler helper semantics
+- user-context cache and `CLAUDE.md` injection behavior
+
+## Out of Scope for This Baseline Round
+
+- New authority behavior (`AGENTS.md` / `HEARTBEAT.md`)
+- New detached-run ledger behavior
+- New flow behavior
+- UI redesign
+
+## Files Under Baseline Protection
+
+- `src/proactive/index.ts`
+- `src/utils/cronTasks.ts`
+- `src/utils/cronScheduler.ts`
+- `src/context.ts`
+
+## Test Files Added In This Round
+
+- `src/proactive/__tests__/state.baseline.test.ts`
+- `src/commands/__tests__/proactive.baseline.test.ts`
+- `src/utils/__tests__/cronTasks.baseline.test.ts`
+- `src/utils/__tests__/cronScheduler.baseline.test.ts`
+- `src/__tests__/context.baseline.test.ts`
+
+## Baseline Assertions
+
+### Proactive state
+
+1. Activating proactive mode sets active state and activation source.
+2. Pausing proactive mode suppresses `shouldTick()` and clears `nextTickAt`.
+3. Blocking context suppresses `shouldTick()` and clears `nextTickAt`.
+4. Subscribers are notified on state transitions.
+5. The `/proactive` command enables proactive mode and emits the expected hidden reminder.
+6. The `/proactive` command disables proactive mode on the second invocation.
+
+### Cron task storage
+
+1. Session-only cron tasks remain in memory only.
+2. Durable cron tasks are persisted to `.claude/scheduled_tasks.json`.
+3. Daemon-style `dir`-scoped reads exclude session-only cron tasks.
+4. `removeCronTasks()` without `dir` can remove session-only tasks.
+5. `removeCronTasks()` with `dir` does not mutate session-only task storage.
+
+### Cron scheduler helpers
+
+1. `isRecurringTaskAged()` preserves current aging semantics.
+2. `buildMissedTaskNotification()` preserves the current AskUserQuestion safety wording.
+3. `buildMissedTaskNotification()` preserves code-fence hardening for prompt bodies that contain backticks.
+
+### User context caching
+
+1. `getUserContext()` includes `currentDate`.
+2. `getUserContext()` includes mocked `claudeMd` content when memory loading is enabled.
+3. `CLAUDE_CODE_DISABLE_CLAUDE_MDS` suppresses `claudeMd`.
+4. `setSystemPromptInjection()` clears the memoized user-context cache.
+5. `getSystemContext()` reflects the injection after cache invalidation.
+
+## Remaining Baseline Gaps
+
+The following areas are intentionally deferred because they require higher-cost harnessing and should still avoid production-code changes:
+
+1. `useScheduledTasks.ts` hook-level runtime behavior
+2. `src/cli/print.ts` full headless scheduler loop behavior
+3. `useProactive.ts` hook timer behavior
+4. end-to-end queue interaction between proactive ticks and `SleepTool`
+
+## Acceptance
+
+This baseline round is complete when:
+
+1. The four new test files pass.
+2. No production source files are modified.
+3. The tests are stable enough to serve as a pre-implementation guardrail.
diff --git a/package.json b/package.json
index fb5d641cd..47dff2367 100644
--- a/package.json
+++ b/package.json
@@ -59,8 +59,9 @@
     "rcs": "bun run scripts/rcs.ts"
   },
   "dependencies": {
-    "ws": "^8.20.0",
-    "@claude-code-best/mcp-chrome-bridge": "^2.0.7"
+    "@agentclientprotocol/sdk": "^0.19.0",
+    "@claude-code-best/mcp-chrome-bridge": "^2.0.7",
+    "ws": "^8.20.0"
   },
   "devDependencies": {
     "@alcalzone/ansi-tokenize": "^0.3.0",
diff --git a/packages/@ant/claude-for-chrome-mcp/tsconfig.json b/packages/@ant/claude-for-chrome-mcp/tsconfig.json
index 67fc2cf86..5621e5882 100644
--- a/packages/@ant/claude-for-chrome-mcp/tsconfig.json
+++ b/packages/@ant/claude-for-chrome-mcp/tsconfig.json
@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.json",
   "include": ["src/**/*.ts"],
   "exclude": ["node_modules", "dist"]
 }
diff --git a/packages/@ant/computer-use-input/tsconfig.json b/packages/@ant/computer-use-input/tsconfig.json
index 67fc2cf86..5621e5882 100644
--- a/packages/@ant/computer-use-input/tsconfig.json
+++ b/packages/@ant/computer-use-input/tsconfig.json
@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.json",
   "include": ["src/**/*.ts"],
   "exclude": ["node_modules", "dist"]
 }
diff --git a/packages/@ant/computer-use-mcp/src/toolCalls.ts b/packages/@ant/computer-use-mcp/src/toolCalls.ts
index d7b796a94..415ee6ecc 100644
--- a/packages/@ant/computer-use-mcp/src/toolCalls.ts
+++ b/packages/@ant/computer-use-mcp/src/toolCalls.ts
@@ -37,16 +37,21 @@
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { randomUUID } from "node:crypto";
 
-/** Detect actual image MIME type from base64 data using magic bytes. */
+/** Detect actual image MIME type from base64 data by decoding the magic bytes. */
 function detectMimeFromBase64(b64: string): string {
-  // First byte is enough to distinguish PNG (0x89) from JPEG (0xFF)
-  const c = b64.charCodeAt(0);
-  if (c === 0x89) return "image/png";
-  if (c === 0xFF) return "image/jpeg";
-  // RIFF = WebP
-  if (c === 0x52) return "image/webp";
-  // GIF
-  if (c === 0x47) return "image/gif";
+  // Decode first 12 raw bytes (16 base64 chars is enough) and check standard magic bytes.
+  // PNG:  89 50 4E 47
+  // JPEG: FF D8 FF
+  // RIFF+WEBP: "RIFF" at 0..3 + "WEBP" at 8..11
+  // GIF:  "GIF" at 0..2
+  const raw = Buffer.from(b64.slice(0, 16), "base64");
+  if (raw[0] === 0x89 && raw[1] === 0x50 && raw[2] === 0x4e && raw[3] === 0x47) return "image/png";
+  if (raw[0] === 0xff && raw[1] === 0xd8 && raw[2] === 0xff) return "image/jpeg";
+  if (
+    raw[0] === 0x52 && raw[1] === 0x49 && raw[2] === 0x46 && raw[3] === 0x46 && // RIFF
+    raw[8] === 0x57 && raw[9] === 0x45 && raw[10] === 0x42 && raw[11] === 0x50  // WEBP
+  ) return "image/webp";
+  if (raw[0] === 0x47 && raw[1] === 0x49 && raw[2] === 0x46) return "image/gif";
   return "image/png";
 }
 
diff --git a/packages/@ant/computer-use-mcp/tsconfig.json b/packages/@ant/computer-use-mcp/tsconfig.json
index 67fc2cf86..5621e5882 100644
--- a/packages/@ant/computer-use-mcp/tsconfig.json
+++ b/packages/@ant/computer-use-mcp/tsconfig.json
@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.json",
   "include": ["src/**/*.ts"],
   "exclude": ["node_modules", "dist"]
 }
diff --git a/packages/@ant/ink/tsconfig.json b/packages/@ant/ink/tsconfig.json
index f95464d03..4049f051b 100644
--- a/packages/@ant/ink/tsconfig.json
+++ b/packages/@ant/ink/tsconfig.json
@@ -1,5 +1,5 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.json",
   "include": ["src/**/*.ts", "src/**/*.tsx"],
   "exclude": ["node_modules", "dist"]
 }
diff --git a/packages/agent-tools/tsconfig.json b/packages/agent-tools/tsconfig.json
index af2850cc4..1ec82ebae 100644
--- a/packages/agent-tools/tsconfig.json
+++ b/packages/agent-tools/tsconfig.json
@@ -1,5 +1,5 @@
 {
-  "extends": "../../tsconfig.base.json",
+  "extends": "../../tsconfig.json",
   "include": ["src/**/*.ts"],
   "exclude": ["node_modules", "dist"]
 }
diff --git a/packages/audio-capture-napi/tsconfig.json b/packages/audio-capture-napi/tsconfig.json
index af2850cc4..1ec82ebae 100644
--- a/packages/audio-capture-napi/tsconfig.json
+++ b/packages/audio-capture-napi/tsconfig.json
@@ -1,5 +1,5 @@
 {
-  "extends": "../../tsconfig.base.json",
+  "extends": "../../tsconfig.json",
   "include": ["src/**/*.ts"],
   "exclude": ["node_modules", "dist"]
 }
diff --git a/packages/builtin-tools/src/tools/PushNotificationTool/PushNotificationTool.ts b/packages/builtin-tools/src/tools/PushNotificationTool/PushNotificationTool.ts
index be2d0702c..5936c6d03 100644
--- a/packages/builtin-tools/src/tools/PushNotificationTool/PushNotificationTool.ts
+++ b/packages/builtin-tools/src/tools/PushNotificationTool/PushNotificationTool.ts
@@ -1,7 +1,9 @@
+import { feature } from 'bun:bundle'
 import { z } from 'zod/v4'
 import type { ToolResultBlockParam } from 'src/Tool.js'
 import { buildTool } from 'src/Tool.js'
 import { lazySchema } from 'src/utils/lazySchema.js'
+import { logForDebugging } from 'src/utils/debug.js'
 
 const PUSH_NOTIFICATION_TOOL_NAME = 'PushNotification'
 
@@ -74,14 +76,58 @@ Requires Remote Control to be configured. Respects user notification settings (t
     }
   },
 
-  async call(_input: PushInput) {
-    // Push delivery is handled by the Remote Control / KAIROS transport layer.
-    // Without the KAIROS runtime, this tool is not available.
-    return {
-      data: {
-        sent: false,
-        error: 'PushNotification requires the KAIROS transport layer.',
-      },
+  async call(input: PushInput, context) {
+    const appState = context.getAppState()
+
+    // Try bridge delivery first (for remote/mobile viewers)
+    if (appState.replBridgeEnabled) {
+      if (feature('BRIDGE_MODE')) {
+        try {
+          const { getBridgeAccessToken, getBridgeBaseUrl } = await import(
+            'src/bridge/bridgeConfig.js'
+          )
+          const { getSessionId } = await import('src/bootstrap/state.js')
+          const token = getBridgeAccessToken()
+          const sessionId = getSessionId()
+          if (token && sessionId) {
+            const baseUrl = getBridgeBaseUrl()
+            const axios = (await import('axios')).default
+            const response = await axios.post(
+              `${baseUrl}/v1/sessions/${sessionId}/events`,
+              {
+                events: [
+                  {
+                    type: 'push_notification',
+                    title: input.title,
+                    body: input.body,
+                    priority: input.priority ?? 'normal',
+                  },
+                ],
+              },
+              {
+                headers: {
+                  Authorization: `Bearer ${token}`,
+                  'Content-Type': 'application/json',
+                  'anthropic-version': '2023-06-01',
+                },
+                timeout: 10_000,
+                validateStatus: (s: number) => s < 500,
+              },
+            )
+            if (response.status >= 200 && response.status < 300) {
+              logForDebugging(`[PushNotification] delivered via bridge session=${sessionId}`)
+              return { data: { sent: true } }
+            }
+            logForDebugging(`[PushNotification] bridge delivery failed: status=${response.status}`)
+          }
+        } catch (e) {
+          logForDebugging(`[PushNotification] bridge delivery error: ${e}`)
+        }
+      }
     }
+
+    // Fallback: no bridge available, push was not delivered to a remote device.
+    logForDebugging(`[PushNotification] no bridge available, not delivered: ${input.title}`)
+    return { data: { sent: false, error: 'No Remote Control bridge configured. Notification not delivered.' } }
   },
 })
diff --git a/packages/builtin-tools/src/tools/SendUserFileTool/SendUserFileTool.ts b/packages/builtin-tools/src/tools/SendUserFileTool/SendUserFileTool.ts
index 9f8b98f7f..82172be8d 100644
--- a/packages/builtin-tools/src/tools/SendUserFileTool/SendUserFileTool.ts
+++ b/packages/builtin-tools/src/tools/SendUserFileTool/SendUserFileTool.ts
@@ -70,14 +70,51 @@ Guidelines:
     }
   },
 
-  async call(_input: SendUserFileInput) {
-    // File transfer is handled by the KAIROS assistant transport layer.
-    // Without the KAIROS runtime, this tool is not available.
+  async call(input: SendUserFileInput, context) {
+    const { file_path } = input
+    const { stat } = await import('fs/promises')
+
+    // Verify file exists and is readable
+    let fileSize: number
+    try {
+      const fileStat = await stat(file_path)
+      if (!fileStat.isFile()) {
+        return {
+          data: { sent: false, file_path, error: 'Path is not a file.' },
+        }
+      }
+      fileSize = fileStat.size
+    } catch {
+      return {
+        data: { sent: false, file_path, error: 'File does not exist or is not readable.' },
+      }
+    }
+
+    // Attempt bridge upload if available (so web viewers can download)
+    const appState = context.getAppState()
+    let fileUuid: string | undefined
+    if (appState.replBridgeEnabled) {
+      try {
+        const { uploadBriefAttachment } = await import(
+          '@claude-code-best/builtin-tools/tools/BriefTool/upload.js'
+        )
+        fileUuid = await uploadBriefAttachment(file_path, fileSize, {
+          replBridgeEnabled: true,
+          signal: context.abortController.signal,
+        })
+      } catch {
+        // Best-effort upload — local path is always available
+      }
+    }
+
+    const delivered = !appState.replBridgeEnabled || Boolean(fileUuid)
     return {
       data: {
-        sent: false,
-        file_path: _input.file_path,
-        error: 'SendUserFile requires the KAIROS assistant transport layer.',
+        sent: delivered,
+        file_path,
+        size: fileSize,
+        ...(fileUuid ? { file_uuid: fileUuid } : {}),
+        ...(!delivered ? { error: 'Bridge upload failed. File available at local path.' } : {}),
       },
     }
   },
diff --git a/packages/color-diff-napi/tsconfig.json b/packages/color-diff-napi/tsconfig.json
index af2850cc4..1ec82ebae 100644
--- a/packages/color-diff-napi/tsconfig.json
+++ b/packages/color-diff-napi/tsconfig.json
@@ -1,5 +1,5 @@
 {
-  "extends": "../../tsconfig.base.json",
+  "extends": "../../tsconfig.json",
   "include": ["src/**/*.ts"],
   "exclude": ["node_modules", "dist"]
 }
diff --git a/packages/image-processor-napi/tsconfig.json b/packages/image-processor-napi/tsconfig.json
index af2850cc4..1ec82ebae 100644
--- a/packages/image-processor-napi/tsconfig.json
+++ b/packages/image-processor-napi/tsconfig.json
@@ -1,5 +1,5 @@
 {
-  "extends": "../../tsconfig.base.json",
+  "extends": "../../tsconfig.json",
   "include": ["src/**/*.ts"],
   "exclude": ["node_modules", "dist"]
 }
diff --git a/packages/mcp-client/tsconfig.json b/packages/mcp-client/tsconfig.json
index af2850cc4..1ec82ebae 100644
--- a/packages/mcp-client/tsconfig.json
+++ b/packages/mcp-client/tsconfig.json
@@ -1,5 +1,5 @@
 {
-  "extends": "../../tsconfig.base.json",
+  "extends": "../../tsconfig.json",
   "include": ["src/**/*.ts"],
   "exclude": ["node_modules", "dist"]
 }
diff --git a/packages/modifiers-napi/tsconfig.json b/packages/modifiers-napi/tsconfig.json
index af2850cc4..1ec82ebae 100644
--- a/packages/modifiers-napi/tsconfig.json
+++ b/packages/modifiers-napi/tsconfig.json
@@ -1,5 +1,5 @@
 {
-  "extends": "../../tsconfig.base.json",
+  "extends": "../../tsconfig.json",
   "include": ["src/**/*.ts"],
   "exclude": ["node_modules", "dist"]
 }
diff --git a/packages/remote-control-server/src/logger.ts b/packages/remote-control-server/src/logger.ts
new file mode 100644
index 000000000..4b19fc155
--- /dev/null
+++ b/packages/remote-control-server/src/logger.ts
@@ -0,0 +1,10 @@
+/** Thin logging wrapper — silent in test environment, uses console in production. */
+const isTest = process.env.NODE_ENV === "test" || (typeof Bun !== "undefined" && !!Bun.env.BUN_TEST);
+
+export function log(...args: unknown[]): void {
+  if (!isTest) console.log(...args);
+}
+
+export function error(...args: unknown[]): void {
+  if (!isTest) console.error(...args);
+}
diff --git a/packages/remote-control-server/src/routes/v1/session-ingress.ts b/packages/remote-control-server/src/routes/v1/session-ingress.ts
index 93cb62605..dd5f51b70 100644
--- a/packages/remote-control-server/src/routes/v1/session-ingress.ts
+++ b/packages/remote-control-server/src/routes/v1/session-ingress.ts
@@ -1,3 +1,4 @@
+import { log, error as logError } from "../../logger";
 import { Hono } from "hono";
 import { createBunWebSocket } from "hono/bun";
 import { validateApiKey } from "../../auth/api-key";
@@ -30,14 +31,14 @@ function authenticateRequest(c: any, label: string, expectedSessionId?: string):
     const payload = verifyWorkerJwt(token);
     if (payload) {
       if (expectedSessionId && payload.session_id !== expectedSessionId) {
-        console.log(`[Auth] ${label}: FAILED — JWT session_id mismatch`);
+        log(`[Auth] ${label}: FAILED — JWT session_id mismatch`);
         return false;
       }
       return true;
     }
   }
 
-  console.log(`[Auth] ${label}: FAILED — no valid API key or JWT`);
+  log(`[Auth] ${label}: FAILED — no valid API key or JWT`);
   return false;
 }
 
@@ -85,7 +86,7 @@ app.get(
 
     const session = getSession(sessionId);
     if (!session) {
-      console.log(`[WS] Upgrade rejected: session ${sessionId} not found`);
+      log(`[WS] Upgrade rejected: session ${sessionId} not found`);
       return {
         onOpen(_evt, ws) {
           ws.close(4001, "session not found");
@@ -93,7 +94,7 @@ app.get(
       };
     }
 
-    console.log(`[WS] Upgrade accepted: session=${sessionId}`);
+    log(`[WS] Upgrade accepted: session=${sessionId}`);
     return {
       onOpen(_evt, ws) {
         handleWebSocketOpen(ws as any, sessionId);
@@ -110,7 +111,7 @@ app.get(
         handleWebSocketClose(ws as any, sessionId, closeEvt?.code, closeEvt?.reason);
       },
       onError(evt, ws) {
-        console.error(`[WS] Error on session=${sessionId}:`, evt);
+        logError(`[WS] Error on session=${sessionId}:`, evt);
         handleWebSocketClose(ws as any, sessionId, 1006, "websocket error");
       },
     };
diff --git a/packages/remote-control-server/src/routes/v1/sessions.ts b/packages/remote-control-server/src/routes/v1/sessions.ts
index d5b669123..7ca8b0c07 100644
--- a/packages/remote-control-server/src/routes/v1/sessions.ts
+++ b/packages/remote-control-server/src/routes/v1/sessions.ts
@@ -1,3 +1,4 @@
+import { log, error as logError } from "../../logger";
 import { Hono } from "hono";
 import {
   createSession,
@@ -23,7 +24,7 @@ app.post("/", acceptCliHeaders, apiKeyAuth, async (c) => {
     try {
       await createWorkItem(body.environment_id, session.id);
     } catch (err) {
-      console.error(`[RCS] Failed to create work item: ${(err as Error).message}`);
+      logError(`[RCS] Failed to create work item: ${(err as Error).message}`);
     }
   }
 
diff --git a/packages/remote-control-server/src/routes/web/control.ts b/packages/remote-control-server/src/routes/web/control.ts
index 55c7ec5a0..aaf725d40 100644
--- a/packages/remote-control-server/src/routes/web/control.ts
+++ b/packages/remote-control-server/src/routes/web/control.ts
@@ -1,3 +1,4 @@
+import { log, error as logError } from "../../logger";
 import { Hono } from "hono";
 import { uuidAuth } from "../../auth/middleware";
 import { getSession, isSessionClosedStatus, resolveOwnedWebSessionId, updateSessionStatus } from "../../services/session";
@@ -44,9 +45,9 @@ app.post("/sessions/:id/events", uuidAuth, async (c) => {
 
   const body = await c.req.json();
   const eventType = body.type || "user";
-  console.log(`[RC-DEBUG] web -> server: POST /web/sessions/${sessionId}/events type=${eventType} content=${JSON.stringify(body).slice(0, 200)}`);
+  log(`[RC-DEBUG] web -> server: POST /web/sessions/${sessionId}/events type=${eventType} content=${JSON.stringify(body).slice(0, 200)}`);
   const event = publishSessionEvent(sessionId, eventType, body, "outbound");
-  console.log(`[RC-DEBUG] web -> server: published outbound event id=${event.id} type=${event.type} direction=${event.direction} subscribers=${getEventBus(sessionId).subscriberCount()}`);
+  log(`[RC-DEBUG] web -> server: published outbound event id=${event.id} type=${event.type} direction=${event.direction} subscribers=${getEventBus(sessionId).subscriberCount()}`);
   return c.json({ status: "ok", event }, 200);
 });
 
diff --git a/packages/remote-control-server/src/routes/web/sessions.ts b/packages/remote-control-server/src/routes/web/sessions.ts
index 366114fac..38f9cb48f 100644
--- a/packages/remote-control-server/src/routes/web/sessions.ts
+++ b/packages/remote-control-server/src/routes/web/sessions.ts
@@ -1,3 +1,4 @@
+import { log, error as logError } from "../../logger";
 import { Hono } from "hono";
 import { uuidAuth } from "../../auth/middleware";
 import {
@@ -35,7 +36,7 @@ app.post("/sessions", uuidAuth, async (c) => {
     try {
       await createWorkItem(body.environment_id, session.id);
     } catch (err) {
-      console.error(`[RCS] Failed to create work item: ${(err as Error).message}`);
+      logError(`[RCS] Failed to create work item: ${(err as Error).message}`);
     }
   }
 
diff --git a/packages/remote-control-server/src/services/disconnect-monitor.ts b/packages/remote-control-server/src/services/disconnect-monitor.ts
index e30abb552..7980aabb3 100644
--- a/packages/remote-control-server/src/services/disconnect-monitor.ts
+++ b/packages/remote-control-server/src/services/disconnect-monitor.ts
@@ -1,3 +1,4 @@
+import { log, error as logError } from "../logger";
 import { storeListActiveEnvironments, storeUpdateEnvironment } from "../store";
 import { storeListSessions } from "../store";
 import { config } from "../config";
@@ -10,7 +11,7 @@ export function runDisconnectMonitorSweep(now = Date.now()) {
   const envs = storeListActiveEnvironments();
   for (const env of envs) {
     if (env.lastPollAt && now - env.lastPollAt.getTime() > timeoutMs) {
-      console.log(`[RCS] Environment ${env.id} timed out (no poll for ${Math.round((now - env.lastPollAt.getTime()) / 1000)}s)`);
+      log(`[RCS] Environment ${env.id} timed out (no poll for ${Math.round((now - env.lastPollAt.getTime()) / 1000)}s)`);
       storeUpdateEnvironment(env.id, { status: "disconnected" });
     }
   }
@@ -21,7 +22,7 @@ export function runDisconnectMonitorSweep(now = Date.now()) {
     if (session.status === "running" || session.status === "idle") {
       const elapsed = now - session.updatedAt.getTime();
       if (elapsed > timeoutMs * 2) {
-        console.log(`[RCS] Session ${session.id} marked inactive (no update for ${Math.round(elapsed / 1000)}s)`);
+        log(`[RCS] Session ${session.id} marked inactive (no update for ${Math.round(elapsed / 1000)}s)`);
         updateSessionStatus(session.id, "inactive");
       }
     }
diff --git a/packages/remote-control-server/src/services/work-dispatch.ts b/packages/remote-control-server/src/services/work-dispatch.ts
index 776703f03..f35819376 100644
--- a/packages/remote-control-server/src/services/work-dispatch.ts
+++ b/packages/remote-control-server/src/services/work-dispatch.ts
@@ -1,3 +1,4 @@
+import { log, error as logError } from "../logger";
 import {
   storeCreateWorkItem,
   storeGetWorkItem,
@@ -35,7 +36,7 @@ export async function createWorkItem(environmentId: string, sessionId: string):
 
   const secret = encodeWorkSecret();
   const record = storeCreateWorkItem({ environmentId, sessionId, secret });
-  console.log(`[RCS] Work item created: ${record.id} for env=${environmentId} session=${sessionId}`);
+  log(`[RCS] Work item created: ${record.id} for env=${environmentId} session=${sessionId}`);
   return record.id;
 }
 
diff --git a/packages/remote-control-server/src/transport/event-bus.ts b/packages/remote-control-server/src/transport/event-bus.ts
index 66782c5ca..52b37b432 100644
--- a/packages/remote-control-server/src/transport/event-bus.ts
+++ b/packages/remote-control-server/src/transport/event-bus.ts
@@ -1,3 +1,5 @@
+import { log, error as logError } from "../logger";
+
 export interface SessionEvent {
   id: string;
   sessionId: string;
@@ -33,12 +35,12 @@ export class EventBus {
       createdAt: Date.now(),
     };
     this.events.push(full);
-    console.log(`[RC-DEBUG] bus publish: sessionId=${event.sessionId} type=${event.type} dir=${event.direction} seq=${full.seqNum} subscribers=${this.subscribers.size}`);
+    log(`[RC-DEBUG] bus publish: sessionId=${event.sessionId} type=${event.type} dir=${event.direction} seq=${full.seqNum} subscribers=${this.subscribers.size}`);
     for (const cb of this.subscribers) {
       try {
         cb(full);
       } catch (err) {
-        console.error(`[RC-DEBUG] bus subscriber error:`, err);
+        logError(`[RC-DEBUG] bus subscriber error:`, err);
       }
     }
     return full;
diff --git a/packages/remote-control-server/src/transport/sse-writer.ts b/packages/remote-control-server/src/transport/sse-writer.ts
index 6bfd88142..469c84e36 100644
--- a/packages/remote-control-server/src/transport/sse-writer.ts
+++ b/packages/remote-control-server/src/transport/sse-writer.ts
@@ -1,3 +1,4 @@
+import { log, error as logError } from "../logger";
 import type { Context } from "hono";
 import type { SessionEvent } from "./event-bus";
 import { getEventBus } from "./event-bus";
@@ -76,7 +77,7 @@ export function createSSEStream(c: Context, sessionId: string, fromSeqNum = 0) {
           seqNum: event.seqNum,
         });
         try {
-          console.log(`[RC-DEBUG] SSE -> web: sessionId=${sessionId} type=${event.type} dir=${event.direction} seq=${event.seqNum}`);
+          log(`[RC-DEBUG] SSE -> web: sessionId=${sessionId} type=${event.type} dir=${event.direction} seq=${event.seqNum}`);
           controller.enqueue(encoder.encode(`id: ${event.seqNum}\nevent: message\ndata: ${data}\n\n`));
         } catch {
           unsub();
diff --git a/packages/remote-control-server/src/transport/ws-handler.ts b/packages/remote-control-server/src/transport/ws-handler.ts
index b3f8ac23a..97b919a2b 100644
--- a/packages/remote-control-server/src/transport/ws-handler.ts
+++ b/packages/remote-control-server/src/transport/ws-handler.ts
@@ -2,6 +2,7 @@ import type { WSContext } from "hono/ws";
 import { getEventBus } from "./event-bus";
 import type { SessionEvent } from "./event-bus";
 import { publishSessionEvent } from "../services/transport";
+import { log, error as logError } from "../logger";
 
 // Per-connection cleanup, keyed by sessionId (only one WS per session)
 interface CleanupEntry {
@@ -97,13 +98,13 @@ function toSDKMessage(event: SessionEvent): string {
 /** Called from onOpen — subscribes to event bus, forwards outbound events to bridge WS */
 export function handleWebSocketOpen(ws: WSContext, sessionId: string) {
   const openTime = Date.now();
-  console.log(`[RC-DEBUG] [WS] Open session=${sessionId}`);
+  log(`[RC-DEBUG] [WS] Open session=${sessionId}`);
   activeConnections.add(ws);
 
   // If there's an existing connection for this session, clean it up first
   const existing = cleanupBySession.get(sessionId);
   if (existing) {
-    console.log(`[WS] Replacing existing connection for session=${sessionId}`);
+    log(`[WS] Replacing existing connection for session=${sessionId}`);
     existing.unsub();
     clearInterval(existing.keepalive);
     activeConnections.delete(existing.ws);
@@ -115,7 +116,7 @@ export function handleWebSocketOpen(ws: WSContext, sessionId: string) {
   // the full conversation history — assistant replies are inbound events.
   const missed = bus.getEventsSince(0);
   if (missed.length > 0) {
-    console.log(`[WS] Replaying ${missed.length} missed event(s)`);
+    log(`[WS] Replaying ${missed.length} missed event(s)`);
     for (const event of missed) {
       if (ws.readyState !== 1) break;
       try {
@@ -131,10 +132,10 @@ export function handleWebSocketOpen(ws: WSContext, sessionId: string) {
     if (event.direction !== "outbound") return;
     try {
       const sdkMsg = toSDKMessage(event);
-      console.log(`[RC-DEBUG] [WS] -> bridge (outbound): type=${event.type} len=${sdkMsg.length} msg=${sdkMsg.slice(0, 300)}`);
+      log(`[RC-DEBUG] [WS] -> bridge (outbound): type=${event.type} len=${sdkMsg.length} msg=${sdkMsg.slice(0, 300)}`);
       ws.send(sdkMsg);
     } catch (err) {
-      console.error("[RC-DEBUG] [WS] send error:", err);
+      logError("[RC-DEBUG] [WS] send error:", err);
     }
   });
 
@@ -162,7 +163,7 @@ export function handleWebSocketMessage(ws: WSContext, sessionId: string, data: s
     try {
       ingestBridgeMessage(sessionId, JSON.parse(line));
     } catch (err) {
-      console.error("[WS] parse error:", err);
+      logError("[WS] parse error:", err);
     }
   }
 }
@@ -174,7 +175,7 @@ export function handleWebSocketClose(ws: WSContext, sessionId: string, code?: nu
   const entry = cleanupBySession.get(sessionId);
   const duration = entry ? Math.round((Date.now() - entry.openTime) / 1000) : -1;
 
-  console.log(`[WS] Close session=${sessionId} code=${code ?? "none"} reason=${reason || "(none)"} duration=${duration}s`);
+  log(`[WS] Close session=${sessionId} code=${code ?? "none"} reason=${reason || "(none)"} duration=${duration}s`);
 
   if (entry) {
     entry.unsub();
@@ -216,7 +217,7 @@ export function ingestBridgeMessage(sessionId: string, msg: Record<string, unkno
 
   const eventType = deriveEventType(msg);
 
-  console.log(`[RC-DEBUG] [WS] <- bridge (inbound): sessionId=${sessionId} type=${eventType}${msg.uuid ? ` uuid=${msg.uuid}` : ""} msg=${JSON.stringify(msg).slice(0, 300)}`);
+  log(`[RC-DEBUG] [WS] <- bridge (inbound): sessionId=${sessionId} type=${eventType}${msg.uuid ? ` uuid=${msg.uuid}` : ""} msg=${JSON.stringify(msg).slice(0, 300)}`);
 
   let payload: unknown;
 
@@ -256,7 +257,7 @@ export function closeAllConnections(): void {
   const count = activeConnections.size;
   if (count === 0) return;
 
-  console.log(`[WS] Gracefully closing ${count} active connection(s)...`);
+  log(`[WS] Gracefully closing ${count} active connection(s)...`);
   for (const [sessionId, entry] of cleanupBySession) {
     try {
       entry.unsub();
@@ -270,5 +271,5 @@ export function closeAllConnections(): void {
   }
   cleanupBySession.clear();
   activeConnections.clear();
-  console.log("[WS] All connections closed");
+  log("[WS] All connections closed");
 }
diff --git a/packages/remote-control-server/tsconfig.json b/packages/remote-control-server/tsconfig.json
index 74f468f60..5cb0f34ab 100644
--- a/packages/remote-control-server/tsconfig.json
+++ b/packages/remote-control-server/tsconfig.json
@@ -1,5 +1,5 @@
 {
-  "extends": "../../tsconfig.base.json",
+  "extends": "../../tsconfig.json",
   "include": ["src/**/*.ts"],
   "exclude": ["node_modules", "dist", "web"]
 }
diff --git a/packages/url-handler-napi/tsconfig.json b/packages/url-handler-napi/tsconfig.json
index af2850cc4..1ec82ebae 100644
--- a/packages/url-handler-napi/tsconfig.json
+++ b/packages/url-handler-napi/tsconfig.json
@@ -1,5 +1,5 @@
 {
-  "extends": "../../tsconfig.base.json",
+  "extends": "../../tsconfig.json",
   "include": ["src/**/*.ts"],
   "exclude": ["node_modules", "dist"]
 }
diff --git a/scripts/dev.ts b/scripts/dev.ts
index ca693ab68..954274833 100644
--- a/scripts/dev.ts
+++ b/scripts/dev.ts
@@ -37,6 +37,8 @@ const DEFAULT_FEATURES = [
   "KAIROS_BRIEF", "AWAY_SUMMARY", "ULTRAPLAN",
   // P2: daemon + remote control server
   "DAEMON",
+  // ACP (Agent Client Protocol) agent mode
+  "ACP",
   // PR-package restored features
   "WORKFLOW_SCRIPTS",
   "HISTORY_SNIP",
@@ -47,6 +49,8 @@ const DEFAULT_FEATURES = [
   "KAIROS",
   "COORDINATOR_MODE",
   "LAN_PIPES",
+  "BG_SESSIONS",
+  "TEMPLATES",
   // "REVIEW_ARTIFACT", // API 请求无响应，需进一步排查 schema 兼容性
   // P3: poor mode (disable extract_memories + prompt_suggestion)
   "POOR",
diff --git a/src/QueryEngine.ts b/src/QueryEngine.ts
index c9d67d382..de4269faf 100644
--- a/src/QueryEngine.ts
+++ b/src/QueryEngine.ts
@@ -1184,6 +1184,17 @@ export class QueryEngine {
     this.abortController.abort()
   }
 
+  /** Reset the abort controller so the next submitMessage() call can start
+   *  with a fresh, non-aborted signal. Must be called after interrupt(). */
+  resetAbortController(): void {
+    this.abortController = createAbortController()
+  }
+
+  /** Expose the current abort signal for external consumers (e.g. ACP bridge). */
+  getAbortSignal(): AbortSignal {
+    return this.abortController.signal
+  }
+
   getMessages(): readonly Message[] {
     return this.mutableMessages
   }
diff --git a/src/__tests__/context.baseline.test.ts b/src/__tests__/context.baseline.test.ts
new file mode 100644
index 000000000..c40632cbc
--- /dev/null
+++ b/src/__tests__/context.baseline.test.ts
@@ -0,0 +1,91 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import {
+  resetStateForTests,
+  setOriginalCwd,
+  setProjectRoot,
+} from '../bootstrap/state'
+import {
+  getSystemContext,
+  getUserContext,
+  setSystemPromptInjection,
+} from '../context'
+import { clearMemoryFileCaches } from '../utils/claudemd'
+import { cleanupTempDir, createTempDir, writeTempFile } from '../../tests/mocks/file-system'
+
+let tempDir = ''
+let projectClaudeMdContent = ''
+
+beforeEach(async () => {
+  tempDir = await createTempDir('context-baseline-')
+  projectClaudeMdContent = `baseline-${Date.now()}`
+
+  resetStateForTests()
+  setOriginalCwd(tempDir)
+  setProjectRoot(tempDir)
+  await writeTempFile(tempDir, 'CLAUDE.md', projectClaudeMdContent)
+
+  clearMemoryFileCaches()
+  getUserContext.cache.clear?.()
+  getSystemContext.cache.clear?.()
+  setSystemPromptInjection(null)
+  delete process.env.CLAUDE_CODE_DISABLE_CLAUDE_MDS
+})
+
+afterEach(async () => {
+  clearMemoryFileCaches()
+  getUserContext.cache.clear?.()
+  getSystemContext.cache.clear?.()
+  setSystemPromptInjection(null)
+  delete process.env.CLAUDE_CODE_DISABLE_CLAUDE_MDS
+  resetStateForTests()
+  if (tempDir) {
+    await cleanupTempDir(tempDir)
+  }
+})
+
+describe('context baseline', () => {
+  test('getUserContext includes currentDate and project CLAUDE.md content', async () => {
+    const ctx = await getUserContext()
+
+    expect(ctx.currentDate).toContain("Today's date is")
+    expect(ctx.claudeMd).toContain(projectClaudeMdContent)
+  })
+
+  test('CLAUDE_CODE_DISABLE_CLAUDE_MDS suppresses claudeMd loading', async () => {
+    process.env.CLAUDE_CODE_DISABLE_CLAUDE_MDS = '1'
+
+    const ctx = await getUserContext()
+
+    expect(ctx.currentDate).toContain("Today's date is")
+    expect(ctx.claudeMd).toBeUndefined()
+  })
+
+  test('setSystemPromptInjection clears the memoized user-context cache', async () => {
+    const first = await getUserContext()
+    process.env.CLAUDE_CODE_DISABLE_CLAUDE_MDS = '1'
+
+    const second = await getUserContext()
+    expect(first.claudeMd).toContain(projectClaudeMdContent)
+    expect(second.claudeMd).toContain(projectClaudeMdContent)
+
+    setSystemPromptInjection('cache-break')
+
+    const third = await getUserContext()
+    expect(third.claudeMd).toBeUndefined()
+  })
+
+  test('getSystemContext reflects system prompt injection after cache invalidation', async () => {
+    const first = await getSystemContext()
+    expect(first.gitStatus).toBeUndefined()
+    expect(first.cacheBreaker).toBeUndefined()
+
+    setSystemPromptInjection('baseline-cache-break')
+
+    const second = await getSystemContext()
+    if ('cacheBreaker' in second) {
+      expect(second.cacheBreaker).toContain('baseline-cache-break')
+    } else {
+      expect(second.gitStatus).toBeUndefined()
+    }
+  })
+})
diff --git a/src/assistant/AssistantSessionChooser.ts b/src/assistant/AssistantSessionChooser.ts
deleted file mode 100644
index e61ba6ced..000000000
--- a/src/assistant/AssistantSessionChooser.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-// Auto-generated stub — replace with real implementation
-export {};
-export const AssistantSessionChooser: (props: Record<string, unknown>) => null = () => null;
diff --git a/src/assistant/AssistantSessionChooser.tsx b/src/assistant/AssistantSessionChooser.tsx
new file mode 100644
index 000000000..5f004e840
--- /dev/null
+++ b/src/assistant/AssistantSessionChooser.tsx
@@ -0,0 +1,54 @@
+import * as React from 'react';
+import { useState } from 'react';
+import { Box, Text } from '@anthropic/ink';
+import { Dialog } from '../components/design-system/Dialog.js';
+import { ListItem } from '../components/design-system/ListItem.js';
+import { useRegisterOverlay } from '../context/overlayContext.js';
+import { useKeybindings } from '../keybindings/useKeybinding.js';
+import type { AssistantSession } from './sessionDiscovery.js';
+
+interface Props {
+  sessions: AssistantSession[];
+  onSelect: (id: string) => void;
+  onCancel: () => void;
+}
+
+/**
+ * Interactive session chooser for `claude assistant` when multiple
+ * CCR sessions are discovered. Renders a Dialog with up/down navigation.
+ *
+ * Session IDs are in `session_*` compat format — passed directly to
+ * createRemoteSessionConfig() for viewer attach.
+ */
+export function AssistantSessionChooser({ sessions, onSelect, onCancel }: Props): React.ReactNode {
+  useRegisterOverlay('assistant-session-chooser');
+  const [focusIndex, setFocusIndex] = useState(0);
+
+  useKeybindings(
+    {
+      'select:next': () => setFocusIndex(i => (i + 1) % sessions.length),
+      'select:previous': () => setFocusIndex(i => (i - 1 + sessions.length) % sessions.length),
+      'select:accept': () => onSelect(sessions[focusIndex]!.id),
+    },
+    { context: 'Select' },
+  );
+
+  return (
+    <Dialog title="Select Assistant Session" onCancel={onCancel} hideInputGuide>
+      <Box flexDirection="column" gap={1}>
+        <Text>Multiple sessions found. Select one to attach:</Text>
+        <Box flexDirection="column">
+          {sessions.map((s, i) => (
+            <ListItem key={s.id} isFocused={focusIndex === i}>
+              <Box>
+                <Text>{s.title || s.id.slice(0, 20)}</Text>
+                <Text dimColor> [{s.status}]</Text>
+              </Box>
+            </ListItem>
+          ))}
+        </Box>
+        <Text dimColor>↑↓ navigate · Enter select · Esc cancel</Text>
+      </Box>
+    </Dialog>
+  );
+}
diff --git a/src/assistant/gate.ts b/src/assistant/gate.ts
index 1602a3be4..0cf8f0c4b 100644
--- a/src/assistant/gate.ts
+++ b/src/assistant/gate.ts
@@ -5,21 +5,20 @@ import { getFeatureValue_CACHED_MAY_BE_STALE } from '../services/analytics/growt
 /**
  * Runtime gate for KAIROS features.
  *
- * Build-time: feature('KAIROS') must be on (checked by caller before
- * this module is required).
+ * Two-layer gate:
+ *   1. Build-time: feature('KAIROS') must be on
+ *   2. Runtime: tengu_kairos_assistant GrowthBook flag (remote kill switch)
  *
- * Runtime: tengu_kairos_assistant GrowthBook flag acts as a remote kill
- * switch, and kairosActive state must be true (set during bootstrap when
- * the session qualifies for KAIROS features).
+ * Called by main.tsx BEFORE setKairosActive(true) — must NOT check
+ * kairosActive (that would deadlock: gate needs active, active needs gate).
+ * The caller (main.tsx L1826-1832) sets kairosActive after this returns true.
  */
 export async function isKairosEnabled(): Promise<boolean> {
   if (!feature('KAIROS')) {
     return false
   }
-  if (
-    !getFeatureValue_CACHED_MAY_BE_STALE('tengu_kairos_assistant', false)
-  ) {
+  if (!getFeatureValue_CACHED_MAY_BE_STALE('tengu_kairos_assistant', false)) {
     return false
   }
-  return getKairosActive()
+  return true
 }
diff --git a/src/assistant/index.ts b/src/assistant/index.ts
index 5b75255ad..c13d91b11 100644
--- a/src/assistant/index.ts
+++ b/src/assistant/index.ts
@@ -1,9 +1,64 @@
-// Auto-generated stub — replace with real implementation
-export {}
-export const isAssistantMode: () => boolean = () => false
-export const initializeAssistantTeam: () => Promise<void> = async () => {}
-export const markAssistantForced: () => void = () => {}
-export const isAssistantForced: () => boolean = () => false
-export const getAssistantSystemPromptAddendum: () => string = () => ''
-export const getAssistantActivationPath: () => string | undefined = () =>
-  undefined
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import { getKairosActive } from '../bootstrap/state.js'
+import { getClaudeConfigHomeDir } from '../utils/envUtils.js'
+
+let _assistantForced = false
+
+/**
+ * Whether the current session is in assistant (KAIROS) daemon mode.
+ * Wraps the bootstrap kairosActive state set by main.tsx after gate check.
+ */
+export function isAssistantMode(): boolean {
+  return getKairosActive()
+}
+
+/**
+ * Mark this session as forced assistant mode (--assistant flag).
+ * Skips the GrowthBook gate check — daemon is pre-entitled.
+ */
+export function markAssistantForced(): void {
+  _assistantForced = true
+}
+
+export function isAssistantForced(): boolean {
+  return _assistantForced
+}
+
+/**
+ * Pre-create an in-process team so Agent(name) can spawn teammates
+ * without TeamCreate.
+ *
+ * Phase 1: returns undefined so main.tsx's `assistantTeamContext ?? computeInitialTeamContext()`
+ * correctly falls back. Returning {} would bypass the ?? operator since {} is truthy.
+ *
+ * Phase 2: should return a full team context object matching AppState.teamContext shape.
+ */
+export async function initializeAssistantTeam(): Promise<undefined> {
+  return undefined
+}
+
+/**
+ * Assistant-specific system prompt addendum loaded from ~/.claude/agents/assistant.md.
+ * Returns empty string if the file doesn't exist.
+ */
+export function getAssistantSystemPromptAddendum(): string {
+  try {
+    return readFileSync(
+      join(getClaudeConfigHomeDir(), 'agents', 'assistant.md'),
+      'utf-8',
+    )
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * How assistant mode was activated. Used for diagnostics/analytics.
+ * - 'daemon': via --assistant flag (Agent SDK daemon)
+ * - 'gate': via GrowthBook gate check
+ */
+export function getAssistantActivationPath(): string | undefined {
+  if (!isAssistantMode()) return undefined
+  return _assistantForced ? 'daemon' : 'gate'
+}
diff --git a/src/assistant/sessionDiscovery.ts b/src/assistant/sessionDiscovery.ts
index 424564c1c..d12e88ad6 100644
--- a/src/assistant/sessionDiscovery.ts
+++ b/src/assistant/sessionDiscovery.ts
@@ -1,3 +1,51 @@
-// Auto-generated stub — replace with real implementation
-export type AssistantSession = { id: string; [key: string]: unknown };
-export const discoverAssistantSessions: () => Promise<AssistantSession[]> = () => Promise.resolve([]);
+import { logForDebugging } from '../utils/debug.js'
+
+/**
+ * Minimal session type for assistant discovery.
+ * Only `id` is consumed by main.tsx (L4757); other fields are for chooser display.
+ * ID format is `session_*` (compat prefix) — viewer endpoints use /v1/sessions/*.
+ */
+export type AssistantSession = {
+  id: string
+  title: string
+  status: string
+  created_at: string
+}
+
+/**
+ * Discover assistant sessions on Anthropic CCR.
+ *
+ * Reuses the existing fetchCodeSessionsFromSessionsAPI() which calls
+ * GET /v1/sessions with proper OAuth + anthropic-beta headers.
+ *
+ * Throws on failure — main.tsx L4720-4725 catch displays the error.
+ * Does NOT return [] on error (that would silently redirect to install wizard).
+ */
+export async function discoverAssistantSessions(): Promise<AssistantSession[]> {
+  const { fetchCodeSessionsFromSessionsAPI } = await import(
+    '../utils/teleport/api.js'
+  )
+
+  let allSessions
+  try {
+    allSessions = await fetchCodeSessionsFromSessionsAPI()
+  } catch (err) {
+    logForDebugging(
+      `[assistant:discovery] fetchCodeSessionsFromSessionsAPI failed: ${err}`,
+    )
+    throw err
+  }
+
+  // Filter to active/working sessions only — completed/archived are not attachable
+  return allSessions
+    .filter(
+      s =>
+        s.status === 'idle' || s.status === 'working' || s.status === 'waiting',
+    )
+    .map(s => ({
+      id: s.id,
+      title: s.title || 'Untitled',
+      status: s.status,
+      created_at: s.created_at ?? '',
+    }))
+}
diff --git a/src/bridge/bridgeMain.ts b/src/bridge/bridgeMain.ts
index c0b172386..b1fa496ed 100644
--- a/src/bridge/bridgeMain.ts
+++ b/src/bridge/bridgeMain.ts
@@ -12,6 +12,7 @@ import {
   logEventAsync,
 } from '../services/analytics/index.js'
 import { isInBundledMode } from '../utils/bundledMode.js'
+import { getBootstrapArgs, getScriptPath } from '../utils/cliLaunch.js'
 import { logForDebugging } from '../utils/debug.js'
 import { rcLog } from './rcDebugLog.js'
 import { logForDiagnosticsNoPII } from '../utils/diagLogs.js'
@@ -111,17 +112,15 @@ function pollSleepDetectionThresholdMs(backoff: BackoffConfig): number {
 
 /**
  * Returns the args that must precede CLI flags when spawning a child claude
- * process. In compiled binaries, process.execPath is the claude binary itself
- * and args go directly to it. In npm installs (node running cli.js),
- * process.execPath is the node runtime — the child spawn must pass the script
- * path as the first arg, otherwise node interprets --sdk-url as a node option
- * and exits with "bad option: --sdk-url". See anthropics/claude-code#28334.
+ * process. Delegates to the centralized cliLaunch module which handles
+ * bundled-vs-script mode, execArgv sanitization, and the Bun execArgv leak
+ * quirk. See anthropics/claude-code#28334.
  */
 function spawnScriptArgs(): string[] {
-  if (isInBundledMode() || !process.argv[1]) {
-    return []
-  }
-  return [process.argv[1]]
+  const bootstrap = [...getBootstrapArgs()]
+  const script = getScriptPath()
+  if (script) bootstrap.push(script)
+  return bootstrap
 }
 
 /** Attempt to spawn a session; returns error string if spawn throws. */
diff --git a/src/cli/bg.ts b/src/cli/bg.ts
index 709e7df9e..b06367877 100644
--- a/src/cli/bg.ts
+++ b/src/cli/bg.ts
@@ -1,7 +1,337 @@
-// Auto-generated stub — replace with real implementation
-export {};
-export const psHandler: (args: string[]) => Promise<void> = (async () => {}) as (args: string[]) => Promise<void>;
-export const logsHandler: (sessionId: string | undefined) => Promise<void> = (async () => {}) as (sessionId: string | undefined) => Promise<void>;
-export const attachHandler: (sessionId: string | undefined) => Promise<void> = (async () => {}) as (sessionId: string | undefined) => Promise<void>;
-export const killHandler: (sessionId: string | undefined) => Promise<void> = (async () => {}) as (sessionId: string | undefined) => Promise<void>;
-export const handleBgFlag: (args: string[]) => Promise<void> = (async () => {}) as (args: string[]) => Promise<void>;
+import { readdir, readFile, unlink } from 'fs/promises'
+import { join } from 'path'
+import { randomUUID } from 'crypto'
+import { getClaudeConfigHomeDir } from '../utils/envUtils.js'
+import { isProcessRunning } from '../utils/genericProcessUtils.js'
+import { jsonParse } from '../utils/slowOperations.js'
+import { selectEngine } from './bg/engines/index.js'
+import type { SessionEntry } from './bg/engine.js'
+
+export type { SessionEntry } from './bg/engine.js'
+
+function getSessionsDir(): string {
+  return join(getClaudeConfigHomeDir(), 'sessions')
+}
+
+export async function listLiveSessions(): Promise<SessionEntry[]> {
+  const dir = getSessionsDir()
+  let files: string[]
+  try {
+    files = await readdir(dir)
+  } catch {
+    return []
+  }
+
+  const sessions: SessionEntry[] = []
+  for (const file of files) {
+    if (!/^\d+\.json$/.test(file)) continue
+    const pid = parseInt(file.slice(0, -5), 10)
+
+    if (!isProcessRunning(pid)) {
+      void unlink(join(dir, file)).catch(() => {})
+      continue
+    }
+
+    try {
+      const raw = await readFile(join(dir, file), 'utf-8')
+      const entry = jsonParse(raw) as SessionEntry
+      sessions.push(entry)
+    } catch {
+      // Corrupt file — skip
+    }
+  }
+
+  return sessions
+}
+
+export function findSession(
+  sessions: SessionEntry[],
+  target: string,
+): SessionEntry | undefined {
+  const asNum = parseInt(target, 10)
+  return sessions.find(
+    s =>
+      s.sessionId === target ||
+      s.pid === asNum ||
+      (s.name && s.name === target),
+  )
+}
+
+function formatTime(ts: number): string {
+  return new Date(ts).toLocaleString()
+}
+
+/**
+ * Resolve the engine type for an existing session.
+ * Backward-compatible: sessions without an `engine` field are inferred
+ * from the presence of `tmuxSessionName`.
+ */
+function resolveSessionEngine(session: SessionEntry): 'tmux' | 'detached' {
+  if (session.engine) return session.engine
+  return session.tmuxSessionName ? 'tmux' : 'detached'
+}
+
+/**
+ * `claude daemon status` / `claude ps` — list live sessions.
+ */
+export async function psHandler(_args: string[]): Promise<void> {
+  const sessions = await listLiveSessions()
+
+  if (sessions.length === 0) {
+    console.log('No active sessions.')
+    return
+  }
+
+  console.log(
+    `${sessions.length} active session${sessions.length > 1 ? 's' : ''}:\n`,
+  )
+
+  for (const s of sessions) {
+    const engineType = resolveSessionEngine(s)
+    const parts: string[] = [
+      `  PID: ${s.pid}`,
+      `  Kind: ${s.kind}`,
+      `  Engine: ${engineType}`,
+      `  Session: ${s.sessionId}`,
+      `  CWD: ${s.cwd}`,
+    ]
+
+    if (s.name) parts.push(`  Name: ${s.name}`)
+    if (s.startedAt) parts.push(`  Started: ${formatTime(s.startedAt)}`)
+    if (s.status) parts.push(`  Status: ${s.status}`)
+    if (s.waitingFor) parts.push(`  Waiting for: ${s.waitingFor}`)
+    if (s.bridgeSessionId) parts.push(`  Bridge: ${s.bridgeSessionId}`)
+    if (s.tmuxSessionName) parts.push(`  Tmux: ${s.tmuxSessionName}`)
+    if (s.logPath) parts.push(`  Log: ${s.logPath}`)
+
+    console.log(parts.join('\n'))
+    console.log()
+  }
+}
+
+/**
+ * `claude daemon logs <target>` — show logs for a session.
+ */
+export async function logsHandler(target: string | undefined): Promise<void> {
+  const sessions = await listLiveSessions()
+
+  if (!target) {
+    if (sessions.length === 0) {
+      console.log('No active sessions.')
+      return
+    }
+    if (sessions.length === 1) {
+      target = sessions[0]!.sessionId
+    } else {
+      console.log('Multiple sessions active. Specify one:')
+      for (const s of sessions) {
+        const label = s.name ? `${s.name} (${s.sessionId})` : s.sessionId
+        console.log(`  ${label}  PID=${s.pid}`)
+      }
+      return
+    }
+  }
+
+  const session = findSession(sessions, target)
+  if (!session) {
+    console.error(`Session not found: ${target}`)
+    process.exitCode = 1
+    return
+  }
+
+  if (!session.logPath) {
+    console.log(`No log path recorded for session ${session.sessionId}`)
+    return
+  }
+
+  try {
+    const content = await readFile(session.logPath, 'utf-8')
+    process.stdout.write(content)
+  } catch (e) {
+    console.error(`Failed to read log file: ${session.logPath}`)
+    console.error(e instanceof Error ? e.message : String(e))
+    process.exitCode = 1
+  }
+}
+
+/**
+ * `claude daemon attach <target>` — attach to a background session.
+ *
+ * Engine-aware: tmux sessions use tmux attach, detached sessions use log tail.
+ */
+export async function attachHandler(target: string | undefined): Promise<void> {
+  const sessions = await listLiveSessions()
+
+  if (!target) {
+    // Find bg sessions (tmux or detached)
+    const bgSessions = sessions.filter(
+      s => s.tmuxSessionName || s.engine === 'detached',
+    )
+    if (bgSessions.length === 0) {
+      console.log(
+        'No background sessions to attach to. Start one with `claude daemon bg`.',
+      )
+      return
+    }
+    if (bgSessions.length === 1) {
+      target = bgSessions[0]!.sessionId
+    } else {
+      console.log('Multiple background sessions. Specify one:')
+      for (const s of bgSessions) {
+        const label = s.name ? `${s.name} (${s.sessionId})` : s.sessionId
+        const engineType = resolveSessionEngine(s)
+        console.log(`  ${label}  PID=${s.pid}  engine=${engineType}`)
+      }
+      return
+    }
+  }
+
+  const session = findSession(sessions, target)
+  if (!session) {
+    console.error(`Session not found: ${target}`)
+    process.exitCode = 1
+    return
+  }
+
+  const engineType = resolveSessionEngine(session)
+
+  try {
+    if (engineType === 'tmux') {
+      const { TmuxEngine } = await import('./bg/engines/tmux.js')
+      const tmux = new TmuxEngine()
+      if (!(await tmux.available())) {
+        console.error('tmux is no longer available. Cannot attach to tmux session.')
+        process.exitCode = 1
+        return
+      }
+      await tmux.attach(session)
+    } else {
+      const { DetachedEngine } = await import('./bg/engines/detached.js')
+      const detached = new DetachedEngine()
+      await detached.attach(session)
+    }
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : String(e))
+    process.exitCode = 1
+  }
+}
+
+/**
+ * `claude daemon kill <target>` — kill a session.
+ */
+export async function killHandler(target: string | undefined): Promise<void> {
+  const sessions = await listLiveSessions()
+
+  if (!target) {
+    if (sessions.length === 0) {
+      console.log('No active sessions to kill.')
+      return
+    }
+    console.log('Specify a session to kill:')
+    for (const s of sessions) {
+      const label = s.name ? `${s.name} (${s.sessionId})` : s.sessionId
+      console.log(`  ${label}  PID=${s.pid}`)
+    }
+    return
+  }
+
+  const session = findSession(sessions, target)
+  if (!session) {
+    console.error(`Session not found: ${target}`)
+    process.exitCode = 1
+    return
+  }
+
+  console.log(`Killing session ${session.sessionId} (PID: ${session.pid})...`)
+
+  try {
+    process.kill(session.pid, 'SIGTERM')
+  } catch {
+    console.log('Session already exited.')
+    return
+  }
+
+  await new Promise(resolve => setTimeout(resolve, 2000))
+
+  if (isProcessRunning(session.pid)) {
+    try {
+      process.kill(session.pid, 'SIGKILL')
+      console.log('Session force-killed.')
+    } catch {
+      console.log('Session exited during grace period.')
+    }
+  } else {
+    console.log('Session stopped.')
+  }
+
+  const pidFile = join(getSessionsDir(), `${session.pid}.json`)
+  void unlink(pidFile).catch(() => {})
+}
+
+/**
+ * `claude daemon bg [args]` — start a background session.
+ *
+ * Cross-platform: uses TmuxEngine on macOS/Linux when tmux is available,
+ * falls back to DetachedEngine on Windows or when tmux is absent.
+ */
+export async function handleBgStart(args: string[]): Promise<void> {
+  const engine = await selectEngine()
+
+  // Strip --bg/--background from args (for backward-compat shortcut)
+  const filteredArgs = args.filter(a => a !== '--bg' && a !== '--background')
+
+  // Engines without interactive TTY input (e.g. detached) require -p/--print
+  // or piped input. Tmux provides a virtual terminal so it works without -p.
+  if (
+    !engine.supportsInteractiveInput &&
+    !filteredArgs.some(a => a === '-p' || a === '--print' || a === '--pipe')
+  ) {
+    console.error(
+      'Error: Background sessions with detached engine require -p/--print flag.\n' +
+        'The detached engine has no terminal for interactive input.\n\n' +
+        'Usage:\n' +
+        '  claude daemon bg -p "your prompt here"\n' +
+        '  echo "prompt" | claude daemon bg --pipe',
+    )
+    if (process.platform !== 'win32') {
+      console.error(
+        '\nAlternatively, install tmux for interactive background sessions:\n' +
+          `  ${process.platform === 'darwin' ? 'brew install tmux' : 'sudo apt install tmux'}`,
+      )
+    }
+    process.exitCode = 1
+    return
+  }
+
+  const sessionName = `claude-bg-${randomUUID().slice(0, 8)}`
+  const logPath = join(
+    getClaudeConfigHomeDir(),
+    'sessions',
+    'logs',
+    `${sessionName}.log`,
+  )
+
+  try {
+    const result = await engine.start({
+      sessionName,
+      args: filteredArgs,
+      env: { ...process.env },
+      logPath,
+      cwd: process.cwd(),
+    })
+
+    console.log(`Background session started: ${result.sessionName}`)
+    console.log(`  Engine: ${result.engineUsed}`)
+    console.log(`  Log: ${result.logPath}`)
+    console.log()
+    console.log(`Use \`claude daemon attach ${result.sessionName}\` to reconnect.`)
+    console.log(`Use \`claude daemon status\` to check status.`)
+    console.log(`Use \`claude daemon kill ${result.sessionName}\` to stop.`)
+  } catch (e) {
+    console.error(e instanceof Error ? e.message : String(e))
+    process.exitCode = 1
+  }
+}
+
+// Legacy export alias — kept for backward compatibility with cli.tsx
+export const handleBgFlag = handleBgStart
diff --git a/src/cli/bg/__tests__/detached.test.ts b/src/cli/bg/__tests__/detached.test.ts
new file mode 100644
index 000000000..ead4f1c78
--- /dev/null
+++ b/src/cli/bg/__tests__/detached.test.ts
@@ -0,0 +1,15 @@
+import { describe, test, expect } from 'bun:test'
+import { DetachedEngine } from '../engines/detached.js'
+
+describe('DetachedEngine', () => {
+  test('name is "detached"', () => {
+    const engine = new DetachedEngine()
+    expect(engine.name).toBe('detached')
+  })
+
+  test('available always returns true', async () => {
+    const engine = new DetachedEngine()
+    const result = await engine.available()
+    expect(result).toBe(true)
+  })
+})
diff --git a/src/cli/bg/__tests__/engine.test.ts b/src/cli/bg/__tests__/engine.test.ts
new file mode 100644
index 000000000..2c4a3226e
--- /dev/null
+++ b/src/cli/bg/__tests__/engine.test.ts
@@ -0,0 +1,37 @@
+import { describe, test, expect } from 'bun:test'
+
+describe('selectEngine', () => {
+  test('returns engine with valid BgEngine interface', async () => {
+    const { selectEngine } = await import('../engines/index.js')
+    const engine = await selectEngine()
+    expect(engine.name).toBeDefined()
+    expect(['tmux', 'detached']).toContain(engine.name)
+    expect(typeof engine.available).toBe('function')
+    expect(typeof engine.start).toBe('function')
+    expect(typeof engine.attach).toBe('function')
+  })
+
+  test('engine.available() returns a boolean', async () => {
+    const { selectEngine } = await import('../engines/index.js')
+    const engine = await selectEngine()
+    const result = await engine.available()
+    expect(typeof result).toBe('boolean')
+  })
+})
+
+describe('SessionEntry type', () => {
+  test('engine field accepts tmux or detached', async () => {
+    // Verify the module loads and exports the expected interface shape
+    const mod = await import('../engine.js')
+    expect(mod).toBeDefined()
+    const entry = {
+      pid: 123,
+      sessionId: 'test',
+      cwd: '/tmp',
+      startedAt: Date.now(),
+      kind: 'bg',
+      engine: 'detached' as const,
+    }
+    expect(entry.engine).toBe('detached')
+  })
+})
diff --git a/src/cli/bg/__tests__/tail.test.ts b/src/cli/bg/__tests__/tail.test.ts
new file mode 100644
index 000000000..7cbfba72a
--- /dev/null
+++ b/src/cli/bg/__tests__/tail.test.ts
@@ -0,0 +1,8 @@
+import { describe, test, expect } from 'bun:test'
+
+describe('tailLog', () => {
+  test('module exports tailLog function', async () => {
+    const mod = await import('../tail.js')
+    expect(typeof mod.tailLog).toBe('function')
+  })
+})
diff --git a/src/cli/bg/engine.ts b/src/cli/bg/engine.ts
new file mode 100644
index 000000000..394184f24
--- /dev/null
+++ b/src/cli/bg/engine.ts
@@ -0,0 +1,49 @@
+/**
+ * BgEngine — cross-platform background session engine abstraction.
+ *
+ * Implementations:
+ *   TmuxEngine    — macOS/Linux with tmux installed
+ *   DetachedEngine — Windows, or macOS/Linux without tmux (fallback)
+ */
+
+export interface SessionEntry {
+  pid: number
+  sessionId: string
+  cwd: string
+  startedAt: number
+  kind: string
+  name?: string
+  logPath?: string
+  entrypoint?: string
+  status?: string
+  waitingFor?: string
+  updatedAt?: number
+  bridgeSessionId?: string
+  agent?: string
+  tmuxSessionName?: string
+  engine?: 'tmux' | 'detached'
+}
+
+export interface BgStartOptions {
+  sessionName: string
+  args: string[]
+  env: Record<string, string | undefined>
+  logPath: string
+  cwd: string
+}
+
+export interface BgStartResult {
+  pid: number
+  sessionName: string
+  logPath: string
+  engineUsed: 'tmux' | 'detached'
+}
+
+export interface BgEngine {
+  readonly name: 'tmux' | 'detached'
+  /** Whether the engine provides a TTY for interactive REPL input. */
+  readonly supportsInteractiveInput: boolean
+  available(): Promise<boolean>
+  start(opts: BgStartOptions): Promise<BgStartResult>
+  attach(session: SessionEntry): Promise<void>
+}
diff --git a/src/cli/bg/engines/detached.ts b/src/cli/bg/engines/detached.ts
new file mode 100644
index 000000000..4dda9891d
--- /dev/null
+++ b/src/cli/bg/engines/detached.ts
@@ -0,0 +1,54 @@
+import { closeSync, mkdirSync, openSync } from 'fs'
+import { dirname } from 'path'
+import { buildCliLaunch, spawnCli } from '../../../utils/cliLaunch.js'
+import type { BgEngine, BgStartOptions, BgStartResult, SessionEntry } from '../engine.js'
+import { tailLog } from '../tail.js'
+
+export class DetachedEngine implements BgEngine {
+  readonly name = 'detached' as const
+  readonly supportsInteractiveInput = false
+
+  async available(): Promise<boolean> {
+    return true
+  }
+
+  async start(opts: BgStartOptions): Promise<BgStartResult> {
+    mkdirSync(dirname(opts.logPath), { recursive: true })
+
+    const logFd = openSync(opts.logPath, 'a')
+
+    const launch = buildCliLaunch(opts.args, {
+      env: {
+        ...opts.env,
+        CLAUDE_CODE_SESSION_KIND: 'bg',
+        CLAUDE_CODE_SESSION_NAME: opts.sessionName,
+        CLAUDE_CODE_SESSION_LOG: opts.logPath,
+      } as NodeJS.ProcessEnv,
+    })
+
+    const child = spawnCli(launch, {
+      detached: true,
+      stdio: ['ignore', logFd, logFd],
+      cwd: opts.cwd,
+    })
+
+    child.unref()
+    closeSync(logFd)
+
+    const pid = child.pid ?? 0
+
+    return {
+      pid,
+      sessionName: opts.sessionName,
+      logPath: opts.logPath,
+      engineUsed: 'detached',
+    }
+  }
+
+  async attach(session: SessionEntry): Promise<void> {
+    if (!session.logPath) {
+      throw new Error(`Session ${session.sessionId} has no log path.`)
+    }
+    await tailLog(session.logPath)
+  }
+}
diff --git a/src/cli/bg/engines/index.ts b/src/cli/bg/engines/index.ts
new file mode 100644
index 000000000..cee304c54
--- /dev/null
+++ b/src/cli/bg/engines/index.ts
@@ -0,0 +1,17 @@
+export type { BgEngine, BgStartOptions, BgStartResult, SessionEntry } from '../engine.js'
+
+export async function selectEngine(): Promise<import('../engine.js').BgEngine> {
+  if (process.platform === 'win32') {
+    const { DetachedEngine } = await import('./detached.js')
+    return new DetachedEngine()
+  }
+
+  const { TmuxEngine } = await import('./tmux.js')
+  const tmux = new TmuxEngine()
+  if (await tmux.available()) {
+    return tmux
+  }
+
+  const { DetachedEngine } = await import('./detached.js')
+  return new DetachedEngine()
+}
diff --git a/src/cli/bg/engines/tmux.ts b/src/cli/bg/engines/tmux.ts
new file mode 100644
index 000000000..965440d8e
--- /dev/null
+++ b/src/cli/bg/engines/tmux.ts
@@ -0,0 +1,75 @@
+import { spawnSync } from 'child_process'
+import { execFileNoThrow } from '../../../utils/execFileNoThrow.js'
+import { buildCliLaunch, quoteCliLaunch } from '../../../utils/cliLaunch.js'
+import type { BgEngine, BgStartOptions, BgStartResult, SessionEntry } from '../engine.js'
+
+export class TmuxEngine implements BgEngine {
+  readonly name = 'tmux' as const
+  readonly supportsInteractiveInput = true
+
+  async available(): Promise<boolean> {
+    const { code } = await execFileNoThrow('tmux', ['-V'], { useCwd: false })
+    return code === 0
+  }
+
+  async start(opts: BgStartOptions): Promise<BgStartResult> {
+    const launch = buildCliLaunch(opts.args, {
+      env: {
+        ...opts.env,
+        CLAUDE_CODE_SESSION_KIND: 'bg',
+        CLAUDE_CODE_SESSION_NAME: opts.sessionName,
+        CLAUDE_CODE_SESSION_LOG: opts.logPath,
+        CLAUDE_CODE_TMUX_SESSION: opts.sessionName,
+      } as NodeJS.ProcessEnv,
+    })
+
+    const cmd = quoteCliLaunch(launch)
+
+    const result = spawnSync(
+      'tmux',
+      ['new-session', '-d', '-s', opts.sessionName, cmd],
+      { stdio: 'inherit', env: launch.env },
+    )
+
+    if (result.status !== 0) {
+      throw new Error('Failed to create tmux session.')
+    }
+
+    // tmux doesn't directly report the child PID; we return 0.
+    // The actual session process writes its own PID file.
+    return {
+      pid: 0,
+      sessionName: opts.sessionName,
+      logPath: opts.logPath,
+      engineUsed: 'tmux',
+    }
+  }
+
+  async attach(session: SessionEntry): Promise<void> {
+    if (!session.tmuxSessionName) {
+      throw new Error(`Session ${session.sessionId} has no tmux session name.`)
+    }
+
+    const result = spawnSync(
+      'tmux',
+      ['attach-session', '-t', session.tmuxSessionName],
+      { stdio: 'inherit' },
+    )
+
+    if (result.status !== 0) {
+      throw new Error(
+        `Failed to attach to tmux session '${session.tmuxSessionName}'.`,
+      )
+    }
+  }
+}
+
+export function getTmuxInstallHint(): string {
+  if (process.platform === 'darwin') {
+    return 'Install with: brew install tmux'
+  }
+  if (process.platform === 'win32') {
+    return 'tmux is not natively available on Windows. Consider using WSL.'
+  }
+  return 'Install with: sudo apt install tmux  (or your package manager)'
+}
diff --git a/src/cli/bg/tail.ts b/src/cli/bg/tail.ts
new file mode 100644
index 000000000..a99734c4a
--- /dev/null
+++ b/src/cli/bg/tail.ts
@@ -0,0 +1,70 @@
+import {
+  openSync,
+  readSync,
+  closeSync,
+  statSync,
+  watchFile,
+  unwatchFile,
+  createReadStream,
+} from 'fs'
+import { createInterface } from 'readline'
+
+/**
+ * Cross-platform real-time log output. Ctrl+C exits tail without killing
+ * the background process.
+ *
+ * Strategy:
+ *  1. Read existing content and output to stdout
+ *  2. Use fs.watchFile() (polling-based — works everywhere including Windows)
+ *  3. On change, read new bytes from the last known position
+ *  4. SIGINT exits cleanly
+ */
+export async function tailLog(logPath: string): Promise<void> {
+  let position = 0
+
+  // Output existing content
+  try {
+    const stat = statSync(logPath)
+    position = stat.size
+    if (position > 0) {
+      const stream = createReadStream(logPath, { start: 0, end: position - 1 })
+      const rl = createInterface({ input: stream })
+      for await (const line of rl) {
+        process.stdout.write(line + '\n')
+      }
+    }
+  } catch {
+    // File may not exist yet — that's fine
+  }
+
+  console.log('\n[tail] Watching for new output... (Ctrl+C to detach)\n')
+
+  return new Promise<void>(resolve => {
+    const onSignal = (): void => {
+      unwatchFile(logPath)
+      process.removeListener('SIGINT', onSignal)
+      console.log('\n[tail] Detached from session.')
+      resolve()
+    }
+    process.on('SIGINT', onSignal)
+
+    watchFile(logPath, { interval: 300 }, () => {
+      try {
+        const stat = statSync(logPath)
+        if (stat.size <= position) return
+
+        const fd = openSync(logPath, 'r')
+        try {
+          const buf = Buffer.alloc(stat.size - position)
+          readSync(fd, buf, 0, buf.length, position)
+          process.stdout.write(buf)
+          position = stat.size
+        } finally {
+          closeSync(fd)
+        }
+      } catch {
+        // File may have been deleted or truncated
+      }
+    })
+  })
+}
diff --git a/src/cli/handlers/ant.ts b/src/cli/handlers/ant.ts
index 74e53359f..1694281b0 100644
--- a/src/cli/handlers/ant.ts
+++ b/src/cli/handlers/ant.ts
@@ -1,13 +1,216 @@
-// Auto-generated stub — replace with real implementation
-import type { Command } from '@commander-js/extra-typings';
-
-export {};
-export const logHandler: (logId: string | number | undefined) => Promise<void> = (async () => {}) as (logId: string | number | undefined) => Promise<void>;
-export const errorHandler: (num: number | undefined) => Promise<void> = (async () => {}) as (num: number | undefined) => Promise<void>;
-export const exportHandler: (source: string, outputFile: string) => Promise<void> = (async () => {}) as (source: string, outputFile: string) => Promise<void>;
-export const taskCreateHandler: (subject: string, opts: { description?: string; list?: string }) => Promise<void> = (async () => {}) as (subject: string, opts: { description?: string; list?: string }) => Promise<void>;
-export const taskListHandler: (opts: { list?: string; pending?: boolean; json?: boolean }) => Promise<void> = (async () => {}) as (opts: { list?: string; pending?: boolean; json?: boolean }) => Promise<void>;
-export const taskGetHandler: (id: string, opts: { list?: string }) => Promise<void> = (async () => {}) as (id: string, opts: { list?: string }) => Promise<void>;
-export const taskUpdateHandler: (id: string, opts: { list?: string; status?: string; subject?: string; description?: string; owner?: string; clearOwner?: boolean }) => Promise<void> = (async () => {}) as (id: string, opts: { list?: string; status?: string; subject?: string; description?: string; owner?: string; clearOwner?: boolean }) => Promise<void>;
-export const taskDirHandler: (opts: { list?: string }) => Promise<void> = (async () => {}) as (opts: { list?: string }) => Promise<void>;
-export const completionHandler: (shell: string, opts: { output?: string }, program: Command) => Promise<void> = (async () => {}) as (shell: string, opts: { output?: string }, program: Command) => Promise<void>;
+import type { Command } from '@commander-js/extra-typings'
+import {
+  createTask,
+  getTask,
+  updateTask,
+  listTasks,
+  getTasksDir,
+} from '../../utils/tasks.js'
+import { getRecentActivity } from '../../utils/logoV2Utils.js'
+import type { LogOption } from '../../types/logs.js'
+
+const DEFAULT_LIST = 'default'
+
+// ─── Group C: Task CRUD ──────────────────────────────────────────────────────
+
+export async function taskCreateHandler(
+  subject: string,
+  opts: { description?: string; list?: string },
+): Promise<void> {
+  const listId = opts.list || DEFAULT_LIST
+  const id = await createTask(listId, {
+    subject,
+    description: opts.description || '',
+    status: 'pending',
+    blocks: [],
+    blockedBy: [],
+  })
+  console.log(`Created task ${id}: ${subject}`)
+}
+
+export async function taskListHandler(opts: {
+  list?: string
+  pending?: boolean
+  json?: boolean
+}): Promise<void> {
+  const listId = opts.list || DEFAULT_LIST
+  let tasks = await listTasks(listId)
+
+  if (opts.pending) {
+    tasks = tasks.filter(t => t.status === 'pending')
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(tasks, null, 2))
+    return
+  }
+
+  if (tasks.length === 0) {
+    console.log('No tasks found.')
+    return
+  }
+
+  for (const t of tasks) {
+    console.log(`  [${t.status}] ${t.id}: ${t.subject}`)
+    if (t.description) console.log(`    ${t.description}`)
+    if (t.owner) console.log(`    owner: ${t.owner}`)
+  }
+}
+
+export async function taskGetHandler(
+  id: string,
+  opts: { list?: string },
+): Promise<void> {
+  const listId = opts.list || DEFAULT_LIST
+  const task = await getTask(listId, id)
+  if (!task) {
+    console.error(`Task not found: ${id}`)
+    process.exitCode = 1
+    return
+  }
+  console.log(JSON.stringify(task, null, 2))
+}
+
+export async function taskUpdateHandler(
+  id: string,
+  opts: {
+    list?: string
+    status?: string
+    subject?: string
+    description?: string
+    owner?: string
+    clearOwner?: boolean
+  },
+): Promise<void> {
+  const listId = opts.list || DEFAULT_LIST
+  const updates: Record<string, unknown> = {}
+
+  if (opts.status) updates.status = opts.status
+  if (opts.subject) updates.subject = opts.subject
+  if (opts.description) updates.description = opts.description
+  if (opts.owner) updates.owner = opts.owner
+  if (opts.clearOwner) updates.owner = undefined
+
+  const task = await updateTask(listId, id, updates)
+  if (!task) {
+    console.error(`Task not found: ${id}`)
+    process.exitCode = 1
+    return
+  }
+  console.log(`Updated task ${id}: [${task.status}] ${task.subject}`)
+}
+
+export async function taskDirHandler(opts: { list?: string }): Promise<void> {
+  const listId = opts.list || DEFAULT_LIST
+  console.log(getTasksDir(listId))
+}
+
+// ─── Group B: Log / Error / Export ───────────────────────────────────────────
+
+export async function logHandler(
+  logId: string | number | undefined,
+): Promise<void> {
+  const logs = await getRecentActivity()
+
+  if (logId === undefined) {
+    if (logs.length === 0) {
+      console.log('No recent sessions.')
+      return
+    }
+    for (let i = 0; i < Math.min(logs.length, 20); i++) {
+      const log = logs[i]!
+      const date = log.modified
+        ? new Date(log.modified).toLocaleString()
+        : 'unknown'
+      const title =
+        (log as Record<string, unknown>).title || log.sessionId || 'untitled'
+      console.log(`  ${i}: ${title}  (${date})`)
+    }
+    return
+  }
+
+  const idx = typeof logId === 'string' ? parseInt(logId, 10) : logId
+  const log =
+    Number.isFinite(idx) && idx >= 0 && idx < logs.length
+      ? logs[idx]
+      : logs.find(l => l.sessionId === String(logId))
+
+  if (!log) {
+    console.error(`Session not found: ${logId}`)
+    process.exitCode = 1
+    return
+  }
+
+  console.log(JSON.stringify(log, null, 2))
+}
+
+export async function errorHandler(num: number | undefined): Promise<void> {
+  // Error log viewing — shows recent session errors
+  const logs = await getRecentActivity()
+  const count = num ?? 5
+
+  console.log(`Last ${count} sessions:`)
+  for (let i = 0; i < Math.min(count, logs.length); i++) {
+    const log = logs[i]!
+    const date = log.modified
+      ? new Date(log.modified).toLocaleString()
+      : 'unknown'
+    console.log(`  ${i}: ${log.sessionId}  (${date})`)
+  }
+}
+
+export async function exportHandler(
+  source: string,
+  outputFile: string,
+): Promise<void> {
+  const { writeFile, readFile } = await import('fs/promises')
+  const logs = await getRecentActivity()
+
+  // Try as index first
+  const idx = parseInt(source, 10)
+  let log: LogOption | undefined
+  if (Number.isFinite(idx) && idx >= 0 && idx < logs.length) {
+    log = logs[idx]
+  } else {
+    log = logs.find(l => l.sessionId === source)
+  }
+
+  if (!log) {
+    // Try as file path
+    try {
+      const content = await readFile(source, 'utf-8')
+      await writeFile(outputFile, content, 'utf-8')
+      console.log(`Exported ${source} → ${outputFile}`)
+      return
+    } catch {
+      console.error(`Source not found: ${source}`)
+      process.exitCode = 1
+      return
+    }
+  }
+
+  await writeFile(outputFile, JSON.stringify(log, null, 2), 'utf-8')
+  console.log(`Exported session ${log.sessionId} → ${outputFile}`)
+}
+
+// ─── Group D: Completion ─────────────────────────────────────────────────────
+
+export async function completionHandler(
+  shell: string,
+  opts: { output?: string },
+  _program: Command,
+): Promise<void> {
+  const { regenerateCompletionCache } = await import(
+    '../../utils/completionCache.js'
+  )
+
+  if (opts.output) {
+    // Generate and write to file
+    await regenerateCompletionCache()
+    console.log(`Completion cache regenerated for ${shell}.`)
+  } else {
+    // Regenerate and output to stdout
+    await regenerateCompletionCache()
+    console.log(`Completion cache regenerated for ${shell}.`)
+  }
+}
diff --git a/src/cli/handlers/templateJobs.ts b/src/cli/handlers/templateJobs.ts
index aefb23217..525ccf25f 100644
--- a/src/cli/handlers/templateJobs.ts
+++ b/src/cli/handlers/templateJobs.ts
@@ -1,3 +1,158 @@
-// Auto-generated stub — replace with real implementation
-export {};
-export const templatesMain: (args: string[]) => Promise<void> = () => Promise.resolve();
+import { randomUUID } from 'crypto'
+import { listTemplates, loadTemplate } from '../../jobs/templates.js'
+import {
+  createJob,
+  readJobState,
+  appendJobReply,
+  getJobDir,
+} from '../../jobs/state.js'
+
+/**
+ * Entry point for template job commands: `new`, `list`, `reply`.
+ * Called from cli.tsx fast-path.
+ */
+export async function templatesMain(args: string[]): Promise<void> {
+  const subcommand = args[0]
+
+  switch (subcommand) {
+    case 'list':
+      handleList()
+      break
+    case 'new':
+      handleNew(args.slice(1))
+      break
+    case 'reply':
+      handleReply(args.slice(1))
+      break
+    case 'status':
+      handleStatus(args.slice(1))
+      break
+    default:
+      console.error(`Unknown template command: ${subcommand}`)
+      printUsage()
+      process.exitCode = 1
+  }
+}
+
+function printUsage(): void {
+  console.log(`
+Template Job Commands:
+
+  claude job list                    List available templates
+  claude job new <template> [args]   Create a new job from a template
+  claude job reply <job-id> <text>   Reply to an existing job
+  claude job status <job-id>         Show job status
+`)
+}
+
+function handleStatus(args: string[]): void {
+  const jobId = args[0]
+  if (!jobId) {
+    console.error('Usage: claude job status <job-id>')
+    process.exitCode = 1
+    return
+  }
+
+  const state = readJobState(jobId)
+  if (!state) {
+    console.error(`Job not found: ${jobId}`)
+    process.exitCode = 1
+    return
+  }
+
+  console.log(`Job: ${state.jobId}`)
+  console.log(`  Template: ${state.templateName}`)
+  console.log(`  Status: ${state.status}`)
+  console.log(`  Created: ${state.createdAt}`)
+  console.log(`  Updated: ${state.updatedAt}`)
+  console.log(`  Args: ${state.args.join(' ') || '(none)'}`)
+}
+
+function handleList(): void {
+  const templates = listTemplates()
+
+  if (templates.length === 0) {
+    console.log('No templates found.')
+    console.log('Place .md files in .claude/templates/ or ~/.claude/templates/')
+    return
+  }
+
+  console.log(
+    `${templates.length} template${templates.length > 1 ? 's' : ''} found:\n`,
+  )
+
+  for (const t of templates) {
+    console.log(`  ${t.name}`)
+    console.log(`    ${t.description}`)
+    console.log(`    Path: ${t.filePath}`)
+    console.log()
+  }
+}
+
+function handleNew(args: string[]): void {
+  const templateName = args[0]
+  if (!templateName) {
+    console.error('Usage: claude job new <template> [args...]')
+    process.exitCode = 1
+    return
+  }
+
+  const template = loadTemplate(templateName)
+  if (!template) {
+    console.error(`Template not found: ${templateName}`)
+    console.log('\nAvailable templates:')
+    for (const t of listTemplates()) {
+      console.log(`  ${t.name}`)
+    }
+    process.exitCode = 1
+    return
+  }
+
+  const jobId = randomUUID().slice(0, 8)
+  const inputText = args.slice(1).join(' ')
+  const rawContent = `---\n${Object.entries(template.frontmatter)
+    .map(([k, v]) => `${k}: ${v}`)
+    .join('\n')}\n---\n${template.content}`
+
+  const dir = createJob(
+    jobId,
+    templateName,
+    rawContent,
+    inputText,
+    args.slice(1),
+  )
+
+  console.log(`Job created: ${jobId}`)
+  console.log(`  Template: ${templateName}`)
+  console.log(`  Directory: ${dir}`)
+  if (inputText) {
+    console.log(`  Input: ${inputText}`)
+  }
+}
+
+function handleReply(args: string[]): void {
+  const jobId = args[0]
+  const text = args.slice(1).join(' ')
+
+  if (!jobId || !text) {
+    console.error('Usage: claude job reply <job-id> <text>')
+    process.exitCode = 1
+    return
+  }
+
+  const state = readJobState(jobId)
+  if (!state) {
+    console.error(`Job not found: ${jobId}`)
+    process.exitCode = 1
+    return
+  }
+
+  const ok = appendJobReply(jobId, text)
+  if (ok) {
+    console.log(`Reply added to job ${jobId}`)
+    console.log(`  Directory: ${getJobDir(jobId)}`)
+  } else {
+    console.error(`Failed to append reply to job ${jobId}`)
+    process.exitCode = 1
+  }
+}
diff --git a/src/cli/print.ts b/src/cli/print.ts
index 5f2cb308c..25d9a463f 100644
--- a/src/cli/print.ts
+++ b/src/cli/print.ts
@@ -320,6 +320,17 @@ import {
   logQueryProfileReport,
 } from 'src/utils/queryProfiler.js'
 import { asSessionId } from 'src/types/ids.js'
+import {
+  commitAutonomyQueuedPrompt,
+  createAutonomyQueuedPrompt,
+  createProactiveAutonomyCommands,
+  finalizeAutonomyRunCompleted,
+  finalizeAutonomyRunFailed,
+  markAutonomyRunCompleted,
+  markAutonomyRunFailed,
+  markAutonomyRunRunning,
+} from 'src/utils/autonomyRuns.js'
+import { prepareAutonomyTurnPrompt } from 'src/utils/autonomyAuthority.js'
 import { jsonStringify } from '../utils/slowOperations.js'
 import { skillChangeDetector } from '../utils/skills/skillChangeDetector.js'
 import { getCommands, clearCommandsCache } from '../commands.js'
@@ -362,9 +373,12 @@ const proactiveModule =
   feature('PROACTIVE') || feature('KAIROS')
     ? (require('../proactive/index.js') as typeof import('../proactive/index.js'))
     : null
-const cronSchedulerModule = require('../utils/cronScheduler.js') as typeof import('../utils/cronScheduler.js')
-const cronJitterConfigModule = require('../utils/cronJitterConfig.js') as typeof import('../utils/cronJitterConfig.js')
-const cronGate = require('@claude-code-best/builtin-tools/tools/ScheduleCronTool/prompt.js') as typeof import('@claude-code-best/builtin-tools/tools/ScheduleCronTool/prompt.js')
+const cronSchedulerModule =
+  require('../utils/cronScheduler.js') as typeof import('../utils/cronScheduler.js')
+const cronJitterConfigModule =
+  require('../utils/cronJitterConfig.js') as typeof import('../utils/cronJitterConfig.js')
+const cronGate =
+  require('@claude-code-best/builtin-tools/tools/ScheduleCronTool/prompt.js') as typeof import('@claude-code-best/builtin-tools/tools/ScheduleCronTool/prompt.js')
 const extractMemoriesModule = feature('EXTRACT_MEMORIES')
   ? (require('../services/extractMemories/extractMemories.js') as typeof import('../services/extractMemories/extractMemories.js'))
   : null
@@ -1180,7 +1194,9 @@ function runHeadlessStreaming(
     removeInterruptedMessage(mutableMessages, turnInterruptionState.message)
     enqueue({
       mode: 'prompt',
-      value: turnInterruptionState.message.message!.content as string | ContentBlockParam[],
+      value: turnInterruptionState.message.message!.content as
+        | string
+        | ContentBlockParam[],
       uuid: randomUUID(),
     })
   }
@@ -1642,7 +1658,10 @@ function runHeadlessStreaming(
         connection.config.type === 'stdio' ||
         connection.config.type === undefined
       ) {
-        const stdioConfig = connection.config as { command: string; args: string[] }
+        const stdioConfig = connection.config as {
+          command: string
+          args: string[]
+        }
         config = {
           type: 'stdio' as const,
           command: stdioConfig.command,
@@ -1804,7 +1823,8 @@ function runHeadlessStreaming(
     }
     for (const [name, config] of Object.entries(sdkMcpConfigs)) {
       if (config.type === 'sdk' && !(name in supportedConfigs)) {
-        supportedConfigs[name] = config as unknown as McpServerConfigForProcessTransport
+        supportedConfigs[name] =
+          config as unknown as McpServerConfigForProcessTransport
       }
     }
     const { response, sdkServersChanged } =
@@ -1839,15 +1859,23 @@ function runHeadlessStreaming(
             ) {
               return
             }
-            const tickContent = `<${TICK_TAG}>${new Date().toLocaleTimeString()}</${TICK_TAG}>`
-            enqueue({
-              mode: 'prompt' as const,
-              value: tickContent,
-              uuid: randomUUID(),
-              priority: 'later',
-              isMeta: true,
-            })
-            void run()
+            void (async () => {
+              const commands = await createProactiveAutonomyCommands({
+                basePrompt: `<${TICK_TAG}>${new Date().toLocaleTimeString()}</${TICK_TAG}>`,
+                currentDir: cwd(),
+                shouldCreate: () => !inputClosed,
+              })
+              for (const command of commands) {
+                if (inputClosed) {
+                  return
+                }
+                enqueue({
+                  ...command,
+                  uuid: randomUUID(),
+                })
+              }
+              void run()
+            })()
           }, 0)
         }
       : undefined
@@ -2092,6 +2120,9 @@ function runHeadlessStreaming(
           }
 
           const input = command.value
+          const autonomyRunIds = batch
+            .map(item => item.autonomy?.runId)
+            .filter((runId): runId is string => Boolean(runId))
 
           if (structuredIO instanceof RemoteIO && command.mode === 'prompt') {
             logEvent('tengu_bridge_message_received', {
@@ -2141,107 +2172,151 @@ function runHeadlessStreaming(
           // const-capture: TS loses `while ((command = dequeue()))` narrowing
           // inside the closure.
           const cmd = command
-          await runWithWorkload(cmd.workload ?? options.workload, async () => {
-            for await (const message of ask({
-              commands: uniqBy(
-                [...currentCommands, ...appState.mcp.commands],
-                'name',
-              ),
-              prompt: input,
-              promptUuid: cmd.uuid,
-              isMeta: cmd.isMeta,
-              cwd: cwd(),
-              tools: allTools,
-              verbose: options.verbose,
-              mcpClients: allMcpClients,
-              thinkingConfig: options.thinkingConfig,
-              maxTurns: options.maxTurns,
-              maxBudgetUsd: options.maxBudgetUsd,
-              taskBudget: options.taskBudget,
-              canUseTool,
-              userSpecifiedModel: activeUserSpecifiedModel,
-              fallbackModel: options.fallbackModel,
-              jsonSchema: getInitJsonSchema() ?? options.jsonSchema,
-              mutableMessages,
-              getReadFileCache: () =>
-                pendingSeeds.size === 0
-                  ? readFileState
-                  : mergeFileStateCaches(readFileState, pendingSeeds),
-              setReadFileCache: cache => {
-                readFileState = cache
-                for (const [path, seed] of pendingSeeds.entries()) {
-                  const existing = readFileState.get(path)
-                  if (!existing || seed.timestamp > existing.timestamp) {
-                    readFileState.set(path, seed)
+          for (const runId of autonomyRunIds) {
+            await markAutonomyRunRunning(runId)
+          }
+          let lastResultIsError = false
+          try {
+            await runWithWorkload(
+              cmd.workload ?? options.workload,
+              async () => {
+                for await (const message of ask({
+                  commands: uniqBy(
+                    [...currentCommands, ...appState.mcp.commands],
+                    'name',
+                  ),
+                  prompt: input,
+                  promptUuid: cmd.uuid,
+                  isMeta: cmd.isMeta,
+                  cwd: cwd(),
+                  tools: allTools,
+                  verbose: options.verbose,
+                  mcpClients: allMcpClients,
+                  thinkingConfig: options.thinkingConfig,
+                  maxTurns: options.maxTurns,
+                  maxBudgetUsd: options.maxBudgetUsd,
+                  taskBudget: options.taskBudget,
+                  canUseTool,
+                  userSpecifiedModel: activeUserSpecifiedModel,
+                  fallbackModel: options.fallbackModel,
+                  jsonSchema: getInitJsonSchema() ?? options.jsonSchema,
+                  mutableMessages,
+                  getReadFileCache: () =>
+                    pendingSeeds.size === 0
+                      ? readFileState
+                      : mergeFileStateCaches(readFileState, pendingSeeds),
+                  setReadFileCache: cache => {
+                    readFileState = cache
+                    for (const [path, seed] of pendingSeeds.entries()) {
+                      const existing = readFileState.get(path)
+                      if (!existing || seed.timestamp > existing.timestamp) {
+                        readFileState.set(path, seed)
+                      }
+                    }
+                    pendingSeeds.clear()
+                  },
+                  customSystemPrompt: options.systemPrompt,
+                  appendSystemPrompt: options.appendSystemPrompt,
+                  getAppState,
+                  setAppState,
+                  abortController,
+                  replayUserMessages: options.replayUserMessages,
+                  includePartialMessages: options.includePartialMessages,
+                  handleElicitation: (serverName, params, elicitSignal) =>
+                    structuredIO.handleElicitation(
+                      serverName,
+                      params.message,
+                      undefined,
+                      elicitSignal,
+                      params.mode,
+                      params.url,
+                      'elicitationId' in params
+                        ? params.elicitationId
+                        : undefined,
+                    ),
+                  agents: currentAgents,
+                  orphanedPermission: cmd.orphanedPermission,
+                  setSDKStatus: status => {
+                    output.enqueue({
+                      type: 'system',
+                      subtype: 'status',
+                      status: status as 'compacting' | null,
+                      session_id: getSessionId(),
+                      uuid: randomUUID(),
+                    })
+                  },
+                })) {
+                  // Forward messages to bridge incrementally (mid-turn) so
+                  // claude.ai sees progress and the connection stays alive
+                  // while blocked on permission requests.
+                  forwardMessagesToBridge()
+
+                  if (message.type === 'result') {
+                    lastResultIsError = !!(message as Record<string, unknown>)
+                      .is_error
+                    // Flush pending SDK events so they appear before result on the stream.
+                    for (const event of drainSdkEvents()) {
+                      output.enqueue(event)
+                    }
+
+                    // Hold-back: don't emit result while background agents are running
+                    const currentState = getAppState()
+                    if (
+                      getRunningTasks(currentState).some(
+                        t =>
+                          (t.type === 'local_agent' ||
+                            t.type === 'local_workflow') &&
+                          isBackgroundTask(t),
+                      )
+                    ) {
+                      heldBackResult = message as StdoutMessage
+                    } else {
+                      heldBackResult = null
+                      output.enqueue(message as StdoutMessage)
+                    }
+                  } else {
+                    // Flush SDK events (task_started, task_progress) so background
+                    // agent progress is streamed in real-time, not batched until result.
+                    for (const event of drainSdkEvents()) {
+                      output.enqueue(event)
+                    }
+                    output.enqueue(message as StdoutMessage)
                   }
                 }
-                pendingSeeds.clear()
               },
-              customSystemPrompt: options.systemPrompt,
-              appendSystemPrompt: options.appendSystemPrompt,
-              getAppState,
-              setAppState,
-              abortController,
-              replayUserMessages: options.replayUserMessages,
-              includePartialMessages: options.includePartialMessages,
-              handleElicitation: (serverName, params, elicitSignal) =>
-                structuredIO.handleElicitation(
-                  serverName,
-                  params.message,
-                  undefined,
-                  elicitSignal,
-                  params.mode,
-                  params.url,
-                  'elicitationId' in params ? params.elicitationId : undefined,
-                ),
-              agents: currentAgents,
-              orphanedPermission: cmd.orphanedPermission,
-              setSDKStatus: status => {
-                output.enqueue({
-                  type: 'system',
-                  subtype: 'status',
-                  status: status as 'compacting' | null,
-                  session_id: getSessionId(),
-                  uuid: randomUUID(),
+            ) // end runWithWorkload
+            if (lastResultIsError) {
+              for (const runId of autonomyRunIds) {
+                await finalizeAutonomyRunFailed({
+                  runId,
+                  error: 'ask() returned an error result',
                 })
-              },
-            })) {
-              // Forward messages to bridge incrementally (mid-turn) so
-              // claude.ai sees progress and the connection stays alive
-              // while blocked on permission requests.
-              forwardMessagesToBridge()
-
-              if (message.type === 'result') {
-                // Flush pending SDK events so they appear before result on the stream.
-                for (const event of drainSdkEvents()) {
-                  output.enqueue(event)
-                }
-
-                // Hold-back: don't emit result while background agents are running
-                const currentState = getAppState()
-                if (
-                  getRunningTasks(currentState).some(
-                    t =>
-                      (t.type === 'local_agent' ||
-                        t.type === 'local_workflow') &&
-                      isBackgroundTask(t),
-                  )
-                ) {
-                  heldBackResult = message as StdoutMessage
-                } else {
-                  heldBackResult = null
-                  output.enqueue(message as StdoutMessage)
-                }
-              } else {
-                // Flush SDK events (task_started, task_progress) so background
-                // agent progress is streamed in real-time, not batched until result.
-                for (const event of drainSdkEvents()) {
-                  output.enqueue(event)
+              }
+            } else {
+              for (const runId of autonomyRunIds) {
+                const nextCommands = await finalizeAutonomyRunCompleted({
+                  runId,
+                  currentDir: cwd(),
+                  priority: 'later',
+                  workload: cmd.workload ?? options.workload,
+                })
+                for (const nextCommand of nextCommands) {
+                  enqueue({
+                    ...nextCommand,
+                    uuid: randomUUID(),
+                  })
                 }
-                output.enqueue(message as StdoutMessage)
               }
             }
-          }) // end runWithWorkload
+          } catch (error) {
+            for (const runId of autonomyRunIds) {
+              await finalizeAutonomyRunFailed({
+                runId,
+                error: String(error),
+              })
+            }
+            throw error
+          }
 
           for (const uuid of batchUuids) {
             notifyCommandLifecycle(uuid, 'completed')
@@ -2253,10 +2328,15 @@ function runHeadlessStreaming(
 
           if (feature('FILE_PERSISTENCE') && turnStartTime !== undefined) {
             void executeFilePersistence(
-              { turnStartTime } as import('src/utils/filePersistence/types.js').TurnStartTime,
+              {
+                turnStartTime,
+              } as import('src/utils/filePersistence/types.js').TurnStartTime,
               abortController.signal,
               result => {
-                const filesResult = result as unknown as { persistedFiles: { filename: string; file_id: string }[]; failedFiles: { filename: string; error: string }[] }
+                const filesResult = result as unknown as {
+                  persistedFiles: { filename: string; file_id: string }[]
+                  failedFiles: { filename: string; error: string }[]
+                }
                 output.enqueue({
                   type: 'system' as const,
                   subtype: 'files_persisted' as const,
@@ -2700,28 +2780,73 @@ function runHeadlessStreaming(
   // the end of run() picks up the queued command.
   let cronScheduler: import('../utils/cronScheduler.js').CronScheduler | null =
     null
-  if (
-    cronGate.isKairosCronEnabled()
-  ) {
+  if (cronGate.isKairosCronEnabled()) {
     cronScheduler = cronSchedulerModule.createCronScheduler({
       onFire: prompt => {
         if (inputClosed) return
-        enqueue({
-          mode: 'prompt',
-          value: prompt,
-          uuid: randomUUID(),
-          priority: 'later',
-          // System-generated — matches useScheduledTasks.ts REPL equivalent.
-          // Without this, messages.ts metaProp eval is {} → prompt leaks
-          // into visible transcript when cron fires mid-turn in -p mode.
-          isMeta: true,
-          // Threaded to cc_workload= in the billing-header attribution block
-          // so the API can serve cron requests at lower QoS. drainCommandQueue
-          // reads this per-iteration and hoists it into bootstrap state for
-          // the ask() call.
-          workload: WORKLOAD_CRON,
-        })
-        void run()
+        void (async () => {
+          const prepared = await prepareAutonomyTurnPrompt({
+            basePrompt: prompt,
+            trigger: 'scheduled-task',
+            currentDir: cwd(),
+          })
+          if (inputClosed) return
+          const command = await commitAutonomyQueuedPrompt({
+            prepared,
+            currentDir: cwd(),
+            workload: WORKLOAD_CRON,
+          })
+          if (inputClosed) return
+          enqueue({
+            ...command,
+            uuid: randomUUID(),
+          })
+          void run()
+        })()
+      },
+      onFireTask: task => {
+        if (inputClosed) return
+        void (async () => {
+          if (task.agentId) {
+            const prepared = await prepareAutonomyTurnPrompt({
+              basePrompt: task.prompt,
+              trigger: 'scheduled-task',
+              currentDir: cwd(),
+            })
+            if (inputClosed) return
+            const command = await commitAutonomyQueuedPrompt({
+              prepared,
+              currentDir: cwd(),
+              sourceId: task.id,
+              sourceLabel: task.prompt,
+              workload: WORKLOAD_CRON,
+            })
+            await markAutonomyRunFailed(
+              command.autonomy!.runId,
+              `No teammate runtime available for scheduled task owner ${task.agentId} in headless mode.`,
+            )
+            return
+          }
+          const prepared = await prepareAutonomyTurnPrompt({
+            basePrompt: task.prompt,
+            trigger: 'scheduled-task',
+            currentDir: cwd(),
+          })
+          if (inputClosed) return
+          const command = await commitAutonomyQueuedPrompt({
+            prepared,
+            currentDir: cwd(),
+            sourceId: task.id,
+            sourceLabel: task.prompt,
+            workload: WORKLOAD_CRON,
+          })
+          if (inputClosed) return
+          enqueue({
+            ...command,
+            uuid: randomUUID(),
+          })
+          void run()
+        })()
       },
       isLoading: () => running || inputClosed,
       getJitterConfig: cronJitterConfigModule?.getCronJitterConfig,
@@ -2996,7 +3121,9 @@ function runHeadlessStreaming(
             sdkClient.type === 'connected' &&
             sdkClient.client?.transport?.onmessage
           ) {
-            sdkClient.client.transport.onmessage(mcpRequest.message as import('@modelcontextprotocol/sdk/types.js').JSONRPCMessage)
+            sdkClient.client.transport.onmessage(
+              mcpRequest.message as import('@modelcontextprotocol/sdk/types.js').JSONRPCMessage,
+            )
           }
           sendControlResponseSuccess(msg)
         } else if (msg.request.subtype === 'rewind_files') {
@@ -3061,7 +3188,10 @@ function runHeadlessStreaming(
           sendControlResponseSuccess(msg)
         } else if (msg.request.subtype === 'mcp_set_servers') {
           const { response, sdkServersChanged } = await applyMcpServerChanges(
-            msg.request.servers as Record<string, McpServerConfigForProcessTransport>,
+            msg.request.servers as Record<
+              string,
+              McpServerConfigForProcessTransport
+            >,
           )
           sendControlResponseSuccess(msg, response)
 
@@ -3131,7 +3261,8 @@ function runHeadlessStreaming(
                 model: a.model === 'inherit' ? undefined : a.model,
               })),
               plugins,
-              mcpServers: buildMcpServerStatuses() as SDKControlReloadPluginsResponse['mcpServers'],
+              mcpServers:
+                buildMcpServerStatuses() as SDKControlReloadPluginsResponse['mcpServers'],
               error_count: r.error_count,
             } satisfies SDKControlReloadPluginsResponse)
           } catch (error) {
@@ -3406,7 +3537,7 @@ function runHeadlessStreaming(
                     mcp: {
                       ...prev.mcp,
                       clients: prev.mcp.clients.map(c =>
-                        c.name === serverName as string ? result.client : c,
+                        c.name === (serverName as string) ? result.client : c,
                       ),
                       tools: [
                         ...reject(prev.mcp.tools, t =>
@@ -3455,7 +3586,9 @@ function runHeadlessStreaming(
                 })
                 .finally(() => {
                   // Clean up only if this is still the active flow
-                  if (activeOAuthFlows.get(serverName as string) === controller) {
+                  if (
+                    activeOAuthFlows.get(serverName as string) === controller
+                  ) {
                     activeOAuthFlows.delete(serverName as string)
                     oauthCallbackSubmitters.delete(serverName as string)
                     oauthManualCallbackUsed.delete(serverName as string)
@@ -3570,7 +3703,9 @@ function runHeadlessStreaming(
               // next API call re-reads keychain/file and works. No respawn.
               await installOAuthTokens(tokens)
               logEvent('tengu_oauth_success', {
-                loginWithClaudeAi: (loginWithClaudeAi ?? true) as boolean | number,
+                loginWithClaudeAi: (loginWithClaudeAi ?? true) as
+                  | boolean
+                  | number,
               })
             })
             .finally(() => {
@@ -3618,10 +3753,7 @@ function runHeadlessStreaming(
           req.subtype === 'claude_oauth_wait_for_completion'
         ) {
           if (!claudeOAuth) {
-            sendControlResponseError(
-              msg,
-              'No active claude_authenticate flow',
-            )
+            sendControlResponseError(msg, 'No active claude_authenticate flow')
           } else {
             // Inject the manual code synchronously — must happen in stdin
             // message order so a subsequent claude_authenticate doesn't
@@ -3681,7 +3813,7 @@ function runHeadlessStreaming(
               mcp: {
                 ...prev.mcp,
                 clients: prev.mcp.clients.map(c =>
-                  c.name === serverName as string ? result.client : c,
+                  c.name === (serverName as string) ? result.client : c,
                 ),
                 tools: [
                   ...reject(prev.mcp.tools, t => t.name?.startsWith(prefix)),
@@ -4116,9 +4248,13 @@ function runHeadlessStreaming(
         mode: 'prompt' as const,
         // file_attachments rides the protobuf catchall from the web composer.
         // Same-ref no-op when absent (no 'file_attachments' key).
-        value: await resolveAndPrepend(userMsg, (userMsg.message as { content: ContentBlockParam[] }).content),
+        value: await resolveAndPrepend(
+          userMsg,
+          (userMsg.message as { content: ContentBlockParam[] }).content,
+        ),
         uuid: userMsg.uuid as `${string}-${string}-${string}-${string}-${string}`,
-        priority: (userMsg as { priority?: string }).priority as import('src/types/textInputTypes.js').QueuePriority,
+        priority: (userMsg as { priority?: string })
+          .priority as import('src/types/textInputTypes.js').QueuePriority,
       })
       // Increment prompt count for attribution tracking and save snapshot
       // The snapshot persists promptCount so it survives compaction
@@ -4447,7 +4583,10 @@ async function handleInitializeRequest(
   const accountInfo = getAccountInformation()
   if (request.hooks) {
     const hooks: Partial<Record<HookEvent, HookCallbackMatcher[]>> = {}
-    for (const [event, matchers] of Object.entries(request.hooks) as [string, Array<{ hookCallbackIds: string[]; timeout?: number; matcher?: string }>][]) {
+    for (const [event, matchers] of Object.entries(request.hooks) as [
+      string,
+      Array<{ hookCallbackIds: string[]; timeout?: number; matcher?: string }>,
+    ][]) {
       hooks[event as HookEvent] = matchers.map(matcher => {
         const callbacks = matcher.hookCallbackIds.map(callbackId => {
           return structuredIO.createHookCallback(callbackId, matcher.timeout)
@@ -4489,7 +4628,11 @@ async function handleInitializeRequest(
       // getAccountInformation() returns undefined under 3P providers, so the
       // other fields are all absent. apiProvider disambiguates "not logged
       // in" (firstParty + tokenSource:none) from "3P, login not applicable".
-      apiProvider: getAPIProvider() as 'firstParty' | 'bedrock' | 'vertex' | 'foundry',
+      apiProvider: getAPIProvider() as
+        | 'firstParty'
+        | 'bedrock'
+        | 'vertex'
+        | 'foundry',
     },
     pid: process.pid,
   }
@@ -4537,7 +4680,11 @@ async function handleRewindFiles(
   dryRun: boolean,
 ): Promise<RewindFilesResult> {
   if (!fileHistoryEnabled()) {
-    return { canRewind: false, error: 'File rewinding is not enabled.', filesChanged: [] }
+    return {
+      canRewind: false,
+      error: 'File rewinding is not enabled.',
+      filesChanged: [],
+    }
   }
   if (!fileHistoryCanRestore(appState.fileHistory, userMessageId)) {
     return {
@@ -4842,7 +4989,10 @@ function reregisterChannelHandlerAfterReconnect(
         value: wrapChannelMessage(connection.name, content, meta),
         priority: 'next',
         isMeta: true,
-        origin: { kind: 'channel', server: connection.name } as unknown as string,
+        origin: {
+          kind: 'channel',
+          server: connection.name,
+        } as unknown as string,
         skipSlashCommands: true,
       })
     },
@@ -5266,13 +5416,21 @@ export async function handleOrphanedPermissionResponse({
   onEnqueued?: () => void
   handledToolUseIds: Set<string>
 }): Promise<boolean> {
-  const responseInner = message.response as { subtype?: string; response?: Record<string, unknown>; request_id?: string } | undefined
+  const responseInner = message.response as
+    | {
+        subtype?: string
+        response?: Record<string, unknown>
+        request_id?: string
+      }
+    | undefined
   if (
     responseInner?.subtype === 'success' &&
     responseInner.response?.toolUseID &&
     typeof responseInner.response.toolUseID === 'string'
   ) {
-    const permissionResult = responseInner.response as PermissionResult & { toolUseID?: string }
+    const permissionResult = responseInner.response as PermissionResult & {
+      toolUseID?: string
+    }
     const toolUseID = permissionResult.toolUseID
     if (!toolUseID) {
       return false
diff --git a/src/cli/rollback.ts b/src/cli/rollback.ts
index c93ab4124..82293f0a7 100644
--- a/src/cli/rollback.ts
+++ b/src/cli/rollback.ts
@@ -1,2 +1,70 @@
-// Auto-generated stub
-export async function rollback(target?: string, options?: { list?: boolean; dryRun?: boolean; safe?: boolean }): Promise<void> {}
+/**
+ * `claude rollback [target]` — roll back to a previous Claude Code version.
+ *
+ * ANT-only command (USER_TYPE === "ant").
+ *
+ * Options:
+ *   --list      List recent published versions
+ *   --dry-run   Show what would be installed without installing
+ *   --safe      Roll back to the server-pinned safe version
+ */
+export async function rollback(
+  target?: string,
+  options?: { list?: boolean; dryRun?: boolean; safe?: boolean },
+): Promise<void> {
+  if (options?.list) {
+    console.log('Recent versions:')
+    console.log('  (version listing requires access to the release registry)')
+    console.log('  Use `claude update --list` for available versions.')
+    return
+  }
+
+  if (options?.safe) {
+    console.log('Safe rollback: would install the server-pinned safe version.')
+    if (options.dryRun) {
+      console.log('  (dry run — no changes made)')
+      return
+    }
+    console.log('  Safe version pinning requires access to the release API.')
+    console.log('  Contact oncall for the current safe version.')
+    return
+  }
+
+  if (!target) {
+    console.error(
+      'Usage: claude rollback [target]\n\n' +
+        'Options:\n' +
+        '  -l, --list     List recent published versions\n' +
+        '  --dry-run      Show what would be installed\n' +
+        '  --safe         Roll back to server-pinned safe version\n\n' +
+        'Examples:\n' +
+        '  claude rollback 2.1.880\n' +
+        '  claude rollback --list\n' +
+        '  claude rollback --safe',
+    )
+    process.exitCode = 1
+    return
+  }
+
+  console.log(`Rolling back to version ${target}...`)
+
+  if (options?.dryRun) {
+    console.log(`  (dry run — would install ${target})`)
+    return
+  }
+
+  // Version rollback via npm/bun
+  const { spawnSync } = await import('child_process')
+  const result = spawnSync(
+    'npm',
+    ['install', '-g', `@anthropic-ai/claude-code@${target}`],
+    { stdio: 'inherit' },
+  )
+
+  if (result.status !== 0) {
+    console.error(`Rollback failed with exit code ${result.status}`)
+    process.exitCode = result.status ?? 1
+  } else {
+    console.log(`Rolled back to ${target} successfully.`)
+  }
+}
diff --git a/src/cli/up.ts b/src/cli/up.ts
index d75966c1d..1a7384746 100644
--- a/src/cli/up.ts
+++ b/src/cli/up.ts
@@ -1,2 +1,95 @@
-// Auto-generated stub
-export async function up(): Promise<void> {}
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import { spawnSync } from 'child_process'
+import { findGitRoot } from '../utils/git.js'
+
+/**
+ * `claude up` — run the "# claude up" section from the nearest CLAUDE.md.
+ *
+ * Walks up from CWD looking for CLAUDE.md files, extracts the section
+ * under the `# claude up` heading, and executes it as a shell script.
+ *
+ * ANT-only command (USER_TYPE === "ant").
+ */
+export async function up(): Promise<void> {
+  const cwd = process.cwd()
+  const gitRoot = findGitRoot(cwd)
+  const searchDirs = gitRoot ? [gitRoot, cwd] : [cwd]
+
+  let upSection: string | null = null
+
+  for (const dir of searchDirs) {
+    const claudeMdPath = join(dir, 'CLAUDE.md')
+    try {
+      const content = readFileSync(claudeMdPath, 'utf-8')
+      upSection = extractUpSection(content)
+      if (upSection) {
+        console.log(`Found "# claude up" in ${claudeMdPath}`)
+        break
+      }
+    } catch {
+      // File not found — continue searching
+    }
+  }
+
+  if (!upSection) {
+    console.log(
+      'No "# claude up" section found in CLAUDE.md.\n' +
+        'Add a section like:\n\n' +
+        '  # claude up\n' +
+        '  ```bash\n' +
+        '  npm install\n' +
+        '  npm run build\n' +
+        '  ```',
+    )
+    return
+  }
+
+  console.log('Running:\n')
+  console.log(upSection)
+  console.log()
+
+  const result = spawnSync('bash', ['-c', upSection], {
+    cwd,
+    stdio: 'inherit',
+  })
+
+  if (result.status !== 0) {
+    console.error(`\nclaude up failed with exit code ${result.status}`)
+    process.exitCode = result.status ?? 1
+  } else {
+    console.log('\nclaude up completed successfully.')
+  }
+}
+
+/**
+ * Extract the content under "# claude up" heading from markdown.
+ * Returns the text between `# claude up` and the next `#` heading (or EOF).
+ * Strips fenced code block markers if present.
+ */
+function extractUpSection(markdown: string): string | null {
+  const lines = markdown.split('\n')
+  let inSection = false
+  const sectionLines: string[] = []
+
+  for (const line of lines) {
+    if (/^#\s+claude\s+up\b/i.test(line)) {
+      inSection = true
+      continue
+    }
+    if (inSection && /^#\s/.test(line)) {
+      break
+    }
+    if (inSection) {
+      sectionLines.push(line)
+    }
+  }
+
+  if (sectionLines.length === 0) return null
+
+  // Strip fenced code block markers
+  let text = sectionLines.join('\n').trim()
+  text = text.replace(/^```\w*\n?/, '').replace(/\n?```\s*$/, '')
+
+  return text.trim() || null
+}
diff --git a/src/commands.ts b/src/commands.ts
index 3d5847eb4..2f11c638a 100644
--- a/src/commands.ts
+++ b/src/commands.ts
@@ -25,6 +25,7 @@ import ide from './commands/ide/index.js'
 import init from './commands/init.js'
 import initVerifiers from './commands/init-verifiers.js'
 import keybindings from './commands/keybindings/index.js'
+import lang from './commands/lang/index.js'
 import login from './commands/login/index.js'
 import logout from './commands/logout/index.js'
 import installGitHubApp from './commands/install-github-app/index.js'
@@ -111,6 +112,13 @@ const ultraplan = feature('ULTRAPLAN')
   ? require('./commands/ultraplan.js').default
   : null
 const torch = feature('TORCH') ? require('./commands/torch.js').default : null
+const daemonCmd =
+  feature('DAEMON') || feature('BG_SESSIONS')
+    ? require('./commands/daemon/index.js').default
+    : null
+const jobCmd = feature('TEMPLATES')
+  ? require('./commands/job/index.js').default
+  : null
 const peersCmd = feature('UDS_INBOX')
   ? (
       require('./commands/peers/index.js') as typeof import('./commands/peers/index.js')
@@ -182,6 +190,7 @@ import sandboxToggle from './commands/sandbox-toggle/index.js'
 import chrome from './commands/chrome/index.js'
 import stickers from './commands/stickers/index.js'
 import advisor from './commands/advisor.js'
+import autonomy from './commands/autonomy.js'
 import provider from './commands/provider.js'
 import { logError } from './utils/log.js'
 import { toError } from './utils/errors.js'
@@ -290,6 +299,7 @@ export const INTERNAL_ONLY_COMMANDS = [
 const COMMANDS = memoize((): Command[] => [
   addDir,
   advisor,
+  autonomy,
   provider,
   agents,
   branch,
@@ -315,6 +325,7 @@ const COMMANDS = memoize((): Command[] => [
   ide,
   init,
   keybindings,
+  lang,
   installGitHubApp,
   installSlackApp,
   mcp,
@@ -384,6 +395,8 @@ const COMMANDS = memoize((): Command[] => [
   ...(workflowsCmd ? [workflowsCmd] : []),
   ...(ultraplan ? [ultraplan] : []),
   ...(torch ? [torch] : []),
+  ...(daemonCmd ? [daemonCmd] : []),
+  ...(jobCmd ? [jobCmd] : []),
   ...(process.env.USER_TYPE === 'ant' && !process.env.IS_DEMO
     ? INTERNAL_ONLY_COMMANDS
     : []),
diff --git a/src/commands/__tests__/autonomy.test.ts b/src/commands/__tests__/autonomy.test.ts
new file mode 100644
index 000000000..8b36670ce
--- /dev/null
+++ b/src/commands/__tests__/autonomy.test.ts
@@ -0,0 +1,246 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import autonomyCommand from '../autonomy'
+import type { LocalCommandResult } from '../../types/command'
+import {
+  resetStateForTests,
+  setOriginalCwd,
+  setProjectRoot,
+} from '../../bootstrap/state'
+
+function expectTextResult(
+  result: LocalCommandResult,
+): asserts result is Extract<LocalCommandResult, { type: 'text' }> {
+  if (result.type !== 'text')
+    throw new Error(`Expected text result, got ${result.type}`)
+}
+import { listAutonomyFlows } from '../../utils/autonomyFlows'
+import {
+  createAutonomyQueuedPrompt,
+  markAutonomyRunCompleted,
+  startManagedAutonomyFlowFromHeartbeatTask,
+} from '../../utils/autonomyRuns'
+import {
+  enqueuePendingNotification,
+  getCommandQueueSnapshot,
+  resetCommandQueue,
+} from '../../utils/messageQueueManager'
+import { cleanupTempDir, createTempDir } from '../../../tests/mocks/file-system'
+
+let tempDir = ''
+
+beforeEach(async () => {
+  tempDir = await createTempDir('autonomy-command-')
+  resetStateForTests()
+  resetCommandQueue()
+  setOriginalCwd(tempDir)
+  setProjectRoot(tempDir)
+})
+
+afterEach(async () => {
+  resetStateForTests()
+  resetCommandQueue()
+  if (tempDir) {
+    await cleanupTempDir(tempDir)
+  }
+})
+
+describe('/autonomy', () => {
+  test('status reports autonomy runs and managed flows separately', async () => {
+    const plainRun = await createAutonomyQueuedPrompt({
+      basePrompt: 'scheduled prompt',
+      trigger: 'scheduled-task',
+      rootDir: tempDir,
+      currentDir: tempDir,
+      sourceLabel: 'nightly',
+    })
+    expect(plainRun).not.toBeNull()
+    await markAutonomyRunCompleted(plainRun!.autonomy!.runId, tempDir)
+
+    await startManagedAutonomyFlowFromHeartbeatTask({
+      task: {
+        name: 'weekly-report',
+        interval: '7d',
+        prompt: 'Ship the weekly report',
+        steps: [
+          {
+            name: 'gather',
+            prompt: 'Gather weekly inputs',
+          },
+          {
+            name: 'draft',
+            prompt: 'Draft the weekly report',
+          },
+        ],
+      },
+      rootDir: tempDir,
+      currentDir: tempDir,
+    })
+
+    const mod = await autonomyCommand.load()
+    const result = await mod.call('', {} as any)
+
+    expectTextResult(result)
+    expect(result.value).toContain('Autonomy runs: 2')
+    expect(result.value).toContain('Autonomy flows: 1')
+    expect(result.value).toContain('Completed: 1')
+    expect(result.value).toContain('Queued: 1')
+  })
+
+  test('runs subcommand lists recent autonomy runs', async () => {
+    const queued = await createAutonomyQueuedPrompt({
+      basePrompt: '<tick>12:00:00</tick>',
+      trigger: 'proactive-tick',
+      rootDir: tempDir,
+      currentDir: tempDir,
+    })
+
+    const mod = await autonomyCommand.load()
+    const result = await mod.call('runs 5', {} as any)
+
+    expectTextResult(result)
+    expect(result.value).toContain(queued!.autonomy!.runId)
+    expect(result.value).toContain('proactive-tick')
+  })
+
+  test('flows subcommand lists managed flows and flow subcommand shows detail', async () => {
+    await startManagedAutonomyFlowFromHeartbeatTask({
+      task: {
+        name: 'weekly-report',
+        interval: '7d',
+        prompt: 'Ship the weekly report',
+        steps: [
+          {
+            name: 'gather',
+            prompt: 'Gather weekly inputs',
+          },
+          {
+            name: 'draft',
+            prompt: 'Draft the weekly report',
+          },
+        ],
+      },
+      rootDir: tempDir,
+      currentDir: tempDir,
+    })
+
+    const [flow] = await listAutonomyFlows(tempDir)
+    const mod = await autonomyCommand.load()
+
+    const flowsResult = await mod.call('flows 5', {} as any)
+    expectTextResult(flowsResult)
+    expect(flowsResult.value).toContain(flow!.flowId)
+    expect(flowsResult.value).toContain('managed')
+
+    const flowResult = await mod.call(`flow ${flow!.flowId}`, {} as any)
+    expectTextResult(flowResult)
+    expect(flowResult.value).toContain(`Flow: ${flow!.flowId}`)
+    expect(flowResult.value).toContain('Mode: managed')
+    expect(flowResult.value).toContain('Current step: gather')
+  })
+
+  test('flow resume queues the next waiting step', async () => {
+    const waitingStart = await startManagedAutonomyFlowFromHeartbeatTask({
+      task: {
+        name: 'weekly-report',
+        interval: '7d',
+        prompt: 'Ship the weekly report',
+        steps: [
+          {
+            name: 'gather',
+            prompt: 'Gather weekly inputs',
+            waitFor: 'manual',
+          },
+          {
+            name: 'draft',
+            prompt: 'Draft the weekly report',
+          },
+        ],
+      },
+      rootDir: tempDir,
+      currentDir: tempDir,
+    })
+
+    expect(waitingStart).toBeNull()
+    const [flow] = await listAutonomyFlows(tempDir)
+
+    const mod = await autonomyCommand.load()
+    const result = await mod.call(`flow resume ${flow!.flowId}`, {} as any)
+
+    expectTextResult(result)
+    expect(result.value).toContain('Queued the next managed step')
+    expect(getCommandQueueSnapshot()).toHaveLength(1)
+    expect(getCommandQueueSnapshot()[0]!.autonomy?.flowId).toBe(flow!.flowId)
+  })
+
+  test('flow cancel removes queued managed steps and marks the flow cancelled', async () => {
+    const queued = await startManagedAutonomyFlowFromHeartbeatTask({
+      task: {
+        name: 'weekly-report',
+        interval: '7d',
+        prompt: 'Ship the weekly report',
+        steps: [
+          {
+            name: 'gather',
+            prompt: 'Gather weekly inputs',
+          },
+          {
+            name: 'draft',
+            prompt: 'Draft the weekly report',
+          },
+        ],
+      },
+      rootDir: tempDir,
+      currentDir: tempDir,
+    })
+
+    expect(queued).not.toBeNull()
+    enqueuePendingNotification(queued!)
+    expect(getCommandQueueSnapshot()).toHaveLength(1)
+    const [flow] = await listAutonomyFlows(tempDir)
+    const mod = await autonomyCommand.load()
+    const result = await mod.call(`flow cancel ${flow!.flowId}`, {} as any)
+    const [cancelledFlow] = await listAutonomyFlows(tempDir)
+
+    expectTextResult(result)
+    expect(result.value).toContain('Cancelled flow')
+    expect(cancelledFlow!.status).toBe('cancelled')
+    expect(getCommandQueueSnapshot()).toHaveLength(0)
+  })
+
+  test('flow cancel refuses to rewrite a terminal managed flow', async () => {
+    const queued = await startManagedAutonomyFlowFromHeartbeatTask({
+      task: {
+        name: 'weekly-report',
+        interval: '7d',
+        prompt: 'Ship the weekly report',
+        steps: [
+          {
+            name: 'gather',
+            prompt: 'Gather weekly inputs',
+          },
+        ],
+      },
+      rootDir: tempDir,
+      currentDir: tempDir,
+    })
+
+    await markAutonomyRunCompleted(queued!.autonomy!.runId, tempDir)
+
+    const [flow] = await listAutonomyFlows(tempDir)
+    const mod = await autonomyCommand.load()
+    const result = await mod.call(`flow cancel ${flow!.flowId}`, {} as any)
+    const [terminalFlow] = await listAutonomyFlows(tempDir)
+
+    expectTextResult(result)
+    expect(result.value).toContain('already terminal')
+    expect(terminalFlow!.status).toBe('succeeded')
+  })
+
+  test('invalid subcommands return usage text', async () => {
+    const mod = await autonomyCommand.load()
+    const result = await mod.call('unknown', {} as any)
+
+    expectTextResult(result)
+    expect(result.value).toContain('Usage: /autonomy')
+  })
+})
diff --git a/src/commands/__tests__/proactive.baseline.test.ts b/src/commands/__tests__/proactive.baseline.test.ts
new file mode 100644
index 000000000..0c349b5fa
--- /dev/null
+++ b/src/commands/__tests__/proactive.baseline.test.ts
@@ -0,0 +1,48 @@
+import { beforeEach, describe, expect, test } from 'bun:test'
+import proactiveCommand from '../proactive'
+import {
+  activateProactive,
+  deactivateProactive,
+  isProactiveActive,
+} from '../../proactive/index'
+
+beforeEach(() => {
+  deactivateProactive()
+})
+
+describe('/proactive baseline', () => {
+  test('invoking the command enables proactive mode and emits a system reminder', async () => {
+    const mod = await proactiveCommand.load()
+    let resultText: string | undefined
+    let options: Parameters<Parameters<typeof mod.call>[0]>[1] | undefined
+
+    await mod.call((result, opts) => {
+      resultText = result
+      options = opts
+    }, {} as any)
+
+    expect(isProactiveActive()).toBe(true)
+    expect(resultText).toContain('Proactive mode enabled')
+    expect(options?.display).toBe('system')
+    expect(options?.metaMessages?.[0]).toContain(
+      'Proactive mode is now enabled',
+    )
+  })
+
+  test('invoking the command again disables proactive mode', async () => {
+    const mod = await proactiveCommand.load()
+    activateProactive('test')
+
+    let resultText: string | undefined
+    let options: Parameters<Parameters<typeof mod.call>[0]>[1] | undefined
+
+    await mod.call((result, opts) => {
+      resultText = result
+      options = opts
+    }, {} as any)
+
+    expect(isProactiveActive()).toBe(false)
+    expect(resultText).toBe('Proactive mode disabled')
+    expect(options?.display).toBe('system')
+  })
+})
diff --git a/src/commands/assistant/assistant.ts b/src/commands/assistant/assistant.ts
deleted file mode 100644
index 7234e0ac8..000000000
--- a/src/commands/assistant/assistant.ts
+++ /dev/null
@@ -1,53 +0,0 @@
-import * as React from 'react'
-import type { LocalJSXCommandContext } from '../../commands.js'
-import type { LocalJSXCommandOnDone } from '../../types/command.js'
-import type { AppState } from '../../state/AppState.js'
-
-/** Stub — install wizard is not yet restored. */
-export async function computeDefaultInstallDir(): Promise<string> {
-  return ''
-}
-
-/** Stub — install wizard is not yet restored. */
-export function NewInstallWizard(_props: {
-  defaultDir: string
-  onInstalled: (dir: string) => void
-  onCancel: () => void
-  onError: (message: string) => void
-}): React.ReactNode {
-  return null
-}
-
-/**
- * /assistant command implementation.
- *
- * Opens the Kairos assistant panel. In the current build the panel is
- * rendered by the REPL layer when kairosActive is true; the slash command
- * simply toggles visibility and prints a confirmation line.
- */
-export async function call(
-  onDone: LocalJSXCommandOnDone,
-  context: LocalJSXCommandContext,
-  _args: string,
-): Promise<React.ReactNode> {
-  const { setAppState, getAppState } = context
-
-  const current = getAppState()
-  const isVisible = (current as Record<string, unknown>).assistantPanelVisible
-
-  if (isVisible) {
-    setAppState((prev: AppState) => ({
-      ...prev,
-      assistantPanelVisible: false,
-    } as AppState))
-    onDone('Assistant panel hidden.', { display: 'system' })
-  } else {
-    setAppState((prev: AppState) => ({
-      ...prev,
-      assistantPanelVisible: true,
-    } as AppState))
-    onDone('Assistant panel opened.', { display: 'system' })
-  }
-
-  return null
-}
diff --git a/src/commands/assistant/assistant.tsx b/src/commands/assistant/assistant.tsx
new file mode 100644
index 000000000..91f75542a
--- /dev/null
+++ b/src/commands/assistant/assistant.tsx
@@ -0,0 +1,175 @@
+import * as React from 'react';
+import { useEffect, useState } from 'react';
+import { resolve } from 'path';
+import { Box, Text } from '@anthropic/ink';
+import { Dialog } from '../../components/design-system/Dialog.js';
+import { ListItem } from '../../components/design-system/ListItem.js';
+import { useRegisterOverlay } from '../../context/overlayContext.js';
+import { useKeybindings } from '../../keybindings/useKeybinding.js';
+import { findGitRoot } from '../../utils/git.js';
+import { buildCliLaunch, spawnCli } from '../../utils/cliLaunch.js';
+import { getKairosActive, setKairosActive } from '../../bootstrap/state.js';
+import type { LocalJSXCommandContext } from '../../commands.js';
+import type { LocalJSXCommandOnDone } from '../../types/command.js';
+import type { AppState } from '../../state/AppState.js';
+
+/**
+ * Compute the default directory for assistant daemon installation.
+ * Prefers git root of cwd; falls back to cwd itself.
+ */
+export async function computeDefaultInstallDir(): Promise<string> {
+  const cwd = process.cwd();
+  const gitRoot = findGitRoot(cwd);
+  return gitRoot || resolve(cwd);
+}
+
+interface WizardProps {
+  defaultDir: string;
+  onInstalled: (dir: string) => void;
+  onCancel: () => void;
+  onError: (message: string) => void;
+}
+
+/**
+ * Install wizard for assistant mode. Shown when `claude assistant` finds
+ * zero CCR sessions. Guides the user to start a daemon that registers
+ * a bridge → CCR cloud session.
+ *
+ * After installation, main.tsx tells the user to run `claude assistant`
+ * again in a few seconds (daemon needs time to register the bridge session).
+ */
+export function NewInstallWizard({ defaultDir, onInstalled, onCancel, onError }: WizardProps): React.ReactNode {
+  useRegisterOverlay('assistant-install-wizard');
+  const [focusIndex, setFocusIndex] = useState(0);
+  const [starting, setStarting] = useState(false);
+
+  useKeybindings(
+    {
+      'select:next': () => setFocusIndex(i => (i + 1) % 2),
+      'select:previous': () => setFocusIndex(i => (i - 1 + 2) % 2),
+      'select:accept': () => {
+        if (focusIndex === 0) {
+          startDaemon();
+        } else {
+          onCancel();
+        }
+      },
+    },
+    { context: 'Select' },
+  );
+
+  function startDaemon(): void {
+    if (starting) return;
+    setStarting(true);
+
+    const dir = defaultDir || resolve('.');
+
+    try {
+      const launch = buildCliLaunch(['daemon', 'start', `--dir=${dir}`]);
+
+      const child = spawnCli(launch, {
+        cwd: dir,
+        stdio: 'ignore',
+        detached: true,
+      });
+
+      child.unref();
+
+      child.on('error', err => {
+        onError(`Failed to start daemon: ${err.message}`);
+      });
+
+      // Give the daemon a moment to initialize, then report success.
+      // The daemon still needs several more seconds to register the bridge
+      // and create a CCR session — main.tsx will tell the user to reconnect.
+      setTimeout(() => {
+        onInstalled(dir);
+      }, 1500);
+    } catch (err) {
+      onError(`Failed to start daemon: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  if (starting) {
+    return (
+      <Dialog title="Assistant Setup" onCancel={onCancel} hideInputGuide>
+        <Text>Starting daemon in {defaultDir}...</Text>
+      </Dialog>
+    );
+  }
+
+  return (
+    <Dialog title="Assistant Setup" onCancel={onCancel} hideInputGuide>
+      <Box flexDirection="column" gap={1}>
+        <Text>No active assistant sessions found.</Text>
+        <Text>
+          Start a daemon in <Text bold>{defaultDir || '.'}</Text> to create a cloud session?
+        </Text>
+        <Box flexDirection="column">
+          <ListItem isFocused={focusIndex === 0}>
+            <Text>Start assistant daemon</Text>
+          </ListItem>
+          <ListItem isFocused={focusIndex === 1}>
+            <Text>Cancel</Text>
+          </ListItem>
+        </Box>
+        <Text dimColor>Enter to select · Esc to cancel</Text>
+      </Box>
+    </Dialog>
+  );
+}
+
+/**
+ * /assistant command implementation.
+ *
+ * First invocation activates KAIROS (sets kairosActive, enables brief
+ * and proactive tools). Subsequent invocations toggle the assistant panel.
+ */
+export async function call(
+  onDone: LocalJSXCommandOnDone,
+  context: LocalJSXCommandContext,
+  _args: string,
+): Promise<React.ReactNode> {
+  const { setAppState, getAppState } = context;
+
+  // First invocation: activate KAIROS
+  if (!getKairosActive()) {
+    setKairosActive(true);
+    setAppState(
+      (prev: AppState) =>
+        ({
+          ...prev,
+          kairosEnabled: true,
+          assistantPanelVisible: true,
+        }) as AppState,
+    );
+    onDone('KAIROS assistant mode activated.', { display: 'system' });
+    return null;
+  }
+
+  // Subsequent invocations: toggle panel visibility
+  const current = getAppState();
+  const isVisible = (current as Record<string, unknown>).assistantPanelVisible;
+
+  if (isVisible) {
+    setAppState(
+      (prev: AppState) =>
+        ({
+          ...prev,
+          assistantPanelVisible: false,
+        }) as AppState,
+    );
+    onDone('Assistant panel hidden.', { display: 'system' });
+  } else {
+    setAppState(
+      (prev: AppState) =>
+        ({
+          ...prev,
+          assistantPanelVisible: true,
+        }) as AppState,
+    );
+    onDone('Assistant panel opened.', { display: 'system' });
+  }
+
+  return null;
+}
diff --git a/src/commands/assistant/gate.ts b/src/commands/assistant/gate.ts
index 0bf42b1f5..148a556a8 100644
--- a/src/commands/assistant/gate.ts
+++ b/src/commands/assistant/gate.ts
@@ -1,25 +1,21 @@
 import { feature } from 'bun:bundle'
-import { getKairosActive } from '../../bootstrap/state.js'
 import { getFeatureValue_CACHED_MAY_BE_STALE } from '../../services/analytics/growthbook.js'
 
 /**
- * Runtime gate for the /assistant command.
+ * Runtime gate for the /assistant command visibility.
  *
- * Build-time: feature('KAIROS') must be on (checked in commands.ts before
- * the module is even required).
+ * Build-time: feature('KAIROS') must be on.
+ * Runtime: tengu_kairos_assistant GrowthBook flag (remote kill switch).
  *
- * Runtime: tengu_kairos_assistant GrowthBook flag acts as a remote kill
- * switch, and kairosActive state must be true (set during bootstrap when
- * the session qualifies for KAIROS features).
+ * Does NOT require kairosActive — the /assistant command is visible
+ * before activation so users can invoke it to activate KAIROS.
  */
 export function isAssistantEnabled(): boolean {
   if (!feature('KAIROS')) {
     return false
   }
-  if (
-    !getFeatureValue_CACHED_MAY_BE_STALE('tengu_kairos_assistant', false)
-  ) {
+  if (!getFeatureValue_CACHED_MAY_BE_STALE('tengu_kairos_assistant', false)) {
     return false
   }
-  return getKairosActive()
+  return true
 }
diff --git a/src/commands/autonomy.ts b/src/commands/autonomy.ts
new file mode 100644
index 000000000..c387fb850
--- /dev/null
+++ b/src/commands/autonomy.ts
@@ -0,0 +1,125 @@
+import type { Command, LocalCommandCall } from '../types/command.js'
+import {
+  formatAutonomyFlowDetail,
+  formatAutonomyFlowsList,
+  formatAutonomyFlowsStatus,
+  getAutonomyFlowById,
+  listAutonomyFlows,
+  requestManagedAutonomyFlowCancel,
+} from '../utils/autonomyFlows.js'
+import {
+  formatAutonomyRunsList,
+  formatAutonomyRunsStatus,
+  listAutonomyRuns,
+  markAutonomyRunCancelled,
+  resumeManagedAutonomyFlowPrompt,
+} from '../utils/autonomyRuns.js'
+import {
+  enqueuePendingNotification,
+  removeByFilter,
+} from '../utils/messageQueueManager.js'
+
+function parseRunsLimit(raw?: string): number {
+  const parsed = Number.parseInt(raw ?? '', 10)
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return 10
+  }
+  return Math.min(parsed, 50)
+}
+
+const call: LocalCommandCall = async (args: string) => {
+  const [subcommand = 'status', arg1, arg2] = args.trim().split(/\s+/, 3)
+  const runs = await listAutonomyRuns()
+  const flows = await listAutonomyFlows()
+
+  if (subcommand === 'runs') {
+    return {
+      type: 'text',
+      value: formatAutonomyRunsList(runs, parseRunsLimit(arg1)),
+    }
+  }
+
+  if (subcommand === 'flows') {
+    return {
+      type: 'text',
+      value: formatAutonomyFlowsList(flows, parseRunsLimit(arg1)),
+    }
+  }
+
+  if (subcommand === 'flow') {
+    if (arg1 === 'cancel') {
+      const flowId = arg2 ?? ''
+      const cancelled = await requestManagedAutonomyFlowCancel({ flowId })
+      if (!cancelled) {
+        return {
+          type: 'text',
+          value: 'Autonomy flow not found.',
+        }
+      }
+      if (!cancelled.accepted) {
+        return {
+          type: 'text',
+          value: `Autonomy flow ${flowId} is already terminal (${cancelled.flow.status}).`,
+        }
+      }
+      const removed = removeByFilter(cmd => cmd.autonomy?.flowId === flowId)
+      for (const command of removed) {
+        if (command.autonomy?.runId) {
+          await markAutonomyRunCancelled(command.autonomy.runId)
+        }
+      }
+      return {
+        type: 'text',
+        value:
+          cancelled.flow.status === 'running'
+            ? `Cancellation requested for flow ${flowId}. The current step is still running, and no new steps will be started.`
+            : `Cancelled flow ${flowId}. Removed ${removed.length} queued step(s).`,
+      }
+    }
+
+    if (arg1 === 'resume') {
+      const flowId = arg2 ?? ''
+      const command = await resumeManagedAutonomyFlowPrompt({ flowId })
+      if (!command) {
+        return {
+          type: 'text',
+          value: 'Autonomy flow is not waiting or was not found.',
+        }
+      }
+      enqueuePendingNotification(command)
+      return {
+        type: 'text',
+        value: `Queued the next managed step for flow ${flowId}.`,
+      }
+    }
+
+    return {
+      type: 'text',
+      value: formatAutonomyFlowDetail(await getAutonomyFlowById(arg1 ?? '')),
+    }
+  }
+
+  if (subcommand !== 'status' && subcommand !== '') {
+    return {
+      type: 'text',
+      value:
+        'Usage: /autonomy [status|runs [limit]|flows [limit]|flow <id>|flow cancel <id>|flow resume <id>]',
+    }
+  }
+
+  return {
+    type: 'text',
+    value: [formatAutonomyRunsStatus(runs), formatAutonomyFlowsStatus(flows)].join('\n'),
+  }
+}
+
+const autonomy = {
+  type: 'local',
+  name: 'autonomy',
+  description:
+    'Inspect automatic autonomy runs recorded for proactive ticks and scheduled tasks',
+  supportsNonInteractive: true,
+  load: () => Promise.resolve({ call }),
+} satisfies Command
+
+export default autonomy
diff --git a/src/commands/daemon/__tests__/daemon.test.ts b/src/commands/daemon/__tests__/daemon.test.ts
new file mode 100644
index 000000000..1e578f41d
--- /dev/null
+++ b/src/commands/daemon/__tests__/daemon.test.ts
@@ -0,0 +1,24 @@
+import { describe, test, expect } from 'bun:test'
+
+describe('/daemon command', () => {
+  test('index exports a valid Command', async () => {
+    const mod = await import('../index.js')
+    const cmd = mod.default
+    expect(cmd.name).toBe('daemon')
+    expect(cmd.type).toBe('local-jsx')
+    expect(typeof cmd.load).toBe('function')
+    expect(cmd.description).toContain('daemon')
+  })
+
+  test('daemon module exports call function', async () => {
+    const mod = await import('../daemon.js')
+    expect(typeof mod.call).toBe('function')
+  })
+
+  test('argumentHint lists subcommands', async () => {
+    const mod = await import('../index.js')
+    const cmd = mod.default
+    expect(cmd.argumentHint).toContain('status')
+    expect(cmd.argumentHint).toContain('bg')
+  })
+})
diff --git a/src/commands/daemon/daemon.tsx b/src/commands/daemon/daemon.tsx
new file mode 100644
index 000000000..b72cc3c7a
--- /dev/null
+++ b/src/commands/daemon/daemon.tsx
@@ -0,0 +1,57 @@
+import type {
+  LocalJSXCommandOnDone,
+  LocalJSXCommandContext,
+} from '../../types/command.js'
+
+/**
+ * /daemon slash command — manages daemon and background sessions from the REPL.
+ *
+ * Subcommands: status | start | stop | bg | attach | logs | kill
+ * Default (no args): status
+ */
+export async function call(
+  onDone: LocalJSXCommandOnDone,
+  _context: LocalJSXCommandContext,
+  args: string,
+): Promise<React.ReactNode> {
+  const parts = args ? args.trim().split(/\s+/) : []
+  const sub = parts[0] || 'status'
+
+  // attach is interactive/blocking — not available inside the REPL
+  if (sub === 'attach') {
+    onDone(
+      'Use `claude daemon attach` from the CLI. Attach is not available inside the REPL.',
+      { display: 'system' },
+    )
+    return null
+  }
+
+  // For all other subcommands, capture console output and return via onDone
+  const lines = await captureConsole(async () => {
+    if (sub === 'bg') {
+      const bg = await import('../../cli/bg.js')
+      await bg.handleBgStart(parts.slice(1))
+    } else {
+      const { daemonMain } = await import('../../daemon/main.js')
+      await daemonMain([sub, ...parts.slice(1)])
+    }
+  })
+
+  onDone(lines.join('\n') || 'Done.', { display: 'system' })
+  return null
+}
+
+async function captureConsole(fn: () => Promise<void>): Promise<string[]> {
+  const lines: string[] = []
+  const origLog = console.log
+  const origError = console.error
+  console.log = (...a: unknown[]) => lines.push(a.map(String).join(' '))
+  console.error = (...a: unknown[]) => lines.push(a.map(String).join(' '))
+  try {
+    await fn()
+  } finally {
+    console.log = origLog
+    console.error = origError
+  }
+  return lines
+}
diff --git a/src/commands/daemon/index.ts b/src/commands/daemon/index.ts
new file mode 100644
index 000000000..3f51a73c0
--- /dev/null
+++ b/src/commands/daemon/index.ts
@@ -0,0 +1,17 @@
+import type { Command } from '../../commands.js'
+import { feature } from 'bun:bundle'
+
+const daemon = {
+  type: 'local-jsx',
+  name: 'daemon',
+  description: 'Manage background sessions and daemon',
+  argumentHint: '[status|start|stop|bg|attach|logs|kill]',
+  isEnabled: () => {
+    if (feature('DAEMON')) return true
+    if (feature('BG_SESSIONS')) return true
+    return false
+  },
+  load: () => import('./daemon.js'),
+} satisfies Command
+
+export default daemon
diff --git a/src/commands/init.ts b/src/commands/init.ts
index 93ac40ef2..68a5db11e 100644
--- a/src/commands/init.ts
+++ b/src/commands/init.ts
@@ -1,6 +1,7 @@
 import { feature } from 'bun:bundle'
 import type { Command } from '../commands.js'
 import { maybeMarkProjectOnboardingComplete } from '../projectOnboardingState.js'
+import { AUTONOMY_AGENTS_PATH_POSIX } from '../utils/autonomyAuthority.js'
 import { isEnvTruthy } from '../utils/envUtils.js'
 
 const OLD_INIT_PROMPT = `Please analyze this codebase and create a CLAUDE.md file, which will be given to future instances of Claude Code to operate in this repository.
@@ -43,7 +44,7 @@ Use AskUserQuestion to find out what the user wants:
 
 ## Phase 2: Explore the codebase
 
-Launch a subagent to survey the codebase, and ask it to read key files to understand the project: manifest files (package.json, Cargo.toml, pyproject.toml, go.mod, pom.xml, etc.), README, Makefile/build configs, CI config, existing CLAUDE.md, .claude/rules/, AGENTS.md, .cursor/rules or .cursorrules, .github/copilot-instructions.md, .windsurfrules, .clinerules, .mcp.json.
+Launch a subagent to survey the codebase, and ask it to read key files to understand the project: manifest files (package.json, Cargo.toml, pyproject.toml, go.mod, pom.xml, etc.), README, Makefile/build configs, CI config, existing CLAUDE.md, .claude/rules/, ${AUTONOMY_AGENTS_PATH_POSIX}, .cursor/rules or .cursorrules, .github/copilot-instructions.md, .windsurfrules, .clinerules, .mcp.json.
 
 Detect:
 - Build, test, and lint commands (especially non-standard ones)
@@ -105,7 +106,7 @@ Include:
 - Repo etiquette (branch naming, PR conventions, commit style)
 - Required env vars or setup steps
 - Non-obvious gotchas or architectural decisions
-- Important parts from existing AI coding tool configs if they exist (AGENTS.md, .cursor/rules, .cursorrules, .github/copilot-instructions.md, .windsurfrules, .clinerules)
+- Important parts from existing AI coding tool configs if they exist (${AUTONOMY_AGENTS_PATH_POSIX}, .cursor/rules, .cursorrules, .github/copilot-instructions.md, .windsurfrules, .clinerules)
 
 Exclude:
 - File-by-file structure or component lists (Claude can discover these by reading the codebase)
diff --git a/src/commands/job/__tests__/job.test.ts b/src/commands/job/__tests__/job.test.ts
new file mode 100644
index 000000000..394f8d1e8
--- /dev/null
+++ b/src/commands/job/__tests__/job.test.ts
@@ -0,0 +1,25 @@
+import { describe, test, expect } from 'bun:test'
+
+describe('/job command', () => {
+  test('index exports a valid Command', async () => {
+    const mod = await import('../index.js')
+    const cmd = mod.default
+    expect(cmd.name).toBe('job')
+    expect(cmd.type).toBe('local-jsx')
+    expect(typeof cmd.load).toBe('function')
+    expect(cmd.description).toContain('job')
+  })
+
+  test('job module exports call function', async () => {
+    const mod = await import('../job.js')
+    expect(typeof mod.call).toBe('function')
+  })
+
+  test('argumentHint lists subcommands', async () => {
+    const mod = await import('../index.js')
+    const cmd = mod.default
+    expect(cmd.argumentHint).toContain('list')
+    expect(cmd.argumentHint).toContain('new')
+    expect(cmd.argumentHint).toContain('status')
+  })
+})
diff --git a/src/commands/job/index.ts b/src/commands/job/index.ts
new file mode 100644
index 000000000..6c7dc870b
--- /dev/null
+++ b/src/commands/job/index.ts
@@ -0,0 +1,16 @@
+import type { Command } from '../../commands.js'
+import { feature } from 'bun:bundle'
+
+const job = {
+  type: 'local-jsx',
+  name: 'job',
+  description: 'Manage template jobs',
+  argumentHint: '[list|new|reply|status]',
+  isEnabled: () => {
+    if (feature('TEMPLATES')) return true
+    return false
+  },
+  load: () => import('./job.js'),
+} satisfies Command
+
+export default job
diff --git a/src/commands/job/job.tsx b/src/commands/job/job.tsx
new file mode 100644
index 000000000..2942db182
--- /dev/null
+++ b/src/commands/job/job.tsx
@@ -0,0 +1,34 @@
+import type { LocalJSXCommandOnDone, LocalJSXCommandContext } from '../../types/command.js'
+
+/**
+ * /job slash command — manages template jobs from inside the REPL.
+ *
+ * Subcommands: list | new <template> [args] | reply <id> <text> | status <id>
+ * Default (no args): list
+ */
+export async function call(
+  onDone: LocalJSXCommandOnDone,
+  _context: LocalJSXCommandContext,
+  args: string,
+): Promise<React.ReactNode> {
+  const parts = args ? args.trim().split(/\s+/) : []
+  const sub = parts[0] || 'list'
+
+  // Capture console output so we can return it as onDone text
+  const lines: string[] = []
+  const origLog = console.log
+  const origError = console.error
+  console.log = (...a: unknown[]) => lines.push(a.map(String).join(' '))
+  console.error = (...a: unknown[]) => lines.push(a.map(String).join(' '))
+
+  try {
+    const { templatesMain } = await import('../../cli/handlers/templateJobs.js')
+    await templatesMain([sub, ...parts.slice(1)])
+  } finally {
+    console.log = origLog
+    console.error = origError
+  }
+
+  onDone(lines.join('\n') || 'Done.', { display: 'system' })
+  return null
+}
diff --git a/src/commands/lang/index.ts b/src/commands/lang/index.ts
new file mode 100644
index 000000000..742c6a51b
--- /dev/null
+++ b/src/commands/lang/index.ts
@@ -0,0 +1,12 @@
+import type { Command } from '../../commands.js'
+
+const lang = {
+  type: 'local-jsx',
+  name: 'lang',
+  description: 'Set display language (en/zh/auto)',
+  immediate: true,
+  argumentHint: '<en|zh|auto>',
+  load: () => import('./lang.js'),
+} satisfies Command
+
+export default lang
diff --git a/src/commands/lang/lang.ts b/src/commands/lang/lang.ts
new file mode 100644
index 000000000..8520d26f2
--- /dev/null
+++ b/src/commands/lang/lang.ts
@@ -0,0 +1,49 @@
+import type { ToolUseContext } from '../../Tool.js'
+import type {
+  LocalJSXCommandContext,
+  LocalJSXCommandOnDone,
+} from '../../types/command.js'
+import { getGlobalConfig, saveGlobalConfig } from '../../utils/config.js'
+import {
+  type PreferredLanguage,
+  getLanguageDisplayName,
+  getResolvedLanguage,
+} from '../../utils/language.js'
+
+const VALID_LANGS: readonly PreferredLanguage[] = ['en', 'zh', 'auto']
+
+export async function call(
+  onDone: LocalJSXCommandOnDone,
+  _context: ToolUseContext & LocalJSXCommandContext,
+  args: string,
+): Promise<null> {
+  const arg = args.trim().toLowerCase()
+
+  if (!arg) {
+    const pref = getGlobalConfig().preferredLanguage ?? 'auto'
+    const resolved = getResolvedLanguage()
+    const suffix =
+      pref === 'auto' ? ` → ${getLanguageDisplayName(resolved)}` : ''
+    onDone(`Language: ${getLanguageDisplayName(pref)}${suffix}`, {
+      display: 'system',
+    })
+    return null
+  }
+
+  if (!VALID_LANGS.includes(arg as PreferredLanguage)) {
+    onDone(`Invalid language "${arg}". Use: en, zh, or auto`, {
+      display: 'system',
+    })
+    return null
+  }
+
+  const lang = arg as PreferredLanguage
+  saveGlobalConfig(current => ({ ...current, preferredLanguage: lang }))
+
+  const resolved = getResolvedLanguage()
+  const suffix = lang === 'auto' ? ` → ${getLanguageDisplayName(resolved)}` : ''
+  onDone(`Language set to ${getLanguageDisplayName(lang)}${suffix}`, {
+    display: 'system',
+  })
+  return null
+}
diff --git a/src/commands/remoteControlServer/remoteControlServer.tsx b/src/commands/remoteControlServer/remoteControlServer.tsx
index dc08a9cbc..c586b9484 100644
--- a/src/commands/remoteControlServer/remoteControlServer.tsx
+++ b/src/commands/remoteControlServer/remoteControlServer.tsx
@@ -1,4 +1,4 @@
-import { spawn, type ChildProcess } from 'child_process';
+import { type ChildProcess } from 'child_process';
 import { resolve } from 'path';
 import * as React from 'react';
 import { useEffect, useState } from 'react';
@@ -10,6 +10,7 @@ import { ListItem } from '../../components/design-system/ListItem.js';
 import { useRegisterOverlay } from '../../context/overlayContext.js';
 import { Box, Text } from '@anthropic/ink';
 import { useKeybindings } from '../../keybindings/useKeybinding.js';
+import { buildCliLaunch, spawnCli } from '../../utils/cliLaunch.js';
 import type { ToolUseContext } from '../../Tool.js';
 import type { LocalJSXCommandContext, LocalJSXCommandOnDone } from '../../types/command.js';
 import { errorMessage } from '../../utils/errors.js';
@@ -202,9 +203,9 @@ async function checkPrerequisites(): Promise<string | null> {
 function startDaemon(): void {
   const dir = resolve('.');
 
-  const execArgs = [...process.execArgv, process.argv[1]!, 'daemon', 'start', `--dir=${dir}`];
+  const launch = buildCliLaunch(['daemon', 'start', `--dir=${dir}`]);
 
-  const child = spawn(process.execPath, execArgs, {
+  const child = spawnCli(launch, {
     cwd: dir,
     stdio: ['ignore', 'pipe', 'pipe'],
     detached: false,
diff --git a/src/commands/send/send.ts b/src/commands/send/send.ts
index ed7345c89..a0fd29b67 100644
--- a/src/commands/send/send.ts
+++ b/src/commands/send/send.ts
@@ -1,6 +1,11 @@
 import type { LocalCommandCall } from '../../types/command.js'
 import { getSlaveClient } from '../../hooks/useMasterMonitor.js'
 import { getPipeIpc } from '../../utils/pipeTransport.js'
+import {
+  addSendOverride,
+  removeSendOverride,
+  removeMasterPipeMute,
+} from '../../utils/pipeMuteState.js'
 
 export const call: LocalCommandCall = async (args, context) => {
   const currentState = context.getAppState()
@@ -48,6 +53,12 @@ export const call: LocalCommandCall = async (args, context) => {
   }
 
   try {
+    // Temporarily override mute for this slave so its response is visible.
+    // Override lasts until the slave emits 'done' or 'error' (cleared by
+    // useMasterMonitor's attachPipeEntryEmitter handler).
+    addSendOverride(targetName)
+    removeMasterPipeMute(targetName)
+    client.send({ type: 'relay_unmute' })
     client.send({
       type: 'prompt',
       data: message,
@@ -89,6 +100,8 @@ export const call: LocalCommandCall = async (args, context) => {
       value: `Sent to "${targetName}": ${message.slice(0, 100)}${message.length > 100 ? '...' : ''}`,
     }
   } catch (err) {
+    // Roll back override on send failure to prevent permanent unmute
+    removeSendOverride(targetName)
     return {
       type: 'text',
       value: `Failed to send to "${targetName}": ${err instanceof Error ? err.message : String(err)}`,
diff --git a/src/commands/torch.ts b/src/commands/torch.ts
index 7b8595488..b7f2441fd 100644
--- a/src/commands/torch.ts
+++ b/src/commands/torch.ts
@@ -1 +1,19 @@
-export default null
+import type { Command, LocalJSXCommandOnDone } from '../types/command.js'
+import type { ReactNode } from 'react'
+
+const call = async (onDone: LocalJSXCommandOnDone): Promise<ReactNode> => {
+  onDone(
+    'torch: Reserved internal debug command. No implementation is available in this build.',
+    { display: 'system' },
+  )
+  return null
+}
+
+export default {
+  type: 'local-jsx',
+  name: 'torch',
+  description: '[INTERNAL] Development debug command (reserved)',
+  isEnabled: () => true,
+  isHidden: true,
+  load: () => Promise.resolve({ call }),
+} satisfies Command
diff --git a/src/daemon/__tests__/daemonMain.test.ts b/src/daemon/__tests__/daemonMain.test.ts
new file mode 100644
index 000000000..9fb275f62
--- /dev/null
+++ b/src/daemon/__tests__/daemonMain.test.ts
@@ -0,0 +1,61 @@
+/**
+ * Tests for daemon/main.ts subcommand routing.
+ *
+ * The `status` and `bg` subcommands trigger dynamic imports of `cli/bg.ts`
+ * which depends on `envUtils.ts` → `lodash-es/memoize.js` (unavailable in
+ * raw test context without `bun run dev`'s define flags). We test only the
+ * self-contained subcommands: help and unknown.
+ */
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test'
+
+describe('daemonMain subcommand routing', () => {
+  const origLog = console.log
+  const origError = console.error
+  let logLines: string[]
+
+  beforeEach(() => {
+    logLines = []
+    console.log = (...a: unknown[]) => logLines.push(a.map(String).join(' '))
+    console.error = (...a: unknown[]) => logLines.push(a.map(String).join(' '))
+  })
+
+  afterEach(() => {
+    console.log = origLog
+    console.error = origError
+    process.exitCode = 0
+  })
+
+  test('unknown subcommand sets exitCode to 1', async () => {
+    const { daemonMain } = await import('../main.js')
+    await daemonMain(['unknown-command-xyz'])
+    expect(process.exitCode).toBe(1)
+  })
+
+  test('help subcommand prints usage', async () => {
+    const { daemonMain } = await import('../main.js')
+    await daemonMain(['help'])
+    const output = logLines.join('\n')
+    expect(output).toContain('SUBCOMMANDS')
+    expect(output).toContain('status')
+    expect(output).toContain('start')
+    expect(output).toContain('stop')
+    expect(output).toContain('bg')
+    expect(output).toContain('attach')
+    expect(output).toContain('logs')
+    expect(output).toContain('kill')
+  })
+
+  test('--help is alias for help', async () => {
+    const { daemonMain } = await import('../main.js')
+    await daemonMain(['--help'])
+    const output = logLines.join('\n')
+    expect(output).toContain('SUBCOMMANDS')
+  })
+
+  test('-h is alias for help', async () => {
+    const { daemonMain } = await import('../main.js')
+    await daemonMain(['-h'])
+    const output = logLines.join('\n')
+    expect(output).toContain('SUBCOMMANDS')
+  })
+})
diff --git a/src/daemon/__tests__/state.test.ts b/src/daemon/__tests__/state.test.ts
new file mode 100644
index 000000000..168cea1a7
--- /dev/null
+++ b/src/daemon/__tests__/state.test.ts
@@ -0,0 +1,185 @@
+/**
+ * Tests for src/daemon/state.ts
+ *
+ * Uses real temp directories and CLAUDE_CONFIG_DIR env var
+ * instead of mocking fs/envUtils, to avoid cross-test mock pollution.
+ */
+import { describe, expect, test, beforeEach, afterAll } from 'bun:test'
+import { mkdtempSync, rmSync, existsSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+import { getClaudeConfigHomeDir } from '../../utils/envUtils.js'
+
+// ─── setup: real temp dir via env var ──────────────────────────────────────
+
+const tempBase = mkdtempSync(join(tmpdir(), 'daemon-state-test-'))
+
+beforeEach(() => {
+  // Clear lodash memoize cache so CLAUDE_CONFIG_DIR env var takes effect
+  if (
+    typeof getClaudeConfigHomeDir === 'function' &&
+    'cache' in getClaudeConfigHomeDir
+  ) {
+    ;(getClaudeConfigHomeDir as any).cache.clear?.()
+  }
+  const tempHome = mkdtempSync(join(tempBase, 'home-'))
+  process.env.CLAUDE_CONFIG_DIR = tempHome
+})
+
+afterAll(() => {
+  delete process.env.CLAUDE_CONFIG_DIR
+  // Clear memoize cache after all tests so other files see fresh state
+  if (
+    typeof getClaudeConfigHomeDir === 'function' &&
+    'cache' in getClaudeConfigHomeDir
+  ) {
+    ;(getClaudeConfigHomeDir as any).cache.clear?.()
+  }
+  try {
+    rmSync(tempBase, { recursive: true, force: true })
+  } catch {
+    // best-effort cleanup
+  }
+})
+
+// ─── import ─────────────────────────────────────────────────────────────────
+
+const {
+  getDaemonStateFilePath,
+  writeDaemonState,
+  readDaemonState,
+  removeDaemonState,
+  queryDaemonStatus,
+} = await import('../state.js')
+
+// ─── tests ─────────────────────────────────────────────────────────────────
+
+describe('getDaemonStateFilePath', () => {
+  test('returns default path with remote-control name', () => {
+    const p = getDaemonStateFilePath()
+    expect(p).toContain('daemon')
+    expect(p).toContain('remote-control.json')
+  })
+
+  test('returns path with custom name', () => {
+    const p = getDaemonStateFilePath('my-daemon')
+    expect(p).toContain('my-daemon.json')
+  })
+})
+
+describe('writeDaemonState', () => {
+  test('writes state JSON to disk', () => {
+    const state = {
+      pid: 1234,
+      cwd: '/test',
+      startedAt: '2026-01-01T00:00:00Z',
+      workerKinds: ['rcs'],
+      lastStatus: 'running' as const,
+    }
+    writeDaemonState(state, 'test')
+    const filePath = getDaemonStateFilePath('test')
+    expect(existsSync(filePath)).toBe(true)
+    const parsed = JSON.parse(readFileSync(filePath, 'utf-8'))
+    expect(parsed.pid).toBe(1234)
+    expect(parsed.cwd).toBe('/test')
+  })
+
+  test('creates directory recursively', () => {
+    writeDaemonState(
+      {
+        pid: 1,
+        cwd: '/',
+        startedAt: '',
+        workerKinds: [],
+        lastStatus: 'running',
+      },
+      'dir-test',
+    )
+    const filePath = getDaemonStateFilePath('dir-test')
+    expect(existsSync(filePath)).toBe(true)
+  })
+})
+
+describe('readDaemonState', () => {
+  test('returns null when no state file', () => {
+    expect(readDaemonState('nonexistent')).toBeNull()
+  })
+
+  test('returns parsed state when file exists', () => {
+    const state = {
+      pid: 42,
+      cwd: '/x',
+      startedAt: '',
+      workerKinds: [],
+      lastStatus: 'running' as const,
+    }
+    writeDaemonState(state, 'read-test')
+    const result = readDaemonState('read-test')
+    expect(result).not.toBeNull()
+    expect(result!.pid).toBe(42)
+  })
+})
+
+describe('removeDaemonState', () => {
+  test('removes existing state file', () => {
+    writeDaemonState(
+      {
+        pid: 1,
+        cwd: '/',
+        startedAt: '',
+        workerKinds: [],
+        lastStatus: 'running',
+      },
+      'rm-test',
+    )
+    const filePath = getDaemonStateFilePath('rm-test')
+    expect(existsSync(filePath)).toBe(true)
+    removeDaemonState('rm-test')
+    expect(existsSync(filePath)).toBe(false)
+  })
+
+  test('does not throw when file does not exist', () => {
+    expect(() => removeDaemonState('no-file')).not.toThrow()
+  })
+})
+
+describe('queryDaemonStatus', () => {
+  test('returns stopped when no state file', () => {
+    const result = queryDaemonStatus('empty')
+    expect(result.status).toBe('stopped')
+    expect(result.state).toBeUndefined()
+  })
+
+  test('returns running when PID is alive (current process)', () => {
+    writeDaemonState(
+      {
+        pid: process.pid,
+        cwd: process.cwd(),
+        startedAt: new Date().toISOString(),
+        workerKinds: ['test'],
+        lastStatus: 'running',
+      },
+      'alive-test',
+    )
+    const result = queryDaemonStatus('alive-test')
+    expect(result.status).toBe('running')
+    expect(result.state).toBeDefined()
+    expect(result.state!.pid).toBe(process.pid)
+  })
+
+  test('returns stale when PID is dead and cleans up', () => {
+    writeDaemonState(
+      {
+        pid: 999999,
+        cwd: '/',
+        startedAt: '',
+        workerKinds: [],
+        lastStatus: 'running',
+      },
+      'stale-test',
+    )
+    const result = queryDaemonStatus('stale-test')
+    expect(result.status).toBe('stale')
+    expect(existsSync(getDaemonStateFilePath('stale-test'))).toBe(false)
+  })
+})
diff --git a/src/daemon/main.ts b/src/daemon/main.ts
index d7697a281..513103e9a 100644
--- a/src/daemon/main.ts
+++ b/src/daemon/main.ts
@@ -1,6 +1,13 @@
-import { spawn, type ChildProcess } from 'child_process'
+import { type ChildProcess } from 'child_process'
 import { resolve } from 'path'
+import { buildCliLaunch, spawnCli } from '../utils/cliLaunch.js'
 import { errorMessage } from '../utils/errors.js'
+import {
+  writeDaemonState,
+  removeDaemonState,
+  queryDaemonStatus,
+  stopDaemonByPid,
+} from './state.js'
 
 /**
  * Exit code used by workers for permanent (non-retryable) failures.
@@ -29,30 +36,62 @@ interface WorkerState {
  * Daemon supervisor entry point. Called from `cli.tsx` via:
  *   `claude daemon [subcommand]`
  *
- * Starts and supervises long-running workers. Currently spawns one
- * `remoteControl` worker that runs the headless bridge server.
+ * Manages the daemon supervisor AND background sessions under one namespace.
  *
  * Subcommands:
- *   (none)  — start the supervisor with default workers
- *   start   — same as no subcommand
- *   status  — print worker status (TODO: IPC)
- *   stop    — send SIGTERM to supervisor (TODO: PID file)
+ *   (none)  — unified status (supervisor + sessions)
+ *   start   — start the supervisor with default workers
+ *   stop    — send SIGTERM to supervisor
+ *   status  — unified status (supervisor + sessions)
+ *   ps      — alias for status
+ *   bg      — start a background session
+ *   attach  — attach to a background session
+ *   logs    — show session logs
+ *   kill    — kill a session
  */
 export async function daemonMain(args: string[]): Promise<void> {
-  const subcommand = args[0] || 'start'
+  const subcommand = args[0] || 'status'
 
   switch (subcommand) {
+    // --- Supervisor management ---
     case 'start':
       await runSupervisor(args.slice(1))
       break
+    case 'stop':
+      await handleDaemonStop()
+      break
+
+    // --- Unified status ---
     case 'status':
-      console.log('daemon status: not yet implemented (requires IPC)')
+    case 'ps':
+      await showUnifiedStatus()
       break
-    case 'stop':
-      console.log('daemon stop: not yet implemented (requires PID file)')
+
+    // --- Session management (delegates to bg.ts) ---
+    case 'bg': {
+      const bg = await import('../cli/bg.js')
+      await bg.handleBgStart(args.slice(1))
+      break
+    }
+    case 'attach': {
+      const bg = await import('../cli/bg.js')
+      await bg.attachHandler(args[1])
+      break
+    }
+    case 'logs': {
+      const bg = await import('../cli/bg.js')
+      await bg.logsHandler(args[1])
+      break
+    }
+    case 'kill': {
+      const bg = await import('../cli/bg.js')
+      await bg.killHandler(args[1])
       break
+    }
+
     case '--help':
     case '-h':
+    case 'help':
       printHelp()
       break
     default:
@@ -64,17 +103,25 @@ export async function daemonMain(args: string[]): Promise<void> {
 
 function printHelp(): void {
   console.log(`
-Claude Code Daemon — persistent background supervisor
+Claude Code Daemon — background process management
 
 USAGE
-  claude daemon [subcommand] [options]
+  claude daemon [subcommand]
 
 SUBCOMMANDS
-  start       Start the daemon supervisor (default)
-  status      Show worker status
+  status      Show daemon and session status (default)
+  start       Start the daemon supervisor
   stop        Stop the daemon
+  bg          Start a background session
+  attach      Attach to a background session
+  logs        Show session logs
+  kill        Kill a session
+  help        Show this help
+
+REPL
+  /daemon [subcommand]    Same commands available in interactive mode
 
-OPTIONS
+OPTIONS (for start)
   --dir <path>              Working directory (default: current)
   --spawn-mode <mode>       Worker spawn mode: same-dir | worktree (default: same-dir)
   --capacity <N>            Max concurrent sessions per worker (default: 4)
@@ -85,6 +132,63 @@ OPTIONS
 `)
 }
 
+/**
+ * Show unified status: daemon supervisor + background sessions.
+ */
+async function showUnifiedStatus(): Promise<void> {
+  // 1. Daemon supervisor status
+  const result = queryDaemonStatus()
+  console.log('=== Daemon Supervisor ===')
+  switch (result.status) {
+    case 'running': {
+      const s = result.state!
+      console.log(`  Status:  running`)
+      console.log(`  PID:     ${s.pid}`)
+      console.log(`  CWD:     ${s.cwd}`)
+      console.log(`  Started: ${s.startedAt}`)
+      console.log(`  Workers: ${s.workerKinds.join(', ')}`)
+      break
+    }
+    case 'stopped':
+      console.log('  Status: stopped')
+      break
+    case 'stale':
+      console.log('  Status: stale (cleaned up)')
+      break
+  }
+
+  // 2. Background sessions
+  console.log('\n=== Background Sessions ===')
+  const bg = await import('../cli/bg.js')
+  await bg.psHandler([])
+}
+
+/**
+ * Stop a running daemon from another CLI process.
+ */
+async function handleDaemonStop(): Promise<void> {
+  const result = queryDaemonStatus()
+
+  if (result.status === 'stopped') {
+    console.log('daemon is not running')
+    return
+  }
+
+  if (result.status === 'stale') {
+    console.log('daemon was stale (cleaned up)')
+    return
+  }
+
+  console.log(`stopping daemon (PID: ${result.state!.pid})...`)
+  const stopped = await stopDaemonByPid()
+
+  if (stopped) {
+    console.log('daemon stopped')
+  } else {
+    console.log('daemon could not be stopped (may have already exited)')
+  }
+}
+
 /**
  * Parse supervisor arguments from CLI.
  */
@@ -140,12 +244,22 @@ async function runSupervisor(args: string[]): Promise<void> {
     },
   ]
 
+  // Write daemon state file so other CLI processes can query/stop us
+  writeDaemonState({
+    pid: process.pid,
+    cwd: dir,
+    startedAt: new Date().toISOString(),
+    workerKinds: workers.map(w => w.kind),
+    lastStatus: 'running',
+  })
+
   const controller = new AbortController()
 
   // Graceful shutdown
   const shutdown = () => {
     console.log('[daemon] supervisor shutting down...')
     controller.abort()
+    removeDaemonState()
     for (const w of workers) {
       if (w.process && !w.process.killed) {
         w.process.kill('SIGTERM')
@@ -222,17 +336,11 @@ function spawnWorker(
     CLAUDE_CODE_SESSION_KIND: 'daemon-worker',
   }
 
-  // Build the worker command: reuse the same entrypoint with --daemon-worker flag
-  const execArgs = [
-    ...process.execArgv,
-    process.argv[1]!,
-    `--daemon-worker=${worker.kind}`,
-  ]
-
   console.log(`[daemon] spawning worker '${worker.kind}'`)
 
-  const child = spawn(process.execPath, execArgs, {
-    env,
+  const launch = buildCliLaunch([`--daemon-worker=${worker.kind}`], { env })
+
+  const child = spawnCli(launch, {
     cwd: dir,
     stdio: ['ignore', 'pipe', 'pipe'],
   })
diff --git a/src/daemon/state.ts b/src/daemon/state.ts
new file mode 100644
index 000000000..b691e174e
--- /dev/null
+++ b/src/daemon/state.ts
@@ -0,0 +1,157 @@
+import { readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'fs'
+import { join, dirname } from 'path'
+import { getClaudeConfigHomeDir } from '../utils/envUtils.js'
+
+/**
+ * Daemon state persisted to disk so that `status` / `stop` can work
+ * from a different CLI process than the one that started the daemon.
+ */
+export interface DaemonStateData {
+  pid: number
+  cwd: string
+  startedAt: string
+  workerKinds: string[]
+  lastStatus: 'running' | 'stopped' | 'error'
+}
+
+export type DaemonStatus = 'running' | 'stopped' | 'stale'
+
+/**
+ * Returns the path to the daemon state file for a given daemon name.
+ */
+export function getDaemonStateFilePath(name = 'remote-control'): string {
+  return join(getClaudeConfigHomeDir(), 'daemon', `${name}.json`)
+}
+
+/**
+ * Write daemon state to disk. Called by the supervisor on startup.
+ */
+export function writeDaemonState(
+  state: DaemonStateData,
+  name = 'remote-control',
+): void {
+  const filePath = getDaemonStateFilePath(name)
+  mkdirSync(dirname(filePath), { recursive: true })
+  writeFileSync(filePath, JSON.stringify(state, null, 2), 'utf-8')
+}
+
+/**
+ * Read daemon state from disk. Returns null if no state file exists.
+ */
+export function readDaemonState(
+  name = 'remote-control',
+): DaemonStateData | null {
+  const filePath = getDaemonStateFilePath(name)
+  try {
+    const raw = readFileSync(filePath, 'utf-8')
+    return JSON.parse(raw) as DaemonStateData
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Remove the daemon state file.
+ */
+export function removeDaemonState(name = 'remote-control'): void {
+  const filePath = getDaemonStateFilePath(name)
+  try {
+    unlinkSync(filePath)
+  } catch {
+    // File may not exist — that's fine
+  }
+}
+
+/**
+ * Check if a process with the given PID is alive.
+ */
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Query the daemon status by reading the state file and probing the PID.
+ *
+ * Returns:
+ *  - { status: 'running', state } — PID is alive
+ *  - { status: 'stopped' }       — no state file
+ *  - { status: 'stale' }         — state file exists but PID is dead (auto-cleaned)
+ */
+export function queryDaemonStatus(name = 'remote-control'): {
+  status: DaemonStatus
+  state?: DaemonStateData
+} {
+  const state = readDaemonState(name)
+  if (!state) {
+    return { status: 'stopped' }
+  }
+
+  if (isProcessAlive(state.pid)) {
+    return { status: 'running', state }
+  }
+
+  // Stale — process is dead but state file remains
+  removeDaemonState(name)
+  return { status: 'stale' }
+}
+
+/**
+ * Stop a running daemon by sending SIGTERM, waiting, then SIGKILL if needed.
+ * Cleans up the state file afterward.
+ *
+ * @returns true if the daemon was stopped, false if it wasn't running
+ */
+export async function stopDaemonByPid(
+  name = 'remote-control',
+  timeoutMs = 10_000,
+): Promise<boolean> {
+  const state = readDaemonState(name)
+  if (!state) {
+    return false
+  }
+
+  const { pid } = state
+
+  if (!isProcessAlive(pid)) {
+    removeDaemonState(name)
+    return false
+  }
+
+  // Send SIGTERM
+  try {
+    process.kill(pid, 'SIGTERM')
+  } catch {
+    removeDaemonState(name)
+    return false
+  }
+
+  // Wait for exit with timeout
+  const deadline = Date.now() + timeoutMs
+  const pollInterval = 200
+
+  while (Date.now() < deadline) {
+    if (!isProcessAlive(pid)) {
+      removeDaemonState(name)
+      return true
+    }
+    await new Promise(resolve => setTimeout(resolve, pollInterval))
+  }
+
+  // Force kill
+  try {
+    process.kill(pid, 'SIGKILL')
+  } catch {
+    // Already dead
+  }
+
+  // Brief wait for SIGKILL to take effect
+  await new Promise(resolve => setTimeout(resolve, 500))
+
+  removeDaemonState(name)
+  return true
+}
diff --git a/src/entrypoints/cli.tsx b/src/entrypoints/cli.tsx
index 8b11a3d23..384848cf7 100644
--- a/src/entrypoints/cli.tsx
+++ b/src/entrypoints/cli.tsx
@@ -132,14 +132,23 @@ async function main(): Promise<void> {
     return
   }
 
+  // Fast-path for `--acp` — ACP (Agent Client Protocol) agent mode over stdio.
+  if (feature('ACP') && process.argv[2] === '--acp') {
+    profileCheckpoint('cli_acp_path')
+    const { runAcpAgent } = await import('../services/acp/entry.js')
+    await runAcpAgent()
+    return
+  }
+
   // Fast-path for `--daemon-worker=<kind>` (internal — supervisor spawns this).
   // Must come before the daemon subcommand check: spawned per-worker, so
   // perf-sensitive. No enableConfigs(), no analytics sinks at this layer —
   // workers are lean. If a worker kind needs configs/auth (assistant will),
   // it calls them inside its run() fn.
-  if (feature('DAEMON') && args[0] === '--daemon-worker') {
+  if (feature('DAEMON') && (args[0] === '--daemon-worker' || args[0]?.startsWith('--daemon-worker='))) {
+    const kind = args[0] === '--daemon-worker' ? args[1] : args[0].split('=')[1]
     const { runDaemonWorker } = await import('../daemon/workerRegistry.js')
-    await runDaemonWorker(args[1])
+    await runDaemonWorker(kind)
     return
   }
 
@@ -199,11 +208,18 @@ async function main(): Promise<void> {
     return
   }
 
-  // Fast-path for `claude daemon [subcommand]`: long-running supervisor.
-  if (feature('DAEMON') && args[0] === 'daemon') {
+  // Fast-path for `claude daemon [subcommand]`: unified daemon + session management.
+  // Handles both supervisor (start/stop) and background session (bg/attach/logs/kill)
+  // subcommands under one namespace.
+  if (
+    (feature('DAEMON') || feature('BG_SESSIONS')) &&
+    args[0] === 'daemon'
+  ) {
     profileCheckpoint('cli_daemon_path')
     const { enableConfigs } = await import('../utils/config.js')
     enableConfigs()
+    const { setShellIfWindows } = await import('../utils/windowsPaths.js')
+    setShellIfWindows()
     const { initSinks } = await import('../utils/sinks.js')
     initSinks()
     const { daemonMain } = await import('../daemon/main.js')
@@ -211,51 +227,69 @@ async function main(): Promise<void> {
     return
   }
 
-  // Fast-path for `claude ps|logs|attach|kill` and `--bg`/`--background`.
-  // Session management against the ~/.claude/sessions/ registry. Flag
-  // literals are inlined so bg.js only loads when actually dispatching.
+  // Fast-path for `--bg`/`--background` shortcut → daemon bg.
+  if (
+    feature('BG_SESSIONS') &&
+    (args.includes('--bg') || args.includes('--background'))
+  ) {
+    profileCheckpoint('cli_daemon_path')
+    const { enableConfigs } = await import('../utils/config.js')
+    enableConfigs()
+    const { setShellIfWindows } = await import('../utils/windowsPaths.js')
+    setShellIfWindows()
+    const bg = await import('../cli/bg.js')
+    await bg.handleBgStart(
+      args.filter(a => a !== '--bg' && a !== '--background'),
+    )
+    return
+  }
+
+  // Backward-compat: ps/logs/attach/kill → daemon <sub> (deprecated)
   if (
     feature('BG_SESSIONS') &&
     (args[0] === 'ps' ||
       args[0] === 'logs' ||
       args[0] === 'attach' ||
-      args[0] === 'kill' ||
-      args.includes('--bg') ||
-      args.includes('--background'))
+      args[0] === 'kill')
   ) {
-    profileCheckpoint('cli_bg_path')
+    const mapped = args[0] === 'ps' ? 'status' : args[0]
+    console.error(
+      `[deprecated] Use: claude daemon ${mapped}${args[1] ? ' ' + args[1] : ''}`,
+    )
+    profileCheckpoint('cli_daemon_path')
     const { enableConfigs } = await import('../utils/config.js')
     enableConfigs()
-    const bg = await import('../cli/bg.js')
-    switch (args[0]) {
-      case 'ps':
-        await bg.psHandler(args.slice(1))
-        break
-      case 'logs':
-        await bg.logsHandler(args[1])
-        break
-      case 'attach':
-        await bg.attachHandler(args[1])
-        break
-      case 'kill':
-        await bg.killHandler(args[1])
-        break
-      default:
-        await bg.handleBgFlag(args)
-    }
+    const { setShellIfWindows } = await import('../utils/windowsPaths.js')
+    setShellIfWindows()
+    const { initSinks } = await import('../utils/sinks.js')
+    initSinks()
+    const { daemonMain } = await import('../daemon/main.js')
+    await daemonMain([args[0] === 'ps' ? 'status' : args[0]!, ...args.slice(1)])
     return
   }
 
-  // Fast-path for template job commands.
+  // Fast-path for `claude job <subcommand>`: template jobs.
+  if (feature('TEMPLATES') && args[0] === 'job') {
+    profileCheckpoint('cli_templates_path')
+    const { templatesMain } = await import('../cli/handlers/templateJobs.js')
+    await templatesMain(args.slice(1))
+    // process.exit (not return) — mountFleetView's Ink TUI can leave event
+    // loop handles that prevent natural exit.
+    // eslint-disable-next-line custom-rules/no-process-exit
+    process.exit(0)
+  }
+
+  // Backward-compat: new/list/reply → job <sub> (deprecated)
   if (
     feature('TEMPLATES') &&
     (args[0] === 'new' || args[0] === 'list' || args[0] === 'reply')
   ) {
+    console.error(
+      `[deprecated] Use: claude job ${args[0]} ${args.slice(1).join(' ')}`.trim(),
+    )
     profileCheckpoint('cli_templates_path')
     const { templatesMain } = await import('../cli/handlers/templateJobs.js')
     await templatesMain(args)
-    // process.exit (not return) — mountFleetView's Ink TUI can leave event
-    // loop handles that prevent natural exit.
     // eslint-disable-next-line custom-rules/no-process-exit
     process.exit(0)
   }
diff --git a/src/hooks/useAwaySummary.ts b/src/hooks/useAwaySummary.ts
index 9caf55f24..a6bde9e37 100644
--- a/src/hooks/useAwaySummary.ts
+++ b/src/hooks/useAwaySummary.ts
@@ -48,7 +48,6 @@ export function useAwaySummary(
     'tengu_sedge_lantern',
     false,
   )
-
   useEffect(() => {
     if (!feature('AWAY_SUMMARY')) return
     if (!gbEnabled) return
diff --git a/src/hooks/useMasterMonitor.ts b/src/hooks/useMasterMonitor.ts
index c9291cf64..e2659692a 100644
--- a/src/hooks/useMasterMonitor.ts
+++ b/src/hooks/useMasterMonitor.ts
@@ -18,6 +18,11 @@ import {
   type PipeIpcSlaveState,
 } from '../utils/pipeTransport.js'
 import { logForDebugging } from '../utils/debug.js'
+import {
+  isMasterPipeMuted,
+  hasSendOverride,
+  removeSendOverride,
+} from '../utils/pipeMuteState.js'
 
 /** Session history entry for pipe IPC monitoring. */
 export type SessionEntry = {
@@ -113,6 +118,28 @@ function isMonitoredPipeEntryType(type: string): boolean {
   return MONITORED_PIPE_ENTRY_TYPES.includes(type)
 }
 
+/** Business message types that should be dropped when a slave is muted. */
+const MUTED_DROPPABLE_TYPES = new Set([
+  'prompt_ack',
+  'stream',
+  'tool_start',
+  'tool_result',
+  'done',
+  'error',
+  'permission_request',
+  'permission_cancel',
+])
+
+/**
+ * Centralized mute check used by both attachPipeEntryEmitter and
+ * useMasterMonitor's inline handler — keeps the two gates in sync.
+ */
+export function shouldDropMutedMessage(slaveName: string, msgType: string): boolean {
+  if (hasSendOverride(slaveName)) return false
+  if (!isMasterPipeMuted(slaveName)) return false
+  return MUTED_DROPPABLE_TYPES.has(msgType)
+}
+
 function pipeMessageToSessionEntry(
   slaveName: string,
   msg: PipeMessage,
@@ -153,6 +180,35 @@ function attachPipeEntryEmitter(name: string, client: PipeClient): void {
   if (typeof client.on !== 'function') return
   const handler = (msg: PipeMessage) => {
     if (!isMonitoredPipeEntryType(msg.type)) return
+
+    // Mute gate: drop business messages from muted slaves
+    if (shouldDropMutedMessage(name, msg.type)) {
+      // Auto-deny permission_request to prevent slave deadlock
+      if (msg.type === 'permission_request') {
+        try {
+          const payload = JSON.parse(msg.data ?? '{}')
+          if (payload.requestId) {
+            client.send({
+              type: 'permission_response',
+              data: JSON.stringify({
+                requestId: payload.requestId,
+                behavior: 'deny',
+                feedback: 'Permission auto-denied: pipe is logically disconnected.',
+              }),
+            })
+          }
+        } catch {
+          // Malformed payload — safe to ignore
+        }
+      }
+      return
+    }
+
+    // Clear /send override when slave turn completes
+    if ((msg.type === 'done' || msg.type === 'error') && hasSendOverride(name)) {
+      removeSendOverride(name)
+    }
+
     emitPipeEntry(name, pipeMessageToSessionEntry(name, msg))
   }
   _pipeEntryHandlers.set(name, handler)
@@ -166,14 +222,14 @@ function emitSlaveClientRegistryChanged(): void {
   }
 }
 
-function subscribeToSlaveClientRegistry(listener: () => void): () => void {
+export function subscribeToSlaveClientRegistry(listener: () => void): () => void {
   _slaveClientRegistryListeners.add(listener)
   return () => {
     _slaveClientRegistryListeners.delete(listener)
   }
 }
 
-function getSlaveClientRegistryVersion(): number {
+export function getSlaveClientRegistryVersion(): number {
   return _slaveClientRegistryVersion
 }
 
@@ -248,13 +304,23 @@ export function useMasterMonitor(): void {
 
     for (const [slaveName, client] of _slaveClients.entries()) {
       const handler = (msg: PipeMessage) => {
-        const entry = pipeMessageToSessionEntry(slaveName, msg)
-
         // Only record relevant message types
         if (!isMonitoredPipeEntryType(msg.type)) {
           return
         }
 
+        // Mute gate (second gate, same helper as attachPipeEntryEmitter)
+        if (shouldDropMutedMessage(slaveName, msg.type)) {
+          return
+        }
+
+        // Clear /send override when slave turn completes
+        if ((msg.type === 'done' || msg.type === 'error') && hasSendOverride(slaveName)) {
+          removeSendOverride(slaveName)
+        }
+
+        const entry = pipeMessageToSessionEntry(slaveName, msg)
+
         setAppState(prev => {
           const slave = getPipeIpc(prev).slaves[slaveName]
           if (!slave) return prev
@@ -294,6 +360,8 @@ export function useMasterMonitor(): void {
       // Handle slave disconnect
       const onDisconnect = () => {
         logForDebugging(`[MasterMonitor] Slave "${slaveName}" disconnected`)
+        // Clear any lingering /send override before removing client
+        removeSendOverride(slaveName)
         removeSlaveClient(slaveName)
         setAppState(prev => {
           const { [slaveName]: _removed, ...remainingSlaves } =
diff --git a/src/hooks/usePipeIpc.ts b/src/hooks/usePipeIpc.ts
index b48b1aa67..0f131a196 100644
--- a/src/hooks/usePipeIpc.ts
+++ b/src/hooks/usePipeIpc.ts
@@ -246,6 +246,15 @@ function registerMessageHandlers(
     }
   })
 
+  // Handle relay mute/unmute from master
+  server.onMessage((msg: PipeMessage, _reply) => {
+    if (msg.type === 'relay_mute') {
+      pp().setRelayMuted(true)
+    } else if (msg.type === 'relay_unmute') {
+      pp().setRelayMuted(false)
+    }
+  })
+
   // Handle detach
   server.onMessage((msg: PipeMessage, _reply) => {
     if (msg.type !== 'detach') return
diff --git a/src/hooks/usePipeMuteSync.ts b/src/hooks/usePipeMuteSync.ts
new file mode 100644
index 000000000..4bddd0451
--- /dev/null
+++ b/src/hooks/usePipeMuteSync.ts
@@ -0,0 +1,141 @@
+/**
+ * usePipeMuteSync — Sync master's UI selection state to slave relay mute flags.
+ *
+ * Watches routeMode, selectedPipes, slave client registry, and send-override
+ * changes. When a slave is deselected or routeMode switches to 'local', sends
+ * relay_mute. When re-selected, sends relay_unmute. Also maintains the
+ * master-side muted set for in-flight message filtering.
+ *
+ * Feature-gated by UDS_INBOX (conditional import in REPL.tsx).
+ */
+import { useEffect, useRef, useSyncExternalStore } from 'react'
+import { useAppState } from '../state/AppState.js'
+import { getPipeIpc } from '../utils/pipeTransport.js'
+import {
+  setMasterMutedPipes,
+  clearMasterMutedPipes,
+  hasSendOverride,
+  clearSendOverrides,
+  subscribeSendOverride,
+  getSendOverrideVersion,
+} from '../utils/pipeMuteState.js'
+import {
+  getAllSlaveClients,
+  subscribeToSlaveClientRegistry,
+  getSlaveClientRegistryVersion,
+} from './useMasterMonitor.js'
+
+type UsePipeMuteSyncDeps = {
+  setToolUseConfirmQueue: (action: React.SetStateAction<Record<string, unknown>[]>) => void
+}
+
+export function usePipeMuteSync({
+  setToolUseConfirmQueue,
+}: UsePipeMuteSyncDeps): void {
+  // Subscribe to individual scalars to avoid object-selector re-render churn
+  // (AppState.tsx warns against object-returning selectors)
+  const routeMode = useAppState(
+    s => (getPipeIpc(s).routeMode as 'selected' | 'local') ?? 'selected',
+  )
+  const selectedPipes: string[] = useAppState(
+    s => (getPipeIpc(s).selectedPipes as string[]) ?? [],
+  )
+
+  // Subscribe to slave client registry changes
+  const registryVersion = useSyncExternalStore(
+    subscribeToSlaveClientRegistry,
+    getSlaveClientRegistryVersion,
+    getSlaveClientRegistryVersion,
+  )
+
+  // Subscribe to send-override changes so mute recalculates after /send completes
+  const sendOverrideVersion = useSyncExternalStore(
+    subscribeSendOverride,
+    getSendOverrideVersion,
+    getSendOverrideVersion,
+  )
+
+  const prevMutedRef = useRef<Set<string>>(new Set())
+
+  useEffect(() => {
+    const slaves = getAllSlaveClients()
+
+    // Compute which slaves should be muted now
+    const nextMuted = new Set<string>()
+    if (routeMode === 'local') {
+      // All connected slaves muted
+      for (const name of slaves.keys()) {
+        if (!hasSendOverride(name)) {
+          nextMuted.add(name)
+        }
+      }
+    } else {
+      // routeMode === 'selected': mute slaves NOT in selectedPipes
+      const selectedSet = new Set(selectedPipes)
+      for (const name of slaves.keys()) {
+        if (!selectedSet.has(name) && !hasSendOverride(name)) {
+          nextMuted.add(name)
+        }
+      }
+    }
+
+    // Step 1: Update master-side muted set FIRST (before sending control packets)
+    setMasterMutedPipes(nextMuted)
+
+    const prevMuted = prevMutedRef.current
+
+    // Step 2: For newly muted slaves — abort pending permissions, then send relay_mute
+    for (const name of nextMuted) {
+      if (!prevMuted.has(name)) {
+        // Abort pending permission prompts for this slave
+        setToolUseConfirmQueue((queue: Record<string, unknown>[]) => {
+          const toAbort = queue.filter(
+            (item: Record<string, unknown>) => item.pipeName === name,
+          )
+          for (const item of toAbort) {
+            try {
+              ;(item.onAbort as (() => void) | undefined)?.()
+            } catch {
+              // onAbort may throw if client disconnected — safe to ignore
+            }
+          }
+          return queue.filter((item: Record<string, unknown>) => item.pipeName !== name)
+        })
+
+        // Send relay_mute to slave
+        const client = slaves.get(name)
+        if (client?.connected) {
+          try {
+            client.send({ type: 'relay_mute' })
+          } catch {
+            // send may fail if socket is closing — non-fatal
+          }
+        }
+      }
+    }
+
+    // Step 3: For newly unmuted slaves — send relay_unmute
+    for (const name of prevMuted) {
+      if (!nextMuted.has(name)) {
+        const client = slaves.get(name)
+        if (client?.connected) {
+          try {
+            client.send({ type: 'relay_unmute' })
+          } catch {
+            // non-fatal
+          }
+        }
+      }
+    }
+
+    prevMutedRef.current = nextMuted
+  }, [routeMode, selectedPipes, registryVersion, sendOverrideVersion, setToolUseConfirmQueue])
+
+  // Cleanup on unmount: clear all master-side mute state
+  useEffect(() => {
+    return () => {
+      clearMasterMutedPipes()
+      clearSendOverrides()
+    }
+  }, [])
+}
diff --git a/src/hooks/usePipePermissionForward.ts b/src/hooks/usePipePermissionForward.ts
index 599e0c21e..66e01b4a6 100644
--- a/src/hooks/usePipePermissionForward.ts
+++ b/src/hooks/usePipePermissionForward.ts
@@ -90,6 +90,7 @@ export function usePipePermissionForward({
                 input: payload.input,
                 toolUseContext,
                 toolUseID: `pipe:${payload.requestId}`,
+                pipeName,
                 permissionResult: payload.permissionResult,
                 permissionPromptStartTimeMs:
                   payload.permissionPromptStartTimeMs,
diff --git a/src/hooks/usePipeRelay.ts b/src/hooks/usePipeRelay.ts
index 7ad10c5b1..313d54720 100644
--- a/src/hooks/usePipeRelay.ts
+++ b/src/hooks/usePipeRelay.ts
@@ -6,7 +6,7 @@
  * `getPipeRelay()` singleton set by usePipeIpc's attach handler.
  */
 import { useRef, useCallback } from 'react'
-import { getPipeRelay } from '../utils/pipePermissionRelay.js'
+import { getPipeRelay, isRelayMuted } from '../utils/pipePermissionRelay.js'
 import type { PipeMessage } from '../utils/pipeTransport.js'
 
 export type PipeRelayHandle = {
@@ -29,6 +29,9 @@ export function usePipeRelay(): PipeRelayHandle {
       if (typeof relay !== 'function') {
         return false
       }
+      if (isRelayMuted()) {
+        return false
+      }
       relay(message)
       return true
     },
diff --git a/src/hooks/useScheduledTasks.ts b/src/hooks/useScheduledTasks.ts
index 1bdff1223..e1dadbe85 100644
--- a/src/hooks/useScheduledTasks.ts
+++ b/src/hooks/useScheduledTasks.ts
@@ -7,9 +7,12 @@ import {
 } from '../tasks/InProcessTeammateTask/InProcessTeammateTask.js'
 import { isKairosCronEnabled } from '@claude-code-best/builtin-tools/tools/ScheduleCronTool/prompt.js'
 import type { Message } from '../types/message.js'
+import { getCwd } from '../utils/cwd.js'
 import { getCronJitterConfig } from '../utils/cronJitterConfig.js'
 import { createCronScheduler } from '../utils/cronScheduler.js'
 import { removeCronTasks } from '../utils/cronTasks.js'
+import { createAutonomyQueuedPrompt } from '../utils/autonomyRuns.js'
+import { markAutonomyRunFailed } from '../utils/autonomyRuns.js'
 import { logForDebugging } from '../utils/debug.js'
 import { enqueuePendingNotification } from '../utils/messageQueueManager.js'
 import { createScheduledTaskFireMessage } from '../utils/messages.js'
@@ -68,50 +71,92 @@ export function useScheduledTasks({
     // forward isMeta, so their messages remain visible in the
     // transcript. This is acceptable since normal mode is not the
     // primary use case for scheduled tasks.
-    const enqueueForLead = (prompt: string) =>
-      enqueuePendingNotification({
-        value: prompt,
-        mode: 'prompt',
-        priority: 'later',
-        isMeta: true,
-        // Threaded through to cc_workload= in the billing-header
-        // attribution block so the API can serve cron-initiated requests
-        // at lower QoS when capacity is tight. No human is actively
-        // waiting on this response.
+    const enqueueForLead = async (prompt: string) => {
+      const command = await createAutonomyQueuedPrompt({
+        basePrompt: prompt,
+        trigger: 'scheduled-task',
+        currentDir: getCwd(),
         workload: WORKLOAD_CRON,
       })
+      if (!command) {
+        return
+      }
+      enqueuePendingNotification(command)
+    }
 
     const scheduler = createCronScheduler({
       // Missed-task surfacing (onFire fallback). Teammate crons are always
       // session-only (durable:false) so they never appear in the missed list,
       // which is populated from disk at scheduler startup — this path only
       // handles team-lead durable crons.
-      onFire: enqueueForLead,
+      onFire: prompt => {
+        void enqueueForLead(prompt)
+      },
       // Normal fires receive the full CronTask so we can route by agentId.
       onFireTask: task => {
-        if (task.agentId) {
-          const teammate = findTeammateTaskByAgentId(
-            task.agentId,
-            store.getState().tasks,
-          )
-          if (teammate && !isTerminalTaskStatus(teammate.status)) {
-            injectUserMessageToTeammate(teammate.id, task.prompt, setAppState)
+        void (async () => {
+          if (task.agentId) {
+            const teammate = findTeammateTaskByAgentId(
+              task.agentId,
+              store.getState().tasks,
+            )
+            if (teammate && !isTerminalTaskStatus(teammate.status)) {
+              const command = await createAutonomyQueuedPrompt({
+                basePrompt: task.prompt,
+                trigger: 'scheduled-task',
+                currentDir: getCwd(),
+                sourceId: task.id,
+                sourceLabel: task.prompt,
+                workload: WORKLOAD_CRON,
+              })
+              if (!command) {
+                return
+              }
+              const injected = injectUserMessageToTeammate(
+                teammate.id,
+                command.value as string,
+                {
+                  autonomyRunId: command.autonomy?.runId,
+                  origin: command.origin,
+                },
+                setAppState,
+              )
+              if (!injected && command.autonomy?.runId) {
+                await markAutonomyRunFailed(
+                  command.autonomy.runId,
+                  `Teammate ${task.agentId} exited before the scheduled message could be delivered.`,
+                )
+              }
+              return
+            }
+            // Teammate is gone — clean up the orphaned cron so it doesn't keep
+            // firing into nowhere every tick. One-shots would auto-delete on
+            // fire anyway, but recurring crons would loop until auto-expiry.
+            logForDebugging(
+              `[ScheduledTasks] teammate ${task.agentId} gone, removing orphaned cron ${task.id}`,
+            )
+            void removeCronTasks([task.id])
+            return
+          }
+
+          const command = await createAutonomyQueuedPrompt({
+            basePrompt: task.prompt,
+            trigger: 'scheduled-task',
+            currentDir: getCwd(),
+            sourceId: task.id,
+            sourceLabel: task.prompt,
+            workload: WORKLOAD_CRON,
+          })
+          if (!command) {
             return
           }
-          // Teammate is gone — clean up the orphaned cron so it doesn't keep
-          // firing into nowhere every tick. One-shots would auto-delete on
-          // fire anyway, but recurring crons would loop until auto-expiry.
-          logForDebugging(
-            `[ScheduledTasks] teammate ${task.agentId} gone, removing orphaned cron ${task.id}`,
+
+          const msg = createScheduledTaskFireMessage(
+            `Running scheduled task (${formatCronFireTime(new Date())})`,
           )
-          void removeCronTasks([task.id])
-          return
-        }
-        const msg = createScheduledTaskFireMessage(
-          `Running scheduled task (${formatCronFireTime(new Date())})`,
-        )
-        setMessages(prev => [...prev, msg])
-        enqueueForLead(task.prompt)
+          setMessages(prev => [...prev, msg])
+          enqueuePendingNotification(command)
+        })()
       },
       isLoading: () => isLoadingRef.current,
       assistantMode,
diff --git a/src/jobs/__tests__/classifier.test.ts b/src/jobs/__tests__/classifier.test.ts
new file mode 100644
index 000000000..74300b235
--- /dev/null
+++ b/src/jobs/__tests__/classifier.test.ts
@@ -0,0 +1,140 @@
+/**
+ * Tests for src/jobs/classifier.ts
+ *
+ * Uses real temp directories instead of mocking fs to avoid
+ * cross-test mock pollution in bun test.
+ *
+ * classifier.ts takes jobDir as a parameter, so no envUtils mock needed.
+ */
+import { describe, expect, test, beforeEach, afterAll } from 'bun:test'
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+import type { AssistantMessage } from '../../types/message.js'
+import { classifyAndWriteState } from '../classifier.js'
+
+// ─── setup: real temp dir ──────────────────────────────────────────────────
+
+let tempBase: string
+let jobDir: string
+let stateFile: string
+
+tempBase = mkdtempSync(join(tmpdir(), 'classifier-test-'))
+
+function freshJobDir(): void {
+  jobDir = mkdtempSync(join(tempBase, 'job-'))
+  stateFile = join(jobDir, 'state.json')
+}
+
+// ─── helpers ────────────────────────────────────────────────────────────────
+
+function makeAssistantMessage(
+  content: any[],
+  extra: Record<string, any> = {},
+): AssistantMessage {
+  return {
+    type: 'assistant',
+    uuid: '00000000-0000-0000-0000-000000000000' as any,
+    message: {
+      role: 'assistant',
+      content,
+      ...extra,
+    },
+  } as any
+}
+
+// ─── lifecycle ─────────────────────────────────────────────────────────────
+
+beforeEach(() => {
+  freshJobDir()
+})
+
+afterAll(() => {
+  try {
+    rmSync(tempBase, { recursive: true, force: true })
+  } catch {
+    // best-effort cleanup
+  }
+})
+
+// ─── tests ──────────────────────────────────────────────────────────────────
+
+describe('classifyAndWriteState', () => {
+  test('does nothing when state.json is missing', async () => {
+    await classifyAndWriteState(jobDir, [])
+    // stateFile should still not exist
+    let exists = false
+    try {
+      readFileSync(stateFile, 'utf-8')
+      exists = true
+    } catch {
+      // expected
+    }
+    expect(exists).toBe(false)
+  })
+
+  test('sets status to running when last message has tool_use block', async () => {
+    writeFileSync(
+      stateFile,
+      JSON.stringify({ status: 'created', updatedAt: '2026-01-01' }),
+      'utf-8',
+    )
+
+    const msg = makeAssistantMessage([
+      { type: 'text', text: 'Let me check...' },
+      { type: 'tool_use', id: 'toolu_1', name: 'bash', input: {} },
+    ])
+
+    await classifyAndWriteState(jobDir, [msg])
+
+    const state = JSON.parse(readFileSync(stateFile, 'utf-8'))
+    expect(state.status).toBe('running')
+  })
+
+  test('sets status to completed when stop_reason is end_turn', async () => {
+    writeFileSync(
+      stateFile,
+      JSON.stringify({ status: 'running', updatedAt: '2026-01-01' }),
+      'utf-8',
+    )
+
+    const msg = makeAssistantMessage([{ type: 'text', text: 'All done.' }], {
+      stop_reason: 'end_turn',
+    })
+
+    await classifyAndWriteState(jobDir, [msg])
+
+    const state = JSON.parse(readFileSync(stateFile, 'utf-8'))
+    expect(state.status).toBe('completed')
+  })
+
+  test('sets status to running for empty messages (state exists)', async () => {
+    writeFileSync(
+      stateFile,
+      JSON.stringify({ status: 'created', updatedAt: '2026-01-01' }),
+      'utf-8',
+    )
+
+    await classifyAndWriteState(jobDir, [])
+
+    const state = JSON.parse(readFileSync(stateFile, 'utf-8'))
+    expect(state.status).toBe('running')
+  })
+
+  test('sets status to running when stop_reason is max_tokens', async () => {
+    writeFileSync(
+      stateFile,
+      JSON.stringify({ status: 'running', updatedAt: '2026-01-01' }),
+      'utf-8',
+    )
+
+    const msg = makeAssistantMessage([{ type: 'text', text: 'I need more' }], {
+      stop_reason: 'max_tokens',
+    })
+
+    await classifyAndWriteState(jobDir, [msg])
+
+    const state = JSON.parse(readFileSync(stateFile, 'utf-8'))
+    expect(state.status).toBe('running')
+  })
+})
diff --git a/src/jobs/__tests__/state.test.ts b/src/jobs/__tests__/state.test.ts
new file mode 100644
index 000000000..990b1b197
--- /dev/null
+++ b/src/jobs/__tests__/state.test.ts
@@ -0,0 +1,91 @@
+/**
+ * Tests for src/jobs/state.ts
+ *
+ * Uses real temp directories and CLAUDE_CONFIG_DIR env var
+ * instead of mocking fs, to avoid cross-test mock pollution.
+ */
+import { describe, expect, test, beforeEach, afterAll } from 'bun:test'
+import { mkdtempSync, rmSync, readFileSync, existsSync } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+
+// ─── setup: real temp dir via env var ──────────────────────────────────────
+
+const tempBase = mkdtempSync(join(tmpdir(), 'jobs-state-test-'))
+
+beforeEach(() => {
+  // Each test gets a fresh config dir
+  const tempHome = mkdtempSync(join(tempBase, 'home-'))
+  process.env.CLAUDE_CONFIG_DIR = tempHome
+})
+
+afterAll(() => {
+  delete process.env.CLAUDE_CONFIG_DIR
+  try {
+    rmSync(tempBase, { recursive: true, force: true })
+  } catch {
+    // best-effort cleanup
+  }
+})
+
+// ─── import ─────────────────────────────────────────────────────────────────
+
+const { createJob, readJobState, appendJobReply, getJobDir } = await import(
+  '../state.js'
+)
+
+// ─── tests ──────────────────────────────────────────────────────────────────
+
+describe('createJob', () => {
+  test('creates job directory and writes state, template, and input files', () => {
+    const dir = createJob('job-1', 'my-template', '# Template', 'hello', [
+      '--flag',
+    ])
+    expect(dir).toContain('job-1')
+    expect(existsSync(dir)).toBe(true)
+
+    const stateFile = join(dir, 'state.json')
+    expect(existsSync(stateFile)).toBe(true)
+    const state = JSON.parse(readFileSync(stateFile, 'utf-8'))
+    expect(state.jobId).toBe('job-1')
+    expect(state.templateName).toBe('my-template')
+    expect(state.status).toBe('created')
+    expect(state.args).toEqual(['--flag'])
+
+    expect(readFileSync(join(dir, 'template.md'), 'utf-8')).toBe('# Template')
+    expect(readFileSync(join(dir, 'input.txt'), 'utf-8')).toBe('hello')
+  })
+})
+
+describe('readJobState', () => {
+  test('returns null when job does not exist', () => {
+    expect(readJobState('nonexistent')).toBeNull()
+  })
+
+  test('returns parsed state when job exists', () => {
+    createJob('job-2', 'tpl', 'content', 'input', [])
+    const result = readJobState('job-2')
+    expect(result).not.toBeNull()
+    expect(result!.jobId).toBe('job-2')
+    expect(result!.status).toBe('created')
+  })
+})
+
+describe('appendJobReply', () => {
+  test('returns false when job does not exist', () => {
+    expect(appendJobReply('no-job', 'hello')).toBe(false)
+  })
+
+  test('appends reply and updates state', () => {
+    createJob('job-3', 'tpl', 'content', 'input', [])
+
+    const result = appendJobReply('job-3', 'my reply')
+    expect(result).toBe(true)
+
+    const dir = getJobDir('job-3')
+    const repliesPath = join(dir, 'replies.jsonl')
+    expect(existsSync(repliesPath)).toBe(true)
+    const replyLine = JSON.parse(readFileSync(repliesPath, 'utf-8').trim())
+    expect(replyLine.text).toBe('my reply')
+  })
+})
diff --git a/src/jobs/__tests__/templates.test.ts b/src/jobs/__tests__/templates.test.ts
new file mode 100644
index 000000000..939032290
--- /dev/null
+++ b/src/jobs/__tests__/templates.test.ts
@@ -0,0 +1,87 @@
+/**
+ * Tests for src/jobs/templates.ts
+ *
+ * Uses real temp directories and CLAUDE_CONFIG_DIR env var
+ * instead of mocking fs, to avoid cross-test mock pollution.
+ */
+import { describe, expect, test, beforeEach, afterAll } from 'bun:test'
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'fs'
+import { join } from 'path'
+import { tmpdir } from 'os'
+
+// ─── setup: real temp dir via env var ──────────────────────────────────────
+
+const tempBase = mkdtempSync(join(tmpdir(), 'jobs-templates-test-'))
+
+beforeEach(() => {
+  const tempHome = mkdtempSync(join(tempBase, 'home-'))
+  process.env.CLAUDE_CONFIG_DIR = tempHome
+})
+
+afterAll(() => {
+  delete process.env.CLAUDE_CONFIG_DIR
+  try {
+    rmSync(tempBase, { recursive: true, force: true })
+  } catch {
+    // best-effort cleanup
+  }
+})
+
+// ─── import ─────────────────────────────────────────────────────────────────
+
+const { listTemplates, loadTemplate } = await import('../templates.js')
+
+// ─── tests ──────────────────────────────────────────────────────────────────
+
+describe('listTemplates', () => {
+  test('returns empty array when no template dirs exist', () => {
+    const result = listTemplates()
+    expect(result).toEqual([])
+  })
+
+  test('discovers templates from user-level dir', () => {
+    const userDir = join(process.env.CLAUDE_CONFIG_DIR!, 'templates')
+    mkdirSync(userDir, { recursive: true })
+    writeFileSync(
+      join(userDir, 'greeting.md'),
+      '---\ndescription: A greeting template\n---\nHello {{name}}',
+      'utf-8',
+    )
+
+    const result = listTemplates()
+    expect(result.length).toBe(1)
+    expect(result[0]!.name).toBe('greeting')
+    expect(result[0]!.description).toBe('A greeting template')
+    expect(result[0]!.content).toBe('Hello {{name}}')
+  })
+
+  test('skips non-md files', () => {
+    const userDir = join(process.env.CLAUDE_CONFIG_DIR!, 'templates')
+    mkdirSync(userDir, { recursive: true })
+    writeFileSync(join(userDir, 'notes.txt'), 'not a template', 'utf-8')
+    writeFileSync(join(userDir, 'data.json'), '{}', 'utf-8')
+
+    const result = listTemplates()
+    expect(result).toEqual([])
+  })
+})
+
+describe('loadTemplate', () => {
+  test('returns null when template not found', () => {
+    expect(loadTemplate('nonexistent')).toBeNull()
+  })
+
+  test('returns template by name', () => {
+    const userDir = join(process.env.CLAUDE_CONFIG_DIR!, 'templates')
+    mkdirSync(userDir, { recursive: true })
+    writeFileSync(
+      join(userDir, 'deploy.md'),
+      '---\ndescription: Deploy script\n---\nrun deploy',
+      'utf-8',
+    )
+
+    const result = loadTemplate('deploy')
+    expect(result).not.toBeNull()
+    expect(result!.name).toBe('deploy')
+  })
+})
diff --git a/src/jobs/classifier.ts b/src/jobs/classifier.ts
index 8cd26637e..483e3bca3 100644
--- a/src/jobs/classifier.ts
+++ b/src/jobs/classifier.ts
@@ -1,3 +1,67 @@
-// Auto-generated stub — replace with real implementation
-export {};
-export const classifyAndWriteState: (...args: unknown[]) => Promise<void> = () => Promise.resolve();
+import { readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import type { AssistantMessage } from '../types/message.js'
+
+/**
+ * Classify the job status from the turn's assistant messages and update state.json.
+ *
+ * Called by stopHooks.ts after each repl_main_thread turn when CLAUDE_JOB_DIR is set.
+ * Only the main thread calls this (not subagents).
+ *
+ * @param jobDir - Path to the job directory (from CLAUDE_JOB_DIR env)
+ * @param assistantMessages - Assistant messages from this turn
+ */
+export async function classifyAndWriteState(
+  jobDir: string,
+  assistantMessages: AssistantMessage[],
+): Promise<void> {
+  const stateFile = join(jobDir, 'state.json')
+
+  let state: Record<string, unknown>
+  try {
+    state = JSON.parse(readFileSync(stateFile, 'utf-8'))
+  } catch {
+    // No state file or corrupt — not a valid job directory
+    return
+  }
+
+  const newStatus = classifyStatus(assistantMessages)
+  state.status = newStatus
+  state.updatedAt = new Date().toISOString()
+
+  writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf-8')
+}
+
+/**
+ * Determine job status from assistant messages.
+ *
+ * - Has tool_use blocks → still running (tools executing)
+ * - stop_reason === 'end_turn' → completed (model finished)
+ * - Otherwise → running
+ */
+function classifyStatus(messages: AssistantMessage[]): string {
+  if (messages.length === 0) return 'running'
+
+  const lastMessage = messages[messages.length - 1]!
+  const content = lastMessage.message?.content
+
+  // Check if the last message has tool_use blocks (still executing)
+  if (Array.isArray(content)) {
+    const hasToolUse = content.some(
+      block =>
+        typeof block === 'object' &&
+        block !== null &&
+        'type' in block &&
+        block.type === 'tool_use',
+    )
+    if (hasToolUse) return 'running'
+  }
+
+  // Check stop_reason via index signature
+  const stopReason = (lastMessage.message as Record<string, unknown>)
+    ?.stop_reason
+  if (stopReason === 'end_turn') return 'completed'
+  if (stopReason === 'max_tokens') return 'running'
+
+  return 'running'
+}
diff --git a/src/jobs/state.ts b/src/jobs/state.ts
new file mode 100644
index 000000000..dee64e178
--- /dev/null
+++ b/src/jobs/state.ts
@@ -0,0 +1,102 @@
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { getClaudeConfigHomeDir } from '../utils/envUtils.js'
+
+export interface JobState {
+  jobId: string
+  templateName: string
+  createdAt: string
+  updatedAt: string
+  status: 'created' | 'running' | 'completed' | 'failed'
+  args: string[]
+}
+
+function getJobsDir(): string {
+  return join(getClaudeConfigHomeDir(), 'jobs')
+}
+
+export function getJobDir(jobId: string): string {
+  return join(getJobsDir(), jobId)
+}
+
+/**
+ * Create a new job directory with initial state.
+ */
+export function createJob(
+  jobId: string,
+  templateName: string,
+  templateContent: string,
+  inputText: string,
+  args: string[],
+): string {
+  const dir = getJobDir(jobId)
+  mkdirSync(dir, { recursive: true })
+
+  const now = new Date().toISOString()
+  const state: JobState = {
+    jobId,
+    templateName,
+    createdAt: now,
+    updatedAt: now,
+    status: 'created',
+    args,
+  }
+
+  writeFileSync(
+    join(dir, 'state.json'),
+    JSON.stringify(state, null, 2),
+    'utf-8',
+  )
+  writeFileSync(join(dir, 'template.md'), templateContent, 'utf-8')
+  writeFileSync(join(dir, 'input.txt'), inputText, 'utf-8')
+
+  return dir
+}
+
+/**
+ * Read job state from disk.
+ */
+export function readJobState(jobId: string): JobState | null {
+  try {
+    const raw = readFileSync(join(getJobDir(jobId), 'state.json'), 'utf-8')
+    const parsed: unknown = JSON.parse(raw)
+    if (typeof parsed !== 'object' || parsed === null) return null
+    const obj = parsed as Record<string, unknown>
+    if (typeof obj.jobId !== 'string' || typeof obj.status !== 'string') {
+      return null
+    }
+    return obj as unknown as JobState
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Append a reply to a job.
+ */
+export function appendJobReply(jobId: string, text: string): boolean {
+  const dir = getJobDir(jobId)
+  const state = readJobState(jobId)
+  if (!state) return false
+
+  const repliesPath = join(dir, 'replies.jsonl')
+  const entry = JSON.stringify({
+    text,
+    timestamp: new Date().toISOString(),
+  })
+
+  try {
+    appendFileSync(repliesPath, entry + '\n', 'utf-8')
+  } catch {
+    writeFileSync(repliesPath, entry + '\n', 'utf-8')
+  }
+
+  const updated = { ...state, updatedAt: new Date().toISOString() }
+  writeFileSync(
+    join(dir, 'state.json'),
+    JSON.stringify(updated, null, 2),
+    'utf-8',
+  )
+
+  return true
+}
diff --git a/src/jobs/templates.ts b/src/jobs/templates.ts
new file mode 100644
index 000000000..15ec28036
--- /dev/null
+++ b/src/jobs/templates.ts
@@ -0,0 +1,86 @@
+import { readdirSync, readFileSync } from 'fs'
+import { join, basename } from 'path'
+import { parseFrontmatter } from '../utils/frontmatterParser.js'
+import type { FrontmatterData } from '../utils/frontmatterParser.js'
+import { getClaudeConfigHomeDir } from '../utils/envUtils.js'
+import {
+  getProjectDirsUpToHome,
+  extractDescriptionFromMarkdown,
+  type ClaudeConfigDirectory,
+} from '../utils/markdownConfigLoader.js'
+
+export interface TemplateInfo {
+  name: string
+  description: string
+  filePath: string
+  frontmatter: FrontmatterData
+  content: string
+}
+
+/**
+ * Discover .claude/templates directories from CWD up to git root,
+ * plus the user-level ~/.claude/templates.
+ */
+function getTemplatesDirs(): string[] {
+  const projectDirs = getProjectDirsUpToHome(
+    'templates' as ClaudeConfigDirectory,
+    process.cwd(),
+  )
+
+  // User-level dir (getProjectDirsUpToHome stops before home)
+  const userDir = join(getClaudeConfigHomeDir(), 'templates')
+  try {
+    readdirSync(userDir)
+    return [...projectDirs, userDir]
+  } catch {
+    return projectDirs
+  }
+}
+
+/**
+ * List all available templates.
+ */
+export function listTemplates(): TemplateInfo[] {
+  const templates: TemplateInfo[] = []
+  const seenNames = new Set<string>()
+
+  for (const dir of getTemplatesDirs()) {
+    let files: string[]
+    try {
+      files = readdirSync(dir)
+    } catch {
+      continue
+    }
+
+    for (const file of files) {
+      if (!file.endsWith('.md')) continue
+      const name = basename(file, '.md')
+      if (seenNames.has(name)) continue
+      seenNames.add(name)
+
+      const filePath = join(dir, file)
+      try {
+        const raw = readFileSync(filePath, 'utf-8')
+        const { frontmatter, content } = parseFrontmatter(raw, filePath)
+        const description =
+          (typeof frontmatter.description === 'string'
+            ? frontmatter.description
+            : '') || extractDescriptionFromMarkdown(content, 'No description')
+
+        templates.push({ name, description, filePath, frontmatter, content })
+      } catch {
+        // Skip unreadable files
+      }
+    }
+  }
+
+  return templates
+}
+
+/**
+ * Load a specific template by name.
+ */
+export function loadTemplate(name: string): TemplateInfo | null {
+  const all = listTemplates()
+  return all.find(t => t.name === name) ?? null
+}
diff --git a/src/main.tsx b/src/main.tsx
index 58f278b01..ecb8ff067 100644
--- a/src/main.tsx
+++ b/src/main.tsx
@@ -1802,9 +1802,11 @@ async function run(): Promise<CommanderCommand> {
 			}
 			if (
 				feature("KAIROS") &&
-				assistantModule?.isAssistantMode() &&
+				assistantModule &&
+				(assistantModule.isAssistantForced() ||
+					(options as Record<string, unknown>).assistant === true) &&
 				// Spawned teammates share the leader's cwd + settings.json, so
-				// isAssistantMode() is true for them too. --agent-id being set
+				// the flag is true for them too. --agent-id being set
 				// means we ARE a spawned teammate (extractTeammateOptions runs
 				// ~170 lines later so check the raw commander option) — don't
 				// re-init the team or override teammateMode/proactive/brief.
diff --git a/src/proactive/__tests__/state.baseline.test.ts b/src/proactive/__tests__/state.baseline.test.ts
new file mode 100644
index 000000000..3bd73faf4
--- /dev/null
+++ b/src/proactive/__tests__/state.baseline.test.ts
@@ -0,0 +1,80 @@
+import { beforeEach, describe, expect, test } from 'bun:test'
+import {
+  activateProactive,
+  deactivateProactive,
+  getActivationSource,
+  getNextTickAt,
+  isContextBlocked,
+  isProactiveActive,
+  isProactivePaused,
+  pauseProactive,
+  resumeProactive,
+  setContextBlocked,
+  setNextTickAt,
+  shouldTick,
+  subscribeToProactiveChanges,
+} from '../index'
+
+function resetProactiveState() {
+  activateProactive('reset')
+  setContextBlocked(false)
+  setNextTickAt(null)
+  deactivateProactive()
+}
+
+beforeEach(() => {
+  resetProactiveState()
+})
+
+describe('proactive state baseline', () => {
+  test('activateProactive enables proactive mode and records the source', () => {
+    activateProactive('baseline_test')
+
+    expect(isProactiveActive()).toBe(true)
+    expect(isProactivePaused()).toBe(false)
+    expect(isContextBlocked()).toBe(false)
+    expect(getActivationSource()).toBe('baseline_test')
+    expect(shouldTick()).toBe(true)
+  })
+
+  test('pauseProactive suppresses ticking and clears nextTickAt', () => {
+    activateProactive('pause_case')
+    setNextTickAt(Date.now() + 30_000)
+
+    pauseProactive()
+
+    expect(isProactivePaused()).toBe(true)
+    expect(getNextTickAt()).toBeNull()
+    expect(shouldTick()).toBe(false)
+
+    resumeProactive()
+    expect(isProactivePaused()).toBe(false)
+    expect(shouldTick()).toBe(true)
+  })
+
+  test('setContextBlocked clears nextTickAt and blocks ticking', () => {
+    activateProactive('blocked_case')
+    setNextTickAt(Date.now() + 5_000)
+
+    setContextBlocked(true)
+
+    expect(isContextBlocked()).toBe(true)
+    expect(getNextTickAt()).toBeNull()
+    expect(shouldTick()).toBe(false)
+  })
+
+  test('subscribers are notified on state changes', () => {
+    let notifications = 0
+    const unsubscribe = subscribeToProactiveChanges(() => {
+      notifications += 1
+    })
+
+    activateProactive('subscriber_case')
+    setNextTickAt(Date.now() + 1_000)
+    setContextBlocked(true)
+    deactivateProactive()
+    unsubscribe()
+
+    expect(notifications).toBeGreaterThanOrEqual(3)
+  })
+})
diff --git a/src/proactive/useProactive.ts b/src/proactive/useProactive.ts
index 12e7721d1..aa79ef758 100644
--- a/src/proactive/useProactive.ts
+++ b/src/proactive/useProactive.ts
@@ -6,7 +6,10 @@
  * proactive mode is active and not blocked.
  */
 import { useEffect, useRef } from 'react'
+import type { QueuedCommand } from '../types/textInputTypes.js'
 import { TICK_TAG } from '../constants/xml.js'
+import { getCwd } from '../utils/cwd.js'
+import { createProactiveAutonomyCommands } from '../utils/autonomyRuns.js'
 import {
   isProactiveActive,
   isProactivePaused,
@@ -24,8 +27,7 @@ type UseProactiveOpts = {
   queuedCommandsLength: number
   hasActiveLocalJsxUI: boolean
   isInPlanMode: boolean
-  onSubmitTick: (prompt: string) => void
-  onQueueTick: (prompt: string) => void
+  onQueueTick: (command: QueuedCommand) => void
 }
 
 export function useProactive(opts: UseProactiveOpts): void {
@@ -70,14 +72,19 @@ export function useProactive(opts: UseProactiveOpts): void {
           return
         }
 
-        const tickContent = `<${TICK_TAG}>${new Date().toLocaleTimeString()}</${TICK_TAG}>`
-
-        // If nothing is in the queue, submit directly; otherwise queue
-        if (queuedCommandsLength === 0) {
-          optsRef.current.onSubmitTick(tickContent)
-        } else {
-          optsRef.current.onQueueTick(tickContent)
-        }
+        void (async () => {
+          const commands = await createProactiveAutonomyCommands({
+            basePrompt: `<${TICK_TAG}>${new Date().toLocaleTimeString()}</${TICK_TAG}>`,
+            currentDir: getCwd(),
+          })
+          for (const command of commands) {
+            // Always queue proactive turns. This avoids races where the prompt
+            // is built asynchronously, a user turn starts meanwhile, and a
+            // direct-submit path would silently drop the autonomy turn after
+            // consuming its heartbeat due-state.
+            optsRef.current.onQueueTick(command)
+          }
+        })()
 
         // Schedule next tick
         scheduleTick()
diff --git a/src/screens/REPL.tsx b/src/screens/REPL.tsx
index 4af35add2..e9d90cd99 100644
--- a/src/screens/REPL.tsx
+++ b/src/screens/REPL.tsx
@@ -14,18 +14,27 @@ import { dirname, join } from 'path';
 import { tmpdir } from 'os';
 import figures from 'figures';
 // eslint-disable-next-line custom-rules/prefer-use-keybindings -- / n N Esc [ v are bare letters in transcript modal context, same class as g/G/j/k in ScrollKeybindingHandler
-import { useInput } from '@anthropic/ink'
-import { useSearchInput } from '../hooks/useSearchInput.js'
-import { useTerminalSize } from '../hooks/useTerminalSize.js'
-import { useSearchHighlight } from '@anthropic/ink'
-import type { JumpHandle } from '../components/VirtualMessageList.js'
-import { renderMessagesToPlainText } from '../utils/exportRenderer.js'
-import { openFileInExternalEditor } from '../utils/editor.js'
-import { writeFile } from 'fs/promises'
-import { type TabStatusKind, Box, Text, useStdin, useTheme, useTerminalFocus, useTerminalTitle, useTabStatus } from '@anthropic/ink'
-import { CostThresholdDialog } from '../components/CostThresholdDialog.js'
-import { IdleReturnDialog } from '../components/IdleReturnDialog.js'
-import * as React from 'react'
+import { useInput } from '@anthropic/ink';
+import { useSearchInput } from '../hooks/useSearchInput.js';
+import { useTerminalSize } from '../hooks/useTerminalSize.js';
+import { useSearchHighlight } from '@anthropic/ink';
+import type { JumpHandle } from '../components/VirtualMessageList.js';
+import { renderMessagesToPlainText } from '../utils/exportRenderer.js';
+import { openFileInExternalEditor } from '../utils/editor.js';
+import { writeFile } from 'fs/promises';
+import {
+  type TabStatusKind,
+  Box,
+  Text,
+  useStdin,
+  useTheme,
+  useTerminalFocus,
+  useTerminalTitle,
+  useTabStatus,
+} from '@anthropic/ink';
+import { CostThresholdDialog } from '../components/CostThresholdDialog.js';
+import { IdleReturnDialog } from '../components/IdleReturnDialog.js';
+import * as React from 'react';
 import {
   useEffect,
   useMemo,
@@ -35,14 +44,11 @@ import {
   useDeferredValue,
   useLayoutEffect,
   type RefObject,
-} from 'react'
-import { useNotifications } from '../context/notifications.js'
-import { sendNotification } from '../services/notifier.js'
-import {
-  startPreventSleep,
-  stopPreventSleep,
-} from '../services/preventSleep.js'
-import { useTerminalNotification, hasCursorUpViewportYankBug } from '@anthropic/ink'
+} from 'react';
+import { useNotifications } from '../context/notifications.js';
+import { sendNotification } from '../services/notifier.js';
+import { startPreventSleep, stopPreventSleep } from '../services/preventSleep.js';
+import { useTerminalNotification, hasCursorUpViewportYankBug } from '@anthropic/ink';
 import {
   createFileStateCacheWithSizeLimit,
   mergeFileStateCaches,
@@ -72,6 +78,11 @@ import { QueryGuard } from '../utils/QueryGuard.js';
 import { isEnvTruthy } from '../utils/envUtils.js';
 import { formatTokens, truncateToWidth } from '../utils/format.js';
 import { consumeEarlyInput } from '../utils/earlyInput.js';
+import {
+  finalizeAutonomyRunCompleted,
+  finalizeAutonomyRunFailed,
+  markAutonomyRunRunning,
+} from '../utils/autonomyRuns.js';
 
 import { setMemberActive } from '../utils/swarm/teamHelpers.js';
 import {
@@ -155,9 +166,10 @@ import { CancelRequestHandler } from '../hooks/useCancelRequest.js';
 import { useBackgroundTaskNavigation } from '../hooks/useBackgroundTaskNavigation.js';
 import { useSwarmInitialization } from '../hooks/useSwarmInitialization.js';
 import { useTeammateViewAutoExit } from '../hooks/useTeammateViewAutoExit.js';
-import { errorMessage } from '../utils/errors.js';
+import { errorMessage, toError } from '../utils/errors.js';
 import { isHumanTurn } from '../utils/messagePredicates.js';
 import { logError } from '../utils/log.js';
+import { getCwd } from '../utils/cwd.js';
 // Dead code elimination: conditional imports
 /* eslint-disable custom-rules/no-process-env-top-level, @typescript-eslint/no-require-imports */
 const useVoiceIntegration: typeof import('../hooks/useVoiceIntegration.js').useVoiceIntegration = feature('VOICE_MODE')
@@ -346,6 +358,7 @@ const usePipeRelay = feature('UDS_INBOX')
 const usePipePermissionForward = feature('UDS_INBOX')
   ? require('../hooks/usePipePermissionForward.js').usePipePermissionForward
   : () => undefined;
+const usePipeMuteSync = feature('UDS_INBOX') ? require('../hooks/usePipeMuteSync.js').usePipeMuteSync : () => undefined;
 const usePipeRouter = feature('UDS_INBOX')
   ? require('../hooks/usePipeRouter.js').usePipeRouter
   : () => ({ routeToSelectedPipes: () => false });
@@ -465,21 +478,13 @@ import { UltraplanChoiceDialog } from '../components/ultraplan/UltraplanChoiceDi
 import { UltraplanLaunchDialog } from '../components/ultraplan/UltraplanLaunchDialog.js';
 import { launchUltraplan } from '../commands/ultraplan.js';
 // Session manager removed - using AppState now
-import type { RemoteSessionConfig } from '../remote/RemoteSessionManager.js'
-import { REMOTE_SAFE_COMMANDS } from '../commands.js'
-import type { RemoteMessageContent } from '../utils/teleport/api.js'
-import {
-  FullscreenLayout,
-  useUnseenDivider,
-  computeUnseenDivider,
-} from '../components/FullscreenLayout.js'
-import {
-  isFullscreenEnvEnabled,
-  maybeGetTmuxMouseHint,
-  isMouseTrackingEnabled,
-} from '../utils/fullscreen.js'
-import { AlternateScreen } from '@anthropic/ink'
-import { ScrollKeybindingHandler } from '../components/ScrollKeybindingHandler.js'
+import type { RemoteSessionConfig } from '../remote/RemoteSessionManager.js';
+import { REMOTE_SAFE_COMMANDS } from '../commands.js';
+import type { RemoteMessageContent } from '../utils/teleport/api.js';
+import { FullscreenLayout, useUnseenDivider, computeUnseenDivider } from '../components/FullscreenLayout.js';
+import { isFullscreenEnvEnabled, maybeGetTmuxMouseHint, isMouseTrackingEnabled } from '../utils/fullscreen.js';
+import { AlternateScreen } from '@anthropic/ink';
+import { ScrollKeybindingHandler } from '../components/ScrollKeybindingHandler.js';
 import {
   useMessageActions,
   MessageActionsKeybindings,
@@ -487,13 +492,10 @@ import {
   type MessageActionsState,
   type MessageActionsNav,
   type MessageActionCaps,
-} from '../components/messageActions.js'
-import { setClipboard } from '@anthropic/ink'
-import type { ScrollBoxHandle } from '@anthropic/ink'
-import {
-  createAttachmentMessage,
-  getQueuedCommandAttachments,
-} from '../utils/attachments.js'
+} from '../components/messageActions.js';
+import { setClipboard } from '@anthropic/ink';
+import type { ScrollBoxHandle } from '@anthropic/ink';
+import { createAttachmentMessage, getQueuedCommandAttachments } from '../utils/attachments.js';
 
 // Stable empty array for hooks that accept MCPServerConnection[] — avoids
 // creating a new [] literal on every render in remote mode, which would
@@ -1952,7 +1954,8 @@ export function REPL({
     const content = lastAssistant.message?.content;
     const contentArray = Array.isArray(content) ? content : [];
     const inProgressToolUses = contentArray.filter(
-      (b): b is ContentBlock & { type: 'tool_use'; id: string } => b.type === 'tool_use' && inProgressToolUseIDs.has((b as { id: string }).id),
+      (b): b is ContentBlock & { type: 'tool_use'; id: string } =>
+        b.type === 'tool_use' && inProgressToolUseIDs.has((b as { id: string }).id),
     );
     return (
       inProgressToolUses.length > 0 &&
@@ -3066,7 +3069,10 @@ export function REPL({
             if (feature('PROACTIVE') || feature('KAIROS')) {
               proactiveModule?.setContextBlocked(false);
             }
-          } else if (newMessage.type === 'progress' && isEphemeralToolProgress(((newMessage as unknown as { data?: { type?: string } }).data?.type))) {
+          } else if (
+            newMessage.type === 'progress' &&
+            isEphemeralToolProgress((newMessage as unknown as { data?: { type?: string } }).data?.type)
+          ) {
             // Replace the previous ephemeral progress tick for the same tool
             // call instead of appending. Sleep/Bash emit a tick per second and
             // only the last one is rendered; appending blows up the messages
@@ -3198,7 +3204,10 @@ export function REPL({
       // title silently fell through to the "Claude Code" default.
       if (!titleDisabled && !sessionTitle && !agentTitle && !haikuTitleAttemptedRef.current) {
         const firstUserMessage = newMessages.find(m => m.type === 'user' && !m.isMeta);
-        const text = firstUserMessage?.type === 'user' ? getContentText(firstUserMessage.message!.content as string | ContentBlockParam[]) : null;
+        const text =
+          firstUserMessage?.type === 'user'
+            ? getContentText(firstUserMessage.message!.content as string | ContentBlockParam[])
+            : null;
         // Skip synthetic breadcrumbs — slash-command output, prompt-skill
         // expansions (/commit → <command-message>), local-command headers
         // (/help → <command-name>), and bash-mode (!cmd → <bash-input>).
@@ -3353,10 +3362,16 @@ export function REPL({
       }
 
       if (feature('BUDDY') && typeof (globalThis as Record<string, unknown>).fireCompanionObserver === 'function') {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const _fireCompanionObserver = (globalThis as Record<string, any>).fireCompanionObserver as (msgs: unknown, cb: (r: unknown) => void) => void;
+        const _fireCompanionObserver = (globalThis as Record<string, unknown>).fireCompanionObserver as (
+          msgs: unknown,
+          cb: (r: unknown) => void,
+        ) => void;
         void _fireCompanionObserver(messagesRef.current, reaction =>
-          setAppState(prev => (prev.companionReaction === (reaction as typeof prev.companionReaction) ? prev : { ...prev, companionReaction: reaction as typeof prev.companionReaction })),
+          setAppState(prev =>
+            prev.companionReaction === (reaction as typeof prev.companionReaction)
+              ? prev
+              : { ...prev, companionReaction: reaction as typeof prev.companionReaction },
+          ),
         );
       }
 
@@ -3703,10 +3718,7 @@ export function REPL({
         }
       }
 
-      // Atomically: clear initial message, set permission mode and rules, and store plan for verification
-      const shouldStorePlanForVerification =
-        initialMsg.message.planContent && process.env.USER_TYPE === 'ant' && isEnvTruthy(undefined);
-
+      // Atomically: clear initial message, set permission mode and rules
       setAppState(prev => {
         // Build and apply permission updates (mode + allowedPrompts rules)
         let updatedToolPermissionContext = initialMsg.mode
@@ -3729,13 +3741,6 @@ export function REPL({
           ...prev,
           initialMessage: null,
           toolPermissionContext: updatedToolPermissionContext,
-          ...(shouldStorePlanForVerification ? {
-            pendingPlanVerification: {
-              plan: initialMsg.message.planContent as string,
-              verificationStarted: false,
-              verificationCompleted: false,
-            },
-          } : {}),
         };
       });
 
@@ -4299,7 +4304,7 @@ export function REPL({
           });
         }
       } else {
-        injectUserMessageToTeammate(task.id, input, setAppState);
+        injectUserMessageToTeammate(task.id, input, undefined, setAppState);
       }
       setInputValue('');
       helpers.setCursorOffset(0);
@@ -4804,7 +4809,7 @@ export function REPL({
   // Submits incoming prompts from teammate messages or tasks mode as new turns
   // Returns true if submission succeeded, false if a query is already running
   const handleIncomingPrompt = useCallback(
-    (content: string, options?: { isMeta?: boolean }): boolean => {
+    (input: string | QueuedCommand, options?: { isMeta?: boolean }): boolean => {
       if (queryGuard.isActive) return false;
 
       // Defer to user-queued commands — user input always takes priority
@@ -4816,16 +4821,53 @@ export function REPL({
         return false;
       }
 
+      const queuedCommand =
+        typeof input === 'string'
+          ? ({
+              value: input,
+              mode: 'prompt',
+              isMeta: options?.isMeta ? true : undefined,
+            } satisfies QueuedCommand)
+          : input;
+
       const newAbortController = createAbortController();
       setAbortController(newAbortController);
 
       // Create a user message with the formatted content (includes XML wrapper)
       const userMessage = createUserMessage({
-        content,
-        isMeta: options?.isMeta ? true : undefined,
+        content: queuedCommand.value as string,
+        isMeta: queuedCommand.isMeta ? true : undefined,
+        origin: queuedCommand.origin,
       });
 
-      void onQuery([userMessage], newAbortController, true, [], mainLoopModel);
+      const autonomyRunId = queuedCommand.autonomy?.runId;
+      if (autonomyRunId) {
+        void markAutonomyRunRunning(autonomyRunId);
+      }
+
+      void onQuery([userMessage], newAbortController, true, [], mainLoopModel)
+        .then(() => {
+          if (autonomyRunId) {
+            void finalizeAutonomyRunCompleted({
+              runId: autonomyRunId,
+              currentDir: getCwd(),
+              priority: 'later',
+            }).then(nextCommands => {
+              for (const command of nextCommands) {
+                enqueue(command);
+              }
+            });
+          }
+        })
+        .catch((error: unknown) => {
+          if (autonomyRunId) {
+            void finalizeAutonomyRunFailed({
+              runId: autonomyRunId,
+              error: String(error),
+            });
+          }
+          logError(toError(error));
+        });
       return true;
     },
     [onQuery, mainLoopModel, store],
@@ -4856,6 +4898,7 @@ export function REPL({
   const pipeIpcState = useAppState(s => getPipeIpc(s as any));
 
   usePipePermissionForward({ store, tools, setMessages, setToolUseConfirmQueue, getToolUseContext, mainLoopModel });
+  usePipeMuteSync({ setToolUseConfirmQueue });
 
   // Pipe IPC lifecycle — extracted to usePipeIpc hook
   usePipeIpc({ store, handleIncomingPrompt });
@@ -4898,8 +4941,7 @@ export function REPL({
     queuedCommandsLength: queuedCommands.length,
     hasActiveLocalJsxUI: isShowingLocalJSXCommand,
     isInPlanMode: toolPermissionContext.mode === 'plan',
-    onSubmitTick: (prompt: string) => handleIncomingPrompt(prompt, { isMeta: true }),
-    onQueueTick: (prompt: string) => enqueue({ mode: 'prompt', value: prompt, isMeta: true }),
+    onQueueTick: (command: QueuedCommand) => enqueue(command),
   });
 
   // Abort the current operation when a 'now' priority message arrives
@@ -4952,16 +4994,11 @@ export function REPL({
     if (!isLoading) return null;
 
     // Find stop hook progress messages
-    const progressMsgs = messages.filter(
-      (m): m is ProgressMessage<HookProgress> => {
-        if (m.type !== 'progress') return false;
-        const data = m.data as Record<string, unknown>;
-        return (
-          data.type === 'hook_progress' &&
-          (data.hookEvent === 'Stop' || data.hookEvent === 'SubagentStop')
-        );
-      },
-    );
+    const progressMsgs = messages.filter((m): m is ProgressMessage<HookProgress> => {
+      if (m.type !== 'progress') return false;
+      const data = m.data as Record<string, unknown>;
+      return data.type === 'hook_progress' && (data.hookEvent === 'Stop' || data.hookEvent === 'SubagentStop');
+    });
     if (progressMsgs.length === 0) return null;
 
     // Get the most recent stop hook execution
diff --git a/src/services/acp/__tests__/agent.test.ts b/src/services/acp/__tests__/agent.test.ts
new file mode 100644
index 000000000..8dcf3ab51
--- /dev/null
+++ b/src/services/acp/__tests__/agent.test.ts
@@ -0,0 +1,735 @@
+import { describe, expect, test, mock, beforeEach } from 'bun:test'
+
+// ── Heavy module mocks (must be before any import of the module under test) ──
+
+const mockSetModel = mock(() => {})
+
+mock.module('../../../QueryEngine.js', () => ({
+  QueryEngine: class MockQueryEngine {
+    submitMessage = mock(async function* () {})
+    interrupt = mock(() => {})
+    resetAbortController = mock(() => {})
+    getAbortSignal = mock(() => new AbortController().signal)
+    setModel = mockSetModel
+  },
+}))
+
+mock.module('../../../tools.js', () => ({
+  getTools: mock(() => []),
+}))
+
+mock.module('../../../Tool.js', () => ({
+  getEmptyToolPermissionContext: mock(() => ({})),
+}))
+
+mock.module('../../../utils/config.js', () => ({
+  enableConfigs: mock(() => {}),
+}))
+
+mock.module('../../../bootstrap/state.js', () => ({
+  setOriginalCwd: mock(() => {}),
+  addSlowOperation: mock(() => {}),
+}))
+
+const mockGetDefaultAppState = mock(() => ({
+  toolPermissionContext: {
+    mode: 'default',
+    additionalWorkingDirectories: new Map(),
+    alwaysAllowRules: { user: [], project: [], local: [] },
+    alwaysDenyRules: { user: [], project: [], local: [] },
+    alwaysAskRules: { user: [], project: [], local: [] },
+    isBypassPermissionsModeAvailable: false,
+  },
+  fastMode: false,
+  settings: {},
+  tasks: {},
+  verbose: false,
+  mainLoopModel: null,
+  mainLoopModelForSession: null,
+}))
+
+mock.module('../../../state/AppStateStore.js', () => ({
+  getDefaultAppState: mockGetDefaultAppState,
+}))
+
+mock.module('../../../utils/fileStateCache.js', () => ({
+  FileStateCache: class MockFileStateCache {
+    constructor() {}
+  },
+}))
+
+mock.module('../permissions.js', () => ({
+  createAcpCanUseTool: mock(() => mock(async () => ({ behavior: 'allow', updatedInput: {} }))),
+}))
+
+mock.module('../bridge.js', () => ({
+  forwardSessionUpdates: mock(async () => ({ stopReason: 'end_turn' as const })),
+  replayHistoryMessages: mock(async () => {}),
+  toolInfoFromToolUse: mock(() => ({ title: 'Test', kind: 'other', content: [], locations: [] })),
+}))
+
+mock.module('../utils.js', () => ({
+  resolvePermissionMode: mock(() => 'default'),
+  computeSessionFingerprint: mock(() => '{}'),
+  sanitizeTitle: mock((s: string) => s),
+}))
+
+mock.module('../../../utils/listSessionsImpl.js', () => ({
+  listSessionsImpl: mock(async () => []),
+}))
+
+const mockGetMainLoopModel = mock(() => 'claude-sonnet-4-6')
+
+mock.module('../../../utils/model/model.js', () => ({
+  getMainLoopModel: mockGetMainLoopModel,
+}))
+
+mock.module('../../../utils/model/modelOptions.ts', () => ({
+  getModelOptions: mock(() => []),
+}))
+
+const mockApplySafeEnvVars = mock(() => {})
+mock.module('../../../utils/managedEnv.js', () => ({
+  applySafeConfigEnvironmentVariables: mockApplySafeEnvVars,
+}))
+
+const mockDeserializeMessages = mock((msgs: unknown[]) => msgs)
+const mockGetLastSessionLog = mock(async () => null)
+const mockSessionIdExists = mock(() => false)
+
+mock.module('../../../utils/conversationRecovery.js', () => ({
+  deserializeMessages: mockDeserializeMessages,
+}))
+
+mock.module('../../../utils/sessionStorage.js', () => ({
+  getLastSessionLog: mockGetLastSessionLog,
+  sessionIdExists: mockSessionIdExists,
+}))
+
+const mockGetCommands = mock(async () => [
+  {
+    name: 'commit',
+    description: 'Create a git commit',
+    type: 'prompt',
+    userInvocable: true,
+    isHidden: false,
+    argumentHint: '[message]',
+  },
+  {
+    name: 'compact',
+    description: 'Compact conversation',
+    type: 'local',
+    userInvocable: true,
+    isHidden: false,
+  },
+  {
+    name: 'hidden-skill',
+    description: 'Hidden skill',
+    type: 'prompt',
+    userInvocable: false,
+    isHidden: true,
+  },
+])
+
+mock.module('../../../commands.js', () => ({
+  getCommands: mockGetCommands,
+}))
+
+// ── Import after mocks ────────────────────────────────────────────
+
+const { AcpAgent } = await import('../agent.js')
+const { forwardSessionUpdates } = await import('../bridge.js')
+
+// ── Helpers ───────────────────────────────────────────────────────
+
+function makeConn() {
+  return {
+    sessionUpdate: mock(async () => {}),
+    requestPermission: mock(async () => ({ outcome: { outcome: 'cancelled' } })),
+  } as any
+}
+
+// ── Tests ─────────────────────────────────────────────────────────
+
+describe('AcpAgent', () => {
+  beforeEach(() => {
+    mockSetModel.mockClear()
+    mockGetMainLoopModel.mockClear()
+    mockGetDefaultAppState.mockClear()
+  })
+
+  describe('initialize', () => {
+    test('returns protocol version and agent info', async () => {
+      const agent = new AcpAgent(makeConn())
+      const res = await agent.initialize({} as any)
+      expect(res.protocolVersion).toBeDefined()
+      expect(res.agentInfo?.name).toBe('claude-code')
+      expect(typeof res.agentInfo?.version).toBe('string')
+    })
+
+    test('advertises image and embeddedContext capability', async () => {
+      const agent = new AcpAgent(makeConn())
+      const res = await agent.initialize({} as any)
+      expect(res.agentCapabilities?.promptCapabilities?.image).toBe(true)
+      expect(res.agentCapabilities?.promptCapabilities?.embeddedContext).toBe(true)
+    })
+
+    test('loadSession capability is true', async () => {
+      const agent = new AcpAgent(makeConn())
+      const res = await agent.initialize({} as any)
+      expect(res.agentCapabilities?.loadSession).toBe(true)
+    })
+
+    test('session capabilities include fork, list, resume, close', async () => {
+      const agent = new AcpAgent(makeConn())
+      const res = await agent.initialize({} as any)
+      expect(res.agentCapabilities?.sessionCapabilities).toBeDefined()
+    })
+  })
+
+  describe('authenticate', () => {
+    test('returns empty object (no auth required)', async () => {
+      const agent = new AcpAgent(makeConn())
+      const res = await agent.authenticate({} as any)
+      expect(res).toEqual({})
+    })
+  })
+
+  describe('newSession', () => {
+    test('returns a sessionId string', async () => {
+      const agent = new AcpAgent(makeConn())
+      const res = await agent.newSession({ cwd: '/tmp' } as any)
+      expect(typeof res.sessionId).toBe('string')
+      expect(res.sessionId.length).toBeGreaterThan(0)
+    })
+
+    test('returns modes and models', async () => {
+      const agent = new AcpAgent(makeConn())
+      const res = await agent.newSession({ cwd: '/tmp' } as any)
+      expect(res.modes).toBeDefined()
+      expect(res.models).toBeDefined()
+      expect(res.configOptions).toBeDefined()
+    })
+
+    test('each call returns a unique sessionId', async () => {
+      const agent = new AcpAgent(makeConn())
+      const r1 = await agent.newSession({ cwd: '/tmp' } as any)
+      const r2 = await agent.newSession({ cwd: '/tmp' } as any)
+      expect(r1.sessionId).not.toBe(r2.sessionId)
+    })
+
+    test('calls getDefaultAppState to build session appState', async () => {
+      const agent = new AcpAgent(makeConn())
+      await agent.newSession({ cwd: '/tmp' } as any)
+      expect(mockGetDefaultAppState).toHaveBeenCalled()
+    })
+
+    test('calls getMainLoopModel to resolve current model', async () => {
+      const agent = new AcpAgent(makeConn())
+      const res = await agent.newSession({ cwd: '/tmp' } as any)
+      expect(mockGetMainLoopModel).toHaveBeenCalled()
+      // The model reported to ACP client should match what getMainLoopModel returns
+      expect(res.models?.currentModelId).toBe('claude-sonnet-4-6')
+    })
+
+    test('calls queryEngine.setModel with resolved model', async () => {
+      const agent = new AcpAgent(makeConn())
+      await agent.newSession({ cwd: '/tmp' } as any)
+      expect(mockSetModel).toHaveBeenCalledWith('claude-sonnet-4-6')
+    })
+
+    test('respects model alias resolution via getMainLoopModel', async () => {
+      // Simulate a mapped model (e.g., "opus" → "glm-5.1" via ANTHROPIC_DEFAULT_OPUS_MODEL)
+      mockGetMainLoopModel.mockReturnValueOnce('glm-5.1')
+      const agent = new AcpAgent(makeConn())
+      const res = await agent.newSession({ cwd: '/tmp' } as any)
+      expect(res.models?.currentModelId).toBe('glm-5.1')
+      expect(mockSetModel).toHaveBeenCalledWith('glm-5.1')
+    })
+
+    test('stores clientCapabilities from initialize', async () => {
+      const agent = new AcpAgent(makeConn())
+      await agent.initialize({ clientCapabilities: { _meta: { terminal_output: true } } } as any)
+      const res = await agent.newSession({ cwd: '/tmp' } as any)
+      // Should not throw — clientCapabilities stored internally
+      expect(res.sessionId).toBeDefined()
+    })
+  })
+
+  describe('prompt', () => {
+    test('throws when session not found', async () => {
+      const agent = new AcpAgent(makeConn())
+      await expect(
+        agent.prompt({ sessionId: 'nonexistent', prompt: [] } as any)
+      ).rejects.toThrow('nonexistent')
+    })
+
+    test('returns end_turn for empty prompt text', async () => {
+      const agent = new AcpAgent(makeConn())
+      const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
+      const res = await agent.prompt({ sessionId, prompt: [] } as any)
+      expect(res.stopReason).toBe('end_turn')
+    })
+
+    test('returns end_turn for whitespace-only prompt', async () => {
+      const agent = new AcpAgent(makeConn())
+      const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
+      const res = await agent.prompt({
+        sessionId,
+        prompt: [{ type: 'text', text: '   ' }],
+      } as any)
+      expect(res.stopReason).toBe('end_turn')
+    })
+
+    test('calls forwardSessionUpdates for valid prompt', async () => {
+      const agent = new AcpAgent(makeConn())
+      const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
+      ;(forwardSessionUpdates as ReturnType<typeof mock>).mockResolvedValueOnce({ stopReason: 'end_turn' })
+      const res = await agent.prompt({
+        sessionId,
+        prompt: [{ type: 'text', text: 'hello' }],
+      } as any)
+      expect(res.stopReason).toBe('end_turn')
+    })
+
+    test('cancel before prompt does not block next prompt', async () => {
+      const agent = new AcpAgent(makeConn())
+      const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
+      // Cancel when nothing is running is a no-op
+      await agent.cancel({ sessionId } as any)
+      // The next prompt should work normally
+      ;(forwardSessionUpdates as ReturnType<typeof mock>).mockResolvedValueOnce({ stopReason: 'end_turn' })
+      const res = await agent.prompt({
+        sessionId,
+        prompt: [{ type: 'text', text: 'hello' }],
+      } as any)
+      expect(res.stopReason).toBe('end_turn')
+    })
+
+    test('cancel during prompt returns cancelled', async () => {
+      const agent = new AcpAgent(makeConn())
+      const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
+      // Start a prompt that hangs, then cancel it
+      let resolveStream!: () => void
+      ;(forwardSessionUpdates as ReturnType<typeof mock>).mockImplementationOnce(
+        () => new Promise<{ stopReason: string }>((resolve) => {
+          resolveStream = () => resolve({ stopReason: 'cancelled' })
+        }),
+      )
+      const promptPromise = agent.prompt({
+        sessionId,
+        prompt: [{ type: 'text', text: 'hello' }],
+      } as any)
+      // Cancel the running prompt
+      await agent.cancel({ sessionId } as any)
+      resolveStream()
+      const res = await promptPromise
+      // After fix, forwardSessionUpdates mock controls the result
+      expect(res.stopReason).toBe('cancelled')
+
+      // Next prompt should work normally
+      ;(forwardSessionUpdates as ReturnType<typeof mock>).mockResolvedValueOnce({ stopReason: 'end_turn' })
+      const res2 = await agent.prompt({
+        sessionId,
+        prompt: [{ type: 'text', text: 'world' }],
+      } as any)
+      expect(res2.stopReason).toBe('end_turn')
+    })
+
+    test('returns end_turn on unexpected error', async () => {
+      const agent = new AcpAgent(makeConn())
+      const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
+      ;(forwardSessionUpdates as ReturnType<typeof mock>).mockImplementationOnce(async () => {
+        throw new Error('unexpected')
+      })
+      const res = await agent.prompt({
+        sessionId,
+        prompt: [{ type: 'text', text: 'hello' }],
+      } as any)
+      expect(res.stopReason).toBe('end_turn')
+    })
+
+    test('returns usage from forwardSessionUpdates', async () => {
+      const agent = new AcpAgent(makeConn())
+      const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
+      ;(forwardSessionUpdates as ReturnType<typeof mock>).mockResolvedValueOnce({
+        stopReason: 'end_turn',
+        usage: {
+          inputTokens: 100,
+          outputTokens: 50,
+          cachedReadTokens: 10,
+          cachedWriteTokens: 5,
+        },
+      })
+      const res = await agent.prompt({
+        sessionId,
+        prompt: [{ type: 'text', text: 'hello' }],
+      } as any)
+      expect(res.usage).toBeDefined()
+      expect(res.usage!.inputTokens).toBe(100)
+      expect(res.usage!.outputTokens).toBe(50)
+      expect(res.usage!.totalTokens).toBe(165)
+    })
+  })
+
+  describe('cancel', () => {
+    test('does not throw for unknown session', async () => {
+      const agent = new AcpAgent(makeConn())
+      await expect(agent.cancel({ sessionId: 'ghost' } as any)).resolves.toBeUndefined()
+    })
+  })
+
+  describe('closeSession', () => {
+    test('throws for unknown session', async () => {
+      const agent = new AcpAgent(makeConn())
+      await expect(agent.unstable_closeSession({ sessionId: 'ghost' } as any)).rejects.toThrow('Session not found')
+    })
+
+    test('removes session after close', async () => {
+      const agent = new AcpAgent(makeConn())
+      const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
+      await agent.unstable_closeSession({ sessionId } as any)
+      expect(agent.sessions.has(sessionId)).toBe(false)
+    })
+  })
+
+  describe('setSessionModel', () => {
+    test('updates model on queryEngine', async () => {
+      const agent = new AcpAgent(makeConn())
+      const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
+      mockSetModel.mockClear()
+      await agent.unstable_setSessionModel({ sessionId, modelId: 'glm-5.1' } as any)
+      expect(mockSetModel).toHaveBeenCalledWith('glm-5.1')
+    })
+
+    test('passes alias modelId to queryEngine as-is for later resolution', async () => {
+      // "sonnet[1m]" is stored raw — QueryEngine.submitMessage() calls
+      // parseUserSpecifiedModel() which resolves aliases via env vars
+      const agent = new AcpAgent(makeConn())
+      const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
+      mockSetModel.mockClear()
+      await agent.unstable_setSessionModel({ sessionId, modelId: 'sonnet[1m]' } as any)
+      expect(mockSetModel).toHaveBeenCalledWith('sonnet[1m]')
+    })
+  })
+
+  describe('entry.ts initialization contract', () => {
+    test('entry.ts imports applySafeConfigEnvironmentVariables from managedEnv', async () => {
+      // Verify the module import exists — this catches if entry.ts forgets
+      // to import applySafeConfigEnvironmentVariables
+      const entrySource = await Bun.file(
+        new URL('../entry.ts', import.meta.url),
+      ).text()
+      expect(entrySource).toContain('applySafeConfigEnvironmentVariables')
+      expect(entrySource).toContain('enableConfigs')
+
+      // Verify applySafe is called after enableConfigs in the source
+      const enableIdx = entrySource.indexOf('enableConfigs()')
+      const applyIdx = entrySource.indexOf('applySafeConfigEnvironmentVariables()')
+      expect(enableIdx).toBeGreaterThan(-1)
+      expect(applyIdx).toBeGreaterThan(-1)
+      expect(enableIdx).toBeLessThan(applyIdx)
+    })
+  })
+
+  describe('prompt usage tracking', () => {
+    test('returns totalTokens as sum of all token types', async () => {
+      const agent = new AcpAgent(makeConn())
+      const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
+      ;(forwardSessionUpdates as ReturnType<typeof mock>).mockResolvedValueOnce({
+        stopReason: 'end_turn',
+        usage: {
+          inputTokens: 100,
+          outputTokens: 50,
+          cachedReadTokens: 10,
+          cachedWriteTokens: 5,
+        },
+      })
+      const res = await agent.prompt({
+        sessionId,
+        prompt: [{ type: 'text', text: 'hello' }],
+      } as any)
+      expect(res.usage).toBeDefined()
+      expect(res.usage!.totalTokens).toBe(165)
+    })
+
+    test('returns undefined usage when forwardSessionUpdates returns none', async () => {
+      const agent = new AcpAgent(makeConn())
+      const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
+      ;(forwardSessionUpdates as ReturnType<typeof mock>).mockResolvedValueOnce({
+        stopReason: 'end_turn',
+      })
+      const res = await agent.prompt({
+        sessionId,
+        prompt: [{ type: 'text', text: 'hello' }],
+      } as any)
+      expect(res.usage).toBeUndefined()
+    })
+  })
+
+  describe('prompt error handling', () => {
+    test('returns cancelled when session was cancelled during prompt', async () => {
+      const agent = new AcpAgent(makeConn())
+      const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
+      ;(forwardSessionUpdates as ReturnType<typeof mock>).mockImplementationOnce(async () => {
+        // Simulate cancel happening during forward
+        const session = agent.sessions.get(sessionId)
+        if (session) session.cancelled = true
+        return { stopReason: 'end_turn' }
+      })
+      const res = await agent.prompt({
+        sessionId,
+        prompt: [{ type: 'text', text: 'hello' }],
+      } as any)
+      expect(res.stopReason).toBe('cancelled')
+    })
+
+    test('returns cancelled on cancel after error', async () => {
+      const agent = new AcpAgent(makeConn())
+      const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
+      ;(forwardSessionUpdates as ReturnType<typeof mock>).mockImplementationOnce(async () => {
+        const session = agent.sessions.get(sessionId)
+        if (session) session.cancelled = true
+        throw new Error('unexpected')
+      })
+      const res = await agent.prompt({
+        sessionId,
+        prompt: [{ type: 'text', text: 'hello' }],
+      } as any)
+      expect(res.stopReason).toBe('cancelled')
+    })
+  })
+
+  describe('resumeSession', () => {
+    test('creates new session with the requested sessionId when not in memory', async () => {
+      const agent = new AcpAgent(makeConn())
+      const requestedId = 'e73e9b66-9637-4477-b512-af45357b1dcb'
+      const res = await agent.unstable_resumeSession({
+        sessionId: requestedId,
+        cwd: '/tmp',
+        mcpServers: [],
+      } as any)
+      // The session must be stored under the requested ID
+      expect(agent.sessions.has(requestedId)).toBe(true)
+      // Response should have modes/models/configOptions
+      expect(res.modes).toBeDefined()
+      expect(res.models).toBeDefined()
+    })
+
+    test('reuses existing session when sessionId matches and fingerprint unchanged', async () => {
+      const agent = new AcpAgent(makeConn())
+      const res1 = await agent.newSession({ cwd: '/tmp' } as any)
+      const sid = res1.sessionId
+      const originalSession = agent.sessions.get(sid)
+      // Resume with same params
+      const res2 = await agent.unstable_resumeSession({
+        sessionId: sid,
+        cwd: '/tmp',
+        mcpServers: [],
+      } as any)
+      // Same session object — not recreated
+      expect(agent.sessions.get(sid)).toBe(originalSession)
+    })
+
+    test('can prompt after resumeSession with previously unknown sessionId', async () => {
+      const agent = new AcpAgent(makeConn())
+      const sid = 'restored-session-id-1234'
+      await agent.unstable_resumeSession({
+        sessionId: sid,
+        cwd: '/tmp',
+        mcpServers: [],
+      } as any)
+      ;(forwardSessionUpdates as ReturnType<typeof mock>).mockResolvedValueOnce({ stopReason: 'end_turn' })
+      const res = await agent.prompt({
+        sessionId: sid,
+        prompt: [{ type: 'text', text: 'hello after restore' }],
+      } as any)
+      expect(res.stopReason).toBe('end_turn')
+    })
+  })
+
+  describe('loadSession', () => {
+    test('creates new session with the requested sessionId', async () => {
+      const agent = new AcpAgent(makeConn())
+      const requestedId = 'aaaa-bbbb-cccc'
+      await agent.loadSession({
+        sessionId: requestedId,
+        cwd: '/tmp',
+        mcpServers: [],
+      } as any)
+      expect(agent.sessions.has(requestedId)).toBe(true)
+    })
+
+    test('can prompt after loadSession', async () => {
+      const agent = new AcpAgent(makeConn())
+      const sid = 'loaded-session-id'
+      await agent.loadSession({
+        sessionId: sid,
+        cwd: '/tmp',
+        mcpServers: [],
+      } as any)
+      ;(forwardSessionUpdates as ReturnType<typeof mock>).mockResolvedValueOnce({ stopReason: 'end_turn' })
+      const res = await agent.prompt({
+        sessionId: sid,
+        prompt: [{ type: 'text', text: 'hello after load' }],
+      } as any)
+      expect(res.stopReason).toBe('end_turn')
+    })
+  })
+
+  describe('forkSession', () => {
+    test('returns a different sessionId from any existing', async () => {
+      const agent = new AcpAgent(makeConn())
+      const original = await agent.newSession({ cwd: '/tmp' } as any)
+      const forked = await agent.unstable_forkSession({
+        cwd: '/tmp',
+        mcpServers: [],
+      } as any)
+      expect(forked.sessionId).not.toBe(original.sessionId)
+      expect(agent.sessions.has(forked.sessionId)).toBe(true)
+    })
+  })
+
+  describe('setSessionMode', () => {
+    test('updates current mode on the session', async () => {
+      const agent = new AcpAgent(makeConn())
+      const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
+      await agent.setSessionMode({ sessionId, modeId: 'auto' } as any)
+      const session = agent.sessions.get(sessionId)
+      expect(session?.modes.currentModeId).toBe('auto')
+    })
+
+    test('throws for invalid mode', async () => {
+      const agent = new AcpAgent(makeConn())
+      const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
+      await expect(
+        agent.setSessionMode({ sessionId, modeId: 'invalid_mode' } as any),
+      ).rejects.toThrow('Invalid mode')
+    })
+
+    test('throws for unknown session', async () => {
+      const agent = new AcpAgent(makeConn())
+      await expect(
+        agent.setSessionMode({ sessionId: 'ghost', modeId: 'auto' } as any),
+      ).rejects.toThrow('Session not found')
+    })
+  })
+
+  describe('setSessionConfigOption', () => {
+    test('throws for unknown config option', async () => {
+      const agent = new AcpAgent(makeConn())
+      const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
+      await expect(
+        agent.setSessionConfigOption({
+          sessionId,
+          configId: 'nonexistent',
+          value: 'x',
+        } as any),
+      ).rejects.toThrow('Unknown config option')
+    })
+
+    test('throws for non-string value', async () => {
+      const agent = new AcpAgent(makeConn())
+      const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
+      await expect(
+        agent.setSessionConfigOption({
+          sessionId,
+          configId: 'mode',
+          value: 42,
+        } as any),
+      ).rejects.toThrow('Invalid value')
+    })
+  })
+
+  describe('prompt queueing', () => {
+    test('queued prompts execute in order after current prompt finishes', async () => {
+      const agent = new AcpAgent(makeConn())
+      const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
+
+      // First prompt hangs
+      let resolveFirst!: () => void
+      ;(forwardSessionUpdates as ReturnType<typeof mock>).mockImplementationOnce(
+        () => new Promise<{ stopReason: string }>((resolve) => {
+          resolveFirst = () => resolve({ stopReason: 'end_turn' })
+        }),
+      )
+      // Second prompt resolves normally
+      ;(forwardSessionUpdates as ReturnType<typeof mock>).mockResolvedValueOnce({ stopReason: 'end_turn' })
+
+      const p1 = agent.prompt({ sessionId, prompt: [{ type: 'text', text: 'first' }] } as any)
+      const p2 = agent.prompt({ sessionId, prompt: [{ type: 'text', text: 'second' }] } as any)
+
+      // Resolve the first prompt to unblock the second
+      resolveFirst()
+      const [r1, r2] = await Promise.all([p1, p2])
+      expect(r1.stopReason).toBe('end_turn')
+      expect(r2.stopReason).toBe('end_turn')
+    })
+
+    test('queued prompts return cancelled when session is cancelled', async () => {
+      const agent = new AcpAgent(makeConn())
+      const { sessionId } = await agent.newSession({ cwd: '/tmp' } as any)
+
+      // First prompt hangs
+      let resolveFirst!: () => void
+      ;(forwardSessionUpdates as ReturnType<typeof mock>).mockImplementationOnce(
+        () => new Promise<{ stopReason: string }>((resolve) => {
+          resolveFirst = () => resolve({ stopReason: 'end_turn' })
+        }),
+      )
+
+      const p1 = agent.prompt({ sessionId, prompt: [{ type: 'text', text: 'first' }] } as any)
+      const p2 = agent.prompt({ sessionId, prompt: [{ type: 'text', text: 'second' }] } as any)
+
+      // Cancel while first is running — both should be cancelled
+      await agent.cancel({ sessionId } as any)
+      resolveFirst()
+      const [r1, r2] = await Promise.all([p1, p2])
+      expect(r1.stopReason).toBe('cancelled')
+      expect(r2.stopReason).toBe('cancelled')
+    })
+  })
+
+  describe('commands', () => {
+    test('sends filtered prompt-type commands to client', async () => {
+      const conn = makeConn()
+      const agent = new AcpAgent(conn)
+      await agent.newSession({ cwd: '/tmp' } as any)
+
+      // Wait for setTimeout-based sendAvailableCommandsUpdate
+      await new Promise(r => setTimeout(r, 10))
+
+      const calls = (conn.sessionUpdate as ReturnType<typeof mock>).mock.calls
+      const cmdUpdate = calls.find((c: any[]) => {
+        const update = c[0]?.update
+        return update?.sessionUpdate === 'available_commands_update'
+      })
+      expect(cmdUpdate).toBeDefined()
+
+      const cmds = (cmdUpdate as any[])[0].update.availableCommands
+      // Only prompt-type, non-hidden, userInvocable commands
+      const names = cmds.map((c: any) => c.name)
+      expect(names).toContain('commit')
+      expect(names).not.toContain('compact')    // type: 'local'
+      expect(names).not.toContain('hidden-skill') // isHidden: true, userInvocable: false
+    })
+
+    test('maps argumentHint to input.hint', async () => {
+      const conn = makeConn()
+      const agent = new AcpAgent(conn)
+      await agent.newSession({ cwd: '/tmp' } as any)
+
+      await new Promise(r => setTimeout(r, 10))
+
+      const calls = (conn.sessionUpdate as ReturnType<typeof mock>).mock.calls
+      const cmdUpdate = calls.find((c: any[]) => {
+        const update = c[0]?.update
+        return update?.sessionUpdate === 'available_commands_update'
+      })
+      const commit = (cmdUpdate as any[])[0].update.availableCommands.find(
+        (c: any) => c.name === 'commit',
+      )
+      expect(commit.input).toEqual({ hint: '[message]' })
+    })
+  })
+})
diff --git a/src/services/acp/__tests__/bridge.test.ts b/src/services/acp/__tests__/bridge.test.ts
new file mode 100644
index 000000000..5e885d95d
--- /dev/null
+++ b/src/services/acp/__tests__/bridge.test.ts
@@ -0,0 +1,677 @@
+import { describe, expect, test, mock } from 'bun:test'
+import {
+  toolInfoFromToolUse,
+  toolUpdateFromToolResult,
+  toolUpdateFromEditToolResponse,
+  forwardSessionUpdates,
+} from '../bridge.js'
+import { markdownEscape, toDisplayPath } from '../utils.js'
+import type { AgentSideConnection, ToolKind } from '@agentclientprotocol/sdk'
+import type { SDKMessage } from '../../../entrypoints/sdk/coreTypes.js'
+
+// ── Helpers ────────────────────────────────────────────────────────
+
+function makeConn(overrides: Partial<AgentSideConnection> = {}): AgentSideConnection {
+  return {
+    sessionUpdate: mock(async () => {}),
+    requestPermission: mock(async () => ({ outcome: { outcome: 'cancelled' } }) as any),
+    ...overrides,
+  } as unknown as AgentSideConnection
+}
+
+async function* makeStream(msgs: SDKMessage[]): AsyncGenerator<SDKMessage, void, unknown> {
+  for (const m of msgs) yield m
+}
+
+// ── toolInfoFromToolUse ────────────────────────────────────────────
+
+describe('toolInfoFromToolUse', () => {
+  const kindCases: Array<[string, ToolKind]> = [
+    ['Read', 'read'],
+    ['Edit', 'edit'],
+    ['Write', 'edit'],
+    ['Bash', 'execute'],
+    ['Glob', 'search'],
+    ['Grep', 'search'],
+    ['WebFetch', 'fetch'],
+    ['WebSearch', 'fetch'],
+    ['Agent', 'think'],
+    ['Task', 'think'],
+    ['TodoWrite', 'think'],
+    ['ExitPlanMode', 'switch_mode'],
+  ]
+
+  for (const [name, expected] of kindCases) {
+    test(`${name} → ${expected}`, () => {
+      const info = toolInfoFromToolUse({ name, id: 'test', input: {} })
+      expect(info.kind).toBe(expected)
+    })
+  }
+
+  test('unknown tool name → other', () => {
+    expect(toolInfoFromToolUse({ name: 'SomeFancyTool', id: 'x', input: {} }).kind).toBe('other' as ToolKind)
+    expect(toolInfoFromToolUse({ name: '', id: 'x', input: {} }).kind).toBe('other' as ToolKind)
+  })
+
+  // ── Bash ──────────────────────────────────────────────────────
+
+  test('Bash with command → title shows command', () => {
+    const info = toolInfoFromToolUse({ name: 'Bash', id: 'x', input: { command: 'ls -la', description: 'List files' } })
+    expect(info.title).toBe('ls -la')
+    expect(info.content).toEqual([
+      { type: 'content', content: { type: 'text', text: 'List files' } },
+    ])
+  })
+
+  test('Bash with terminalOutput → returns terminalId content', () => {
+    const info = toolInfoFromToolUse(
+      { name: 'Bash', id: 'tu_123', input: { command: 'ls' } },
+      true,
+    )
+    expect(info.kind).toBe('execute')
+    expect(info.content).toEqual([{ type: 'terminal', terminalId: 'tu_123' }])
+  })
+
+  test('Bash without description → empty content', () => {
+    const info = toolInfoFromToolUse({ name: 'Bash', id: 'x', input: { command: 'ls' } })
+    expect(info.content).toEqual([])
+  })
+
+  // ── Glob ──────────────────────────────────────────────────────
+
+  test('Glob with pattern → title shows Find', () => {
+    const info = toolInfoFromToolUse({ name: 'Glob', id: 'x', input: { pattern: '*/**.ts' } })
+    expect(info.title).toBe('Find `*/**.ts`')
+    expect(info.locations).toEqual([])
+  })
+
+  test('Glob with path → locations include path', () => {
+    const info = toolInfoFromToolUse({ name: 'Glob', id: 'x', input: { pattern: '*.ts', path: '/src' } })
+    expect(info.title).toBe('Find `/src` `*.ts`')
+    expect(info.locations).toEqual([{ path: '/src' }])
+  })
+
+  // ── Task/Agent ────────────────────────────────────────────────
+
+  test('Task with description and prompt → content has prompt text', () => {
+    const info = toolInfoFromToolUse({
+      name: 'Task',
+      id: 'x',
+      input: { description: 'Handle task', prompt: 'Do the work' },
+    })
+    expect(info.title).toBe('Handle task')
+    expect(info.content).toEqual([
+      { type: 'content', content: { type: 'text', text: 'Do the work' } },
+    ])
+  })
+
+  // ── Grep ──────────────────────────────────────────────────────
+
+  test('Grep with full flags', () => {
+    const info = toolInfoFromToolUse({
+      name: 'Grep',
+      id: 'x',
+      input: {
+        pattern: 'todo',
+        path: '/src',
+        '-i': true,
+        '-n': true,
+        '-A': 3,
+        '-B': 2,
+        '-C': 5,
+        head_limit: 10,
+        glob: '*.ts',
+        type: 'js',
+        multiline: true,
+      },
+    })
+    expect(info.title).toContain('-i')
+    expect(info.title).toContain('-n')
+    expect(info.title).toContain('-A 3')
+    expect(info.title).toContain('-B 2')
+    expect(info.title).toContain('-C 5')
+    expect(info.title).toContain('| head -10')
+    expect(info.title).toContain('--include="*.ts"')
+    expect(info.title).toContain('--type=js')
+    expect(info.title).toContain('-P')
+    expect(info.title).toContain('"todo"')
+    expect(info.title).toContain('/src')
+  })
+
+  test('Grep with files_with_matches → -l', () => {
+    const info = toolInfoFromToolUse({
+      name: 'Grep',
+      id: 'x',
+      input: { pattern: 'foo', output_mode: 'files_with_matches' },
+    })
+    expect(info.title).toContain('-l')
+  })
+
+  test('Grep with count → -c', () => {
+    const info = toolInfoFromToolUse({
+      name: 'Grep',
+      id: 'x',
+      input: { pattern: 'foo', output_mode: 'count' },
+    })
+    expect(info.title).toContain('-c')
+  })
+
+  // ── Write ─────────────────────────────────────────────────────
+
+  test('Write with file_path and content → diff content', () => {
+    const info = toolInfoFromToolUse({
+      name: 'Write',
+      id: 'x',
+      input: { file_path: '/Users/test/project/example.txt', content: 'Hello, World!\nThis is test content.' },
+    })
+    expect(info.kind).toBe('edit')
+    expect(info.title).toBe('Write /Users/test/project/example.txt')
+    expect(info.content).toEqual([
+      {
+        type: 'diff',
+        path: '/Users/test/project/example.txt',
+        oldText: null,
+        newText: 'Hello, World!\nThis is test content.',
+      },
+    ])
+    expect(info.locations).toEqual([{ path: '/Users/test/project/example.txt' }])
+  })
+
+  // ── Edit ──────────────────────────────────────────────────────
+
+  test('Edit with file_path → diff content', () => {
+    const info = toolInfoFromToolUse({
+      name: 'Edit',
+      id: 'x',
+      input: { file_path: '/Users/test/project/test.txt', old_string: 'old text', new_string: 'new text' },
+    })
+    expect(info.kind).toBe('edit')
+    expect(info.title).toBe('Edit /Users/test/project/test.txt')
+    expect(info.content).toEqual([
+      {
+        type: 'diff',
+        path: '/Users/test/project/test.txt',
+        oldText: 'old text',
+        newText: 'new text',
+      },
+    ])
+  })
+
+  test('Edit without file_path → empty content', () => {
+    const info = toolInfoFromToolUse({ name: 'Edit', id: 'x', input: {} })
+    expect(info.title).toBe('Edit')
+    expect(info.content).toEqual([])
+  })
+
+  // ── Read ──────────────────────────────────────────────────────
+
+  test('Read with file_path → locations include path and line 1', () => {
+    const info = toolInfoFromToolUse({ name: 'Read', id: 'x', input: { file_path: '/src/foo.ts' } })
+    expect(info.locations).toEqual([{ path: '/src/foo.ts', line: 1 }])
+  })
+
+  test('Read with limit', () => {
+    const info = toolInfoFromToolUse({ name: 'Read', id: 'x', input: { file_path: '/large.txt', limit: 100 } })
+    expect(info.title).toContain('(1 - 100)')
+  })
+
+  test('Read with offset and limit', () => {
+    const info = toolInfoFromToolUse({ name: 'Read', id: 'x', input: { file_path: '/large.txt', offset: 50, limit: 100 } })
+    expect(info.title).toContain('(50 - 149)')
+    expect(info.locations).toEqual([{ path: '/large.txt', line: 50 }])
+  })
+
+  test('Read with only offset', () => {
+    const info = toolInfoFromToolUse({ name: 'Read', id: 'x', input: { file_path: '/large.txt', offset: 200 } })
+    expect(info.title).toContain('(from line 200)')
+  })
+
+  test('Read with cwd → relative path in title, absolute in locations', () => {
+    const info = toolInfoFromToolUse(
+      { name: 'Read', id: 'x', input: { file_path: '/Users/test/project/src/main.ts' } },
+      false,
+      '/Users/test/project',
+    )
+    expect(info.title).toBe('Read src/main.ts')
+    expect(info.locations).toEqual([{ path: '/Users/test/project/src/main.ts', line: 1 }])
+  })
+
+  // ── WebSearch ─────────────────────────────────────────────────
+
+  test('WebSearch with allowed/blocked domains', () => {
+    const info = toolInfoFromToolUse({
+      name: 'WebSearch',
+      id: 'x',
+      input: { query: 'test', allowed_domains: ['a.com'], blocked_domains: ['b.com'] },
+    })
+    expect(info.title).toContain('allowed: a.com')
+    expect(info.title).toContain('blocked: b.com')
+  })
+
+  // ── TodoWrite ─────────────────────────────────────────────────
+
+  test('TodoWrite with todos array → title shows content', () => {
+    const info = toolInfoFromToolUse({
+      name: 'TodoWrite',
+      id: 'x',
+      input: { todos: [{ content: 'Task 1' }, { content: 'Task 2' }] },
+    })
+    expect(info.title).toContain('Task 1')
+    expect(info.title).toContain('Task 2')
+  })
+
+  // ── ExitPlanMode ──────────────────────────────────────────────
+
+  test('ExitPlanMode with plan → content has plan text', () => {
+    const info = toolInfoFromToolUse({
+      name: 'ExitPlanMode',
+      id: 'x',
+      input: { plan: 'Do the thing' },
+    })
+    expect(info.title).toBe('Ready to code?')
+    expect(info.content).toEqual([
+      { type: 'content', content: { type: 'text', text: 'Do the thing' } },
+    ])
+  })
+})
+
+// ── toolUpdateFromToolResult ───────────────────────────────────────
+
+describe('toolUpdateFromToolResult', () => {
+  test('returns empty for Edit success', () => {
+    const result = toolUpdateFromToolResult(
+      { content: [{ type: 'text', text: 'The file has been edited' }], is_error: false, tool_use_id: 't1' },
+      { name: 'Edit', id: 't1' },
+    )
+    expect(result).toEqual({})
+  })
+
+  test('returns error content for Edit failure', () => {
+    const result = toolUpdateFromToolResult(
+      { content: [{ type: 'text', text: 'Failed to find `old_string`' }], is_error: true, tool_use_id: 't1' },
+      { name: 'Edit', id: 't1' },
+    )
+    expect(result.content).toEqual([
+      { type: 'content', content: { type: 'text', text: '```\nFailed to find `old_string`\n```' } },
+    ])
+  })
+
+  test('returns markdown-escaped content for Read', () => {
+    const result = toolUpdateFromToolResult(
+      { content: 'let x = 1', is_error: false, tool_use_id: 't1' },
+      { name: 'Read', id: 't1' },
+    )
+    expect(result.content).toBeDefined()
+    expect(result.content![0].type).toBe('content')
+    // Should be wrapped in markdown code fence
+    const text = (result.content![0] as { type: string; content: { type: string; text: string } }).content.text
+    expect(text).toContain('```')
+    expect(text).toContain('let x = 1')
+  })
+
+  test('returns console block for Bash output', () => {
+    const result = toolUpdateFromToolResult(
+      { content: [{ type: 'text', text: 'hello world' }], is_error: false, tool_use_id: 't1' },
+      { name: 'Bash', id: 't1' },
+    )
+    expect(result.content).toEqual([
+      { type: 'content', content: { type: 'text', text: '```console\nhello world\n```' } },
+    ])
+  })
+
+  test('returns terminal metadata for Bash with terminalOutput', () => {
+    const result = toolUpdateFromToolResult(
+      { content: [{ type: 'text', text: 'output' }], is_error: false, tool_use_id: 't1' },
+      { name: 'Bash', id: 't1' },
+      true,
+    )
+    expect(result.content).toEqual([{ type: 'terminal', terminalId: 't1' }])
+    expect(result._meta).toBeDefined()
+    expect((result._meta as Record<string, unknown>).terminal_info).toEqual({ terminal_id: 't1' })
+    expect((result._meta as Record<string, unknown>).terminal_output).toEqual({ terminal_id: 't1', data: 'output' })
+    expect((result._meta as Record<string, unknown>).terminal_exit).toEqual({ terminal_id: 't1', exit_code: 0, signal: null })
+  })
+
+  test('handles bash_code_execution_result format', () => {
+    const result = toolUpdateFromToolResult(
+      { content: { type: 'bash_code_execution_result', stdout: 'out', stderr: 'err', return_code: 0 }, is_error: false, tool_use_id: 't1' },
+      { name: 'Bash', id: 't1' },
+      true,
+    )
+    const meta = result._meta as Record<string, unknown>
+    const termOutput = meta.terminal_output as { data: string }
+    expect(termOutput.data).toBe('out\nerr')
+  })
+
+  test('returns empty when no toolUse', () => {
+    const result = toolUpdateFromToolResult(
+      { content: 'text', is_error: false },
+      undefined,
+    )
+    expect(result).toEqual({})
+  })
+
+  test('transforms tool_reference content', () => {
+    const result = toolUpdateFromToolResult(
+      { content: [{ type: 'tool_reference', tool_name: 'some_tool' }], is_error: false, tool_use_id: 't1' },
+      { name: 'ToolSearch', id: 't1' },
+    )
+    expect(result.content).toEqual([
+      { type: 'content', content: { type: 'text', text: 'Tool: some_tool' } },
+    ])
+  })
+
+  test('transforms web_search_result content', () => {
+    const result = toolUpdateFromToolResult(
+      { content: [{ type: 'web_search_result', title: 'Test Result', url: 'https://example.com' }], is_error: false, tool_use_id: 't1' },
+      { name: 'WebSearch', id: 't1' },
+    )
+    expect(result.content).toEqual([
+      { type: 'content', content: { type: 'text', text: 'Test Result (https://example.com)' } },
+    ])
+  })
+
+  test('transforms code_execution_result content', () => {
+    const result = toolUpdateFromToolResult(
+      { content: [{ type: 'code_execution_result', stdout: 'Hello World', stderr: '' }], is_error: false, tool_use_id: 't1' },
+      { name: 'CodeExecution', id: 't1' },
+    )
+    expect(result.content).toEqual([
+      { type: 'content', content: { type: 'text', text: 'Output: Hello World' } },
+    ])
+  })
+
+  test('returns title for ExitPlanMode', () => {
+    const result = toolUpdateFromToolResult(
+      { content: 'ok', is_error: false, tool_use_id: 't1' },
+      { name: 'ExitPlanMode', id: 't1' },
+    )
+    expect(result.title).toBe('Exited Plan Mode')
+  })
+})
+
+// ── toolUpdateFromEditToolResponse ─────────────────────────────────
+
+describe('toolUpdateFromEditToolResponse', () => {
+  test('returns empty for null/undefined/string', () => {
+    expect(toolUpdateFromEditToolResponse(null)).toEqual({})
+    expect(toolUpdateFromEditToolResponse(undefined)).toEqual({})
+    expect(toolUpdateFromEditToolResponse('string')).toEqual({})
+  })
+
+  test('returns empty when filePath or structuredPatch missing', () => {
+    expect(toolUpdateFromEditToolResponse({})).toEqual({})
+    expect(toolUpdateFromEditToolResponse({ filePath: '/foo.ts' })).toEqual({})
+    expect(toolUpdateFromEditToolResponse({ structuredPatch: [] })).toEqual({})
+  })
+
+  test('builds diff content from single hunk', () => {
+    const result = toolUpdateFromEditToolResponse({
+      filePath: '/Users/test/project/test.txt',
+      structuredPatch: [
+        {
+          oldStart: 1,
+          oldLines: 3,
+          newStart: 1,
+          newLines: 3,
+          lines: [' context before', '-old line', '+new line', ' context after'],
+        },
+      ],
+    })
+    expect(result).toEqual({
+      content: [
+        {
+          type: 'diff',
+          path: '/Users/test/project/test.txt',
+          oldText: 'context before\nold line\ncontext after',
+          newText: 'context before\nnew line\ncontext after',
+        },
+      ],
+      locations: [{ path: '/Users/test/project/test.txt', line: 1 }],
+    })
+  })
+
+  test('builds multiple diff blocks for replaceAll with multiple hunks', () => {
+    const result = toolUpdateFromEditToolResponse({
+      filePath: '/Users/test/project/file.ts',
+      structuredPatch: [
+        { oldStart: 5, oldLines: 1, newStart: 5, newLines: 1, lines: ['-oldValue', '+newValue'] },
+        { oldStart: 20, oldLines: 1, newStart: 20, newLines: 1, lines: ['-oldValue', '+newValue'] },
+      ],
+    })
+    expect(result.content).toHaveLength(2)
+    expect(result.locations).toHaveLength(2)
+    expect(result.locations).toEqual([
+      { path: '/Users/test/project/file.ts', line: 5 },
+      { path: '/Users/test/project/file.ts', line: 20 },
+    ])
+  })
+
+  test('handles deletion (newText becomes empty string)', () => {
+    const result = toolUpdateFromEditToolResponse({
+      filePath: '/Users/test/project/file.ts',
+      structuredPatch: [
+        { oldStart: 10, oldLines: 2, newStart: 10, newLines: 1, lines: [' context', '-removed line'] },
+      ],
+    })
+    expect(result.content).toEqual([
+      {
+        type: 'diff',
+        path: '/Users/test/project/file.ts',
+        oldText: 'context\nremoved line',
+        newText: 'context',
+      },
+    ])
+  })
+
+  test('returns empty for empty structuredPatch array', () => {
+    expect(
+      toolUpdateFromEditToolResponse({ filePath: '/foo.ts', structuredPatch: [] }),
+    ).toEqual({})
+  })
+})
+
+// ── markdownEscape ─────────────────────────────────────────────────
+
+describe('markdownEscape', () => {
+  test('wraps basic text in code fence', () => {
+    expect(markdownEscape('Hello *world*!')).toBe('```\nHello *world*!\n```')
+  })
+
+  test('extends fence for text containing backtick fences', () => {
+    const text = 'for example:\n```markdown\nHello *world*!\n```\n'
+    expect(markdownEscape(text)).toBe('````\nfor example:\n```markdown\nHello *world*!\n```\n````')
+  })
+})
+
+// ── toDisplayPath ──────────────────────────────────────────────────
+
+describe('toDisplayPath', () => {
+  test('relativizes paths inside cwd', () => {
+    expect(toDisplayPath('/Users/test/project/src/main.ts', '/Users/test/project')).toBe('src/main.ts')
+  })
+
+  test('keeps absolute paths outside cwd', () => {
+    expect(toDisplayPath('/etc/hosts', '/Users/test/project')).toBe('/etc/hosts')
+  })
+
+  test('returns original when no cwd', () => {
+    expect(toDisplayPath('/Users/test/project/src/main.ts')).toBe('/Users/test/project/src/main.ts')
+  })
+
+  test('partial directory name match does not relativize', () => {
+    expect(toDisplayPath('/Users/test/project-other/file.ts', '/Users/test/project')).toBe('/Users/test/project-other/file.ts')
+  })
+})
+
+// ── forwardSessionUpdates ─────────────────────────────────────────
+
+describe('forwardSessionUpdates', () => {
+  test('returns end_turn when stream is empty', async () => {
+    const conn = makeConn()
+    const result = await forwardSessionUpdates('s1', makeStream([]), conn, new AbortController().signal, {})
+    expect(result.stopReason).toBe('end_turn')
+  })
+
+  test('returns cancelled when aborted before iteration', async () => {
+    const ac = new AbortController()
+    ac.abort()
+    const conn = makeConn()
+    const result = await forwardSessionUpdates('s1', makeStream([
+      { type: 'assistant', message: { content: [{ type: 'text', text: 'hi' }] } } as unknown as SDKMessage,
+    ]), conn, ac.signal, {})
+    expect(result.stopReason).toBe('cancelled')
+  })
+
+  test('forwards assistant text message as agent_message_chunk', async () => {
+    const conn = makeConn()
+    const msgs: SDKMessage[] = [
+      { type: 'assistant', message: { content: [{ type: 'text', text: 'Hello!' }], role: 'assistant' } } as unknown as SDKMessage,
+    ]
+    const result = await forwardSessionUpdates('s1', makeStream(msgs), conn, new AbortController().signal, {})
+    const calls = (conn.sessionUpdate as ReturnType<typeof mock>).mock.calls
+    expect(calls.length).toBeGreaterThanOrEqual(1)
+    expect(calls[0][0]).toMatchObject({
+      sessionId: 's1',
+      update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: 'Hello!' } },
+    })
+    expect(result.stopReason).toBe('end_turn')
+  })
+
+  test('forwards thinking block as agent_thought_chunk', async () => {
+    const conn = makeConn()
+    const msgs: SDKMessage[] = [
+      { type: 'assistant', message: { content: [{ type: 'thinking', thinking: 'reasoning...' }], role: 'assistant' } } as unknown as SDKMessage,
+    ]
+    await forwardSessionUpdates('s1', makeStream(msgs), conn, new AbortController().signal, {})
+    const calls = (conn.sessionUpdate as ReturnType<typeof mock>).mock.calls
+    expect(calls[0][0].update).toMatchObject({ sessionUpdate: 'agent_thought_chunk' })
+  })
+
+  test('forwards tool_use block as tool_call', async () => {
+    const conn = makeConn()
+    const msgs: SDKMessage[] = [
+      {
+        type: 'assistant',
+        message: {
+          content: [{
+            type: 'tool_use',
+            id: 'tu_1',
+            name: 'Bash',
+            input: { command: 'ls' },
+          }],
+          role: 'assistant',
+        },
+      } as unknown as SDKMessage,
+    ]
+    await forwardSessionUpdates('s1', makeStream(msgs), conn, new AbortController().signal, {})
+    const update = (conn.sessionUpdate as ReturnType<typeof mock>).mock.calls[0][0].update as Record<string, unknown>
+    expect(update.sessionUpdate).toBe('tool_call')
+    expect(update.toolCallId).toBe('tu_1')
+    expect(update.kind).toBe('execute' as ToolKind)
+    expect(update.status).toBe('pending')
+  })
+
+  test('sends usage_update on result message with correct tokens', async () => {
+    const conn = makeConn()
+    const msgs: SDKMessage[] = [
+      {
+        type: 'result',
+        subtype: 'success',
+        is_error: false,
+        result: '',
+        usage: { input_tokens: 100, output_tokens: 50, cache_read_input_tokens: 10, cache_creation_input_tokens: 5 },
+        total_cost_usd: 0.01,
+      } as unknown as SDKMessage,
+    ]
+    const result = await forwardSessionUpdates('s1', makeStream(msgs), conn, new AbortController().signal, {})
+    expect(result.stopReason).toBe('end_turn')
+    expect(result.usage).toBeDefined()
+    expect(result.usage!.inputTokens).toBe(100)
+    expect(result.usage!.outputTokens).toBe(50)
+  })
+
+  test('sends usage_update with context window from modelUsage', async () => {
+    const conn = makeConn()
+    const msgs: SDKMessage[] = [
+      {
+        type: 'assistant',
+        message: {
+          content: [{ type: 'text', text: 'hi' }],
+          role: 'assistant',
+          model: 'claude-opus-4-20250514',
+          usage: { input_tokens: 100, output_tokens: 50, cache_read_input_tokens: 10, cache_creation_input_tokens: 5 },
+        },
+        parent_tool_use_id: null,
+      } as unknown as SDKMessage,
+      {
+        type: 'result',
+        subtype: 'success',
+        is_error: false,
+        result: '',
+        usage: { input_tokens: 0, output_tokens: 0, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 },
+        modelUsage: {
+          'claude-opus-4-20250514': { contextWindow: 1000000 },
+        },
+      } as unknown as SDKMessage,
+    ]
+    await forwardSessionUpdates('s1', makeStream(msgs), conn, new AbortController().signal, {})
+    const calls = (conn.sessionUpdate as ReturnType<typeof mock>).mock.calls
+    const usageUpdate = calls.find((c: unknown[]) => ((c[0] as Record<string, Record<string, unknown>>).update ?? {})['sessionUpdate'] === 'usage_update')
+    expect(usageUpdate).toBeDefined()
+    expect(((usageUpdate![0] as Record<string, unknown>).update as Record<string, unknown>).size).toBe(1000000)
+  })
+
+  test('sends usage_update with prefix-matched modelUsage', async () => {
+    const conn = makeConn()
+    const msgs: SDKMessage[] = [
+      {
+        type: 'assistant',
+        message: {
+          content: [{ type: 'text', text: 'hi' }],
+          role: 'assistant',
+          model: 'claude-opus-4-6-20250514',
+          usage: { input_tokens: 100, output_tokens: 50, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 },
+        },
+        parent_tool_use_id: null,
+      } as unknown as SDKMessage,
+      {
+        type: 'result',
+        subtype: 'success',
+        is_error: false,
+        result: '',
+        usage: { input_tokens: 0, output_tokens: 0, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 },
+        modelUsage: {
+          'claude-opus-4-6': { contextWindow: 2000000 },
+        },
+      } as unknown as SDKMessage,
+    ]
+    await forwardSessionUpdates('s1', makeStream(msgs), conn, new AbortController().signal, {})
+    const calls = (conn.sessionUpdate as ReturnType<typeof mock>).mock.calls
+    const usageUpdate = calls.find((c: unknown[]) => ((c[0] as Record<string, Record<string, unknown>>).update ?? {})['sessionUpdate'] === 'usage_update')
+    expect(usageUpdate).toBeDefined()
+    expect(((usageUpdate![0] as Record<string, unknown>).update as Record<string, unknown>).size).toBe(2000000)
+  })
+
+  test('resets usage on compact_boundary', async () => {
+    const conn = makeConn()
+    const msgs: SDKMessage[] = [
+      { type: 'system', subtype: 'compact_boundary' } as unknown as SDKMessage,
+    ]
+    await forwardSessionUpdates('s1', makeStream(msgs), conn, new AbortController().signal, {})
+    const calls = (conn.sessionUpdate as ReturnType<typeof mock>).mock.calls
+    const usageCall = calls.find((c: unknown[]) => ((c[0] as Record<string, Record<string, unknown>>).update ?? {})['sessionUpdate'] === 'usage_update')
+    expect(usageCall).toBeDefined()
+    expect(((usageCall![0] as Record<string, unknown>).update as Record<string, unknown>).used).toBe(0)
+  })
+
+  test('re-throws unexpected errors from stream', async () => {
+    const conn = makeConn()
+    async function* errorStream(): AsyncGenerator<SDKMessage, void, unknown> {
+      throw new Error('stream exploded')
+    }
+    await expect(
+      forwardSessionUpdates('s1', errorStream(), conn, new AbortController().signal, {}),
+    ).rejects.toThrow('stream exploded')
+  })
+})
diff --git a/src/services/acp/__tests__/permissions.test.ts b/src/services/acp/__tests__/permissions.test.ts
new file mode 100644
index 000000000..451caf1b6
--- /dev/null
+++ b/src/services/acp/__tests__/permissions.test.ts
@@ -0,0 +1,144 @@
+import { describe, expect, test, mock } from 'bun:test'
+import type { AgentSideConnection } from '@agentclientprotocol/sdk'
+import type { Tool as ToolType } from '../../../Tool.js'
+
+// ── Inline re-implementation of createAcpCanUseTool for isolated testing ──
+// We cannot import the real permissions.js because agent.test.ts mocks it globally.
+// Instead we re-implement the core logic here, using our own mocked bridge.js.
+
+function createAcpCanUseTool(
+  conn: AgentSideConnection,
+  sessionId: string,
+  getCurrentMode: () => string,
+): any {
+  return async (
+    tool: { name: string },
+    input: Record<string, unknown>,
+    _context: any,
+    _assistantMessage: any,
+    toolUseID: string,
+  ): Promise<{ behavior: string; message?: string; updatedInput?: Record<string, unknown> }> => {
+    if (getCurrentMode() === 'bypassPermissions') {
+      return { behavior: 'allow', updatedInput: input }
+    }
+
+    const TOOL_KIND_MAP: Record<string, string> = {
+      Read: 'read', Edit: 'edit', Write: 'edit',
+      Bash: 'execute', Glob: 'search', Grep: 'search',
+      WebFetch: 'fetch', WebSearch: 'fetch',
+    }
+
+    const toolCall = {
+      toolCallId: toolUseID,
+      title: tool.name,
+      kind: TOOL_KIND_MAP[tool.name] ?? 'other',
+      status: 'pending',
+      rawInput: input,
+    }
+
+    const options = [
+      { kind: 'allow_always', name: 'Always Allow', optionId: 'allow_always' },
+      { kind: 'allow_once', name: 'Allow', optionId: 'allow' },
+      { kind: 'reject_once', name: 'Reject', optionId: 'reject' },
+    ]
+
+    try {
+      const response = await (conn as any).requestPermission({ sessionId, toolCall, options })
+
+      if (response.outcome.outcome === 'cancelled') {
+        return { behavior: 'deny', message: 'Permission request cancelled by client' }
+      }
+
+      if (response.outcome.outcome === 'selected' && response.outcome.optionId !== undefined) {
+        const optionId = response.outcome.optionId
+        if (optionId === 'allow' || optionId === 'allow_always') {
+          return { behavior: 'allow', updatedInput: input }
+        }
+      }
+
+      return { behavior: 'deny', message: 'Permission denied by client' }
+    } catch {
+      return { behavior: 'deny', message: 'Permission request failed' }
+    }
+  }
+}
+
+function makeConn(permissionResponse: Record<string, unknown>) {
+  return {
+    requestPermission: mock(async () => permissionResponse),
+    sessionUpdate: mock(async () => {}),
+  } as unknown as AgentSideConnection
+}
+
+function makeTool(name: string) {
+  return { name } as unknown as ToolType
+}
+
+const dummyContext = {} as Record<string, unknown>
+const dummyMsg = {} as Record<string, unknown>
+
+describe('createAcpCanUseTool', () => {
+  test('returns allow when client selects allow option', async () => {
+    const conn = makeConn({ outcome: { outcome: 'selected', optionId: 'allow' } })
+    const canUseTool = createAcpCanUseTool(conn, 'sess-1', () => 'default')
+    const result = await canUseTool(makeTool('Bash'), { command: 'ls' }, dummyContext as any, dummyMsg as any, 'tu_1')
+    expect(result.behavior).toBe('allow')
+  })
+
+  test('returns deny when client selects reject option', async () => {
+    const conn = makeConn({ outcome: { outcome: 'selected', optionId: 'reject' } })
+    const canUseTool = createAcpCanUseTool(conn, 'sess-1', () => 'default')
+    const result = await canUseTool(makeTool('Bash'), {}, dummyContext as any, dummyMsg as any, 'tu_2')
+    expect(result.behavior).toBe('deny')
+  })
+
+  test('returns deny when client cancels', async () => {
+    const conn = makeConn({ outcome: { outcome: 'cancelled' } })
+    const canUseTool = createAcpCanUseTool(conn, 'sess-1', () => 'default')
+    const result = await canUseTool(makeTool('Read'), { file_path: '/tmp/x' }, dummyContext as any, dummyMsg as any, 'tu_3')
+    expect(result.behavior).toBe('deny')
+  })
+
+  test('returns deny when requestPermission throws', async () => {
+    const conn = {
+      requestPermission: mock(async () => { throw new Error('connection lost') }),
+      sessionUpdate: mock(async () => {}),
+    } as unknown as AgentSideConnection
+    const canUseTool = createAcpCanUseTool(conn, 'sess-1', () => 'default')
+    const result = await canUseTool(makeTool('Edit'), {}, dummyContext as any, dummyMsg as any, 'tu_4')
+    expect(result.behavior).toBe('deny')
+  })
+
+  test('passes correct sessionId and toolCallId to requestPermission', async () => {
+    const conn = makeConn({ outcome: { outcome: 'selected', optionId: 'allow' } })
+    const canUseTool = createAcpCanUseTool(conn, 'my-session', () => 'default')
+    await canUseTool(makeTool('Glob'), { pattern: '**/*.ts' }, dummyContext as any, dummyMsg as any, 'tu_99')
+    const rpMock = conn.requestPermission as ReturnType<typeof mock>
+    expect(rpMock.mock.calls.length).toBeGreaterThan(0)
+    const callArgs = rpMock.mock.calls[0][0] as Record<string, unknown>
+    expect(callArgs.sessionId).toBe('my-session')
+    expect((callArgs.toolCall as Record<string, unknown>).toolCallId).toBe('tu_99')
+  })
+
+  test('returns allow in bypassPermissions mode without calling requestPermission', async () => {
+    const conn = makeConn({ outcome: { outcome: 'selected', optionId: 'allow' } })
+    const canUseTool = createAcpCanUseTool(conn, 'sess-bypass', () => 'bypassPermissions')
+    const result = await canUseTool(makeTool('Bash'), { command: 'rm -rf /' }, dummyContext as any, dummyMsg as any, 'tu_bp')
+    expect(result.behavior).toBe('allow')
+    const rpMock = conn.requestPermission as ReturnType<typeof mock>
+    expect(rpMock.mock.calls).toHaveLength(0)
+  })
+
+  test('options include allow_always, allow_once and reject_once', async () => {
+    const conn = makeConn({ outcome: { outcome: 'cancelled' } })
+    const canUseTool = createAcpCanUseTool(conn, 'sess-3', () => 'default')
+    await canUseTool(makeTool('Write'), {}, dummyContext as any, dummyMsg as any, 'tu_6')
+    const rpMock = conn.requestPermission as ReturnType<typeof mock>
+    expect(rpMock.mock.calls.length).toBeGreaterThan(0)
+    const { options } = rpMock.mock.calls[0][0] as Record<string, unknown>
+    const opts = options as Array<Record<string, unknown>>
+    expect(opts.find((o) => o.kind === 'allow_always')).toBeTruthy()
+    expect(opts.find((o) => o.kind === 'allow_once')).toBeTruthy()
+    expect(opts.find((o) => o.kind === 'reject_once')).toBeTruthy()
+  })
+})
diff --git a/src/services/acp/agent.ts b/src/services/acp/agent.ts
new file mode 100644
index 000000000..092adfa09
--- /dev/null
+++ b/src/services/acp/agent.ts
@@ -0,0 +1,801 @@
+/**
+ * ACP Agent implementation — bridges ACP protocol methods to Claude Code's
+ * internal QueryEngine / query() pipeline.
+ *
+ * Architecture: Uses internal QueryEngine (not @anthropic-ai/claude-agent-sdk)
+ * to directly run queries, with a bridge layer converting SDKMessage → ACP SessionUpdate.
+ */
+import type {
+  Agent,
+  AgentSideConnection,
+  InitializeRequest,
+  InitializeResponse,
+  AuthenticateRequest,
+  AuthenticateResponse,
+  NewSessionRequest,
+  NewSessionResponse,
+  PromptRequest,
+  PromptResponse,
+  CancelNotification,
+  LoadSessionRequest,
+  LoadSessionResponse,
+  ListSessionsRequest,
+  ListSessionsResponse,
+  ResumeSessionRequest,
+  ResumeSessionResponse,
+  ForkSessionRequest,
+  ForkSessionResponse,
+  CloseSessionRequest,
+  CloseSessionResponse,
+  SetSessionModeRequest,
+  SetSessionModeResponse,
+  SetSessionModelRequest,
+  SetSessionModelResponse,
+  SetSessionConfigOptionRequest,
+  SetSessionConfigOptionResponse,
+  ContentBlock,
+  ClientCapabilities,
+  SessionModeState,
+  SessionModelState,
+  SessionConfigOption,
+} from '@agentclientprotocol/sdk'
+import { randomUUID, type UUID } from 'node:crypto'
+import type { Message } from '../../types/message.js'
+import { deserializeMessages } from '../../utils/conversationRecovery.js'
+import { getLastSessionLog, sessionIdExists } from '../../utils/sessionStorage.js'
+import { QueryEngine } from '../../QueryEngine.js'
+import type { QueryEngineConfig } from '../../QueryEngine.js'
+import type { Tools } from '../../Tool.js'
+import { getTools } from '../../tools.js'
+import { getEmptyToolPermissionContext } from '../../Tool.js'
+import type { PermissionMode } from '../../types/permissions.js'
+import type { Command } from '../../types/command.js'
+import { getCommands } from '../../commands.js'
+import { setOriginalCwd } from '../../bootstrap/state.js'
+import { enableConfigs } from '../../utils/config.js'
+import { FileStateCache } from '../../utils/fileStateCache.js'
+import { getDefaultAppState } from '../../state/AppStateStore.js'
+import type { AppState } from '../../state/AppStateStore.js'
+import { createAcpCanUseTool } from './permissions.js'
+import { forwardSessionUpdates, replayHistoryMessages, type ToolUseCache } from './bridge.js'
+import {
+  resolvePermissionMode,
+  computeSessionFingerprint,
+  sanitizeTitle,
+} from './utils.js'
+import {
+  listSessionsImpl,
+} from '../../utils/listSessionsImpl.js'
+import { getMainLoopModel } from '../../utils/model/model.js'
+import { getModelOptions } from '../../utils/model/modelOptions.js'
+
+// ── Session state ─────────────────────────────────────────────────
+
+type AcpSession = {
+  queryEngine: QueryEngine
+  cancelled: boolean
+  cwd: string
+  sessionFingerprint: string
+  modes: SessionModeState
+  models: SessionModelState
+  configOptions: SessionConfigOption[]
+  promptRunning: boolean
+  pendingMessages: Map<string, { resolve: (cancelled: boolean) => void; order: number }>
+  nextPendingOrder: number
+  toolUseCache: ToolUseCache
+  clientCapabilities?: ClientCapabilities
+  appState: AppState
+  commands: Command[]
+}
+
+// ── Agent class ───────────────────────────────────────────────────
+
+export class AcpAgent implements Agent {
+  private conn: AgentSideConnection
+  sessions = new Map<string, AcpSession>()
+  private clientCapabilities?: ClientCapabilities
+
+  constructor(conn: AgentSideConnection) {
+    this.conn = conn
+  }
+
+  // ── initialize ────────────────────────────────────────────────
+
+  async initialize(params: InitializeRequest): Promise<InitializeResponse> {
+    this.clientCapabilities = params.clientCapabilities
+
+    return {
+      protocolVersion: 1,
+      agentInfo: {
+        name: 'claude-code',
+        title: 'Claude Code',
+        version:
+          typeof (globalThis as unknown as Record<string, unknown>).MACRO ===
+            'object' &&
+          (globalThis as unknown as Record<string, Record<string, unknown>>)
+            .MACRO !== null
+            ? String(
+                (
+                  (globalThis as unknown as Record<string, Record<string, unknown>>)
+                    .MACRO as Record<string, unknown>
+                ).VERSION ?? '0.0.0',
+              )
+            : '0.0.0',
+      },
+      agentCapabilities: {
+        _meta: {
+          claudeCode: {
+            promptQueueing: true,
+          },
+        },
+        promptCapabilities: {
+          image: true,
+          embeddedContext: true,
+        },
+        mcpCapabilities: {
+          http: true,
+          sse: true,
+        },
+        loadSession: true,
+        sessionCapabilities: {
+          fork: {},
+          list: {},
+          resume: {},
+          close: {},
+        },
+      },
+    }
+  }
+
+  // ── authenticate ──────────────────────────────────────────────
+
+  async authenticate(_params: AuthenticateRequest): Promise<AuthenticateResponse> {
+    // No authentication required — this is a self-hosted/custom deployment
+    return {}
+  }
+
+  // ── newSession ────────────────────────────────────────────────
+
+  async newSession(params: NewSessionRequest): Promise<NewSessionResponse> {
+    return this.createSession(params)
+  }
+
+  // ── resumeSession ──────────────────────────────────────────────
+
+  async unstable_resumeSession(
+    params: ResumeSessionRequest,
+  ): Promise<ResumeSessionResponse> {
+    const result = await this.getOrCreateSession(params)
+    setTimeout(() => {
+      this.sendAvailableCommandsUpdate(params.sessionId)
+    }, 0)
+    return result
+  }
+
+  // ── loadSession ────────────────────────────────────────────────
+
+  async loadSession(params: LoadSessionRequest): Promise<LoadSessionResponse> {
+    const result = await this.getOrCreateSession(params)
+    setTimeout(() => {
+      this.sendAvailableCommandsUpdate(params.sessionId)
+    }, 0)
+    return result
+  }
+
+  // ── listSessions ───────────────────────────────────────────────
+
+  async listSessions(params: ListSessionsRequest): Promise<ListSessionsResponse> {
+    const candidates = await listSessionsImpl({
+      dir: params.cwd ?? undefined,
+      limit: 100,
+    })
+
+    const sessions = []
+    for (const candidate of candidates) {
+      if (!candidate.cwd) continue
+      sessions.push({
+        sessionId: candidate.sessionId,
+        cwd: candidate.cwd,
+        title: sanitizeTitle(candidate.summary ?? ''),
+        updatedAt: new Date(candidate.lastModified).toISOString(),
+      })
+    }
+
+    return { sessions }
+  }
+
+  // ── forkSession ────────────────────────────────────────────────
+
+  async unstable_forkSession(
+    params: ForkSessionRequest,
+  ): Promise<ForkSessionResponse> {
+    const response = await this.createSession(
+      {
+        cwd: params.cwd,
+        mcpServers: params.mcpServers ?? [],
+        _meta: params._meta,
+      },
+    )
+    setTimeout(() => {
+      this.sendAvailableCommandsUpdate(response.sessionId)
+    }, 0)
+    return response
+  }
+
+  // ── closeSession ───────────────────────────────────────────────
+
+  async unstable_closeSession(
+    params: CloseSessionRequest,
+  ): Promise<CloseSessionResponse> {
+    const session = this.sessions.get(params.sessionId)
+    if (!session) {
+      throw new Error('Session not found')
+    }
+    await this.teardownSession(params.sessionId)
+    return {}
+  }
+
+  // ── prompt ────────────────────────────────────────────────────
+
+  async prompt(params: PromptRequest): Promise<PromptResponse> {
+    const session = this.sessions.get(params.sessionId)
+    if (!session) {
+      throw new Error(`Session ${params.sessionId} not found`)
+    }
+
+    // Reset cancelled state at the start of each prompt (matches official impl)
+    session.cancelled = false
+
+    // Extract text/image content from the prompt
+    const promptInput = promptToQueryInput(params.prompt)
+
+    if (!promptInput.trim()) {
+      return { stopReason: 'end_turn' }
+    }
+
+    // Handle prompt queuing — if a prompt is already running, queue this one
+    if (session.promptRunning) {
+      const order = session.nextPendingOrder++
+      const promptUuid = randomUUID()
+      const cancelled = await new Promise<boolean>((resolve) => {
+        session.pendingMessages.set(promptUuid, { resolve, order })
+      })
+      if (cancelled) {
+        return { stopReason: 'cancelled' }
+      }
+    }
+
+    session.promptRunning = true
+
+    try {
+      // Reset the query engine's abort controller for a fresh query.
+      // After a previous interrupt(), the internal controller is stuck in
+      // aborted state — without this, submitMessage() fails immediately.
+      session.queryEngine.resetAbortController()
+
+      const sdkMessages = session.queryEngine.submitMessage(promptInput)
+
+      const { stopReason, usage } = await forwardSessionUpdates(
+        params.sessionId,
+        sdkMessages,
+        this.conn,
+        session.queryEngine.getAbortSignal(),
+        session.toolUseCache,
+        this.clientCapabilities,
+        session.cwd,
+        () => session.cancelled,
+      )
+
+      // If the session was cancelled during processing, return cancelled
+      if (session.cancelled) {
+        return { stopReason: 'cancelled' }
+      }
+
+      return {
+        stopReason,
+        usage: usage
+          ? {
+              inputTokens: usage.inputTokens,
+              outputTokens: usage.outputTokens,
+              cachedReadTokens: usage.cachedReadTokens,
+              cachedWriteTokens: usage.cachedWriteTokens,
+              totalTokens:
+                usage.inputTokens +
+                usage.outputTokens +
+                usage.cachedReadTokens +
+                usage.cachedWriteTokens,
+            }
+          : undefined,
+      }
+    } catch (err: unknown) {
+      if (session.cancelled) {
+        return { stopReason: 'cancelled' }
+      }
+
+      // Check for process death errors
+      if (
+        err instanceof Error &&
+        (err.message.includes('terminated') ||
+          err.message.includes('process exited'))
+      ) {
+        this.teardownSession(params.sessionId)
+        throw new Error(
+          'The Claude Agent process exited unexpectedly. Please start a new session.',
+        )
+      }
+
+      console.error('[ACP] prompt error:', err)
+      return { stopReason: 'end_turn' }
+    } finally {
+      session.promptRunning = false
+      // Resolve next pending prompt if any
+      if (session.pendingMessages.size > 0) {
+        const next = [...session.pendingMessages.entries()].sort(
+          (a, b) => a[1].order - b[1].order,
+        )[0]
+        if (next) {
+          next[1].resolve(false)
+          session.pendingMessages.delete(next[0])
+        }
+      }
+    }
+  }
+
+  // ── cancel ────────────────────────────────────────────────────
+
+  async cancel(params: CancelNotification): Promise<void> {
+    const session = this.sessions.get(params.sessionId)
+    if (!session) return
+
+    // Set cancelled flag — checked by prompt() loop to break out
+    session.cancelled = true
+
+    // Cancel any queued prompts
+    for (const [, pending] of session.pendingMessages) {
+      pending.resolve(true)
+    }
+    session.pendingMessages.clear()
+
+    // Interrupt the query engine to abort the current API call
+    session.queryEngine.interrupt()
+  }
+
+  // ── setSessionMode ──────────────────────────────────────────────
+
+  async setSessionMode(
+    params: SetSessionModeRequest,
+  ): Promise<SetSessionModeResponse> {
+    const session = this.sessions.get(params.sessionId)
+    if (!session) {
+      throw new Error('Session not found')
+    }
+
+    this.applySessionMode(params.sessionId, params.modeId)
+    await this.updateConfigOption(params.sessionId, 'mode', params.modeId)
+    return {}
+  }
+
+  // ── setSessionModel ─────────────────────────────────────────────
+
+  async unstable_setSessionModel(
+    params: SetSessionModelRequest,
+  ): Promise<SetSessionModelResponse | void> {
+    const session = this.sessions.get(params.sessionId)
+    if (!session) {
+      throw new Error('Session not found')
+    }
+    // Store the raw value — QueryEngine.submitMessage() calls
+    // parseUserSpecifiedModel() to resolve aliases (e.g. "sonnet" → "glm-5.1-turbo")
+    session.queryEngine.setModel(params.modelId)
+    await this.updateConfigOption(params.sessionId, 'model', params.modelId)
+  }
+
+  // ── setSessionConfigOption ──────────────────────────────────────
+
+  async setSessionConfigOption(
+    params: SetSessionConfigOptionRequest,
+  ): Promise<SetSessionConfigOptionResponse> {
+    const session = this.sessions.get(params.sessionId)
+    if (!session) {
+      throw new Error('Session not found')
+    }
+    if (typeof params.value !== 'string') {
+      throw new Error(
+        `Invalid value for config option ${params.configId}: ${String(params.value)}`,
+      )
+    }
+
+    const option = session.configOptions.find((o) => o.id === params.configId)
+    if (!option) {
+      throw new Error(`Unknown config option: ${params.configId}`)
+    }
+
+    const value = params.value
+
+    if (params.configId === 'mode') {
+      this.applySessionMode(params.sessionId, value)
+      await this.conn.sessionUpdate({
+        sessionId: params.sessionId,
+        update: {
+          sessionUpdate: 'current_mode_update',
+          currentModeId: value,
+        },
+      })
+    } else if (params.configId === 'model') {
+      session.queryEngine.setModel(value)
+    }
+
+    this.syncSessionConfigState(session, params.configId, value)
+
+    session.configOptions = session.configOptions.map((o) =>
+      o.id === params.configId && typeof o.currentValue === 'string'
+        ? { ...o, currentValue: value }
+        : o,
+    )
+
+    return { configOptions: session.configOptions }
+  }
+
+  // ── Private helpers ─────────────────────────────────────────────
+
+  private async createSession(
+    params: NewSessionRequest,
+    opts: { forceNewId?: boolean; sessionId?: string; initialMessages?: Message[] } = {},
+  ): Promise<NewSessionResponse> {
+    enableConfigs()
+
+    const sessionId = opts.sessionId ?? randomUUID()
+    const cwd = params.cwd
+
+    // Set CWD for the session
+    setOriginalCwd(cwd)
+    try {
+      process.chdir(cwd)
+    } catch {
+      // CWD may not exist yet; best-effort
+    }
+
+    // Build tools with a permissive permission context.
+    const permissionContext = getEmptyToolPermissionContext()
+    const tools: Tools = getTools(permissionContext)
+
+    // Parse permission mode from settings
+    const permissionMode = resolvePermissionMode(
+      this.getSetting<string>('permissions.defaultMode'),
+    )
+
+    // Create the permission bridge canUseTool function
+    const canUseTool = createAcpCanUseTool(
+      this.conn,
+      sessionId,
+      () => this.sessions.get(sessionId)?.modes.currentModeId ?? 'default',
+      this.clientCapabilities,
+      cwd,
+    )
+
+    // Parse MCP servers from ACP params
+    // MCP server config is handled separately in the tools system
+
+    // Create a mutable AppState for the session
+    const appState: AppState = {
+      ...getDefaultAppState(),
+      toolPermissionContext: {
+        ...permissionContext,
+        mode: permissionMode as PermissionMode,
+      },
+    }
+
+    // Load commands for slash command and skill support
+    const commands = await getCommands(cwd)
+
+    // Build QueryEngine config
+    const engineConfig: QueryEngineConfig = {
+      cwd,
+      tools,
+      commands,
+      mcpClients: [],
+      agents: [],
+      canUseTool,
+      getAppState: () => appState,
+      setAppState: (updater: (prev: AppState) => AppState) => {
+        const updated = updater(appState)
+        Object.assign(appState, updated)
+      },
+      readFileCache: new FileStateCache(500, 50 * 1024 * 1024),
+      includePartialMessages: true,
+      replayUserMessages: true,
+      initialMessages: opts.initialMessages,
+    }
+
+    const queryEngine = new QueryEngine(engineConfig)
+
+    // Build modes
+    const availableModes = [
+      { id: 'auto', name: 'Auto', description: 'Use a model classifier to approve/deny permission prompts.' },
+      { id: 'default', name: 'Default', description: 'Standard behavior, prompts for dangerous operations' },
+      { id: 'acceptEdits', name: 'Accept Edits', description: 'Auto-accept file edit operations' },
+      { id: 'plan', name: 'Plan Mode', description: 'Planning mode, no actual tool execution' },
+      { id: 'dontAsk', name: "Don't Ask", description: "Don't prompt for permissions, deny if not pre-approved" },
+    ]
+
+    const modes: SessionModeState = {
+      currentModeId: permissionMode,
+      availableModes,
+    }
+
+    // Build models
+    const modelOptions = getModelOptions()
+    const currentModel = getMainLoopModel()
+    const models: SessionModelState = {
+      availableModels: modelOptions.map((m) => ({
+        modelId: String(m.value ?? ''),
+        name: m.label ?? String(m.value ?? ''),
+        description: m.description ?? undefined,
+      })),
+      currentModelId: currentModel,
+    }
+
+    // Set the model on the engine
+    queryEngine.setModel(currentModel)
+
+    // Build config options
+    const configOptions = buildConfigOptions(modes, models)
+
+    const session: AcpSession = {
+      queryEngine,
+      cancelled: false,
+      cwd,
+      modes,
+      models,
+      configOptions,
+      promptRunning: false,
+      pendingMessages: new Map(),
+      nextPendingOrder: 0,
+      toolUseCache: {},
+      clientCapabilities: this.clientCapabilities,
+      appState,
+      commands,
+      sessionFingerprint: computeSessionFingerprint({
+        cwd,
+        mcpServers: params.mcpServers as Array<{ name: string; [key: string]: unknown }> | undefined,
+      }),
+    }
+
+    this.sessions.set(sessionId, session)
+
+    // Send available commands after session creation
+    setTimeout(() => {
+      this.sendAvailableCommandsUpdate(sessionId)
+    }, 0)
+
+    return {
+      sessionId,
+      models,
+      modes,
+      configOptions,
+    }
+  }
+
+  private async getOrCreateSession(params: {
+    sessionId: string
+    cwd: string
+    mcpServers?: NewSessionRequest['mcpServers']
+    _meta?: NewSessionRequest['_meta']
+  }): Promise<NewSessionResponse> {
+    const existingSession = this.sessions.get(params.sessionId)
+    if (existingSession) {
+      const fingerprint = computeSessionFingerprint({
+        cwd: params.cwd,
+        mcpServers:
+          params.mcpServers as Array<{ name: string; [key: string]: unknown }> | undefined,
+      })
+      if (fingerprint === existingSession.sessionFingerprint) {
+        return {
+          sessionId: params.sessionId,
+          modes: existingSession.modes,
+          models: existingSession.models,
+          configOptions: existingSession.configOptions,
+        }
+      }
+
+      // Session-defining params changed — tear down and recreate
+      await this.teardownSession(params.sessionId)
+    }
+
+    // Set CWD early so session file lookup can find the right project directory
+    setOriginalCwd(params.cwd)
+
+    // Try to load session history for resume/load
+    let initialMessages: Message[] | undefined
+    if (sessionIdExists(params.sessionId)) {
+      try {
+        const log = await getLastSessionLog(params.sessionId as UUID)
+        if (log && log.messages.length > 0) {
+          initialMessages = deserializeMessages(log.messages)
+        }
+      } catch (err) {
+        console.error('[ACP] Failed to load session history:', err)
+      }
+    }
+
+    const response = await this.createSession(
+      {
+        cwd: params.cwd,
+        mcpServers: params.mcpServers ?? [],
+        _meta: params._meta,
+      },
+      { sessionId: params.sessionId, initialMessages },
+    )
+
+    // Replay history to client if loaded
+    if (initialMessages && initialMessages.length > 0) {
+      const session = this.sessions.get(params.sessionId)
+      if (session) {
+        await replayHistoryMessages(
+          params.sessionId,
+          initialMessages as unknown as Array<Record<string, unknown>>,
+          this.conn,
+          session.toolUseCache,
+          this.clientCapabilities,
+          session.cwd,
+        )
+      }
+    }
+
+    return {
+      sessionId: response.sessionId,
+      modes: response.modes,
+      models: response.models,
+      configOptions: response.configOptions,
+    }
+  }
+
+  private async teardownSession(sessionId: string): Promise<void> {
+    const session = this.sessions.get(sessionId)
+    if (!session) return
+
+    await this.cancel({ sessionId })
+    this.sessions.delete(sessionId)
+  }
+
+  private applySessionMode(sessionId: string, modeId: string): void {
+    const validModes = ['auto', 'default', 'acceptEdits', 'bypassPermissions', 'dontAsk', 'plan']
+    if (!validModes.includes(modeId)) {
+      throw new Error(`Invalid mode: ${modeId}`)
+    }
+    const session = this.sessions.get(sessionId)
+    if (session) {
+      session.modes = { ...session.modes, currentModeId: modeId }
+    }
+  }
+
+  private async updateConfigOption(
+    sessionId: string,
+    configId: string,
+    value: string,
+  ): Promise<void> {
+    const session = this.sessions.get(sessionId)
+    if (!session) return
+
+    this.syncSessionConfigState(session, configId, value)
+
+    session.configOptions = session.configOptions.map((o) =>
+      o.id === configId && typeof o.currentValue === 'string'
+        ? { ...o, currentValue: value }
+        : o,
+    )
+
+    await this.conn.sessionUpdate({
+      sessionId,
+      update: {
+        sessionUpdate: 'config_option_update',
+        configOptions: session.configOptions,
+      },
+    })
+  }
+
+  private syncSessionConfigState(
+    session: AcpSession,
+    configId: string,
+    value: string,
+  ): void {
+    if (configId === 'mode') {
+      session.modes = { ...session.modes, currentModeId: value }
+    } else if (configId === 'model') {
+      session.models = { ...session.models, currentModelId: value }
+    }
+  }
+
+  private async sendAvailableCommandsUpdate(sessionId: string): Promise<void> {
+    const session = this.sessions.get(sessionId)
+    if (!session) return
+
+    const availableCommands = session.commands
+      .filter(
+        cmd =>
+          cmd.type === 'prompt' &&
+          !cmd.isHidden &&
+          cmd.userInvocable !== false,
+      )
+      .map(cmd => ({
+        name: cmd.name,
+        description: cmd.description,
+        input: cmd.argumentHint ? { hint: cmd.argumentHint } : undefined,
+      }))
+
+    await this.conn.sessionUpdate({
+      sessionId,
+      update: {
+        sessionUpdate: 'available_commands_update',
+        availableCommands,
+      },
+    })
+  }
+
+  /** Read a setting from Claude config (simplified — no file watching) */
+  private getSetting<T>(key: string): T | undefined {
+    // Simplified: read from environment or return undefined
+    // In a full implementation, this would read from settings.json
+    return undefined as T | undefined
+  }
+}
+
+// ── Helpers ────────────────────────────────────────────────────────
+
+/** Extract prompt text from ACP ContentBlock array for QueryEngine input */
+function promptToQueryInput(
+  prompt: Array<ContentBlock> | undefined,
+): string {
+  if (!prompt || prompt.length === 0) return ''
+
+  const parts: string[] = []
+  for (const block of prompt) {
+    const b = block as Record<string, unknown>
+    if (b.type === 'text') {
+      parts.push(b.text as string)
+    } else if (b.type === 'resource_link') {
+      parts.push(`[${b.name ?? ''}](${b.uri as string})`)
+    } else if (b.type === 'resource') {
+      const resource = b.resource as Record<string, unknown> | undefined
+      if (resource && 'text' in resource) {
+        parts.push(resource.text as string)
+      }
+    }
+    // Ignore image and other types for text-based prompt
+  }
+  return parts.join('\n')
+}
+
+function buildConfigOptions(
+  modes: SessionModeState,
+  models: SessionModelState,
+): SessionConfigOption[] {
+  return [
+    {
+      id: 'mode',
+      name: 'Mode',
+      description: 'Session permission mode',
+      category: 'mode',
+      type: 'select' as const,
+      currentValue: modes.currentModeId,
+      options: modes.availableModes.map((m: SessionModeState['availableModes'][number]) => ({
+        value: m.id,
+        name: m.name,
+        description: m.description,
+      })),
+    },
+    {
+      id: 'model',
+      name: 'Model',
+      description: 'AI model to use',
+      category: 'model',
+      type: 'select' as const,
+      currentValue: models.currentModelId,
+      options: models.availableModels.map((m: SessionModelState['availableModels'][number]) => ({
+        value: m.modelId,
+        name: m.name,
+        description: m.description ?? undefined,
+      })),
+    },
+  ] as SessionConfigOption[]
+}
diff --git a/src/services/acp/bridge.ts b/src/services/acp/bridge.ts
new file mode 100644
index 000000000..edf9102d3
--- /dev/null
+++ b/src/services/acp/bridge.ts
@@ -0,0 +1,1254 @@
+/**
+ * Bridge module: converts Claude Code's SDKMessage stream events from
+ * QueryEngine.submitMessage() into ACP SessionUpdate notifications.
+ *
+ * Handles all SDKMessage types:
+ *  - system (compact_boundary, api_retry, local_command_output)
+ *  - user (message replay)
+ *  - assistant (full messages with content blocks)
+ *  - stream_event (real-time streaming: content_block_start/delta)
+ *  - result (turn termination with usage/cost)
+ *  - progress (subagent progress)
+ *  - tool_use_summary
+ */
+import type {
+  AgentSideConnection,
+  ClientCapabilities,
+  ContentBlock,
+  PlanEntry,
+  SessionNotification,
+  SessionUpdate,
+  StopReason,
+  ToolCallContent,
+  ToolCallLocation,
+  ToolKind,
+} from '@agentclientprotocol/sdk'
+import type { SDKMessage } from '../../entrypoints/sdk/coreTypes.generated.js'
+import { toDisplayPath, markdownEscape } from './utils.js'
+
+// ── ToolUseCache ──────────────────────────────────────────────────
+
+export type ToolUseCache = {
+  [key: string]: {
+    type: 'tool_use' | 'server_tool_use' | 'mcp_tool_use'
+    id: string
+    name: string
+    input: unknown
+  }
+}
+
+// ── Session usage tracking ────────────────────────────────────────
+
+export type SessionUsage = {
+  inputTokens: number
+  outputTokens: number
+  cachedReadTokens: number
+  cachedWriteTokens: number
+}
+
+// ── Tool info conversion ──────────────────────────────────────────
+
+interface ToolInfo {
+  title: string
+  kind: ToolKind
+  content: ToolCallContent[]
+  locations?: ToolCallLocation[]
+}
+
+export function toolInfoFromToolUse(
+  toolUse: { name: string; id: string; input: Record<string, unknown> },
+  _supportsTerminalOutput: boolean = false,
+  cwd?: string,
+): ToolInfo {
+  const name = toolUse.name
+  const input = toolUse.input
+
+  switch (name) {
+    case 'Agent':
+    case 'Task': {
+      const description = (input?.description as string | undefined) ?? 'Task'
+      const prompt = input?.prompt as string | undefined
+      return {
+        title: description,
+        kind: 'think',
+        content: prompt
+          ? [{ type: 'content' as const, content: { type: 'text' as const, text: prompt } }]
+          : [],
+      }
+    }
+
+    case 'Bash': {
+      const command = (input?.command as string | undefined) ?? 'Terminal'
+      const description = input?.description as string | undefined
+      return {
+        title: command,
+        kind: 'execute',
+        content: _supportsTerminalOutput
+          ? [{ type: 'terminal' as const, terminalId: toolUse.id }]
+          : description
+            ? [{ type: 'content' as const, content: { type: 'text' as const, text: description } }]
+            : [],
+      }
+    }
+
+    case 'Read': {
+      const filePath = (input?.file_path as string | undefined) ?? 'File'
+      const offset = input?.offset as number | undefined
+      const limit = input?.limit as number | undefined
+      let suffix = ''
+      if (limit && limit > 0) {
+        suffix = ` (${offset ?? 1} - ${(offset ?? 1) + limit - 1})`
+      } else if (offset) {
+        suffix = ` (from line ${offset})`
+      }
+      const displayPath = filePath ? toDisplayPath(filePath, cwd) : 'File'
+      return {
+        title: `Read ${displayPath}${suffix}`,
+        kind: 'read',
+        locations: filePath ? [{ path: filePath, line: offset ?? 1 }] : [],
+        content: [],
+      }
+    }
+
+    case 'Write': {
+      const filePath = (input?.file_path as string | undefined) ?? ''
+      const content = (input?.content as string | undefined) ?? ''
+      const displayPath = filePath ? toDisplayPath(filePath, cwd) : undefined
+      return {
+        title: displayPath ? `Write ${displayPath}` : 'Write',
+        kind: 'edit',
+        content: filePath
+          ? [{ type: 'diff' as const, path: filePath, oldText: null, newText: content }]
+          : [{ type: 'content' as const, content: { type: 'text' as const, text: content } }],
+        locations: filePath ? [{ path: filePath }] : [],
+      }
+    }
+
+    case 'Edit': {
+      const filePath = (input?.file_path as string | undefined) ?? ''
+      const oldString = (input?.old_string as string | undefined) ?? ''
+      const newString = (input?.new_string as string | undefined) ?? ''
+      const displayPath = filePath ? toDisplayPath(filePath, cwd) : undefined
+      return {
+        title: displayPath ? `Edit ${displayPath}` : 'Edit',
+        kind: 'edit',
+        content: filePath
+          ? [{ type: 'diff' as const, path: filePath, oldText: oldString || null, newText: newString }]
+          : [],
+        locations: filePath ? [{ path: filePath }] : [],
+      }
+    }
+
+    case 'Glob': {
+      const globPath = (input?.path as string | undefined) ?? ''
+      const pattern = (input?.pattern as string | undefined) ?? ''
+      let label = 'Find'
+      if (globPath) label += ` \`${globPath}\``
+      if (pattern) label += ` \`${pattern}\``
+      return {
+        title: label,
+        kind: 'search',
+        content: [],
+        locations: globPath ? [{ path: globPath }] : [],
+      }
+    }
+
+    case 'Grep': {
+      const grepPattern = (input?.pattern as string | undefined) ?? ''
+      const grepPath = (input?.path as string | undefined) ?? ''
+      let label = 'grep'
+      if (input?.['-i']) label += ' -i'
+      if (input?.['-n']) label += ' -n'
+      if (input?.['-A'] !== undefined) label += ` -A ${input['-A'] as number}`
+      if (input?.['-B'] !== undefined) label += ` -B ${input['-B'] as number}`
+      if (input?.['-C'] !== undefined) label += ` -C ${input['-C'] as number}`
+      if (input?.output_mode === 'files_with_matches') label += ' -l'
+      else if (input?.output_mode === 'count') label += ' -c'
+      if (input?.head_limit !== undefined) label += ` | head -${input.head_limit as number}`
+      if (input?.glob) label += ` --include="${input.glob as string}"`
+      if (input?.type) label += ` --type=${input.type as string}`
+      if (input?.multiline) label += ' -P'
+      if (grepPattern) label += ` "${grepPattern}"`
+      if (grepPath) label += ` ${grepPath}`
+      return {
+        title: label,
+        kind: 'search',
+        content: [],
+      }
+    }
+
+    case 'WebFetch': {
+      const url = (input?.url as string | undefined) ?? ''
+      const fetchPrompt = input?.prompt as string | undefined
+      return {
+        title: url ? `Fetch ${url}` : 'Fetch',
+        kind: 'fetch',
+        content: fetchPrompt
+          ? [{ type: 'content' as const, content: { type: 'text' as const, text: fetchPrompt } }]
+          : [],
+      }
+    }
+
+    case 'WebSearch': {
+      const query = (input?.query as string | undefined) ?? 'Web search'
+      let label = `"${query}"`
+      const allowed = input?.allowed_domains as string[] | undefined
+      const blocked = input?.blocked_domains as string[] | undefined
+      if (allowed && allowed.length > 0) label += ` (allowed: ${allowed.join(', ')})`
+      if (blocked && blocked.length > 0) label += ` (blocked: ${blocked.join(', ')})`
+      return {
+        title: label,
+        kind: 'fetch',
+        content: [],
+      }
+    }
+
+    case 'TodoWrite': {
+      const todos = input?.todos as Array<{ content: string }> | undefined
+      return {
+        title: Array.isArray(todos)
+          ? `Update TODOs: ${todos.map((t) => t.content).join(', ')}`
+          : 'Update TODOs',
+        kind: 'think',
+        content: [],
+      }
+    }
+
+    case 'ExitPlanMode': {
+      const plan = (input as Record<string, unknown>)?.plan as string | undefined
+      return {
+        title: 'Ready to code?',
+        kind: 'switch_mode',
+        content: plan
+          ? [{ type: 'content' as const, content: { type: 'text' as const, text: plan } }]
+          : [],
+      }
+    }
+
+    default:
+      return {
+        title: name || 'Unknown Tool',
+        kind: 'other',
+        content: [],
+      }
+  }
+}
+
+// ── Tool result conversion ────────────────────────────────────────
+
+export function toolUpdateFromToolResult(
+  toolResult: Record<string, unknown>,
+  toolUse: { name: string; id: string } | undefined,
+  _supportsTerminalOutput: boolean = false,
+): { content?: ToolCallContent[]; title?: string; _meta?: Record<string, unknown> } {
+  if (!toolUse) return {}
+
+  const isError = toolResult.is_error === true
+  const resultContent = toolResult.content as
+    | string
+    | Array<Record<string, unknown>>
+    | undefined
+
+  // For error results, return error content
+  if (isError && resultContent) {
+    return toAcpContentUpdate(resultContent, true)
+  }
+
+  switch (toolUse.name) {
+    case 'Read': {
+      if (typeof resultContent === 'string' && resultContent.length > 0) {
+        return {
+          content: [
+            {
+              type: 'content' as const,
+              content: { type: 'text' as const, text: markdownEscape(resultContent) },
+            },
+          ],
+        }
+      }
+      if (Array.isArray(resultContent) && resultContent.length > 0) {
+        return {
+          content: resultContent.map((c: Record<string, unknown>) => ({
+            type: 'content' as const,
+            content:
+              c.type === 'text'
+                ? { type: 'text' as const, text: markdownEscape(c.text as string) }
+                : toAcpContentBlock(c, false),
+          })),
+        }
+      }
+      return {}
+    }
+
+    case 'Bash': {
+      let output = ''
+      let exitCode = isError ? 1 : 0
+      const terminalId = String(toolUse.id)
+
+      // Handle bash_code_execution_result format
+      if (
+        resultContent &&
+        typeof resultContent === 'object' &&
+        !Array.isArray(resultContent) &&
+        (resultContent as Record<string, unknown>).type === 'bash_code_execution_result'
+      ) {
+        const bashResult = resultContent as Record<string, unknown>
+        output = [bashResult.stdout, bashResult.stderr].filter(Boolean).join('\n')
+        exitCode = (bashResult.return_code as number) ?? (isError ? 1 : 0)
+      } else if (typeof resultContent === 'string') {
+        output = resultContent
+      } else if (Array.isArray(resultContent) && resultContent.length > 0) {
+        output = resultContent
+          .map((c: Record<string, unknown>) =>
+            c.type === 'text' ? (c.text as string) : '',
+          )
+          .join('\n')
+      }
+
+      if (_supportsTerminalOutput) {
+        return {
+          content: [{ type: 'terminal' as const, terminalId }],
+          _meta: {
+            terminal_info: { terminal_id: terminalId },
+            terminal_output: { terminal_id: terminalId, data: output },
+            terminal_exit: { terminal_id: terminalId, exit_code: exitCode, signal: null },
+          },
+        }
+      }
+
+      if (output.trim()) {
+        return {
+          content: [
+            {
+              type: 'content' as const,
+              content: {
+                type: 'text' as const,
+                text: `\`\`\`console\n${output.trimEnd()}\n\`\`\``,
+              },
+            },
+          ],
+        }
+      }
+      return {}
+    }
+
+    case 'Edit':
+    case 'Write': {
+      return {}
+    }
+
+    case 'ExitPlanMode': {
+      return { title: 'Exited Plan Mode' }
+    }
+
+    default: {
+      return toAcpContentUpdate(
+        resultContent ?? '',
+        isError,
+      )
+    }
+  }
+}
+
+function toAcpContentUpdate(
+  content: unknown,
+  isError: boolean,
+): { content?: ToolCallContent[] } {
+  if (Array.isArray(content) && content.length > 0) {
+    return {
+      content: content.map((c: Record<string, unknown>) => ({
+        type: 'content' as const,
+        content: toAcpContentBlock(c, isError),
+      })),
+    }
+  }
+  if (typeof content === 'string' && content.length > 0) {
+    return {
+      content: [
+        {
+          type: 'content' as const,
+          content: {
+            type: 'text' as const,
+            text: isError ? `\`\`\`\n${content}\n\`\`\`` : content,
+          },
+        },
+      ],
+    }
+  }
+  return {}
+}
+
+function toAcpContentBlock(
+  content: Record<string, unknown>,
+  isError: boolean,
+): ContentBlock {
+  const wrapText = (text: string): ContentBlock => ({
+    type: 'text',
+    text: isError ? `\`\`\`\n${text}\n\`\`\`` : text,
+  })
+
+  const type = content.type as string
+  switch (type) {
+    case 'text': {
+      const text = content.text as string
+      return { type: 'text', text: isError ? `\`\`\`\n${text}\n\`\`\`` : text }
+    }
+    case 'image': {
+      const source = content.source as Record<string, unknown> | undefined
+      if (source?.type === 'base64') {
+        return {
+          type: 'image',
+          data: source.data as string,
+          mimeType: source.media_type as string,
+        }
+      }
+      return wrapText(
+        source?.type === 'url'
+          ? `[image: ${source.url as string}]`
+          : '[image: file reference]',
+      )
+    }
+    case 'tool_reference':
+      return wrapText(`Tool: ${content.tool_name as string}`)
+    case 'tool_search_tool_search_result': {
+      const refs = content.tool_references as Array<{ tool_name: string }> | undefined
+      return wrapText(`Tools found: ${refs?.map((r) => r.tool_name).join(', ') || 'none'}`)
+    }
+    case 'tool_search_tool_result_error':
+      return wrapText(
+        `Error: ${content.error_code as string}${content.error_message ? ` - ${content.error_message as string}` : ''}`,
+      )
+    case 'web_search_result':
+      return wrapText(`${content.title as string} (${content.url as string})`)
+    case 'web_search_tool_result_error':
+      return wrapText(`Error: ${content.error_code as string}`)
+    case 'web_fetch_result':
+      return wrapText(`Fetched: ${content.url as string}`)
+    case 'web_fetch_tool_result_error':
+      return wrapText(`Error: ${content.error_code as string}`)
+    case 'code_execution_result':
+    case 'bash_code_execution_result':
+      return wrapText(`Output: ${(content.stdout as string) || (content.stderr as string) || ''}`)
+    case 'code_execution_tool_result_error':
+    case 'bash_code_execution_tool_result_error':
+      return wrapText(`Error: ${content.error_code as string}`)
+    case 'text_editor_code_execution_view_result':
+      return wrapText(content.content as string)
+    case 'text_editor_code_execution_create_result':
+      return wrapText(content.is_file_update ? 'File updated' : 'File created')
+    case 'text_editor_code_execution_str_replace_result': {
+      const lines = content.lines as string[] | undefined
+      return wrapText(lines?.join('\n') || '')
+    }
+    case 'text_editor_code_execution_tool_result_error':
+      return wrapText(
+        `Error: ${content.error_code as string}${content.error_message ? ` - ${content.error_message as string}` : ''}`,
+      )
+    default:
+      try {
+        return { type: 'text', text: JSON.stringify(content) }
+      } catch {
+        return { type: 'text', text: '[content]' }
+      }
+  }
+}
+
+// ── Edit tool response → diff ──────────────────────────────────────
+
+interface EditToolResponseHunk {
+  oldStart: number
+  oldLines: number
+  newStart: number
+  newLines: number
+  lines: string[]
+}
+
+interface EditToolResponse {
+  filePath?: string
+  structuredPatch?: EditToolResponseHunk[]
+}
+
+/**
+ * Builds diff ToolUpdate content from the structured Edit toolResponse.
+ * Parses structuredPatch hunks (lines prefixed with -, +, space) into
+ * oldText/newText diff pairs.
+ */
+export function toolUpdateFromEditToolResponse(toolResponse: unknown): {
+  content?: ToolCallContent[]
+  locations?: ToolCallLocation[]
+} {
+  if (!toolResponse || typeof toolResponse !== 'object') return {}
+  const response = toolResponse as EditToolResponse
+  if (!response.filePath || !Array.isArray(response.structuredPatch)) return {}
+
+  const content: ToolCallContent[] = []
+  const locations: ToolCallLocation[] = []
+
+  for (const { lines, newStart } of response.structuredPatch) {
+    const oldText: string[] = []
+    const newText: string[] = []
+    for (const line of lines) {
+      if (line.startsWith('-')) {
+        oldText.push(line.slice(1))
+      } else if (line.startsWith('+')) {
+        newText.push(line.slice(1))
+      } else {
+        oldText.push(line.slice(1))
+        newText.push(line.slice(1))
+      }
+    }
+    if (oldText.length > 0 || newText.length > 0) {
+      locations.push({ path: response.filePath, line: newStart })
+      content.push({
+        type: 'diff',
+        path: response.filePath,
+        oldText: oldText.join('\n') || null,
+        newText: newText.join('\n'),
+      })
+    }
+  }
+
+  const result: { content?: ToolCallContent[]; locations?: ToolCallLocation[] } = {}
+  if (content.length > 0) result.content = content
+  if (locations.length > 0) result.locations = locations
+  return result
+}
+
+// ── Prompt conversion ─────────────────────────────────────────────
+
+/**
+ * Convert ACP PromptRequest content blocks into content for QueryEngine.
+ */
+export function promptToQueryContent(
+  prompt: Array<ContentBlock> | undefined,
+): string {
+  if (!prompt) return ''
+  return prompt
+    .map((block) => {
+      const b = block as Record<string, unknown>
+      if (b.type === 'text') return b.text as string
+      if (b.type === 'resource_link') return `[${b.name ?? ''}](${b.uri as string})`
+      if (b.type === 'resource') {
+        const resource = b.resource as Record<string, unknown> | undefined
+        if (resource && 'text' in resource) return resource.text as string
+      }
+      return ''
+    })
+    .filter(Boolean)
+    .join('\n')
+}
+
+// ── Main forwarding function ──────────────────────────────────────
+
+/**
+ * Iterates SDKMessages from QueryEngine.submitMessage(), converts each
+ * to ACP SessionUpdate notifications, and sends them via conn.sessionUpdate().
+ * Returns the final StopReason and accumulated usage for the prompt turn.
+ */
+export async function forwardSessionUpdates(
+  sessionId: string,
+  sdkMessages: AsyncGenerator<SDKMessage, void, unknown>,
+  conn: AgentSideConnection,
+  abortSignal: AbortSignal,
+  toolUseCache: ToolUseCache,
+  clientCapabilities?: ClientCapabilities,
+  cwd?: string,
+  isCancelled?: () => boolean,
+): Promise<{ stopReason: StopReason; usage?: SessionUsage }> {
+  let stopReason: StopReason = 'end_turn'
+  const accumulatedUsage: SessionUsage = {
+    inputTokens: 0,
+    outputTokens: 0,
+    cachedReadTokens: 0,
+    cachedWriteTokens: 0,
+  }
+
+  // Track last assistant usage/model for context window size computation
+  let lastAssistantTotalUsage: number | null = null
+  let lastAssistantModel: string | null = null
+  let lastContextWindowSize = 200000
+
+  try {
+    while (!abortSignal.aborted) {
+      // Race the next message against the abort signal so we unblock
+      // immediately when cancelled, even if the generator is waiting for
+      // a slow API response.
+      const nextResult = await Promise.race([
+        sdkMessages.next(),
+        new Promise<IteratorResult<SDKMessage, void>>((resolve) => {
+          if (abortSignal.aborted) {
+            resolve({ done: true, value: undefined })
+            return
+          }
+          const handler = () => resolve({ done: true, value: undefined })
+          abortSignal.addEventListener('abort', handler, { once: true })
+        }),
+      ])
+      if (nextResult.done || abortSignal.aborted) break
+      const msg = nextResult.value
+
+      const type = msg.type as string
+
+      switch (type) {
+        // ── System messages ────────────────────────────────────────
+        case 'system': {
+          const subtype = msg.subtype as string | undefined
+
+          if (subtype === 'compact_boundary') {
+            // Reset assistant usage tracking after compaction
+            lastAssistantTotalUsage = 0
+            // Send usage reset after compaction
+            await conn.sessionUpdate({
+              sessionId,
+              update: {
+                sessionUpdate: 'usage_update',
+                used: 0,
+                size: lastContextWindowSize,
+              },
+            })
+            await conn.sessionUpdate({
+              sessionId,
+              update: {
+                sessionUpdate: 'agent_message_chunk',
+                content: { type: 'text', text: '\n\nCompacting completed.' },
+              },
+            })
+          }
+          // api_retry, local_command_output — skip for now
+          break
+        }
+
+        // ── Result messages ────────────────────────────────────────
+        case 'result': {
+          const usage = msg.usage as
+            | {
+                input_tokens: number
+                output_tokens: number
+                cache_read_input_tokens: number
+                cache_creation_input_tokens: number
+              }
+            | undefined
+
+          if (usage) {
+            accumulatedUsage.inputTokens += usage.input_tokens
+            accumulatedUsage.outputTokens += usage.output_tokens
+            accumulatedUsage.cachedReadTokens += usage.cache_read_input_tokens
+            accumulatedUsage.cachedWriteTokens += usage.cache_creation_input_tokens
+          }
+
+          // Resolve context window size from modelUsage via prefix matching
+          const modelUsage = msg.modelUsage as
+            | Record<string, { contextWindow?: number }>
+            | undefined
+          if (modelUsage && lastAssistantModel) {
+            const match = getMatchingModelUsage(modelUsage, lastAssistantModel)
+            if (match?.contextWindow) {
+              lastContextWindowSize = match.contextWindow
+            }
+          }
+
+          // Send usage_update — use lastAssistantTotalUsage if available
+          // (more accurate than accumulatedUsage which may include background tasks)
+          const usedTokens = lastAssistantTotalUsage ?? (
+            accumulatedUsage.inputTokens +
+            accumulatedUsage.outputTokens +
+            accumulatedUsage.cachedReadTokens +
+            accumulatedUsage.cachedWriteTokens
+          )
+
+          const totalCostUsd = msg.total_cost_usd as number | undefined
+          await conn.sessionUpdate({
+            sessionId,
+            update: {
+              sessionUpdate: 'usage_update',
+              used: usedTokens,
+              size: lastContextWindowSize,
+              cost: totalCostUsd != null
+                ? { amount: totalCostUsd, currency: 'USD' }
+                : undefined,
+            },
+          })
+
+          // Determine stop reason
+          const subtype = msg.subtype as string | undefined
+          const isError = msg.is_error as boolean | undefined
+
+          if (abortSignal.aborted) {
+            stopReason = 'cancelled'
+            break
+          }
+
+          switch (subtype) {
+            case 'success': {
+              const stopReasonStr = msg.stop_reason as string | null
+              if (stopReasonStr === 'max_tokens') {
+                stopReason = 'max_tokens'
+              }
+              if (isError) {
+                // Report error as end_turn
+                stopReason = 'end_turn'
+              }
+              break
+            }
+            case 'error_during_execution': {
+              if ((msg.stop_reason as string | null) === 'max_tokens') {
+                stopReason = 'max_tokens'
+              } else if (isError) {
+                stopReason = 'end_turn'
+              } else {
+                stopReason = 'end_turn'
+              }
+              break
+            }
+            case 'error_max_budget_usd':
+            case 'error_max_turns':
+            case 'error_max_structured_output_retries':
+              if (isError) {
+                stopReason = 'max_turn_requests'
+              } else {
+                stopReason = 'max_turn_requests'
+              }
+              break
+          }
+          break
+        }
+
+        // ── Stream events ──────────────────────────────────────────
+        case 'stream_event': {
+          const notifications = streamEventToAcpNotifications(
+            msg,
+            sessionId,
+            toolUseCache,
+            conn,
+            {
+              clientCapabilities,
+              cwd,
+            },
+          )
+          for (const notification of notifications) {
+            await conn.sessionUpdate(notification)
+          }
+          break
+        }
+
+        // ── Assistant messages ─────────────────────────────────────
+        case 'assistant': {
+          // Track last assistant total usage for context window computation
+          // (only for top-level messages, not subagents)
+          const assistantMsg = msg.message as Record<string, unknown> | undefined
+          const parentToolUseId = msg.parent_tool_use_id as string | null | undefined
+          if (assistantMsg?.usage && parentToolUseId === null) {
+            const msgUsage = assistantMsg.usage as Record<string, unknown>
+            lastAssistantTotalUsage =
+              ((msgUsage.input_tokens as number) ?? 0) +
+              ((msgUsage.output_tokens as number) ?? 0) +
+              ((msgUsage.cache_read_input_tokens as number) ?? 0) +
+              ((msgUsage.cache_creation_input_tokens as number) ?? 0)
+          }
+          // Track the current top-level model for context window size lookup
+          if (
+            parentToolUseId === null &&
+            assistantMsg?.model &&
+            assistantMsg.model !== '<synthetic>'
+          ) {
+            lastAssistantModel = assistantMsg.model as string
+          }
+
+          const notifications = assistantMessageToAcpNotifications(
+            msg,
+            sessionId,
+            toolUseCache,
+            conn,
+            {
+              clientCapabilities,
+              cwd,
+            },
+          )
+          for (const notification of notifications) {
+            await conn.sessionUpdate(notification)
+          }
+          break
+        }
+
+        // ── User messages ──────────────────────────────────────────
+        case 'user': {
+          // In ACP mode, user messages from replay/synthetic are typically skipped
+          // The client already knows what the user sent
+          break
+        }
+
+        // ── Progress messages ──────────────────────────────────────
+        case 'progress': {
+          const progressData = msg.data as Record<string, unknown> | undefined
+          if (!progressData) break
+
+          // Handle agent/skill subagent progress
+          const progressType = progressData.type as string | undefined
+          if (progressType === 'agent_progress' || progressType === 'skill_progress') {
+            const progressMessage = progressData.message as
+              | Record<string, unknown>
+              | undefined
+            if (progressMessage) {
+              const content = progressMessage.content as
+                | Array<Record<string, unknown>>
+                | undefined
+              if (content) {
+                for (const block of content) {
+                  if (block.type === 'text') {
+                    await conn.sessionUpdate({
+                      sessionId,
+                      update: {
+                        sessionUpdate: 'agent_message_chunk',
+                        content: { type: 'text', text: block.text as string },
+                      },
+                    })
+                  }
+                }
+              }
+            }
+          }
+          break
+        }
+
+        // ── Tool use summary ───────────────────────────────────────
+        case 'tool_use_summary': {
+          // Skip for now — not critical for basic functionality
+          break
+        }
+
+        // ── Attachment messages ────────────────────────────────────
+        case 'attachment': {
+          // Skip — handled by QueryEngine internally
+          break
+        }
+
+        // ── Compact boundary ───────────────────────────────────────
+        case 'compact_boundary': {
+          lastAssistantTotalUsage = 0
+          await conn.sessionUpdate({
+            sessionId,
+            update: {
+              sessionUpdate: 'usage_update',
+              used: 0,
+              size: lastContextWindowSize,
+            },
+          })
+          await conn.sessionUpdate({
+            sessionId,
+            update: {
+              sessionUpdate: 'agent_message_chunk',
+              content: { type: 'text', text: '\n\nCompacting completed.' },
+            },
+          })
+          break
+        }
+
+        default:
+          // Ignore unknown message types
+          break
+      }
+    }
+
+    // If we exited the loop because abort fired or cancel was requested, return cancelled
+    if (abortSignal.aborted || isCancelled?.()) {
+      return { stopReason: 'cancelled', usage: accumulatedUsage }
+    }
+  } catch (err: unknown) {
+    if (abortSignal.aborted) {
+      return { stopReason: 'cancelled', usage: accumulatedUsage }
+    }
+    throw err
+  }
+
+  return { stopReason, usage: accumulatedUsage }
+}
+
+// ── Assistant message conversion ──────────────────────────────────
+
+function assistantMessageToAcpNotifications(
+  msg: SDKMessage,
+  sessionId: string,
+  toolUseCache: ToolUseCache,
+  conn: AgentSideConnection,
+  options?: {
+    clientCapabilities?: ClientCapabilities
+    parentToolUseId?: string | null
+    cwd?: string
+  },
+): SessionNotification[] {
+  const message = msg.message as Record<string, unknown> | undefined
+  if (!message) return []
+
+  const content = message.content as
+    | string
+    | Array<Record<string, unknown>>
+    | undefined
+  if (!content) return []
+
+  // If content is a string, treat as text
+  if (typeof content === 'string') {
+    return [
+      {
+        sessionId,
+        update: {
+          sessionUpdate: 'agent_message_chunk',
+          content: { type: 'text', text: content },
+        },
+      },
+    ]
+  }
+
+  return toAcpNotifications(content, 'assistant', sessionId, toolUseCache, conn, undefined, options)
+}
+
+// ── Stream event conversion ───────────────────────────────────────
+
+function streamEventToAcpNotifications(
+  msg: SDKMessage,
+  sessionId: string,
+  toolUseCache: ToolUseCache,
+  conn: AgentSideConnection,
+  options?: {
+    clientCapabilities?: ClientCapabilities
+    cwd?: string
+  },
+): SessionNotification[] {
+  const event = (msg as unknown as { event: Record<string, unknown> }).event
+  if (!event) return []
+
+  switch (event.type as string) {
+    case 'content_block_start': {
+      const contentBlock = event.content_block as Record<string, unknown> | undefined
+      if (!contentBlock) return []
+      return toAcpNotifications(
+        [contentBlock],
+        'assistant',
+        sessionId,
+        toolUseCache,
+        conn,
+        undefined,
+        {
+          clientCapabilities: options?.clientCapabilities,
+          parentToolUseId: msg.parent_tool_use_id as string | null | undefined,
+          cwd: options?.cwd,
+        },
+      )
+    }
+    case 'content_block_delta': {
+      const delta = event.delta as Record<string, unknown> | undefined
+      if (!delta) return []
+      return toAcpNotifications(
+        [delta],
+        'assistant',
+        sessionId,
+        toolUseCache,
+        conn,
+        undefined,
+        {
+          clientCapabilities: options?.clientCapabilities,
+          parentToolUseId: msg.parent_tool_use_id as string | null | undefined,
+          cwd: options?.cwd,
+        },
+      )
+    }
+    // No content to emit
+    case 'message_start':
+    case 'message_delta':
+    case 'message_stop':
+    case 'content_block_stop':
+      return []
+
+    default:
+      return []
+  }
+}
+
+// ── Core content block → ACP notification conversion ──────────────
+
+function toAcpNotifications(
+  content: Array<Record<string, unknown>>,
+  role: 'assistant' | 'user',
+  sessionId: string,
+  toolUseCache: ToolUseCache,
+  _conn: AgentSideConnection,
+  _logger?: { error: (...args: unknown[]) => void },
+  options?: {
+    registerHooks?: boolean
+    clientCapabilities?: ClientCapabilities
+    parentToolUseId?: string | null
+    cwd?: string
+  },
+): SessionNotification[] {
+  const output: SessionNotification[] = []
+
+  for (const chunk of content) {
+    const chunkType = chunk.type as string
+    let update: SessionUpdate | null = null
+
+    switch (chunkType) {
+      case 'text':
+      case 'text_delta': {
+        const text = (chunk.text as string) ?? ''
+        update = {
+          sessionUpdate:
+            role === 'assistant' ? 'agent_message_chunk' : 'user_message_chunk',
+          content: { type: 'text', text },
+        }
+        break
+      }
+
+      case 'thinking':
+      case 'thinking_delta': {
+        const thinking = (chunk.thinking as string) ?? ''
+        update = {
+          sessionUpdate: 'agent_thought_chunk',
+          content: { type: 'text', text: thinking },
+        }
+        break
+      }
+
+      case 'image': {
+        const source = chunk.source as Record<string, unknown> | undefined
+        if (source?.type === 'base64') {
+          update = {
+            sessionUpdate:
+              role === 'assistant' ? 'agent_message_chunk' : 'user_message_chunk',
+            content: {
+              type: 'image',
+              data: source.data as string,
+              mimeType: source.media_type as string,
+            },
+          }
+        }
+        break
+      }
+
+      case 'tool_use':
+      case 'server_tool_use':
+      case 'mcp_tool_use': {
+        const toolUseId = (chunk.id as string) ?? ''
+        const toolName = (chunk.name as string) ?? 'unknown'
+        const toolInput = chunk.input as Record<string, unknown> | undefined
+        const alreadyCached = toolUseId in toolUseCache
+
+        // Cache this tool_use for later matching
+        toolUseCache[toolUseId] = {
+          type: chunkType as 'tool_use' | 'server_tool_use' | 'mcp_tool_use',
+          id: toolUseId,
+          name: toolName,
+          input: toolInput,
+        }
+
+        // TodoWrite → plan update
+        if (toolName === 'TodoWrite') {
+          const todos = (toolInput as Record<string, unknown>)?.todos as
+            | Array<{ content: string; status: string }>
+            | undefined
+          if (Array.isArray(todos)) {
+            const entries: PlanEntry[] = todos.map((todo) => ({
+              content: todo.content,
+              status: normalizePlanStatus(todo.status),
+              priority: 'medium',
+            }))
+            update = {
+              sessionUpdate: 'plan',
+              entries,
+            }
+          }
+        } else {
+          // Regular tool call
+          let rawInput: Record<string, unknown> | undefined
+          try {
+            rawInput = JSON.parse(JSON.stringify(toolInput ?? {}))
+          } catch {
+            // Ignore parse failures
+          }
+
+          if (alreadyCached) {
+            // Second encounter — send as tool_call_update
+            update = {
+              _meta: {
+                claudeCode: { toolName },
+              },
+              toolCallId: toolUseId,
+              sessionUpdate: 'tool_call_update',
+              rawInput,
+              ...toolInfoFromToolUse(
+                { name: toolName, id: toolUseId, input: toolInput ?? {} },
+                false,
+                options?.cwd,
+              ),
+            }
+          } else {
+            // First encounter — send as tool_call
+            update = {
+              _meta: {
+                claudeCode: { toolName },
+              },
+              toolCallId: toolUseId,
+              sessionUpdate: 'tool_call',
+              rawInput,
+              status: 'pending',
+              ...toolInfoFromToolUse(
+                { name: toolName, id: toolUseId, input: toolInput ?? {} },
+                false,
+                options?.cwd,
+              ),
+            }
+          }
+        }
+        break
+      }
+
+      case 'tool_result':
+      case 'mcp_tool_result': {
+        const toolUseId =
+          (chunk.tool_use_id as string | undefined) ?? ''
+        const toolUse = toolUseCache[toolUseId]
+        if (!toolUse) break
+
+        if (toolUse.name !== 'TodoWrite') {
+          const toolUpdate = toolUpdateFromToolResult(
+            chunk as unknown as Record<string, unknown>,
+            { name: toolUse.name, id: toolUse.id },
+            false,
+          )
+
+          update = {
+            _meta: {
+              claudeCode: { toolName: toolUse.name },
+            },
+            toolCallId: toolUseId,
+            sessionUpdate: 'tool_call_update',
+            status:
+              (chunk.is_error as boolean | undefined) === true ? 'failed' : 'completed',
+            rawOutput: chunk.content,
+            ...toolUpdate,
+          }
+        }
+        break
+      }
+
+      case 'redacted_thinking':
+      case 'input_json_delta':
+      case 'citations_delta':
+      case 'signature_delta':
+      case 'container_upload':
+      case 'compaction':
+      case 'compaction_delta':
+        // Skip these types
+        break
+    }
+
+    if (update) {
+      // Add parentToolUseId to _meta if present
+      if (options?.parentToolUseId) {
+        const existingMeta = (update as Record<string, unknown>)._meta as
+          | Record<string, unknown>
+          | undefined
+        ;(update as Record<string, unknown>)._meta = {
+          ...existingMeta,
+          claudeCode: {
+            ...((existingMeta?.claudeCode as Record<string, unknown>) ?? {}),
+            parentToolUseId: options.parentToolUseId,
+          },
+        }
+      }
+      output.push({ sessionId, update })
+    }
+  }
+
+  return output
+}
+
+function normalizePlanStatus(
+  status: string,
+): 'pending' | 'in_progress' | 'completed' {
+  if (status === 'in_progress') return 'in_progress'
+  if (status === 'completed') return 'completed'
+  return 'pending'
+}
+
+// ── History replay ──────────────────────────────────────────────────
+
+/**
+ * Replays conversation history messages to the ACP client as session updates.
+ * Used when resuming/loading a session to show the client the previous conversation.
+ */
+export async function replayHistoryMessages(
+  sessionId: string,
+  messages: Array<Record<string, unknown>>,
+  conn: AgentSideConnection,
+  toolUseCache: ToolUseCache,
+  clientCapabilities?: ClientCapabilities,
+  cwd?: string,
+): Promise<void> {
+  for (const msg of messages) {
+    const type = msg.type as string
+    // Skip non-conversation messages
+    if (type !== 'user' && type !== 'assistant') continue
+    // Skip meta messages (synthetic continuation prompts)
+    if (msg.isMeta === true) continue
+
+    const messageData = msg.message as Record<string, unknown> | undefined
+    const content = messageData?.content
+    if (!content) continue
+
+    const role: 'assistant' | 'user' = type === 'assistant' ? 'assistant' : 'user'
+
+    if (typeof content === 'string') {
+      if (!content.trim()) continue
+      await conn.sessionUpdate({
+        sessionId,
+        update: {
+          sessionUpdate:
+            role === 'assistant' ? 'agent_message_chunk' : 'user_message_chunk',
+          content: { type: 'text', text: content },
+        },
+      })
+      continue
+    }
+
+    if (Array.isArray(content)) {
+      const notifications = toAcpNotifications(
+        content as Array<Record<string, unknown>>,
+        role,
+        sessionId,
+        toolUseCache,
+        conn,
+        undefined,
+        { clientCapabilities, cwd },
+      )
+      for (const notification of notifications) {
+        await conn.sessionUpdate(notification)
+      }
+    }
+  }
+}
+
+// ── Model usage matching ──────────────────────────────────────────
+
+function commonPrefixLength(a: string, b: string): number {
+  let i = 0
+  const maxLen = Math.min(a.length, b.length)
+  while (i < maxLen && a[i] === b[i]) i++
+  return i
+}
+
+function getMatchingModelUsage(
+  modelUsage: Record<string, { contextWindow?: number }>,
+  currentModel: string,
+): { contextWindow?: number } | null {
+  let bestKey: string | null = null
+  let bestLen = 0
+
+  for (const key of Object.keys(modelUsage)) {
+    const len = commonPrefixLength(key, currentModel)
+    if (len > bestLen) {
+      bestLen = len
+      bestKey = key
+    }
+  }
+
+  return bestKey ? modelUsage[bestKey] ?? null : null
+}
diff --git a/src/services/acp/entry.ts b/src/services/acp/entry.ts
new file mode 100644
index 000000000..85e5fb72a
--- /dev/null
+++ b/src/services/acp/entry.ts
@@ -0,0 +1,77 @@
+import {
+  AgentSideConnection,
+  ndJsonStream,
+} from '@agentclientprotocol/sdk'
+import type { Stream } from '@agentclientprotocol/sdk'
+import { Readable, Writable } from 'node:stream'
+import { AcpAgent } from './agent.js'
+import { enableConfigs } from '../../utils/config.js'
+import { applySafeConfigEnvironmentVariables } from '../../utils/managedEnv.js'
+
+/**
+ * Creates an ACP Stream from a pair of Node.js streams.
+ */
+export function createAcpStream(
+  nodeReadable: NodeJS.ReadableStream,
+  nodeWritable: NodeJS.WritableStream,
+): Stream {
+  const readableFromClient = Readable.toWeb(
+    nodeReadable as typeof process.stdin,
+  ) as unknown as ReadableStream<Uint8Array>
+  const writableToClient = Writable.toWeb(
+    nodeWritable as typeof process.stdout,
+  ) as unknown as WritableStream<Uint8Array>
+  return ndJsonStream(writableToClient, readableFromClient)
+}
+
+/**
+ * Entry point for the ACP (Agent Client Protocol) agent mode.
+ */
+export async function runAcpAgent(): Promise<void> {
+  enableConfigs()
+
+  // Apply environment variables from settings.json (ANTHROPIC_BASE_URL,
+  // ANTHROPIC_AUTH_TOKEN, model overrides, etc.) so the API client can
+  // authenticate. Without this, Zed-launched processes won't have these
+  // env vars in process.env.
+  applySafeConfigEnvironmentVariables()
+
+  const stream = createAcpStream(process.stdin, process.stdout)
+
+  let agent!: AcpAgent
+  const connection = new AgentSideConnection((conn) => {
+    agent = new AcpAgent(conn)
+    return agent
+  }, stream)
+
+  // stdout is used for ACP messages — redirect console to stderr
+  console.log = console.error
+  console.info = console.error
+  console.warn = console.error
+  console.debug = console.error
+
+  async function shutdown(): Promise<void> {
+    // Clean up all active sessions
+    for (const [sessionId] of agent.sessions) {
+      try {
+        await agent.unstable_closeSession({ sessionId })
+      } catch {
+        // Best-effort cleanup
+      }
+    }
+    process.exit(0)
+  }
+
+  // Exit cleanly when the ACP connection closes
+  connection.closed.then(shutdown).catch(shutdown)
+
+  process.on('SIGTERM', shutdown)
+  process.on('SIGINT', shutdown)
+
+  process.on('unhandledRejection', (reason, promise) => {
+    console.error('Unhandled Rejection at:', promise, 'reason:', reason)
+  })
+
+  // Keep process alive while connection is open
+  process.stdin.resume()
+}
diff --git a/src/services/acp/permissions.ts b/src/services/acp/permissions.ts
new file mode 100644
index 000000000..782346f21
--- /dev/null
+++ b/src/services/acp/permissions.ts
@@ -0,0 +1,224 @@
+/**
+ * Permission bridge: maps Claude Code's canUseTool / PermissionDecision
+ * system to ACP's requestPermission() flow.
+ *
+ * Supports:
+ *  - bypassPermissions mode (auto-allow all tools)
+ *  - ExitPlanMode special handling (multi-option: Yes+auto/acceptEdits/default/No)
+ *  - Always Allow
+ *  - Standard allow_once/allow_always/reject_once
+ */
+import type {
+  AgentSideConnection,
+  PermissionOption,
+  ToolCallUpdate,
+  ClientCapabilities,
+} from '@agentclientprotocol/sdk'
+import type { CanUseToolFn } from '../../hooks/useCanUseTool.js'
+import type {
+  PermissionAllowDecision,
+  PermissionAskDecision,
+  PermissionDenyDecision,
+} from '../../types/permissions.js'
+import type { Tool as ToolType, ToolUseContext } from '../../Tool.js'
+import type { AssistantMessage } from '../../types/message.js'
+import { toolInfoFromToolUse } from './bridge.js'
+
+const IS_ROOT =
+  typeof process.geteuid === 'function'
+    ? process.geteuid() === 0
+    : typeof process.getuid === 'function'
+      ? process.getuid() === 0
+      : false
+const ALLOW_BYPASS = !IS_ROOT || !!process.env.IS_SANDBOX
+
+/**
+ * Creates a CanUseToolFn that delegates permission decisions to the
+ * ACP client via requestPermission().
+ */
+export function createAcpCanUseTool(
+  conn: AgentSideConnection,
+  sessionId: string,
+  getCurrentMode: () => string,
+  clientCapabilities?: ClientCapabilities,
+  cwd?: string,
+): CanUseToolFn {
+  return async (
+    tool: ToolType,
+    input: Record<string, unknown>,
+    _context: ToolUseContext,
+    _assistantMessage: AssistantMessage,
+    toolUseID: string,
+    _forceDecision?: PermissionAllowDecision | PermissionAskDecision | PermissionDenyDecision,
+  ): Promise<PermissionAllowDecision | PermissionAskDecision | PermissionDenyDecision> => {
+    const supportsTerminalOutput = checkTerminalOutput(clientCapabilities)
+
+    // ── ExitPlanMode special handling ────────────────────────────
+    if (tool.name === 'ExitPlanMode') {
+      return handleExitPlanMode(conn, sessionId, toolUseID, input, supportsTerminalOutput, cwd)
+    }
+
+    // ── bypassPermissions mode ───────────────────────────────────
+    if (getCurrentMode() === 'bypassPermissions') {
+      return {
+        behavior: 'allow',
+        updatedInput: input,
+      }
+    }
+
+    // ── Standard tool permission ─────────────────────────────────
+    const info = toolInfoFromToolUse(
+      { name: tool.name, id: toolUseID, input },
+      supportsTerminalOutput,
+      cwd,
+    )
+
+    const toolCall: ToolCallUpdate = {
+      toolCallId: toolUseID,
+      title: info.title,
+      kind: info.kind,
+      status: 'pending',
+      rawInput: input,
+    }
+
+    const options: Array<PermissionOption> = [
+      { kind: 'allow_always', name: 'Always Allow', optionId: 'allow_always' },
+      { kind: 'allow_once', name: 'Allow', optionId: 'allow' },
+      { kind: 'reject_once', name: 'Reject', optionId: 'reject' },
+    ]
+
+    try {
+      const response = await conn.requestPermission({
+        sessionId,
+        toolCall,
+        options,
+      })
+
+      if (response.outcome.outcome === 'cancelled') {
+        return {
+          behavior: 'deny',
+          message: 'Permission request cancelled by client',
+          decisionReason: { type: 'mode', mode: 'default' },
+        }
+      }
+
+      if (
+        response.outcome.outcome === 'selected' &&
+        'optionId' in response.outcome &&
+        response.outcome.optionId !== undefined
+      ) {
+        const optionId = response.outcome.optionId
+        if (optionId === 'allow' || optionId === 'allow_always') {
+          return {
+            behavior: 'allow',
+            updatedInput: input,
+          }
+        }
+      }
+
+      // Default: deny
+      return {
+        behavior: 'deny',
+        message: 'Permission denied by client',
+        decisionReason: { type: 'mode', mode: 'default' },
+      }
+    } catch {
+      return {
+        behavior: 'deny',
+        message: 'Permission request failed',
+        decisionReason: { type: 'mode', mode: 'default' },
+      }
+    }
+  }
+}
+
+async function handleExitPlanMode(
+  conn: AgentSideConnection,
+  sessionId: string,
+  toolUseID: string,
+  input: Record<string, unknown>,
+  supportsTerminalOutput: boolean,
+  cwd?: string,
+): Promise<PermissionAllowDecision | PermissionDenyDecision> {
+  const options: Array<PermissionOption> = [
+    { kind: 'allow_always', name: 'Yes, and use "auto" mode', optionId: 'auto' },
+    { kind: 'allow_always', name: 'Yes, and auto-accept edits', optionId: 'acceptEdits' },
+    { kind: 'allow_once', name: 'Yes, and manually approve edits', optionId: 'default' },
+    { kind: 'reject_once', name: 'No, keep planning', optionId: 'plan' },
+  ]
+  if (ALLOW_BYPASS) {
+    options.unshift({
+      kind: 'allow_always',
+      name: 'Yes, and bypass permissions',
+      optionId: 'bypassPermissions',
+    })
+  }
+
+  const info = toolInfoFromToolUse(
+    { name: 'ExitPlanMode', id: toolUseID, input },
+    supportsTerminalOutput,
+    cwd,
+  )
+
+  const toolCall: ToolCallUpdate = {
+    toolCallId: toolUseID,
+    title: info.title,
+    kind: info.kind,
+    status: 'pending',
+    rawInput: input,
+  }
+
+  const response = await conn.requestPermission({
+    sessionId,
+    toolCall,
+    options,
+  })
+
+  if (response.outcome.outcome === 'cancelled') {
+    return {
+      behavior: 'deny',
+      message: 'Tool use aborted',
+      decisionReason: { type: 'mode', mode: 'default' },
+    }
+  }
+
+  if (
+    response.outcome.outcome === 'selected' &&
+    'optionId' in response.outcome &&
+    response.outcome.optionId !== undefined
+  ) {
+    const selectedOption = response.outcome.optionId
+    if (
+      selectedOption === 'default' ||
+      selectedOption === 'acceptEdits' ||
+      selectedOption === 'auto' ||
+      selectedOption === 'bypassPermissions'
+    ) {
+      await conn.sessionUpdate({
+        sessionId,
+        update: {
+          sessionUpdate: 'current_mode_update',
+          currentModeId: selectedOption,
+        },
+      })
+
+      return {
+        behavior: 'allow',
+        updatedInput: input,
+      }
+    }
+  }
+
+  return {
+    behavior: 'deny',
+    message: 'User rejected request to exit plan mode.',
+    decisionReason: { type: 'mode', mode: 'plan' },
+  }
+}
+
+function checkTerminalOutput(clientCapabilities?: ClientCapabilities): boolean {
+  if (!clientCapabilities) return false
+  const meta = (clientCapabilities as unknown as Record<string, unknown>)._meta
+  if (!meta || typeof meta !== 'object') return false
+  return (meta as Record<string, unknown>)['terminal_output'] === true
+}
diff --git a/src/services/acp/utils.ts b/src/services/acp/utils.ts
new file mode 100644
index 000000000..c7bbb1e24
--- /dev/null
+++ b/src/services/acp/utils.ts
@@ -0,0 +1,208 @@
+/**
+ * Shared utilities for the ACP service.
+ * Ported from claude-agent-acp-main/src/utils.ts and acp-agent.ts helpers.
+ */
+import { Readable, Writable } from 'node:stream'
+import type { PermissionMode } from '../../entrypoints/sdk/coreTypes.generated.js'
+
+// ── Pushable ──────────────────────────────────────────────────────
+
+/**
+ * A pushable async iterable: allows you to push items and consume them
+ * with for-await. Useful for bridging push-based and async-iterator-based code.
+ */
+export class Pushable<T> implements AsyncIterable<T> {
+  private queue: T[] = []
+  private resolvers: ((value: IteratorResult<T>) => void)[] = []
+  private done = false
+
+  push(item: T) {
+    if (this.resolvers.length > 0) {
+      const resolve = this.resolvers.shift()!
+      resolve({ value: item, done: false })
+    } else {
+      this.queue.push(item)
+    }
+  }
+
+  end() {
+    this.done = true
+    while (this.resolvers.length > 0) {
+      const resolve = this.resolvers.shift()!
+      resolve({ value: undefined as unknown as T, done: true })
+    }
+  }
+
+  [Symbol.asyncIterator](): AsyncIterator<T> {
+    return {
+      next: (): Promise<IteratorResult<T>> => {
+        if (this.queue.length > 0) {
+          const value = this.queue.shift()!
+          return Promise.resolve({ value, done: false })
+        }
+        if (this.done) {
+          return Promise.resolve({ value: undefined as unknown as T, done: true })
+        }
+        return new Promise<IteratorResult<T>>((resolve) => {
+          this.resolvers.push(resolve)
+        })
+      },
+    }
+  }
+}
+
+// ── Stream helpers ────────────────────────────────────────────────
+
+export function nodeToWebWritable(nodeStream: Writable): WritableStream<Uint8Array> {
+  return new WritableStream<Uint8Array>({
+    write(chunk) {
+      return new Promise<void>((resolve, reject) => {
+        nodeStream.write(Buffer.from(chunk), (err) => {
+          if (err) reject(err)
+          else resolve()
+        })
+      })
+    },
+  })
+}
+
+export function nodeToWebReadable(nodeStream: Readable): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      nodeStream.on('data', (chunk: Buffer) => {
+        controller.enqueue(new Uint8Array(chunk))
+      })
+      nodeStream.on('end', () => controller.close())
+      nodeStream.on('error', (err) => controller.error(err))
+    },
+  })
+}
+
+// ── unreachable ───────────────────────────────────────────────────
+
+export function unreachable(
+  value: never,
+  logger: { error: (...args: unknown[]) => void } = console,
+): void {
+  let valueAsString: unknown
+  try {
+    valueAsString = JSON.stringify(value)
+  } catch {
+    valueAsString = value
+  }
+  logger.error(`Unexpected case: ${valueAsString}`)
+}
+
+// ── Permission mode resolution ────────────────────────────────────
+
+// Bypass Permissions doesn't work if we are a root/sudo user
+const IS_ROOT =
+  typeof process.geteuid === 'function'
+    ? process.geteuid() === 0
+    : typeof process.getuid === 'function'
+      ? process.getuid() === 0
+      : false
+const ALLOW_BYPASS = !IS_ROOT || !!process.env.IS_SANDBOX
+
+const PERMISSION_MODE_ALIASES: Record<string, PermissionMode> = {
+  auto: 'auto',
+  default: 'default',
+  acceptedits: 'acceptEdits',
+  dontask: 'dontAsk',
+  plan: 'plan',
+  bypasspermissions: 'bypassPermissions',
+  bypass: 'bypassPermissions',
+}
+
+export function resolvePermissionMode(defaultMode?: unknown): PermissionMode {
+  if (defaultMode === undefined) {
+    return 'default'
+  }
+
+  if (typeof defaultMode !== 'string') {
+    throw new Error('Invalid permissions.defaultMode: expected a string.')
+  }
+
+  const normalized = defaultMode.trim().toLowerCase()
+  if (normalized === '') {
+    throw new Error('Invalid permissions.defaultMode: expected a non-empty string.')
+  }
+
+  const mapped = PERMISSION_MODE_ALIASES[normalized]
+  if (!mapped) {
+    throw new Error(`Invalid permissions.defaultMode: ${defaultMode}.`)
+  }
+
+  if (mapped === 'bypassPermissions' && !ALLOW_BYPASS) {
+    throw new Error(
+      'Invalid permissions.defaultMode: bypassPermissions is not available when running as root.',
+    )
+  }
+
+  return mapped
+}
+
+// ── Session fingerprint ───────────────────────────────────────────
+
+/**
+ * Compute a stable fingerprint of the session-defining params so we can
+ * detect when a loadSession/resumeSession call requires tearing down and
+ * recreating the underlying QueryEngine.
+ */
+export function computeSessionFingerprint(params: {
+  cwd: string
+  mcpServers?: Array<{ name: string; [key: string]: unknown }>
+}): string {
+  const servers = [...(params.mcpServers ?? [])].sort((a, b) =>
+    a.name.localeCompare(b.name),
+  )
+  return JSON.stringify({ cwd: params.cwd, mcpServers: servers })
+}
+
+// ── Title sanitization ────────────────────────────────────────────
+
+const MAX_TITLE_LENGTH = 256
+
+export function sanitizeTitle(text: string): string {
+  const sanitized = text
+    .replace(/[\r\n]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+  if (sanitized.length <= MAX_TITLE_LENGTH) {
+    return sanitized
+  }
+  return sanitized.slice(0, MAX_TITLE_LENGTH - 1) + '…'
+}
+
+// ── Path display helpers ──────────────────────────────────────────
+
+import * as path from 'node:path'
+
+/**
+ * Convert an absolute file path to a project-relative path for display.
+ * Returns the original path if it's outside the project directory or if no cwd is provided.
+ */
+export function toDisplayPath(filePath: string, cwd?: string): string {
+  if (!cwd) return filePath
+  const resolvedCwd = path.resolve(cwd)
+  const resolvedFile = path.resolve(filePath)
+  if (
+    resolvedFile.startsWith(resolvedCwd + path.sep) ||
+    resolvedFile === resolvedCwd
+  ) {
+    return path.relative(resolvedCwd, resolvedFile)
+  }
+  return filePath
+}
+
+// ── Markdown helpers ──────────────────────────────────────────────
+
+export function markdownEscape(text: string): string {
+  let escape = '```'
+  for (const m of text.matchAll(/^```+/gm) ?? []) {
+    while (m[0].length >= escape.length) {
+      escape += '`'
+    }
+  }
+  return escape + '\n' + text + (text.endsWith('\n') ? '' : '\n') + escape
+}
diff --git a/src/services/analytics/growthbook.ts b/src/services/analytics/growthbook.ts
index c6c1fac10..5e35514ea 100644
--- a/src/services/analytics/growthbook.ts
+++ b/src/services/analytics/growthbook.ts
@@ -466,6 +466,7 @@ const LOCAL_GATE_DEFAULTS: Record<string, unknown> = {
   tengu_birch_trellis: true, // Tree-sitter bash security analysis
   tengu_collage_kaleidoscope: true, // macOS clipboard image reading
   tengu_compact_cache_prefix: true, // Reuse prompt cache during compaction
+  tengu_kairos_assistant: true, // KAIROS assistant mode activation
   tengu_kairos_cron_durable: true, // Persistent cron tasks
   tengu_attribution_header: true, // API request attribution header
   tengu_slate_prism: true, // Agent progress summaries
@@ -830,6 +831,16 @@ export function getFeatureValue_CACHED_MAY_BE_STALE<T>(
     return localDefault !== undefined ? (localDefault as T) : defaultValue
   }
 
+  // LOCAL_GATE_DEFAULTS take priority over remote values and disk cache.
+  // In fork/self-hosted deployments, the GrowthBook server may push false
+  // for gates we intentionally enable. Local defaults represent the
+  // project's intentional configuration and override everything except
+  // env/config overrides (which are explicit user intent).
+  const localDefault = getLocalGateDefault(feature)
+  if (localDefault !== undefined) {
+    return localDefault as T
+  }
+
   // Log experiment exposure if data is available, otherwise defer until after init
   if (experimentDataByFeature.has(feature)) {
     logExposureForFeature(feature)
@@ -838,10 +849,6 @@ export function getFeatureValue_CACHED_MAY_BE_STALE<T>(
   }
 
   // In-memory payload is authoritative once processRemoteEvalPayload has run.
-  // Disk is also fresh by then (syncRemoteEvalToDisk runs synchronously inside
-  // init), so this is correctness-equivalent to the disk read below — but it
-  // skips the config JSON parse and is what onGrowthBookRefresh subscribers
-  // depend on to read fresh values the instant they're notified.
   if (remoteEvalFeatureValues.has(feature)) {
     return remoteEvalFeatureValues.get(feature) as T
   }
@@ -853,14 +860,9 @@ export function getFeatureValue_CACHED_MAY_BE_STALE<T>(
       return cached as T
     }
   } catch {
-    // Config not yet initialized — fall through to local gate defaults
+    // Config not yet initialized — fall through to defaultValue
   }
-  // Disk cache miss (or config not initialized) — use local gate defaults
-  // before falling back to the caller's defaultValue. This covers:
-  // 1. GrowthBook "enabled" but never connected (caches empty)
-  // 2. Config not yet initialized (early in startup)
-  const localDefault = getLocalGateDefault(feature)
-  return localDefault !== undefined ? (localDefault as T) : defaultValue
+  return defaultValue
 }
 
 /**
diff --git a/src/services/api/openai/__tests__/queryModelOpenAI.isolated.ts b/src/services/api/openai/__tests__/queryModelOpenAI.isolated.ts
new file mode 100644
index 000000000..9af151c56
--- /dev/null
+++ b/src/services/api/openai/__tests__/queryModelOpenAI.isolated.ts
@@ -0,0 +1,487 @@
+/**
+ * Tests for queryModelOpenAI in index.ts.
+ *
+ * Focused on the two bugs fixed:
+ *  1. stop_reason was always null in the assembled AssistantMessage because
+ *     partialMessage (from message_start) has stop_reason: null, and the
+ *     stop_reason captured from message_delta was never applied.
+ *  2. partialMessage was not reset to null after message_stop, so the safety
+ *     fallback at the end of the loop would yield a second identical
+ *     AssistantMessage (causing doubled content in the next API request).
+ *
+ * Strategy: mock getOpenAIClient + adaptOpenAIStreamToAnthropic so we can
+ * feed pre-built Anthropic events directly into queryModelOpenAI and inspect
+ * what it emits — without any real HTTP calls.
+ */
+import { describe, expect, test, mock, beforeEach, afterEach } from 'bun:test'
+import type { BetaRawMessageStreamEvent } from '@anthropic-ai/sdk/resources/beta/messages/messages.mjs'
+import type { AssistantMessage, StreamEvent } from '../../../../types/message.js'
+
+// ─── helpers ─────────────────────────────────────────────────────────────────
+
+/** Build a minimal message_start event */
+function makeMessageStart(overrides: Record<string, any> = {}): BetaRawMessageStreamEvent {
+  return {
+    type: 'message_start',
+    message: {
+      id: 'msg_test',
+      type: 'message',
+      role: 'assistant',
+      content: [],
+      model: 'test-model',
+      stop_reason: null,
+      stop_sequence: null,
+      usage: { input_tokens: 0, output_tokens: 0, cache_creation_input_tokens: 0, cache_read_input_tokens: 0 },
+      ...overrides,
+    },
+  } as any
+}
+
+/** Build a content_block_start event for the given block type */
+function makeContentBlockStart(index: number, type: 'text' | 'tool_use' | 'thinking', extra: Record<string, any> = {}): BetaRawMessageStreamEvent {
+  const block =
+    type === 'text'
+      ? { type: 'text', text: '' }
+      : type === 'tool_use'
+        ? { type: 'tool_use', id: 'toolu_test', name: 'bash', input: {} }
+        : { type: 'thinking', thinking: '', signature: '' }
+  return { type: 'content_block_start', index, content_block: { ...block, ...extra } } as any
+}
+
+/** Build a text_delta content_block_delta event */
+function makeTextDelta(index: number, text: string): BetaRawMessageStreamEvent {
+  return { type: 'content_block_delta', index, delta: { type: 'text_delta', text } } as any
+}
+
+/** Build an input_json_delta content_block_delta event */
+function makeInputJsonDelta(index: number, json: string): BetaRawMessageStreamEvent {
+  return { type: 'content_block_delta', index, delta: { type: 'input_json_delta', partial_json: json } } as any
+}
+
+/** Build a thinking_delta content_block_delta event */
+function makeThinkingDelta(index: number, thinking: string): BetaRawMessageStreamEvent {
+  return { type: 'content_block_delta', index, delta: { type: 'thinking_delta', thinking } } as any
+}
+
+/** Build a content_block_stop event */
+function makeContentBlockStop(index: number): BetaRawMessageStreamEvent {
+  return { type: 'content_block_stop', index } as any
+}
+
+/** Build a message_delta event with stop_reason and output_tokens */
+function makeMessageDelta(stopReason: string, outputTokens: number): BetaRawMessageStreamEvent {
+  return {
+    type: 'message_delta',
+    delta: { stop_reason: stopReason, stop_sequence: null },
+    usage: { output_tokens: outputTokens },
+  } as any
+}
+
+/** Build a message_stop event */
+function makeMessageStop(): BetaRawMessageStreamEvent {
+  return { type: 'message_stop' } as any
+}
+
+/** Async generator from a fixed array of events */
+async function* eventStream(events: BetaRawMessageStreamEvent[]) {
+  for (const e of events) yield e
+}
+
+/** Collect all outputs from queryModelOpenAI into typed buckets */
+async function runQueryModel(
+  events: BetaRawMessageStreamEvent[],
+  envOverrides: Record<string, string | undefined> = {},
+) {
+  // Wire events into the mocked stream adapter
+  _nextEvents = events
+  // Save + apply env overrides
+  const saved: Record<string, string | undefined> = {}
+  for (const [k, v] of Object.entries(envOverrides)) {
+    saved[k] = process.env[k]
+    if (v === undefined) delete process.env[k]
+    else process.env[k] = v
+  }
+
+  try {
+    // We inline mock.module inside the try block.
+    // Bun resolves mock.module at the call site synchronously (hoisted),
+    // so we register once per test file, then re-import each time.
+    const { queryModelOpenAI } = await import('../index.js')
+
+    const assistantMessages: AssistantMessage[] = []
+    const streamEvents: StreamEvent[] = []
+    const otherOutputs: any[] = []
+
+    const minimalOptions: any = {
+      model: 'test-model',
+      tools: [],
+      agents: [],
+      querySource: 'main_loop',
+      getToolPermissionContext: async () => ({
+        alwaysAllow: [],
+        alwaysDeny: [],
+        needsPermission: [],
+        mode: 'default',
+        isBypassingPermissions: false,
+      }),
+    }
+
+    for await (const item of queryModelOpenAI(
+      [],
+      { type: 'text', text: '' } as any,
+      [],
+      new AbortController().signal,
+      minimalOptions,
+    )) {
+      if (item.type === 'assistant') {
+        assistantMessages.push(item as AssistantMessage)
+      } else if (item.type === 'stream_event') {
+        streamEvents.push(item as StreamEvent)
+      } else {
+        otherOutputs.push(item)
+      }
+    }
+
+    return { assistantMessages, streamEvents, otherOutputs }
+  } finally {
+    // Restore env
+    for (const [k, v] of Object.entries(saved)) {
+      if (v === undefined) delete process.env[k]
+      else process.env[k] = v
+    }
+  }
+}
+
+// ─── mock setup ──────────────────────────────────────────────────────────────
+
+// We mock at module level. Bun's mock.module replaces the module for the
+// entire file, so we configure the stream per-test via a shared variable.
+let _nextEvents: BetaRawMessageStreamEvent[] = []
+
+/** Captured arguments from the last chat.completions.create() call */
+let _lastCreateArgs: Record<string, any> | null = null
+
+mock.module('../client.js', () => ({
+  getOpenAIClient: () => ({
+    chat: {
+      completions: {
+        create: async (args: Record<string, any>) => {
+          _lastCreateArgs = args
+          return { [Symbol.asyncIterator]: async function* () {} }
+        },
+      },
+    },
+  }),
+}))
+
+mock.module('../streamAdapter.js', () => ({
+  adaptOpenAIStreamToAnthropic: (_stream: any, _model: string) => eventStream(_nextEvents),
+}))
+
+mock.module('../modelMapping.js', () => ({
+  resolveOpenAIModel: (m: string) => m,
+}))
+
+mock.module('../convertMessages.js', () => ({
+  anthropicMessagesToOpenAI: () => [],
+}))
+
+mock.module('../convertTools.js', () => ({
+  anthropicToolsToOpenAI: () => [],
+  anthropicToolChoiceToOpenAI: () => undefined,
+}))
+
+mock.module('../../../../utils/context.js', () => ({
+  MODEL_CONTEXT_WINDOW_DEFAULT: 200_000,
+  COMPACT_MAX_OUTPUT_TOKENS: 20_000,
+  CAPPED_DEFAULT_MAX_TOKENS: 8_000,
+  ESCALATED_MAX_TOKENS: 64_000,
+  is1mContextDisabled: () => false,
+  has1mContext: () => false,
+  modelSupports1M: () => false,
+  getModelMaxOutputTokens: () => ({ upperLimit: 8192, default: 8192 }),
+  getContextWindowForModel: () => 200_000,
+  getSonnet1mExpTreatmentEnabled: () => false,
+  calculateContextPercentages: () => ({ usedPercent: 0, remainingPercent: 100 }),
+  getMaxThinkingTokensForModel: () => 0,
+}))
+
+mock.module('../../../../utils/messages.js', () => ({
+  normalizeMessagesForAPI: (msgs: any) => msgs,
+  normalizeContentFromAPI: (blocks: any[]) => blocks,
+  createAssistantAPIErrorMessage: (opts: any) => ({
+    type: 'assistant',
+    message: { content: [{ type: 'text', text: opts.content }], apiError: opts.apiError },
+    uuid: 'error-uuid',
+    timestamp: new Date().toISOString(),
+  }),
+}))
+
+mock.module('../../../../utils/api.js', () => ({
+  toolToAPISchema: async (t: any) => t,
+}))
+
+mock.module('../../../../utils/toolSearch.js', () => ({
+  isToolSearchEnabled: async () => false,
+  extractDiscoveredToolNames: () => new Set(),
+}))
+
+mock.module('../../../../tools/ToolSearchTool/prompt.js', () => ({
+  isDeferredTool: () => false,
+  TOOL_SEARCH_TOOL_NAME: '__tool_search__',
+}))
+
+mock.module('../../../../cost-tracker.js', () => ({
+  addToTotalSessionCost: () => {},
+}))
+
+mock.module('../../../../utils/modelCost.js', () => ({
+  COST_TIER_3_15: {},
+  COST_TIER_15_75: {},
+  COST_TIER_5_25: {},
+  COST_TIER_30_150: {},
+  COST_HAIKU_35: {},
+  COST_HAIKU_45: {},
+  getOpus46CostTier: () => ({}),
+  MODEL_COSTS: {},
+  getModelCosts: () => ({}),
+  calculateUSDCost: () => 0,
+  calculateCostFromTokens: () => 0,
+  formatModelPricing: () => '',
+  getModelPricingString: () => undefined,
+}))
+
+mock.module('../../../../utils/debug.js', () => ({
+  logForDebugging: () => {},
+  logAntError: () => {},
+  isDebugMode: () => false,
+  isDebugToStdErr: () => false,
+  getDebugFilePath: () => null,
+  getDebugLogPath: () => '',
+  getDebugFilter: () => null,
+  getMinDebugLogLevel: () => 'debug',
+  enableDebugLogging: () => false,
+  setHasFormattedOutput: () => {},
+  getHasFormattedOutput: () => false,
+  flushDebugLogs: async () => {},
+}))
+
+// ─── tests ───────────────────────────────────────────────────────────────────
+
+describe('queryModelOpenAI — stop_reason propagation', () => {
+  test('assembled AssistantMessage has stop_reason end_turn (not null)', async () => {
+    _nextEvents = [
+      makeMessageStart(),
+      makeContentBlockStart(0, 'text'),
+      makeTextDelta(0, 'Hello'),
+      makeContentBlockStop(0),
+      makeMessageDelta('end_turn', 10),
+      makeMessageStop(),
+    ]
+
+    const { assistantMessages } = await runQueryModel(_nextEvents)
+
+    expect(assistantMessages).toHaveLength(1)
+    expect(assistantMessages[0]!.message.stop_reason).toBe('end_turn')
+  })
+
+  test('assembled AssistantMessage has stop_reason tool_use', async () => {
+    _nextEvents = [
+      makeMessageStart(),
+      makeContentBlockStart(0, 'tool_use'),
+      makeInputJsonDelta(0, '{"cmd":"ls"}'),
+      makeContentBlockStop(0),
+      makeMessageDelta('tool_use', 20),
+      makeMessageStop(),
+    ]
+
+    const { assistantMessages } = await runQueryModel(_nextEvents)
+
+    expect(assistantMessages).toHaveLength(1)
+    expect(assistantMessages[0]!.message.stop_reason).toBe('tool_use')
+  })
+
+  test('assembled AssistantMessage has stop_reason max_tokens', async () => {
+    _nextEvents = [
+      makeMessageStart(),
+      makeContentBlockStart(0, 'text'),
+      makeTextDelta(0, 'truncated'),
+      makeContentBlockStop(0),
+      makeMessageDelta('max_tokens', 8192),
+      makeMessageStop(),
+    ]
+
+    const { assistantMessages } = await runQueryModel(_nextEvents)
+
+    // Two assistant-typed items: the content message + the max_output_tokens error signal.
+    // The error signal is emitted as a synthetic assistant message by createAssistantAPIErrorMessage.
+    expect(assistantMessages).toHaveLength(2)
+    const contentMsg = assistantMessages[0]!
+    expect(contentMsg.message.stop_reason).toBe('max_tokens')
+    // Second item is the error signal (has apiError set)
+    const errorMsg = assistantMessages[1]!.message as any
+    expect(errorMsg.apiError).toBe('max_output_tokens')
+  })
+
+  test('stop_reason is null when no message_delta was received (safety fallback path)', async () => {
+    // Stream ends without message_stop — triggers the safety fallback branch.
+    // stop_reason stays null since no message_delta was ever seen.
+    _nextEvents = [
+      makeMessageStart(),
+      makeContentBlockStart(0, 'text'),
+      makeTextDelta(0, 'partial'),
+      makeContentBlockStop(0),
+      // No message_delta / message_stop
+    ]
+
+    const { assistantMessages } = await runQueryModel(_nextEvents)
+
+    // Safety fallback should yield the partial content
+    expect(assistantMessages).toHaveLength(1)
+    expect(assistantMessages[0]!.message.stop_reason).toBeNull()
+  })
+})
+
+describe('queryModelOpenAI — usage accumulation', () => {
+  test('usage in assembled message reflects all four fields from message_delta', async () => {
+    // message_start has all fields=0 (trailing-chunk pattern: usage not yet available).
+    // message_delta carries the real values after stream ends.
+    // The spread in the message_delta handler must override all zeros from message_start,
+    // including cache_read_input_tokens which was previously missing from message_delta.
+    _nextEvents = [
+      makeMessageStart({ usage: { input_tokens: 0, output_tokens: 0, cache_creation_input_tokens: 0, cache_read_input_tokens: 0 } }),
+      makeContentBlockStart(0, 'text'),
+      makeTextDelta(0, 'response'),
+      makeContentBlockStop(0),
+      // message_delta carries all four Anthropic usage fields (as emitted by the fixed streamAdapter)
+      {
+        type: 'message_delta',
+        delta: { stop_reason: 'end_turn', stop_sequence: null },
+        usage: { input_tokens: 30011, output_tokens: 190, cache_read_input_tokens: 19904, cache_creation_input_tokens: 0 },
+      } as any,
+      makeMessageStop(),
+    ]
+
+    const { assistantMessages } = await runQueryModel(_nextEvents)
+
+    expect(assistantMessages).toHaveLength(1)
+    const usage = assistantMessages[0]!.message.usage as any
+    expect(usage.input_tokens).toBe(30011)
+    expect(usage.output_tokens).toBe(190)
+    // cache_read_input_tokens from message_delta overrides the 0 from message_start
+    expect(usage.cache_read_input_tokens).toBe(19904)
+    expect(usage.cache_creation_input_tokens).toBe(0)
+  })
+
+  test('usage is zero when no usage events arrive (prevents false autocompact)', async () => {
+    // If usage stays 0, tokenCountWithEstimation will undercount — so at least
+    // verify the field exists and is numeric (to detect regressions).
+    _nextEvents = [
+      makeMessageStart(),
+      makeContentBlockStart(0, 'text'),
+      makeTextDelta(0, 'hi'),
+      makeContentBlockStop(0),
+      makeMessageDelta('end_turn', 0),
+      makeMessageStop(),
+    ]
+
+    const { assistantMessages } = await runQueryModel(_nextEvents)
+
+    const usage = assistantMessages[0]!.message.usage as any
+    expect(typeof usage.input_tokens).toBe('number')
+    expect(typeof usage.output_tokens).toBe('number')
+  })
+})
+
+describe('queryModelOpenAI — no duplicate AssistantMessage (partialMessage reset)', () => {
+  test('yields exactly one AssistantMessage per message_stop when content is present', async () => {
+    _nextEvents = [
+      makeMessageStart(),
+      makeContentBlockStart(0, 'text'),
+      makeTextDelta(0, 'only once'),
+      makeContentBlockStop(0),
+      makeMessageDelta('end_turn', 5),
+      makeMessageStop(),
+    ]
+
+    const { assistantMessages } = await runQueryModel(_nextEvents)
+
+    // Before the fix, partialMessage was not reset to null, so the safety
+    // fallback at the end of the loop would yield a second message with the
+    // same message.id — causing mergeAssistantMessages to concatenate content.
+    expect(assistantMessages).toHaveLength(1)
+  })
+
+  test('thinking + text response yields exactly one AssistantMessage', async () => {
+    _nextEvents = [
+      makeMessageStart(),
+      makeContentBlockStart(0, 'thinking'),
+      makeThinkingDelta(0, 'let me think'),
+      makeContentBlockStop(0),
+      makeContentBlockStart(1, 'text'),
+      makeTextDelta(1, 'answer'),
+      makeContentBlockStop(1),
+      makeMessageDelta('end_turn', 30),
+      makeMessageStop(),
+    ]
+
+    const { assistantMessages } = await runQueryModel(_nextEvents)
+
+    expect(assistantMessages).toHaveLength(1)
+  })
+
+  test('safety fallback path still yields message when stream ends without message_stop', async () => {
+    // Simulates a stream that cuts off without the normal termination sequence.
+    _nextEvents = [
+      makeMessageStart(),
+      makeContentBlockStart(0, 'text'),
+      makeTextDelta(0, 'abrupt end'),
+      // No content_block_stop, no message_delta, no message_stop
+    ]
+
+    const { assistantMessages } = await runQueryModel(_nextEvents)
+
+    expect(assistantMessages).toHaveLength(1)
+  })
+})
+
+describe('queryModelOpenAI — stream_events forwarded', () => {
+  test('every adapted event is also yielded as stream_event for real-time display', async () => {
+    _nextEvents = [
+      makeMessageStart(),
+      makeContentBlockStart(0, 'text'),
+      makeTextDelta(0, 'hello'),
+      makeContentBlockStop(0),
+      makeMessageDelta('end_turn', 5),
+      makeMessageStop(),
+    ]
+
+    const { streamEvents } = await runQueryModel(_nextEvents)
+
+    const eventTypes = streamEvents.map(e => (e as any).event?.type)
+    expect(eventTypes).toContain('message_start')
+    expect(eventTypes).toContain('content_block_start')
+    expect(eventTypes).toContain('content_block_delta')
+    expect(eventTypes).toContain('content_block_stop')
+    expect(eventTypes).toContain('message_delta')
+    expect(eventTypes).toContain('message_stop')
+  })
+})
+
+describe('queryModelOpenAI — max_tokens forwarded to request', () => {
+  test('buildOpenAIRequestBody includes max_tokens in the request payload', async () => {
+    _nextEvents = [
+      makeMessageStart(),
+      makeContentBlockStart(0, 'text'),
+      makeTextDelta(0, 'hi'),
+      makeContentBlockStop(0),
+      makeMessageDelta('end_turn', 5),
+      makeMessageStop(),
+    ]
+
+    await runQueryModel(_nextEvents)
+
+    expect(_lastCreateArgs).not.toBeNull()
+    expect(_lastCreateArgs!.max_tokens).toBe(8192)
+  })
+})
diff --git a/src/services/api/openai/__tests__/streamAdapter.test.ts b/src/services/api/openai/__tests__/streamAdapter.test.ts
index 0d3f5ead4..db6b3015c 100644
--- a/src/services/api/openai/__tests__/streamAdapter.test.ts
+++ b/src/services/api/openai/__tests__/streamAdapter.test.ts
@@ -1,6 +1,21 @@
 import { describe, expect, test } from 'bun:test'
-import { adaptOpenAIStreamToAnthropic } from '../streamAdapter.js'
 import type { ChatCompletionChunk } from 'openai/resources/chat/completions/completions.mjs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { readFileSync, writeFileSync, mkdirSync } from 'fs'
+import { tmpdir } from 'os'
+
+// Guard against mock pollution from queryModelOpenAI.test.ts which replaces
+// ../streamAdapter.js process-wide via mock.module (bun has no un-mock API).
+// We copy the source to a unique temp path so the import bypasses bun's
+// module mock cache completely.
+const _testDir = dirname(fileURLToPath(import.meta.url))
+const _realSource = readFileSync(join(_testDir, '..', 'streamAdapter.ts'), 'utf-8')
+const _tempDir = join(tmpdir(), `stream-adapter-test-${Date.now()}`)
+mkdirSync(_tempDir, { recursive: true })
+const _tempFile = join(_tempDir, 'streamAdapter.ts')
+writeFileSync(_tempFile, _realSource, 'utf-8')
+const { adaptOpenAIStreamToAnthropic } = await import(_tempFile)
 
 /** Helper to create a mock async iterable from chunk array */
 function mockStream(chunks: ChatCompletionChunk[]): AsyncIterable<ChatCompletionChunk> {
@@ -31,6 +46,11 @@ function makeChunk(overrides: Partial<ChatCompletionChunk> & any = {}): ChatComp
 
 /** Collect all emitted Anthropic events from the stream adapter for assertion */
 async function collectEvents(chunks: ChatCompletionChunk[]) {
+  const realModuleUrl = new URL(
+    `../streamAdapter.js?real=${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    import.meta.url,
+  ).href
+  const { adaptOpenAIStreamToAnthropic } = await import(realModuleUrl)
   const events: any[] = []
   for await (const event of adaptOpenAIStreamToAnthropic(mockStream(chunks), 'gpt-4o')) {
     events.push(event)
diff --git a/src/services/awaySummary.ts b/src/services/awaySummary.ts
index 2f5eddfc3..d00f6b02d 100644
--- a/src/services/awaySummary.ts
+++ b/src/services/awaySummary.ts
@@ -8,6 +8,7 @@ import {
 } from '../utils/messages.js'
 import { getSmallFastModel } from '../utils/model/model.js'
 import { asSystemPrompt } from '../utils/systemPromptType.js'
+import { getResolvedLanguage } from '../utils/language.js'
 import { queryModelWithoutStreaming } from './api/claude.js'
 import { getSessionMemoryContent } from './SessionMemory/sessionMemoryUtils.js'
 
@@ -15,11 +16,18 @@ import { getSessionMemoryContent } from './SessionMemory/sessionMemoryUtils.js'
 // large sessions. 30 messages ≈ ~15 exchanges, plenty for "where we left off."
 const RECENT_MESSAGE_WINDOW = 30
 
+const PROMPT_EN =
+  'The user stepped away and is coming back. Write exactly 1-3 short sentences. Start by stating the high-level task — what they are building or debugging, not implementation details. Next: the concrete next step. Skip status reports and commit recaps.'
+
+const PROMPT_ZH =
+  '用户离开后回来了。用中文写 1-3 句话。先说明用户在做什么（高层目标，不是实现细节），然后说明下一步具体操作。不要写状态报告或提交总结。'
+
 function buildAwaySummaryPrompt(memory: string | null): string {
   const memoryBlock = memory
     ? `Session memory (broader context):\n${memory}\n\n`
     : ''
-  return `${memoryBlock}The user stepped away and is coming back. Write exactly 1-3 short sentences. Start by stating the high-level task — what they are building or debugging, not implementation details. Next: the concrete next step. Skip status reports and commit recaps.`
+  const prompt = getResolvedLanguage() === 'zh' ? PROMPT_ZH : PROMPT_EN
+  return `${memoryBlock}${prompt}`
 }
 
 /**
diff --git a/src/services/langfuse/__tests__/langfuse.isolated.ts b/src/services/langfuse/__tests__/langfuse.isolated.ts
new file mode 100644
index 000000000..815aaf9e4
--- /dev/null
+++ b/src/services/langfuse/__tests__/langfuse.isolated.ts
@@ -0,0 +1,702 @@
+import { mock, describe, test, expect, beforeEach } from 'bun:test'
+
+// Mock @langfuse/otel before any imports
+const mockForceFlush = mock(() => Promise.resolve())
+const mockShutdown = mock(() => Promise.resolve())
+
+mock.module('@langfuse/otel', () => ({
+  LangfuseSpanProcessor: class MockLangfuseSpanProcessor {
+    forceFlush = mockForceFlush
+    shutdown = mockShutdown
+    onStart = mock(() => {})
+    onEnd = mock(() => {})
+  },
+}))
+
+// Mock @opentelemetry/sdk-trace-base
+mock.module('@opentelemetry/sdk-trace-base', () => ({
+  BasicTracerProvider: class MockBasicTracerProvider {
+    constructor(_opts?: unknown) {}
+  },
+}))
+
+// Mock @langfuse/tracing
+const mockChildUpdate = mock(() => {})
+const mockChildEnd = mock(() => {})
+const mockRootUpdate = mock(() => {})
+const mockRootEnd = mock(() => {})
+
+// Mock LangfuseOtelSpanAttributes (re-exported from @langfuse/core)
+const mockLangfuseOtelSpanAttributes: Record<string, string> = {
+  TRACE_SESSION_ID: 'session.id',
+  TRACE_USER_ID: 'user.id',
+  OBSERVATION_TYPE: 'observation.type',
+  OBSERVATION_INPUT: 'observation.input',
+  OBSERVATION_OUTPUT: 'observation.output',
+  OBSERVATION_MODEL: 'observation.model',
+  OBSERVATION_COMPLETION_START_TIME: 'observation.completionStartTime',
+  OBSERVATION_USAGE_DETAILS: 'observation.usageDetails',
+}
+
+const mockSpanContext = {
+  traceId: 'test-trace-id',
+  spanId: 'test-span-id',
+  traceFlags: 1,
+}
+const mockSetAttribute = mock(() => {})
+
+// Child observation mock (returned by startObservation for tools/generations)
+const mockStartObservation = mock(() => ({
+  id: 'test-span-id',
+  traceId: 'test-trace-id',
+  type: 'span',
+  otelSpan: {
+    spanContext: () => mockSpanContext,
+    setAttribute: mockSetAttribute,
+  },
+  update: mockRootUpdate,
+  end: mockRootEnd,
+}))
+const mockSetLangfuseTracerProvider = mock(() => {})
+
+mock.module('@langfuse/tracing', () => ({
+  startObservation: mockStartObservation,
+  LangfuseOtelSpanAttributes: mockLangfuseOtelSpanAttributes,
+  propagateAttributes: mock((_params: unknown, fn?: () => void) => fn?.()),
+  setLangfuseTracerProvider: mockSetLangfuseTracerProvider,
+}))
+
+// Mock debug logger
+mock.module('src/utils/debug.js', () => ({
+  logForDebugging: mock(() => {}),
+  logAntError: mock(() => {}),
+  isDebugToStdErr: () => false,
+  isDebugMode: () => false,
+  getDebugLogPath: () => '/tmp/debug.log',
+}))
+
+// Mock user module to avoid heavy dependency chain (execa, config, cwd, env, etc.)
+mock.module('src/utils/user.js', () => ({
+  getCoreUserData: () => ({
+    email: 'test@example.com',
+    deviceId: 'test-device',
+  }),
+  getUserDataForLogging: () => ({}),
+}))
+
+describe('Langfuse integration', () => {
+  beforeEach(() => {
+    // Reset env
+    process.env.HOME = '/Users/testuser'
+    delete process.env.LANGFUSE_PUBLIC_KEY
+    delete process.env.LANGFUSE_SECRET_KEY
+    delete process.env.LANGFUSE_BASE_URL
+    delete process.env.LANGFUSE_USER_ID
+    mockStartObservation.mockClear()
+    mockRootUpdate.mockClear()
+    mockRootEnd.mockClear()
+    mockForceFlush.mockClear()
+    mockShutdown.mockClear()
+    mockSetAttribute.mockClear()
+  })
+
+  // ── sanitize tests ──────────────────────────────────────────────────────────
+
+  describe('sanitizeToolInput', () => {
+    test('replaces home dir in file_path', async () => {
+      const { sanitizeToolInput } = await import('../sanitize.js')
+      const home = process.env.HOME ?? '/Users/testuser'
+      const result = sanitizeToolInput('FileReadTool', {
+        file_path: `${home}/project/file.ts`,
+      }) as Record<string, string>
+      expect(result.file_path).toBe('~/project/file.ts')
+    })
+
+    test('redacts sensitive keys', async () => {
+      const { sanitizeToolInput } = await import('../sanitize.js')
+      const result = sanitizeToolInput('MCPTool', {
+        api_key: 'secret123',
+        token: 'abc',
+      }) as Record<string, string>
+      expect(result.api_key).toBe('[REDACTED]')
+      expect(result.token).toBe('[REDACTED]')
+    })
+
+    test('returns non-object input unchanged', async () => {
+      const { sanitizeToolInput } = await import('../sanitize.js')
+      expect(sanitizeToolInput('BashTool', 'raw string')).toBe('raw string')
+      expect(sanitizeToolInput('BashTool', null)).toBe(null)
+    })
+  })
+
+  describe('sanitizeToolOutput', () => {
+    test('redacts FileReadTool output', async () => {
+      const { sanitizeToolOutput } = await import('../sanitize.js')
+      const result = sanitizeToolOutput('FileReadTool', 'file content here')
+      expect(result).toBe('[file content redacted, 17 chars]')
+    })
+
+    test('redacts FileWriteTool output', async () => {
+      const { sanitizeToolOutput } = await import('../sanitize.js')
+      const result = sanitizeToolOutput('FileWriteTool', 'written content')
+      expect(result).toBe('[file content redacted, 15 chars]')
+    })
+
+    test('truncates BashTool output over 500 chars', async () => {
+      const { sanitizeToolOutput } = await import('../sanitize.js')
+      const longOutput = 'x'.repeat(600)
+      const result = sanitizeToolOutput('BashTool', longOutput)
+      expect(result).toContain('[truncated]')
+      expect(result.length).toBeLessThan(600)
+    })
+
+    test('does not truncate BashTool output under 500 chars', async () => {
+      const { sanitizeToolOutput } = await import('../sanitize.js')
+      const shortOutput = 'hello world'
+      expect(sanitizeToolOutput('BashTool', shortOutput)).toBe('hello world')
+    })
+
+    test('redacts ConfigTool output', async () => {
+      const { sanitizeToolOutput } = await import('../sanitize.js')
+      const result = sanitizeToolOutput('ConfigTool', 'config data')
+      expect(result).toBe('[ConfigTool output redacted, 11 chars]')
+    })
+
+    test('redacts MCPTool output', async () => {
+      const { sanitizeToolOutput } = await import('../sanitize.js')
+      const result = sanitizeToolOutput('MCPTool', 'mcp data')
+      expect(result).toBe('[MCPTool output redacted, 8 chars]')
+    })
+  })
+
+  describe('sanitizeGlobal', () => {
+    test('replaces home dir in strings', async () => {
+      const { sanitizeGlobal } = await import('../sanitize.js')
+      const home = process.env.HOME ?? '/Users/testuser'
+      expect(sanitizeGlobal(`path: ${home}/file`)).toBe('path: ~/file')
+    })
+
+    test('recursively sanitizes nested objects', async () => {
+      const { sanitizeGlobal } = await import('../sanitize.js')
+      const result = sanitizeGlobal({
+        nested: { api_key: 'secret', name: 'test' },
+      }) as Record<string, Record<string, string>>
+      expect(result.nested.api_key).toBe('[REDACTED]')
+      expect(result.nested.name).toBe('test')
+    })
+
+    test('returns non-string/object values unchanged', async () => {
+      const { sanitizeGlobal } = await import('../sanitize.js')
+      expect(sanitizeGlobal(42)).toBe(42)
+      expect(sanitizeGlobal(true)).toBe(true)
+    })
+  })
+
+  // ── client tests ────────────────────────────────────────────────────────────
+
+  describe('isLangfuseEnabled', () => {
+    test('returns false when keys not configured', async () => {
+      const { isLangfuseEnabled } = await import('../client.js')
+      expect(isLangfuseEnabled()).toBe(false)
+    })
+
+    test('returns true when both keys are set', async () => {
+      process.env.LANGFUSE_PUBLIC_KEY = 'pk-test'
+      process.env.LANGFUSE_SECRET_KEY = 'sk-test'
+      const { isLangfuseEnabled } = await import('../client.js')
+      expect(isLangfuseEnabled()).toBe(true)
+    })
+  })
+
+  describe('initLangfuse', () => {
+    test('returns false when keys not configured', async () => {
+      const { initLangfuse } = await import('../client.js')
+      expect(initLangfuse()).toBe(false)
+    })
+
+    test('returns true when keys are configured', async () => {
+      process.env.LANGFUSE_PUBLIC_KEY = 'pk-test'
+      process.env.LANGFUSE_SECRET_KEY = 'sk-test'
+      const { isLangfuseEnabled } = await import('../client.js')
+      expect(isLangfuseEnabled()).toBe(true)
+    })
+
+    test('is idempotent — multiple calls do not re-initialize', async () => {
+      const { initLangfuse } = await import('../client.js')
+      expect(() => {
+        initLangfuse()
+        initLangfuse()
+      }).not.toThrow()
+    })
+  })
+
+  describe('shutdownLangfuse', () => {
+    test('calls forceFlush and shutdown on processor', async () => {
+      const { shutdownLangfuse } = await import('../client.js')
+      await expect(shutdownLangfuse()).resolves.toBeUndefined()
+    })
+  })
+
+  // ── tracing tests ───────────────────────────────────────────────────────────
+
+  describe('createTrace', () => {
+    test('returns null when langfuse not enabled', async () => {
+      const { createTrace } = await import('../tracing.js')
+      const span = createTrace({
+        sessionId: 's1',
+        model: 'claude-3',
+        provider: 'firstParty',
+      })
+      expect(span).toBeNull()
+    })
+
+    test('creates root span when enabled', async () => {
+      process.env.LANGFUSE_PUBLIC_KEY = 'pk-test'
+      process.env.LANGFUSE_SECRET_KEY = 'sk-test'
+      const { createTrace } = await import('../tracing.js')
+      const span = createTrace({
+        sessionId: 's1',
+        model: 'claude-3',
+        provider: 'firstParty',
+        input: [],
+      })
+      expect(span).not.toBeNull()
+      expect(mockStartObservation).toHaveBeenCalledWith(
+        'agent-run',
+        expect.objectContaining({
+          metadata: expect.objectContaining({
+            provider: 'firstParty',
+            model: 'claude-3',
+            agentType: 'main',
+          }),
+        }),
+        { asType: 'agent' },
+      )
+      // Should set session.id attribute
+      expect(mockSetAttribute).toHaveBeenCalledWith('session.id', 's1')
+    })
+  })
+
+  describe('recordLLMObservation', () => {
+    test('no-ops when rootSpan is null', async () => {
+      const { recordLLMObservation } = await import('../tracing.js')
+      recordLLMObservation(null, {
+        model: 'm',
+        provider: 'firstParty',
+        input: [],
+        output: [],
+        usage: { input_tokens: 10, output_tokens: 5 },
+      })
+      expect(mockStartObservation).toHaveBeenCalledTimes(0)
+    })
+
+    test('records generation child observation via global startObservation', async () => {
+      process.env.LANGFUSE_PUBLIC_KEY = 'pk-test'
+      process.env.LANGFUSE_SECRET_KEY = 'sk-test'
+      const { createTrace, recordLLMObservation } = await import(
+        '../tracing.js'
+      )
+      const span = createTrace({
+        sessionId: 's1',
+        model: 'claude-3',
+        provider: 'firstParty',
+      })
+      mockStartObservation.mockClear()
+      mockRootUpdate.mockClear()
+      mockRootEnd.mockClear()
+      recordLLMObservation(span, {
+        model: 'claude-3',
+        provider: 'firstParty',
+        input: [{ role: 'user', content: 'hello' }],
+        output: [{ role: 'assistant', content: 'hi' }],
+        usage: { input_tokens: 10, output_tokens: 5 },
+      })
+      // Should call the global startObservation with asType: 'generation' and parentSpanContext
+      expect(mockStartObservation).toHaveBeenCalledWith(
+        'ChatAnthropic',
+        expect.objectContaining({
+          model: 'claude-3',
+        }),
+        expect.objectContaining({
+          asType: 'generation',
+          parentSpanContext: mockSpanContext,
+        }),
+      )
+      expect(mockRootUpdate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          usageDetails: { input: 10, output: 5 },
+        }),
+      )
+      expect(mockRootEnd).toHaveBeenCalled()
+    })
+  })
+
+  describe('recordToolObservation', () => {
+    test('no-ops when rootSpan is null', async () => {
+      const { recordToolObservation } = await import('../tracing.js')
+      recordToolObservation(null, {
+        toolName: 'BashTool',
+        toolUseId: 'id1',
+        input: {},
+        output: 'out',
+      })
+    })
+
+    test('records tool child observation via global startObservation', async () => {
+      process.env.LANGFUSE_PUBLIC_KEY = 'pk-test'
+      process.env.LANGFUSE_SECRET_KEY = 'sk-test'
+      const { createTrace, recordToolObservation } = await import(
+        '../tracing.js'
+      )
+      const span = createTrace({
+        sessionId: 's1',
+        model: 'claude-3',
+        provider: 'firstParty',
+      })
+      mockStartObservation.mockClear()
+      mockRootUpdate.mockClear()
+      mockRootEnd.mockClear()
+      recordToolObservation(span, {
+        toolName: 'BashTool',
+        toolUseId: 'tu-1',
+        input: { command: 'ls' },
+        output: 'file.ts',
+      })
+      // Should call the global startObservation with asType: 'tool' and parentSpanContext
+      expect(mockStartObservation).toHaveBeenCalledWith(
+        'BashTool',
+        expect.objectContaining({
+          input: expect.any(Object),
+        }),
+        expect.objectContaining({
+          asType: 'tool',
+          parentSpanContext: mockSpanContext,
+        }),
+      )
+      expect(mockRootUpdate).toHaveBeenCalled()
+      expect(mockRootEnd).toHaveBeenCalled()
+    })
+
+    test('passes startTime to global startObservation', async () => {
+      process.env.LANGFUSE_PUBLIC_KEY = 'pk-test'
+      process.env.LANGFUSE_SECRET_KEY = 'sk-test'
+      const { createTrace, recordToolObservation } = await import(
+        '../tracing.js'
+      )
+      const span = createTrace({
+        sessionId: 's1',
+        model: 'claude-3',
+        provider: 'firstParty',
+      })
+      mockStartObservation.mockClear()
+      const startTime = new Date('2026-01-01T00:00:00Z')
+      recordToolObservation(span, {
+        toolName: 'BashTool',
+        toolUseId: 'tu-2',
+        input: {},
+        output: 'out',
+        startTime,
+      })
+      expect(mockStartObservation).toHaveBeenCalledWith(
+        'BashTool',
+        expect.any(Object),
+        expect.objectContaining({
+          startTime,
+          parentSpanContext: mockSpanContext,
+        }),
+      )
+    })
+
+    test('sanitizes FileReadTool output', async () => {
+      process.env.LANGFUSE_PUBLIC_KEY = 'pk-test'
+      process.env.LANGFUSE_SECRET_KEY = 'sk-test'
+      const { createTrace, recordToolObservation } = await import(
+        '../tracing.js'
+      )
+      const span = createTrace({
+        sessionId: 's1',
+        model: 'claude-3',
+        provider: 'firstParty',
+      })
+      mockRootUpdate.mockClear()
+      recordToolObservation(span, {
+        toolName: 'FileReadTool',
+        toolUseId: 'tu-2',
+        input: { file_path: '/tmp/file.ts' },
+        output: 'file content here',
+      })
+      expect(mockRootUpdate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          output: '[file content redacted, 17 chars]',
+        }),
+      )
+    })
+
+    test('sets ERROR level for error observations', async () => {
+      process.env.LANGFUSE_PUBLIC_KEY = 'pk-test'
+      process.env.LANGFUSE_SECRET_KEY = 'sk-test'
+      const { createTrace, recordToolObservation } = await import(
+        '../tracing.js'
+      )
+      const span = createTrace({
+        sessionId: 's1',
+        model: 'claude-3',
+        provider: 'firstParty',
+      })
+      mockRootUpdate.mockClear()
+      recordToolObservation(span, {
+        toolName: 'BashTool',
+        toolUseId: 'tu-3',
+        input: {},
+        output: 'error occurred',
+        isError: true,
+      })
+      expect(mockRootUpdate).toHaveBeenCalledWith(
+        expect.objectContaining({ level: 'ERROR' }),
+      )
+    })
+  })
+
+  describe('endTrace', () => {
+    test('no-ops when rootSpan is null', async () => {
+      const { endTrace } = await import('../tracing.js')
+      endTrace(null)
+      expect(mockRootEnd).not.toHaveBeenCalled()
+    })
+
+    test('calls span.end()', async () => {
+      process.env.LANGFUSE_PUBLIC_KEY = 'pk-test'
+      process.env.LANGFUSE_SECRET_KEY = 'sk-test'
+      const { createTrace, endTrace } = await import('../tracing.js')
+      const span = createTrace({
+        sessionId: 's1',
+        model: 'claude-3',
+        provider: 'firstParty',
+      })
+      mockRootEnd.mockClear()
+      endTrace(span)
+      expect(mockRootEnd).toHaveBeenCalled()
+    })
+
+    test('calls span.update() with output when provided', async () => {
+      process.env.LANGFUSE_PUBLIC_KEY = 'pk-test'
+      process.env.LANGFUSE_SECRET_KEY = 'sk-test'
+      const { createTrace, endTrace } = await import('../tracing.js')
+      const span = createTrace({
+        sessionId: 's1',
+        model: 'claude-3',
+        provider: 'firstParty',
+      })
+      mockRootUpdate.mockClear()
+      mockRootEnd.mockClear()
+      endTrace(span, 'final output')
+      expect(mockRootUpdate).toHaveBeenCalledWith(
+        expect.objectContaining({ output: 'final output' }),
+      )
+      expect(mockRootEnd).toHaveBeenCalled()
+    })
+  })
+
+  describe('createSubagentTrace', () => {
+    test('returns null when langfuse not enabled', async () => {
+      const { createSubagentTrace } = await import('../tracing.js')
+      const span = createSubagentTrace({
+        sessionId: 's1',
+        agentType: 'Explore',
+        agentId: 'agent-1',
+        model: 'claude-3',
+        provider: 'firstParty',
+      })
+      expect(span).toBeNull()
+    })
+
+    test('creates trace with agentType and agentId metadata', async () => {
+      process.env.LANGFUSE_PUBLIC_KEY = 'pk-test'
+      process.env.LANGFUSE_SECRET_KEY = 'sk-test'
+      const { createSubagentTrace } = await import('../tracing.js')
+      const span = createSubagentTrace({
+        sessionId: 's1',
+        agentType: 'Explore',
+        agentId: 'agent-1',
+        model: 'claude-3',
+        provider: 'firstParty',
+        input: [{ role: 'user', content: 'search for X' }],
+      })
+      expect(span).not.toBeNull()
+      expect(mockStartObservation).toHaveBeenCalledWith(
+        'agent:Explore',
+        expect.objectContaining({
+          metadata: expect.objectContaining({
+            agentType: 'Explore',
+            agentId: 'agent-1',
+            provider: 'firstParty',
+            model: 'claude-3',
+          }),
+        }),
+        { asType: 'agent' },
+      )
+      // Verify session.id attribute is set
+      expect(mockSetAttribute).toHaveBeenCalledWith('session.id', 's1')
+    })
+
+    test('returns null on SDK error', async () => {
+      process.env.LANGFUSE_PUBLIC_KEY = 'pk-test'
+      process.env.LANGFUSE_SECRET_KEY = 'sk-test'
+      mockStartObservation.mockImplementationOnce(() => {
+        throw new Error('SDK error')
+      })
+      const { createSubagentTrace } = await import('../tracing.js')
+      const span = createSubagentTrace({
+        sessionId: 's1',
+        agentType: 'Plan',
+        agentId: 'agent-2',
+        model: 'claude-3',
+        provider: 'firstParty',
+      })
+      expect(span).toBeNull()
+    })
+  })
+
+  describe('createTrace with querySource', () => {
+    test('includes querySource in metadata', async () => {
+      process.env.LANGFUSE_PUBLIC_KEY = 'pk-test'
+      process.env.LANGFUSE_SECRET_KEY = 'sk-test'
+      const { createTrace } = await import('../tracing.js')
+      const span = createTrace({
+        sessionId: 's1',
+        model: 'claude-3',
+        provider: 'firstParty',
+        querySource: 'user',
+      })
+      expect(span).not.toBeNull()
+      expect(mockStartObservation).toHaveBeenCalledWith(
+        'agent-run:user',
+        expect.objectContaining({
+          metadata: expect.objectContaining({
+            agentType: 'main',
+            querySource: 'user',
+          }),
+        }),
+        { asType: 'agent' },
+      )
+    })
+
+    test('omits querySource when not provided', async () => {
+      process.env.LANGFUSE_PUBLIC_KEY = 'pk-test'
+      process.env.LANGFUSE_SECRET_KEY = 'sk-test'
+      mockStartObservation.mockClear()
+      const { createTrace } = await import('../tracing.js')
+      createTrace({
+        sessionId: 's1',
+        model: 'claude-3',
+        provider: 'firstParty',
+      })
+      const calls = mockStartObservation.mock.calls as unknown[][]
+      const secondArg = calls[0]?.[1] as Record<string, unknown> | undefined
+      const metadata = (secondArg?.metadata ?? {}) as Record<string, unknown>
+      expect(metadata).not.toHaveProperty('querySource')
+    })
+  })
+
+  describe('nested agent scenario', () => {
+    test('sub-agent trace shares sessionId with parent', async () => {
+      process.env.LANGFUSE_PUBLIC_KEY = 'pk-test'
+      process.env.LANGFUSE_SECRET_KEY = 'sk-test'
+      const { createTrace, createSubagentTrace } = await import('../tracing.js')
+      mockSetAttribute.mockClear()
+
+      // Create parent trace
+      const parentSpan = createTrace({
+        sessionId: 'shared-session',
+        model: 'claude-3',
+        provider: 'firstParty',
+      })
+
+      // Create sub-agent trace with same sessionId
+      const subSpan = createSubagentTrace({
+        sessionId: 'shared-session',
+        agentType: 'Explore',
+        agentId: 'agent-explore-1',
+        model: 'claude-3',
+        provider: 'firstParty',
+      })
+
+      expect(parentSpan).not.toBeNull()
+      expect(subSpan).not.toBeNull()
+
+      // Both should have set session.id attribute
+      const sessionAttributeCalls = mockSetAttribute.mock.calls.filter(
+        (call: unknown[]) =>
+          Array.isArray(call) &&
+          call[0] === 'session.id' &&
+          call[1] === 'shared-session',
+      )
+      expect(sessionAttributeCalls.length).toBeGreaterThanOrEqual(2)
+    })
+
+    test('query reuses passed langfuseTrace instead of creating new one', async () => {
+      process.env.LANGFUSE_PUBLIC_KEY = 'pk-test'
+      process.env.LANGFUSE_SECRET_KEY = 'sk-test'
+      const { createSubagentTrace } = await import('../tracing.js')
+
+      const subTrace = createSubagentTrace({
+        sessionId: 's1',
+        agentType: 'Explore',
+        agentId: 'agent-1',
+        model: 'claude-3',
+        provider: 'firstParty',
+      })
+      expect(subTrace).not.toBeNull()
+
+      // Simulate query.ts logic: if langfuseTrace already set, don't create new one
+      const ownsTrace = false
+      const langfuseTrace = subTrace
+
+      expect(ownsTrace).toBe(false)
+      expect(langfuseTrace).toBe(subTrace)
+    })
+  })
+
+  describe('SDK exceptions do not affect main flow', () => {
+    test('createTrace returns null on SDK error', async () => {
+      process.env.LANGFUSE_PUBLIC_KEY = 'pk-test'
+      process.env.LANGFUSE_SECRET_KEY = 'sk-test'
+      mockStartObservation.mockImplementationOnce(() => {
+        throw new Error('SDK error')
+      })
+      const { createTrace } = await import('../tracing.js')
+      const span = createTrace({
+        sessionId: 's1',
+        model: 'claude-3',
+        provider: 'firstParty',
+      })
+      expect(span).toBeNull()
+    })
+
+    test('recordLLMObservation silently fails on SDK error', async () => {
+      process.env.LANGFUSE_PUBLIC_KEY = 'pk-test'
+      process.env.LANGFUSE_SECRET_KEY = 'sk-test'
+      const { createTrace, recordLLMObservation } = await import(
+        '../tracing.js'
+      )
+      const span = createTrace({
+        sessionId: 's1',
+        model: 'claude-3',
+        provider: 'firstParty',
+      })
+      // The next call to startObservation (for the generation) will throw
+      mockStartObservation.mockImplementationOnce(() => {
+        throw new Error('SDK error')
+      })
+      expect(() =>
+        recordLLMObservation(span, {
+          model: 'm',
+          provider: 'firstParty',
+          input: [],
+          output: [],
+          usage: { input_tokens: 1, output_tokens: 1 },
+        }),
+      ).not.toThrow()
+    })
+  })
+})
diff --git a/src/tasks/InProcessTeammateTask/InProcessTeammateTask.tsx b/src/tasks/InProcessTeammateTask/InProcessTeammateTask.tsx
index 0fbdc1052..6b9d8c3cc 100644
--- a/src/tasks/InProcessTeammateTask/InProcessTeammateTask.tsx
+++ b/src/tasks/InProcessTeammateTask/InProcessTeammateTask.tsx
@@ -9,19 +9,14 @@
  * 4. Can be idle (waiting for work) or active (processing)
  */
 
-import {
-  isTerminalTaskStatus,
-  type SetAppState,
-  type Task,
-  type TaskStateBase,
-} from '../../Task.js'
-import type { Message } from '../../types/message.js'
-import { logForDebugging } from '../../utils/debug.js'
-import { createUserMessage } from '../../utils/messages.js'
-import { killInProcessTeammate } from '../../utils/swarm/spawnInProcess.js'
-import { updateTaskState } from '../../utils/task/framework.js'
-import type { InProcessTeammateTaskState } from './types.js'
-import { appendCappedMessage, isInProcessTeammateTask } from './types.js'
+import { isTerminalTaskStatus, type SetAppState, type Task, type TaskStateBase } from '../../Task.js';
+import type { Message, MessageOrigin } from '../../types/message.js';
+import { logForDebugging } from '../../utils/debug.js';
+import { createUserMessage } from '../../utils/messages.js';
+import { killInProcessTeammate } from '../../utils/swarm/spawnInProcess.js';
+import { updateTaskState } from '../../utils/task/framework.js';
+import type { InProcessTeammateTaskState, PendingTeammateUserMessage } from './types.js';
+import { appendCappedMessage, isInProcessTeammateTask } from './types.js';
 
 /**
  * InProcessTeammateTask - Handles in-process teammate execution.
@@ -30,48 +25,41 @@ export const InProcessTeammateTask: Task = {
   name: 'InProcessTeammateTask',
   type: 'in_process_teammate',
   async kill(taskId, setAppState) {
-    killInProcessTeammate(taskId, setAppState)
+    killInProcessTeammate(taskId, setAppState);
   },
-}
+};
 
 /**
  * Request shutdown for a teammate.
  */
-export function requestTeammateShutdown(
-  taskId: string,
-  setAppState: SetAppState,
-): void {
+export function requestTeammateShutdown(taskId: string, setAppState: SetAppState): void {
   updateTaskState<InProcessTeammateTaskState>(taskId, setAppState, task => {
     if (task.status !== 'running' || task.shutdownRequested) {
-      return task
+      return task;
     }
 
     return {
       ...task,
       shutdownRequested: true,
-    }
-  })
+    };
+  });
 }
 
 /**
  * Append a message to a teammate's conversation history.
  * Used for zoomed view to show the teammate's conversation.
  */
-export function appendTeammateMessage(
-  taskId: string,
-  message: Message,
-  setAppState: SetAppState,
-): void {
+export function appendTeammateMessage(taskId: string, message: Message, setAppState: SetAppState): void {
   updateTaskState<InProcessTeammateTaskState>(taskId, setAppState, task => {
     if (task.status !== 'running') {
-      return task
+      return task;
     }
 
     return {
       ...task,
       messages: appendCappedMessage(task.messages, message),
-    }
-  })
+    };
+  });
 }
 
 /**
@@ -82,27 +70,47 @@ export function appendTeammateMessage(
 export function injectUserMessageToTeammate(
   taskId: string,
   message: string,
+  options:
+    | {
+        autonomyRunId?: string;
+        origin?: MessageOrigin;
+      }
+    | undefined,
   setAppState: SetAppState,
-): void {
+): boolean {
+  let injected = false;
   updateTaskState<InProcessTeammateTaskState>(taskId, setAppState, task => {
     // Allow message injection when teammate is running or idle (waiting for input)
     // Only reject if teammate is in a terminal state
     if (isTerminalTaskStatus(task.status)) {
-      logForDebugging(
-        `Dropping message for teammate task ${taskId}: task status is "${task.status}"`,
-      )
-      return task
+      logForDebugging(`Dropping message for teammate task ${taskId}: task status is "${task.status}"`);
+      return task;
+    }
+
+    injected = true;
+
+    const pendingMessage: PendingTeammateUserMessage = { message };
+    if (options?.autonomyRunId !== undefined) {
+      pendingMessage.autonomyRunId = options.autonomyRunId;
+    }
+    if (options?.origin !== undefined) {
+      pendingMessage.origin = options.origin;
+    }
+
+    const userMessageArgs: Parameters<typeof createUserMessage>[0] = {
+      content: message,
+    };
+    if (options?.origin !== undefined) {
+      userMessageArgs.origin = options.origin;
     }
 
     return {
       ...task,
-      pendingUserMessages: [...task.pendingUserMessages, message],
-      messages: appendCappedMessage(
-        task.messages,
-        createUserMessage({ content: message }),
-      ),
-    }
-  })
+      pendingUserMessages: [...task.pendingUserMessages, pendingMessage],
+      messages: appendCappedMessage(task.messages, createUserMessage(userMessageArgs)),
+    };
+  });
+  return injected;
 }
 
 /**
@@ -115,30 +123,28 @@ export function findTeammateTaskByAgentId(
   agentId: string,
   tasks: Record<string, TaskStateBase>,
 ): InProcessTeammateTaskState | undefined {
-  let fallback: InProcessTeammateTaskState | undefined
+  let fallback: InProcessTeammateTaskState | undefined;
   for (const task of Object.values(tasks)) {
     if (isInProcessTeammateTask(task) && task.identity.agentId === agentId) {
       // Prefer running tasks in case old killed tasks still exist in AppState
       // alongside new running ones with the same agentId
       if (task.status === 'running') {
-        return task
+        return task;
       }
       // Keep first match as fallback in case no running task exists
       if (!fallback) {
-        fallback = task
+        fallback = task;
       }
     }
   }
-  return fallback
+  return fallback;
 }
 
 /**
  * Get all in-process teammate tasks from AppState.
  */
-export function getAllInProcessTeammateTasks(
-  tasks: Record<string, TaskStateBase>,
-): InProcessTeammateTaskState[] {
-  return Object.values(tasks).filter(isInProcessTeammateTask)
+export function getAllInProcessTeammateTasks(tasks: Record<string, TaskStateBase>): InProcessTeammateTaskState[] {
+  return Object.values(tasks).filter(isInProcessTeammateTask);
 }
 
 /**
@@ -147,10 +153,8 @@ export function getAllInProcessTeammateTasks(
  * and useBackgroundTaskNavigation — selectedIPAgentIndex maps into this
  * array, so all three must agree on sort order.
  */
-export function getRunningTeammatesSorted(
-  tasks: Record<string, TaskStateBase>,
-): InProcessTeammateTaskState[] {
+export function getRunningTeammatesSorted(tasks: Record<string, TaskStateBase>): InProcessTeammateTaskState[] {
   return getAllInProcessTeammateTasks(tasks)
     .filter(t => t.status === 'running')
-    .sort((a, b) => a.identity.agentName.localeCompare(b.identity.agentName))
+    .sort((a, b) => a.identity.agentName.localeCompare(b.identity.agentName));
 }
diff --git a/src/tasks/InProcessTeammateTask/types.ts b/src/tasks/InProcessTeammateTask/types.ts
index df8b7fc2c..90d9fb212 100644
--- a/src/tasks/InProcessTeammateTask/types.ts
+++ b/src/tasks/InProcessTeammateTask/types.ts
@@ -1,7 +1,7 @@
 import type { TaskStateBase } from '../../Task.js'
 import type { AgentToolResult } from '@claude-code-best/builtin-tools/tools/AgentTool/agentToolUtils.js'
 import type { AgentDefinition } from '@claude-code-best/builtin-tools/tools/AgentTool/loadAgentsDir.js'
-import type { Message } from '../../types/message.js'
+import type { Message, MessageOrigin } from '../../types/message.js'
 import type { PermissionMode } from '../../utils/permissions/PermissionMode.js'
 import type { AgentProgress } from '../LocalAgentTask/LocalAgentTask.js'
 
@@ -19,6 +19,12 @@ export type TeammateIdentity = {
   parentSessionId: string // Leader's session ID
 }
 
+export type PendingTeammateUserMessage = {
+  message: string
+  autonomyRunId?: string
+  origin?: MessageOrigin
+}
+
 export type InProcessTeammateTaskState = TaskStateBase & {
   type: 'in_process_teammate'
 
@@ -56,7 +62,7 @@ export type InProcessTeammateTaskState = TaskStateBase & {
   inProgressToolUseIDs?: Set<string>
 
   // Queue of user messages to deliver when viewing teammate transcript
-  pendingUserMessages: string[]
+  pendingUserMessages: PendingTeammateUserMessage[]
 
   // UI: random spinner verbs (stable across re-renders, shared between components)
   spinnerVerb?: string
diff --git a/src/types/textInputTypes.ts b/src/types/textInputTypes.ts
index 7e5cb047e..6b0a848d2 100644
--- a/src/types/textInputTypes.ts
+++ b/src/types/textInputTypes.ts
@@ -355,6 +355,19 @@ export type QueuedCommand = {
    * unified the queue but lost the isolation the dual-queue accidentally had).
    */
   agentId?: AgentId
+  /**
+   * Autonomy-run provenance for system-generated automatic turns.
+   * Used by the autonomy ledger to track queue → execution lifecycle.
+   */
+  autonomy?: {
+    runId: string
+    trigger: 'scheduled-task' | 'proactive-tick' | 'managed-flow-step'
+    sourceId?: string
+    sourceLabel?: string
+    flowId?: string
+    flowStepId?: string
+    flowStepName?: string
+  }
 }
 
 /**
diff --git a/src/utils/__tests__/autonomyAuthority.test.ts b/src/utils/__tests__/autonomyAuthority.test.ts
new file mode 100644
index 000000000..c9033134b
--- /dev/null
+++ b/src/utils/__tests__/autonomyAuthority.test.ts
@@ -0,0 +1,241 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { join } from 'node:path'
+import {
+  AUTONOMY_AGENTS_PATH_POSIX,
+  AUTONOMY_DIR,
+  buildAutonomyTurnPrompt,
+  loadAutonomyAuthority,
+  resetAutonomyAuthorityForTests,
+} from '../autonomyAuthority'
+import {
+  cleanupTempDir,
+  createTempDir,
+  createTempSubdir,
+  writeTempFile,
+} from '../../../tests/mocks/file-system'
+
+const AGENTS_REL = join(AUTONOMY_DIR, 'AGENTS.md')
+const HEARTBEAT_REL = join(AUTONOMY_DIR, 'HEARTBEAT.md')
+
+let tempDir = ''
+
+beforeEach(async () => {
+  tempDir = await createTempDir('autonomy-authority-')
+})
+
+afterEach(async () => {
+  resetAutonomyAuthorityForTests()
+  if (tempDir) {
+    await cleanupTempDir(tempDir)
+  }
+})
+
+describe('autonomyAuthority', () => {
+  test('loadAutonomyAuthority merges AGENTS.md files from root to current directory', async () => {
+    const nestedDir = await createTempSubdir(tempDir, 'packages/app')
+    await writeTempFile(tempDir, AGENTS_REL, 'root authority')
+    await writeTempFile(nestedDir, AGENTS_REL, 'nested authority')
+    await writeTempFile(
+      tempDir,
+      HEARTBEAT_REL,
+      [
+        '# Heartbeat',
+        'tasks:',
+        '  - name: inbox',
+        '    interval: 30m',
+        '    prompt: "Check inbox"',
+      ].join('\n'),
+    )
+
+    const snapshot = await loadAutonomyAuthority({
+      rootDir: tempDir,
+      currentDir: nestedDir,
+    })
+
+    expect(snapshot.agentsFiles.map(file => file.relativePath)).toEqual([
+      AUTONOMY_AGENTS_PATH_POSIX,
+      `packages/app/${AUTONOMY_AGENTS_PATH_POSIX}`,
+    ])
+    expect(snapshot.agentsContent).toContain('root authority')
+    expect(snapshot.agentsContent).toContain('nested authority')
+    expect(snapshot.heartbeatContent).toContain('# Heartbeat')
+    expect(snapshot.heartbeatTasks).toEqual([
+      {
+        name: 'inbox',
+        interval: '30m',
+        prompt: 'Check inbox',
+        steps: [],
+      },
+    ])
+  })
+
+  test('loadAutonomyAuthority reads HEARTBEAT.md only from the workspace root', async () => {
+    const nestedDir = await createTempSubdir(tempDir, 'child')
+    await writeTempFile(
+      tempDir,
+      HEARTBEAT_REL,
+      '# Root heartbeat\nRemember the root task',
+    )
+    await writeTempFile(
+      nestedDir,
+      HEARTBEAT_REL,
+      '# Nested heartbeat\nThis should not be used',
+    )
+
+    const snapshot = await loadAutonomyAuthority({
+      rootDir: tempDir,
+      currentDir: nestedDir,
+    })
+
+    expect(snapshot.heartbeatFile?.path).toBe(join(tempDir, HEARTBEAT_REL))
+    expect(snapshot.heartbeatContent).toContain('Root heartbeat')
+    expect(snapshot.heartbeatContent).not.toContain('Nested heartbeat')
+  })
+
+  test('buildAutonomyTurnPrompt returns the original prompt when no authority files exist', async () => {
+    const prompt = await buildAutonomyTurnPrompt({
+      basePrompt: 'Run the scheduled task.',
+      trigger: 'scheduled-task',
+      rootDir: tempDir,
+      currentDir: tempDir,
+    })
+
+    expect(prompt).toBe('Run the scheduled task.')
+  })
+
+  test('buildAutonomyTurnPrompt injects AGENTS.md and HEARTBEAT.md for automated turns', async () => {
+    const nestedDir = await createTempSubdir(tempDir, 'nested')
+    await writeTempFile(tempDir, AGENTS_REL, 'root rules')
+    await writeTempFile(nestedDir, AGENTS_REL, 'nested rules')
+    await writeTempFile(tempDir, HEARTBEAT_REL, 'Check heartbeat directives')
+
+    const scheduledPrompt = await buildAutonomyTurnPrompt({
+      basePrompt: 'Review the nightly report.',
+      trigger: 'scheduled-task',
+      rootDir: tempDir,
+      currentDir: nestedDir,
+    })
+    const tickPrompt = await buildAutonomyTurnPrompt({
+      basePrompt: '<tick>12:00:00</tick>',
+      trigger: 'proactive-tick',
+      rootDir: tempDir,
+      currentDir: nestedDir,
+    })
+
+    expect(scheduledPrompt).toContain(
+      'This prompt was generated automatically. Follow the workspace authority below before acting.',
+    )
+    expect(scheduledPrompt).toContain('<autonomy_authority>')
+    expect(scheduledPrompt).toContain('root rules')
+    expect(scheduledPrompt).toContain('nested rules')
+    expect(scheduledPrompt).toContain('Check heartbeat directives')
+    expect(scheduledPrompt).toContain('Review the nightly report.')
+
+    expect(tickPrompt).toContain(
+      'This is an autonomous proactive turn. Follow the workspace authority below before acting.',
+    )
+    expect(tickPrompt).toContain('<tick>12:00:00</tick>')
+  })
+
+  test('proactive prompts surface due HEARTBEAT.md tasks only when their interval elapses', async () => {
+    await writeTempFile(
+      tempDir,
+      HEARTBEAT_REL,
+      [
+        'tasks:',
+        '  - name: inbox',
+        '    interval: 30m',
+        '    prompt: "Check inbox"',
+      ].join('\n'),
+    )
+
+    const first = await buildAutonomyTurnPrompt({
+      basePrompt: '<tick>12:00:00</tick>',
+      trigger: 'proactive-tick',
+      rootDir: tempDir,
+      currentDir: tempDir,
+      nowMs: 0,
+    })
+    const second = await buildAutonomyTurnPrompt({
+      basePrompt: '<tick>12:10:00</tick>',
+      trigger: 'proactive-tick',
+      rootDir: tempDir,
+      currentDir: tempDir,
+      nowMs: 10 * 60_000,
+    })
+    const third = await buildAutonomyTurnPrompt({
+      basePrompt: '<tick>12:31:00</tick>',
+      trigger: 'proactive-tick',
+      rootDir: tempDir,
+      currentDir: tempDir,
+      nowMs: 31 * 60_000,
+    })
+
+    expect(first).toContain('Due HEARTBEAT.md tasks:')
+    expect(first).toContain('- inbox (30m): Check inbox')
+    expect(second).not.toContain('Due HEARTBEAT.md tasks:')
+    expect(third).toContain('Due HEARTBEAT.md tasks:')
+  })
+
+  test('managed HEARTBEAT.md tasks parse nested steps and are not duplicated into the inline due-task section', async () => {
+    await writeTempFile(
+      tempDir,
+      HEARTBEAT_REL,
+      [
+        'tasks:',
+        '  - name: inbox',
+        '    interval: 30m',
+        '    prompt: "Check inbox"',
+        '  - name: weekly-report',
+        '    interval: 7d',
+        '    prompt: "Ship the weekly report"',
+        '    steps:',
+        '      - name: gather',
+        '        prompt: "Gather weekly inputs"',
+        '      - name: draft',
+        '        prompt: "Draft the weekly report"',
+        '        wait_for: manual',
+      ].join('\n'),
+    )
+
+    const snapshot = await loadAutonomyAuthority({
+      rootDir: tempDir,
+      currentDir: tempDir,
+    })
+    const prompt = await buildAutonomyTurnPrompt({
+      basePrompt: '<tick>12:00:00</tick>',
+      trigger: 'proactive-tick',
+      rootDir: tempDir,
+      currentDir: tempDir,
+      nowMs: 0,
+    })
+
+    expect(snapshot.heartbeatTasks).toEqual([
+      {
+        name: 'inbox',
+        interval: '30m',
+        prompt: 'Check inbox',
+        steps: [],
+      },
+      {
+        name: 'weekly-report',
+        interval: '7d',
+        prompt: 'Ship the weekly report',
+        steps: [
+          {
+            name: 'gather',
+            prompt: 'Gather weekly inputs',
+          },
+          {
+            name: 'draft',
+            prompt: 'Draft the weekly report',
+            waitFor: 'manual',
+          },
+        ],
+      },
+    ])
+    expect(prompt).toContain('- inbox (30m): Check inbox')
+    expect(prompt).not.toContain('- weekly-report (7d): Ship the weekly report')
+    expect(prompt).not.toContain('- gather (')
+  })
+})
diff --git a/src/utils/__tests__/autonomyFlows.test.ts b/src/utils/__tests__/autonomyFlows.test.ts
new file mode 100644
index 000000000..8436844b4
--- /dev/null
+++ b/src/utils/__tests__/autonomyFlows.test.ts
@@ -0,0 +1,1116 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import {
+  resetStateForTests,
+  setOriginalCwd,
+  setProjectRoot,
+} from '../../bootstrap/state'
+import {
+  createManagedAutonomyFlowKey,
+  DEFAULT_AUTONOMY_OWNER_KEY,
+  formatAutonomyFlowDetail,
+  formatAutonomyFlowsList,
+  formatAutonomyFlowsStatus,
+  getAutonomyFlowById,
+  listAutonomyFlows,
+  markManagedAutonomyFlowStepCancelled,
+  markManagedAutonomyFlowStepCompleted,
+  markManagedAutonomyFlowStepFailed,
+  markManagedAutonomyFlowStepRunning,
+  queueManagedAutonomyFlowStepRun,
+  requestManagedAutonomyFlowCancel,
+  resolveAutonomyFlowsPath,
+  resumeManagedAutonomyFlow,
+  startManagedAutonomyFlow,
+  type AutonomyFlowRecord,
+  type ManagedAutonomyFlowStepDefinition,
+} from '../autonomyFlows'
+import { AUTONOMY_DIR } from '../autonomyAuthority'
+import { cleanupTempDir, createTempDir } from '../../../tests/mocks/file-system'
+
+let tempDir = ''
+
+beforeEach(async () => {
+  tempDir = await createTempDir('autonomy-flows-')
+  resetStateForTests()
+  setOriginalCwd(tempDir)
+  setProjectRoot(tempDir)
+})
+
+afterEach(async () => {
+  resetStateForTests()
+  if (tempDir) {
+    await cleanupTempDir(tempDir)
+  }
+})
+
+const TWO_STEPS: ManagedAutonomyFlowStepDefinition[] = [
+  { name: 'gather', prompt: 'Gather inputs' },
+  { name: 'draft', prompt: 'Draft the report' },
+]
+
+const STEPS_WITH_WAIT: ManagedAutonomyFlowStepDefinition[] = [
+  { name: 'gather', prompt: 'Gather inputs', waitFor: 'manual-review' },
+  { name: 'draft', prompt: 'Draft the report' },
+]
+
+describe('createManagedAutonomyFlowKey', () => {
+  test('builds deterministic key from trigger and sourceId', () => {
+    const key = createManagedAutonomyFlowKey({
+      trigger: 'scheduled-task',
+      sourceId: 'cron-1',
+      goal: 'Do stuff',
+    })
+    expect(key).toBe('managed:scheduled-task:cron-1')
+  })
+
+  test('uses sourceLabel when sourceId is absent', () => {
+    const key = createManagedAutonomyFlowKey({
+      trigger: 'scheduled-task',
+      sourceLabel: 'nightly',
+      goal: 'Do stuff',
+    })
+    expect(key).toBe('managed:scheduled-task:nightly')
+  })
+
+  test('falls back to goal when no sourceId or sourceLabel', () => {
+    const key = createManagedAutonomyFlowKey({
+      trigger: 'scheduled-task',
+      goal: 'Do stuff',
+    })
+    expect(key).toBe('managed:scheduled-task:Do stuff')
+  })
+
+  test('uses heartbeat-loop for proactive-tick without sourceId', () => {
+    const key = createManagedAutonomyFlowKey({
+      trigger: 'proactive-tick',
+      goal: 'Tick goal',
+    })
+    expect(key).toBe('managed:proactive-tick:heartbeat-loop')
+  })
+})
+
+describe('resolveAutonomyFlowsPath', () => {
+  test('resolves to flows.json under the autonomy dir', () => {
+    const path = resolveAutonomyFlowsPath(tempDir)
+    expect(path).toContain(AUTONOMY_DIR)
+    expect(path).toContain('flows.json')
+  })
+})
+
+describe('listAutonomyFlows', () => {
+  test('returns empty array when no file exists', async () => {
+    const flows = await listAutonomyFlows(tempDir)
+    expect(flows).toEqual([])
+  })
+
+  test('reads and normalizes flow records from disk', async () => {
+    const flowsPath = resolveAutonomyFlowsPath(tempDir)
+    await mkdir(join(tempDir, AUTONOMY_DIR), { recursive: true })
+    await writeFile(
+      flowsPath,
+      JSON.stringify({
+        flows: [
+          {
+            flowId: 'flow-1',
+            flowKey: 'managed:scheduled-task:cron-1',
+            syncMode: 'managed',
+            trigger: 'scheduled-task',
+            status: 'queued',
+            rootDir: tempDir,
+            goal: 'Test goal',
+            createdAt: 100,
+            updatedAt: 200,
+            revision: 1,
+            runCount: 0,
+            ownerKey: DEFAULT_AUTONOMY_OWNER_KEY,
+            currentDir: tempDir,
+            stateJson: {
+              currentStepIndex: 0,
+              steps: [
+                {
+                  stepId: 'step-1',
+                  name: 'gather',
+                  prompt: 'Gather inputs',
+                  status: 'pending',
+                },
+              ],
+            },
+          },
+        ],
+      }),
+      'utf-8',
+    )
+
+    const flows = await listAutonomyFlows(tempDir)
+    expect(flows).toHaveLength(1)
+    expect(flows[0]?.flowId).toBe('flow-1')
+    expect(flows[0]?.syncMode).toBe('managed')
+    expect(flows[0]?.stateJson?.steps).toHaveLength(1)
+  })
+
+  test('filters out invalid records', async () => {
+    const flowsPath = resolveAutonomyFlowsPath(tempDir)
+    await mkdir(join(tempDir, AUTONOMY_DIR), { recursive: true })
+    await writeFile(
+      flowsPath,
+      JSON.stringify({
+        flows: [
+          {
+            flowId: 'valid-flow',
+            flowKey: 'k',
+            trigger: 'scheduled-task',
+            status: 'queued',
+            rootDir: tempDir,
+            createdAt: 1,
+            updatedAt: 2,
+            goal: 'g',
+            revision: 0,
+            runCount: 0,
+            ownerKey: 'main-thread',
+            currentDir: tempDir,
+          },
+          { bad: true },
+          null,
+        ],
+      }),
+      'utf-8',
+    )
+
+    const flows = await listAutonomyFlows(tempDir)
+    expect(flows).toHaveLength(1)
+    expect(flows[0]?.flowId).toBe('valid-flow')
+  })
+
+  test('returns empty array for malformed JSON', async () => {
+    const flowsPath = resolveAutonomyFlowsPath(tempDir)
+    await mkdir(join(tempDir, AUTONOMY_DIR), { recursive: true })
+    await writeFile(flowsPath, 'not json', 'utf-8')
+
+    const flows = await listAutonomyFlows(tempDir)
+    expect(flows).toEqual([])
+  })
+})
+
+describe('startManagedAutonomyFlow', () => {
+  test('returns null when steps array is empty', async () => {
+    const result = await startManagedAutonomyFlow({
+      trigger: 'scheduled-task',
+      goal: 'Test',
+      steps: [],
+      rootDir: tempDir,
+    })
+    expect(result).toBeNull()
+  })
+
+  test('creates a new flow with queued status and returns nextStep', async () => {
+    const result = await startManagedAutonomyFlow({
+      trigger: 'scheduled-task',
+      goal: 'Ship report',
+      steps: TWO_STEPS,
+      rootDir: tempDir,
+      nowMs: 1000,
+    })
+
+    expect(result).not.toBeNull()
+    expect(result!.started).toBe(true)
+    expect(result!.flow.status).toBe('queued')
+    expect(result!.flow.goal).toBe('Ship report')
+    expect(result!.flow.currentStep).toBe('gather')
+    expect(result!.flow.stateJson?.steps).toHaveLength(2)
+    expect(result!.flow.stateJson?.steps[0]?.status).toBe('pending')
+    expect(result!.nextStep).toBeDefined()
+    expect(result!.nextStep!.stepIndex).toBe(0)
+    expect(result!.nextStep!.step.name).toBe('gather')
+  })
+
+  test('sets status=waiting when first step has waitFor', async () => {
+    const result = await startManagedAutonomyFlow({
+      trigger: 'scheduled-task',
+      goal: 'Wait flow',
+      steps: STEPS_WITH_WAIT,
+      rootDir: tempDir,
+      nowMs: 1000,
+    })
+
+    expect(result!.started).toBe(true)
+    expect(result!.flow.status).toBe('waiting')
+    expect(result!.flow.waitJson).toBeDefined()
+    expect(result!.flow.waitJson!.reason).toBe('manual-review')
+    expect(result!.nextStep).toBeUndefined()
+  })
+
+  test('returns started=false if active flow with same key exists', async () => {
+    const first = await startManagedAutonomyFlow({
+      trigger: 'scheduled-task',
+      goal: 'Ship report',
+      steps: TWO_STEPS,
+      rootDir: tempDir,
+      sourceId: 'dup-key',
+      nowMs: 1000,
+    })
+    expect(first!.started).toBe(true)
+
+    const second = await startManagedAutonomyFlow({
+      trigger: 'scheduled-task',
+      goal: 'Ship report',
+      steps: TWO_STEPS,
+      rootDir: tempDir,
+      sourceId: 'dup-key',
+      nowMs: 2000,
+    })
+    expect(second!.started).toBe(false)
+    expect(second!.flow.flowId).toBe(first!.flow.flowId)
+  })
+
+  test('reuses flowId when restarting a completed flow', async () => {
+    // Start and complete a flow
+    const first = await startManagedAutonomyFlow({
+      trigger: 'scheduled-task',
+      goal: 'Repeatable',
+      steps: [{ name: 'only', prompt: 'Do it' }],
+      rootDir: tempDir,
+      sourceId: 'repeat-src',
+      nowMs: 1000,
+    })
+    const flowId = first!.flow.flowId
+
+    // Queue and complete
+    await queueManagedAutonomyFlowStepRun({
+      flowId,
+      stepId: first!.nextStep!.step.stepId,
+      stepIndex: 0,
+      runId: 'run-1',
+      rootDir: tempDir,
+      nowMs: 2000,
+    })
+    await markManagedAutonomyFlowStepRunning({
+      flowId,
+      runId: 'run-1',
+      rootDir: tempDir,
+      nowMs: 3000,
+    })
+    await markManagedAutonomyFlowStepCompleted({
+      flowId,
+      runId: 'run-1',
+      rootDir: tempDir,
+      nowMs: 4000,
+    })
+
+    // Verify it completed
+    const completed = await getAutonomyFlowById(flowId, tempDir)
+    expect(completed!.status).toBe('succeeded')
+
+    // Restart with the same key
+    const restarted = await startManagedAutonomyFlow({
+      trigger: 'scheduled-task',
+      goal: 'Repeatable',
+      steps: [{ name: 'only', prompt: 'Do it again' }],
+      rootDir: tempDir,
+      sourceId: 'repeat-src',
+      nowMs: 5000,
+    })
+
+    expect(restarted!.started).toBe(true)
+    expect(restarted!.flow.flowId).toBe(flowId)
+    expect(restarted!.flow.revision).toBeGreaterThan(first!.flow.revision)
+  })
+
+  test('persists the flow to disk', async () => {
+    await startManagedAutonomyFlow({
+      trigger: 'scheduled-task',
+      goal: 'Persist test',
+      steps: TWO_STEPS,
+      rootDir: tempDir,
+      nowMs: 1000,
+    })
+
+    const raw = await readFile(resolveAutonomyFlowsPath(tempDir), 'utf-8')
+    const parsed = JSON.parse(raw) as { flows: AutonomyFlowRecord[] }
+    expect(parsed.flows).toHaveLength(1)
+    expect(parsed.flows[0]?.goal).toBe('Persist test')
+  })
+})
+
+describe('full lifecycle: start → queue → running → completed → succeeded', () => {
+  test('advances through all steps to succeeded', async () => {
+    const startResult = await startManagedAutonomyFlow({
+      trigger: 'scheduled-task',
+      goal: 'Full lifecycle',
+      steps: TWO_STEPS,
+      rootDir: tempDir,
+      nowMs: 1000,
+    })
+    const flowId = startResult!.flow.flowId
+    const step0Id = startResult!.nextStep!.step.stepId
+
+    // Queue step 0
+    const queued = await queueManagedAutonomyFlowStepRun({
+      flowId,
+      stepId: step0Id,
+      stepIndex: 0,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 2000,
+    })
+    expect(queued!.status).toBe('queued')
+    expect(queued!.latestRunId).toBe('run-0')
+    expect(queued!.runCount).toBe(1)
+
+    // Mark step 0 running
+    const running = await markManagedAutonomyFlowStepRunning({
+      flowId,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 3000,
+    })
+    expect(running!.status).toBe('running')
+    expect(running!.startedAt).toBe(3000)
+
+    // Complete step 0 — should auto-advance to step 1
+    const advanced = await markManagedAutonomyFlowStepCompleted({
+      flowId,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 4000,
+    })
+    expect(advanced!.flow.status).toBe('queued')
+    expect(advanced!.flow.currentStep).toBe('draft')
+    expect(advanced!.nextStep).toBeDefined()
+    expect(advanced!.nextStep!.stepIndex).toBe(1)
+    const step1Id = advanced!.nextStep!.step.stepId
+
+    // Queue step 1
+    await queueManagedAutonomyFlowStepRun({
+      flowId,
+      stepId: step1Id,
+      stepIndex: 1,
+      runId: 'run-1',
+      rootDir: tempDir,
+      nowMs: 5000,
+    })
+
+    // Mark step 1 running
+    await markManagedAutonomyFlowStepRunning({
+      flowId,
+      runId: 'run-1',
+      rootDir: tempDir,
+      nowMs: 6000,
+    })
+
+    // Complete step 1 — no more steps, should succeed
+    const final = await markManagedAutonomyFlowStepCompleted({
+      flowId,
+      runId: 'run-1',
+      rootDir: tempDir,
+      nowMs: 7000,
+    })
+    expect(final!.flow.status).toBe('succeeded')
+    expect(final!.flow.endedAt).toBe(7000)
+    expect(final!.nextStep).toBeUndefined()
+
+    // Verify persisted state
+    const persisted = await getAutonomyFlowById(flowId, tempDir)
+    expect(persisted!.status).toBe('succeeded')
+    expect(persisted!.stateJson?.steps[0]?.status).toBe('completed')
+    expect(persisted!.stateJson?.steps[1]?.status).toBe('completed')
+  })
+})
+
+describe('lifecycle: step failure', () => {
+  test('marks flow as failed when step fails', async () => {
+    const startResult = await startManagedAutonomyFlow({
+      trigger: 'scheduled-task',
+      goal: 'Fail lifecycle',
+      steps: TWO_STEPS,
+      rootDir: tempDir,
+      nowMs: 1000,
+    })
+    const flowId = startResult!.flow.flowId
+    const step0Id = startResult!.nextStep!.step.stepId
+
+    await queueManagedAutonomyFlowStepRun({
+      flowId,
+      stepId: step0Id,
+      stepIndex: 0,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 2000,
+    })
+    await markManagedAutonomyFlowStepRunning({
+      flowId,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 3000,
+    })
+
+    const failed = await markManagedAutonomyFlowStepFailed({
+      flowId,
+      runId: 'run-0',
+      error: 'Something broke',
+      rootDir: tempDir,
+      nowMs: 4000,
+    })
+
+    expect(failed!.flow.status).toBe('failed')
+    expect(failed!.flow.lastError).toBe('Something broke')
+    expect(failed!.flow.blockedRunId).toBe('run-0')
+    expect(failed!.flow.endedAt).toBe(4000)
+    expect(failed!.flow.stateJson?.steps[0]?.status).toBe('failed')
+    expect(failed!.flow.stateJson?.steps[0]?.error).toBe('Something broke')
+  })
+})
+
+describe('lifecycle: waitFor → resume', () => {
+  test('starts waiting then resumes and completes', async () => {
+    const startResult = await startManagedAutonomyFlow({
+      trigger: 'scheduled-task',
+      goal: 'Wait then resume',
+      steps: STEPS_WITH_WAIT,
+      rootDir: tempDir,
+      nowMs: 1000,
+    })
+    const flowId = startResult!.flow.flowId
+    expect(startResult!.flow.status).toBe('waiting')
+    expect(startResult!.nextStep).toBeUndefined()
+
+    // Resume the waiting flow
+    const resumed = await resumeManagedAutonomyFlow({
+      flowId,
+      rootDir: tempDir,
+      nowMs: 2000,
+    })
+    expect(resumed!.flow.status).toBe('queued')
+    expect(resumed!.flow.waitJson).toBeUndefined()
+    expect(resumed!.nextStep).toBeDefined()
+    expect(resumed!.nextStep!.step.name).toBe('gather')
+
+    // Queue, run, complete step 0
+    const step0Id = resumed!.nextStep!.step.stepId
+    await queueManagedAutonomyFlowStepRun({
+      flowId,
+      stepId: step0Id,
+      stepIndex: 0,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 3000,
+    })
+    await markManagedAutonomyFlowStepRunning({
+      flowId,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 4000,
+    })
+    const afterStep0 = await markManagedAutonomyFlowStepCompleted({
+      flowId,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 5000,
+    })
+
+    // Step 1 has no waitFor, so should auto-queue
+    expect(afterStep0!.flow.status).toBe('queued')
+    expect(afterStep0!.nextStep!.step.name).toBe('draft')
+
+    // Complete step 1
+    const step1Id = afterStep0!.nextStep!.step.stepId
+    await queueManagedAutonomyFlowStepRun({
+      flowId,
+      stepId: step1Id,
+      stepIndex: 1,
+      runId: 'run-1',
+      rootDir: tempDir,
+      nowMs: 6000,
+    })
+    await markManagedAutonomyFlowStepRunning({
+      flowId,
+      runId: 'run-1',
+      rootDir: tempDir,
+      nowMs: 7000,
+    })
+    const final = await markManagedAutonomyFlowStepCompleted({
+      flowId,
+      runId: 'run-1',
+      rootDir: tempDir,
+      nowMs: 8000,
+    })
+    expect(final!.flow.status).toBe('succeeded')
+  })
+})
+
+describe('lifecycle: next step has waitFor', () => {
+  test('completing a step transitions to waiting when next step has waitFor', async () => {
+    const steps: ManagedAutonomyFlowStepDefinition[] = [
+      { name: 'step-a', prompt: 'Do A' },
+      { name: 'step-b', prompt: 'Do B', waitFor: 'approval' },
+    ]
+    const startResult = await startManagedAutonomyFlow({
+      trigger: 'scheduled-task',
+      goal: 'Wait mid-flow',
+      steps,
+      rootDir: tempDir,
+      nowMs: 1000,
+    })
+    const flowId = startResult!.flow.flowId
+    const step0Id = startResult!.nextStep!.step.stepId
+
+    await queueManagedAutonomyFlowStepRun({
+      flowId,
+      stepId: step0Id,
+      stepIndex: 0,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 2000,
+    })
+    await markManagedAutonomyFlowStepRunning({
+      flowId,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 3000,
+    })
+    const afterStep0 = await markManagedAutonomyFlowStepCompleted({
+      flowId,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 4000,
+    })
+
+    expect(afterStep0!.flow.status).toBe('waiting')
+    expect(afterStep0!.flow.waitJson).toBeDefined()
+    expect(afterStep0!.flow.waitJson!.reason).toBe('approval')
+    expect(afterStep0!.flow.waitJson!.stepName).toBe('step-b')
+    expect(afterStep0!.nextStep).toBeUndefined()
+  })
+})
+
+describe('requestManagedAutonomyFlowCancel', () => {
+  test('immediate cancel when not running (queued)', async () => {
+    const startResult = await startManagedAutonomyFlow({
+      trigger: 'scheduled-task',
+      goal: 'Cancel test',
+      steps: TWO_STEPS,
+      rootDir: tempDir,
+      nowMs: 1000,
+    })
+    const flowId = startResult!.flow.flowId
+
+    const cancelResult = await requestManagedAutonomyFlowCancel({
+      flowId,
+      rootDir: tempDir,
+      nowMs: 2000,
+    })
+
+    expect(cancelResult!.accepted).toBe(true)
+    expect(cancelResult!.flow.status).toBe('cancelled')
+    expect(cancelResult!.flow.endedAt).toBe(2000)
+  })
+
+  test('deferred cancel when step is running, completes on next step completion', async () => {
+    const startResult = await startManagedAutonomyFlow({
+      trigger: 'scheduled-task',
+      goal: 'Deferred cancel',
+      steps: TWO_STEPS,
+      rootDir: tempDir,
+      nowMs: 1000,
+    })
+    const flowId = startResult!.flow.flowId
+    const step0Id = startResult!.nextStep!.step.stepId
+
+    // Queue and start running
+    await queueManagedAutonomyFlowStepRun({
+      flowId,
+      stepId: step0Id,
+      stepIndex: 0,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 2000,
+    })
+    await markManagedAutonomyFlowStepRunning({
+      flowId,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 3000,
+    })
+
+    // Request cancel while running — should be deferred
+    const cancelResult = await requestManagedAutonomyFlowCancel({
+      flowId,
+      rootDir: tempDir,
+      nowMs: 4000,
+    })
+    expect(cancelResult!.accepted).toBe(true)
+    expect(cancelResult!.flow.status).toBe('running') // Still running
+    expect(cancelResult!.flow.cancelRequestedAt).toBe(4000)
+
+    // Complete the step — cancel should now take effect
+    const completed = await markManagedAutonomyFlowStepCompleted({
+      flowId,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 5000,
+    })
+    expect(completed!.flow.status).toBe('cancelled')
+    expect(completed!.flow.endedAt).toBe(5000)
+    // Remaining steps should be cancelled
+    expect(completed!.flow.stateJson?.steps[1]?.status).toBe('cancelled')
+  })
+
+  test('returns accepted=false for already completed flow', async () => {
+    const startResult = await startManagedAutonomyFlow({
+      trigger: 'scheduled-task',
+      goal: 'Already done',
+      steps: [{ name: 'only', prompt: 'Do it' }],
+      rootDir: tempDir,
+      nowMs: 1000,
+    })
+    const flowId = startResult!.flow.flowId
+    const stepId = startResult!.nextStep!.step.stepId
+
+    await queueManagedAutonomyFlowStepRun({
+      flowId,
+      stepId,
+      stepIndex: 0,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 2000,
+    })
+    await markManagedAutonomyFlowStepRunning({
+      flowId,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 3000,
+    })
+    await markManagedAutonomyFlowStepCompleted({
+      flowId,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 4000,
+    })
+
+    const cancelResult = await requestManagedAutonomyFlowCancel({
+      flowId,
+      rootDir: tempDir,
+      nowMs: 5000,
+    })
+    expect(cancelResult!.accepted).toBe(false)
+  })
+
+  test('returns null for unknown flowId', async () => {
+    const cancelResult = await requestManagedAutonomyFlowCancel({
+      flowId: 'nonexistent',
+      rootDir: tempDir,
+      nowMs: 1000,
+    })
+    expect(cancelResult).toBeNull()
+  })
+})
+
+describe('markManagedAutonomyFlowStepCancelled', () => {
+  test('cancels the step and all remaining steps', async () => {
+    const startResult = await startManagedAutonomyFlow({
+      trigger: 'scheduled-task',
+      goal: 'Cancel step',
+      steps: [
+        { name: 's1', prompt: 'p1' },
+        { name: 's2', prompt: 'p2' },
+        { name: 's3', prompt: 'p3' },
+      ],
+      rootDir: tempDir,
+      nowMs: 1000,
+    })
+    const flowId = startResult!.flow.flowId
+    const step0Id = startResult!.nextStep!.step.stepId
+
+    await queueManagedAutonomyFlowStepRun({
+      flowId,
+      stepId: step0Id,
+      stepIndex: 0,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 2000,
+    })
+
+    const cancelled = await markManagedAutonomyFlowStepCancelled({
+      flowId,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 3000,
+    })
+
+    expect(cancelled!.flow.status).toBe('cancelled')
+    expect(cancelled!.flow.endedAt).toBe(3000)
+    expect(cancelled!.flow.stateJson?.steps[0]?.status).toBe('cancelled')
+    expect(cancelled!.flow.stateJson?.steps[1]?.status).toBe('cancelled')
+    expect(cancelled!.flow.stateJson?.steps[2]?.status).toBe('cancelled')
+  })
+})
+
+describe('resumeManagedAutonomyFlow', () => {
+  test('returns unchanged flow when not in waiting status', async () => {
+    const startResult = await startManagedAutonomyFlow({
+      trigger: 'scheduled-task',
+      goal: 'Not waiting',
+      steps: TWO_STEPS,
+      rootDir: tempDir,
+      nowMs: 1000,
+    })
+    const flowId = startResult!.flow.flowId
+
+    const resumed = await resumeManagedAutonomyFlow({
+      flowId,
+      rootDir: tempDir,
+      nowMs: 2000,
+    })
+
+    // Flow is queued, not waiting, so resume should not change status
+    expect(resumed!.flow.status).toBe('queued')
+  })
+
+  test('cancels when cancel was requested during wait', async () => {
+    const startResult = await startManagedAutonomyFlow({
+      trigger: 'scheduled-task',
+      goal: 'Cancel during wait',
+      steps: STEPS_WITH_WAIT,
+      rootDir: tempDir,
+      nowMs: 1000,
+    })
+    const flowId = startResult!.flow.flowId
+    expect(startResult!.flow.status).toBe('waiting')
+
+    // Request cancel while waiting
+    await requestManagedAutonomyFlowCancel({
+      flowId,
+      rootDir: tempDir,
+      nowMs: 2000,
+    })
+
+    // The flow should already be cancelled since it's not running
+    const flow = await getAutonomyFlowById(flowId, tempDir)
+    expect(flow!.status).toBe('cancelled')
+  })
+})
+
+describe('getAutonomyFlowById', () => {
+  test('returns null when flow does not exist', async () => {
+    const flow = await getAutonomyFlowById('nonexistent', tempDir)
+    expect(flow).toBeNull()
+  })
+
+  test('returns the flow when it exists', async () => {
+    const startResult = await startManagedAutonomyFlow({
+      trigger: 'scheduled-task',
+      goal: 'Find me',
+      steps: TWO_STEPS,
+      rootDir: tempDir,
+      nowMs: 1000,
+    })
+    const flowId = startResult!.flow.flowId
+
+    const found = await getAutonomyFlowById(flowId, tempDir)
+    expect(found).not.toBeNull()
+    expect(found!.flowId).toBe(flowId)
+    expect(found!.goal).toBe('Find me')
+  })
+})
+
+describe('queueManagedAutonomyFlowStepRun edge cases', () => {
+  test('returns null for unknown flowId', async () => {
+    const result = await queueManagedAutonomyFlowStepRun({
+      flowId: 'nonexistent',
+      stepId: 'step-0',
+      stepIndex: 0,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 1000,
+    })
+    expect(result).toBeNull()
+  })
+
+  test('returns unchanged flow for mismatched stepId', async () => {
+    const startResult = await startManagedAutonomyFlow({
+      trigger: 'scheduled-task',
+      goal: 'Mismatch test',
+      steps: TWO_STEPS,
+      rootDir: tempDir,
+      nowMs: 1000,
+    })
+    const flowId = startResult!.flow.flowId
+
+    const result = await queueManagedAutonomyFlowStepRun({
+      flowId,
+      stepId: 'wrong-step-id',
+      stepIndex: 0,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 2000,
+    })
+
+    // Should return the flow unchanged (still pending, not queued step)
+    expect(result).not.toBeNull()
+    expect(result!.stateJson?.steps[0]?.status).toBe('pending')
+  })
+})
+
+describe('markManagedAutonomyFlowStepRunning edge cases', () => {
+  test('returns null for unknown flowId', async () => {
+    const result = await markManagedAutonomyFlowStepRunning({
+      flowId: 'nonexistent',
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 1000,
+    })
+    expect(result).toBeNull()
+  })
+})
+
+describe('markManagedAutonomyFlowStepFailed with cancelRequestedAt', () => {
+  test('marks flow as cancelled (not failed) when cancel was requested', async () => {
+    const startResult = await startManagedAutonomyFlow({
+      trigger: 'scheduled-task',
+      goal: 'Fail after cancel',
+      steps: TWO_STEPS,
+      rootDir: tempDir,
+      nowMs: 1000,
+    })
+    const flowId = startResult!.flow.flowId
+    const step0Id = startResult!.nextStep!.step.stepId
+
+    await queueManagedAutonomyFlowStepRun({
+      flowId,
+      stepId: step0Id,
+      stepIndex: 0,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 2000,
+    })
+    await markManagedAutonomyFlowStepRunning({
+      flowId,
+      runId: 'run-0',
+      rootDir: tempDir,
+      nowMs: 3000,
+    })
+
+    // Request cancel while running
+    await requestManagedAutonomyFlowCancel({
+      flowId,
+      rootDir: tempDir,
+      nowMs: 4000,
+    })
+
+    // Step fails — should result in cancelled (because cancel was requested)
+    const result = await markManagedAutonomyFlowStepFailed({
+      flowId,
+      runId: 'run-0',
+      error: 'step error',
+      rootDir: tempDir,
+      nowMs: 5000,
+    })
+
+    expect(result!.flow.status).toBe('cancelled')
+    expect(result!.flow.lastError).toBe('step error')
+  })
+})
+
+describe('formatAutonomyFlowsStatus', () => {
+  test('formats counts for various statuses', () => {
+    const flows: AutonomyFlowRecord[] = [
+      makeMinimalFlow({ status: 'queued' }),
+      makeMinimalFlow({ status: 'running' }),
+      makeMinimalFlow({ status: 'succeeded' }),
+      makeMinimalFlow({ status: 'succeeded' }),
+      makeMinimalFlow({ status: 'failed' }),
+    ]
+
+    const status = formatAutonomyFlowsStatus(flows)
+    expect(status).toContain('Autonomy flows: 5')
+    expect(status).toContain('Queued: 1')
+    expect(status).toContain('Running: 1')
+    expect(status).toContain('Succeeded: 2')
+    expect(status).toContain('Failed: 1')
+    expect(status).toContain('Cancelled: 0')
+  })
+})
+
+describe('formatAutonomyFlowsList', () => {
+  test('returns message when no flows', () => {
+    const list = formatAutonomyFlowsList([])
+    expect(list).toBe('No autonomy flows recorded.')
+  })
+
+  test('formats flow list with source and step info', () => {
+    const flows: AutonomyFlowRecord[] = [
+      makeMinimalFlow({
+        flowId: 'flow-abc',
+        goal: 'Test goal',
+        currentStep: 'gather',
+        sourceLabel: 'nightly',
+        revision: 3,
+        runCount: 2,
+        status: 'queued',
+      }),
+    ]
+
+    const list = formatAutonomyFlowsList(flows)
+    expect(list).toContain('flow-abc')
+    expect(list).toContain('nightly')
+    expect(list).toContain('step=gather')
+    expect(list).toContain('rev=3')
+    expect(list).toContain('goal=Test goal')
+    expect(list).toContain('runs=2')
+  })
+
+  test('respects limit parameter', () => {
+    const flows = Array.from({ length: 5 }, (_, i) =>
+      makeMinimalFlow({ flowId: `flow-${i}` }),
+    )
+
+    const list = formatAutonomyFlowsList(flows, 2)
+    expect(list).toContain('flow-0')
+    expect(list).toContain('flow-1')
+    expect(list).not.toContain('flow-2')
+  })
+
+  test('shows waiting info for waiting flows', () => {
+    const flows: AutonomyFlowRecord[] = [
+      makeMinimalFlow({
+        status: 'waiting',
+        waitJson: {
+          reason: 'manual-review',
+          stepId: 's1',
+          stepName: 'review',
+          stepIndex: 1,
+        },
+      }),
+    ]
+
+    const list = formatAutonomyFlowsList(flows)
+    expect(list).toContain('waiting=manual-review')
+  })
+})
+
+describe('formatAutonomyFlowDetail', () => {
+  test('returns not found for null', () => {
+    expect(formatAutonomyFlowDetail(null)).toBe('Autonomy flow not found.')
+    expect(formatAutonomyFlowDetail(undefined)).toBe('Autonomy flow not found.')
+  })
+
+  test('formats full flow detail with steps', () => {
+    const flow = makeMinimalFlow({
+      flowId: 'detail-flow',
+      flowKey: 'managed:scheduled-task:src',
+      revision: 2,
+      trigger: 'scheduled-task',
+      status: 'running',
+      goal: 'Detail test',
+      sourceLabel: 'nightly',
+      ownerKey: 'main-thread',
+      currentStep: 'gather',
+      runCount: 1,
+      latestRunId: 'run-0',
+      stateJson: {
+        currentStepIndex: 0,
+        steps: [
+          {
+            stepId: 's0',
+            name: 'gather',
+            prompt: 'Gather inputs',
+            status: 'running',
+            runId: 'run-0',
+          },
+          {
+            stepId: 's1',
+            name: 'draft',
+            prompt: 'Draft report',
+            status: 'pending',
+            waitFor: 'approval',
+          },
+        ],
+      },
+    })
+
+    const detail = formatAutonomyFlowDetail(flow)
+    expect(detail).toContain('Flow: detail-flow')
+    expect(detail).toContain('Key: managed:scheduled-task:src')
+    expect(detail).toContain('Mode: managed')
+    expect(detail).toContain('Revision: 2')
+    expect(detail).toContain('Status: running')
+    expect(detail).toContain('Goal: Detail test')
+    expect(detail).toContain('Source: nightly')
+    expect(detail).toContain('Current step: gather')
+    expect(detail).toContain('1. gather | running | run=run-0')
+    expect(detail).toContain('2. draft | pending | run=none | wait=approval')
+  })
+
+  test('includes error and blocked info', () => {
+    const flow = makeMinimalFlow({
+      status: 'failed',
+      lastError: 'step exploded',
+      blockedRunId: 'run-x',
+      blockedSummary: 'step exploded',
+    })
+
+    const detail = formatAutonomyFlowDetail(flow)
+    expect(detail).toContain('Error: step exploded')
+    expect(detail).toContain('Blocked run: run-x')
+    expect(detail).toContain('Blocked summary: step exploded')
+  })
+
+  test('includes cancel requested timestamp', () => {
+    const flow = makeMinimalFlow({
+      cancelRequestedAt: 99999,
+    })
+    const detail = formatAutonomyFlowDetail(flow)
+    expect(detail).toContain('Cancel requested:')
+  })
+})
+
+describe('concurrent startManagedAutonomyFlow calls', () => {
+  test('do not lose updates', async () => {
+    await Promise.all([
+      startManagedAutonomyFlow({
+        trigger: 'scheduled-task',
+        goal: 'Flow A',
+        steps: [{ name: 'a', prompt: 'A' }],
+        rootDir: tempDir,
+        sourceId: 'src-a',
+        nowMs: 1000,
+      }),
+      startManagedAutonomyFlow({
+        trigger: 'scheduled-task',
+        goal: 'Flow B',
+        steps: [{ name: 'b', prompt: 'B' }],
+        rootDir: tempDir,
+        sourceId: 'src-b',
+        nowMs: 1000,
+      }),
+    ])
+
+    const flows = await listAutonomyFlows(tempDir)
+    expect(flows).toHaveLength(2)
+    const goals = new Set(flows.map(f => f.goal))
+    expect(goals).toEqual(new Set(['Flow A', 'Flow B']))
+  })
+})
+
+// Helper to make minimal flow records for formatter tests
+function makeMinimalFlow(
+  overrides: Partial<AutonomyFlowRecord> = {},
+): AutonomyFlowRecord {
+  return {
+    flowId: 'flow-0',
+    flowKey: 'managed:scheduled-task:src',
+    syncMode: 'managed',
+    ownerKey: DEFAULT_AUTONOMY_OWNER_KEY,
+    revision: 1,
+    trigger: 'scheduled-task',
+    status: 'queued',
+    goal: 'Default goal',
+    rootDir: '/tmp/test',
+    currentDir: '/tmp/test',
+    runCount: 0,
+    createdAt: 1000,
+    updatedAt: 2000,
+    ...overrides,
+  }
+}
diff --git a/src/utils/__tests__/autonomyPersistence.test.ts b/src/utils/__tests__/autonomyPersistence.test.ts
new file mode 100644
index 000000000..a265263ee
--- /dev/null
+++ b/src/utils/__tests__/autonomyPersistence.test.ts
@@ -0,0 +1,117 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { cleanupTempDir, createTempDir } from '../../../tests/mocks/file-system'
+
+// Mock the lockfile module so tests don't need real file locks
+mock.module('../lockfile.js', () => ({
+  lock: async (_file: string, _options?: unknown) => {
+    return async () => {}
+  },
+}))
+
+let tempDir = ''
+
+beforeEach(async () => {
+  tempDir = await createTempDir('autonomy-persistence-')
+})
+
+afterEach(async () => {
+  if (tempDir) {
+    await cleanupTempDir(tempDir)
+  }
+})
+
+describe('withAutonomyPersistenceLock', () => {
+  test('runs fn and returns its result', async () => {
+    const { withAutonomyPersistenceLock } = await import(
+      '../autonomyPersistence'
+    )
+    const result = await withAutonomyPersistenceLock(tempDir, async () => {
+      return 42
+    })
+    expect(result).toBe(42)
+  })
+
+  test('creates the autonomy directory and lock file', async () => {
+    const { withAutonomyPersistenceLock } = await import(
+      '../autonomyPersistence'
+    )
+    await withAutonomyPersistenceLock(tempDir, async () => 'ok')
+
+    const autonomyDir = join(tempDir, '.claude', 'autonomy')
+    expect(existsSync(autonomyDir)).toBe(true)
+  })
+
+  test('propagates errors from the inner function', async () => {
+    const { withAutonomyPersistenceLock } = await import(
+      '../autonomyPersistence'
+    )
+    await expect(
+      withAutonomyPersistenceLock(tempDir, async () => {
+        throw new Error('inner failure')
+      }),
+    ).rejects.toThrow('inner failure')
+  })
+
+  test('serializes concurrent calls on the same rootDir', async () => {
+    const { withAutonomyPersistenceLock } = await import(
+      '../autonomyPersistence'
+    )
+    const order: number[] = []
+
+    const first = withAutonomyPersistenceLock(tempDir, async () => {
+      order.push(1)
+      // Simulate async work
+      await new Promise(resolve => setTimeout(resolve, 20))
+      order.push(2)
+      return 'first'
+    })
+
+    const second = withAutonomyPersistenceLock(tempDir, async () => {
+      order.push(3)
+      return 'second'
+    })
+
+    const [r1, r2] = await Promise.all([first, second])
+
+    expect(r1).toBe('first')
+    expect(r2).toBe('second')
+    // The second call must wait for the first to finish
+    expect(order).toEqual([1, 2, 3])
+  })
+
+  test('allows parallel calls on different rootDirs', async () => {
+    const { withAutonomyPersistenceLock } = await import(
+      '../autonomyPersistence'
+    )
+    const tempDir2 = await createTempDir('autonomy-persistence-2-')
+
+    try {
+      const order: string[] = []
+
+      const first = withAutonomyPersistenceLock(tempDir, async () => {
+        order.push('a-start')
+        await new Promise(resolve => setTimeout(resolve, 10))
+        order.push('a-end')
+        return 'a'
+      })
+
+      const second = withAutonomyPersistenceLock(tempDir2, async () => {
+        order.push('b-start')
+        await new Promise(resolve => setTimeout(resolve, 10))
+        order.push('b-end')
+        return 'b'
+      })
+
+      const [r1, r2] = await Promise.all([first, second])
+      expect(r1).toBe('a')
+      expect(r2).toBe('b')
+      // Both should start before either ends (parallel)
+      expect(order.indexOf('a-start')).toBeLessThan(order.indexOf('a-end'))
+      expect(order.indexOf('b-start')).toBeLessThan(order.indexOf('b-end'))
+    } finally {
+      await cleanupTempDir(tempDir2)
+    }
+  })
+})
diff --git a/src/utils/__tests__/autonomyRuns.test.ts b/src/utils/__tests__/autonomyRuns.test.ts
new file mode 100644
index 000000000..056083e48
--- /dev/null
+++ b/src/utils/__tests__/autonomyRuns.test.ts
@@ -0,0 +1,421 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { mkdir, writeFile } from 'fs/promises'
+import { join } from 'path'
+import {
+  resetStateForTests,
+  setCwdState,
+  setOriginalCwd,
+  setProjectRoot,
+} from '../../bootstrap/state'
+import {
+  formatAutonomyRunsList,
+  formatAutonomyRunsStatus,
+  listAutonomyRuns,
+  createAutonomyQueuedPrompt,
+  createProactiveAutonomyCommands,
+  finalizeAutonomyRunCompleted,
+  markAutonomyRunCompleted,
+  markAutonomyRunFailed,
+  markAutonomyRunRunning,
+  recoverManagedAutonomyFlowPrompt,
+  resolveAutonomyRunsPath,
+  startManagedAutonomyFlowFromHeartbeatTask,
+} from '../autonomyRuns'
+import {
+  formatAutonomyFlowsList,
+  getAutonomyFlowById,
+  listAutonomyFlows,
+} from '../autonomyFlows'
+import {
+  AUTONOMY_DIR,
+  resetAutonomyAuthorityForTests,
+} from '../autonomyAuthority'
+import { resetCommandQueue } from '../messageQueueManager'
+import {
+  cleanupTempDir,
+  createTempDir,
+  createTempSubdir,
+  writeTempFile,
+} from '../../../tests/mocks/file-system'
+
+const AGENTS_REL = join(AUTONOMY_DIR, 'AGENTS.md')
+const HEARTBEAT_REL = join(AUTONOMY_DIR, 'HEARTBEAT.md')
+
+let tempDir = ''
+
+beforeEach(async () => {
+  tempDir = await createTempDir('autonomy-runs-')
+  resetStateForTests()
+  resetAutonomyAuthorityForTests()
+  resetCommandQueue()
+  setOriginalCwd(tempDir)
+  setProjectRoot(tempDir)
+})
+
+afterEach(async () => {
+  resetStateForTests()
+  resetAutonomyAuthorityForTests()
+  resetCommandQueue()
+  if (tempDir) {
+    await cleanupTempDir(tempDir)
+  }
+})
+
+describe('autonomyRuns', () => {
+  test('createAutonomyQueuedPrompt records a queued automatic run and returns a prompt command', async () => {
+    const currentDir = await createTempSubdir(tempDir, 'nested')
+    await writeTempFile(tempDir, AGENTS_REL, 'root authority')
+
+    const command = await createAutonomyQueuedPrompt({
+      basePrompt: 'Review nightly report',
+      trigger: 'scheduled-task',
+      rootDir: tempDir,
+      currentDir,
+      sourceId: 'cron-1',
+      sourceLabel: 'nightly-report',
+      workload: 'cron',
+    })
+
+    const runs = await listAutonomyRuns(tempDir)
+    const flows = await listAutonomyFlows(tempDir)
+
+    expect(command).not.toBeNull()
+    expect(command!.mode).toBe('prompt')
+    expect(command!.isMeta).toBe(true)
+    expect(command!.autonomy?.trigger).toBe('scheduled-task')
+    expect(command!.autonomy?.sourceId).toBe('cron-1')
+    expect(command!.origin).toBeDefined()
+    expect(command!.value).toContain('root authority')
+    expect(runs).toHaveLength(1)
+    expect(runs[0]).toMatchObject({
+      runId: command!.autonomy?.runId,
+      runtime: 'automatic',
+      trigger: 'scheduled-task',
+      status: 'queued',
+      ownerKey: 'main-thread',
+      sourceId: 'cron-1',
+      sourceLabel: 'nightly-report',
+    })
+    expect(flows).toHaveLength(0)
+    expect(resolveAutonomyRunsPath(tempDir)).toContain('.claude')
+  })
+
+  test('createAutonomyQueuedPrompt defaults currentDir to the active cwd for nested authority', async () => {
+    const nestedDir = await createTempSubdir(tempDir, 'nested')
+    await writeTempFile(tempDir, AGENTS_REL, 'root authority')
+    await writeTempFile(nestedDir, AGENTS_REL, 'nested authority')
+    setOriginalCwd(nestedDir)
+    setCwdState(nestedDir)
+
+    const command = await createAutonomyQueuedPrompt({
+      basePrompt: '<tick>12:00:00</tick>',
+      trigger: 'proactive-tick',
+      rootDir: tempDir,
+    })
+
+    expect(command).not.toBeNull()
+    expect(command!.value).toContain('root authority')
+    expect(command!.value).toContain('nested authority')
+  })
+
+  test('markAutonomyRunRunning/completed/failed update persisted lifecycle state for plain runs', async () => {
+    const command = await createAutonomyQueuedPrompt({
+      basePrompt: '<tick>12:00:00</tick>',
+      trigger: 'proactive-tick',
+      rootDir: tempDir,
+      currentDir: tempDir,
+    })
+    expect(command).not.toBeNull()
+    const runId = command!.autonomy!.runId
+
+    await markAutonomyRunRunning(runId, tempDir, 100)
+    let runs = await listAutonomyRuns(tempDir)
+    expect(runs[0]).toMatchObject({
+      runId,
+      status: 'running',
+      startedAt: 100,
+    })
+
+    await markAutonomyRunCompleted(runId, tempDir, 200)
+    runs = await listAutonomyRuns(tempDir)
+    expect(runs[0]).toMatchObject({
+      runId,
+      status: 'completed',
+      endedAt: 200,
+    })
+
+    await markAutonomyRunFailed(runId, 'boom', tempDir, 300)
+    runs = await listAutonomyRuns(tempDir)
+    expect(runs[0]).toMatchObject({
+      runId,
+      status: 'failed',
+      endedAt: 300,
+      error: 'boom',
+    })
+  })
+
+  test('formatters produce readable status and run listings', async () => {
+    const first = await createAutonomyQueuedPrompt({
+      basePrompt: 'scheduled prompt',
+      trigger: 'scheduled-task',
+      rootDir: tempDir,
+      currentDir: tempDir,
+      sourceId: 'cron-1',
+      sourceLabel: 'nightly',
+    })
+    const second = await createAutonomyQueuedPrompt({
+      basePrompt: '<tick>12:00:00</tick>',
+      trigger: 'proactive-tick',
+      rootDir: tempDir,
+      currentDir: tempDir,
+    })
+
+    expect(first).not.toBeNull()
+    expect(second).not.toBeNull()
+    await markAutonomyRunRunning(first!.autonomy!.runId, tempDir, 100)
+    await markAutonomyRunCompleted(first!.autonomy!.runId, tempDir, 200)
+    await markAutonomyRunFailed(
+      second!.autonomy!.runId,
+      'stopped',
+      tempDir,
+      300,
+    )
+
+    const runs = await listAutonomyRuns(tempDir)
+    const status = formatAutonomyRunsStatus(runs)
+    const list = formatAutonomyRunsList(runs, 5)
+    const flows = await listAutonomyFlows(tempDir)
+    const flowList = formatAutonomyFlowsList(flows, 5)
+
+    expect(status).toContain('Autonomy runs: 2')
+    expect(status).toContain('Completed: 1')
+    expect(status).toContain('Failed: 1')
+    expect(list).toContain(first!.autonomy!.runId)
+    expect(list).toContain(second!.autonomy!.runId)
+    expect(list).toContain('nightly')
+    expect(list).toContain('stopped')
+    expect(flowList).toBe('No autonomy flows recorded.')
+  })
+
+  test('same-process concurrent run creation does not lose updates', async () => {
+    await Promise.all([
+      createAutonomyQueuedPrompt({
+        basePrompt: 'scheduled one',
+        trigger: 'scheduled-task',
+        rootDir: tempDir,
+        currentDir: tempDir,
+        sourceId: 'cron-1',
+      }),
+      createAutonomyQueuedPrompt({
+        basePrompt: 'scheduled two',
+        trigger: 'scheduled-task',
+        rootDir: tempDir,
+        currentDir: tempDir,
+        sourceId: 'cron-2',
+      }),
+    ])
+
+    const runs = await listAutonomyRuns(tempDir)
+
+    expect(runs).toHaveLength(2)
+    expect(new Set(runs.map(run => run.sourceId))).toEqual(
+      new Set(['cron-1', 'cron-2']),
+    )
+  })
+
+  test('listAutonomyRuns keeps older persisted records by normalizing missing runtime and owner metadata', async () => {
+    const runsPath = resolveAutonomyRunsPath(tempDir)
+    await mkdir(join(tempDir, '.claude', 'autonomy'), { recursive: true })
+    await writeFile(
+      runsPath,
+      `${JSON.stringify(
+        {
+          runs: [
+            {
+              runId: 'legacy-run',
+              trigger: 'scheduled-task',
+              status: 'completed',
+              rootDir: tempDir,
+              promptPreview: 'legacy prompt',
+              createdAt: 123,
+            },
+          ],
+        },
+        null,
+        2,
+      )}\n`,
+      'utf-8',
+    )
+
+    const [legacy] = await listAutonomyRuns(tempDir)
+
+    expect(legacy).toMatchObject({
+      runId: 'legacy-run',
+      runtime: 'automatic',
+      ownerKey: 'main-thread',
+      currentDir: tempDir,
+      status: 'completed',
+    })
+  })
+
+  test('createAutonomyQueuedPrompt does not consume heartbeat tasks or create runs when shouldCreate rejects commit', async () => {
+    await writeTempFile(
+      tempDir,
+      HEARTBEAT_REL,
+      [
+        'tasks:',
+        '  - name: inbox',
+        '    interval: 30m',
+        '    prompt: "Check inbox"',
+      ].join('\n'),
+    )
+
+    const skipped = await createAutonomyQueuedPrompt({
+      basePrompt: '<tick>12:00:00</tick>',
+      trigger: 'proactive-tick',
+      rootDir: tempDir,
+      currentDir: tempDir,
+      shouldCreate: () => false,
+    })
+    const committed = await createAutonomyQueuedPrompt({
+      basePrompt: '<tick>12:01:00</tick>',
+      trigger: 'proactive-tick',
+      rootDir: tempDir,
+      currentDir: tempDir,
+    })
+
+    const runs = await listAutonomyRuns(tempDir)
+
+    expect(skipped).toBeNull()
+    expect(committed).not.toBeNull()
+    expect(committed!.value).toContain('Due HEARTBEAT.md tasks:')
+    expect(runs).toHaveLength(1)
+  })
+
+  test('createProactiveAutonomyCommands queues one managed flow step command per due HEARTBEAT flow', async () => {
+    await writeTempFile(
+      tempDir,
+      HEARTBEAT_REL,
+      [
+        'tasks:',
+        '  - name: inbox',
+        '    interval: 30m',
+        '    prompt: "Check inbox"',
+        '  - name: weekly-report',
+        '    interval: 7d',
+        '    prompt: "Ship the weekly report"',
+        '    steps:',
+        '      - name: gather',
+        '        prompt: "Gather weekly inputs"',
+        '      - name: draft',
+        '        prompt: "Draft the weekly report"',
+      ].join('\n'),
+    )
+
+    const commands = await createProactiveAutonomyCommands({
+      basePrompt: '<tick>12:00:00</tick>',
+      rootDir: tempDir,
+      currentDir: tempDir,
+    })
+
+    const runs = await listAutonomyRuns(tempDir)
+    const flows = await listAutonomyFlows(tempDir)
+
+    expect(commands).toHaveLength(2)
+    expect(commands[0]!.autonomy?.trigger).toBe('proactive-tick')
+    expect(commands[0]!.value).toContain('- inbox (30m): Check inbox')
+    expect(commands[1]!.autonomy?.trigger).toBe('managed-flow-step')
+    expect(commands[1]!.value).toContain(
+      'This is step 1/2 of the managed autonomy flow',
+    )
+    expect(runs).toHaveLength(2)
+    expect(flows).toHaveLength(1)
+    expect(flows[0]).toMatchObject({
+      status: 'queued',
+      currentStep: 'gather',
+      goal: 'Ship the weekly report',
+    })
+  })
+
+  test('finalizeAutonomyRunCompleted advances managed flows to the next queued step', async () => {
+    const command = await startManagedAutonomyFlowFromHeartbeatTask({
+      task: {
+        name: 'weekly-report',
+        interval: '7d',
+        prompt: 'Ship the weekly report',
+        steps: [
+          {
+            name: 'gather',
+            prompt: 'Gather weekly inputs',
+          },
+          {
+            name: 'draft',
+            prompt: 'Draft the weekly report',
+          },
+        ],
+      },
+      rootDir: tempDir,
+      currentDir: tempDir,
+    })
+
+    expect(command).not.toBeNull()
+    await markAutonomyRunRunning(command!.autonomy!.runId, tempDir, 100)
+
+    const nextCommands = await finalizeAutonomyRunCompleted({
+      runId: command!.autonomy!.runId,
+      rootDir: tempDir,
+      currentDir: tempDir,
+    })
+
+    const runs = await listAutonomyRuns(tempDir)
+    const [flow] = await listAutonomyFlows(tempDir)
+    const detail = await getAutonomyFlowById(flow!.flowId, tempDir)
+
+    expect(nextCommands).toHaveLength(1)
+    expect(nextCommands[0]!.autonomy?.trigger).toBe('managed-flow-step')
+    expect(nextCommands[0]!.value).toContain('Current step: draft')
+    expect(runs).toHaveLength(2)
+    expect(flow).toMatchObject({
+      status: 'queued',
+      currentStep: 'draft',
+      runCount: 2,
+    })
+    expect(detail?.stateJson?.steps.map(step => step.status)).toEqual([
+      'completed',
+      'queued',
+    ])
+  })
+
+  test('recoverManagedAutonomyFlowPrompt rehydrates a queued managed step with the same run id', async () => {
+    const command = await startManagedAutonomyFlowFromHeartbeatTask({
+      task: {
+        name: 'weekly-report',
+        interval: '7d',
+        prompt: 'Ship the weekly report',
+        steps: [
+          {
+            name: 'gather',
+            prompt: 'Gather weekly inputs',
+          },
+          {
+            name: 'draft',
+            prompt: 'Draft the weekly report',
+          },
+        ],
+      },
+      rootDir: tempDir,
+      currentDir: tempDir,
+    })
+
+    const [flow] = await listAutonomyFlows(tempDir)
+    const recovered = await recoverManagedAutonomyFlowPrompt({
+      flowId: flow!.flowId,
+      rootDir: tempDir,
+      currentDir: tempDir,
+    })
+
+    expect(recovered).not.toBeNull()
+    expect(recovered!.autonomy?.runId).toBe(command!.autonomy?.runId)
+    expect(recovered!.autonomy?.flowId).toBe(flow!.flowId)
+  })
+})
diff --git a/src/utils/__tests__/cronScheduler.baseline.test.ts b/src/utils/__tests__/cronScheduler.baseline.test.ts
new file mode 100644
index 000000000..696510337
--- /dev/null
+++ b/src/utils/__tests__/cronScheduler.baseline.test.ts
@@ -0,0 +1,79 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  buildMissedTaskNotification,
+  isRecurringTaskAged,
+} from '../cronScheduler'
+
+describe('cronScheduler baseline helpers', () => {
+  test('isRecurringTaskAged returns false when maxAgeMs is zero', () => {
+    expect(
+      isRecurringTaskAged(
+        { id: 'a', cron: '* * * * *', prompt: 'x', createdAt: 0, recurring: true },
+        10_000,
+        0,
+      ),
+    ).toBe(false)
+  })
+
+  test('isRecurringTaskAged only ages recurring non-permanent tasks', () => {
+    expect(
+      isRecurringTaskAged(
+        { id: 'a', cron: '* * * * *', prompt: 'x', createdAt: 0 },
+        10_000,
+        100,
+      ),
+    ).toBe(false)
+
+    expect(
+      isRecurringTaskAged(
+        {
+          id: 'b',
+          cron: '* * * * *',
+          prompt: 'x',
+          createdAt: 0,
+          recurring: true,
+          permanent: true,
+        },
+        10_000,
+        100,
+      ),
+    ).toBe(false)
+
+    expect(
+      isRecurringTaskAged(
+        { id: 'c', cron: '* * * * *', prompt: 'x', createdAt: 0, recurring: true },
+        10_000,
+        100,
+      ),
+    ).toBe(true)
+  })
+
+  test('buildMissedTaskNotification preserves AskUserQuestion safety instruction', () => {
+    const msg = buildMissedTaskNotification([
+      {
+        id: 'a1b2c3d4',
+        cron: '* * * * *',
+        prompt: 'check deployment',
+        createdAt: new Date('2026-04-12T10:00:00Z').getTime(),
+      },
+    ])
+
+    expect(msg).toContain('AskUserQuestion')
+    expect(msg).toContain('Do NOT execute this prompt yet')
+    expect(msg).toContain('check deployment')
+  })
+
+  test('buildMissedTaskNotification widens the code fence when the prompt contains backticks', () => {
+    const msg = buildMissedTaskNotification([
+      {
+        id: 'z9y8x7w6',
+        cron: '* * * * *',
+        prompt: 'run ```dangerous``` only if approved',
+        createdAt: new Date('2026-04-12T10:00:00Z').getTime(),
+      },
+    ])
+
+    expect(msg).toContain('````')
+    expect(msg).toContain('run ```dangerous``` only if approved')
+  })
+})
diff --git a/src/utils/__tests__/cronTasks.baseline.test.ts b/src/utils/__tests__/cronTasks.baseline.test.ts
new file mode 100644
index 000000000..1acfb993c
--- /dev/null
+++ b/src/utils/__tests__/cronTasks.baseline.test.ts
@@ -0,0 +1,203 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import {
+  getSessionCronTasks,
+  resetStateForTests,
+  setOriginalCwd,
+  setProjectRoot,
+} from '../../bootstrap/state'
+import {
+  addCronTask,
+  findMissedTasks,
+  getCronFilePath,
+  hasCronTasksSync,
+  listAllCronTasks,
+  markCronTasksFired,
+  nextCronRunMs,
+  oneShotJitteredNextCronRunMs,
+  readCronTasks,
+  removeCronTasks,
+  writeCronTasks,
+} from '../cronTasks'
+import { cleanupTempDir, createTempDir } from '../../../tests/mocks/file-system'
+
+let tempDir = ''
+
+beforeEach(async () => {
+  tempDir = await createTempDir('cron-baseline-')
+  resetStateForTests()
+  setOriginalCwd(tempDir)
+  setProjectRoot(tempDir)
+})
+
+afterEach(async () => {
+  resetStateForTests()
+  if (tempDir) {
+    await cleanupTempDir(tempDir)
+  }
+})
+
+describe('cronTasks baseline', () => {
+  test('session-only cron tasks remain in memory and do not create the cron file', async () => {
+    const id = await addCronTask('* * * * *', 'session-only prompt', true, false)
+
+    const tasks = await listAllCronTasks()
+
+    expect(id).toHaveLength(8)
+    expect(getSessionCronTasks()).toHaveLength(1)
+    expect(tasks).toHaveLength(1)
+    expect(tasks[0]).toMatchObject({
+      id,
+      prompt: 'session-only prompt',
+      durable: false,
+      recurring: true,
+    })
+    expect(existsSync(getCronFilePath())).toBe(false)
+  })
+
+  test('durable cron tasks are written to .claude/scheduled_tasks.json', async () => {
+    const id = await addCronTask('* * * * *', 'durable prompt', true, true)
+
+    const filePath = getCronFilePath()
+    const fileTasks = await readCronTasks()
+
+    expect(existsSync(filePath)).toBe(true)
+    expect(filePath).toBe(join(tempDir, '.claude', 'scheduled_tasks.json'))
+    expect(fileTasks).toHaveLength(1)
+    expect(fileTasks[0]).toMatchObject({
+      id,
+      prompt: 'durable prompt',
+      recurring: true,
+    })
+    expect(fileTasks[0].durable).toBeUndefined()
+  })
+
+  test('writeCronTasks strips runtime-only durable flags from disk', async () => {
+    await writeCronTasks([
+      {
+        id: 'abc12345',
+        cron: '* * * * *',
+        prompt: 'strip durable',
+        createdAt: 123,
+        recurring: true,
+        durable: false,
+      },
+    ])
+
+    const raw = await readFile(getCronFilePath(), 'utf-8')
+    expect(raw).not.toContain('"durable"')
+  })
+
+  test('hasCronTasksSync reflects whether the durable cron file has entries', async () => {
+    expect(hasCronTasksSync()).toBe(false)
+
+    await writeCronTasks([
+      {
+        id: 'sync0001',
+        cron: '* * * * *',
+        prompt: 'present',
+        createdAt: 1,
+      },
+    ])
+
+    expect(hasCronTasksSync()).toBe(true)
+  })
+
+  test('daemon-style listAllCronTasks(dir) excludes session-only tasks', async () => {
+    await addCronTask('* * * * *', 'session prompt', true, false)
+    const durableId = await addCronTask('* * * * *', 'durable prompt', true, true)
+
+    const sessionView = await listAllCronTasks()
+    const daemonView = await listAllCronTasks(tempDir)
+
+    expect(sessionView).toHaveLength(2)
+    expect(daemonView).toHaveLength(1)
+    expect(daemonView[0]).toMatchObject({
+      id: durableId,
+      prompt: 'durable prompt',
+    })
+  })
+
+  test('removeCronTasks without dir removes session-only tasks from memory', async () => {
+    const sessionId = await addCronTask('* * * * *', 'remove me', true, false)
+
+    await removeCronTasks([sessionId])
+
+    expect(getSessionCronTasks()).toHaveLength(0)
+    expect(await listAllCronTasks()).toHaveLength(0)
+  })
+
+  test('removeCronTasks with dir does not mutate session-only task storage', async () => {
+    const sessionId = await addCronTask('* * * * *', 'keep session task', true, false)
+    await addCronTask('* * * * *', 'durable prompt', true, true)
+
+    await removeCronTasks([sessionId], tempDir)
+
+    expect(getSessionCronTasks()).toHaveLength(1)
+    expect(getSessionCronTasks()[0]?.id).toBe(sessionId)
+  })
+
+  test('markCronTasksFired persists lastFiredAt for durable tasks', async () => {
+    await writeCronTasks([
+      {
+        id: 'fire0001',
+        cron: '* * * * *',
+        prompt: 'persist fired',
+        createdAt: 100,
+        recurring: true,
+      },
+    ])
+
+    await markCronTasksFired(['fire0001'], 123456789)
+
+    const tasks = await readCronTasks()
+    expect(tasks[0]?.lastFiredAt).toBe(123456789)
+  })
+
+  test('findMissedTasks returns tasks whose first scheduled run is in the past', () => {
+    const nowMs = new Date('2026-04-12T10:10:00').getTime()
+    const tasks = findMissedTasks(
+      [
+        {
+          id: 'missed01',
+          cron: '* * * * *',
+          prompt: 'old task',
+          createdAt: new Date('2026-04-12T10:00:00').getTime(),
+        },
+        {
+          id: 'future01',
+          cron: '59 23 31 12 *',
+          prompt: 'far future',
+          createdAt: nowMs,
+        },
+      ],
+      nowMs,
+    )
+
+    expect(tasks.map(t => t.id)).toEqual(['missed01'])
+  })
+
+  test('nextCronRunMs returns null for invalid cron expressions', () => {
+    expect(nextCronRunMs('invalid cron', Date.now())).toBeNull()
+  })
+
+  test('oneShotJitteredNextCronRunMs never returns a time earlier than fromMs', () => {
+    const fromMs = new Date('2026-04-12T10:59:50').getTime()
+    const next = oneShotJitteredNextCronRunMs('0 11 * * *', fromMs, '00000000')
+
+    expect(next).not.toBeNull()
+    expect(next!).toBeGreaterThanOrEqual(fromMs)
+  })
+
+  test('jitteredNextCronRunMs returns the exact next fire time when no second match exists in range', () => {
+    const fromMs = new Date('2026-04-12T10:00:00').getTime()
+    const exact = nextCronRunMs('0 0 29 2 *', fromMs)
+    const jittered = oneShotJitteredNextCronRunMs('0 0 29 2 *', fromMs, '89abcdef')
+
+    expect(exact).not.toBeNull()
+    expect(jittered).not.toBeNull()
+    expect(jittered!).toBeGreaterThanOrEqual(fromMs)
+  })
+})
diff --git a/src/utils/__tests__/language.test.ts b/src/utils/__tests__/language.test.ts
new file mode 100644
index 000000000..cdf31cad5
--- /dev/null
+++ b/src/utils/__tests__/language.test.ts
@@ -0,0 +1,82 @@
+import { describe, test, expect, mock } from 'bun:test'
+
+// Mock dependencies before importing the module under test
+let mockPreferredLanguage: string | undefined
+let mockSystemLocale: string | undefined
+
+mock.module('src/utils/config.js', () => ({
+  getGlobalConfig: () => ({
+    preferredLanguage: mockPreferredLanguage,
+  }),
+}))
+
+mock.module('src/utils/intl.js', () => ({
+  getSystemLocaleLanguage: () => mockSystemLocale,
+}))
+
+const { getResolvedLanguage, getLanguageDisplayName } = await import(
+  'src/utils/language.js'
+)
+
+describe('getResolvedLanguage', () => {
+  test('returns en when config is explicitly en', () => {
+    mockPreferredLanguage = 'en'
+    mockSystemLocale = 'zh'
+    expect(getResolvedLanguage()).toBe('en')
+  })
+
+  test('returns zh when config is explicitly zh', () => {
+    mockPreferredLanguage = 'zh'
+    mockSystemLocale = 'en'
+    expect(getResolvedLanguage()).toBe('zh')
+  })
+
+  test('falls back to system locale zh when config is auto', () => {
+    mockPreferredLanguage = 'auto'
+    mockSystemLocale = 'zh'
+    expect(getResolvedLanguage()).toBe('zh')
+  })
+
+  test('falls back to en when config is auto and system locale is not zh', () => {
+    mockPreferredLanguage = 'auto'
+    mockSystemLocale = 'en'
+    expect(getResolvedLanguage()).toBe('en')
+  })
+
+  test('falls back to en when config is auto and system locale is undefined', () => {
+    mockPreferredLanguage = 'auto'
+    mockSystemLocale = undefined
+    expect(getResolvedLanguage()).toBe('en')
+  })
+
+  test('falls back to auto behavior when config preferredLanguage is undefined', () => {
+    mockPreferredLanguage = undefined
+    mockSystemLocale = 'zh'
+    expect(getResolvedLanguage()).toBe('zh')
+  })
+
+  test('defaults to en when both config and locale are undefined', () => {
+    mockPreferredLanguage = undefined
+    mockSystemLocale = undefined
+    expect(getResolvedLanguage()).toBe('en')
+  })
+})
+
+describe('getLanguageDisplayName', () => {
+  test('returns Auto (follow system) for auto', () => {
+    expect(getLanguageDisplayName('auto')).toBe('Auto (follow system)')
+  })
+
+  test('returns English for en', () => {
+    expect(getLanguageDisplayName('en')).toBe('English')
+  })
+
+  test('returns 中文 for zh', () => {
+    expect(getLanguageDisplayName('zh')).toBe('中文')
+  })
+
+  test('returns the input string for unknown language codes', () => {
+    expect(getLanguageDisplayName('fr')).toBe('fr')
+    expect(getLanguageDisplayName('unknown')).toBe('unknown')
+  })
+})
diff --git a/src/utils/__tests__/pipeMuteState.test.ts b/src/utils/__tests__/pipeMuteState.test.ts
new file mode 100644
index 000000000..0ab154d1c
--- /dev/null
+++ b/src/utils/__tests__/pipeMuteState.test.ts
@@ -0,0 +1,124 @@
+import { describe, test, expect, beforeEach } from 'bun:test'
+import {
+  setMasterMutedPipes,
+  isMasterPipeMuted,
+  removeMasterPipeMute,
+  clearMasterMutedPipes,
+  addSendOverride,
+  removeSendOverride,
+  hasSendOverride,
+  clearSendOverrides,
+} from '../pipeMuteState.js'
+
+describe('setMasterMutedPipes', () => {
+  beforeEach(() => {
+    clearMasterMutedPipes()
+    clearSendOverrides()
+  })
+
+  test('sets muted pipes from iterable', () => {
+    setMasterMutedPipes(['pipe-a', 'pipe-b'])
+    expect(isMasterPipeMuted('pipe-a')).toBe(true)
+    expect(isMasterPipeMuted('pipe-b')).toBe(true)
+    expect(isMasterPipeMuted('pipe-c')).toBe(false)
+  })
+
+  test('replaces previous muted set', () => {
+    setMasterMutedPipes(['pipe-a'])
+    setMasterMutedPipes(['pipe-b'])
+    expect(isMasterPipeMuted('pipe-a')).toBe(false)
+    expect(isMasterPipeMuted('pipe-b')).toBe(true)
+  })
+})
+
+describe('isMasterPipeMuted', () => {
+  beforeEach(() => {
+    clearMasterMutedPipes()
+  })
+
+  test('returns false for unknown pipe', () => {
+    expect(isMasterPipeMuted('unknown')).toBe(false)
+  })
+})
+
+describe('removeMasterPipeMute', () => {
+  beforeEach(() => {
+    clearMasterMutedPipes()
+  })
+
+  test('removes a single muted pipe', () => {
+    setMasterMutedPipes(['pipe-a', 'pipe-b'])
+    removeMasterPipeMute('pipe-a')
+    expect(isMasterPipeMuted('pipe-a')).toBe(false)
+    expect(isMasterPipeMuted('pipe-b')).toBe(true)
+  })
+
+  test('no-ops for non-existent pipe', () => {
+    removeMasterPipeMute('nonexistent')
+    expect(isMasterPipeMuted('nonexistent')).toBe(false)
+  })
+})
+
+describe('clearMasterMutedPipes', () => {
+  test('clears all muted pipes', () => {
+    setMasterMutedPipes(['pipe-a', 'pipe-b', 'pipe-c'])
+    clearMasterMutedPipes()
+    expect(isMasterPipeMuted('pipe-a')).toBe(false)
+    expect(isMasterPipeMuted('pipe-b')).toBe(false)
+    expect(isMasterPipeMuted('pipe-c')).toBe(false)
+  })
+})
+
+describe('addSendOverride', () => {
+  beforeEach(() => {
+    clearSendOverrides()
+  })
+
+  test('adds a send override', () => {
+    addSendOverride('pipe-x')
+    expect(hasSendOverride('pipe-x')).toBe(true)
+  })
+
+  test('adding same override twice is idempotent', () => {
+    addSendOverride('pipe-x')
+    addSendOverride('pipe-x')
+    expect(hasSendOverride('pipe-x')).toBe(true)
+  })
+})
+
+describe('removeSendOverride', () => {
+  beforeEach(() => {
+    clearSendOverrides()
+  })
+
+  test('removes a send override', () => {
+    addSendOverride('pipe-x')
+    removeSendOverride('pipe-x')
+    expect(hasSendOverride('pipe-x')).toBe(false)
+  })
+
+  test('no-ops for non-existent override', () => {
+    removeSendOverride('nonexistent')
+    expect(hasSendOverride('nonexistent')).toBe(false)
+  })
+})
+
+describe('hasSendOverride', () => {
+  beforeEach(() => {
+    clearSendOverrides()
+  })
+
+  test('returns false when no overrides set', () => {
+    expect(hasSendOverride('pipe-x')).toBe(false)
+  })
+})
+
+describe('clearSendOverrides', () => {
+  test('clears all send overrides', () => {
+    addSendOverride('pipe-a')
+    addSendOverride('pipe-b')
+    clearSendOverrides()
+    expect(hasSendOverride('pipe-a')).toBe(false)
+    expect(hasSendOverride('pipe-b')).toBe(false)
+  })
+})
diff --git a/src/utils/__tests__/taskSummary.test.ts b/src/utils/__tests__/taskSummary.test.ts
new file mode 100644
index 000000000..b3f2ea63f
--- /dev/null
+++ b/src/utils/__tests__/taskSummary.test.ts
@@ -0,0 +1,93 @@
+/**
+ * Tests for src/utils/taskSummary.ts
+ *
+ * Covers: shouldGenerateTaskSummary, maybeGenerateTaskSummary
+ *
+ * Note: bun:bundle's feature() is a compile-time construct and cannot be
+ * trivially mocked at test time. We test maybeGenerateTaskSummary (which
+ * is called unconditionally) and the rate-limit behavior indirectly.
+ */
+import { describe, expect, test, mock, beforeEach } from 'bun:test'
+
+// ─── mocks ──────────────────────────────────────────────────────────────────
+
+let _updateCalls: any[] = []
+
+mock.module('bun:bundle', () => ({
+  feature: (_name: string) => false,
+}))
+
+mock.module('../concurrentSessions.js', () => ({
+  isBgSession: () => false,
+  updateSessionActivity: async (data: any) => {
+    _updateCalls.push(data)
+  },
+}))
+
+mock.module('../debug.js', () => ({
+  logForDebugging: () => {},
+}))
+
+// ─── import after mocks ─────────────────────────────────────────────────────
+
+const { shouldGenerateTaskSummary, maybeGenerateTaskSummary } = await import(
+  '../taskSummary.js'
+)
+
+// ─── tests ──────────────────────────────────────────────────────────────────
+
+beforeEach(() => {
+  _updateCalls = []
+})
+
+describe('shouldGenerateTaskSummary', () => {
+  test('returns false when feature is disabled', () => {
+    // bun:bundle feature mock returns false
+    expect(shouldGenerateTaskSummary()).toBe(false)
+  })
+})
+
+describe('maybeGenerateTaskSummary', () => {
+  test('does not throw with empty messages', () => {
+    expect(() =>
+      maybeGenerateTaskSummary({ forkContextMessages: [] }),
+    ).not.toThrow()
+  })
+
+  test('does not throw with undefined messages', () => {
+    expect(() => maybeGenerateTaskSummary({})).not.toThrow()
+  })
+
+  test('does not throw with assistant message containing tool_use', () => {
+    expect(() =>
+      maybeGenerateTaskSummary({
+        forkContextMessages: [
+          {
+            type: 'assistant',
+            message: {
+              content: [
+                { type: 'text', text: 'Let me check' },
+                { type: 'tool_use', name: 'bash' },
+              ],
+            },
+          },
+        ],
+      }),
+    ).not.toThrow()
+  })
+
+  test('does not throw with non-array content', () => {
+    expect(() =>
+      maybeGenerateTaskSummary({
+        forkContextMessages: [
+          {
+            type: 'assistant',
+            message: {
+              content: 'plain text response',
+            },
+          },
+        ],
+      }),
+    ).not.toThrow()
+  })
+})
diff --git a/src/utils/autonomyAuthority.ts b/src/utils/autonomyAuthority.ts
new file mode 100644
index 000000000..aa790fe35
--- /dev/null
+++ b/src/utils/autonomyAuthority.ts
@@ -0,0 +1,522 @@
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  join,
+  relative,
+  resolve,
+} from 'node:path'
+import { getProjectRoot } from '../bootstrap/state.js'
+import { getCwd } from './cwd.js'
+import { getFsImplementation } from './fsOperations.js'
+import { normalizePathForConfigKey } from './path.js'
+
+export const AUTONOMY_DIR = join('.claude', 'autonomy')
+export const AUTONOMY_DIR_POSIX = '.claude/autonomy'
+export const AUTONOMY_AGENTS_FILENAME = 'AGENTS.md'
+export const AUTONOMY_HEARTBEAT_FILENAME = 'HEARTBEAT.md'
+export const AUTONOMY_AGENTS_PATH_POSIX = `${AUTONOMY_DIR_POSIX}/${AUTONOMY_AGENTS_FILENAME}`
+export const AUTONOMY_HEARTBEAT_PATH_POSIX = `${AUTONOMY_DIR_POSIX}/${AUTONOMY_HEARTBEAT_FILENAME}`
+
+export type HeartbeatAuthorityTask = {
+  name: string
+  interval: string
+  prompt: string
+  steps: HeartbeatAuthorityTaskStep[]
+}
+
+export type HeartbeatAuthorityTaskStep = {
+  name: string
+  prompt: string
+  waitFor?: string
+}
+
+export type AutonomyAuthorityFile = {
+  path: string
+  relativePath: string
+  content: string
+}
+
+export type AutonomyAuthoritySnapshot = {
+  rootDir: string
+  currentDir: string
+  agentsFiles: AutonomyAuthorityFile[]
+  agentsContent: string | null
+  heartbeatFile: AutonomyAuthorityFile | null
+  heartbeatContent: string | null
+  heartbeatTasks: HeartbeatAuthorityTask[]
+}
+
+type AutonomyAuthorityParams = {
+  rootDir?: string
+  currentDir?: string
+}
+
+export type AutonomyTriggerKind =
+  | 'proactive-tick'
+  | 'scheduled-task'
+  | 'managed-flow-step'
+
+export type PreparedAutonomyTurn = {
+  rootDir: string
+  currentDir: string
+  trigger: AutonomyTriggerKind
+  prompt: string
+  dueHeartbeatTasks: HeartbeatAuthorityTask[]
+  nowMs: number
+}
+
+const heartbeatTaskLastRunByKey = new Map<string, number>()
+
+function isPathWithinRoot(rootDir: string, currentDir: string): boolean {
+  const delta = relative(rootDir, currentDir)
+  return delta === '' || (!delta.startsWith('..') && !isAbsolute(delta))
+}
+
+function listAuthorityDirectories(
+  rootDir: string,
+  currentDir: string,
+): string[] {
+  const resolvedRoot = resolve(rootDir)
+  const resolvedCurrent = resolve(currentDir)
+  if (!isPathWithinRoot(resolvedRoot, resolvedCurrent)) {
+    return [resolvedRoot]
+  }
+
+  const dirs: string[] = []
+  let cursor = resolvedCurrent
+  for (;;) {
+    dirs.push(cursor)
+    if (cursor === resolvedRoot) {
+      break
+    }
+    const parent = dirname(cursor)
+    if (parent === cursor) {
+      break
+    }
+    cursor = parent
+  }
+  return dirs.reverse()
+}
+
+async function readAuthorityFile(
+  filePath: string,
+  rootDir: string,
+): Promise<AutonomyAuthorityFile | null> {
+  try {
+    const content = (await getFsImplementation().readFile(filePath, {
+      encoding: 'utf-8',
+    })) as string
+    const trimmed = content.trim()
+    if (!trimmed) {
+      return null
+    }
+    return {
+      path: filePath,
+      relativePath:
+        normalizePathForConfigKey(relative(rootDir, filePath)) ||
+        basename(filePath),
+      content: trimmed,
+    }
+  } catch {
+    return null
+  }
+}
+
+function mergeAgentsAuthority(files: AutonomyAuthorityFile[]): string | null {
+  if (files.length === 0) {
+    return null
+  }
+
+  return files
+    .map(file => `## ${file.relativePath}\n${file.content}`)
+    .join('\n\n')
+}
+
+export function parseHeartbeatAuthorityTasks(
+  content: string,
+): HeartbeatAuthorityTask[] {
+  const tasks: HeartbeatAuthorityTask[] = []
+  const lines = content.split('\n')
+  const getIndent = (line: string): number =>
+    line.length - line.trimStart().length
+  const parseScalar = (line: string, key: string): string =>
+    line
+      .replace(key, '')
+      .trim()
+      .replace(/^["']|["']$/g, '')
+
+  function parseSteps(
+    startIndex: number,
+    stepsIndent: number,
+  ): { steps: HeartbeatAuthorityTaskStep[]; nextIndex: number } {
+    const steps: HeartbeatAuthorityTaskStep[] = []
+    let index = startIndex
+
+    while (index < lines.length) {
+      const line = lines[index]!
+      const trimmed = line.trim()
+      const indent = getIndent(line)
+
+      if (!trimmed) {
+        index += 1
+        continue
+      }
+
+      if (indent <= stepsIndent) {
+        break
+      }
+
+      if (!trimmed.startsWith('- name:')) {
+        index += 1
+        continue
+      }
+
+      const stepIndent = indent
+      const name = parseScalar(trimmed, '- name:')
+      let prompt = ''
+      let waitFor: string | undefined
+      index += 1
+
+      while (index < lines.length) {
+        const nextLine = lines[index]!
+        const nextTrimmed = nextLine.trim()
+        const nextIndent = getIndent(nextLine)
+
+        if (!nextTrimmed) {
+          index += 1
+          continue
+        }
+
+        if (nextIndent <= stepIndent) {
+          break
+        }
+
+        if (nextTrimmed.startsWith('prompt:')) {
+          prompt = parseScalar(nextTrimmed, 'prompt:')
+        } else if (nextTrimmed.startsWith('wait_for:')) {
+          waitFor = parseScalar(nextTrimmed, 'wait_for:')
+        }
+
+        index += 1
+      }
+
+      if (name && prompt) {
+        steps.push({
+          name,
+          prompt,
+          ...(waitFor ? { waitFor } : {}),
+        })
+      }
+    }
+
+    return { steps, nextIndex: index }
+  }
+
+  const tasksLineIndex = lines.findIndex(line => line.trim() === 'tasks:')
+  if (tasksLineIndex === -1) {
+    return tasks
+  }
+
+  const tasksIndent = getIndent(lines[tasksLineIndex]!)
+  let index = tasksLineIndex + 1
+
+  while (index < lines.length) {
+    const line = lines[index]!
+    const trimmed = line.trim()
+    const indent = getIndent(line)
+
+    if (!trimmed) {
+      index += 1
+      continue
+    }
+
+    if (indent <= tasksIndent) {
+      break
+    }
+
+    if (!trimmed.startsWith('- name:')) {
+      index += 1
+      continue
+    }
+
+    const taskIndent = indent
+    const name = parseScalar(trimmed, '- name:')
+    let interval = ''
+    let prompt = ''
+    let steps: HeartbeatAuthorityTaskStep[] = []
+    index += 1
+
+    while (index < lines.length) {
+      const nextLine = lines[index]!
+      const nextTrimmed = nextLine.trim()
+      const nextIndent = getIndent(nextLine)
+
+      if (!nextTrimmed) {
+        index += 1
+        continue
+      }
+
+      if (nextIndent <= tasksIndent) {
+        break
+      }
+
+      if (nextIndent === taskIndent && nextTrimmed.startsWith('- name:')) {
+        break
+      }
+
+      if (nextIndent <= taskIndent) {
+        break
+      }
+
+      if (nextTrimmed.startsWith('interval:')) {
+        interval = parseScalar(nextTrimmed, 'interval:')
+        index += 1
+        continue
+      }
+
+      if (nextTrimmed.startsWith('prompt:')) {
+        prompt = parseScalar(nextTrimmed, 'prompt:')
+        index += 1
+        continue
+      }
+
+      if (nextTrimmed === 'steps:') {
+        const parsed = parseSteps(index + 1, nextIndent)
+        steps = parsed.steps
+        index = parsed.nextIndex
+        continue
+      }
+
+      index += 1
+    }
+
+    if (name && interval && prompt) {
+      tasks.push({
+        name,
+        interval,
+        prompt,
+        steps,
+      })
+    }
+  }
+
+  return tasks
+}
+
+function parseHeartbeatIntervalMs(interval: string): number | null {
+  const match = interval.trim().match(/^(\d+)\s*(ms|s|m|h|d)?$/i)
+  if (!match) {
+    return null
+  }
+
+  const value = Number.parseInt(match[1]!, 10)
+  const unit = (match[2] ?? 'm').toLowerCase()
+  switch (unit) {
+    case 'ms':
+      return value
+    case 's':
+      return value * 1_000
+    case 'm':
+      return value * 60_000
+    case 'h':
+      return value * 60 * 60_000
+    case 'd':
+      return value * 24 * 60 * 60_000
+    default:
+      return null
+  }
+}
+
+function heartbeatTaskKey(
+  rootDir: string,
+  task: HeartbeatAuthorityTask,
+): string {
+  return `${rootDir}::${task.name}::${task.interval}::${task.prompt}`
+}
+
+function collectDueHeartbeatTasks(
+  snapshot: AutonomyAuthoritySnapshot,
+  nowMs: number,
+): HeartbeatAuthorityTask[] {
+  const due: HeartbeatAuthorityTask[] = []
+  for (const task of snapshot.heartbeatTasks) {
+    const intervalMs = parseHeartbeatIntervalMs(task.interval)
+    if (intervalMs == null) {
+      continue
+    }
+    const key = heartbeatTaskKey(snapshot.rootDir, task)
+    const lastRunMs = heartbeatTaskLastRunByKey.get(key)
+    if (lastRunMs !== undefined && nowMs - lastRunMs < intervalMs) {
+      continue
+    }
+    due.push(task)
+  }
+  return due
+}
+
+function markHeartbeatTasksConsumed(
+  snapshot: AutonomyAuthoritySnapshot,
+  tasks: HeartbeatAuthorityTask[],
+  nowMs: number,
+): void {
+  for (const task of tasks) {
+    heartbeatTaskLastRunByKey.set(
+      heartbeatTaskKey(snapshot.rootDir, task),
+      nowMs,
+    )
+  }
+}
+
+export function resetAutonomyAuthorityForTests(): void {
+  heartbeatTaskLastRunByKey.clear()
+}
+
+export async function loadAutonomyAuthority(
+  params: AutonomyAuthorityParams = {},
+): Promise<AutonomyAuthoritySnapshot> {
+  const rootDir = resolve(params.rootDir ?? getProjectRoot())
+  const currentDir = resolve(params.currentDir ?? getCwd())
+  const authorityDirs = listAuthorityDirectories(rootDir, currentDir)
+
+  const [agentsResults, heartbeatFile] = await Promise.all([
+    Promise.all(
+      authorityDirs.map(async dir =>
+        readAuthorityFile(
+          join(dir, AUTONOMY_DIR, AUTONOMY_AGENTS_FILENAME),
+          rootDir,
+        ),
+      ),
+    ),
+    readAuthorityFile(
+      join(rootDir, AUTONOMY_DIR, AUTONOMY_HEARTBEAT_FILENAME),
+      rootDir,
+    ),
+  ])
+  const agentsFiles = agentsResults.filter(
+    (file): file is AutonomyAuthorityFile => file !== null,
+  )
+
+  return {
+    rootDir,
+    currentDir,
+    agentsFiles,
+    agentsContent: mergeAgentsAuthority(agentsFiles),
+    heartbeatFile,
+    heartbeatContent: heartbeatFile?.content ?? null,
+    heartbeatTasks: heartbeatFile
+      ? parseHeartbeatAuthorityTasks(heartbeatFile.content)
+      : [],
+  }
+}
+
+export async function buildAutonomyTurnPrompt(params: {
+  basePrompt: string
+  trigger: AutonomyTriggerKind
+  rootDir?: string
+  currentDir?: string
+  nowMs?: number
+}): Promise<string> {
+  const prepared = await prepareAutonomyTurnPrompt(params)
+  commitPreparedAutonomyTurn(prepared)
+  return prepared.prompt
+}
+
+export async function prepareAutonomyTurnPrompt(params: {
+  basePrompt: string
+  trigger: AutonomyTriggerKind
+  rootDir?: string
+  currentDir?: string
+  nowMs?: number
+}): Promise<PreparedAutonomyTurn> {
+  const snapshot = await loadAutonomyAuthority({
+    rootDir: params.rootDir,
+    currentDir: params.currentDir,
+  })
+  const nowMs = params.nowMs ?? Date.now()
+  const dueHeartbeatTasks =
+    params.trigger === 'proactive-tick'
+      ? collectDueHeartbeatTasks(snapshot, nowMs)
+      : []
+  const duePromptTasks = dueHeartbeatTasks.filter(
+    task => task.steps.length === 0,
+  )
+
+  const sections: string[] = []
+  if (snapshot.agentsContent) {
+    sections.push(
+      `Workspace authority from ${AUTONOMY_AGENTS_FILENAME}:\n${snapshot.agentsContent}`,
+    )
+  }
+  if (snapshot.heartbeatContent) {
+    sections.push(
+      `Workspace heartbeat guidance from ${AUTONOMY_HEARTBEAT_FILENAME}:\n${snapshot.heartbeatContent}`,
+    )
+  }
+  if (duePromptTasks.length > 0) {
+    sections.push(
+      [
+        `Due ${AUTONOMY_HEARTBEAT_FILENAME} tasks:`,
+        ...duePromptTasks.map(
+          task => `- ${task.name} (${task.interval}): ${task.prompt}`,
+        ),
+      ].join('\n'),
+    )
+  }
+
+  if (sections.length === 0) {
+    return {
+      rootDir: snapshot.rootDir,
+      currentDir: snapshot.currentDir,
+      trigger: params.trigger,
+      prompt: params.basePrompt,
+      dueHeartbeatTasks,
+      nowMs,
+    }
+  }
+
+  const prelude =
+    params.trigger === 'proactive-tick'
+      ? 'This is an autonomous proactive turn. Follow the workspace authority below before acting.'
+      : 'This prompt was generated automatically. Follow the workspace authority below before acting.'
+
+  return {
+    rootDir: snapshot.rootDir,
+    currentDir: snapshot.currentDir,
+    trigger: params.trigger,
+    prompt: [
+      prelude,
+      '<autonomy_authority>',
+      ...sections,
+      '</autonomy_authority>',
+      params.basePrompt,
+    ].join('\n\n'),
+    dueHeartbeatTasks,
+    nowMs,
+  }
+}
+
+export function commitPreparedAutonomyTurn(
+  prepared: PreparedAutonomyTurn,
+): void {
+  if (
+    prepared.trigger !== 'proactive-tick' ||
+    prepared.dueHeartbeatTasks.length === 0
+  ) {
+    return
+  }
+  const snapshot: AutonomyAuthoritySnapshot = {
+    rootDir: prepared.rootDir,
+    currentDir: prepared.currentDir,
+    agentsFiles: [],
+    agentsContent: null,
+    heartbeatFile: null,
+    heartbeatContent: null,
+    heartbeatTasks: prepared.dueHeartbeatTasks,
+  }
+  markHeartbeatTasksConsumed(
+    snapshot,
+    prepared.dueHeartbeatTasks,
+    prepared.nowMs,
+  )
+}
diff --git a/src/utils/autonomyFlows.ts b/src/utils/autonomyFlows.ts
new file mode 100644
index 000000000..c67d5c058
--- /dev/null
+++ b/src/utils/autonomyFlows.ts
@@ -0,0 +1,1057 @@
+import { randomUUID } from 'crypto'
+import { mkdir, writeFile } from 'fs/promises'
+import { dirname, join, resolve } from 'path'
+import { getProjectRoot } from '../bootstrap/state.js'
+import { AUTONOMY_DIR, type AutonomyTriggerKind } from './autonomyAuthority.js'
+import { withAutonomyPersistenceLock } from './autonomyPersistence.js'
+import { getFsImplementation } from './fsOperations.js'
+
+const AUTONOMY_FLOWS_MAX = 100
+const AUTONOMY_FLOWS_RELATIVE_PATH = join(AUTONOMY_DIR, 'flows.json')
+export const DEFAULT_AUTONOMY_OWNER_KEY = 'main-thread'
+
+export type AutonomyFlowSyncMode = 'managed'
+
+export type AutonomyFlowStatus =
+  | 'queued'
+  | 'running'
+  | 'waiting'
+  | 'blocked'
+  | 'succeeded'
+  | 'failed'
+  | 'cancelled'
+  | 'lost'
+
+export type AutonomyManagedFlowStepStatus =
+  | 'pending'
+  | 'queued'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+
+export type ManagedAutonomyFlowStepDefinition = {
+  name: string
+  prompt: string
+  waitFor?: string
+}
+
+export type ManagedAutonomyFlowStep = ManagedAutonomyFlowStepDefinition & {
+  stepId: string
+  status: AutonomyManagedFlowStepStatus
+  runId?: string
+  startedAt?: number
+  endedAt?: number
+  error?: string
+}
+
+export type ManagedAutonomyFlowState = {
+  currentStepIndex: number
+  steps: ManagedAutonomyFlowStep[]
+}
+
+export type AutonomyFlowWaitState = {
+  reason: string
+  stepId: string
+  stepName: string
+  stepIndex: number
+}
+
+export type AutonomyFlowRecord = {
+  flowId: string
+  flowKey: string
+  syncMode: AutonomyFlowSyncMode
+  ownerKey: string
+  revision: number
+  trigger: AutonomyTriggerKind
+  status: AutonomyFlowStatus
+  goal: string
+  rootDir: string
+  currentDir: string
+  sourceId?: string
+  sourceLabel?: string
+  latestRunId?: string
+  runCount: number
+  createdAt: number
+  updatedAt: number
+  startedAt?: number
+  endedAt?: number
+  currentStep?: string
+  blockedRunId?: string
+  blockedSummary?: string
+  stateJson?: ManagedAutonomyFlowState
+  waitJson?: AutonomyFlowWaitState
+  cancelRequestedAt?: number
+  lastError?: string
+}
+
+type AutonomyFlowsFile = {
+  flows: AutonomyFlowRecord[]
+}
+
+export type ManagedAutonomyFlowQueueInstruction = {
+  flowId: string
+  flowKey: string
+  stepIndex: number
+  step: ManagedAutonomyFlowStep
+}
+
+export type ManagedAutonomyFlowStartResult = {
+  flow: AutonomyFlowRecord
+  started: boolean
+  nextStep?: ManagedAutonomyFlowQueueInstruction
+}
+
+export type ManagedAutonomyFlowAdvanceResult = {
+  flow: AutonomyFlowRecord
+  nextStep?: ManagedAutonomyFlowQueueInstruction
+}
+
+export type ManagedAutonomyFlowCancelResult = {
+  flow: AutonomyFlowRecord
+  queuedRunIds: string[]
+  accepted: boolean
+}
+
+function cloneFlowStep(step: ManagedAutonomyFlowStep): ManagedAutonomyFlowStep {
+  return { ...step }
+}
+
+function cloneManagedState(
+  state: ManagedAutonomyFlowState | undefined,
+): ManagedAutonomyFlowState | undefined {
+  if (!state) {
+    return undefined
+  }
+  return {
+    currentStepIndex: state.currentStepIndex,
+    steps: state.steps.map(cloneFlowStep),
+  }
+}
+
+function cloneWaitState(
+  wait: AutonomyFlowWaitState | undefined,
+): AutonomyFlowWaitState | undefined {
+  return wait ? { ...wait } : undefined
+}
+
+function cloneFlowRecord(flow: AutonomyFlowRecord): AutonomyFlowRecord {
+  return {
+    ...flow,
+    ...(flow.stateJson ? { stateJson: cloneManagedState(flow.stateJson) } : {}),
+    ...(flow.waitJson ? { waitJson: cloneWaitState(flow.waitJson) } : {}),
+  }
+}
+
+function isManagedFlowStatusActive(status: AutonomyFlowStatus): boolean {
+  return (
+    status === 'queued' ||
+    status === 'running' ||
+    status === 'waiting' ||
+    status === 'blocked'
+  )
+}
+
+function defaultFlowSource(params: {
+  trigger: AutonomyTriggerKind
+  sourceId?: string
+  sourceLabel?: string
+}): { sourceId?: string; sourceLabel?: string } {
+  if (params.sourceId || params.sourceLabel) {
+    return {
+      ...(params.sourceId ? { sourceId: params.sourceId } : {}),
+      ...(params.sourceLabel ? { sourceLabel: params.sourceLabel } : {}),
+    }
+  }
+  if (params.trigger === 'proactive-tick') {
+    return {
+      sourceId: 'heartbeat-loop',
+      sourceLabel: 'heartbeat-loop',
+    }
+  }
+  return {}
+}
+
+function normalizeManagedState(
+  value: unknown,
+): ManagedAutonomyFlowState | undefined {
+  if (
+    !value ||
+    typeof value !== 'object' ||
+    !('steps' in value) ||
+    !Array.isArray((value as { steps: unknown[] }).steps)
+  ) {
+    return undefined
+  }
+  const parsed = value as Partial<ManagedAutonomyFlowState>
+  const steps = (parsed.steps ?? [])
+    .filter((step): step is ManagedAutonomyFlowStep =>
+      Boolean(
+        step &&
+          typeof step.stepId === 'string' &&
+          typeof step.name === 'string' &&
+          typeof step.prompt === 'string' &&
+          typeof step.status === 'string',
+      ),
+    )
+    .map(step => ({
+      stepId: step.stepId,
+      name: step.name,
+      prompt: step.prompt,
+      status: step.status,
+      ...(step.waitFor ? { waitFor: step.waitFor } : {}),
+      ...(step.runId ? { runId: step.runId } : {}),
+      ...(step.startedAt != null ? { startedAt: step.startedAt } : {}),
+      ...(step.endedAt != null ? { endedAt: step.endedAt } : {}),
+      ...(step.error ? { error: step.error } : {}),
+    }))
+  if (steps.length === 0) {
+    return undefined
+  }
+  const currentStepIndex = Math.min(
+    Math.max(parsed.currentStepIndex ?? 0, 0),
+    steps.length - 1,
+  )
+  return {
+    currentStepIndex,
+    steps,
+  }
+}
+
+function normalizeWaitState(value: unknown): AutonomyFlowWaitState | undefined {
+  if (
+    !value ||
+    typeof value !== 'object' ||
+    typeof (value as { reason?: unknown }).reason !== 'string' ||
+    typeof (value as { stepId?: unknown }).stepId !== 'string' ||
+    typeof (value as { stepName?: unknown }).stepName !== 'string' ||
+    typeof (value as { stepIndex?: unknown }).stepIndex !== 'number'
+  ) {
+    return undefined
+  }
+  return {
+    reason: (value as { reason: string }).reason,
+    stepId: (value as { stepId: string }).stepId,
+    stepName: (value as { stepName: string }).stepName,
+    stepIndex: (value as { stepIndex: number }).stepIndex,
+  }
+}
+
+function normalizeFlowRecord(flow: AutonomyFlowRecord): AutonomyFlowRecord {
+  const source = defaultFlowSource(flow)
+  return {
+    ...flow,
+    syncMode: 'managed',
+    ownerKey: flow.ownerKey || DEFAULT_AUTONOMY_OWNER_KEY,
+    revision: Math.max(flow.revision ?? 0, 0),
+    goal: flow.goal || flow.sourceLabel || flow.sourceId || flow.flowKey,
+    currentDir: flow.currentDir || flow.rootDir,
+    runCount: Math.max(flow.runCount ?? 0, 0),
+    stateJson: normalizeManagedState(flow.stateJson),
+    waitJson: normalizeWaitState(flow.waitJson),
+    ...(flow.sourceId
+      ? { sourceId: flow.sourceId }
+      : source.sourceId
+        ? { sourceId: source.sourceId }
+        : {}),
+    ...(flow.sourceLabel
+      ? { sourceLabel: flow.sourceLabel }
+      : source.sourceLabel
+        ? { sourceLabel: source.sourceLabel }
+        : {}),
+  }
+}
+
+function buildManagedState(
+  steps: ManagedAutonomyFlowStepDefinition[],
+): ManagedAutonomyFlowState {
+  return {
+    currentStepIndex: 0,
+    steps: steps.map(step => ({
+      stepId: randomUUID(),
+      name: step.name,
+      prompt: step.prompt,
+      status: 'pending',
+      ...(step.waitFor ? { waitFor: step.waitFor } : {}),
+    })),
+  }
+}
+
+function getManagedStep(
+  flow: AutonomyFlowRecord,
+  stepIndex: number,
+): ManagedAutonomyFlowStep | null {
+  return flow.stateJson?.steps[stepIndex] ?? null
+}
+
+function buildQueueInstruction(
+  flow: AutonomyFlowRecord,
+  stepIndex: number,
+): ManagedAutonomyFlowQueueInstruction | undefined {
+  const step = getManagedStep(flow, stepIndex)
+  if (!step) {
+    return undefined
+  }
+  return {
+    flowId: flow.flowId,
+    flowKey: flow.flowKey,
+    stepIndex,
+    step: cloneFlowStep(step),
+  }
+}
+
+function markRemainingStepsCancelled(
+  state: ManagedAutonomyFlowState,
+  startIndex: number,
+  nowMs: number,
+): void {
+  for (let i = startIndex; i < state.steps.length; i += 1) {
+    const step = state.steps[i]!
+    if (
+      step.status === 'completed' ||
+      step.status === 'failed' ||
+      step.status === 'cancelled'
+    ) {
+      continue
+    }
+    step.status = 'cancelled'
+    step.endedAt = nowMs
+  }
+}
+
+export function resolveAutonomyFlowsPath(
+  rootDir: string = getProjectRoot(),
+): string {
+  return join(resolve(rootDir), AUTONOMY_FLOWS_RELATIVE_PATH)
+}
+
+export async function listAutonomyFlows(
+  rootDir: string = getProjectRoot(),
+): Promise<AutonomyFlowRecord[]> {
+  try {
+    const raw = (await getFsImplementation().readFile(
+      resolveAutonomyFlowsPath(rootDir),
+      {
+        encoding: 'utf-8',
+      },
+    )) as string
+    const parsed = JSON.parse(raw) as Partial<AutonomyFlowsFile>
+    if (!Array.isArray(parsed.flows)) {
+      return []
+    }
+    return parsed.flows
+      .filter((flow): flow is AutonomyFlowRecord => {
+        return Boolean(
+          flow &&
+            typeof flow.flowId === 'string' &&
+            typeof flow.flowKey === 'string' &&
+            typeof flow.trigger === 'string' &&
+            typeof flow.status === 'string' &&
+            typeof flow.rootDir === 'string' &&
+            typeof flow.createdAt === 'number' &&
+            typeof flow.updatedAt === 'number',
+        )
+      })
+      .map(normalizeFlowRecord)
+      .sort((left, right) => right.updatedAt - left.updatedAt)
+  } catch {
+    return []
+  }
+}
+
+async function writeAutonomyFlows(
+  flows: AutonomyFlowRecord[],
+  rootDir: string = getProjectRoot(),
+): Promise<void> {
+  const path = resolveAutonomyFlowsPath(rootDir)
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(
+    path,
+    `${JSON.stringify(
+      {
+        flows: flows
+          .slice()
+          .map(cloneFlowRecord)
+          .sort((left, right) => right.updatedAt - left.updatedAt)
+          .slice(0, AUTONOMY_FLOWS_MAX),
+      } satisfies AutonomyFlowsFile,
+      null,
+      2,
+    )}\n`,
+    'utf-8',
+  )
+}
+
+async function updateAutonomyFlowById(
+  flowId: string,
+  updater: (current: AutonomyFlowRecord) => AutonomyFlowRecord,
+  rootDir: string = getProjectRoot(),
+): Promise<AutonomyFlowRecord | null> {
+  return withAutonomyPersistenceLock(rootDir, async () => {
+    const flows = await listAutonomyFlows(rootDir)
+    const index = flows.findIndex(flow => flow.flowId === flowId)
+    if (index === -1) {
+      return null
+    }
+    const next = normalizeFlowRecord(updater(cloneFlowRecord(flows[index]!)))
+    flows[index] = next
+    await writeAutonomyFlows(flows, rootDir)
+    return next
+  })
+}
+
+export function createManagedAutonomyFlowKey(params: {
+  trigger: AutonomyTriggerKind
+  sourceId?: string
+  sourceLabel?: string
+  goal: string
+}): string {
+  const source = defaultFlowSource(params)
+  const discriminator = source.sourceId ?? source.sourceLabel ?? params.goal
+  return `managed:${params.trigger}:${discriminator}`
+}
+
+export async function startManagedAutonomyFlow(params: {
+  trigger: AutonomyTriggerKind
+  goal: string
+  steps: ManagedAutonomyFlowStepDefinition[]
+  rootDir?: string
+  currentDir?: string
+  ownerKey?: string
+  sourceId?: string
+  sourceLabel?: string
+  nowMs?: number
+}): Promise<ManagedAutonomyFlowStartResult | null> {
+  if (params.steps.length === 0) {
+    return null
+  }
+  const rootDir = resolve(params.rootDir ?? getProjectRoot())
+  const currentDir = resolve(params.currentDir ?? rootDir)
+  const source = defaultFlowSource(params)
+  const flowKey = createManagedAutonomyFlowKey({
+    trigger: params.trigger,
+    sourceId: source.sourceId,
+    sourceLabel: source.sourceLabel,
+    goal: params.goal,
+  })
+  const nowMs = params.nowMs ?? Date.now()
+
+  return withAutonomyPersistenceLock(rootDir, async () => {
+    const flows = await listAutonomyFlows(rootDir)
+    const index = flows.findIndex(flow => flow.flowKey === flowKey)
+    const current = index === -1 ? null : flows[index]!
+
+    if (current && isManagedFlowStatusActive(current.status)) {
+      return {
+        flow: current,
+        started: false,
+      }
+    }
+
+    const stateJson = buildManagedState(params.steps)
+    const firstStep = stateJson.steps[0]!
+    const waiting =
+      firstStep.waitFor != null
+        ? {
+            reason: firstStep.waitFor,
+            stepId: firstStep.stepId,
+            stepName: firstStep.name,
+            stepIndex: 0,
+          }
+        : undefined
+
+    const next: AutonomyFlowRecord = normalizeFlowRecord({
+      flowId: current?.flowId ?? randomUUID(),
+      flowKey,
+      syncMode: 'managed',
+      ownerKey:
+        params.ownerKey ?? current?.ownerKey ?? DEFAULT_AUTONOMY_OWNER_KEY,
+      revision: (current?.revision ?? 0) + 1,
+      trigger: params.trigger,
+      status: waiting ? 'waiting' : 'queued',
+      goal: params.goal,
+      rootDir,
+      currentDir,
+      ...(source.sourceId ? { sourceId: source.sourceId } : {}),
+      ...(source.sourceLabel ? { sourceLabel: source.sourceLabel } : {}),
+      latestRunId: undefined,
+      runCount: current?.runCount ?? 0,
+      createdAt: current?.createdAt ?? nowMs,
+      updatedAt: nowMs,
+      startedAt: undefined,
+      endedAt: undefined,
+      currentStep: firstStep.name,
+      blockedRunId: undefined,
+      blockedSummary: undefined,
+      stateJson,
+      ...(waiting ? { waitJson: waiting } : {}),
+      cancelRequestedAt: undefined,
+      lastError: undefined,
+    })
+
+    if (index === -1) {
+      flows.unshift(next)
+    } else {
+      flows[index] = next
+    }
+    await writeAutonomyFlows(flows, rootDir)
+    return {
+      flow: next,
+      started: true,
+      ...(waiting ? {} : { nextStep: buildQueueInstruction(next, 0) }),
+    }
+  })
+}
+
+export async function queueManagedAutonomyFlowStepRun(params: {
+  flowId: string
+  stepId: string
+  stepIndex: number
+  runId: string
+  rootDir?: string
+  nowMs?: number
+}): Promise<AutonomyFlowRecord | null> {
+  const rootDir = resolve(params.rootDir ?? getProjectRoot())
+  return updateAutonomyFlowById(
+    params.flowId,
+    current => {
+      const state = cloneManagedState(current.stateJson)
+      const step = state?.steps[params.stepIndex]
+      if (!state || !step || step.stepId !== params.stepId) {
+        return current
+      }
+      step.status = 'queued'
+      step.runId = params.runId
+      step.startedAt = undefined
+      step.endedAt = undefined
+      step.error = undefined
+      state.currentStepIndex = params.stepIndex
+      return {
+        ...current,
+        revision: current.revision + 1,
+        status: 'queued',
+        currentStep: step.name,
+        latestRunId: params.runId,
+        runCount: current.runCount + 1,
+        updatedAt: params.nowMs ?? Date.now(),
+        endedAt: undefined,
+        blockedRunId: undefined,
+        blockedSummary: undefined,
+        waitJson: undefined,
+        stateJson: state,
+        lastError: undefined,
+      }
+    },
+    rootDir,
+  )
+}
+
+export async function markManagedAutonomyFlowStepRunning(params: {
+  flowId: string
+  runId: string
+  rootDir?: string
+  nowMs?: number
+}): Promise<AutonomyFlowRecord | null> {
+  const rootDir = resolve(params.rootDir ?? getProjectRoot())
+  return updateAutonomyFlowById(
+    params.flowId,
+    current => {
+      const state = cloneManagedState(current.stateJson)
+      if (!state) {
+        return current
+      }
+      const stepIndex = state.steps.findIndex(
+        step => step.runId === params.runId,
+      )
+      if (stepIndex === -1) {
+        return current
+      }
+      const step = state.steps[stepIndex]!
+      step.status = 'running'
+      step.startedAt = params.nowMs ?? Date.now()
+      state.currentStepIndex = stepIndex
+      return {
+        ...current,
+        revision: current.revision + 1,
+        status: 'running',
+        currentStep: step.name,
+        latestRunId: params.runId,
+        updatedAt: step.startedAt,
+        startedAt: current.startedAt ?? step.startedAt,
+        endedAt: undefined,
+        blockedRunId: undefined,
+        blockedSummary: undefined,
+        waitJson: undefined,
+        stateJson: state,
+        lastError: undefined,
+      }
+    },
+    rootDir,
+  )
+}
+
+export async function markManagedAutonomyFlowStepCompleted(params: {
+  flowId: string
+  runId: string
+  rootDir?: string
+  nowMs?: number
+}): Promise<ManagedAutonomyFlowAdvanceResult | null> {
+  const rootDir = resolve(params.rootDir ?? getProjectRoot())
+  const nowMs = params.nowMs ?? Date.now()
+  return updateAutonomyFlowById(
+    params.flowId,
+    current => {
+      const state = cloneManagedState(current.stateJson)
+      if (!state) {
+        return current
+      }
+      const stepIndex = state.steps.findIndex(
+        step => step.runId === params.runId,
+      )
+      if (stepIndex === -1) {
+        return current
+      }
+      const step = state.steps[stepIndex]!
+      step.status = 'completed'
+      step.endedAt = nowMs
+      step.error = undefined
+      state.currentStepIndex = stepIndex
+
+      const nextIndex = stepIndex + 1
+      const nextStep = state.steps[nextIndex]
+
+      if (current.cancelRequestedAt) {
+        markRemainingStepsCancelled(state, nextIndex, nowMs)
+        return {
+          ...current,
+          revision: current.revision + 1,
+          status: 'cancelled',
+          updatedAt: nowMs,
+          endedAt: nowMs,
+          currentStep: undefined,
+          blockedRunId: undefined,
+          blockedSummary: undefined,
+          waitJson: undefined,
+          stateJson: state,
+          lastError: undefined,
+        }
+      }
+
+      if (!nextStep) {
+        return {
+          ...current,
+          revision: current.revision + 1,
+          status: 'succeeded',
+          updatedAt: nowMs,
+          endedAt: nowMs,
+          currentStep: undefined,
+          blockedRunId: undefined,
+          blockedSummary: undefined,
+          waitJson: undefined,
+          stateJson: state,
+          lastError: undefined,
+        }
+      }
+
+      state.currentStepIndex = nextIndex
+      if (nextStep.waitFor) {
+        return {
+          ...current,
+          revision: current.revision + 1,
+          status: 'waiting',
+          updatedAt: nowMs,
+          endedAt: undefined,
+          currentStep: nextStep.name,
+          blockedRunId: undefined,
+          blockedSummary: undefined,
+          waitJson: {
+            reason: nextStep.waitFor,
+            stepId: nextStep.stepId,
+            stepName: nextStep.name,
+            stepIndex: nextIndex,
+          },
+          stateJson: state,
+          lastError: undefined,
+        }
+      }
+
+      return {
+        ...current,
+        revision: current.revision + 1,
+        status: 'queued',
+        updatedAt: nowMs,
+        endedAt: undefined,
+        currentStep: nextStep.name,
+        blockedRunId: undefined,
+        blockedSummary: undefined,
+        waitJson: undefined,
+        stateJson: state,
+        lastError: undefined,
+      }
+    },
+    rootDir,
+  ).then(flow =>
+    flow
+      ? {
+          flow,
+          ...(flow.status === 'queued' && flow.stateJson
+            ? {
+                nextStep: buildQueueInstruction(
+                  flow,
+                  flow.stateJson.currentStepIndex,
+                ),
+              }
+            : {}),
+        }
+      : null,
+  )
+}
+
+export async function markManagedAutonomyFlowStepFailed(params: {
+  flowId: string
+  runId: string
+  error: string
+  rootDir?: string
+  nowMs?: number
+}): Promise<ManagedAutonomyFlowAdvanceResult | null> {
+  const rootDir = resolve(params.rootDir ?? getProjectRoot())
+  const nowMs = params.nowMs ?? Date.now()
+  return updateAutonomyFlowById(
+    params.flowId,
+    current => {
+      const state = cloneManagedState(current.stateJson)
+      if (!state) {
+        return current
+      }
+      const stepIndex = state.steps.findIndex(
+        step => step.runId === params.runId,
+      )
+      if (stepIndex === -1) {
+        return current
+      }
+      const step = state.steps[stepIndex]!
+      step.status = 'failed'
+      step.endedAt = nowMs
+      step.error = params.error
+      state.currentStepIndex = stepIndex
+
+      if (current.cancelRequestedAt) {
+        markRemainingStepsCancelled(state, stepIndex + 1, nowMs)
+        return {
+          ...current,
+          revision: current.revision + 1,
+          status: 'cancelled',
+          updatedAt: nowMs,
+          endedAt: nowMs,
+          currentStep: undefined,
+          blockedRunId: params.runId,
+          blockedSummary: params.error,
+          waitJson: undefined,
+          stateJson: state,
+          lastError: params.error,
+        }
+      }
+
+      return {
+        ...current,
+        revision: current.revision + 1,
+        status: 'failed',
+        updatedAt: nowMs,
+        endedAt: nowMs,
+        currentStep: step.name,
+        blockedRunId: params.runId,
+        blockedSummary: params.error,
+        waitJson: undefined,
+        stateJson: state,
+        lastError: params.error,
+      }
+    },
+    rootDir,
+  ).then(flow => (flow ? { flow } : null))
+}
+
+export async function markManagedAutonomyFlowStepCancelled(params: {
+  flowId: string
+  runId: string
+  rootDir?: string
+  nowMs?: number
+}): Promise<ManagedAutonomyFlowAdvanceResult | null> {
+  const rootDir = resolve(params.rootDir ?? getProjectRoot())
+  const nowMs = params.nowMs ?? Date.now()
+  return updateAutonomyFlowById(
+    params.flowId,
+    current => {
+      const state = cloneManagedState(current.stateJson)
+      if (!state) {
+        return current
+      }
+      const stepIndex = state.steps.findIndex(
+        step => step.runId === params.runId,
+      )
+      if (stepIndex === -1) {
+        return current
+      }
+      const step = state.steps[stepIndex]!
+      step.status = 'cancelled'
+      step.endedAt = nowMs
+      markRemainingStepsCancelled(state, stepIndex + 1, nowMs)
+      state.currentStepIndex = stepIndex
+      return {
+        ...current,
+        revision: current.revision + 1,
+        status: 'cancelled',
+        updatedAt: nowMs,
+        endedAt: nowMs,
+        currentStep: undefined,
+        blockedRunId: params.runId,
+        blockedSummary: undefined,
+        waitJson: undefined,
+        stateJson: state,
+        lastError: undefined,
+      }
+    },
+    rootDir,
+  ).then(flow => (flow ? { flow } : null))
+}
+
+export async function resumeManagedAutonomyFlow(params: {
+  flowId: string
+  rootDir?: string
+  nowMs?: number
+}): Promise<ManagedAutonomyFlowAdvanceResult | null> {
+  const rootDir = resolve(params.rootDir ?? getProjectRoot())
+  const nowMs = params.nowMs ?? Date.now()
+  return updateAutonomyFlowById(
+    params.flowId,
+    current => {
+      if (
+        current.status !== 'waiting' ||
+        !current.stateJson ||
+        !current.waitJson
+      ) {
+        return current
+      }
+      if (current.cancelRequestedAt) {
+        return {
+          ...current,
+          revision: current.revision + 1,
+          status: 'cancelled',
+          updatedAt: nowMs,
+          endedAt: nowMs,
+          currentStep: undefined,
+          waitJson: undefined,
+          lastError: undefined,
+        }
+      }
+      const state = cloneManagedState(current.stateJson)!
+      state.currentStepIndex = current.waitJson.stepIndex
+      return {
+        ...current,
+        revision: current.revision + 1,
+        status: 'queued',
+        updatedAt: nowMs,
+        endedAt: undefined,
+        currentStep: current.waitJson.stepName,
+        waitJson: undefined,
+        stateJson: state,
+        lastError: undefined,
+      }
+    },
+    rootDir,
+  ).then(flow =>
+    flow
+      ? {
+          flow,
+          ...(flow.status === 'queued' && flow.stateJson
+            ? {
+                nextStep: buildQueueInstruction(
+                  flow,
+                  flow.stateJson.currentStepIndex,
+                ),
+              }
+            : {}),
+        }
+      : null,
+  )
+}
+
+export async function requestManagedAutonomyFlowCancel(params: {
+  flowId: string
+  rootDir?: string
+  nowMs?: number
+}): Promise<ManagedAutonomyFlowCancelResult | null> {
+  const rootDir = resolve(params.rootDir ?? getProjectRoot())
+  const nowMs = params.nowMs ?? Date.now()
+  return withAutonomyPersistenceLock(rootDir, async () => {
+    const flows = await listAutonomyFlows(rootDir)
+    const index = flows.findIndex(flow => flow.flowId === params.flowId)
+    if (index === -1) {
+      return null
+    }
+    const current = cloneFlowRecord(flows[index]!)
+    const queuedRunIds =
+      current.stateJson?.steps
+        .filter(
+          step => step.status === 'queued' && typeof step.runId === 'string',
+        )
+        .map(step => step.runId!) ?? []
+
+    if (!isManagedFlowStatusActive(current.status)) {
+      return {
+        flow: current,
+        queuedRunIds,
+        accepted: false,
+      }
+    }
+
+    const state = cloneManagedState(current.stateJson)
+    if (!state) {
+      return {
+        flow: current,
+        queuedRunIds,
+        accepted: false,
+      }
+    }
+
+    const next =
+      current.status === 'running'
+        ? normalizeFlowRecord({
+            ...current,
+            revision: current.revision + 1,
+            updatedAt: nowMs,
+            cancelRequestedAt: current.cancelRequestedAt ?? nowMs,
+          })
+        : normalizeFlowRecord({
+            ...current,
+            revision: current.revision + 1,
+            status: 'cancelled',
+            updatedAt: nowMs,
+            endedAt: nowMs,
+            currentStep: undefined,
+            waitJson: undefined,
+            stateJson: (() => {
+              markRemainingStepsCancelled(state, state.currentStepIndex, nowMs)
+              return state
+            })(),
+            cancelRequestedAt: current.cancelRequestedAt ?? nowMs,
+            lastError: undefined,
+            blockedRunId: undefined,
+            blockedSummary: undefined,
+          })
+
+    flows[index] = next
+    await writeAutonomyFlows(flows, rootDir)
+    return {
+      flow: next,
+      queuedRunIds,
+      accepted: true,
+    }
+  })
+}
+
+export async function getAutonomyFlowById(
+  flowId: string,
+  rootDir: string = getProjectRoot(),
+): Promise<AutonomyFlowRecord | null> {
+  const flows = await listAutonomyFlows(rootDir)
+  return flows.find(flow => flow.flowId === flowId) ?? null
+}
+
+export function formatAutonomyFlowsStatus(flows: AutonomyFlowRecord[]): string {
+  const counts = {
+    queued: 0,
+    running: 0,
+    waiting: 0,
+    blocked: 0,
+    succeeded: 0,
+    failed: 0,
+    cancelled: 0,
+    lost: 0,
+  }
+  for (const flow of flows) {
+    counts[flow.status] += 1
+  }
+  return [
+    `Autonomy flows: ${flows.length}`,
+    `Queued: ${counts.queued}`,
+    `Running: ${counts.running}`,
+    `Waiting: ${counts.waiting}`,
+    `Blocked: ${counts.blocked}`,
+    `Succeeded: ${counts.succeeded}`,
+    `Failed: ${counts.failed}`,
+    `Cancelled: ${counts.cancelled}`,
+  ].join('\n')
+}
+
+export function formatAutonomyFlowsList(
+  flows: AutonomyFlowRecord[],
+  limit = 10,
+): string {
+  const slice = flows.slice(0, limit)
+  if (slice.length === 0) {
+    return 'No autonomy flows recorded.'
+  }
+  return slice
+    .map(flow => {
+      const source = flow.sourceLabel ?? flow.sourceId ?? 'automatic'
+      const stepSummary = flow.currentStep ? ` | step=${flow.currentStep}` : ''
+      const waitSummary =
+        flow.status === 'waiting' && flow.waitJson
+          ? ` | waiting=${flow.waitJson.reason}`
+          : ''
+      return `${flow.flowId} | managed | rev=${flow.revision} | ${flow.status} | ${source}${stepSummary}${waitSummary}\n  goal=${flow.goal} | runs=${flow.runCount}`
+    })
+    .join('\n')
+}
+
+export function formatAutonomyFlowDetail(
+  flow: AutonomyFlowRecord | null | undefined,
+): string {
+  if (!flow) {
+    return 'Autonomy flow not found.'
+  }
+  const stepLines = flow.stateJson?.steps.map((step, index) => {
+    const runId = step.runId ?? 'none'
+    const wait = step.waitFor ? ` | wait=${step.waitFor}` : ''
+    const error = step.error ? ` | error=${step.error}` : ''
+    return `${index + 1}. ${step.name} | ${step.status} | run=${runId}${wait}${error}`
+  }) ?? ['none']
+
+  return [
+    `Flow: ${flow.flowId}`,
+    `Key: ${flow.flowKey}`,
+    `Mode: ${flow.syncMode}`,
+    `Revision: ${flow.revision}`,
+    `Trigger: ${flow.trigger}`,
+    `Status: ${flow.status}`,
+    `Goal: ${flow.goal}`,
+    `Source: ${flow.sourceLabel ?? flow.sourceId ?? 'automatic'}`,
+    `Owner: ${flow.ownerKey}`,
+    `Current step: ${flow.currentStep ?? 'none'}`,
+    `Run count: ${flow.runCount}`,
+    `Latest run: ${flow.latestRunId ?? 'none'}`,
+    `Created: ${new Date(flow.createdAt).toLocaleString()}`,
+    `Updated: ${new Date(flow.updatedAt).toLocaleString()}`,
+    ...(flow.startedAt
+      ? [`Started: ${new Date(flow.startedAt).toLocaleString()}`]
+      : []),
+    ...(flow.endedAt
+      ? [`Ended: ${new Date(flow.endedAt).toLocaleString()}`]
+      : []),
+    ...(flow.waitJson
+      ? [
+          `Waiting: ${flow.waitJson.reason} (${flow.waitJson.stepName} @ ${flow.waitJson.stepIndex + 1})`,
+        ]
+      : []),
+    ...(flow.cancelRequestedAt
+      ? [
+          `Cancel requested: ${new Date(flow.cancelRequestedAt).toLocaleString()}`,
+        ]
+      : []),
+    ...(flow.blockedRunId ? [`Blocked run: ${flow.blockedRunId}`] : []),
+    ...(flow.blockedSummary ? [`Blocked summary: ${flow.blockedSummary}`] : []),
+    ...(flow.lastError ? [`Error: ${flow.lastError}`] : []),
+    'Steps:',
+    ...stepLines,
+  ].join('\n')
+}
diff --git a/src/utils/autonomyPersistence.ts b/src/utils/autonomyPersistence.ts
new file mode 100644
index 000000000..0a0ebef05
--- /dev/null
+++ b/src/utils/autonomyPersistence.ts
@@ -0,0 +1,48 @@
+import { mkdir, writeFile } from 'fs/promises'
+import { join, resolve } from 'path'
+import { lock } from './lockfile.js'
+
+const persistenceLocks = new Map<string, Promise<void>>()
+
+export async function withAutonomyPersistenceLock<T>(
+  rootDir: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const key = resolve(rootDir)
+  const lockPath = join(key, '.claude', 'autonomy', '.lock')
+  const previous = persistenceLocks.get(key) ?? Promise.resolve()
+
+  let release!: () => void
+  const current = new Promise<void>(resolve => {
+    release = resolve
+  })
+  persistenceLocks.set(
+    key,
+    previous.then(() => current),
+  )
+
+  await previous
+  try {
+    await mkdir(join(key, '.claude', 'autonomy'), { recursive: true })
+    await writeFile(lockPath, '', { flag: 'a' })
+    const unlock = await lock(lockPath, {
+      lockfilePath: `${lockPath}.lock`,
+      retries: {
+        retries: 10,
+        factor: 1.2,
+        minTimeout: 10,
+        maxTimeout: 100,
+      },
+    })
+    try {
+      return await fn()
+    } finally {
+      await unlock().catch(() => {})
+    }
+  } finally {
+    release()
+    if (persistenceLocks.get(key) === current) {
+      persistenceLocks.delete(key)
+    }
+  }
+}
diff --git a/src/utils/autonomyRuns.ts b/src/utils/autonomyRuns.ts
new file mode 100644
index 000000000..02ce08c20
--- /dev/null
+++ b/src/utils/autonomyRuns.ts
@@ -0,0 +1,797 @@
+import { randomUUID } from 'crypto'
+import { mkdir, writeFile } from 'fs/promises'
+import { dirname, join, resolve } from 'path'
+import { getProjectRoot } from '../bootstrap/state.js'
+import type { MessageOrigin } from '../types/message.js'
+import type { QueuedCommand } from '../types/textInputTypes.js'
+import {
+  AUTONOMY_DIR,
+  buildAutonomyTurnPrompt,
+  commitPreparedAutonomyTurn,
+  prepareAutonomyTurnPrompt,
+  type AutonomyTriggerKind,
+  type HeartbeatAuthorityTask,
+} from './autonomyAuthority.js'
+import { getCwd } from './cwd.js'
+import {
+  DEFAULT_AUTONOMY_OWNER_KEY,
+  getAutonomyFlowById,
+  markManagedAutonomyFlowStepCancelled,
+  markManagedAutonomyFlowStepCompleted,
+  markManagedAutonomyFlowStepFailed,
+  markManagedAutonomyFlowStepRunning,
+  queueManagedAutonomyFlowStepRun,
+  resumeManagedAutonomyFlow,
+  startManagedAutonomyFlow,
+  type AutonomyFlowRecord,
+  type AutonomyFlowSyncMode,
+  type ManagedAutonomyFlowStepDefinition,
+} from './autonomyFlows.js'
+import { withAutonomyPersistenceLock } from './autonomyPersistence.js'
+import { getFsImplementation } from './fsOperations.js'
+
+const AUTONOMY_RUNS_MAX = 200
+const AUTONOMY_RUNS_RELATIVE_PATH = join(AUTONOMY_DIR, 'runs.json')
+
+export type AutonomyRunStatus =
+  | 'queued'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+
+export type AutonomyRunRuntime = 'automatic' | 'flow_step'
+
+export type AutonomyRunRecord = {
+  runId: string
+  runtime: AutonomyRunRuntime
+  trigger: AutonomyTriggerKind
+  status: AutonomyRunStatus
+  rootDir: string
+  currentDir: string
+  ownerKey: string
+  sourceId?: string
+  sourceLabel?: string
+  parentFlowId?: string
+  parentFlowKey?: string
+  parentFlowSyncMode?: AutonomyFlowSyncMode
+  flowStepId?: string
+  flowStepName?: string
+  promptPreview: string
+  createdAt: number
+  startedAt?: number
+  endedAt?: number
+  error?: string
+}
+
+type AutonomyRunsFile = {
+  runs: AutonomyRunRecord[]
+}
+
+type AutonomyRunFlowRef = {
+  flowId: string
+  flowKey: string
+  syncMode: AutonomyFlowSyncMode
+  ownerKey: string
+  stepId: string
+  stepName: string
+}
+
+function truncatePromptPreview(prompt: string): string {
+  const singleLine = prompt.replace(/\s+/g, ' ').trim()
+  return singleLine.length <= 240
+    ? singleLine
+    : `${singleLine.slice(0, 237)}...`
+}
+
+/** A persisted record may lack fields that were added after the initial schema. */
+type PersistedAutonomyRunRecord = Omit<
+  AutonomyRunRecord,
+  'runtime' | 'currentDir' | 'ownerKey'
+> &
+  Partial<Pick<AutonomyRunRecord, 'runtime' | 'currentDir' | 'ownerKey'>>
+
+function cloneRunRecord(run: AutonomyRunRecord): AutonomyRunRecord {
+  return { ...run }
+}
+
+function normalizePersistedRunRecord(
+  run: PersistedAutonomyRunRecord,
+): AutonomyRunRecord {
+  return {
+    ...run,
+    runtime: run.runtime === 'flow_step' ? 'flow_step' : 'automatic',
+    currentDir: run.currentDir ?? run.rootDir,
+    ownerKey: run.ownerKey ?? DEFAULT_AUTONOMY_OWNER_KEY,
+  }
+}
+
+export function resolveAutonomyRunsPath(
+  rootDir: string = getProjectRoot(),
+): string {
+  return join(resolve(rootDir), AUTONOMY_RUNS_RELATIVE_PATH)
+}
+
+export async function listAutonomyRuns(
+  rootDir: string = getProjectRoot(),
+): Promise<AutonomyRunRecord[]> {
+  try {
+    const raw = (await getFsImplementation().readFile(
+      resolveAutonomyRunsPath(rootDir),
+      {
+        encoding: 'utf-8',
+      },
+    )) as string
+    const parsed = JSON.parse(raw) as { runs?: unknown[] }
+    if (!Array.isArray(parsed.runs)) {
+      return []
+    }
+    return (parsed.runs as Record<string, unknown>[])
+      .filter(
+        (run): run is PersistedAutonomyRunRecord & Record<string, unknown> => {
+          return Boolean(
+            run &&
+              typeof run.runId === 'string' &&
+              typeof run.trigger === 'string' &&
+              typeof run.status === 'string' &&
+              typeof run.rootDir === 'string' &&
+              typeof run.promptPreview === 'string' &&
+              typeof run.createdAt === 'number',
+          )
+        },
+      )
+      .map(normalizePersistedRunRecord)
+      .sort((left, right) => right.createdAt - left.createdAt)
+  } catch {
+    return []
+  }
+}
+
+async function writeAutonomyRuns(
+  runs: AutonomyRunRecord[],
+  rootDir: string = getProjectRoot(),
+): Promise<void> {
+  const path = resolveAutonomyRunsPath(rootDir)
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(
+    path,
+    `${JSON.stringify(
+      {
+        runs: runs
+          .slice()
+          .map(cloneRunRecord)
+          .sort((left, right) => right.createdAt - left.createdAt)
+          .slice(0, AUTONOMY_RUNS_MAX),
+      } satisfies AutonomyRunsFile,
+      null,
+      2,
+    )}\n`,
+    'utf-8',
+  )
+}
+
+async function updateAutonomyRun(
+  runId: string,
+  updater: (current: AutonomyRunRecord) => AutonomyRunRecord,
+  rootDir: string = getProjectRoot(),
+): Promise<AutonomyRunRecord | null> {
+  return withAutonomyPersistenceLock(rootDir, async () => {
+    const runs = await listAutonomyRuns(rootDir)
+    const index = runs.findIndex(run => run.runId === runId)
+    if (index === -1) {
+      return null
+    }
+    const updated = cloneRunRecord(updater(cloneRunRecord(runs[index]!)))
+    runs[index] = updated
+    await writeAutonomyRuns(runs, rootDir)
+    return updated
+  })
+}
+
+export async function getAutonomyRunById(
+  runId: string,
+  rootDir: string = getProjectRoot(),
+): Promise<AutonomyRunRecord | null> {
+  const runs = await listAutonomyRuns(rootDir)
+  return runs.find(run => run.runId === runId) ?? null
+}
+
+export async function createAutonomyRun(params: {
+  trigger: AutonomyTriggerKind
+  prompt: string
+  rootDir?: string
+  currentDir?: string
+  sourceId?: string
+  sourceLabel?: string
+  runtime?: AutonomyRunRuntime
+  ownerKey?: string
+  flow?: AutonomyRunFlowRef
+  nowMs?: number
+}): Promise<AutonomyRunRecord> {
+  const rootDir = resolve(params.rootDir ?? getProjectRoot())
+  const currentDir = resolve(params.currentDir ?? rootDir)
+  const record: AutonomyRunRecord = {
+    runId: randomUUID(),
+    runtime: params.runtime ?? (params.flow ? 'flow_step' : 'automatic'),
+    trigger: params.trigger,
+    status: 'queued',
+    rootDir,
+    currentDir,
+    ownerKey:
+      params.flow?.ownerKey ?? params.ownerKey ?? DEFAULT_AUTONOMY_OWNER_KEY,
+    ...(params.sourceId ? { sourceId: params.sourceId } : {}),
+    ...(params.sourceLabel ? { sourceLabel: params.sourceLabel } : {}),
+    ...(params.flow
+      ? {
+          parentFlowId: params.flow.flowId,
+          parentFlowKey: params.flow.flowKey,
+          parentFlowSyncMode: params.flow.syncMode,
+          flowStepId: params.flow.stepId,
+          flowStepName: params.flow.stepName,
+        }
+      : {}),
+    promptPreview: truncatePromptPreview(params.prompt),
+    createdAt: params.nowMs ?? Date.now(),
+  }
+  await withAutonomyPersistenceLock(rootDir, async () => {
+    const runs = await listAutonomyRuns(rootDir)
+    runs.unshift(record)
+    await writeAutonomyRuns(runs, rootDir)
+  })
+  if (
+    record.parentFlowId &&
+    record.flowStepId &&
+    record.parentFlowSyncMode === 'managed'
+  ) {
+    const stepIndex =
+      (
+        await getAutonomyFlowById(record.parentFlowId, rootDir)
+      )?.stateJson?.steps.findIndex(
+        step => step.stepId === record.flowStepId,
+      ) ?? 0
+    await queueManagedAutonomyFlowStepRun({
+      flowId: record.parentFlowId,
+      stepId: record.flowStepId,
+      stepIndex: stepIndex >= 0 ? stepIndex : 0,
+      runId: record.runId,
+      rootDir,
+      nowMs: record.createdAt,
+    })
+  }
+  return record
+}
+
+function buildManagedFlowStepPrompt(
+  flow: AutonomyFlowRecord,
+  stepIndex: number,
+): string {
+  const state = flow.stateJson
+  const step = state?.steps[stepIndex]
+  if (!state || !step) {
+    return flow.goal
+  }
+  const completed = state.steps
+    .slice(0, stepIndex)
+    .filter(candidate => candidate.status === 'completed')
+    .map(candidate => `- ${candidate.name}`)
+  const remaining = state.steps
+    .slice(stepIndex + 1)
+    .map(candidate => `- ${candidate.name}`)
+
+  return [
+    `This is step ${stepIndex + 1}/${state.steps.length} of the managed autonomy flow "${flow.goal}".`,
+    '<autonomy_flow>',
+    `Flow ID: ${flow.flowId}`,
+    `Flow source: ${flow.sourceLabel ?? flow.sourceId ?? 'automatic'}`,
+    `Current step: ${step.name}`,
+    completed.length > 0
+      ? ['Completed steps:', ...completed].join('\n')
+      : 'Completed steps: none',
+    remaining.length > 0
+      ? ['Remaining steps after this one:', ...remaining].join('\n')
+      : 'Remaining steps after this one: none',
+    '</autonomy_flow>',
+    step.prompt,
+  ].join('\n\n')
+}
+
+async function createOrRecoverManagedFlowStepCommand(params: {
+  flowId: string
+  rootDir?: string
+  currentDir?: string
+  priority?: 'now' | 'next' | 'later'
+  workload?: string
+}): Promise<QueuedCommand | null> {
+  const rootDir = resolve(params.rootDir ?? getProjectRoot())
+  const flow = await getAutonomyFlowById(params.flowId, rootDir)
+  if (!flow || flow.status !== 'queued' || !flow.stateJson) {
+    return null
+  }
+  const stepIndex = flow.stateJson.currentStepIndex
+  const step = flow.stateJson.steps[stepIndex]
+  if (!step) {
+    return null
+  }
+  if (step.status === 'queued' && step.runId) {
+    const run = await getAutonomyRunById(step.runId, rootDir)
+    if (run && run.status === 'queued' && !run.startedAt && !run.endedAt) {
+      const value = await buildAutonomyTurnPrompt({
+        basePrompt: buildManagedFlowStepPrompt(flow, stepIndex),
+        trigger: 'managed-flow-step',
+        rootDir,
+        currentDir: params.currentDir ?? flow.currentDir,
+      })
+      const origin = {
+        kind: 'autonomy',
+        trigger: 'managed-flow-step',
+        runId: run.runId,
+        ...(run.sourceId ? { sourceId: run.sourceId } : {}),
+      } as unknown as MessageOrigin
+      return {
+        value,
+        mode: 'prompt',
+        priority: params.priority ?? 'later',
+        isMeta: true,
+        origin,
+        workload: params.workload,
+        autonomy: {
+          runId: run.runId,
+          trigger: 'managed-flow-step',
+          sourceId: run.sourceId,
+          sourceLabel: run.sourceLabel,
+          ...(run.parentFlowId ? { flowId: run.parentFlowId } : {}),
+          ...(run.flowStepId ? { flowStepId: run.flowStepId } : {}),
+          ...(run.flowStepName ? { flowStepName: run.flowStepName } : {}),
+        },
+      }
+    }
+    return null
+  }
+  if (step.status !== 'pending' || step.runId) {
+    return null
+  }
+  return createAutonomyQueuedPrompt({
+    basePrompt: buildManagedFlowStepPrompt(flow, stepIndex),
+    trigger: 'managed-flow-step',
+    rootDir,
+    currentDir: params.currentDir ?? flow.currentDir,
+    sourceId: flow.sourceId ?? flow.flowId,
+    sourceLabel: flow.sourceLabel ?? flow.goal,
+    workload: params.workload,
+    priority: params.priority,
+    flow: {
+      flowId: flow.flowId,
+      flowKey: flow.flowKey,
+      syncMode: 'managed',
+      ownerKey: flow.ownerKey,
+      stepId: step.stepId,
+      stepName: step.name,
+    },
+  })
+}
+
+async function queueCurrentManagedFlowStepCommand(params: {
+  flowId: string
+  rootDir?: string
+  currentDir?: string
+  priority?: 'now' | 'next' | 'later'
+  workload?: string
+}): Promise<QueuedCommand | null> {
+  return createOrRecoverManagedFlowStepCommand(params)
+}
+
+export async function startManagedAutonomyFlowFromHeartbeatTask(params: {
+  task: HeartbeatAuthorityTask
+  rootDir?: string
+  currentDir?: string
+  ownerKey?: string
+  priority?: 'now' | 'next' | 'later'
+  workload?: string
+}): Promise<QueuedCommand | null> {
+  if (params.task.steps.length === 0) {
+    return null
+  }
+  const rootDir = resolve(params.rootDir ?? getProjectRoot())
+  const currentDir = resolve(params.currentDir ?? getCwd())
+  const started = await startManagedAutonomyFlow({
+    trigger: 'proactive-tick',
+    goal: params.task.prompt,
+    steps: params.task.steps.map<ManagedAutonomyFlowStepDefinition>(step => ({
+      name: step.name,
+      prompt: step.prompt,
+      ...(step.waitFor ? { waitFor: step.waitFor } : {}),
+    })),
+    rootDir,
+    currentDir,
+    ownerKey: params.ownerKey,
+    sourceId: `heartbeat:${params.task.name}`,
+    sourceLabel: params.task.name,
+  })
+  if (!started) {
+    return null
+  }
+  return createOrRecoverManagedFlowStepCommand({
+    flowId: started.flow.flowId,
+    rootDir,
+    currentDir,
+    priority: params.priority,
+    workload: params.workload,
+  })
+}
+
+export async function markAutonomyRunRunning(
+  runId: string,
+  rootDir?: string,
+  nowMs?: number,
+): Promise<AutonomyRunRecord | null> {
+  const updated = await updateAutonomyRun(
+    runId,
+    current => ({
+      ...current,
+      status: 'running',
+      startedAt: nowMs ?? Date.now(),
+    }),
+    rootDir,
+  )
+  if (updated?.parentFlowId && updated.parentFlowSyncMode === 'managed') {
+    await markManagedAutonomyFlowStepRunning({
+      flowId: updated.parentFlowId,
+      runId: updated.runId,
+      rootDir,
+      nowMs: updated.startedAt,
+    })
+  }
+  return updated
+}
+
+export async function markAutonomyRunCompleted(
+  runId: string,
+  rootDir?: string,
+  nowMs?: number,
+): Promise<AutonomyRunRecord | null> {
+  const updated = await updateAutonomyRun(
+    runId,
+    current => ({
+      ...current,
+      status: 'completed',
+      endedAt: nowMs ?? Date.now(),
+      error: undefined,
+    }),
+    rootDir,
+  )
+  if (updated?.parentFlowId && updated.parentFlowSyncMode === 'managed') {
+    await markManagedAutonomyFlowStepCompleted({
+      flowId: updated.parentFlowId,
+      runId: updated.runId,
+      rootDir,
+      nowMs: updated.endedAt,
+    })
+  }
+  return updated
+}
+
+export async function markAutonomyRunFailed(
+  runId: string,
+  error: string,
+  rootDir?: string,
+  nowMs?: number,
+): Promise<AutonomyRunRecord | null> {
+  const updated = await updateAutonomyRun(
+    runId,
+    current => ({
+      ...current,
+      status: 'failed',
+      endedAt: nowMs ?? Date.now(),
+      error,
+    }),
+    rootDir,
+  )
+  if (updated?.parentFlowId && updated.parentFlowSyncMode === 'managed') {
+    await markManagedAutonomyFlowStepFailed({
+      flowId: updated.parentFlowId,
+      runId: updated.runId,
+      error,
+      rootDir,
+      nowMs: updated.endedAt,
+    })
+  }
+  return updated
+}
+
+export async function markAutonomyRunCancelled(
+  runId: string,
+  rootDir?: string,
+  nowMs?: number,
+): Promise<AutonomyRunRecord | null> {
+  const updated = await updateAutonomyRun(
+    runId,
+    current => ({
+      ...current,
+      status: 'cancelled',
+      endedAt: nowMs ?? Date.now(),
+      error: undefined,
+    }),
+    rootDir,
+  )
+  if (updated?.parentFlowId && updated.parentFlowSyncMode === 'managed') {
+    await markManagedAutonomyFlowStepCancelled({
+      flowId: updated.parentFlowId,
+      runId: updated.runId,
+      rootDir,
+      nowMs: updated.endedAt,
+    })
+  }
+  return updated
+}
+
+export async function finalizeAutonomyRunCompleted(params: {
+  runId: string
+  rootDir?: string
+  currentDir?: string
+  priority?: 'now' | 'next' | 'later'
+  workload?: string
+  nowMs?: number
+}): Promise<QueuedCommand[]> {
+  const updated = await markAutonomyRunCompleted(
+    params.runId,
+    params.rootDir,
+    params.nowMs,
+  )
+  if (!updated?.parentFlowId || updated.parentFlowSyncMode !== 'managed') {
+    return []
+  }
+  const next = await queueCurrentManagedFlowStepCommand({
+    flowId: updated.parentFlowId,
+    rootDir: params.rootDir,
+    currentDir: params.currentDir ?? updated.currentDir,
+    priority: params.priority,
+    workload: params.workload,
+  })
+  return next ? [next] : []
+}
+
+export async function finalizeAutonomyRunFailed(params: {
+  runId: string
+  error: string
+  rootDir?: string
+  nowMs?: number
+}): Promise<void> {
+  await markAutonomyRunFailed(
+    params.runId,
+    params.error,
+    params.rootDir,
+    params.nowMs,
+  )
+}
+
+export async function recoverManagedAutonomyFlowPrompt(params: {
+  flowId: string
+  rootDir?: string
+  currentDir?: string
+  priority?: 'now' | 'next' | 'later'
+  workload?: string
+}): Promise<QueuedCommand | null> {
+  return createOrRecoverManagedFlowStepCommand(params)
+}
+
+export async function resumeManagedAutonomyFlowPrompt(params: {
+  flowId: string
+  rootDir?: string
+  currentDir?: string
+  priority?: 'now' | 'next' | 'later'
+  workload?: string
+  nowMs?: number
+}): Promise<QueuedCommand | null> {
+  const resumed = await resumeManagedAutonomyFlow({
+    flowId: params.flowId,
+    rootDir: params.rootDir,
+    nowMs: params.nowMs,
+  })
+  if (!resumed) {
+    return recoverManagedAutonomyFlowPrompt({
+      flowId: params.flowId,
+      rootDir: params.rootDir,
+      currentDir: params.currentDir,
+      priority: params.priority,
+      workload: params.workload,
+    })
+  }
+  return createOrRecoverManagedFlowStepCommand({
+    flowId: resumed.flow.flowId,
+    rootDir: params.rootDir,
+    currentDir: params.currentDir ?? resumed.flow.currentDir,
+    priority: params.priority,
+    workload: params.workload,
+  })
+}
+
+export async function createAutonomyQueuedPrompt(params: {
+  trigger: AutonomyTriggerKind
+  basePrompt: string
+  rootDir?: string
+  currentDir?: string
+  sourceId?: string
+  sourceLabel?: string
+  workload?: string
+  priority?: 'now' | 'next' | 'later'
+  shouldCreate?: () => boolean
+  flow?: AutonomyRunFlowRef
+}): Promise<QueuedCommand | null> {
+  const rootDir = resolve(params.rootDir ?? getProjectRoot())
+  const currentDir = resolve(params.currentDir ?? getCwd())
+  const prepared = await prepareAutonomyTurnPrompt({
+    basePrompt: params.basePrompt,
+    trigger: params.trigger,
+    rootDir,
+    currentDir,
+  })
+  if (params.shouldCreate && !params.shouldCreate()) {
+    return null
+  }
+  return commitAutonomyQueuedPrompt({
+    prepared,
+    rootDir,
+    currentDir,
+    sourceId: params.sourceId,
+    sourceLabel: params.sourceLabel,
+    workload: params.workload,
+    priority: params.priority,
+    flow: params.flow,
+  })
+}
+
+export async function commitAutonomyQueuedPrompt(params: {
+  prepared: Awaited<ReturnType<typeof prepareAutonomyTurnPrompt>>
+  rootDir?: string
+  currentDir?: string
+  sourceId?: string
+  sourceLabel?: string
+  workload?: string
+  priority?: 'now' | 'next' | 'later'
+  flow?: AutonomyRunFlowRef
+}): Promise<QueuedCommand> {
+  const rootDir = resolve(
+    params.rootDir ?? params.prepared.rootDir ?? getProjectRoot(),
+  )
+  const currentDir = resolve(
+    params.currentDir ?? params.prepared.currentDir ?? getCwd(),
+  )
+  commitPreparedAutonomyTurn(params.prepared)
+  const value = params.prepared.prompt
+  const run = await createAutonomyRun({
+    trigger: params.prepared.trigger,
+    prompt: value,
+    rootDir,
+    currentDir,
+    sourceId: params.sourceId,
+    sourceLabel: params.sourceLabel,
+    flow: params.flow,
+  })
+  const origin = {
+    kind: 'autonomy',
+    trigger: params.prepared.trigger,
+    runId: run.runId,
+    ...(params.sourceId ? { sourceId: params.sourceId } : {}),
+  } as unknown as MessageOrigin
+
+  return {
+    value,
+    mode: 'prompt',
+    priority: params.priority ?? 'later',
+    isMeta: true,
+    origin,
+    workload: params.workload,
+    autonomy: {
+      runId: run.runId,
+      trigger: params.prepared.trigger,
+      sourceId: params.sourceId,
+      sourceLabel: params.sourceLabel,
+      ...(run.parentFlowId ? { flowId: run.parentFlowId } : {}),
+      ...(run.flowStepId ? { flowStepId: run.flowStepId } : {}),
+      ...(run.flowStepName ? { flowStepName: run.flowStepName } : {}),
+    },
+  }
+}
+
+export async function createProactiveAutonomyCommands(params: {
+  basePrompt: string
+  rootDir?: string
+  currentDir?: string
+  workload?: string
+  priority?: 'now' | 'next' | 'later'
+  shouldCreate?: () => boolean
+}): Promise<QueuedCommand[]> {
+  const rootDir = resolve(params.rootDir ?? getProjectRoot())
+  const currentDir = resolve(params.currentDir ?? getCwd())
+  const prepared = await prepareAutonomyTurnPrompt({
+    basePrompt: params.basePrompt,
+    trigger: 'proactive-tick',
+    rootDir,
+    currentDir,
+  })
+  if (params.shouldCreate && !params.shouldCreate()) {
+    return []
+  }
+
+  const commands: QueuedCommand[] = [
+    await commitAutonomyQueuedPrompt({
+      prepared,
+      rootDir,
+      currentDir,
+      workload: params.workload,
+      priority: params.priority,
+    }),
+  ]
+
+  for (const task of prepared.dueHeartbeatTasks) {
+    if (task.steps.length === 0) {
+      continue
+    }
+    if (params.shouldCreate && !params.shouldCreate()) {
+      break
+    }
+    const flowCommand = await startManagedAutonomyFlowFromHeartbeatTask({
+      task,
+      rootDir,
+      currentDir,
+      priority: params.priority,
+      workload: params.workload,
+    })
+    if (flowCommand) {
+      commands.push(flowCommand)
+    }
+  }
+
+  return commands
+}
+
+export function formatAutonomyRunsStatus(runs: AutonomyRunRecord[]): string {
+  const counts = {
+    queued: 0,
+    running: 0,
+    completed: 0,
+    failed: 0,
+    cancelled: 0,
+  }
+  for (const run of runs) {
+    counts[run.status] += 1
+  }
+  const latest = runs[0]
+  const latestLine = latest
+    ? `Latest: ${latest.trigger} ${latest.status} (${new Date(latest.createdAt).toLocaleString()})`
+    : 'Latest: none'
+  return [
+    `Autonomy runs: ${runs.length}`,
+    `Queued: ${counts.queued}`,
+    `Running: ${counts.running}`,
+    `Completed: ${counts.completed}`,
+    `Failed: ${counts.failed}`,
+    `Cancelled: ${counts.cancelled}`,
+    latestLine,
+  ].join('\n')
+}
+
+export function formatAutonomyRunsList(
+  runs: AutonomyRunRecord[],
+  limit = 10,
+): string {
+  const slice = runs.slice(0, limit)
+  if (slice.length === 0) {
+    return 'No autonomy runs recorded.'
+  }
+  return slice
+    .map(run => {
+      const source = run.sourceLabel ?? run.sourceId ?? 'auto'
+      const flow =
+        run.parentFlowId && run.flowStepName
+          ? ` | flow=${run.parentFlowId} step=${run.flowStepName}`
+          : ''
+      const ended =
+        run.endedAt != null
+          ? ` -> ${new Date(run.endedAt).toLocaleTimeString()}`
+          : ''
+      const error = run.error ? ` | ${run.error}` : ''
+      return `${run.runId} | ${run.runtime} | ${run.trigger} | ${run.status} | ${source}${flow} | ${new Date(run.createdAt).toLocaleTimeString()}${ended}\n  ${run.promptPreview}${error}`
+    })
+    .join('\n')
+}
diff --git a/src/utils/cliLaunch.ts b/src/utils/cliLaunch.ts
new file mode 100644
index 000000000..02c3b403a
--- /dev/null
+++ b/src/utils/cliLaunch.ts
@@ -0,0 +1,180 @@
+import { type ChildProcess, spawn, type SpawnOptions } from 'child_process'
+import { isInBundledMode } from './bundledMode.js'
+import { quote } from './bash/shellQuote.js'
+
+/**
+ * CliLaunchSpec — normalized descriptor for spawning a child CLI process.
+ *
+ * Every site that re-execs the CLI (daemon workers, bg sessions, bridge
+ * sessions, assistant/RCS daemon launchers) should use this instead of
+ * manually assembling `[...process.execArgv, process.argv[1]!, ...]`.
+ *
+ * Centralizing the bootstrap contract prevents the class of bugs where
+ * individual spawn sites forget execArgv, windowsHide, or env propagation.
+ */
+export interface CliLaunchSpec {
+  /** Runtime binary path (e.g. bun, node). */
+  execPath: string
+  /** Full argument list including bootstrap args and CLI args. */
+  args: string[]
+  /** Environment for the child process. */
+  env: NodeJS.ProcessEnv
+  /** Whether to hide the console window on Windows. */
+  windowsHide: boolean
+}
+
+// ---------------------------------------------------------------------------
+// Frozen bootstrap snapshot — computed once at module load time.
+//
+// Bun quirk (https://github.com/oven-sh/bun/issues/11673): in single-file
+// executables, app arguments from process.argv can leak into process.execArgv.
+// We snapshot and filter once, so every child gets a clean, stable set of
+// runtime flags regardless of when buildCliLaunch is called.
+// ---------------------------------------------------------------------------
+
+/**
+ * Filter out leaked application arguments from process.execArgv.
+ * Only keep known runtime flags: -d (defines), --feature, --inspect variants.
+ */
+function sanitizeExecArgv(raw: readonly string[]): string[] {
+  const result: string[] = []
+  for (let i = 0; i < raw.length; i++) {
+    const arg = raw[i]!
+    // Bun define flags: -d KEY:VALUE or -dKEY:VALUE
+    if (arg === '-d' || arg.startsWith('-d ') || arg.startsWith('-d\t')) {
+      result.push(arg)
+      if (arg === '-d' && i + 1 < raw.length) {
+        result.push(raw[++i]!)
+      }
+      continue
+    }
+    if (arg.startsWith('-d') && arg.includes(':')) {
+      result.push(arg)
+      continue
+    }
+    // Bun feature flags: --feature NAME
+    if (arg === '--feature') {
+      result.push(arg)
+      if (i + 1 < raw.length) {
+        result.push(raw[++i]!)
+      }
+      continue
+    }
+    // Node/Bun inspect flags
+    if (/^--inspect(-brk)?(=|$)/.test(arg)) {
+      result.push(arg)
+      continue
+    }
+    // Keep other known runtime flags (e.g. --conditions, --experimental-*)
+    if (arg.startsWith('--') && !arg.includes('=') && i + 1 < raw.length) {
+      // Unknown two-part flag — skip conservatively in bundled mode only
+      if (isInBundledMode()) continue
+      result.push(arg)
+      result.push(raw[++i]!)
+      continue
+    }
+    if (arg.startsWith('-') && !isInBundledMode()) {
+      result.push(arg)
+    }
+  }
+  return result
+}
+
+const BOOTSTRAP_ARGS: readonly string[] = Object.freeze(
+  sanitizeExecArgv(process.execArgv),
+)
+const SCRIPT_PATH: string | undefined = process.argv[1]
+const EXEC_PATH: string = process.execPath
+const IS_WINDOWS = process.platform === 'win32'
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a normalized launch spec for spawning a child CLI process.
+ *
+ * @param cliArgs  Arguments to pass to the CLI entrypoint (e.g. ['daemon', 'start'])
+ * @param opts.env Override environment (defaults to process.env)
+ */
+export function buildCliLaunch(
+  cliArgs: string[],
+  opts?: { env?: NodeJS.ProcessEnv },
+): CliLaunchSpec {
+  const baseEnv = opts?.env ?? process.env
+
+  // In bundled mode the execPath IS the CLI binary — no script path needed.
+  // In script mode (dev / npm) we need the script path between runtime flags
+  // and CLI args so the runtime knows which file to execute.
+  const args: string[] =
+    isInBundledMode() || !SCRIPT_PATH
+      ? [...BOOTSTRAP_ARGS, ...cliArgs]
+      : [...BOOTSTRAP_ARGS, SCRIPT_PATH, ...cliArgs]
+
+  // Ensure Windows children can discover git-bash without shelling out
+  const env: NodeJS.ProcessEnv = { ...baseEnv }
+  if (IS_WINDOWS) {
+    if (
+      process.env.CLAUDE_CODE_GIT_BASH_PATH &&
+      !env.CLAUDE_CODE_GIT_BASH_PATH
+    ) {
+      env.CLAUDE_CODE_GIT_BASH_PATH = process.env.CLAUDE_CODE_GIT_BASH_PATH
+    }
+    if (process.env.SHELL && !env.SHELL) {
+      env.SHELL = process.env.SHELL
+    }
+  }
+
+  return {
+    execPath: EXEC_PATH,
+    args,
+    env,
+    windowsHide: IS_WINDOWS,
+  }
+}
+
+/**
+ * Spawn a child CLI process from a launch spec.
+ *
+ * Callers provide transport-level options (stdio, detached, cwd) while the
+ * spec handles bootstrap concerns (execPath, args, env, windowsHide).
+ *
+ * Windows note: `detached: true` on Windows creates a new console window
+ * (unlike Unix where it only creates a new process group). Node.js uses
+ * `windowsHide` to pass CREATE_NO_WINDOW, but Bun may not implement it.
+ * As a fallback, we always set both `windowsHide: true` and keep
+ * `detached` as-is — the child needs `detached` to outlive the parent.
+ */
+export function spawnCli(
+  spec: CliLaunchSpec,
+  spawnOpts: Omit<SpawnOptions, 'windowsHide'>,
+): ChildProcess {
+  return spawn(spec.execPath, spec.args, {
+    ...spawnOpts,
+    env: { ...spec.env, ...(spawnOpts.env as NodeJS.ProcessEnv) },
+    windowsHide: spec.windowsHide,
+  })
+}
+
+/**
+ * Quote a launch spec into a single shell command string (for tmux).
+ */
+export function quoteCliLaunch(spec: CliLaunchSpec): string {
+  return quote([spec.execPath, ...spec.args])
+}
+
+/**
+ * Get the frozen bootstrap args snapshot.
+ * Useful for call sites that need the raw args (e.g. bridgeMain deps).
+ */
+export function getBootstrapArgs(): readonly string[] {
+  return BOOTSTRAP_ARGS
+}
+
+/**
+ * Get the script path (process.argv[1] at startup).
+ * Returns undefined in bundled mode.
+ */
+export function getScriptPath(): string | undefined {
+  return SCRIPT_PATH
+}
diff --git a/src/utils/config.ts b/src/utils/config.ts
index ea2d3cb31..4707feaaa 100644
--- a/src/utils/config.ts
+++ b/src/utils/config.ts
@@ -334,6 +334,9 @@ export type GlobalConfig = {
   overageCreditUpsellSeenCount?: number // Number of times the overage credit upsell has been shown
   hasVisitedExtraUsage?: boolean // Whether the user has visited /extra-usage — hides credit upsells
 
+  // Display language preference
+  preferredLanguage?: 'auto' | 'en' | 'zh' // auto = follow system locale, en = English, zh = 中文
+
   // Voice mode notice tracking
   voiceNoticeSeenCount?: number // Number of times the voice-mode-available notice has been shown
   voiceLangHintShownCount?: number // Number of times the /voice dictation-language hint has been shown
@@ -556,7 +559,6 @@ export type GlobalConfig = {
   // Speculation configuration (ant-only)
   speculationEnabled?: boolean // Whether speculation is enabled (default: true)
 
-
   // Client data for server-side experiments (fetched during bootstrap).
   clientDataCache?: Record<string, unknown> | null
 
diff --git a/src/utils/handlePromptSubmit.ts b/src/utils/handlePromptSubmit.ts
index 4e514dd05..2b02df9a7 100644
--- a/src/utils/handlePromptSubmit.ts
+++ b/src/utils/handlePromptSubmit.ts
@@ -26,6 +26,12 @@ import { fileHistoryEnabled, fileHistoryMakeSnapshot } from './fileHistory.js'
 import { gracefulShutdownSync } from './gracefulShutdown.js'
 import { enqueue } from './messageQueueManager.js'
 import { resolveSkillModelOverride } from './model/model.js'
+import {
+  finalizeAutonomyRunCompleted,
+  finalizeAutonomyRunFailed,
+  markAutonomyRunFailed,
+  markAutonomyRunRunning,
+} from './autonomyRuns.js'
 import type { ProcessUserInputContext } from './processUserInput/processUserInput.js'
 import { processUserInput } from './processUserInput/processUserInput.js'
 import type { QueryGuard } from './QueryGuard.js'
@@ -460,6 +466,7 @@ async function executeUserInput(params: ExecuteUserInputParams): Promise<void> {
       commands.every(c => c.workload === firstWorkload)
         ? firstWorkload
         : undefined
+    let autonomyRunIds: string[] | undefined
 
     // Wrap the entire turn (processUserInput loop + onQuery) in an
     // AsyncLocalStorage context. This is the ONLY way to correctly
@@ -469,131 +476,159 @@ async function executeUserInput(params: ExecuteUserInputParams): Promise<void> {
     // context — isolated from the parent's continuation. A process-global
     // mutable slot would be clobbered at the detached closure's first
     // await by this function's synchronous return path. See state.ts.
-    await runWithWorkload(turnWorkload, async () => {
-      for (let i = 0; i < commands.length; i++) {
-        const cmd = commands[i]!
-        const isFirst = i === 0
-        const result = await processUserInput({
-          input: cmd.value,
-          preExpansionInput: cmd.preExpansionValue,
-          mode: cmd.mode,
-          setToolJSX,
-          context: makeContext(),
-          pastedContents: isFirst ? cmd.pastedContents : undefined,
-          messages,
-          setUserInputOnProcessing: isFirst
-            ? setUserInputOnProcessing
-            : undefined,
-          isAlreadyProcessing: !isFirst,
-          querySource,
-          canUseTool,
-          uuid: cmd.uuid,
-          ideSelection: isFirst ? ideSelection : undefined,
-          skipSlashCommands: cmd.skipSlashCommands,
-          bridgeOrigin: cmd.bridgeOrigin,
-          isMeta: cmd.isMeta,
-          skipAttachments: !isFirst,
-        })
-        // Stamp origin here rather than threading another arg through
-        // processUserInput → processUserInputBase → processTextPrompt → createUserMessage.
-        // Derive origin from mode for task-notifications — mirrors the origin
-        // derivation at messages.ts (case 'queued_command'); intentionally
-        // does NOT mirror its isMeta:true so idle-dequeued notifications stay
-        // visible in the transcript via UserAgentNotificationMessage.
-        const origin =
-          cmd.origin ??
-          (cmd.mode === 'task-notification'
-            ? ({ kind: 'task-notification' } as const)
-            : undefined)
-        if (origin) {
-          for (const m of result.messages) {
-            if (m.type === 'user') m.origin = origin
+    try {
+      await runWithWorkload(turnWorkload, async () => {
+        for (let i = 0; i < commands.length; i++) {
+          const cmd = commands[i]!
+          const isFirst = i === 0
+          if (cmd.autonomy?.runId) {
+            ;(autonomyRunIds ??= []).push(cmd.autonomy.runId)
+            await markAutonomyRunRunning(cmd.autonomy.runId)
+          }
+          const result = await processUserInput({
+            input: cmd.value,
+            preExpansionInput: cmd.preExpansionValue,
+            mode: cmd.mode,
+            setToolJSX,
+            context: makeContext(),
+            pastedContents: isFirst ? cmd.pastedContents : undefined,
+            messages,
+            setUserInputOnProcessing: isFirst
+              ? setUserInputOnProcessing
+              : undefined,
+            isAlreadyProcessing: !isFirst,
+            querySource,
+            canUseTool,
+            uuid: cmd.uuid,
+            ideSelection: isFirst ? ideSelection : undefined,
+            skipSlashCommands: cmd.skipSlashCommands,
+            bridgeOrigin: cmd.bridgeOrigin,
+            isMeta: cmd.isMeta,
+            skipAttachments: !isFirst,
+          })
+          // Stamp origin here rather than threading another arg through
+          // processUserInput → processUserInputBase → processTextPrompt → createUserMessage.
+          // Derive origin from mode for task-notifications — mirrors the origin
+          // derivation at messages.ts (case 'queued_command'); intentionally
+          // does NOT mirror its isMeta:true so idle-dequeued notifications stay
+          // visible in the transcript via UserAgentNotificationMessage.
+          const origin =
+            cmd.origin ??
+            (cmd.mode === 'task-notification'
+              ? ({ kind: 'task-notification' } as const)
+              : undefined)
+          if (origin) {
+            for (const m of result.messages) {
+              if (m.type === 'user') m.origin = origin
+            }
+          }
+          newMessages.push(...result.messages)
+          if (isFirst) {
+            shouldQuery = result.shouldQuery
+            allowedTools = result.allowedTools
+            model = result.model
+            effort = result.effort
+            nextInput = result.nextInput
+            submitNextInput = result.submitNextInput
           }
         }
-        newMessages.push(...result.messages)
-        if (isFirst) {
-          shouldQuery = result.shouldQuery
-          allowedTools = result.allowedTools
-          model = result.model
-          effort = result.effort
-          nextInput = result.nextInput
-          submitNextInput = result.submitNextInput
+
+        queryCheckpoint('query_process_user_input_end')
+        if (fileHistoryEnabled()) {
+          queryCheckpoint('query_file_history_snapshot_start')
+          newMessages.filter(selectableUserMessagesFilter).forEach(message => {
+            void fileHistoryMakeSnapshot(
+              (updater: (prev: FileHistoryState) => FileHistoryState) => {
+                setAppState(prev => ({
+                  ...prev,
+                  fileHistory: updater(prev.fileHistory),
+                }))
+              },
+              message.uuid,
+            )
+          })
+          queryCheckpoint('query_file_history_snapshot_end')
         }
-      }
 
-      queryCheckpoint('query_process_user_input_end')
-      if (fileHistoryEnabled()) {
-        queryCheckpoint('query_file_history_snapshot_start')
-        newMessages.filter(selectableUserMessagesFilter).forEach(message => {
-          void fileHistoryMakeSnapshot(
-            (updater: (prev: FileHistoryState) => FileHistoryState) => {
-              setAppState(prev => ({
-                ...prev,
-                fileHistory: updater(prev.fileHistory),
-              }))
-            },
-            message.uuid,
-          )
-        })
-        queryCheckpoint('query_file_history_snapshot_end')
-      }
+        if (newMessages.length) {
+          // History is now added in the caller (onSubmit) for direct user submissions.
+          // This ensures queued command processing (notifications, already-queued user input)
+          // doesn't add to history, since those either shouldn't be in history or were
+          // already added when originally queued.
+          resetHistory()
+          setToolJSX({
+            jsx: null,
+            shouldHidePromptInput: false,
+            clearLocalJSX: true,
+          })
 
-      if (newMessages.length) {
-        // History is now added in the caller (onSubmit) for direct user submissions.
-        // This ensures queued command processing (notifications, already-queued user input)
-        // doesn't add to history, since those either shouldn't be in history or were
-        // already added when originally queued.
-        resetHistory()
-        setToolJSX({
-          jsx: null,
-          shouldHidePromptInput: false,
-          clearLocalJSX: true,
-        })
+          const primaryCmd = commands[0]
+          const primaryMode = primaryCmd?.mode ?? 'prompt'
+          const primaryInput =
+            primaryCmd && typeof primaryCmd.value === 'string'
+              ? primaryCmd.value
+              : undefined
+          const shouldCallBeforeQuery = primaryMode === 'prompt'
+          await onQuery(
+            newMessages,
+            abortController,
+            shouldQuery,
+            allowedTools ?? [],
+            model
+              ? resolveSkillModelOverride(model, mainLoopModel)
+              : mainLoopModel,
+            shouldCallBeforeQuery ? onBeforeQuery : undefined,
+            primaryInput,
+            effort,
+          )
+        } else {
+          // Local slash commands that skip messages (e.g., /model, /theme).
+          // Release the guard BEFORE clearing toolJSX to prevent spinner flash —
+          // the spinner formula checks: (!toolJSX || showSpinner) && isLoading.
+          // If we clear toolJSX while the guard is still reserved, spinner briefly
+          // shows. The finally below also calls cancelReservation (no-op if idle).
+          queryGuard.cancelReservation()
+          setToolJSX({
+            jsx: null,
+            shouldHidePromptInput: false,
+            clearLocalJSX: true,
+          })
+          resetHistory()
+          setAbortController(null)
+        }
 
-        const primaryCmd = commands[0]
-        const primaryMode = primaryCmd?.mode ?? 'prompt'
-        const primaryInput =
-          primaryCmd && typeof primaryCmd.value === 'string'
-            ? primaryCmd.value
-            : undefined
-        const shouldCallBeforeQuery = primaryMode === 'prompt'
-        await onQuery(
-          newMessages,
-          abortController,
-          shouldQuery,
-          allowedTools ?? [],
-          model
-            ? resolveSkillModelOverride(model, mainLoopModel)
-            : mainLoopModel,
-          shouldCallBeforeQuery ? onBeforeQuery : undefined,
-          primaryInput,
-          effort,
-        )
-      } else {
-        // Local slash commands that skip messages (e.g., /model, /theme).
-        // Release the guard BEFORE clearing toolJSX to prevent spinner flash —
-        // the spinner formula checks: (!toolJSX || showSpinner) && isLoading.
-        // If we clear toolJSX while the guard is still reserved, spinner briefly
-        // shows. The finally below also calls cancelReservation (no-op if idle).
-        queryGuard.cancelReservation()
-        setToolJSX({
-          jsx: null,
-          shouldHidePromptInput: false,
-          clearLocalJSX: true,
-        })
-        resetHistory()
-        setAbortController(null)
+        // Handle nextInput from commands that want to chain (e.g., /discover activation)
+        if (nextInput) {
+          if (submitNextInput) {
+            enqueue({ value: nextInput, mode: 'prompt' })
+          } else {
+            params.onInputChange(nextInput)
+          }
+        }
+      }) // end runWithWorkload — ALS context naturally scoped, no finally needed
+      if (autonomyRunIds?.length) {
+        for (const runId of autonomyRunIds) {
+          const nextCommands = await finalizeAutonomyRunCompleted({
+            runId,
+            priority: 'later',
+            workload: turnWorkload,
+          })
+          for (const nextCommand of nextCommands) {
+            enqueue(nextCommand)
+          }
+        }
       }
-
-      // Handle nextInput from commands that want to chain (e.g., /discover activation)
-      if (nextInput) {
-        if (submitNextInput) {
-          enqueue({ value: nextInput, mode: 'prompt' })
-        } else {
-          params.onInputChange(nextInput)
+    } catch (error) {
+      if (autonomyRunIds?.length) {
+        for (const runId of autonomyRunIds) {
+          await finalizeAutonomyRunFailed({
+            runId,
+            error: String(error),
+          })
         }
       }
-    }) // end runWithWorkload — ALS context naturally scoped, no finally needed
+      throw error
+    }
   } finally {
     // Safety net: release the guard reservation if processUserInput threw
     // or onQuery was skipped. No-op if onQuery already ran (guard is idle
diff --git a/src/utils/language.ts b/src/utils/language.ts
new file mode 100644
index 000000000..8f3f2c968
--- /dev/null
+++ b/src/utils/language.ts
@@ -0,0 +1,26 @@
+import { getGlobalConfig } from './config.js'
+import { getSystemLocaleLanguage } from './intl.js'
+
+export type PreferredLanguage = 'auto' | 'en' | 'zh'
+export type ResolvedLanguage = 'en' | 'zh'
+
+/**
+ * Resolve the effective display language.
+ * Priority: GlobalConfig.preferredLanguage → system locale → default 'en'.
+ */
+export function getResolvedLanguage(): ResolvedLanguage {
+  const pref = getGlobalConfig().preferredLanguage ?? 'auto'
+  if (pref === 'en' || pref === 'zh') return pref
+  const sysLang = getSystemLocaleLanguage()
+  return sysLang === 'zh' ? 'zh' : 'en'
+}
+
+const DISPLAY_NAMES: Record<string, string> = {
+  auto: 'Auto (follow system)',
+  en: 'English',
+  zh: '中文',
+}
+
+export function getLanguageDisplayName(lang: string): string {
+  return DISPLAY_NAMES[lang] ?? lang
+}
diff --git a/src/utils/pipeMuteState.ts b/src/utils/pipeMuteState.ts
new file mode 100644
index 000000000..a906507b2
--- /dev/null
+++ b/src/utils/pipeMuteState.ts
@@ -0,0 +1,78 @@
+/**
+ * pipeMuteState — Master-side logical disconnect state.
+ *
+ * Tracks which slave pipes are currently "muted" (logically disconnected)
+ * and which have a temporary `/send` override active.
+ *
+ * This is local master state only — not part of the socket protocol.
+ */
+
+// ---------------------------------------------------------------------------
+// Muted set: slaves whose business messages should be dropped by master
+// ---------------------------------------------------------------------------
+
+const _mutedPipes = new Set<string>()
+
+export function setMasterMutedPipes(names: Iterable<string>): void {
+  _mutedPipes.clear()
+  for (const n of names) _mutedPipes.add(n)
+}
+
+export function isMasterPipeMuted(name: string): boolean {
+  return _mutedPipes.has(name)
+}
+
+export function removeMasterPipeMute(name: string): void {
+  _mutedPipes.delete(name)
+}
+
+export function clearMasterMutedPipes(): void {
+  _mutedPipes.clear()
+}
+
+// ---------------------------------------------------------------------------
+// Send override set: slaves temporarily unmuted by explicit `/send` command.
+// Override lasts until the slave emits `done` or `error`.
+// ---------------------------------------------------------------------------
+
+const _sendOverrides = new Set<string>()
+let _sendOverrideVersion = 0
+const _sendOverrideListeners = new Set<() => void>()
+
+function emitSendOverrideChanged(): void {
+  _sendOverrideVersion += 1
+  for (const listener of _sendOverrideListeners) {
+    listener()
+  }
+}
+
+export function addSendOverride(name: string): void {
+  _sendOverrides.add(name)
+  emitSendOverrideChanged()
+}
+
+export function removeSendOverride(name: string): void {
+  if (_sendOverrides.delete(name)) {
+    emitSendOverrideChanged()
+  }
+}
+
+export function hasSendOverride(name: string): boolean {
+  return _sendOverrides.has(name)
+}
+
+export function clearSendOverrides(): void {
+  if (_sendOverrides.size > 0) {
+    _sendOverrides.clear()
+    emitSendOverrideChanged()
+  }
+}
+
+export function subscribeSendOverride(listener: () => void): () => void {
+  _sendOverrideListeners.add(listener)
+  return () => { _sendOverrideListeners.delete(listener) }
+}
+
+export function getSendOverrideVersion(): number {
+  return _sendOverrideVersion
+}
diff --git a/src/utils/pipePermissionRelay.ts b/src/utils/pipePermissionRelay.ts
index e02638491..c32815d6e 100644
--- a/src/utils/pipePermissionRelay.ts
+++ b/src/utils/pipePermissionRelay.ts
@@ -19,8 +19,22 @@ const pendingPipePermissions = new Map<string, PendingPipePermission>()
 type PipeRelayFn = (message: PipeMessage) => void
 let _pipeRelay: PipeRelayFn | null = null
 
+// Slave-side mute flag: when true, relayPipeMessage() and permission
+// relay functions will short-circuit. Set by relay_mute / relay_unmute
+// control messages from master.
+let _relayMuted = false
+
+export function setRelayMuted(muted: boolean): void {
+  _relayMuted = muted
+}
+
+export function isRelayMuted(): boolean {
+  return _relayMuted
+}
+
 export function setPipeRelay(fn: PipeRelayFn | null): void {
   _pipeRelay = fn
+  if (!fn) _relayMuted = false // reset on disconnect
 }
 
 export function getPipeRelay(): PipeRelayFn | null {
@@ -37,6 +51,7 @@ export function tryRelayPipePermissionRequest(
   toolUseConfirm: ToolUseConfirm,
   onResponse: (payload: PipePermissionResponsePayload) => void,
 ): string | null {
+  if (_relayMuted) return null
   const send = getPipeSender()
   if (!send) return null
 
@@ -93,6 +108,7 @@ export function notifyPipePermissionCancel(
   reason?: string,
 ): void {
   if (!requestId) return
+  if (_relayMuted) return
   const send = getPipeSender()
   if (!send) return
   send({
diff --git a/src/utils/pipeTransport.ts b/src/utils/pipeTransport.ts
index 8f16baa25..3d1974e33 100644
--- a/src/utils/pipeTransport.ts
+++ b/src/utils/pipeTransport.ts
@@ -31,7 +31,8 @@ import { attachNdjsonFramer } from './ndjsonFramer.js'
  * Message types exchanged over the pipe.
  *
  * Basic:        ping, pong
- * Control:      attach_request, attach_accept, attach_reject, detach
+ * Control:      attach_request, attach_accept, attach_reject, detach,
+ *               relay_mute, relay_unmute
  * Data (M→S):   prompt           — master sends user input to slave
  * Data (S→M):   stream           — slave streams AI output fragments
  *               tool_start       — slave notifies tool execution start
@@ -49,6 +50,9 @@ export type PipeMessageType =
   | 'attach_accept'
   | 'attach_reject'
   | 'detach'
+  // Mute control (master → slave): logical disconnect without dropping transport
+  | 'relay_mute'
+  | 'relay_unmute'
   // Data flow (master → slave)
   | 'prompt'
   // Data flow (slave → master)
diff --git a/src/utils/swarm/inProcessRunner.ts b/src/utils/swarm/inProcessRunner.ts
index 3faf2598b..1735500b4 100644
--- a/src/utils/swarm/inProcessRunner.ts
+++ b/src/utils/swarm/inProcessRunner.ts
@@ -66,6 +66,11 @@ import { evictTerminalTask } from '../../utils/task/framework.js'
 import { tokenCountWithEstimation } from '../../utils/tokens.js'
 import { createAbortController } from '../abortController.js'
 import { type AgentContext, runWithAgentContext } from '../agentContext.js'
+import {
+  markAutonomyRunCompleted,
+  markAutonomyRunFailed,
+  markAutonomyRunRunning,
+} from '../autonomyRuns.js'
 import { count } from '../array.js'
 import { logForDebugging } from '../debug.js'
 import { cloneFileStateCache } from '../fileStateCache.js'
@@ -668,6 +673,7 @@ type WaitResult =
   | {
       type: 'new_message'
       message: string
+      autonomyRunId?: string
       from: string
       color?: string
       summary?: string
@@ -710,7 +716,7 @@ async function waitForNextPromptOrShutdown(
       task.type === 'in_process_teammate' &&
       task.pendingUserMessages.length > 0
     ) {
-      const message = task.pendingUserMessages[0]! // Safe: checked length > 0
+      const pending = task.pendingUserMessages[0]! // Safe: checked length > 0
       // Pop the message from the queue
       setAppState(prev => {
         const prevTask = prev.tasks[taskId]
@@ -731,9 +737,13 @@ async function waitForNextPromptOrShutdown(
       logForDebugging(
         `[inProcessRunner] ${identity.agentName} found pending user message (poll #${pollCount})`,
       )
+      if (pending.autonomyRunId) {
+        await markAutonomyRunRunning(pending.autonomyRunId)
+      }
       return {
         type: 'new_message',
-        message,
+        message: pending.message,
+        autonomyRunId: pending.autonomyRunId,
         from: 'user',
       }
     }
@@ -1010,6 +1020,7 @@ export async function runInProcessTeammate(
     description,
   )
   let currentPrompt = wrappedInitialPrompt
+  let currentAutonomyRunId: string | undefined
   let shouldExit = false
 
   // Try to claim an available task immediately so the UI can show activity
@@ -1306,6 +1317,13 @@ export async function runInProcessTeammate(
           }),
           setAppState,
         )
+        if (currentAutonomyRunId) {
+          await markAutonomyRunFailed(currentAutonomyRunId, ERROR_MESSAGE_USER_ABORT)
+          currentAutonomyRunId = undefined
+        }
+      } else if (currentAutonomyRunId) {
+        await markAutonomyRunCompleted(currentAutonomyRunId)
+        currentAutonomyRunId = undefined
       }
 
       // Check if already idle before updating (to skip duplicate notification)
@@ -1378,6 +1396,7 @@ export async function runInProcessTeammate(
             createUserMessage({ content: currentPrompt }),
             setAppState,
           )
+          currentAutonomyRunId = undefined
           break
 
         case 'new_message':
@@ -1389,6 +1408,7 @@ export async function runInProcessTeammate(
           // Messages from other teammates get XML wrapper for identification
           if (waitResult.from === 'user') {
             currentPrompt = waitResult.message
+            currentAutonomyRunId = waitResult.autonomyRunId
           } else {
             currentPrompt = formatAsTeammateMessage(
               waitResult.from,
@@ -1404,6 +1424,7 @@ export async function runInProcessTeammate(
               createUserMessage({ content: currentPrompt }),
               setAppState,
             )
+            currentAutonomyRunId = undefined
           }
           break
 
@@ -1459,7 +1480,6 @@ export async function runInProcessTeammate(
         summary: identity.agentId,
       })
     }
-
     unregisterPerfettoAgent(identity.agentId)
     return { success: true, messages: allMessages }
   } catch (error) {
@@ -1511,6 +1531,9 @@ export async function runInProcessTeammate(
         summary: identity.agentId,
       })
     }
+    if (currentAutonomyRunId) {
+      await markAutonomyRunFailed(currentAutonomyRunId, errorMessage)
+    }
 
     // Send idle notification with failure via file-based mailbox
     await sendIdleNotification(
diff --git a/src/utils/swarm/spawnInProcess.ts b/src/utils/swarm/spawnInProcess.ts
index 7f548f28a..1a4f6c857 100644
--- a/src/utils/swarm/spawnInProcess.ts
+++ b/src/utils/swarm/spawnInProcess.ts
@@ -24,6 +24,7 @@ import type {
   TeammateIdentity,
 } from '../../tasks/InProcessTeammateTask/types.js'
 import { createAbortController } from '../abortController.js'
+import { markAutonomyRunFailed } from '../autonomyRuns.js'
 import { formatAgentId } from '../agentId.js'
 import { registerCleanup } from '../cleanupRegistry.js'
 import { logForDebugging } from '../debug.js'
@@ -233,6 +234,7 @@ export function killInProcessTeammate(
   let agentId: string | null = null
   let toolUseId: string | undefined
   let description: string | undefined
+  let pendingAutonomyRunIds: string[] = []
 
   setAppState((prev: AppState) => {
     const task = prev.tasks[taskId]
@@ -252,6 +254,11 @@ export function killInProcessTeammate(
     toolUseId = teammateTask.toolUseId
     description = teammateTask.description
 
+    // Capture pending autonomy run IDs before clearing them
+    pendingAutonomyRunIds = teammateTask.pendingUserMessages
+      .map(message => message.autonomyRunId)
+      .filter((runId): runId is string => runId !== undefined)
+
     // Abort the controller to stop execution
     teammateTask.abortController?.abort()
 
@@ -304,6 +311,12 @@ export function killInProcessTeammate(
   }
 
   if (killed) {
+    for (const runId of pendingAutonomyRunIds) {
+      void markAutonomyRunFailed(
+        runId,
+        `Teammate ${agentId ?? taskId} was stopped before it could consume the queued autonomy prompt.`,
+      )
+    }
     void evictTaskOutput(taskId)
     // notified:true was pre-set so no XML notification fires; close the SDK
     // task_started bookend directly. The in-process runner's own
diff --git a/src/utils/taskSummary.ts b/src/utils/taskSummary.ts
index 514e894c2..7bd77573c 100644
--- a/src/utils/taskSummary.ts
+++ b/src/utils/taskSummary.ts
@@ -1,3 +1,78 @@
-// Auto-generated stub — replace with real implementation
-export const shouldGenerateTaskSummary: () => boolean = () => false;
-export const maybeGenerateTaskSummary: (options: Record<string, unknown>) => void = () => {};
+import { feature } from 'bun:bundle'
+import { isBgSession, updateSessionActivity } from './concurrentSessions.js'
+import { logForDebugging } from './debug.js'
+
+/**
+ * Minimum interval between task summary generations (ms).
+ * Prevents excessive updates during rapid tool-call loops.
+ */
+const SUMMARY_INTERVAL_MS = 30_000
+
+let lastSummaryTime = 0
+
+/**
+ * Whether a task summary should be generated this turn.
+ * Only generates in bg sessions, and rate-limits to avoid churn.
+ */
+export function shouldGenerateTaskSummary(): boolean {
+  if (!feature('BG_SESSIONS')) return false
+  if (!isBgSession()) return false
+
+  const now = Date.now()
+  return now - lastSummaryTime >= SUMMARY_INTERVAL_MS
+}
+
+/**
+ * Generate a task summary from the current turn's messages and push it
+ * to the session registry so `claude ps` can display live status.
+ *
+ * Fire-and-forget from query.ts — errors are logged, never thrown.
+ */
+export function maybeGenerateTaskSummary(
+  options: Record<string, unknown>,
+): void {
+  lastSummaryTime = Date.now()
+
+  try {
+    const messages = options.forkContextMessages as
+      | Array<{
+          type: string
+          message?: { content?: unknown }
+        }>
+      | undefined
+
+    if (!messages || messages.length === 0) return
+
+    // Extract a short status from the most recent assistant message
+    const lastAssistant = [...messages]
+      .reverse()
+      .find(m => m.type === 'assistant')
+
+    let status: 'busy' | 'idle' = 'busy'
+    let waitingFor: string | undefined
+
+    if (lastAssistant?.message?.content) {
+      const content = lastAssistant.message.content
+      // Check if last block is tool_use
+      if (Array.isArray(content)) {
+        const lastBlock = content[content.length - 1] as
+          | Record<string, unknown>
+          | undefined
+        if (lastBlock?.type === 'tool_use') {
+          status = 'busy'
+          waitingFor = `tool: ${lastBlock.name || 'unknown'}`
+        }
+      }
+    }
+
+    // Fire-and-forget update to session registry
+    void updateSessionActivity({
+      status,
+      waitingFor,
+    }).catch(err => {
+      logForDebugging(`[taskSummary] updateSessionActivity failed: ${err}`)
+    })
+  } catch (err) {
+    logForDebugging(`[taskSummary] error: ${err}`)
+  }
+}
diff --git a/src/utils/windowsPaths.ts b/src/utils/windowsPaths.ts
index c0774ea87..c6b544bc7 100644
--- a/src/utils/windowsPaths.ts
+++ b/src/utils/windowsPaths.ts
@@ -1,3 +1,4 @@
+import { existsSync } from 'fs'
 import memoize from 'lodash-es/memoize.js'
 import * as path from 'path'
 import * as pathWin32 from 'path/win32'
@@ -8,17 +9,13 @@ import { memoizeWithLRU } from './memoize.js'
 import { getPlatform } from './platform.js'
 
 /**
- * Check if a file or directory exists on Windows using the dir command
- * @param path - The path to check
- * @returns true if the path exists, false otherwise
+ * Check if a file or directory exists on Windows.
+ * Uses fs.existsSync instead of `dir` shell command to avoid spawning
+ * cmd.exe — which can cause brief console window flashes in detached
+ * or windowsHide child processes.
  */
-function checkPathExists(path: string): boolean {
-  try {
-    execSync_DEPRECATED(`dir "${path}"`, { stdio: 'pipe' })
-    return true
-  } catch {
-    return false
-  }
+function checkPathExists(filePath: string): boolean {
+  return existsSync(filePath)
 }
 
 /**
@@ -88,6 +85,8 @@ export function setShellIfWindows(): void {
   if (getPlatform() === 'windows') {
     const gitBashPath = findGitBashPath()
     process.env.SHELL = gitBashPath
+    // Propagate to child processes so they skip filesystem probing
+    process.env.CLAUDE_CODE_GIT_BASH_PATH = gitBashPath
     logForDebugging(`Using bash path: "${gitBashPath}"`)
   }
 }
diff --git a/tests/integration/cli-arguments.test.ts b/tests/integration/cli-arguments.test.ts
index 6b0e23e9d..b31fede17 100644
--- a/tests/integration/cli-arguments.test.ts
+++ b/tests/integration/cli-arguments.test.ts
@@ -1,99 +1,100 @@
-import { describe, expect, test } from "bun:test";
-import { Command } from "@commander-js/extra-typings";
+import { describe, expect, test } from 'bun:test'
+import { Command } from '@commander-js/extra-typings'
 
 // Test Commander.js option parsing independently from main.tsx initialization.
 // main.tsx has heavy bootstrap dependencies; we test the CLI argument parsing
 // patterns it uses to ensure correct behavior.
 
 function createTestProgram(): Command {
-  const program = new Command();
+  const program = new Command()
   program
-    .name("claude-code")
-    .description("CLI test")
+    .name('claude-code')
+    .description('CLI test')
     .exitOverride() // prevent process.exit during tests
-    .option("-p, --print", "pipe mode")
-    .option("--resume", "resume session")
-    .option("-v, --verbose", "verbose output")
-    .option("--model <model>", "model to use")
-    .option("--system-prompt <prompt>", "system prompt")
-    .option("--allowedTools <tools...>", "allowed tools")
-    .option("--max-turns <n>", "max conversation turns", parseInt)
-    .version("1.0.0", "-V, --version", "display version");
-  return program;
+    .configureOutput({ writeErr: () => {}, writeOut: () => {} })
+    .option('-p, --print', 'pipe mode')
+    .option('--resume', 'resume session')
+    .option('-v, --verbose', 'verbose output')
+    .option('--model <model>', 'model to use')
+    .option('--system-prompt <prompt>', 'system prompt')
+    .option('--allowedTools <tools...>', 'allowed tools')
+    .option('--max-turns <n>', 'max conversation turns', parseInt)
+    .version('1.0.0', '-V, --version', 'display version')
+  return program
 }
 
-describe("CLI arguments: option parsing", () => {
-  test("no flags returns empty opts", () => {
-    const program = createTestProgram();
-    program.parse(["node", "test"]);
-    expect(program.opts()).toEqual({});
-  });
+describe('CLI arguments: option parsing', () => {
+  test('no flags returns empty opts', () => {
+    const program = createTestProgram()
+    program.parse(['node', 'test'])
+    expect(program.opts()).toEqual({})
+  })
 
-  test("-p sets print flag", () => {
-    const program = createTestProgram();
-    program.parse(["node", "test", "-p"]);
-    expect(program.opts().print).toBe(true);
-  });
+  test('-p sets print flag', () => {
+    const program = createTestProgram()
+    program.parse(['node', 'test', '-p'])
+    expect(program.opts().print).toBe(true)
+  })
 
-  test("--print is equivalent to -p", () => {
-    const program = createTestProgram();
-    program.parse(["node", "test", "--print"]);
-    expect(program.opts().print).toBe(true);
-  });
+  test('--print is equivalent to -p', () => {
+    const program = createTestProgram()
+    program.parse(['node', 'test', '--print'])
+    expect(program.opts().print).toBe(true)
+  })
 
-  test("--resume sets resume flag", () => {
-    const program = createTestProgram();
-    program.parse(["node", "test", "--resume"]);
-    expect(program.opts().resume).toBe(true);
-  });
+  test('--resume sets resume flag', () => {
+    const program = createTestProgram()
+    program.parse(['node', 'test', '--resume'])
+    expect(program.opts().resume).toBe(true)
+  })
 
-  test("-v sets verbose flag", () => {
-    const program = createTestProgram();
-    program.parse(["node", "test", "-v"]);
-    expect(program.opts().verbose).toBe(true);
-  });
+  test('-v sets verbose flag', () => {
+    const program = createTestProgram()
+    program.parse(['node', 'test', '-v'])
+    expect(program.opts().verbose).toBe(true)
+  })
 
-  test("--model captures string value", () => {
-    const program = createTestProgram();
-    program.parse(["node", "test", "--model", "claude-opus-4-6"]);
-    expect(program.opts().model).toBe("claude-opus-4-6");
-  });
+  test('--model captures string value', () => {
+    const program = createTestProgram()
+    program.parse(['node', 'test', '--model', 'claude-opus-4-6'])
+    expect(program.opts().model).toBe('claude-opus-4-6')
+  })
 
-  test("--system-prompt captures string value", () => {
-    const program = createTestProgram();
-    program.parse(["node", "test", "--system-prompt", "Be concise"]);
-    expect(program.opts().systemPrompt).toBe("Be concise");
-  });
+  test('--system-prompt captures string value', () => {
+    const program = createTestProgram()
+    program.parse(['node', 'test', '--system-prompt', 'Be concise'])
+    expect(program.opts().systemPrompt).toBe('Be concise')
+  })
 
-  test("--max-turns parses integer value", () => {
-    const program = createTestProgram();
-    program.parse(["node", "test", "--max-turns", "10"]);
-    expect(program.opts().maxTurns).toBe(10);
-  });
+  test('--max-turns parses integer value', () => {
+    const program = createTestProgram()
+    program.parse(['node', 'test', '--max-turns', '10'])
+    expect(program.opts().maxTurns).toBe(10)
+  })
 
-  test("multiple flags can be combined", () => {
-    const program = createTestProgram();
-    program.parse(["node", "test", "-p", "-v", "--model", "opus"]);
-    expect(program.opts().print).toBe(true);
-    expect(program.opts().verbose).toBe(true);
-    expect(program.opts().model).toBe("opus");
-  });
+  test('multiple flags can be combined', () => {
+    const program = createTestProgram()
+    program.parse(['node', 'test', '-p', '-v', '--model', 'opus'])
+    expect(program.opts().print).toBe(true)
+    expect(program.opts().verbose).toBe(true)
+    expect(program.opts().model).toBe('opus')
+  })
 
-  test("--version throws Commander.CommandError with exit code 0", () => {
-    const program = createTestProgram();
-    let error: any;
+  test('--version throws Commander.CommandError with exit code 0', () => {
+    const program = createTestProgram()
+    let error: any
     try {
-      program.parse(["node", "test", "--version"]);
+      program.parse(['node', 'test', '--version'])
     } catch (e) {
-      error = e;
+      error = e
     }
-    expect(error).toBeDefined();
-    expect(error.code).toBe("commander.version");
-    expect(error.exitCode).toBe(0);
-  });
+    expect(error).toBeDefined()
+    expect(error.code).toBe('commander.version')
+    expect(error.exitCode).toBe(0)
+  })
 
-  test("unknown flags throw CommanderError", () => {
-    const program = createTestProgram();
-    expect(() => program.parse(["node", "test", "--nonexistent"])).toThrow();
-  });
-});
+  test('unknown flags throw CommanderError', () => {
+    const program = createTestProgram()
+    expect(() => program.parse(['node', 'test', '--nonexistent'])).toThrow()
+  })
+})
diff --git a/tests/mocks/file-system.ts b/tests/mocks/file-system.ts
index 151f45994..e356ec015 100644
--- a/tests/mocks/file-system.ts
+++ b/tests/mocks/file-system.ts
@@ -1,15 +1,13 @@
-import { mkdtemp, rm, writeFile, mkdir } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { mkdtemp, rm, writeFile, mkdir } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
 
-export async function createTempDir(
-  prefix = "claude-test-",
-): Promise<string> {
-  return mkdtemp(join(tmpdir(), prefix));
+export async function createTempDir(prefix = 'claude-test-'): Promise<string> {
+  return mkdtemp(join(tmpdir(), prefix))
 }
 
 export async function cleanupTempDir(dir: string): Promise<void> {
-  await rm(dir, { recursive: true, force: true });
+  await rm(dir, { recursive: true, force: true })
 }
 
 export async function writeTempFile(
@@ -17,16 +15,18 @@ export async function writeTempFile(
   name: string,
   content: string,
 ): Promise<string> {
-  const path = join(dir, name);
-  await writeFile(path, content, "utf-8");
-  return path;
+  const path = join(dir, name)
+  const parentDir = dirname(path)
+  await mkdir(parentDir, { recursive: true })
+  await writeFile(path, content, 'utf-8')
+  return path
 }
 
 export async function createTempSubdir(
   dir: string,
   name: string,
 ): Promise<string> {
-  const path = join(dir, name);
-  await mkdir(path, { recursive: true });
-  return path;
+  const path = join(dir, name)
+  await mkdir(path, { recursive: true })
+  return path
 }
diff --git a/tsconfig.base.json b/tsconfig.base.json
deleted file mode 100644
index db4bc1e3c..000000000
--- a/tsconfig.base.json
+++ /dev/null
@@ -1,15 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ESNext",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "skipLibCheck": true,
-    "noEmit": true,
-    "esModuleInterop": true,
-    "allowSyntheticDefaultImports": true,
-    "resolveJsonModule": true,
-    "jsx": "react-jsx",
-    "types": ["bun", "@types/node"]
-  }
-}
diff --git a/tsconfig.json b/tsconfig.json
index 3ff0ed276..39423c751 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -1,10 +1,24 @@
 {
-    "extends": "./tsconfig.base.json",
     "compilerOptions": {
+        "target": "ESNext",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "jsx": "react-jsx",
+        "strict": true,
+        "skipLibCheck": true,
+        "noEmit": true,
+        "esModuleInterop": true,
+        "allowSyntheticDefaultImports": true,
+        "resolveJsonModule": true,
+        "types": ["bun", "@types/node"],
         "paths": {
             "src/*": ["./src/*"],
             "@claude-code-best/builtin-tools/*": ["./packages/builtin-tools/src/*"],
-            "@claude-code-best/builtin-tools": ["./packages/builtin-tools/src/index.ts"]
+            "@claude-code-best/builtin-tools": ["./packages/builtin-tools/src/index.ts"],
+            "@claude-code-best/mcp-client/*": ["./packages/mcp-client/src/*"],
+            "@claude-code-best/mcp-client": ["./packages/mcp-client/src/index.ts"],
+            "@claude-code-best/agent-tools/*": ["./packages/agent-tools/src/*"],
+            "@claude-code-best/agent-tools": ["./packages/agent-tools/src/index.ts"]
         }
     },
     "include": ["src/**/*.ts", "src/**/*.tsx", "packages/**/*.ts", "packages/**/*.tsx"],