@caph42/pi-ccline 0.1.0 → 0.2.0

package/README.md

@@ -1,68 +1,72 @@
 # pi-ccline
 
-把 pi 的 footer 交给原版 [CCometixLine](https://github.com/Haleclipse/CCometixLine)（`ccline`）渲染。
+English | [简体中文](./README_zh.md)
 
-这个扩展不做任何渲染：它从 pi 会话采集状态，拼成 Claude Code `statusLine` 形状的 JSON，喂给 `ccline` 二进制的 stdin，再把它的 stdout 当成 footer 显示。配色、主题、图标、折行全部由上游决定；上游升级或改主题，这里不需要跟着改。
+Hands pi's footer over to upstream [CCometixLine](https://github.com/Haleclipse/CCometixLine) (`ccline`) to render.
+
+This extension does no rendering itself: it collects state from the pi session, assembles it into JSON shaped like Claude Code's `statusLine` input, feeds it to the `ccline` binary's stdin, and shows its stdout as the footer. Colors, themes, icons and wrapping are all decided upstream; when upstream upgrades or changes a theme, nothing here needs to follow.
 
 ```
-pi 会话状态 → buildCclineInput() → JSON → ccline（spawn，COLUMNS=当前宽度）→ ANSI 行 → footer
+pi session state → buildCclineInput() → JSON → ccline (spawn, COLUMNS=current width) → ANSI line → footer
 ```
 
-## 能力
+## What it shows
 
-| 显示内容 | 来源 |
+| What you see | Where it comes from |
 |---|---|
-| 模型名（含 provider） | `ctx.model`（`display_name` 取 `model.name`，回退 `model.id`；`showProvider` 为真时追加 ` (provider)`，如 `Sonnet 4.5 (anthropic)`） |
-| 推理强度 | `ctx.thinkingLevel` → `effort.level` |
-| 工作目录 | `ctx.cwd` → `cwd` / `workspace.current_dir` |
-| 上下文百分比 / token 数 | `ctx.getContextUsage()` → 当前上下文（聚合估计值）；**不发会话累计 token** |
-| 成本、会话时长 | assistant 消息 `usage.cost.total` 累加；时长 = 当前时间 − 分支最早 entry |
-| 会话 id / 名称 | `ctx.sessionManager` |
-| git 分支等 ccline 自行探测的信息 | ccline 自己读磁盘 |
-| 其他扩展的 status | `footerData.getExtensionStatuses()`，按 key 排序拼成一行放在 ccline 帧下方 |
+| Model name (with provider) | `ctx.model` (`display_name` takes `model.name`, falling back to `model.id`; when `showProvider` is true it appends ` (provider)`, e.g. `Sonnet 4.5 (anthropic)`) |
+| Reasoning effort | `ctx.thinkingLevel` → `effort.level` |
+| Working directory | `ctx.cwd` → `cwd` / `workspace.current_dir` |
+| Context percentage / token count | `ctx.getContextUsage()` → current context (the aggregate estimate); **no lifetime session tokens are sent** |
+| Prompt-cache hit share | assistant messages' `usage.cacheRead` over `input + cacheRead + cacheWrite`, summed over the branch → `prompt_cache.hit_ratio`; sent from the second request on |
+| Output speed (`tok/s`) | measured from `message_start` → first `message_update` → `message_end`, written to ccline's `bridge/<session>.json` for its `timing.tps` metric |
+| Cost, session duration | assistant messages' `usage.cost.total` summed; duration = now − earliest entry on the branch |
+| Session id / name | `ctx.sessionManager` |
+| git branch and anything else ccline probes itself | ccline reads the disk itself |
+| Status lines from other extensions | `footerData.getExtensionStatuses()`, sorted by key into one line below the ccline frame |
 
-不显示、也不会伪造的：5h / 7d 配额段（pi 没有 `rate_limits` 数据源，字段不传，该段自动消失）。
+Not shown, and never fabricated: the 5h / 7d quota segment (pi has no `rate_limits` source, the field is omitted, and the segment disappears by itself), and the cache warmth / TTL / miss-cause fields (pi knows neither the provider's cache expiry nor why a cache was rebuilt, so only the hit share is sent and ccline is left to hide the rest).
 
-## 安装
+## Installation
 
-先准备外部二进制（扩展不自带渲染器，必须有它）：
+Start with the external binary (the extension ships no renderer, so this is required):
 
 ```sh
 npm i -g @cometix/ccline
-# 或者只放一份到 ~/.claude/ccline/ccline
+# or drop a single copy at ~/.claude/ccline/ccline
 ```
 
-**已在 ccline 2.0.1 上验证。** 更老的 1.1.x 会把 `model` / `workspace` / `transcript_path` 当必填字段，收到这里的输入会直接报
-`missing field ...` 并非 0 退出（footer 会停在上一帧并标 stale），所以旧安装请先升级。
+**Verified against ccline 2.0.1.** Older 1.1.x treats `model` / `workspace` / `transcript_path` as required fields and exits non-zero with
+`missing field ...` on the input built here (the footer then stays on its previous frame and is marked stale), so upgrade first.
 
-再装 pi 包（任选其一）：
+Then install the pi package (pick one):
 
 ```sh
-# 从 npm 正式安装（会写 ~/.pi/agent/settings.json）
+# install from npm for real (writes ~/.pi/agent/settings.json)
 pi install npm:@caph42/pi-ccline
 
-# 从 npm 试用一次，不写 settings.json
+# try it from npm once, without touching settings.json
 pi -e npm:@caph42/pi-ccline
 
-# 本地源码试用 / 正式安装（在包根目录执行）
+# try / install from local source (run in the package root)
 pi -e .
 pi install .
 ```
 
-启动后 footer 直接变成 ccline 的渲染结果。终端需要 Nerd Font v3+ 才能显示图标；`style.mode = "plain"` 的 ccline 主题可以退化成 emoji。
+After startup the footer is whatever ccline renders. Your terminal needs Nerd Font v3+ to show the icons; ccline themes with `style.mode = "plain"` degrade to emoji.
 
-## 命令
+## Commands
 
-| 命令 | 作用 |
+| Command | Effect |
 |---|---|
-| `/pi-ccline on` | 打开 footer（写入配置，立即生效） |
-| `/pi-ccline off` | 关闭并恢复 pi 自带 footer（写入配置） |
-| `/pi-ccline status` | 启用状态、模式、解析到的二进制、节流/超时/定时刷新、刷新次数、上一帧是否 stale |
-| `/pi-ccline path` | 解析到的二进制路径、来源（config/home/path）与 `ccline --version` |
+| `/pi-ccline on` | Turn the footer on (writes config, takes effect immediately) |
+| `/pi-ccline off` | Turn it off and restore pi's built-in footer (writes config) |
+| `/pi-ccline status` | Enabled state, mode, resolved binary, throttle / timeout / live refresh, refresh count, whether the last frame is stale |
+| `/pi-ccline path` | Resolved binary path, its source (config/home/path) and `ccline --version` |
 
-## 配置
+## Configuration
 
-`~/.pi/agent/pi-ccline/config.json`（文件不存在、JSON 坏了、字段类型不对，一律回退默认值，不报错）：
+`~/.pi/agent/pi-ccline/config.json` (a missing file, broken JSON or wrongly typed fields all fall back to the defaults silently):
 
 ```json
 {
@@ -76,80 +80,85 @@ pi install .
 }
 ```
 
-| 字段 | 默认 | 说明 |
+| Field | Default | Meaning |
 |---|---|---|
-| `enabled` | `true` | 会话启动时是否安装 footer |
-| `binary` | `null` | 显式指定 ccline 路径；`null` 走下面的解析顺序。路径不存在时静默回退 |
-| `timeoutMs` | `5000` | 单次调用的硬超时（200–60000） |
-| `refreshThrottleMs` | `1000` | 两次刷新最小间隔，低于 1000 会被抬到 1000 |
-| `liveRefreshMs` | `1000` | agent 运行期间的定时刷新间隔（让 `耗时` 逐秒走）；`0` 关闭定时器，只保留事件刷新。非 0 时低于 250 会被抬到 250 |
-| `showProvider` | `true` | 是否在模型段追加 provider，如 `Sonnet 4.5 (anthropic)`；`false` 只显示模型名。终端窄到模型段被 ccline 截断时 provider 可能不可见 |
-| `env` | `{}` | 追加给 ccline 的环境变量；同名变量覆盖 pi 继承的值（`COLUMNS` 除外，它由扩展按当前宽度写入） |
-
-二进制解析顺序：`config.binary` → `~/.claude/ccline/ccline` → `PATH` 中的 `ccline`。
-
-## 实现要点
-
-- `render(width)` 是同步热路径，**绝不在里面 spawn**：只返回缓存帧；宽度变化只记录并投递一次刷新请求。
-- 刷新由 `session_start` / `turn_start` / `turn_end` / `model_select` / `thinking_level_select` / `session_info_changed` / git 分支变化触发，经 `RefreshScheduler` 单飞 + 节流 + latest-wins：任何时刻最多一个子进程，排队请求合并为一次，读的是发起时刻的最新状态。
-- **耗时这类随时间变化的段靠定时器推进**：纯事件刷新只能在事件发生时算一次「现在 − 起点」，所以 agent 运行期间（`agent_start` → `agent_end`）另有 `RefreshTicker` 按 `liveRefreshMs` 投递刷新请求，`耗时` 才会逐秒走；run 结束即停表，之后只有一次已排队的刷新可能落地，再没有周期刷新。下一轮的 `turn_start` 会重新起表；如果在 run 途中才装上/打开 footer，`attach()` 读 `ctx.isIdle()` 后直接起表。
-- 超时 5s（可配）或非 0 退出：保留上一帧并在行尾加 ` ·stale`（放得下才加），不刷屏、不抛错。
-- 找不到二进制：footer 显示一行安装提示。
-- 行宽一律用 `visibleWidth` / `truncateToWidth` 计算，不用 `.length`。
-- **其他扩展的 `ctx.ui.setStatus` 照样可见**：`render(width)` 读 `footerData.getExtensionStatuses()`，按 key 排序、用空格拼成一行、超宽时用 dim `…` 截断，追加在 ccline 帧下方——行为对齐 pi 内置 footer。读的是实时 map，`setStatus` 自己会触发重绘，所以状态变化不受 1Hz 节流限制。
-- 因为 footer 槽位全局只有一个，本扩展装上后其他扩展的自定义 footer（例如 pi-cursor-provider 的 fast 徽标）会被顶掉；它们的 status 行仍会显示。反过来它们抢占时 ccline 帧会消失，需要 `/pi-ccline on` 取回。
-- **provider 只能拼进模型段。** ccline 2.0.1 的输入 schema 没有 provider 字段，`model` 段只渲染 `display_name`，所以 provider 以 `名称 (provider)` 的形式追加在模型名后；名字里已经带同样的后缀时不重复追加。`showProvider: false` 可关掉。**窄宽度下 provider 可能看不到**：ccline 按 `COLUMNS` 自己折行/截断，实测宽度 40 时模型段只剩 `GPT-5.6`，这是上游布局行为，本扩展只保证把 provider 写进 `display_name`。
-- 输入 JSON **省略 `version` 字段**：ccline 2.0.1 会把它当 Claude Code 版本校验，传 pi 的版本会被直接拒绝。
-- 没有运行时依赖，只用 `node:child_process` / `node:fs` / `node:os` / `node:path` 和 pi 提供的 peer 包 `@earendil-works/pi-tui`。
-- 非 TUI 模式（`-p`、json、rpc）不安装 footer、不 spawn。
-- 扩展自己的配置写在 `~/.pi/agent/pi-ccline/config.json`，不碰 pi 的 `settings.json`。
-
-## 验证
+| `enabled` | `true` | Whether to install the footer when a session starts |
+| `binary` | `null` | Explicit ccline path; `null` follows the resolution order below. A path that doesn't exist falls back silently |
+| `timeoutMs` | `5000` | Hard timeout per invocation (200–60000) |
+| `refreshThrottleMs` | `1000` | Minimum interval between refreshes; anything below 1000 is raised to 1000 |
+| `liveRefreshMs` | `1000` | Interval of the timer that refreshes while the agent runs (so `duration` ticks every second); `0` disables the timer and leaves only event-driven refreshes. When non-zero, anything below 250 is raised to 250 |
+| `showProvider` | `true` | Whether to append the provider to the model segment, e.g. `Sonnet 4.5 (anthropic)`; `false` shows just the model name. If the terminal is narrow enough for ccline to truncate the model segment, the provider may not be visible |
+| `env` | `{}` | Extra environment variables for ccline; same-named variables override the values inherited from pi (except `COLUMNS`, which the extension writes from the current width) |
+
+Binary resolution order: `config.binary` → `~/.claude/ccline/ccline` → `ccline` on `PATH`.
+
+## Implementation notes
+
+- `render(width)` is a synchronous hot path and **never spawns anything** from inside: it returns the cached frame; a width change is only recorded and one refresh request is dispatched.
+- Refreshes are triggered by `session_start` / `turn_start` / `turn_end` / `model_select` / `thinking_level_select` / `session_info_changed` / a git branch change, and go through `RefreshScheduler` with single-flight + throttling + latest-wins: at most one child process at any moment, queued requests collapse into one, and it reads the freshest state as of the moment it starts.
+- **Segments that move with time, like `duration`, are advanced by a timer**: a purely event-driven refresh can only compute "now − start" once, when the event fires, so while the agent runs (`agent_start` → `agent_end`) a `RefreshTicker` dispatches refresh requests at `liveRefreshMs`, which is what makes `duration` tick every second; the clock stops when the run ends, after which at most one already-queued refresh can land and no periodic refresh remains. The next `turn_start` restarts the clock; if the footer is installed or switched on mid-run, `attach()` reads `ctx.isIdle()` and starts it immediately.
+- A timeout (5s, configurable) or a non-zero exit keeps the previous frame and appends ` ·stale` at the end of the line (only if it fits): no flooding, no throwing.
+- Binary not found: the footer shows a one-line install hint.
+- Widths are always computed with `visibleWidth` / `truncateToWidth`, never with `.length`.
+- **Other extensions' `ctx.ui.setStatus` stays visible**: `render(width)` reads `footerData.getExtensionStatuses()`, sorts by key, joins them with spaces into one line, truncates with a dim `…` when too wide, and appends it below the ccline frame, matching pi's built-in footer. It reads the live map and `setStatus` itself triggers a repaint, so status changes are not limited by the 1Hz throttle.
+- Because there is only one footer slot globally, other extensions' custom footers (e.g. pi-cursor-provider's fast badge) get displaced once this extension is installed; their status lines still show. Conversely, when they take over, the ccline frame disappears and `/pi-ccline on` takes it back.
+- **The provider can only be folded into the model segment.** ccline 2.0.1's input schema has no provider field and the `model` segment renders only `display_name`, so the provider is appended after the model name as `name (provider)`; it isn't appended twice when the name already carries the same suffix. `showProvider: false` turns it off. **At narrow widths the provider may be invisible**: ccline wraps/truncates by `COLUMNS` itself, and in practice at width 40 the model segment is left with just `GPT-5.6` — that's upstream layout behaviour, and this extension only guarantees the provider is written into `display_name`.
+- The input JSON **omits the `version` field**: ccline 2.0.1 validates it as a Claude Code version and rejects pi's version outright.
+- **Cache hit share:** `prompt_cache` is sent only from the second assistant message on. That is ccline's own display gate (`requests > 1`), whose rationale is that a single request usually only writes the cache — an initial request can still hit a prefix cached by an earlier session, so the gate is display behaviour, not a claim about request #1. Sending `hit_ratio` before that gate would also make ccline fall back to its "cold" wording, which pi cannot assert. `current_usage` deliberately still carries only `input_tokens`: pi's context estimate already includes the cached tokens, and ccline sums the `current_usage` fields when `total_input_tokens` is absent, so adding the cache counts there would double-count them in the context bar.
+- **Output speed goes through ccline's bridge, not stdin.** ccline's `timing.tps` / `timing.ttft` metrics read `bridge/<session>.json` under its data dir (`$CCLINE_HOME` or `~/.claude/ccline`), the file its companion mod writes inside Claude Code. The statusline payload has no per-request timing, so this extension measures it from `message_start` / `message_update` / `message_end` and writes the same documented `v: 1` shape, atomically, once per finished answer. ttft is stream start → first content block; pi emits `message_start` when the provider starts responding, so that number excludes the connect wait. tps divides the answer's output tokens by the time from the first content block to `message_end`, so the wait for the first token is not counted as generation. Durations use a monotonic clock (`performance.now()`); only the bridge's freshness stamp is wall-clock. The file is removed on `session_shutdown`, and ccline ignores bridges older than 6h.
+- No runtime dependencies: only `node:child_process` / `node:fs` / `node:os` / `node:path` plus the pi peer package `@earendil-works/pi-tui`.
+- Non-TUI modes (`-p`, json, rpc) install no footer and spawn nothing.
+- The extension's own config lives at `~/.pi/agent/pi-ccline/config.json`; pi's `settings.json` is never touched.
+
+## Verification
 
 ```sh
-# 单元测试（输入映射、宽度截断、节流/latest-wins、二进制解析、超时、footer 生命周期）
+# unit tests (input mapping, width truncation, throttle/latest-wins, binary resolution, timeout, footer lifecycle)
 npm test
 
-# 用 fixture 跑真实 ccline，宽 120 与 40 各一次（打印可见宽度，验证不越界）
+# run the real ccline against the fixture at width 120 and 40 (prints visible widths, checks nothing overflows)
 node --experimental-strip-types scripts/render-once.ts --fixture fixtures/basic.json
 
-# 只跑某个宽度 / 指定二进制 / 隔离 HOME
+# single width / pinned binary / raw ANSI
 node --experimental-strip-types scripts/render-once.ts --width 40 --binary ~/.claude/ccline/ccline --raw
 
-# 完全隔离：配置从该 HOME 读，子进程 HOME 也指向它（state 不会写进你的 ~/.claude）
+# fully isolated: config is read from this HOME and the child's HOME points there too (state never lands in your ~/.claude)
 node --experimental-strip-types scripts/render-once.ts --home "$(mktemp -d)" --binary ~/.claude/ccline/ccline
 ```
 
-`--home` 会把该目录同时用于三处：查 `~/.claude/ccline/ccline`、读 `<home>/.pi/agent/pi-ccline/config.json`、以及给子进程设置 `HOME`/`USERPROFILE`。如果解析到的是 npm 包装脚本（`@cometix/ccline/bin/ccline.js`），它可能自己往这个 HOME 里铺主题等资源，想得到干净结果就同时用 `--binary` 钉死真实二进制。
+`--home` is used for three things at once: finding `~/.claude/ccline/ccline`, reading `<home>/.pi/agent/pi-ccline/config.json`, and setting the child's `HOME`/`USERPROFILE`. If what resolves is the npm wrapper script (`@cometix/ccline/bin/ccline.js`), it may populate that HOME with themes and other resources itself; pin the real binary with `--binary` as well when you want a clean result.
 
-`scripts/render-once.ts` 不启动 pi、不发模型请求，只验证「输入 → 二进制 → 行」这一段。
+`scripts/render-once.ts` starts no pi and sends no model requests; it verifies only the "input → binary → line" stretch.
 
-## 已知限制
+## Known limitations
 
-- **5h / 7d 配额段永远为空。** pi 不提供 `rate_limits`，字段整段省略，ccline 自然不显示。
-- **ccline 会写 `~/.claude/ccline/state/`**（会话状态、模型缓存、update.lock）。这是上游行为，扩展无法关闭。
-- **依赖外部二进制。** 没有 `ccline` 时 footer 只有一行安装提示；升级 `ccline` 后无需重启扩展，但二进制路径会被缓存到下一次解析（`/pi-ccline on` 或新会话会重算）。
-- **上游兼容性只覆盖已测版本。** ccline 2.0.1 的 `input.rs` 每个字段都是 `Option` + lenient 反序列化，同一大版本内字段换形状一般只会让对应段消失；但大版本之间已经发生过必填字段变化（1.1.x → 2.0.x），升级 ccline 后请用 `scripts/render-once.ts` 复跑一次。
-- **需要 Nerd Font v3+。** 图标字体缺失时会显示成方块；Windows 未测试。
-- **上下文 token 只有一套口径：当前上下文。** `context_window` 只发 `current_usage.input_tokens`（= `getContextUsage().tokens`）和 `used_percentage`，不发 `total_input_tokens` / `total_output_tokens`。原因是 ccline 优先取累计值，那样进度条百分比会和 token 数互相矛盾（长会话显示成 `15% · 512k/272k`）。代价：会话累计输入/输出 token 不出现在 footer 里；成本与时长仍来自 `cost` 段。pi 只给聚合估计值，没有 input/cache 拆分，所以 `current_usage` 里只填 `input_tokens`。
-- **分支视角。** 汇总只覆盖 `getBranch()` 可见的当前分支；compaction 之后仍按分支上现存记录计算，不等于「整个会话生命周期总量」。切分支后数字会变。
-- **不传 `transcript_path`。** pi 的 session jsonl 不是 Claude Code 的 transcript 格式，传过去只会让上游读到无法解析的内容；因此在那个位置上显示的信息来自 JSON 本身而不是重新解析会话文件。
-- **刷新频率上限 1Hz。** 流式输出期间上下文用量变化不会逐 token 刷新，只在节流窗口后更新一次。
-- **`耗时` 只在 agent 运行期间逐秒走。** 定时器随 run 起停，空闲时停在最后一刻的值，直到下一个事件（发消息、切模型、切分支等）再刷新；`liveRefreshMs` 只控制运行期间的刷新请求节奏，不开启空闲刷新。`liveRefreshMs` 与 `refreshThrottleMs` 都是 1000 时，稳态约 1s 一次，实际间隔受两者共同限制。若以后想让空闲也逐秒走，需要改 `agent_end` 的停表逻辑，属于待评估的耗电取舍。
-- **每次定时刷新都是一次进程创建。** 本机实测 spawn ccline 约 24ms（二进制自身 4.4ms），所以运行期间约每秒一次；`liveRefreshMs: 0` 可以彻底关掉。
-- **首次刷新可能用 100/120 列。** 首帧宽度优先取 `process.stdout.columns`，拿不到时用 120，pi 第一次绘制后会按真实宽度重刷一次（多一次 4ms 级 spawn）。
+- **The 5h / 7d quota segment is always empty.** pi provides no `rate_limits`, the field is omitted entirely, and ccline shows nothing.
+- **ccline writes `~/.claude/ccline/state/`** (session state, model cache, update.lock). That's upstream behaviour and cannot be disabled here. The extension additionally writes `~/.claude/ccline/bridge/<session>.json` for the `timing.tps` segment, and deletes it when the session shuts down.
+- **The cache segment shows only the hit share.** Warmth, TTL countdown, miss counts and miss causes need data pi does not have (the provider's cache expiry and rebuild reasons), so those fields are omitted — with a config `format` of `{hit}% hit` the segment reduces to that one number, and before the second request it disappears entirely rather than claiming "cold".
+- **`tok/s` describes the last finished answer, not a running average.** It is measured per request and only updates when an answer ends (a non-streaming provider, or a streamed answer of a few tokens, produces no sample and leaves the previous value on screen until the next one arrives). `duration` and `tok/s` are unrelated numbers: duration is session wall-clock, tps is streaming speed.
+- **External binary required.** Without `ccline` the footer is a single install hint; upgrading `ccline` needs no extension restart, but the binary path stays cached until the next resolution (`/pi-ccline on` or a new session recomputes it).
+- **Upstream compatibility only covers tested versions.** Every field in ccline 2.0.1's `input.rs` is `Option` with lenient deserialization, so a field changing shape within the same major version usually just makes that segment disappear; but required fields have changed across majors before (1.1.x → 2.0.x), so re-run `scripts/render-once.ts` after upgrading ccline.
+- **Nerd Font v3+ required.** Missing icon fonts render as boxes; Windows is untested.
+- **There is only one measure of context tokens: the current context.** `context_window` sends only `current_usage.input_tokens` (= `getContextUsage().tokens`) and `used_percentage`, never `total_input_tokens` / `total_output_tokens`. The reason is that ccline prefers the lifetime values, which makes the progress-bar percentage contradict the token count (a long session shows up as `15% · 512k/272k`). The cost: lifetime input/output tokens don't appear in the footer; cost and duration still come from the `cost` segment. pi provides only the aggregate estimate, with no input/cache split, so only `input_tokens` is filled in `current_usage`.
+- **Branch perspective.** The aggregate covers only the current branch as seen by `getBranch()`; after compaction it is still computed from the records that remain on that branch, which is not the same as "total for the whole session lifetime". Switching branches changes the numbers.
+- **`transcript_path` is not sent.** pi's session jsonl is not Claude Code's transcript format; passing it would only make upstream read something it cannot parse, so whatever appears in that spot comes from the JSON itself rather than a re-parse of the session file.
+- **Refresh rate is capped at 1Hz.** During streaming, context usage is not refreshed token by token; it updates once after the throttle window.
+- **`duration` only ticks while the agent runs.** The timer starts and stops with the run, so while idle it sits at the last value until the next event (sending a message, switching model, switching branch, …); `liveRefreshMs` only controls the cadence of refresh requests during a run, it does not enable idle refreshes. With both `liveRefreshMs` and `refreshThrottleMs` at 1000, the steady state is roughly once per second, with the actual interval bounded by both. Making idle time tick every second would mean changing the stop logic in `agent_end` — an untested power trade-off.
+- **Every timer tick is a process creation.** On this machine spawning ccline measured about 24ms (4.4ms in the binary itself), hence roughly once per second during a run; `liveRefreshMs: 0` turns it off entirely.
+- **The first refresh may use 100/120 columns.** The first frame prefers `process.stdout.columns` and falls back to 120; after pi's first paint it refreshes once at the real width (one extra ~4ms spawn).
 
-## 目录
+## Layout
 
 ```
 extensions/pi-ccline/
-  index.ts    生命周期、setFooter、命令、CclineFooter（缓存帧 + 单飞刷新）
-  input.ts    pi 状态 → ccline 输入 JSON（纯函数）
-  binary.ts   路径解析/缓存、带超时与中止的 spawn、--version 探测
-  render.ts   输出归一化：分行、按可见宽度截断、stale 标记
-  refresh.ts  单飞 + 节流 + latest-wins 调度器，以及驱动 `耗时` 的定时器
-  config.ts   配置读写
+  index.ts    lifecycle, setFooter, commands, CclineFooter (cached frame + single-flight refresh)
+  input.ts    pi state → ccline input JSON (pure functions)
+  binary.ts   path resolution/caching, spawn with timeout and abort, --version probing
+  render.ts   output normalization: line splitting, truncation by visible width, stale marker
+  refresh.ts  single-flight + throttle + latest-wins scheduler, and the timer that drives `duration`
+  turn.ts     per-request timing from the stream, plus the ccline bridge file for `timing.tps`
+  config.ts   config read/write
   *.test.ts   node --test
-scripts/render-once.ts   用 fixture 跑一次真实 ccline
-fixtures/basic.json      人工验收用输入
+scripts/render-once.ts   run the real ccline once against a fixture
+fixtures/basic.json      input used for manual acceptance
 ```

package/README_zh.md

@@ -0,0 +1,164 @@
+# pi-ccline
+
+[English](./README.md) | 简体中文
+
+把 pi 的 footer 交给原版 [CCometixLine](https://github.com/Haleclipse/CCometixLine)（`ccline`）渲染。
+
+这个扩展不做任何渲染：它从 pi 会话采集状态，拼成 Claude Code `statusLine` 形状的 JSON，喂给 `ccline` 二进制的 stdin，再把它的 stdout 当成 footer 显示。配色、主题、图标、折行全部由上游决定；上游升级或改主题，这里不需要跟着改。
+
+```
+pi 会话状态 → buildCclineInput() → JSON → ccline（spawn，COLUMNS=当前宽度）→ ANSI 行 → footer
+```
+
+## 能力
+
+| 显示内容 | 来源 |
+|---|---|
+| 模型名（含 provider） | `ctx.model`（`display_name` 取 `model.name`，回退 `model.id`；`showProvider` 为真时追加 ` (provider)`，如 `Sonnet 4.5 (anthropic)`） |
+| 推理强度 | `ctx.thinkingLevel` → `effort.level` |
+| 工作目录 | `ctx.cwd` → `cwd` / `workspace.current_dir` |
+| 上下文百分比 / token 数 | `ctx.getContextUsage()` → 当前上下文（聚合估计值）；**不发会话累计 token** |
+| 缓存命中率 | assistant 消息的 `usage.cacheRead` 除以 `input + cacheRead + cacheWrite`，在分支上累加 → `prompt_cache.hit_ratio`；从第二次请求起才发送 |
+| 输出速度（`tok/s`） | 由 `message_start` → 首个 `message_update` → `message_end` 实测，写入 ccline 的 `bridge/<session>.json` 供 `timing.tps` 读取 |
+| 成本、会话时长 | assistant 消息 `usage.cost.total` 累加；时长 = 当前时间 − 分支最早 entry |
+| 会话 id / 名称 | `ctx.sessionManager` |
+| git 分支等 ccline 自行探测的信息 | ccline 自己读磁盘 |
+| 其他扩展的 status | `footerData.getExtensionStatuses()`，按 key 排序拼成一行放在 ccline 帧下方 |
+
+不显示、也不会伪造的：5h / 7d 配额段（pi 没有 `rate_limits` 数据源，字段不传，该段自动消失）；缓存冷热 / TTL 倒计时 / miss 次数与原因（pi 既不知道 provider 的缓存过期时间，也不知道缓存为何重建，所以只发命中率，其余字段交给 ccline 自己隐藏）。
+
+## 安装
+
+先准备外部二进制（扩展不自带渲染器，必须有它）：
+
+```sh
+npm i -g @cometix/ccline
+# 或者只放一份到 ~/.claude/ccline/ccline
+```
+
+**已在 ccline 2.0.1 上验证。** 更老的 1.1.x 会把 `model` / `workspace` / `transcript_path` 当必填字段，收到这里的输入会直接报
+`missing field ...` 并非 0 退出（footer 会停在上一帧并标 stale），所以旧安装请先升级。
+
+再装 pi 包（任选其一）：
+
+```sh
+# 从 npm 正式安装（会写 ~/.pi/agent/settings.json）
+pi install npm:@caph42/pi-ccline
+
+# 从 npm 试用一次，不写 settings.json
+pi -e npm:@caph42/pi-ccline
+
+# 本地源码试用 / 正式安装（在包根目录执行）
+pi -e .
+pi install .
+```
+
+启动后 footer 直接变成 ccline 的渲染结果。终端需要 Nerd Font v3+ 才能显示图标；`style.mode = "plain"` 的 ccline 主题可以退化成 emoji。
+
+## 命令
+
+| 命令 | 作用 |
+|---|---|
+| `/pi-ccline on` | 打开 footer（写入配置，立即生效） |
+| `/pi-ccline off` | 关闭并恢复 pi 自带 footer（写入配置） |
+| `/pi-ccline status` | 启用状态、模式、解析到的二进制、节流/超时/定时刷新、刷新次数、上一帧是否 stale |
+| `/pi-ccline path` | 解析到的二进制路径、来源（config/home/path）与 `ccline --version` |
+
+## 配置
+
+`~/.pi/agent/pi-ccline/config.json`（文件不存在、JSON 坏了、字段类型不对，一律回退默认值，不报错）：
+
+```json
+{
+  "enabled": true,
+  "binary": null,
+  "timeoutMs": 5000,
+  "refreshThrottleMs": 1000,
+  "liveRefreshMs": 1000,
+  "showProvider": true,
+  "env": {}
+}
+```
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| `enabled` | `true` | 会话启动时是否安装 footer |
+| `binary` | `null` | 显式指定 ccline 路径；`null` 走下面的解析顺序。路径不存在时静默回退 |
+| `timeoutMs` | `5000` | 单次调用的硬超时（200–60000） |
+| `refreshThrottleMs` | `1000` | 两次刷新最小间隔，低于 1000 会被抬到 1000 |
+| `liveRefreshMs` | `1000` | agent 运行期间的定时刷新间隔（让 `耗时` 逐秒走）；`0` 关闭定时器，只保留事件刷新。非 0 时低于 250 会被抬到 250 |
+| `showProvider` | `true` | 是否在模型段追加 provider，如 `Sonnet 4.5 (anthropic)`；`false` 只显示模型名。终端窄到模型段被 ccline 截断时 provider 可能不可见 |
+| `env` | `{}` | 追加给 ccline 的环境变量；同名变量覆盖 pi 继承的值（`COLUMNS` 除外，它由扩展按当前宽度写入） |
+
+二进制解析顺序：`config.binary` → `~/.claude/ccline/ccline` → `PATH` 中的 `ccline`。
+
+## 实现要点
+
+- `render(width)` 是同步热路径，**绝不在里面 spawn**：只返回缓存帧；宽度变化只记录并投递一次刷新请求。
+- 刷新由 `session_start` / `turn_start` / `turn_end` / `model_select` / `thinking_level_select` / `session_info_changed` / git 分支变化触发，经 `RefreshScheduler` 单飞 + 节流 + latest-wins：任何时刻最多一个子进程，排队请求合并为一次，读的是发起时刻的最新状态。
+- **耗时这类随时间变化的段靠定时器推进**：纯事件刷新只能在事件发生时算一次「现在 − 起点」，所以 agent 运行期间（`agent_start` → `agent_end`）另有 `RefreshTicker` 按 `liveRefreshMs` 投递刷新请求，`耗时` 才会逐秒走；run 结束即停表，之后只有一次已排队的刷新可能落地，再没有周期刷新。下一轮的 `turn_start` 会重新起表；如果在 run 途中才装上/打开 footer，`attach()` 读 `ctx.isIdle()` 后直接起表。
+- 超时 5s（可配）或非 0 退出：保留上一帧并在行尾加 ` ·stale`（放得下才加），不刷屏、不抛错。
+- 找不到二进制：footer 显示一行安装提示。
+- 行宽一律用 `visibleWidth` / `truncateToWidth` 计算，不用 `.length`。
+- **其他扩展的 `ctx.ui.setStatus` 照样可见**：`render(width)` 读 `footerData.getExtensionStatuses()`，按 key 排序、用空格拼成一行、超宽时用 dim `…` 截断，追加在 ccline 帧下方——行为对齐 pi 内置 footer。读的是实时 map，`setStatus` 自己会触发重绘，所以状态变化不受 1Hz 节流限制。
+- 因为 footer 槽位全局只有一个，本扩展装上后其他扩展的自定义 footer（例如 pi-cursor-provider 的 fast 徽标）会被顶掉；它们的 status 行仍会显示。反过来它们抢占时 ccline 帧会消失，需要 `/pi-ccline on` 取回。
+- **provider 只能拼进模型段。** ccline 2.0.1 的输入 schema 没有 provider 字段，`model` 段只渲染 `display_name`，所以 provider 以 `名称 (provider)` 的形式追加在模型名后；名字里已经带同样的后缀时不重复追加。`showProvider: false` 可关掉。**窄宽度下 provider 可能看不到**：ccline 按 `COLUMNS` 自己折行/截断，实测宽度 40 时模型段只剩 `GPT-5.6`，这是上游布局行为，本扩展只保证把 provider 写进 `display_name`。
+- 输入 JSON **省略 `version` 字段**：ccline 2.0.1 会把它当 Claude Code 版本校验，传 pi 的版本会被直接拒绝。
+- **缓存命中率：** `prompt_cache` 从第二条 assistant 消息起才发。这是 ccline 自己的显示门槛（`requests > 1`），它的理由是一次请求通常只是在写缓存——但首个请求确实可能命中之前会话已缓存的 prefix，所以这是显示行为，不是对「第一次请求」的事实断言。若在门槛前就发 `hit_ratio`，ccline 还会回退到 `cold` 文案，而那是 pi 无法断言的。`current_usage` 仍然只填 `input_tokens`：pi 的上下文估计值本就包含缓存 token，而缺少 `total_input_tokens` 时 ccline 会把 `current_usage` 各项相加，把 cache 数填进去会让它们被重复计入上下文进度条。
+- **输出速度走 ccline 的 bridge，不走 stdin。** ccline 的 `timing.tps` / `timing.ttft` 读的是其数据目录（`$CCLINE_HOME` 或 `~/.claude/ccline`）下的 `bridge/<session>.json`，也就是它家在 Claude Code 里的伴生 mod 写的文件。statusline 载荷里没有单次请求耗时，所以本扩展用 `message_start` / `message_update` / `message_end` 自己计时，并按同样的 `v: 1` 结构原子写入，每个答完的请求写一次。ttft = 流开始 → 首个内容块；pi 是在 provider 开始响应后才发 `message_start`，所以这个数不含建立连接的等待。tps = 该回答的 output token 除以「首个内容块 → `message_end`」的时长，所以等首字的耗时不算进生成速度。计时用单调时钟（`performance.now()`），只有 bridge 的新鲜度标记用墙钟。`session_shutdown` 时删除该文件；ccline 也会忽略超过 6 小时的 bridge。
+- 没有运行时依赖，只用 `node:child_process` / `node:fs` / `node:os` / `node:path` 和 pi 提供的 peer 包 `@earendil-works/pi-tui`。
+- 非 TUI 模式（`-p`、json、rpc）不安装 footer、不 spawn。
+- 扩展自己的配置写在 `~/.pi/agent/pi-ccline/config.json`，不碰 pi 的 `settings.json`。
+
+## 验证
+
+```sh
+# 单元测试（输入映射、宽度截断、节流/latest-wins、二进制解析、超时、footer 生命周期）
+npm test
+
+# 用 fixture 跑真实 ccline，宽 120 与 40 各一次（打印可见宽度，验证不越界）
+node --experimental-strip-types scripts/render-once.ts --fixture fixtures/basic.json
+
+# 只跑某个宽度 / 指定二进制 / 隔离 HOME
+node --experimental-strip-types scripts/render-once.ts --width 40 --binary ~/.claude/ccline/ccline --raw
+
+# 完全隔离：配置从该 HOME 读，子进程 HOME 也指向它（state 不会写进你的 ~/.claude）
+node --experimental-strip-types scripts/render-once.ts --home "$(mktemp -d)" --binary ~/.claude/ccline/ccline
+```
+
+`--home` 会把该目录同时用于三处：查 `~/.claude/ccline/ccline`、读 `<home>/.pi/agent/pi-ccline/config.json`、以及给子进程设置 `HOME`/`USERPROFILE`。如果解析到的是 npm 包装脚本（`@cometix/ccline/bin/ccline.js`），它可能自己往这个 HOME 里铺主题等资源，想得到干净结果就同时用 `--binary` 钉死真实二进制。
+
+`scripts/render-once.ts` 不启动 pi、不发模型请求，只验证「输入 → 二进制 → 行」这一段。
+
+## 已知限制
+
+- **5h / 7d 配额段永远为空。** pi 不提供 `rate_limits`，字段整段省略，ccline 自然不显示。
+- **ccline 会写 `~/.claude/ccline/state/`**（会话状态、模型缓存、update.lock）。这是上游行为，扩展无法关闭。另外本扩展会写 `~/.claude/ccline/bridge/<session>.json` 供 `timing.tps` 段使用，会话关闭时删掉。
+- **缓存段只显示命中率。** 冷热状态、TTL 倒计时、miss 次数与原因需要 pi 没有的数据（provider 的缓存过期时间、重建原因），这些字段一律不发；配置里用 `format = "{hit}% hit"` 就只剩这一个数字，而第二次请求之前整段直接消失，而不是谎称 `cold`。
+- **`tok/s` 描述的是最后一次答完的请求，不是滚动平均。** 它按请求实测，只在回答结束时更新（非流式 provider、或只有几个 token 的回答不会产生样本，上一轮的数值会继续显示到下一次更新）。`duration` 和 `tok/s` 没有关系：前者是会话墙钟时长，后者是流式速度。
+- **依赖外部二进制。** 没有 `ccline` 时 footer 只有一行安装提示；升级 `ccline` 后无需重启扩展，但二进制路径会被缓存到下一次解析（`/pi-ccline on` 或新会话会重算）。
+- **上游兼容性只覆盖已测版本。** ccline 2.0.1 的 `input.rs` 每个字段都是 `Option` + lenient 反序列化，同一大版本内字段换形状一般只会让对应段消失；但大版本之间已经发生过必填字段变化（1.1.x → 2.0.x），升级 ccline 后请用 `scripts/render-once.ts` 复跑一次。
+- **需要 Nerd Font v3+。** 图标字体缺失时会显示成方块；Windows 未测试。
+- **上下文 token 只有一套口径：当前上下文。** `context_window` 只发 `current_usage.input_tokens`（= `getContextUsage().tokens`）和 `used_percentage`，不发 `total_input_tokens` / `total_output_tokens`。原因是 ccline 优先取累计值，那样进度条百分比会和 token 数互相矛盾（长会话显示成 `15% · 512k/272k`）。代价：会话累计输入/输出 token 不出现在 footer 里；成本与时长仍来自 `cost` 段。pi 只给聚合估计值，没有 input/cache 拆分，所以 `current_usage` 里只填 `input_tokens`。
+- **分支视角。** 汇总只覆盖 `getBranch()` 可见的当前分支；compaction 之后仍按分支上现存记录计算，不等于「整个会话生命周期总量」。切分支后数字会变。
+- **不传 `transcript_path`。** pi 的 session jsonl 不是 Claude Code 的 transcript 格式，传过去只会让上游读到无法解析的内容；因此在那个位置上显示的信息来自 JSON 本身而不是重新解析会话文件。
+- **刷新频率上限 1Hz。** 流式输出期间上下文用量变化不会逐 token 刷新，只在节流窗口后更新一次。
+- **`耗时` 只在 agent 运行期间逐秒走。** 定时器随 run 起停，空闲时停在最后一刻的值，直到下一个事件（发消息、切模型、切分支等）再刷新；`liveRefreshMs` 只控制运行期间的刷新请求节奏，不开启空闲刷新。`liveRefreshMs` 与 `refreshThrottleMs` 都是 1000 时，稳态约 1s 一次，实际间隔受两者共同限制。若以后想让空闲也逐秒走，需要改 `agent_end` 的停表逻辑，属于待评估的耗电取舍。
+- **每次定时刷新都是一次进程创建。** 本机实测 spawn ccline 约 24ms（二进制自身 4.4ms），所以运行期间约每秒一次；`liveRefreshMs: 0` 可以彻底关掉。
+- **首次刷新可能用 100/120 列。** 首帧宽度优先取 `process.stdout.columns`，拿不到时用 120，pi 第一次绘制后会按真实宽度重刷一次（多一次 4ms 级 spawn）。
+
+## 目录
+
+```
+extensions/pi-ccline/
+  index.ts    生命周期、setFooter、命令、CclineFooter（缓存帧 + 单飞刷新）
+  input.ts    pi 状态 → ccline 输入 JSON（纯函数）
+  binary.ts   路径解析/缓存、带超时与中止的 spawn、--version 探测
+  render.ts   输出归一化：分行、按可见宽度截断、stale 标记
+  refresh.ts  单飞 + 节流 + latest-wins 调度器，以及驱动 `耗时` 的定时器
+  turn.ts     从流事件实测单次请求耗时，并写 ccline 的 bridge 文件供 `timing.tps`
+  config.ts   配置读写
+  *.test.ts   node --test
+scripts/render-once.ts   用 fixture 跑一次真实 ccline
+fixtures/basic.json      人工验收用输入
+```

package/extensions/pi-ccline/footer.test.ts

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { chmodSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, test } from "node:test";
@@ -318,7 +318,7 @@ function fakePi() {
 		},
 		registerCommand: () => {},
 	};
-	const dispatch = (name: string, ctx: unknown) => handlers.get(name)?.({ type: name }, ctx);
+	const dispatch = (name: string, ctx: unknown, event: Record<string, unknown> = {}) => handlers.get(name)?.({ type: name, ...event }, ctx);
 	return { pi, handlers, dispatch };
 }
 
@@ -383,6 +383,70 @@ test("agent_start ticks the footer and agent_end leaves no periodic refresh behi
 	await dispatch("session_shutdown", ctx);
 });
 
