limbo-code 0.1.16__tar.gz → 0.2__tar.gz

{limbo_code-0.1.16 → limbo_code-0.2}/AGENTS.md

@@ -1,6 +1,6 @@
 # Limbo — Agent Guide
 
-**Limbo** is a minimal terminal AI coding agent (Python 3.11+, Textual). Users converse with an LLM in a TUI to explore, read, edit, and write code via 7 tools.
+**Limbo** is a minimal terminal AI coding agent (Python 3.11+, Textual). Users converse with an LLM in a TUI to explore, read, edit, and write code via 7 tools. A `--headless` flag runs a plain-terminal REPL frontend instead of the TUI (Herdr/script control, RFC LIM-60).
 
 **Tools execute immediately — no confirmation flow, no safety fences.** File tools are not scoped to the workdir (absolute paths and symlinks are honored as-is), there is no sensitive-file skip list, and `bash` runs every command as given (no dangerous-command filter).
 
@@ -27,10 +27,16 @@ src/limbo/
 ├── compaction.py     # Context compaction decision/prompt logic (LIM-14)
 ├── history.py        # tool_call↔result pairing + resume repair
 ├── model_switch.py   # /model domain logic: validate, swap client, persist (UI is an adapter)
+├── code_mode.py      # Code Mode (/code-mode on|off): SDK rendering + CODE_ONLY instruction
+│                     # (deepseek-harness parity: catalog collapses to run_code)
 ├── prompt.py         # System-prompt assembly (tools section derived from the registry)
 ├── steer.py          # Mid-turn steer queue (LIM-20): queueing semantics, cancel boundary
 ├── goal.py           # /goal closed-loop state machine, prompt templates, verify executor (LIM-40)
-├── goal_driver.py    # /goal orchestrator (frontend-agnostic, non-UI): turn → verify → next round
+├── pump.py           # Turn pump (frontend-agnostic, non-UI): single-flight busy flag,
+│                     # steer follow-up drain, /compact mini-turn, goal closed loop
+├── headless.py       # --headless frontend (RFC LIM-60): line-oriented REPL on the
+│                     # primary screen for Herdr (agent prompt/send-keys/read/wait);
+│                     # same TurnPump seam as the TUI, no textual import
 ├── sessions.py       # Session JSONL save/load/list/export
 ├── trace.py          # Append-only JSONL run log (sessions/traces/)
 ├── integrations/     # External mux/orchestrator lifecycle reporters: base.py (protocol
@@ -40,11 +46,15 @@ src/limbo/
 │                     # openai_client.py, anthropic_client.py, responses_client.py, retry.py, sse.py,
 │                     # usage.py (token accounting: usage normalization + prompt-size estimation),
 │                     # scaffold.py (plumbing shared by dialect clients: credentials, retry, images)
-├── tools/            # base.py (BaseTool + path resolution + truncation), registry.py (dispatch),
-│                     # mutation_queue.py (per-file locks), ignore.py (.gitignore),
-│                     # read/bash/edit/write/grep/find/ls.py
+├── tools/            # base.py (BaseTool + path resolution + truncation), registry.py (dispatch;
+│                     # code_mode flag filters definitions() to [run_code], all_definitions() feeds
+│                     # the SDK), mutation_queue.py (per-file locks), ignore.py (.gitignore),
+│                     # read/bash/edit/write/grep/find/ls/run_code.py (the Code Mode transport)
 └── ui/               # app.py + app.tcss (ALL styles here; theme vars only, no bare hex),
-                      # theme.py (limbo-dark/-light, RFC LIM-16), commands.py (slash registry),
+                      # theme.py (limbo-dark/-light, RFC LIM-16), commands.py (slash registry
+                      # + resolve(): the single builtin-vs-skill collision site), path_input.py
+                      # ('/'-path fallback), paste_store.py (pure paste/attachment marker
+                      # state machine; the input widget is its adapter),
                       # screens/ (main, session_picker, model_picker, game2048),
                       # widgets/ (chat, input, status_bar, tool_card, command_menu)
 ```
@@ -79,13 +89,19 @@ Skills: `~/.limbo/skills/<name>/SKILL.md` (user) and `<workdir>/.agents/skills/<
 
 ## UI
 
-Single column: status bar (state/elapsed/tokens/model/workdir/queued + rainbow 🎯GOAL badge while a goal loop runs) → scrolling chat flow (user `❯`, streaming Markdown, tool cards, errors) → input box (Enter submits, Shift+Enter newline, paste markers, `ctrl+v` image attach) → hint line. Slash commands: `/sessions /new /export /compact /model /help /2048 /goal` + skill commands. After palette changes run `python scripts/check_contrast.py` (≥ 4.5:1).
+Single column: status bar (state/elapsed/tokens/model/workdir/queued + rainbow 🎯GOAL badge while a goal loop runs + ⌨code badge while Code Mode is on) → scrolling chat flow (user `❯`, streaming Markdown, tool cards, errors) → input box (Enter submits, Shift+Enter newline, paste markers, `ctrl+v` image attach) → hint line. Slash commands: `/sessions /new /export /compact /model /code-mode /help /2048 /goal` + skill commands. '/'-leading input that matches no command but looks like a path is sent as a normal message with existing files auto-attached (`ui/path_input.py`); a leading space forces plain text. After palette changes run `python scripts/check_contrast.py` (≥ 4.5:1).
 
-`/goal <text>` starts closed-loop mode (LIM-40): the first round is a proposal round — the model explores the repo and proposes acceptance command(s) in a `<verify_proposal>` block; the user confirms in a picker (accept / edit / skip), then `GoalDriver` (non-UI, shared by any frontend) runs each round as a complete `Agent.run()` turn and executes the verify command; exit 0 ends the loop, otherwise the failure output is fed back verbatim into the next round until `max_rounds`, when a no-tool wrap-up turn summarizes and any user message resumes with a fresh budget. Goal state persists on `SessionMeta.goal`. Esc during verify cancels the subprocess.
+`/goal <text>` starts closed-loop mode (LIM-40): the first round is a proposal round — the model explores the repo and proposes acceptance command(s) in a `<verify_proposal>` block; the user confirms in a picker (accept / edit / skip), then the goal branch of the `TurnPump` (non-UI, shared by any frontend) runs each round as a complete `Agent.run()` turn and executes the verify command; exit 0 ends the loop, otherwise the failure output is fed back verbatim into the next round until `max_rounds`, when a no-tool wrap-up turn summarizes and any user message resumes with a fresh budget. Goal state persists on `SessionMeta.goal`. Esc during verify cancels the subprocess.
 
 ## Key Decisions
 
 - Async agent, sync tools via `asyncio.to_thread()`
+- Code Mode (`/code-mode on|off`): `ToolRegistry.code_mode` collapses
+  `definitions()` to `[run_code]`; `RunCodeTool` runs a model-written Python
+  program on a fresh event loop, forwarding `tools.*` sub-calls through the
+  same registry. Only the curated program output (print + return) enters
+  history — sub-calls never do. `SessionMeta.code_mode` persists the mode
+  across resume
 - System prompt = hardcoded tool guidelines + `<workdir>/AGENTS.md` & `~/.limbo/AGENTS.md` (XML-wrapped) + skills catalog. **This file is injected into every request — keep it accurate and lean.**
 - Session files fully rewritten per save (atomic, 0600); trace holds full-fidelity record
 

{limbo_code-0.1.16 → limbo_code-0.2}/CONTEXT.md

@@ -20,11 +20,19 @@ proposals should name modules with these terms.
 
 - **Turn** — one user input through the agent loop until a tool-call-free
   response (or max_iterations). Turns are the save/trace unit.
+- **Turn pump** — the non-UI module that runs turns back-to-back
+  (`pump.py`, `TurnPump`): pulls events out of the lazy `Agent.run()`
+  stream, owns the single-flight busy flag (turns and `/compact`
+  mini-turns alike) and the goal closed loop. The follow-up steer drain
+  lives in its supervisor (stragglers past a round's boundary drain —
+  verify/wrap-up window, teardown race — become one more turn); frontends
+  never drain. Frontends are adapters translating its events into UI
+  updates.
 - **Steer** — a user message queued mid-turn, injected at consistency
   points (loop top, turn end, run head). The `SteerQueue` (`steer.py`) owns
   queueing semantics — id generation, FIFO, and the cancel boundary (an
-  item can be cancelled by id only until drained); the Agent owns drain
-  timing.
+  item can be cancelled by id only until drained); the **Turn pump** owns
+  drain timing.
 - **Compaction** — summarizing the old region of history into a synthetic
   summary message, keeping the recent tail. Triggered automatically
   (loop-top, before context overflow) or manually (`/compact`).

{limbo_code-0.1.16 → limbo_code-0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: limbo-code
-Version: 0.1.16
+Version: 0.2
 Summary: A minimal terminal AI coding agent
 Requires-Python: >=3.11
 Requires-Dist: httpx>=0.27
@@ -232,6 +232,37 @@ tomlkit) so the next launch keeps it. If the write fails, the switch still
 applies for the current session. Switching is refused while a turn is in
 flight.
 
+### Code Mode (`/code-mode on|off`)
+
+Code Mode collapses the model-facing tool catalog to a single `run_code`
+tool: instead of one tool call per action, the model writes a **Python
+program** against a generated SDK and `run_code` executes it — a sequence
+that would take several LLM round trips becomes one. The system prompt
+injects the SDK (every other tool as `await tools.<name>(kwarg=...)`, with
+signatures derived from the registry), so:
+
+```python
+# one run_code call instead of three tool-call round trips
+content = await tools.read(path="src/main.py")
+await tools.write(path="copy.py", content=content)
+return await tools.bash(command="python copy.py")
+```
+
+Inside the program `tools` and `ToolCallError` are bound. Tools return
+their text output as `str`; a failed call raises `ToolCallError` (catchable
+with `try/except`), an unhandled exception fails the run with the
+traceback and captured output so the model self-corrects on the next
+iteration, and independent calls may overlap under `asyncio.gather`. Only
+what the program prints or returns enters the conversation — intermediate
+tool results never do. A runaway program is bounded by a default 120 s
+budget (pass `timeout=` to override) and ESC interrupts at the next tool
+boundary.
+
+Toggle with `/code-mode on|off` (no argument flips). The mode is per
+session: it is persisted in the session file and restored on resume, and
+the status bar shows a `⌨code` badge while it is on. Switching is refused
+while a turn is in flight.
+
 ## Safety
 
 Limbo executes every tool call immediately, without asking for confirmation,