+test("writes ccline's timing bridge from the streamed answer", async () => {
+	const cclineHome = tempDir("pi-ccline-bridge-");
+	const previousHome = process.env.CCLINE_HOME;
+	process.env.CCLINE_HOME = cclineHome;
+	try {
+		const binary = fakeBinary("cat > /dev/null; printf 'FAKE-CCLINE\\n'");
+		const { pi, handlers, dispatch } = fakePi();
+		piCcline(pi as never, { loadConfig: () => ({ ...DEFAULT_CONFIG, binary }) });
+		for (const event of ["message_start", "message_update", "message_end"]) {
+			assert.ok(handlers.has(event), `${event} is wired`);
+		}
+
+		const { ctx } = fakeSession({ idle: true, binary });
+		await dispatch("session_start", ctx);
+
+		const assistant = { role: "assistant", model: "claude-sonnet-4-5", usage: { output: 500 } };
+		await dispatch("message_start", ctx, { message: assistant });
+		await sleep(120);
+		await dispatch("message_update", ctx, { message: assistant });
+		await sleep(220);
+		await dispatch("message_end", ctx, { message: assistant });
+
+		const bridge = JSON.parse(readFileSync(join(cclineHome, "bridge", "sess-1.json"), "utf8"));
+		assert.equal(bridge.v, 1);
+		assert.equal(bridge.session, "sess-1");
+		assert.equal(bridge.turn.model, "claude-sonnet-4-5");
+		assert.equal(bridge.turn.output_tokens, 500);
+		assert.ok(bridge.turn.ttft_ms >= 100, "ttft covers the wait before the first token");
+		assert.ok(bridge.turn.tps > 0 && Number.isFinite(bridge.turn.tps));
+
+		await dispatch("session_shutdown", ctx);
+		assert.equal(existsSync(join(cclineHome, "bridge", "sess-1.json")), false, "a closed session leaves no bridge");
+	} finally {
+		if (previousHome === undefined) delete process.env.CCLINE_HOME;
+		else process.env.CCLINE_HOME = previousHome;
+	}
+});
+
+test("ignores message events that are not the assistant's answer", async () => {
+	const cclineHome = tempDir("pi-ccline-bridge-role-");
+	const previousHome = process.env.CCLINE_HOME;
+	process.env.CCLINE_HOME = cclineHome;
+	try {
+		const binary = fakeBinary("cat > /dev/null; printf 'FAKE-CCLINE\\n'");
+		const { pi, dispatch } = fakePi();
+		piCcline(pi as never, { loadConfig: () => ({ ...DEFAULT_CONFIG, binary }) });
+		const { ctx } = fakeSession({ idle: true, binary });
+		await dispatch("session_start", ctx);
+
+		// A user message or tool result carries no model timing.
+		for (const role of ["user", "toolResult"]) {
+			const message = { role, usage: { output: 500 } };
+			await dispatch("message_start", ctx, { message });
+			await dispatch("message_update", ctx, { message });
+			await dispatch("message_end", ctx, { message });
+		}
+		assert.equal(existsSync(join(cclineHome, "bridge")), false, "no timing is attributed to non-answers");
+		await dispatch("session_shutdown", ctx);
+	} finally {
+		if (previousHome === undefined) delete process.env.CCLINE_HOME;
+		else process.env.CCLINE_HOME = previousHome;
+	}
+});
+
 test("a footer installed mid-run ticks without waiting for the next turn", async () => {
 	const counter = join(tempDir("pi-ccline-lifecycle-midrun-"), "count");
 	const binary = fakeBinary(

package/extensions/pi-ccline/index.ts

@@ -6,6 +6,7 @@ import { loadConfig, saveConfig, type PiCclineConfig } from "./config.ts";
 import { buildCclineInput, collectSnapshot } from "./input.ts";
 import { RefreshScheduler, RefreshTicker } from "./refresh.ts";
 import { extensionStatusLine, loadingNotice, missingBinaryNotice, normalizeFrame, noticeFrame, withStaleMarker } from "./render.ts";
+import { removeTurnBridge, TurnMeter, writeTurnBridge } from "./turn.ts";
 
 /** Structural subsets so the footer does not depend on pi-tui internals. */
 type TuiLike = { requestRender(force?: boolean): void };
@@ -16,6 +17,11 @@ type FooterDataLike = {
 	getExtensionStatuses?(): ReadonlyMap<string, string>;
 };
 
+/** The slice of a pi message event this extension reads. */
+type MessageEventLike = {
+	message?: { role?: string | undefined; model?: string | undefined; usage?: { output?: number | undefined } | undefined } | undefined;
+};
+
 const DEFAULT_WIDTH = 120;
 
 /**
@@ -57,12 +63,16 @@ export class CclineFooter {
 	private footerData: FooterDataLike | null = null;
 	private requestRenderFn: (() => void) | null = null;
 	private branchUnsubscribe: (() => void) | null = null;
+	/** Session whose ccline bridge this footer wrote, removed again on dispose. */
+	private bridgeSessionId: string | null = null;
+	private readonly meter = new TurnMeter();
 	private disposed = false;
 
 	readonly stats = {
 		refreshes: 0,
 		lastRefreshAt: null as number | null,
 		lastDurationMs: null as number | null,
+		lastTps: null as number | null,
 	};
 	resolved: ResolvedBinary = { path: null, source: "missing" };
 
@@ -136,6 +146,56 @@ export class CclineFooter {
 		return this.lastError;
 	}
 
+	/** The session pi reports, or null when it cannot be read or is unusable. */
+	private sessionId(): string | null {
+		try {
+			const id = this.ctx.sessionManager.getSessionId?.();
+			return typeof id === "string" && id.trim() ? id.trim() : null;
+		} catch {
+			return null;
+		}
+	}
+
+	/** A model request went out: start timing until its answer finishes. */
+	onMessageStart(event: MessageEventLike): void {
+		const message = event.message;
+		if (!message || message.role !== "assistant") return;
+		// Stream start, not send time: pi begins the stream once the provider has
+		// answered, so this ttft stops short of the connect wait by design.
+		this.meter.start(message.model, performance.now());
+	}
+
+	/**
+	 * A content block of that answer arrived (`text_start` / `*_delta` /
+	 * `toolcall_*`; pi emits no metadata through this event), so the clock for
+	 * the streaming rate starts at the first sign of content.
+	 */
+	onMessageUpdate(event: MessageEventLike): void {
+		if (event.message?.role !== "assistant") return;
+		this.meter.firstDelta(performance.now());
+	}
+
+	/**
+	 * The answer finished: hand ccline its timing through the bridge file it
+	 * reads for `timing.tps`. No speed, no file.
+	 */
+	onMessageEnd(event: MessageEventLike): void {
+		const message = event.message;
+		if (!message || message.role !== "assistant") return;
+		// Measurement uses the monotonic clock; only the bridge's freshness
+		// stamp is wall-clock, and the two are never mixed.
+		const timing = this.meter.finish(message.usage?.output, performance.now());
+		if (!timing) return;
+		const sessionId = this.sessionId();
+		if (!sessionId) return;
+		if (!writeTurnBridge({ sessionId, timing, nowMs: Date.now() })) return;
+		if (this.bridgeSessionId && this.bridgeSessionId !== sessionId) removeTurnBridge(this.bridgeSessionId);
+		this.bridgeSessionId = sessionId;
+		this.stats.lastTps = timing.tps;
+		// The new speed only shows up in the next frame; let the throttle coalesce it.
+		this.requestRefresh();
+	}
+
 	get hasFrame(): boolean {
 		return this.frame !== null;
 	}
@@ -253,6 +313,8 @@ export class CclineFooter {
 		this.branchUnsubscribe = null;
 		this.footerData = null;
 		this.requestRenderFn = null;
+		if (this.bridgeSessionId) removeTurnBridge(this.bridgeSessionId);
+		this.bridgeSessionId = null;
 	}
 }
 
@@ -307,6 +369,11 @@ export default function piCcline(pi: ExtensionAPI, deps: PiCclineDeps = {}) {
 	pi.on("model_select", () => requestRefresh());
 	pi.on("thinking_level_select", () => requestRefresh());
 	pi.on("session_info_changed", () => requestRefresh());
+	// Per-request timing is not in the statusline payload, so it is measured
+	// from the stream and written to ccline's bridge file when an answer ends.
+	pi.on("message_start", (event) => footer?.onMessageStart(event as MessageEventLike));
+	pi.on("message_update", (event) => footer?.onMessageUpdate(event as MessageEventLike));
+	pi.on("message_end", (event) => footer?.onMessageEnd(event as MessageEventLike));
 	pi.on("session_shutdown", () => teardown());
 
 	pi.registerCommand("pi-ccline", {
@@ -364,6 +431,7 @@ export default function piCcline(pi: ExtensionAPI, deps: PiCclineDeps = {}) {
 				const { refreshes, lastRefreshAt, lastDurationMs } = footer.stats;
 				lines.push(`refreshes: ${refreshes} · last: ${lastRefreshAt === null ? "never" : `${Math.round((Date.now() - lastRefreshAt) / 1000)}s ago`}`);
 				lines.push(`duration: ${lastDurationMs === null ? "n/a" : `${lastDurationMs}ms`} · frame: ${footer.hasFrame ? "cached" : "none"}`);
+				lines.push(`last answer: ${footer.stats.lastTps === null ? "not measured yet" : `${footer.stats.lastTps.toFixed(1)} tok/s`}`);
 				lines.push(`state: ${footer.error ? `stale — ${footer.error}` : "ok"}`);
 			} else {
 				lines.push("state: footer not installed");

package/extensions/pi-ccline/input.test.ts

@@ -185,9 +185,31 @@ test("collectSnapshot sums only assistant usage on the branch", () => {
 test("collectSnapshot reports no totals for an empty branch", () => {
 	const snapshotValue = collectSnapshot(fakeContext([]), Date.now());
 	assert.equal(snapshotValue.totals, undefined);
+	assert.equal(snapshotValue.cache, undefined);
 	assert.equal(snapshotValue.session?.name, "named");
 });
 
+test("collectSnapshot sums prompt-cache reuse over the branch", () => {
+	const branch: BranchEntryLike[] = [
+		entry({ type: "message", message: { role: "user" } }),
+		entry({ type: "message", message: { role: "assistant", usage: { input: 100, cacheRead: 300, cacheWrite: 100 } } }),
+		entry({ type: "message", message: { role: "assistant", usage: { input: 100, cacheRead: 0, cacheWrite: 0 } } }),
+	];
+
+	// 300 of 600 billed input tokens came from the cache.
+	assert.deepEqual(collectSnapshot(fakeContext(branch), Date.now()).cache, { requests: 2, hitRatio: 0.5 });
+});
+
+test("sends the cache hit share only once it means something", () => {
+	// ccline shows the share from the second request on and falls back to a
+	// misleading "cold" label when hit_ratio is missing, so nothing is sent yet.
+	assert.equal("prompt_cache" in buildCclineInput(snapshot({ cache: { requests: 1, hitRatio: 0 } })), false);
+	assert.deepEqual(buildCclineInput(snapshot({ cache: { requests: 41, hitRatio: 0.94123 } })).prompt_cache, {
+		requests: 41,
+		hit_ratio: 0.9412,
+	});
+});
+
 test("collectSnapshot carries the provider from ctx.model", () => {
 	const ctx = fakeContext([], { model: { id: "m", name: "M", provider: "anthropic", contextWindow: 200_000 } });
 	const snapshotValue = collectSnapshot(ctx, Date.now());

package/extensions/pi-ccline/input.ts

@@ -28,6 +28,14 @@ export interface PiSnapshotTotals {
 	durationMs?: number | undefined;
 }
 
+/** Prompt-cache reuse summed over the visible branch. */
+export interface PiSnapshotCache {
+	/** Assistant messages seen, each one a model request. */
+	requests: number;
+	/** cacheRead / (input + cacheRead + cacheWrite); the share read from cache. */
+	hitRatio: number;
+}
+
 export interface PiSnapshotSession {
 	id?: string | undefined;
 	name?: string | undefined;
@@ -39,6 +47,7 @@ export interface PiSnapshot {
 	thinkingLevel?: string | undefined;
 	contextUsage?: PiSnapshotContextUsage | undefined;
 	totals?: PiSnapshotTotals | undefined;
+	cache?: PiSnapshotCache | undefined;
 	session?: PiSnapshotSession | undefined;
 }
 
@@ -95,6 +104,11 @@ function round1(value: number): number {
 	return Math.round(value * 10) / 10;
 }
 
+/** A ratio ccline renders as a whole percent, so four decimals are plenty. */
+function round4(value: number): number {
+	return Math.round(value * 10_000) / 10_000;
+}
+
 function trimmed(value: unknown): string | undefined {
 	if (typeof value !== "string") return undefined;
 	const text = value.trim();
@@ -120,6 +134,10 @@ export function collectSnapshot(ctx: SnapshotContextLike, nowMs: number): PiSnap
 	let costUsd = 0;
 	let sawAssistantUsage = false;
 	let firstTimestamp: number | undefined;
+	let requests = 0;
+	let inputTokens = 0;
+	let cacheReadTokens = 0;
+	let cacheWriteTokens = 0;
 
 	for (const entry of branch) {
 		const timestamp = entry.timestamp ? Date.parse(entry.timestamp) : Number.NaN;
@@ -131,6 +149,10 @@ export function collectSnapshot(ctx: SnapshotContextLike, nowMs: number): PiSnap
 		if (!entryUsage) continue;
 		sawAssistantUsage = true;
 		costUsd += num(entryUsage.cost?.total);
+		requests += 1;
+		inputTokens += num(entryUsage.input);
+		cacheReadTokens += num(entryUsage.cacheRead);
+		cacheWriteTokens += num(entryUsage.cacheWrite);
 	}
 
 	const totals: PiSnapshotTotals | undefined = sawAssistantUsage
@@ -142,6 +164,9 @@ export function collectSnapshot(ctx: SnapshotContextLike, nowMs: number): PiSnap
 
 	const sessionId = attempt(() => ctx.sessionManager.getSessionId?.());
 	const sessionName = attempt(() => ctx.sessionManager.getSessionName?.());
+	// The denominator is every input token the branch was billed for; without
+	// one there is no ratio to report (a session that never sent a prompt yet).
+	const seenInput = inputTokens + cacheReadTokens + cacheWriteTokens;
 
 	return {
 		cwd: ctx.cwd,
@@ -155,6 +180,7 @@ export function collectSnapshot(ctx: SnapshotContextLike, nowMs: number): PiSnap
 				}
 			: undefined,
 		totals,
+		cache: requests > 0 && seenInput > 0 ? { requests, hitRatio: cacheReadTokens / seenInput } : undefined,
 		session: { id: trimmed(sessionId), name: trimmed(sessionName) },
 	};
 }
@@ -236,6 +262,14 @@ export function buildCclineInput(snapshot: PiSnapshot, options: BuildCclineInput
 	const sessionName = trimmed(snapshot.session?.name);
 	if (sessionName) input.session_name = sessionName;
 
+	// ccline only renders the hit share from the second request on, and falls
+	// back to its "cold" wording whenever `hit_ratio` is missing. So the block
+	// is sent only once it can say something pi actually measured.
+	const cache = snapshot.cache;
+	if (cache && cache.requests >= 2) {
+		input.prompt_cache = { requests: cache.requests, hit_ratio: round4(cache.hitRatio) };
+	}
+
 	// rate_limits has no pi data source; omitting it removes the quota segment.
 	return input;
 }

package/extensions/pi-ccline/turn.test.ts

@@ -0,0 +1,135 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, test } from "node:test";
+
+import { bridgeDir, bridgeFileName, removeTurnBridge, TurnMeter, writeTurnBridge } from "./turn.ts";
+
+const createdDirs: string[] = [];
+afterEach(() => {
+	for (const dir of createdDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+function tempDir(): string {
+	const dir = mkdtempSync(join(tmpdir(), "pi-ccline-turn-"));
+	createdDirs.push(dir);
+	return dir;
+}
+
+test("measures streaming speed without counting the wait for the first token", () => {
+	const meter = new TurnMeter();
+	meter.start("claude-sonnet-4-5", 1_000);
+	meter.firstDelta(1_800);
+	assert.deepEqual(meter.finish(500, 6_800), {
+		model: "claude-sonnet-4-5",
+		ttftMs: 800,
+		tps: 100,
+		durationMs: 5_800,
+		outputTokens: 500,
+	});
+});
+
+test("keeps only the first delta of an answer", () => {
+	const meter = new TurnMeter();
+	meter.start("m", 0);
+	meter.firstDelta(500);
+	meter.firstDelta(900);
+	meter.firstDelta(1_200);
+	// 200 tokens over the 1500ms after the first token, not over 1000ms.
+	assert.equal(meter.finish(200, 2_000)?.tps, 200 / 1.5);
+});
+
+test("reports nothing without a first delta, output or a measurable span", () => {
+	const neverStreamed = new TurnMeter();
+	neverStreamed.start("m", 0);
+	assert.equal(neverStreamed.finish(100, 5_000), null, "a non-streaming answer has no speed");
+
+	const empty = new TurnMeter();
+	empty.start("m", 0);
+	empty.firstDelta(100);
+	assert.equal(empty.finish(0, 5_000), null, "no output tokens means no rate");
+
+	const tooShort = new TurnMeter();
+	tooShort.start("m", 0);
+	tooShort.firstDelta(100);
+	assert.equal(tooShort.finish(5, 150), null, "a sub-100ms span is jitter, not speed");
+
+	const unmeasured = new TurnMeter();
+	unmeasured.firstDelta(100);
+	assert.equal(unmeasured.finish(100, 5_000), null, "finish before start is ignored");
+});
+
+test("a finished sample does not leak into the next request", () => {
+	const meter = new TurnMeter();
+	meter.start("first", 0);
+	meter.firstDelta(100);
+	meter.finish(10, 1_100);
+
+	meter.start("second", 2_000);
+	meter.firstDelta(2_400);
+	const second = meter.finish(80, 3_400);
+	assert.equal(second?.model, "second");
+	assert.equal(second?.ttftMs, 400);
+	assert.equal(second?.tps, 80);
+});
+
+test("writes the bridge shape ccline reads", () => {
+	const dir = tempDir();
+	assert.equal(
+		writeTurnBridge({
+			sessionId: "sess-1",
+			timing: { model: "m", ttftMs: 820, tps: 74.234, durationMs: 41_000, outputTokens: 1_400 },
+			nowMs: 1_790_808_780_000,
+			dir,
+		}),
+		true,
+	);
+	assert.deepEqual(JSON.parse(readFileSync(join(dir, "sess-1.json"), "utf8")), {
+		v: 1,
+		session: "sess-1",
+		updated_at: 1_790_808_780_000,
+		turn: { model: "m", ttft_ms: 820, tps: 74.234, duration_ms: 41_000, output_tokens: 1_400 },
+	});
+});
+
+test("omits timing fields it did not measure", () => {
+	const dir = tempDir();
+	writeTurnBridge({ sessionId: "s2", timing: { tps: 12, durationMs: 1_000, outputTokens: 12 }, nowMs: 1, dir });
+	const bridge = JSON.parse(readFileSync(join(dir, "s2.json"), "utf8"));
+	assert.deepEqual(Object.keys(bridge.turn).sort(), ["duration_ms", "output_tokens", "tps"]);
+});
+
+test("refuses session ids that are not plain file names", () => {
+	const dir = tempDir();
+	assert.equal(bridgeFileName("../escape"), null);
+	assert.equal(bridgeFileName("a/b"), null);
+	assert.equal(bridgeFileName(""), null);
+	assert.equal(writeTurnBridge({ sessionId: "../escape", timing: { tps: 1, durationMs: 1, outputTokens: 1 }, nowMs: 1, dir }), false);
+	assert.deepEqual(readdirSync(dir), [], "nothing escaped or landed in the bridge dir");
+});
+
+test("a failed write leaves no temp file behind", () => {
+	const dir = tempDir();
+	// A directory in the target's place makes the rename fail after the temp
+	// file was already written.
+	mkdirSync(join(dir, "blocked.json"));
+	assert.equal(writeTurnBridge({ sessionId: "blocked", timing: { tps: 1, durationMs: 1, outputTokens: 1 }, nowMs: 1, dir }), false);
+	assert.deepEqual(readdirSync(dir), ["blocked.json"]);
+});
+
+test("removes a session bridge and tolerates a missing one", () => {
+	const dir = tempDir();
+	writeTurnBridge({ sessionId: "s3", timing: { tps: 1, durationMs: 1, outputTokens: 1 }, nowMs: 1, dir });
+	assert.equal(existsSync(join(dir, "s3.json")), true);
+	removeTurnBridge("s3", dir);
+	assert.equal(existsSync(join(dir, "s3.json")), false);
+	removeTurnBridge("s3", dir);
+	removeTurnBridge("../escape", dir);
+});
+
+test("follows ccline's own data directory resolution", () => {
+	assert.equal(bridgeDir({ CCLINE_HOME: "/tmp/ccline-home" }, "/home/u"), "/tmp/ccline-home/bridge");
+	assert.equal(bridgeDir({ CCLINE_HOME: "  " }, "/home/u"), "/home/u/.claude/ccline/bridge");
+	assert.equal(bridgeDir({}, "/home/u"), "/home/u/.claude/ccline/bridge");
+});

package/extensions/pi-ccline/turn.ts

@@ -0,0 +1,148 @@
+// Measures the main loop's last model request and hands it to ccline through
+// the bridge file its companion mod normally writes.
+//
+// ccline's `timing.ttft` / `timing.tps` metrics read `bridge/<session>.json`
+// under ccline's data dir, not the statusline JSON: per-request timing is the
+// one thing the Claude Code payload leaves out. pi has the same gap, so the
+// numbers are measured here from streaming events and written in the same
+// documented v1 shape (the file is rewritten on every finished request, which
+// also keeps it inside ccline's 6h freshness window).
+
+import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** One finished model request, in the units ccline's bridge expects. */
+export interface TurnTiming {
+	model?: string | undefined;
+	/** Stream start to the first text, thinking or tool-call delta. */
+	ttftMs?: number | undefined;
+	/** Output tokens per second while the answer streamed (ttft excluded). */
+	tps: number;
+	durationMs: number;
+	outputTokens: number;
+}
+
+/** Below this the sample says more about jitter than about speed. */
+const MIN_STREAM_MS = 100;
+
+/**
+ * ccline resolves its data dir from `CCLINE_HOME`, falling back to
+ * `~/.claude/ccline`; the bridge lives in a `bridge` subdirectory of either.
+ */
+export function bridgeDir(env: NodeJS.ProcessEnv = process.env, home: string = homedir()): string {
+	const override = env.CCLINE_HOME?.trim();
+	return join(override ? override : join(home, ".claude", "ccline"), "bridge");
+}
+
+/**
+ * ccline's own name check rejects anything that could climb out of the bridge
+ * directory; pi session ids are UUIDs, so a strict allowlist costs nothing.
+ */
+export function bridgeFileName(sessionId: string): string | null {
+	return /^[A-Za-z0-9._-]+$/.test(sessionId) ? `${sessionId}.json` : null;
+}
+
+export interface TurnBridgeOptions {
+	sessionId: string;
+	timing: TurnTiming;
+	/** Unix epoch milliseconds of the write; ccline drops bridges older than 6h. */
+	nowMs: number;
+	dir?: string;
+}
+
+/** Write the bridge for one session. Returns false instead of throwing. */
+export function writeTurnBridge(options: TurnBridgeOptions): boolean {
+	const name = bridgeFileName(options.sessionId);
+	if (!name) return false;
+	const dir = options.dir ?? bridgeDir();
+	const path = join(dir, name);
+	const { model, ttftMs, tps, durationMs, outputTokens } = options.timing;
+	const turn: Record<string, unknown> = {
+		tps,
+		duration_ms: Math.round(durationMs),
+		output_tokens: Math.round(outputTokens),
+	};
+	if (model) turn.model = model;
+	if (ttftMs !== undefined) turn.ttft_ms = Math.round(ttftMs);
+	const payload = {
+		v: 1,
+		session: options.sessionId,
+		updated_at: Math.round(options.nowMs),
+		turn,
+	};
+
+	try {
+		mkdirSync(dir, { recursive: true });
+		// ccline tolerates a half-written bridge by retrying once, but an atomic
+		// rename means it never has to.
+		const temp = `${path}.${process.pid}.tmp`;
+		writeFileSync(temp, `${JSON.stringify(payload)}\n`, "utf8");
+		renameSync(temp, path);
+		return true;
+	} catch {
+		// A failed write must not leave a temp file behind next to the bridges
+		// ccline scans (and must never throw into the session).
+		try {
+			rmSync(`${path}.${process.pid}.tmp`, { force: true });
+		} catch {
+			// nothing left to do; ccline prunes the directory itself
+		}
+		return false;
+	}
+}
+
+/** Drop a session's bridge, so a closed session leaves no stale speed behind. */
+export function removeTurnBridge(sessionId: string, dir: string = bridgeDir()): void {
+	const name = bridgeFileName(sessionId);
+	if (!name) return;
+	try {
+		rmSync(join(dir, name), { force: true });
+	} catch {
+		// A bridge that cannot be removed is pruned by ccline after a week.
+	}
+}
+
+/**
+ * Times one request from three streaming events: `message_start` (the answer
+ * began), the first `message_update` (first token) and `message_end`.
+ * A request without a first delta (a non-streaming provider) yields no speed.
+ */
+export class TurnMeter {
+	private startedAt: number | null = null;
+	private firstDeltaAt: number | null = null;
+	private model: string | undefined;
+
+	start(model: string | undefined, nowMs: number): void {
+		this.startedAt = nowMs;
+		this.firstDeltaAt = null;
+		this.model = model;
+	}
+
+	firstDelta(nowMs: number): void {
+		if (this.startedAt === null || this.firstDeltaAt !== null) return;
+		this.firstDeltaAt = nowMs;
+	}
+
+	/** The answer finished; null when the sample cannot describe a speed. */
+	finish(outputTokens: unknown, nowMs: number): TurnTiming | null {
+		const startedAt = this.startedAt;
+		const firstDeltaAt = this.firstDeltaAt;
+		const model = this.model;
+		this.startedAt = null;
+		this.firstDeltaAt = null;
+		this.model = undefined;
+		if (startedAt === null || firstDeltaAt === null) return null;
+
+		const output = typeof outputTokens === "number" && Number.isFinite(outputTokens) ? outputTokens : 0;
+		const streamMs = nowMs - firstDeltaAt;
+		if (output <= 0 || streamMs < MIN_STREAM_MS) return null;
+
+		const tps = output / (streamMs / 1000);
+		if (!Number.isFinite(tps) || tps <= 0) return null;
+
+		const ttftMs = Math.max(0, firstDeltaAt - startedAt);
+		return { model, tps, durationMs: Math.max(0, nowMs - startedAt), outputTokens: output, ttftMs };
+	}
+}
+

package/fixtures/basic.json

@@ -1,7 +1,7 @@
 {
-  "cwd": "/Users/caph/Workspace/pi-packages/packages/pi-ccline",
+  "cwd": "/Users/caph/Workspace/pi-packages/pi-ccline",
   "workspace": {
-    "current_dir": "/Users/caph/Workspace/pi-packages/packages/pi-ccline"
+    "current_dir": "/Users/caph/Workspace/pi-packages/pi-ccline"
   },
   "model": {
     "id": "gpt-5.6-codex",
@@ -18,9 +18,13 @@
     "used_percentage": 15.4
   },
   "cost": {
-    "total_cost_usd": 1.2345,
-    "total_duration_ms": 1830000
+    "total_cost_usd": 0.54,
+    "total_duration_ms": 1800000
   },
-  "session_id": "4f8f2c1a-0000-4000-8000-000000000000",
-  "session_name": "pi-ccline demo"
-}
+  "session_id": "sess-demo",
+  "session_name": "pi-ccline demo",
+  "prompt_cache": {
+    "requests": 2,
+    "hit_ratio": 0.9863
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@caph42/pi-ccline",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Pi extension that renders the footer by delegating to the CCometixLine (ccline) statusline binary",
 	"keywords": [
 		"pi-package",
@@ -28,7 +28,8 @@
 		"extensions",
 		"scripts",
 		"fixtures",
-		"README.md"
+		"README.md",
+		"README_zh.md"
 	],
 	"pi": {
 		"extensions": [