{limbo_code-0.1.16 → limbo_code-0.2}/README.md

@@ -218,6 +218,37 @@ tomlkit) so the next launch keeps it. If the write fails, the switch still
 applies for the current session. Switching is refused while a turn is in
 flight.
 
+### Code Mode (`/code-mode on|off`)
+
+Code Mode collapses the model-facing tool catalog to a single `run_code`
+tool: instead of one tool call per action, the model writes a **Python
+program** against a generated SDK and `run_code` executes it — a sequence
+that would take several LLM round trips becomes one. The system prompt
+injects the SDK (every other tool as `await tools.<name>(kwarg=...)`, with
+signatures derived from the registry), so:
+
+```python
+# one run_code call instead of three tool-call round trips
+content = await tools.read(path="src/main.py")
+await tools.write(path="copy.py", content=content)
+return await tools.bash(command="python copy.py")
+```
+
+Inside the program `tools` and `ToolCallError` are bound. Tools return
+their text output as `str`; a failed call raises `ToolCallError` (catchable
+with `try/except`), an unhandled exception fails the run with the
+traceback and captured output so the model self-corrects on the next
+iteration, and independent calls may overlap under `asyncio.gather`. Only
+what the program prints or returns enters the conversation — intermediate
+tool results never do. A runaway program is bounded by a default 120 s
+budget (pass `timeout=` to override) and ESC interrupts at the next tool
+boundary.
+
+Toggle with `/code-mode on|off` (no argument flips). The mode is per
+session: it is persisted in the session file and restored on resume, and
+the status bar shows a `⌨code` badge while it is on. Switching is refused
+while a turn is in flight.
+
 ## Safety
 
 Limbo executes every tool call immediately, without asking for confirmation,

limbo_code-0.2/design/bang-verification.md

@@ -0,0 +1,24 @@
+# Bang command（`!`）隔离环境验证记录
+
+- 日期：2026-08-13
+- 分支：`feat/bang-command`（含 commit `ad2f1bc`）
+- RFC：design/rfc-bang-command.md
+- 验证方式：真实 `LimboApp`（textual `run_test()` pilot）+ 真实 `BashTool` 子进程（无 mock）；LLM 侧用记录型 stub client，用于断言"无 LLM 请求"并构造一个可被 ESC 打断的长 turn。验证脚本：`/tmp/verify_bang.py`（一次性，未入库）。
+
+## 结果：7/7 通过
+
+| # | 路径 | 结果 | 证据 |
+| --- | --- | --- | --- |
+| 1 | `!echo hello` | ✅ | 卡片 `success`，body 含 `hello`；`llm_calls=0`（无任何 LLM 请求）；`agent.messages` 长度保持 1（仅 system），未进历史 |
+| 2 | `!false` | ✅ | 卡片 `error` 态，body = `Command failed with exit code 1.`（exit code 信息保留，失败路径填的是 output 而非 error） |
+| 3 | 孤立 `!` | ✅ | 对话流出现 `用法：! <bash 命令>（直接执行，不发送给模型）`；未产生 bash 卡片、未发 LLM 请求 |
+| 4 | ` !echo hi`（前导空格） | ✅ | 走普通消息路径：LLM client 收到的末条消息 content 恰为 `!echo hi`；未产生 bash 卡片 |
+| 5 | `!seq 1 5000`（长输出） | ✅ | 卡片 `success`，body 含 `[Showing lines 3001-5000 of 5000. Full output: /var/folders/.../limbo-output-*.log]`；spill 文件真实存在且含完整 5000 行 |
+| 6 | turn 运行中敲 bang + ESC 打断 turn | ✅ | bang（`!sleep 2 && echo survived`）在 turn 运行中立即并行执行（不进 steer 队列，`queued_count=0`）；ESC 打断 turn 后 bang 卡片保持 `running`（未被 `cancel_running_tool_cards()` 误标），2 秒后正常转 `success`，body 含 `survived` |
+| 7 | `!sleep 4711` 运行中退出 app | ✅ | 退出前 `pgrep` 可见 `sleep 4711` 进程；app unmount（`on_unmount` → 私有 `BashTool.cancel()`）后 0.2s 内进程消失，无孤儿 |
+
+## 备注
+
+- 验证环境为临时目录 `tempfile.mkdtemp()` 作为 workdir/session_dir，与日常 `~/.limbo` 数据完全隔离。
+- 第 7 项初次用 `sleep 60 # comment` 做 pgrep 标记失败：`bash -c` 对单条简单命令会 exec 优化，注释不出现在进程 cmdline 中；改用特殊 sleep 时长做标记后通过（验证脚本问题，非产品问题）。
+- 自动化回归：`tests/ui/test_bang_ui.py` 10/10 通过；`make check` 全量 841 passed + ruff + mypy 全绿。

limbo_code-0.2/design/rfc-bang-command.md

@@ -0,0 +1,121 @@
+# RFC: `!` 前缀直接执行 bash 命令（bang command）
+
+- 作者：code-monkey
+- 状态：draft
+- 日期：2026-08-13
+
+## Problem / Motivation
+
+Limbo 输入框提交的所有内容（非 slash 命令）都会作为聊天消息发给 LLM。日常使用中有一类高频诉求：用户只想快速跑一条 shell 命令看一眼结果（`!git status`、`!ls -la`、`!pytest -x` 的最后几行），并不需要消耗一轮 LLM 对话、也不希望这条命令污染对话上下文。pi 等同类工具有成熟的 `!` 前缀惯例：直接执行、结果内联展示。
+
+现状：
+
+- 输入提交链路：`InputWidget.action_submit()`（`src/limbo/ui/widgets/input.py`）发出 `UserSubmitted` 消息 → `MainScreen.on_user_submitted()`（`src/limbo/ui/screens/main.py`）分派：`_editing_verify` 分支 → `/` slash 命令（`ui/commands.py`）→ `/`-path 回退（`ui/path_input.py`，自动 attach）→ steer 队列 / 新 turn。
+- bash 执行能力已有：`BashTool`（`src/limbo/tools/bash.py`）提供流式收集、tail 截断 + spill 临时文件、超时、进程组 kill（ESC 打断）。
+- 结果展示已有：`ChatWidget.add_tool_card()` + `ToolCard`（`src/limbo/ui/widgets/`），状态机 running → success | error | cancelled，`command` 是 header 摘要的优先键（`_SUMMARY_KEYS`）。
+
+即：执行与展示的基础设施都已存在，缺的只是输入层的 `!` 分派和一条"不进 agent 历史的本地执行"通路。
+
+## Non-Goals
+
+- 不把命令/结果写入 agent 对话历史，不作为上下文发给 LLM（包括后续 turn）；不进 session JSONL，resume 后不可见。
+- 不做 bang 结果的 LLM 后处理（不让模型解释输出）。
+- v1 不支持 ESC 取消正在运行的 bang 命令（命令跑完为止； bash 工具无默认超时，与 LLM 侧行为一致）。
+- 不改 slash 命令、`/`-path 回退、steer 队列的任何现有行为。
+- 不做 bang 输出流式刷新（卡片在命令结束后一次性渲染，复用 ToolResult 路径；`BashTool.run()` 本身就是收集完才返回）。
+- 不处理 `/new`、`/sessions` 切换后仍在运行的 bang 的卡片归属（旧卡片随 `chat.clear()` 移除，迟到的结果静默丢弃，见技术视角）；进程本身由 `on_unmount` 兜底（app 退出时 kill）。
+
+## Goal
+
+可验证的成功标准：
+
+1. 输入 `!echo hello` 回车：不产生 LLM 请求（`agent.messages` 不增长、trace 无 `llm_request`），对话流出现一张 bash 工具卡片，header 显示命令，展开可见 stdout `hello`。
+2. 输入 `!false`（或任意非零退出命令）：卡片呈 error 态，展开 body 含完整输出及 `Command failed with exit code N.` 信息。
+3. 输入孤立的 `!`（或 `!` 后全是空白）：不执行任何进程，对话流出现用法提示（info 行），不进历史。
+4. 输入以空格开头的 ` !foo`：与 `/` 的 `force_text` 转义一致，作为普通聊天消息发给 LLM。
+5. agent turn 运行中（busy）提交 `!cmd`：立即并行执行，不进 steer 队列、不打断 turn；turn 的 ESC 打断（`registry.cancel_active()`）不会误杀 bang 进程，且 `InterruptEvent` 触发的 `chat.cancel_running_tool_cards()` **不会把仍在运行的 bang 卡片标记为已取消**（卡片保持 running，命令结束后正常转 success/error）。
+6. `!` 命令进入输入框的 ↑↓ 历史（走现有 `action_submit` 路径即可），长输出复用 bash 工具的截断 + spill 提示。
+7. app 退出时仍在运行的 bang 进程被 kill，不泄漏孤儿进程。
+8. `make check` 全绿，新增 UI 测试覆盖上述 1–5 及 Test Plan 列出的场景。
+
+存疑点（goal unclear，待马越确认，默认按"不做"实现）：
+
+- 是否需要像 pi 那样把 `!` 命令的输出**附加进后续对话上下文**（让模型看得见）？本任务描述明确"不当作聊天消息发给 LLM"，默认结果也不进历史；若后续想要"执行并告知模型"，可作为独立增量（例如 `!!` 变体或开关）。
+- bang 命令是否需要写 trace（`trace.log("bang_command", ...)`）做审计？默认做（一行日志，成本极低），但若认为 trace 只记录 LLM 会话事件可去掉。
+
+## Product / Tech Design
+
+### 用户视角
+
+- 输入框敲 `!` 开头的单行/多行文本并回车 → 不发送给 LLM，直接以 bash 执行（工作目录 = Limbo workdir），对话流中先出现用户消息行（`!cmd` 原样回显，与 slash 命令一致），随后出现工具卡片：`… bash <command>` → 结束后 `✓`（退出码 0）或 `✗`（非零/异常），点击展开看输出；`ctrl+o` 全局展开/收起同样适用。
+- `!` 后无内容 → info 提示 `用法：! <bash 命令>`。
+- 想发送字面 `!` 开头的文本给 LLM：前面加一个空格（与 `/` 的既有转义一致，hint 文案与错误提示沿用同一套话术）。
+- busy（turn/compact 进行中）时 bang 照常可用，行为类似 `/btw`、`/2048`：独立于当前任务。
+- 输入框 hint 行文案追加 `! 命令`（`compose()` 中的 Static）。
+
+### 技术视角
+
+**分派层：MainScreen，与 `/` 完全同构。** `!` 解析放在 `MainScreen.on_user_submitted()`，不放在 InputWidget / pump / agent：
+
+- InputWidget 保持"提交原文"的单一职责（刚重构完，不再加分支）；它现有的 `force_text` 转义判断从"仅 `/`"扩展为"`/` 或 `!`"（`ui/widgets/input.py` 的 `action_submit` 一处改动：`raw.lstrip()[:1] in ("/", "!")`）。
+- pump/agent 完全不感知 bang：不进 `TurnPump`（无 single-flight 约束、无 steer 交互），`agent.py` 零改动。
+- 分派顺序（`on_user_submitted` 内）：`_editing_verify` 分支 **优先于** bang 分支——注意该分支内 slash 与 bang 的语义并不对称：slash 输入是「退出编辑模式、作为命令执行」，而一切非 slash 文本（包括 `!pytest`）都按字面成为验收命令（edit 模式的本意就是编辑一条 shell 命令，`!` 在其中没有特殊含义；`!pytest` 作为验收命令大概率执行失败，用户自证，与现状「任何文本原样成为验收命令」一致）。之后是 bang 分支（`text.startswith("!") and not event.force_text`）；再之后才是现有 `/` 分支。`!` 与 `/` 首字符互斥，与 slash 命令、`/`-path 回退**无优先级冲突**；slash menu 只匹配 `/` 开头，也不受影响。
+
+**执行：复用 `BashTool`，但用 screen 持有的独立实例。** 关键决策——不复用 `agent.registry` 里的那个 `BashTool`：
+
+- turn 的 ESC 打断走 `registry.cancel_active()` → `BashTool.cancel()` 会杀掉该实例所有在途进程；若 bang 复用同一实例，用户打断 turn 会误杀自己手动跑的命令。screen 持有 `BashTool(workdir=self.workdir)` 私有实例即天然隔离。
+- 不受 `[tools] bash_enabled` 影响：该开关控制的是"暴露给 LLM 的工具面"，bang 是用户本人的显式动作（与 LLM 自主调用 bash 的风险模型不同）。
+- 调用方式：`await asyncio.to_thread(bang_tool.execute, {"command": cmd})`（与 `ToolRegistry.execute` 相同的模式，bash 不在 mutation queue 内，无需锁），包在 `run_worker` 里，每次提交一个独立 worker，天然支持并行多条 bang。
+- 超时：不传 `timeout`（与 bash 工具默认一致，无超时）；截断、spill、`[stderr]` 标注全部继承。
+- worker 兜底：`_run_bang` 整体包 `try/except Exception`——`BashTool.execute()` 只捕获 `ToolError`，其余异常（如 trace 写入失败、意外的 OSError）不应让 worker 静默死掉而卡片永远 running；异常时 `card.set_error(f"内部错误：{e}")`。
+- 生命周期：`MainScreen.on_unmount` 增加 `self._bang_tool.cancel()`（进程组 kill），app 退出时不泄漏在途 bang 进程——现有 `on_unmount` 只关 LLM client 和 trace，bang 是唯一新增的外部进程来源。
+
+**结果进对话流：复用 ToolCard，无新消息类型。**
+
+- 回显：`chat.add_user_message(text)`（`!cmd` 原文，**不带 attachments**——粘贴/附件是给 LLM 消息的载荷，bang 不发给 LLM；`InputWidget` 展开粘贴标记后的纯文本照常作为命令的一部分，但若用户先 attach 了图片再敲 `!cmd`，attachment 被静默丢弃）。
+- 卡片：`chat.add_tool_card(tool_id=f"bang-{uuid}", name="bash", arguments={"command": cmd}, agent_owned=False)` —— `ToolCard._summary()` 的 `_SUMMARY_KEYS` 已含 `command`，header 摘要零改动。
+- **bang 卡片标记（B1 修复）**：`add_tool_card` 增加 `agent_owned: bool = True` 参数，落到 `ToolCard` 的同名属性；`ChatWidget.cancel_running_tool_cards()` 只把 `agent_owned` 的 running 卡片置 cancelled。理由（相比 screen 侧维护 bang tool_id 集合）：「running 卡片 ⇔ 等待 agent 工具结果」是 chat 组件自己的不变量，标记随卡片生命周期走（`tool_cards` 字典、`clear()` 一并清理），screen 侧平行维护一个集合会在 `/new`、`/sessions` 切换等 clear 路径上产生同步负担和漂移风险。这样 turn 被打断时 bang 卡片保持 running，`set_cancelled` 的「no result will ever arrive」不变量不被打破——bang 的结果一定会在进程结束时到达并正常转 success/error。
+- 结果映射：`result.success` → `card.set_success(result.output or "")`；失败（非零退出/超时/启动异常）→ `card.set_error(result.output or result.error or "Command failed.")`。注意失败时要用 `output` 而非 `error` 填 body：`BashTool` 把 `Command failed with exit code N.` 置于 output 首行、完整 stdout/stderr 在后，只显示 `error` 会丢掉全部输出。
+- 状态栏：v1 不动（卡片自带 running 态 `…`）；busy 时也不去抢 turn 的状态文案。
+- 迟到结果的容忍：`/new`、`/sessions` 切换后 bang 仍在跑，旧卡片已被 `chat.clear()` 卸载；此时 `set_success`/`set_error` 走 `ToolCard` 现有的 `NoMatches` 静默路径，不崩溃、结果丢弃（符合「bang 不进历史」的定位）。
+- ESC 路由：不变。bang 进程属独立实例，turn ESC 不会波及；v1 也没有"ESC 取消 bang"的路径（Non-Goal）。
+
+**持久化 / trace：** 不进 `agent.messages`、不进 session JSONL（resume 后无 bang 痕迹，与"历史不重建工具卡片"的既有策略一致）。trace 追加一条 `bang_command` 事件（command/exit_code/success），在 worker 完成处 best-effort 写入：worker 启动时捕获当时的 `self.agent.trace` 对象（而不是完成时再取 `self.agent.trace`，避免 `/new` 后写到新会话的 trace）；写入本身包 try/except，因为旧 agent `close()` 后 trace 句柄已释放。
+
+**hint 行：** 文案追加 `· ! 命令`。该行是单行 `Static`，窄终端下超长截断/换行是既有行为，本次只加几个字符，不引入新的折行问题；如快照因此变化按既有 `--snapshot-update` 流程处理。
+
+**涉及文件清单：**
+
+| 文件 | 改动 |
+| --- | --- |
+| `src/limbo/ui/screens/main.py` | `on_user_submitted` 增加 bang 分支；新增 `_run_bang(command)` worker（含 try/except 兜底）；`__init__` 持有私有 `BashTool` 实例；`on_unmount` 增加 `cancel()`；hint 文案 |
+| `src/limbo/ui/widgets/input.py` | `force_text` 转义条件扩展到 `!`（一处） |
+| `src/limbo/ui/widgets/chat.py` | `add_tool_card()` 增加 `agent_owned` 参数；`cancel_running_tool_cards()` 跳过非 agent-owned 卡片 |
+| `src/limbo/ui/widgets/tool_card.py` | `ToolCard` 增加 `agent_owned` 属性（默认 True） |
+| `src/limbo/tools/bash.py` | 不改（仅被实例化复用） |
+| `src/limbo/pump.py` / `agent.py` / `models.py` | 不改 |
+| `tests/ui/test_bang_ui.py`（新增） | 见 Test Plan |
+| `tests/ui/test_widgets.py` 或 chat 相关测试 | `cancel_running_tool_cards` 跳过 bang 卡片的单元用例 |
+| `tests/ui/test_input_paste.py` 或 input 相关测试 | `force_text` 扩展的回归用例 |
+
+**兼容性：** 无迁移。唯一行为变化：此前以 `!` 开头的消息会发给 LLM，现在被本地拦截执行；转义 hatch（前导空格）保留旧行为。
+
+## Test Plan
+
+自动化（`tests/ui/test_bang_ui.py`，textual `run_test()` pilot，参照 `test_path_input.py` / `test_steer_ui.py` 的既有模式；LLM client 用现有 mock/fixture）：
+
+1. `!echo hello` → 无 `llm_request`（断言 mock client 零调用 / `agent.messages` 长度不变），聊天流含 bash 卡片且 body 含 `hello`。
+2. `!exit 3` → 卡片 error 态，body 含 `exit code 3`。
+3. 孤立 `!` → info 提示出现，无卡片、无进程。
+4. ` !echo hi`（前导空格）→ 走普通消息路径（mock client 收到文本 `!echo hi`）。
+5. busy 时提交 `!echo hi` → steer 队列计数不变，卡片照常完成；同时断言对 agent 侧 `BashTool` 实例无交互（隔离性，可用 monkeypatch spy）。
+6. **B1 回归**：bang 运行中打断一个 turn（注入 `InterruptEvent` 或走 ESC 路径）→ `cancel_running_tool_cards()` 后 bang 卡片仍为 running 态，agent 侧 running 卡片被置 cancelled；bang 进程结束后卡片正常转 success。另配一个 widget 级单元测试：`add_tool_card(agent_owned=False)` 的卡片不被 `cancel_running_tool_cards()` 触碰。
+7. `_editing_verify` 模式下提交 `!pytest -x` → 不执行 bang、不出现 bash 卡片，文本按字面成为验收命令（走 `_accept_verify`，断言 `pump.status().verify_command == "!pytest -x"`）。
+8. worker 兜底：monkeypatch 私有 `BashTool.execute` 抛非 `ToolError` 异常 → 卡片转 error 态，无未捕获 worker 异常。
+9. 输入历史：提交 `!ls` 后按 ↑ 能召回。
+
+手测路径：
+
+- `!git status`、`!ls -la`（成功卡片 + 展开）；`!grep -r xxx /nonexistent`（非零退出卡片）；超长输出（`!seq 1 5000`）验证截断 + spill 提示；turn 运行中敲 bang 验证并行、ESC 打断 turn 后 bang 卡片不被误标 cancelled 且进程跑完；`!sleep 60` 后退出 app 验证无孤儿进程。
+
+不需要 snapshot 测试：卡片样式复用 ToolCard 现有快照，无新视觉元素（若 hint 文案改动影响现有快照，按既有流程 `--snapshot-update` 并审查 diff）。

limbo_code-0.2/design/rfc-headless-cli.md

@@ -0,0 +1,174 @@
+# RFC LIM-60: Headless CLI 模式（Herdr 可控）
+
+状态：实现随本 RFC 同 PR 落地
+依赖：LIM-20（steer）、LIM-40（goal 闭环）、LIM-53（interrupt）、integrations/herdr（生命周期上报）
+
+## 背景
+
+Limbo 目前只有 Textual TUI 一个前端。TUI 对 Herdr 编排有三个结构性障碍（依据
+herdr v0.8.0 `skills/herdr/SKILL.md` 的控制模型）：
+
+1. **TUI 跑在 alternate screen**。`herdr agent read` 只能读主屏缓冲 + host
+   scrollback；离开 alternate screen 的行不可恢复，完整回答拿不回来。
+2. **TUI 的输入框是私有控件**。`herdr agent prompt` 往 pane 写"文本 + Enter"，
+   在 TUI 下依赖焦点、输入框状态、kitty keyboard 等一堆巧合才能正常工作。
+3. **交互控件不可见**。VerifyPicker 这类模态在屏幕文本里语义不明确，Herdr 无法
+   可靠地把 `blocked` 归因到"等哪个决策"。
+
+Herdr 实际控制一个 agent 的手段只有四种：
+
+| 手段 | 命令 |
+|---|---|
+| 提交文本（原子发送 + Enter，遵守 pane 的 bracketed-paste 模式） | `herdr agent prompt <name> "..." --wait` |
+| 逻辑按键 | `herdr agent send-keys <name> esc\|ctrl+c` |
+| 读屏（visible / recent / recent-unwrapped / detection） | `herdr agent read <name>` |
+| 生命周期状态同步（agent 自上报，我方已有 `HerdrReporter`） | `herdr agent wait <name> --until blocked` |
+
+**结论：headless 模式必须是一个跑在主屏上的、行导向的纯文本 REPL**，
+而不是 NDJSON-RPC——Herdr 没有到 pane 内进程的结构化 IPC 通道。
+（NDJSON 机器协议作为未来扩展预留，见"非目标"。）
+
+## 目标
+
+`limbo --headless`：无 TUI 的前端，与 TUI 并列，复用全部领域层：
+
+```
+herdr agent prompt ──► stdin (行) ──► HeadlessFrontend ──► TurnPump ──► Agent
+herdr agent read   ◄── stdout (纯文本渲染) ◄── PumpEvent 流
+herdr agent wait   ◄── HerdrReporter(working/idle/blocked)   ← 已有机制
+```
+
+- `pump.py` / `agent.py` / `goal.py` / `sessions.py` / `integrations/` **零改动**；
+  headless 只是又一个 frontend adapter（`pump.py` docstring 本就预留了这个角色）。
+- 不 import textual（与 pump 同规约，测试锁死）。
+- 会话文件与 TUI 完全互通：`--continue` / `--resume` / `/new` 同一套。
+
+## 启动
+
+```bash
+limbo --headless [--workdir DIR] [--session-dir DIR] [--continue|--resume ID] [--model M]
+```
+
+`app.py` 复用现有的 config 加载、API key 校验、resume 解析；
+`--headless` 走 `headless.run_headless()`，否则维持 Textual 路径。
+
+## 输入（stdin）
+
+**TTY 模式**（Herdr pane 内）：termios cbreak + 自行回显（关 ECHO，否则
+`herdr agent read` 在屏上看不到输入内容——读屏是 Herdr 唯一的回读手段）。
+
+- 启动时写 `\e[?2004h` 开启 bracketed paste，退出时 `\e[?2004l` 恢复。
+  `herdr agent prompt` 检测到 2004 后会把多行文本包在 `\e[200~ … \e[201~` 里
+  原子发送——粘贴块整体进入行缓冲，内部换行不触发提交；herdr 随后发送的
+  Enter 完成提交。
+- Enter 提交当前行；Backspace 编辑（CJK 宽字符感知）；可打印 UTF-8 字符回显。
+- **Esc**（孤立 `0x1b`，与转义序列以 80ms 超时区分）→ 中断（= TUI 的 Esc）。
+- **Ctrl+C**（cbreak + 关 ISIG，到达为字节 `0x03`）→ busy 时中断；idle 时退出。
+- **Ctrl+D** 空行 → 退出。
+- 未知转义序列（方向键、Alt 组合）丢弃，不污染行缓冲。
+
+**管道模式**（stdin 非 TTY，如脚本/测试）：逐行读取，每行一条提交；
+EOF = 等当前 turn 跑完后退出（`echo "任务" | limbo --headless` 语义自然）。
+
+## 输出（stdout，纯文本渲染）
+
+PumpEvent → 行的映射（全部走主屏，`herdr agent read --source recent-unwrapped`
+可完整回读）：
+
+| 事件 | 渲染 |
+|---|---|
+| TextDelta / ThinkingDelta | 原文流式写出 |
+| ToolCallRequest | `⚙ name(参数摘要)` 一行（参数截断 100 字符） |
+| ToolResultEvent | `✓/✗` + 输出（成功截断到 60 行；错误全文） |
+| ErrorEvent | `✗ message` |
+| SteerEvent | `➤ 插话已注入: …` |
+| InterruptEvent | `⏹ 已打断` |
+| CompactionEvent | 压缩结果一行（同 TUI 文案） |
+| Goal* 事件 | 同 TUI 的中文文案（验收轮次/通过/耗尽/恢复） |
+| UsageUpdate | 累积 tokens，turn 结束时随分隔行打印 |
+| turn 结束 | `── limbo idle · 累计 tokens N ──` 分隔行 |
+
+忙时提交的普通文本 → `agent.steer()`（与 TUI 输入框行为一致）；
+忙时收到改写历史的命令（/goal /new /model /compact）→ 拒绝并提示（同 TUI）。
+
+## 斜杠命令（v1）
+
+`/goal <text>` · `/goal clear` · `/goal`（查询）· `/compact` · `/model [id]`
+（无参=显示当前）· `/new` · `/help` · `/quit`
+解析复用 `goal.parse_goal_args` / `model_switch.prepare_model_switch` +
+`swap_llm_client`；未知命令报错行。Skills 调用不进 v1（见非目标）。
+
+## Goal 验收确认：唯一的 blocked 场景
+
+TUI 用 VerifyPicker 模态；headless 用"下一条输入即答案"：
+
+1. 提议轮结束（goal active 且无 verify_command）→ 解析最后一条 assistant 消息的
+   `<verify_proposal>`（复用 `parse_verify_proposal`）。
+2. 打印编号候选 + 操作说明，向 Herdr 上报 `blocked`（message="等待确认 /goal
+   验收命令"）。Herdr 侧 `herdr agent wait <name> --until blocked` 此刻返回，
+   编排方 `agent read` 读到候选列表后 `agent prompt <name> "1"` 决策。
+3. 下一条提交被消费为验收答案，**不进入对话历史**：
+   - `1..N` → 采纳该候选；`/skip`（或空行）→ 跳过，保持单轮模式；
+   - 其他任意一行 → 作为编辑后的验收命令（对应 TUI 的"编辑"分支）；
+   - 此间 Esc/Ctrl+C → 等同 `/skip`；其他斜杠命令 → 报错提示，保持等待。
+4. 采纳后 `pump.set_verify(cmd)` + 跑 `build_initial_prompt` 首轮，回报 `working`。
+
+`<none/>`（模型判断无客观验收）→ 提示并保持单轮，不进 blocked。
+提议轮期间收到 EOF（管道关闭）→ 打印候选后自动跳过、退出。
+
+## 生命周期上报（复用 integrations）
+
+| 时点 | 上报 |
+|---|---|
+| 启动就绪 | `report_session(id, path)` + `idle` |
+| turn/compact 开始 | `working` |
+| turn 结束 | `idle` |
+| 等待验收确认 | `blocked` |
+| `/new` | `report_session(...)` |
+| 退出/信号 | `release()`（复用 `install_exit_hooks`，含 SIGHUP/SIGTERM/atexit） |
+
+测试环境注意：conftest 已剥离 HERDR_* 环境变量；headless 测试显式注入
+录制用 fake reporter，不碰真实环境。
+
+## 中断语义（RFC LIM-53 平移）
+
+Esc / busy 时 Ctrl+C → `agent.interrupt()` + `pump.cancel_verify()`。
+被中断的 turn 不自动续跑（pump 既有语义）；剩余 steer 留在队列，
+下一次提交时作为头部输入拼接。
+
+## 测试接缝（预先约定）
+
+1. **`HeadlessFrontend.run(inputs, out)`**：inputs 为 InputEvent 异步迭代器
+   （Submit/Interrupt/Eof），out 为 `str -> None` 收集器。配真实 Agent +
+   脚本化 FakeLLMClient（沿用 test_pump.py 模式）+ 录制 fake reporter。
+   覆盖：单轮渲染、工具调用渲染、忙时 steer、interrupt、
+   goal 提议→blocked→确认/跳过/自定义命令、/compact、/model、/new、
+   EOF 等待 turn 完成后退出、忙时命令拒绝。
+2. **行解析**：`parse_submission` / `parse_verify_answer` /
+   `TerminalLineParser`（bracketed paste、Esc 超时、退格、Ctrl+C/D）——
+   纯函数/纯字节测试。
+3. **入口**：`--headless` flag 路由到 run_headless（沿用 test_cli.py mock 模式）。
+
+不在接缝内：termios 字节级读写循环（手工验证）、真实 Herdr 联调。
+
+## 非目标（v1）
+
+- NDJSON 机器协议（`--json`）：等出现非 Herdr 编排方再做；渲染/输入已按
+  可替换的 out/in 接缝隔离。
+- Skills 斜杠调用、`/sessions` 切换器、`/export`、`!` bang 命令、图片粘贴。
+- `[headless]` 配置段（渲染行数上限等先硬编码合理默认值）。
+
+## 验收命令
+
+```bash
+make check
+```
+
+手工联调（Herdr pane 内）：
+
+```bash
+herdr pane split --current --direction right --cwd "$PWD" --no-focus
+herdr agent start worker --kind limbo --pane <pane-id> -- --headless
+herdr agent prompt worker "读一下 AGENTS.md 并总结架构" --wait --timeout 120000
+herdr agent read worker --source recent-unwrapped --lines 80
+```