@armadra/agent 0.7.1 → 0.7.3

package/dist/tui/program-status.js

@@ -0,0 +1,259 @@
+/**
+ * 终端程序状态协议 OSC 7501（Program Status Protocol rev 0.3，2026-10-07）：
+ * https://www.superlogical.com/rex/docs/build/program-status
+ *
+ * - 编码（纯函数）：`ESC ] 7501 ; key=value:… ESC \`。state 必填；id 每段 `[A-Za-z0-9_.+-]{1,32}`、
+ *   ≤ 8 层、≤ 128 字节；kind 只随 blocked、progress（0–100 整数）只随 working / blocked；app 同 id 段；
+ *   title / msg 去控制字符、压成一行后按 UTF-8 字节截断（192 / 2048，不切坏字符），再 base64。
+ *   字段不合法就丢掉该字段（state / id 不合法整条不发），不发终端会整条丢弃的坏报告；整条 ≤ 4096 字节。
+ * - 检测：发 `OSC 7501 ; ?` 紧跟 `CSI c`（DA1）；先收到 `?` 回复 = 支持，DA1 回复先到或超时 = 不支持。
+ *   两种回复都在输入解析里吞掉（`handleInput`），不会当成按键进输入框；迟到的回复同样吞掉。
+ * - tmux：缺省丢弃未知 OSC，`on` 时用 DCS passthrough（`ESC P tmux; … ESC \`，内容里 ESC 翻倍）包裹，
+ *   需要 `set -g allow-passthrough on`；tmux 不把外层终端对透传查询的回复转给窗格，所以 tmux 里 `auto`
+ *   不检测、等同 `off`。
+ * - 发射器：每个 id 记最后一次写出的报告，同值不重写；同一 state 下只换 msg / title 的更新按节流合并。
+ */
+export const PROGRAM_STATUS_QUERY = "\x1b]7501;?\x1b\\";
+export const DA1_QUERY = "\x1b[c";
+export const MAX_SEQUENCE_BYTES = 4096;
+export const MAX_TITLE_BYTES = 192;
+export const MAX_MSG_BYTES = 2048;
+const MAX_ID_BYTES = 128;
+const MAX_ID_DEPTH = 8;
+const SEGMENT = /^[A-Za-z0-9_.+-]{1,32}$/;
+const STATES = ["idle", "working", "done", "blocked", "error", "clear"];
+const KINDS = ["permission", "question", "auth"];
+const ELLIPSIS = "…";
+/** 控制字符（C0、DEL、C1）换成空格，空白压成一个，去首尾。 */
+export function sanitizeLine(text) {
+    return text
+        .replace(/[\x00-\x1f\x7f-\x9f]/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** 按 UTF-8 字节截断到 maxBytes（按码点切，不出半个字符）；截断时末尾带 `…`。 */
+export function truncateUtf8(text, maxBytes) {
+    if (Buffer.byteLength(text, "utf8") <= maxBytes)
+        return text;
+    const budget = maxBytes - Buffer.byteLength(ELLIPSIS, "utf8");
+    let used = 0;
+    let out = "";
+    for (const ch of text) {
+        const n = Buffer.byteLength(ch, "utf8");
+        if (used + n > budget)
+            break;
+        used += n;
+        out += ch;
+    }
+    return out + ELLIPSIS;
+}
+/** id 是否合法（空串不合法；根记录不带 id）。 */
+export function validId(id) {
+    if (Buffer.byteLength(id, "utf8") > MAX_ID_BYTES)
+        return false;
+    const segments = id.split("/");
+    return segments.length <= MAX_ID_DEPTH && segments.every((s) => SEGMENT.test(s));
+}
+/** 任意字符串 → 合法的单段 id（非法字符换 `_`，截到 n 个字符）；空串给 `x`。 */
+export function idSegment(raw, n = 12) {
+    const s = raw.replace(/[^A-Za-z0-9_.+-]/g, "_").slice(0, n);
+    return s === "" ? "x" : s;
+}
+function encodeText(text, maxBytes) {
+    if (text === undefined)
+        return undefined;
+    const line = sanitizeLine(text);
+    if (line === "")
+        return undefined;
+    return Buffer.from(truncateUtf8(line, maxBytes), "utf8").toString("base64");
+}
+/** 报告 → pairs（不含 OSC 包裹）；state / id 不合法返回 undefined。 */
+export function encodePairs(report) {
+    if (!STATES.includes(report.state))
+        return undefined;
+    if (report.id !== undefined && !validId(report.id))
+        return undefined;
+    const pairs = [`state=${report.state}`];
+    if (report.id !== undefined)
+        pairs.push(`id=${report.id}`);
+    if (report.state === "blocked" && report.kind !== undefined && KINDS.includes(report.kind))
+        pairs.push(`kind=${report.kind}`);
+    const p = report.progress;
+    if ((report.state === "working" || report.state === "blocked") &&
+        p !== undefined &&
+        Number.isInteger(p) &&
+        p >= 0 &&
+        p <= 100)
+        pairs.push(`progress=${p}`);
+    if (report.app !== undefined && SEGMENT.test(report.app))
+        pairs.push(`app=${report.app}`);
+    if (report.state !== "clear") {
+        const title = encodeText(report.title, MAX_TITLE_BYTES);
+        if (title !== undefined)
+            pairs.push(`title=${title}`);
+        const msg = encodeText(report.msg, MAX_MSG_BYTES);
+        if (msg !== undefined)
+            pairs.push(`msg=${msg}`);
+    }
+    // 各字段已有上限，整条最多约 3.2 KB；仍超限就依次丢 msg、title
+    while (osc(pairs.join(":")).length > MAX_SEQUENCE_BYTES) {
+        const last = pairs.at(-1);
+        if (!last.startsWith("msg=") && !last.startsWith("title="))
+            return undefined;
+        pairs.pop();
+    }
+    return pairs.join(":");
+}
+function osc(body) {
+    return `\x1b]7501;${body}\x1b\\`;
+}
+/** 完整的 OSC 7501 序列；报告不合法返回 undefined（不发坏报告）。 */
+export function encodeProgramStatus(report) {
+    const pairs = encodePairs(report);
+    return pairs === undefined ? undefined : osc(pairs);
+}
+/** tmux DCS passthrough：`ESC P tmux; <内容，ESC 翻倍> ESC \`。 */
+export function tmuxPassthrough(sequence) {
+    return `\x1bPtmux;${sequence.replaceAll("\x1b", "\x1b\x1b")}\x1b\\`;
+}
+/** 终端对 `OSC 7501 ; ?` 的回复（`?` 之后的内容忽略）。 */
+export function isProgramStatusReply(sequence) {
+    return /^\x1b\]7501;\?/.test(sequence);
+}
+/** DA1 回复 `CSI ? … c`。 */
+export function isDa1Reply(sequence) {
+    return /^\x1b\[\?[\d;]*c$/.test(sequence);
+}
+/** 发射器：检测、同值去重、节流；只在 `supported` 后写。 */
+export class ProgramStatusEmitter {
+    options;
+    support = "unknown";
+    tmux;
+    desired = new Map();
+    sent = new Map();
+    timers = new Map();
+    probeTimer;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.tmux = Boolean(options.env?.["TMUX"]);
+        this.now = options.now ?? Date.now;
+    }
+    /** 当前是否会写出报告。 */
+    get supported() {
+        return this.support === "yes";
+    }
+    /** 按模式开始：on 直接启用，auto 发检测查询（tmux 里不检测，等同 off），off 什么都不做。 */
+    start() {
+        if (this.support !== "unknown")
+            return;
+        const mode = this.options.mode;
+        if (mode === "off" || (mode === "auto" && this.tmux)) {
+            this.support = "no";
+            return;
+        }
+        if (mode === "on")
+            return this.enable();
+        this.support = "probing";
+        this.options.write(PROGRAM_STATUS_QUERY + DA1_QUERY);
+        this.probeTimer = setTimeout(() => this.settleProbe(false), this.options.timeoutMs ?? 300);
+        this.probeTimer.unref?.();
+    }
+    /** 输入解析里调用：吞掉检测回复（返回 true），其余返回 false。 */
+    handleInput(sequence) {
+        if (isProgramStatusReply(sequence)) {
+            if (this.support === "probing")
+                this.settleProbe(true);
+            return true;
+        }
+        if (isDa1Reply(sequence)) {
+            if (this.support === "probing")
+                this.settleProbe(false);
+            return true;
+        }
+        return false;
+    }
+    /** 设定某个 id（缺省根记录）的状态；`clear` 同时忘掉该 id 及其下层的记录。 */
+    report(report) {
+        const key = report.id ?? "";
+        const full = this.options.app !== undefined ? { ...report, app: this.options.app } : report;
+        if (report.state === "clear") {
+            for (const id of [...this.desired.keys()])
+                if (key === "" || id === key || id.startsWith(`${key}/`))
+                    this.forget(id);
+        }
+        this.desired.set(key, full);
+        if (this.support === "yes")
+            this.flush(key);
+        if (report.state === "clear")
+            this.desired.delete(key);
+    }
+    /** 停止计时器（不再写任何东西）。 */
+    dispose() {
+        if (this.probeTimer !== undefined)
+            clearTimeout(this.probeTimer);
+        this.probeTimer = undefined;
+        for (const timer of this.timers.values())
+            clearTimeout(timer);
+        this.timers.clear();
+        if (this.support === "probing")
+            this.support = "no";
+    }
+    settleProbe(ok) {
+        if (this.probeTimer !== undefined)
+            clearTimeout(this.probeTimer);
+        this.probeTimer = undefined;
+        if (ok)
+            this.enable();
+        else
+            this.support = "no";
+    }
+    enable() {
+        this.support = "yes";
+        for (const key of this.desired.keys())
+            this.flush(key);
+    }
+    forget(id) {
+        this.desired.delete(id);
+        this.sent.delete(id);
+        const timer = this.timers.get(id);
+        if (timer !== undefined)
+            clearTimeout(timer);
+        this.timers.delete(id);
+    }
+    flush(key) {
+        const report = this.desired.get(key);
+        if (report === undefined)
+            return;
+        const body = encodePairs(report);
+        if (body === undefined)
+            return;
+        const last = this.sent.get(key);
+        if (last?.body === body)
+            return;
+        const throttle = this.options.throttleMs ?? 500;
+        const head = `${report.state}:${report.kind ?? ""}`;
+        const wait = last !== undefined && last.head === head ? last.at + throttle - this.now() : 0;
+        if (wait > 0 && report.state !== "clear") {
+            if (!this.timers.has(key)) {
+                const timer = setTimeout(() => {
+                    this.timers.delete(key);
+                    this.flush(key);
+                }, wait);
+                timer.unref?.();
+                this.timers.set(key, timer);
+            }
+            return;
+        }
+        const timer = this.timers.get(key);
+        if (timer !== undefined)
+            clearTimeout(timer);
+        this.timers.delete(key);
+        const sequence = osc(body);
+        this.options.write(this.tmux ? tmuxPassthrough(sequence) : sequence);
+        if (report.state === "clear")
+            this.sent.delete(key);
+        else
+            this.sent.set(key, { body, head, at: this.now() });
+    }
+}

package/docs/acp.md

@@ -60,13 +60,13 @@ ama --mode acp                      # 与 -p 互斥；其余参数（--model、-
 | 工具开始                            | `tool_call_update`（`in_progress`）                                                                                                                                                                                            |
 | 工具结束（含内层）                  | `tool_call_update`（`completed` / `failed`）；`content` 为 `[diff?, 文本]`：edit / write 带 `diff`（`path`、`oldText`、`newText`，新文件 `oldText: null`），文本只带前 4 KB；`locations[].line` 是首个改动行；不发 `rawOutput` |
 | `todo` 更新                         | `plan`                                                                                                                                                                                                                         |
-| 每轮结束                            | `usage_update`（上下文已用、窗口、会话累计美元）                                                                                                                                                                               |
+| 每条助手消息结束、每轮结束          | `usage_update`（上下文已用、窗口、会话累计美元）；与上次同值不重发                                                                                                                                                             |
 | 权限模式变化                        | `current_mode_update`                                                                                                                                                                                                          |
-| 模型 / 思考级别变化                 | `config_option_update`（全部配置项）                                                                                                                                                                                           |
-| 会话开出（new / load / resume）之后 | `available_commands_update` 与 `config_option_update`                                                                                                                                                                          |
+| 模型 / 思考级别变化                 | `config_option_update`（全部配置项）；换模型时另发一条 `usage_update`（窗口可能变了）                                                                                                                                          |
+| 会话开出（new / load / resume）之后 | `available_commands_update`、`config_option_update` 与 `usage_update`（load 在回放之后），客户端不用等第一轮结束                                                                                                               |
 | 回合结束之后                        | `session_info_update`（`updatedAt`；标题与上次不同才带 `title`）                                                                                                                                                               |
 
-diff 的改前 / 改后全文只随实时事件走，不写进会话文件：任一侧超过 256 KiB 不带 diff，`session/load` 回放的工具结果只有前 4 KB 文本。模式列表的 `name` 是显示名（如 `Manual`、`Accept edits`），`description` 随界面语言。`session/prompt` 的结果带本回合 token 用量 `usage`（`inputTokens`、`outputTokens`、`cachedReadTokens`、`cachedWriteTokens`、`totalTokens`）；该字段在 schema 1.24.1 里仍是 UNSTABLE（只在不稳定 schema 中），客户端可以忽略，以 `usage_update` 为准。
+diff 的改前 / 改后全文只随实时事件走，不写进会话文件：任一侧超过 256 KiB 不带 diff，`session/load` 回放的工具结果只有前 4 KB 文本。模式列表的 `name` 是显示名（如 `Manual`、`Accept edits`），`description` 随界面语言。`session/prompt` 的结果带本回合 token 用量 `usage`（`inputTokens`、`outputTokens`、`cachedReadTokens`、`cachedWriteTokens`、`totalTokens`）；该字段在 schema 1.24.1 里仍是 UNSTABLE（只在不稳定 schema 中），客户端可以忽略，以 `usage_update` 为准。模型窗口未知时（如没有 `contextWindow` 的自定义模型）不发 `usage_update`：schema 里 `size` 必填，ama 不编造窗口。
 
 `toolCallId` 在会话内唯一：上游供应商给的 id 若在后续回合重复（个别兼容接口的兜底 id、测试用假模型），线上 id 加 `#2`、`#3`… 区分，之后的状态更新、审批与回放都按这个映射（客户端按 id 合并条目，不区分会把不同调用合成一条）。
 

package/docs/agents.md

@@ -256,7 +256,7 @@ ACP Agent 不给 `modes`、改用 category `mode` 的配置项表达模式时，
 - **信任**：只在 ama 已信任的目录里起外部 Agent（`claude -p` 会跳过目录信任对话框并执行项目 hooks 与配置）；未信任时 `task` 报错并提示 `ama trust`。
 - **并发**：外部 Agent 总共 `agents.maxConcurrent`（缺省 3），每个 Agent 另有上限（`agents.<id>.maxConcurrent`，claude 缺省 2）；超出排队，排队可被中断。与 ama 子会话的并发分开计。
 - **预算**：`task` 的 `budgetUsd`（Claude 透传 `--max-budget-usd`，其余按用量累计、超限中断）；`agents.sessionBudgetUsd` 是本会话外部 Agent 的美元总额，用尽后不再启动。Codex 订阅 token、Copilot premium request 按各自单位记，不换算美元；Claude 的 `total_cost_usd` 是它自己的估算。
-- **记账**：每回合写 `custom{ama.agent-usage}`，会话建立写 `custom{ama.agent-session}`（外部 CLI 自己的会话 id，用于续聊）；`/session` 与 `get_session_stats` 的 `external` 段按 Agent 汇总。ama 会话只存最终文本、工具摘要、用量与引用，外部 Agent 的原始事件只在内存里显示，不落盘。
+- **记账**：每回合写 `custom{ama.agent-usage}`，会话建立写 `custom{ama.agent-session}`（外部 CLI 自己的会话 id，用于续聊）；`/session` 与 `get_session_stats` 的 `external` 段按 Agent 汇总。外部 Agent 报告了上下文占用与窗口（ACP 的 `usage_update`、Codex app-server 的 `tokenUsage`）时，只记这两个数字：任务记录与 `ama.agent-usage` 带 `contextTokens / contextWindow`，`external.byAgent` 取最近一次，`/tasks` 与 Agent 栏的任务行显示 `ctx 34%`（低于 10% 保留一位小数）；回合中途变化也会即时更新。ama 会话只存最终文本、工具摘要、用量与引用，外部 Agent 的原始事件只在内存里显示，不落盘。
 - **看门狗**：单回合缺省 30 分钟；中断后 15 秒内没有回合结束就关 stdin 再结束进程树；空闲 10 分钟关进程，能续接的下次续聊时以 resume 重开。外部 Agent 进程登记在 `<数据目录>/drivers/pids.json`，ama 异常退出留下的孤儿在下次使用时清理（核对命令行，pid 被复用的不杀）。
 
 ### 嵌入宿主

package/docs/en/acp.md

@@ -60,13 +60,13 @@ One `ama --mode acp` process can keep several sessions open (Zed's threads share
 | Tool starts                                 | `tool_call_update` (`in_progress`)                                                                                                                                                                                                                                         |
 | Tool ends (inner calls included)            | `tool_call_update` (`completed` / `failed`); `content` is `[diff?, text]`: edit / write carry a `diff` (`path`, `oldText`, `newText`; `oldText: null` for a new file), the text is limited to the first 4 KB; `locations[].line` is the first changed line; no `rawOutput` |
 | `todo` update                               | `plan`                                                                                                                                                                                                                                                                     |
-| End of each turn                            | `usage_update` (context used, window size, session cost in USD)                                                                                                                                                                                                            |
+| End of each assistant message and each turn | `usage_update` (context used, window size, session cost in USD); not resent when unchanged                                                                                                                                                                                 |
 | Permission mode change                      | `current_mode_update`                                                                                                                                                                                                                                                      |
-| Model / thinking level change               | `config_option_update` (all options)                                                                                                                                                                                                                                       |
-| After a session opens (new / load / resume) | `available_commands_update` and `config_option_update`                                                                                                                                                                                                                     |
+| Model / thinking level change               | `config_option_update` (all options); a model change also sends a `usage_update` (the window may differ)                                                                                                                                                                   |
+| After a session opens (new / load / resume) | `available_commands_update`, `config_option_update` and `usage_update` (for load, after the replay), so clients need not wait for the first turn                                                                                                                           |
 | After a turn                                | `session_info_update` (`updatedAt`; `title` only when it differs from the last one)                                                                                                                                                                                        |
 
-The full before / after text of a diff only travels with live events and is never written to the session file: above 256 KiB on either side there is no diff, and tool results replayed by `session/load` carry only their first 4 KB of text. The `name` of each mode is its display name (such as `Manual` or `Accept edits`); the `description` follows the UI language. The `session/prompt` result carries the turn's token usage `usage` (`inputTokens`, `outputTokens`, `cachedReadTokens`, `cachedWriteTokens`, `totalTokens`); in schema 1.24.1 this field is still UNSTABLE (only in the unstable schema), so clients may ignore it and rely on `usage_update`.
+The full before / after text of a diff only travels with live events and is never written to the session file: above 256 KiB on either side there is no diff, and tool results replayed by `session/load` carry only their first 4 KB of text. The `name` of each mode is its display name (such as `Manual` or `Accept edits`); the `description` follows the UI language. The `session/prompt` result carries the turn's token usage `usage` (`inputTokens`, `outputTokens`, `cachedReadTokens`, `cachedWriteTokens`, `totalTokens`); in schema 1.24.1 this field is still UNSTABLE (only in the unstable schema), so clients may ignore it and rely on `usage_update`. When the model's context window is unknown (such as a custom model without `contextWindow`), no `usage_update` is sent: `size` is required by the schema and ama does not make up a window.
 
 `toolCallId` is unique within a session: when the upstream provider reuses an id in a later turn (fallback ids of a few compatible APIs, the fake test model), the wire id gets `#2`, `#3`, … and later status updates, approvals and replay follow that mapping (clients merge entries by id, so without this different calls would collapse into one).
 

package/docs/en/providers.md

@@ -400,7 +400,7 @@ Inference order: conservative defaults ← inference table (provider id, then ba
 | `requiresReasoningContentOnAssistantMessages` | Earlier assistant messages of reasoning models carry `reasoning_content` (DeepSeek)                                      |
 | `requiresToolResultName`                      | Tool result messages carry `name` (Mistral)                                                                              |
 | `requiresAssistantAfterToolResult`            | Insert an assistant message when a user message directly follows a tool result                                           |
-| `supportsMidConvoSystemMessages`              | Later system prompt patches are inserted back as system messages at their position                                       |
+| `supportsMidConvoSystemMessages`              | Later prompt patches go back as system messages in place; off (default): trailing context, see "Caching"                 |
 | `cacheControlFormat`                          | `anthropic`: put `cache_control` on the system prompt, the last tool and the last user/tool message                      |
 | `supportsStrictTools`                         | Send `strict: true` for strictly compatible tool schemas                                                                 |
 | `supportsStore`                               | Send `store: false`                                                                                                      |
@@ -439,6 +439,8 @@ Most usage in long tasks is cache reads: once the prefix changes, every later re
 
 Prefix stability is guaranteed by assembly: the system prompt sections have a fixed order without timestamps, tools are sorted by name, and mid-session changes are only appended at the end as system patches ([session-format.md](../session-format.md), Chinese).
 
+Section patches after the conversation has started (AGENTS.md, Skills or SessionStart hook output changed on resume, host instructions refreshed, the memory section re-rendered after compaction) **do not rewrite the leading system prompt**: protocols without `supportsMidConvoSystemMessages` render them as a user message wrapped in `<system-reminder>` at the patch's position, so the previous request stays a byte-for-byte prefix. The only exception is a patch that removes tools: the tool list itself changed and the prefix is lost anyway, so all patches are folded back into the head as before. Measured on DeepSeek, a mid-conversation system message is accepted and the prefix cache holds, but the model still answers from the leading one, so DeepSeek keeps the switch off ([cache-midconvo-2026-10-09](../benchmarks/cache-midconvo-2026-10-09.md), Chinese). At the next compaction these patches are folded into the head together with the system checkpoint.
+
 ### Request fields
 
 | Protocol                                  | Field                                                                                                   | Condition                                                                                                    |
@@ -476,7 +478,7 @@ If any cache field appears in the raw usage (even 0) → `Usage.cacheReported =
 
 ### Model catalog `promptCache`
 
-Only publicly documented values are written (seconds / tokens): all Anthropic models `short 300 / long 3600`, with `minTokens` 512–4096 by model; all OpenAI models `short 300 / long 86400 / minTokens 1024`; all Kimi models `short 300`. DeepSeek, Zhipu, Qwen, Groq, xAI, Mistral, OpenRouter and Google promise no TTL, so it stays empty (no warming; attribution assumes 10 minutes for implicit caching). You can fill it in yourself in `models[]` / `modelOverrides[]`.
+Only publicly documented values are written (seconds / tokens): all Anthropic models `short 300 / long 3600`, with `minTokens` 512–4096 by model; all OpenAI models `short 300 / long 86400 / minTokens 1024`; all Kimi models `short 300`; all DeepSeek models `short 3600 / minTokens 2048` (the vendor only says unused cache is cleared after "a few hours to a few days", so the conservative 1 hour is used; cache reads were measured in 2048-token blocks). Zhipu, Qwen, Groq, xAI, Mistral, OpenRouter and Google promise no TTL, so it stays empty: no warming and no early pruning on a guessed lifetime; only miss attribution assumes 10 minutes for implicit caching. You can fill it in yourself in `models[]` / `modelOverrides[]`; DeepSeek models on relays do not inherit the official catalog values, fill them in the same way if needed.
 
 ### Session layer: fingerprints, misses and three states
 
@@ -541,7 +543,7 @@ ama models cache-probe <provider/id> [--tokens 2048] [--gap-ms 3000] [--json] [-
 
 It sends a deterministic fixed prefix (about `--tokens` tokens) + `Reply with: ok`, `maxTokens: 16`, twice `--gap-ms` apart, and decides:
 
-- `reported`: the second cacheRead ≥ 50% of the prefix; when the catalog has no `promptCache`, it suggests filling in `promptCache.short` to enable warming;
+- `reported`: the second cacheRead ≥ 50% of the prefix; when the catalog has no `promptCache`, it explains that the lifetime is unknown (no warming, no early pruning) and to fill it in only with a lifetime the upstream documents, without suggesting a guessed value — a value that is too short fires warming and early pruning while the cache is still valid;
 - `silent`: reads and writes were 0 both times; it suggests setting `compat.cacheReporting: "silent"`. When the response has cache fields that stay 0, it also hints at a possible write delay (kimi-k2.5 on the same relay read 0 twice 3 seconds apart, but the full prefix on the second request 8 seconds apart), so retry with a larger `--gap-ms`;
 - `inconclusive`: a small read or only writes, most likely a cache granularity or TTL issue.
 

package/docs/en/rpc.md

@@ -285,6 +285,7 @@ The `data` of `get_session_stats` is `SessionStats`:
 | `tokens`                                                           | `{ input, output, cacheRead, cacheWrite, total }`, including warming requests                       |
 | `cost`                                                             | USD; absent when any message lacks a cost (the interface shows `$?`)                                |
 | `contextTokens` / `contextWindow` / `contextPercent`               | Current context estimate, window and usage (0–100); absent when the model has no window             |
+| `context`                                                          | Estimate source and auto-compaction thresholds (fields: sessions.md)                                |
 | `cacheHitRate`                                                     | The legacy hit rate: cacheRead / (input + cacheRead + cacheWrite), every request in the denominator |
 | `cache`                                                            | `SessionCacheStats` (example below), present only when the session-layer cache controller is wired  |
 
@@ -334,6 +335,8 @@ The `data` of `get_session_stats` is `SessionStats`:
 
 `cache_miss` gives `detail` only for `prefix_changed` (`system` / `tools`). The values and meanings of `reason` for `cache_warm{stopped}` are in [tui.md](tui.md) "Cache and context". The result object of `ama -p --output-format json` also has a `cache` field of the same shape.
 
+It also carries `context: { tokens, window, percent }` (context used, window size and usage 0–100, defined like `contextTokens` / `contextWindow` / `contextPercent` in the table above); an unknown item is omitted (for a model without a window only `tokens` is present), and when all are unknown there is no `context`.
+
 ## Approvals
 
 1. When a tool call needs confirmation, the server sends `permission_request`. `preview` (optional) is the pre-execution preview: `{ kind: "bash" | "write" | "edit" | "other", lines: string[], severity: "info" | "warn" | "danger", affected?: { path, exists, bytes?, files? }[] }`; `lines` are already laid out without colors and can be shown as is. The preview is read-only and bounded, and absent when it cannot be computed.

package/docs/en/sessions.md

@@ -61,6 +61,29 @@ those notification turns are written to the same session file.
 - A per-file summary is cached in `<data dir>/stats-index.json`, invalidated by file mtime and size; a time-zone change invalidates the whole index; a full scan also drops files that no longer exist. `--no-cache` neither reads nor writes it.
 - Measured (local machine, `src/session/stats-perf.test.ts`): 1000 sessions, 67 MB (12 turns, 24 tool calls and 2 KB tool results each), about 160 ms cold and about 15 ms with the index.
 
+## Context usage of the current session (`getStats()` / `get_session_stats`)
+
+`ama stats` reports historical billed usage; how much context the running session has left is in the context fields of
+`SessionStats` (SDK `session.getStats()`, passed through unchanged by RPC `get_session_stats`; the status bar and `/session` read
+the same fields):
+
+| Field                    | Meaning                                                                                                                                                                                                      |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `contextTokens`          | Estimated tokens of context the next request will carry (see `context.source` for how)                                                                                                                       |
+| `contextWindow`          | The current model's window; **absent** when the model has no window information (fix it with `ama models discover` or by setting `contextWindow` for the model in config)                                    |
+| `contextPercent`         | `contextTokens / contextWindow`, 0–100 with one decimal, capped at 100; **absent** without a window (the UI shows `ctx ?`)                                                                                   |
+| `context.source`         | `usage`: usage of the last valid assistant message + an estimate of the messages after it; `estimate`: no trustworthy usage, the whole context is estimated; `prefix`: the baseline before the first request |
+| `context.usageTokens`    | The part taken from usage; 0 for `estimate` / `prefix`                                                                                                                                                       |
+| `context.trailingTokens` | The estimated part (messages after the usage, or the whole estimate / baseline)                                                                                                                              |
+| `context.autoCompactAt`  | Threshold of automatic summarization (tier two) = window − `compaction.reserveTokens`; **absent** when auto-compaction is off, tripped after repeated failures, or there is no window                        |
+| `context.pruneAt`        | Threshold of tool-result pruning (tier one) = 0.7 × (window − `reserveTokens`); absent under the same conditions                                                                                             |
+
+- **Estimation**: CJK ideographs / kana / hangul count 1 token each, other characters / 4, images 1,600 each; usage uses `totalTokens` (or input + output + cache reads / writes, output included).
+- **Before the first request** (`prefix`): the system prompt and tool table are written to the session only at the first request, so until then the estimate is taken from what is about to be sent (section texts + tool declaration JSON); a new session is not at 0 the moment it opens. This is for stats only: nothing is written to the session and the request body does not change.
+- **After compaction / context edits** (`estimate`): the last usage no longer describes the current context, so the whole context is estimated until the next request brings new usage; the UI puts `≈` in front of the number.
+- **An absent field means "unknown"**, not 0: `contextWindow`, `contextPercent`, `context.autoCompactAt` and `context.pruneAt` are left out of the JSON when absent. Older versions or custom session implementations may not have `context`; reading `contextTokens` is enough there.
+- `tokens` (`{ input, output, cacheRead, cacheWrite, total }`) is the **session total** of billed usage, including requests that never enter the context (compaction summaries, cache warming); do not read it as context usage.
+
 ## Search: `ama sessions search`
 
 ```

package/docs/en/tui.md

@@ -39,8 +39,8 @@ The visual spec (colors, glyphs, screen-by-screen mockups) is in [tui-design.md]
 ────────────────────────────────────────────────
 › Type a message, / commands, @ files, Shift+Enter newline   ← input box (placeholder)
 ────────────────────────────────────────────────
-codemode on        tps: 100 tok/s • 546 tok / 5.5s (avg 100 · ttft 1.4s) · ↑12k ↓1.2k · cache 80% ♨ · [-]   ← rate line (full)
-Accept edits | shift+tab to cycle    claude-opus-5-5 medium | Ctx 3.0% | proj ⎇ main 5ae9e54 ↑2 (+12,-3) | $0.26 | 2h24m
+codemode on        tps: 100 tok/s • 546 tok / 5.5s (avg 100 · ttft 1.4s) · Σ↑12k ↓1.2k R9.6k · cache 80% ♨ · [-]   ← rate line (full)
+Accept edits | shift+tab to cycle    claude-opus-5-5 medium | Ctx 3.0% 8.2k/272k auto | proj ⎇ main 5ae9e54 ↑2 (+12,-3) | $0.26 | 2h24m
                           Session: 10.0% | Reset: 2h 18m | Weekly: 31.0% | Weekly Reset: 6d 5h   ← subscription quota line (full, ChatGPT subscription model)
 ```
 
@@ -50,16 +50,17 @@ Accept edits | shift+tab to cycle    claude-opus-5-5 medium | Ctx 3.0% | proj
 - **Notices**: `✗` errors, `↻ retry n/m`, `!` warnings (cache misses, remaining context), `⛔` hook blocks, host notifications, explanations of denied or timed-out approvals; compaction / branch summaries are left-bar cards (`▎ context compacted  128k → 24k tokens`).
 - **Running**: `⠋ verb · elapsed · …`, with the verb taken from the deepest current state: waiting for confirmation (approval open), `running bash` / `running 3 tools`, `retry 2/3 · in 2s`, compacting context, replying `· ↓≈1.2k` (estimated tokens of this output), thinking. While a foreground sub-agent task blocks the turn, `Ctrl+B to background` is appended; while the agent bar has tasks, `↓ Agent bar` is appended (`↓ handle approval` instead when an approval is docked): `⠏ running task · 4s · Esc to interrupt · Ctrl+B to background · ↓ Agent bar`; items are dropped whole from the end when the line does not fit. With text in the input box, `Enter queue · Ctrl+X interrupt & send` comes first (`Enter interrupt & send · Ctrl+X queue` with `ui.enterWhileRunning: "interrupt"`); with queued steers the queue's last line reads `Alt+↑ take back · Ctrl+X send now · Esc refill and interrupt`.
 - **Status bar**: the mode is always on the far left; `full` splits into two sides — the left column holds state and switches (permission mode, the `shift+tab` hint, codemode, sandbox, preset, fallback), the right column holds metrics and the model (tps, usage, model, Ctx, git, cost, duration, quota), right-aligned, and a line with nothing on the left sits flush right; the status bar is the last line except for the subscription quota line in the `full` layout (`compact` always keeps it last). In `compact` the separator is always `·` (embedding hosts parse it), in `full` it is `|`. The layout follows `ui.statusLine`: `full` (two lines) by default in a standalone terminal, `compact` (one line, same layout as before) by default in an embedding host with a profile; `Ctrl+G` or `/statusline [full|compact]` switches at runtime for this session only. With `full` the input box is the 4th line from the bottom (`compact` keeps it 3rd from the bottom).
-  - **`full` top line (rate line)**: the left side holds switches: `codemode on|only` (with `net!` when the network is not isolated) · `sandbox` · `preset <name>` (when not default) · `→ <fallback model>` (during a fallback, yellow) · queue count · host status; it is empty when there are none. The right side is `tps: <rate> tok/s • <output tokens> tok / <elapsed> (avg <session average> · ttft <time to first token>) · ↑<input> ↓<output> · cache · re-billing · [-]`. While streaming the rate is the instantaneous value over the last 2 s (`tps:` in the accent color); afterwards it is the request's average; whole replies generated in under 0.25 s get no rate and show `—`; elapsed time starts at the first token; `↑` input includes cache reads and writes; in ASCII `•` becomes `*` and `→` becomes `->`; `[-]` at the end hints that it folds. Only chat requests count (compaction summaries, warming and the classifier do not). When narrow, the right-side metrics drop first (output / elapsed, tokens, cache, re-billing, avg, ttft), then the left-side switches (host status, queue count, preset, fallback, sandbox, codemode); `tps` and `[-]` never drop.
-  - **`full` bottom line**: on the left `permission mode | shift+tab to switch`, on the right `model thinking-level | Ctx 3.0% | <dir name> ⎇ <branch> <short commit> ↑N ↓N (+a,-d) | $cost | session duration` (Ctx with one decimal, no meter even when wide); when narrow, these drop in order: the switch hint, thinking level, line changes, directory name, branch and commit, duration, cost, context, model.
+  - **`full` top line (rate line)**: the left side holds switches: `codemode on|only` (with `net!` when the network is not isolated) · `sandbox` · `preset <name>` (when not default) · `→ <fallback model>` (during a fallback, yellow) · queue count · host status; it is empty when there are none. The right side is `tps: <rate> tok/s • <output tokens> tok / <elapsed> (avg <session average> · ttft <time to first token>) · Σ↑<input> ↓<output> R<cache read> W<cache write> · cache · re-billing · [-]`. While streaming the rate is the instantaneous value over the last 2 s (`tps:` in the accent color); afterwards it is the request's average; whole replies generated in under 0.25 s get no rate and show `—`; elapsed time starts at the first token; `Σ` marks the **session total** of billed tokens (not context usage), `↑` input includes cache reads and writes, which are also listed as `R` / `W` (hidden when 0; `Σ` is `sum ` in ASCII); in ASCII `•` becomes `*` and `→` becomes `->`; `[-]` at the end hints that it folds. Only chat requests count (compaction summaries, warming and the classifier do not). When narrow, the right-side metrics drop first (output / elapsed, tokens, cache, re-billing, avg, ttft), then the left-side switches (host status, queue count, preset, fallback, sandbox, codemode); `tps` and `[-]` never drop.
+  - **`full` bottom line**: on the left `permission mode | shift+tab to switch`, on the right `model thinking-level | Ctx 3.0% 8.2k/272k auto | <dir name> ⎇ <branch> <short commit> ↑N ↓N (+a,-d) | $cost | session duration` (Ctx with one decimal, no meter even when wide). The Ctx part is the current context: the percentage, used / window, and `auto` while auto-compaction is on (hidden when it is off, tripped after repeated failures, or the window is unknown); the numbers get a leading `≈` when they do not come from usage reported by the model (the baseline estimated from the system prompt and tool declarations before the first request, or the full estimate after a compaction until the next request); without a window it reads `Ctx ? 8.2k`. When narrow, these drop in order: `auto`, the switch hint, thinking level, `/window`, line changes, directory name, branch and commit, used tokens, duration, cost, the context percentage, model.
   - **Subscription quota line** (third `full` line, below the status bar): when the current model uses a ChatGPT subscription (the `chatgpt` provider) it shows `Session: <used %> | Reset: <time to reset> | Weekly: <used %> | Weekly Reset: <time to reset>` (Chinese labels in the Chinese interface), from the latest `quota_update` (the codex flavor's `x-codex-primary/secondary-*` response headers and `codex.rate_limits` events; siwc only has it after a 429). Reset times are relative (`2h 18m`, `6d 5h`) and refresh once a minute. Before the first request the codex flavor shows "Quota: shown after the first request" (the first request brings the quota back, so holding the line avoids the row count jumping); siwc without data takes no line (it only gets a quota when over the limit, so a placeholder would stay forever); non-subscription models show nothing. Below 80 columns it compresses to `5h 10% ↻2h18m · wk 31% ↻6d5h`, dropping the reset times first when narrower. The quota line is right-aligned. Labels follow the window length rather than the primary / secondary slot: 300 minutes is `Session`, 10080 minutes is `Weekly`, any other length shows the length itself (`1d: `); without a length, primary counts as Session and secondary as Weekly (or the other one if that name is taken); windows are ordered shortest first. A window with 0 % used, no length and no reset time is the server saying "no such window" and is not shown (some plans get a single weekly window from codex, sent as primary). `Ctrl+G` / `/statusline compact` folds the quota line together with the rate line (`compact` stays a single line; hosts anchor on "last line = status bar").
-  - **Colors** (`full`): labels, units, separators and parentheses dim gray; the rate number purple, output / elapsed / avg blue, ttft purple; model and thinking level blue; Ctx and quota percentages by threshold green / yellow / red (≥ 70% yellow, ≥ 90% red); directory and branch green, short commit dim, `↑N` ahead orange, `↓N` behind red, `(+a,-d)` green / red; cost yellow; duration and reset times purple. All come from theme semantic colors with dark / light and 16-color mappings; `NO_COLOR` and ASCII drop the colors and keep the structure. `compact` colors are unchanged.
+  - **Colors** (`full`): labels, units, separators and parentheses dim gray; the rate number purple, output / elapsed / avg blue, ttft purple; model and thinking level blue; Ctx by threshold green / yellow / red (yellow once past the tier-one pruning threshold — 0.7 × (window − reserve), a little under 70%; red at ≥ 90%; ≥ 70% yellow when there is no threshold), quota percentages yellow at ≥ 70% and red at ≥ 90%; directory and branch green, short commit dim, `↑N` ahead orange, `↓N` behind red, `(+a,-d)` green / red; cost yellow; duration and reset times purple. All come from theme semantic colors with dark / light and 16-color mappings; `NO_COLOR` and ASCII drop the colors and keep the structure. `compact` colors are unchanged.
   - **`compact`**: one line; on the right model · thinking level · `↑ ↓` · cache · cost · re-billing · context usage · dir ⎇ branch commit +a −b · session duration · queue count · codemode · preset · host status · a short subscription quota item (`5h 10% wk 31%`, only with quota data; no `·` inside the item); when narrow, these drop in order: the quota item, the switch hint, host status, preset, re-billing, cost, cache, tokens, thinking level, queue count, codemode, line changes, directory name, branch and commit, duration, context, model.
   - **git**: branch and short commit are read directly from `.git/HEAD` (worktrees understood; detached shows only the short commit; outside git the whole part is omitted, leaving only the directory name). `+a −b` is the working tree (staged included) line diff against HEAD, computed in the background with `git diff --numstat HEAD` after a turn ends, a writing tool finishes, a rewind or `/tree`, at most once every 10 seconds; if it takes longer than 2 seconds or fails, line changes are hidden for the rest of the session; `AMA_STATUS_GIT=0` turns it off. In `full`, `↑N` / `↓N` count the commits the current branch is ahead of / behind its upstream: when the branch has an upstream in the git config (`branch.<name>.merge`), the same throttled cycle then runs `git rev-list --left-right --count @{upstream}...HEAD` (same 2-second timeout; after a timeout it stops for the session); zero, no upstream or detached shows nothing; ASCII uses `^N` / `vN`.
   - **Cost** includes sub-tasks, warming, the classifier and external agent usage priced in USD (other units only in `/session`); **duration** counts from when this process opened the current session (`Ns` / `Nm` / `NhMm`).
   - When bash commands run in the OS sandbox (`sandbox.bash: "auto"` and available on this machine, see [sandbox.md](../sandbox.md), Chinese), the usage items gain a sandbox marker, dropped first together with codemode when space runs out.
   - During a model fallback (`fallbackModel`: when the main model is overloaded or retries are exhausted, one retry with the fallback model) the `compact` model item shows `main model → fallback model` (the fallback in yellow), while `full` keeps only the main model there and shows `→ fallback model` on the left of the rate line; it disappears once the fallback model replies and the main model is restored, and the message area gets an explanatory line.
-  - Model names abbreviate with width (provider dropped below 100 columns, channel below 60, version suffix below 48); `compact` at ≥ 110 columns shows context as a meter `ctx ▮▮▮▯▯▯▯▯▯▯ 34%`; changing numbers reserve their widest shape, so items never flicker in and out as values change. In ASCII mode `⎇` → `git`, `−` → `-`, `♨` → `~`, `↻` → `@`.
+  - **Context refresh**: it updates right after a message is submitted (the new message counted as an estimate); while streaming, once the reply carries usage (some protocols report input tokens at the start) it switches to the measured value of the in-flight request, at most twice a second; after the reply ends, a compaction or a model change it goes back to the session stats.
+  - Model names abbreviate with width (provider dropped below 100 columns, channel below 60, version suffix below 48); `compact` at ≥ 110 columns shows context as a meter `ctx ▮▮▮▯▯▯▯▯▯▯ 34%`, keeping one decimal below 1% (`ctx ≈0.4%` rather than 0%), with the same `≈` for estimates; changing numbers reserve their widest shape, so items never flicker in and out as values change. In ASCII mode `⎇` → `git`, `−` → `-`, `♨` → `~`, `↻` → `@`.
 - **Exit**: a session summary line and the resume command are appended at the end of the message area and stay in the terminal scrollback:
 
 ```
@@ -78,7 +79,7 @@ Status bar items:
 | `cache` "not reported" | The endpoint does not report cache usage (`silent`: reads and writes were 0 for 3 comparable requests in a row, or `compat.cacheReporting: "silent"`); such requests stay out of the hit-rate denominator |
 | `♨`                    | Warming timer running (during long tool runs the prefix is replayed per TTL; `/cache warm` switches it)                                                                                                   |
 | `rebill $0.11`         | Re-billing caused by cache misses in this session; token count for models without prices; hidden when 0                                                                                                   |
-| `ctx 72%`              | Context usage: green below 70%, yellow at ≥ 70%, red at ≥ 90%; `ctx ?` means the model has no window information                                                                                          |
+| `ctx 72%`              | Context usage: yellow past the pruning threshold, red at ≥ 90%; `≈` an estimate; `ctx ?` no window information                                                                                            |
 | `codemode only`        | codemode active (`on` / `only`); a red `net!` is appended when the network is not isolated (Node 22 / 24 without an OS sandbox, see sandbox.md)                                                           |
 
 The message area (stderr with an `ama: ` prefix in line mode) shows one line in only two cases; `cache.missNotices: false` turns them off:
@@ -91,10 +92,10 @@ The message area (stderr with an `ama: ` prefix in line mode) shows one line in
 
 ```
 ▎ Session 3f2a9c1e  ~/.local/share/ama/sessions/…/3f2a9c1e.jsonl
-▎ Model    anthropic/claude-sonnet-4-5 · thinking medium · permission Accept edits
-▎ Messages user 7 · assistant 9 · tool calls 23
-▎ Usage    input 3.4k · output 9.4k · cache read 118k · cache write 6.2k · $0.42
-▎ Context  ▮▮▮▯▯▯▯▯▯▯ 34% · 68k / 200k
+▎ Model        anthropic/claude-sonnet-4-5 · thinking medium · permission Accept edits
+▎ Messages     user 7 · assistant 9 · tool calls 23
+▎ Total usage  input 3.4k · output 9.4k · cache read 118k · cache write 6.2k · $0.42
+▎ Context      ▮▮▮▯▯▯▯▯▯▯ 34% · 68k / 200k · ≈ 116k until auto-compaction
 ▎
 ▎ Cache
 ▎   Input      3.4k = cache read 2.2k (65%) + uncached 1.2k
@@ -219,6 +220,38 @@ Design in [rewind-plan.md](../rewind-plan.md) (Chinese). Every user message that
 - `/plan`: the current plan panel (see "Plan approval" below); `/plan <goal>` enters Plan mode and sends the goal; `/plan approve [mode|fresh]` and `/plan reject` approve / discard directly without a dialog.
 - `/tasks`: focus the agent bar, `/tasks <id>` opens the sub-agent view; `/agents`: the available sub-agent types (see "Sub-agents" below).
 - `/paste`: same as `Ctrl+V`.
+- `/context`: a per-category breakdown of the context (see the next section).
+
+### /context
+
+`/context` answers "what is taking up the context". Interactive mode draws a left-bar panel; line mode, and interactive mode without a panel, print the same content as plain text:
+
+```
+▎ Context
+▎ Used          10.6k / 200k (5.3%)
+▎ Left          189k tokens
+▎ Source        reported usage 9k + estimated 1.6k
+▎ Auto-compact  at 184k, ≈ 173k to go
+▎ Pruning       old tool results trimmed from 129k
+▎
+▎ By category (estimated, 5.8k)
+▎   System prompt and tool declarations are counted from the stored system messages; the full estimate can differ from reported usage.
+▎   System prompt           600  ▮▯▯▯▯▯▯▯▯▯ 10%  rules 500 · preamble 100 · cwd 0
+▎   Tool declarations       333  ▮▯▯▯▯▯▯▯▯▯ 6%  bash 241 · read 91
+▎   …
+▎   Tool results           3.2k  ▮▮▮▮▮▯▯▯▯▯ 55%  read 3k · bash 203
+▎   Images                 1.6k  ▮▮▮▯▯▯▯▯▯▯ 27%  1 image · user 1.6k
+▎
+▎ Largest tool results (top 5)
+▎   #1      3k  read
+▎   #2     203  bash
+```
+
+- **Top**: used / window and percentage (the same measure as `/session`: the latest usable usage plus an estimate of the messages after it), tokens left, the source ("reported usage X + estimated Y"; "estimated in full" when there is no usable usage yet, or a compaction / context edit happened after it), the auto-compact trigger (window − `compaction.reserveTokens`; "off" when disabled, "window unknown" without a window) and where tier-one pruning starts.
+- **By category**: system prompt (per section), tool declarations (per tool), user messages, assistant text, reasoning, tool-call arguments (per tool), tool results (summed per tool name), images (1,600 each), summaries (compaction / branch) and custom messages, each with an estimated token count, share and bar. The categories add up to the character-based estimate of the whole projection (one token per CJK character, other characters / 4), so the total in the heading can differ from "Used" at the top, which prefers the usage reported by the model.
+- **System prompt and tool declarations** come from the system messages stored in the session (the first full one and later patches, matching the estimate); before the first request the branch has no system message yet, so both categories are estimated from what the first request will send (the same baseline as the status bar); "Used" matches the status bar and the source reads "system prompt and tools only, estimated before the first request".
+- **Bottom**: only the ordinal (which tool result in the projection), tool name and size of the 5 largest tool results — **never their content**.
+- Read-only: no session entries are written and the request body is untouched, so the prompt-cache prefix is unaffected.
 
 ## Entering Bypass
 
@@ -449,10 +482,33 @@ Requires memory to be enabled (`ama memory enable` or `--memory`, see [memory.md
 
 `ui.quietStartup` / `--quiet-startup`: `normal` shows an "AMA" logo with an info column: version, model and thinking level, directory (`~` abbreviated) and trust state, permission mode / preset / codemode, loaded context files / Skills / prompt templates / hooks, warning count and common keys. At 72 columns or wider the logo sits on the left and the info on the right; at 48–71 columns the logo is on top; below 48 columns a two-line header is shown instead (version · model · thinking / mode · directory · trust). `ui.logo: "off"` or `ui.compact` shows only the info column. The logo takes the theme's accent → user → tool colors letter by letter; ASCII mode swaps in a glyph made of `_ / \ |`. On startup a one-off "light-up" sweep plays for about a second (the glyph starts dim, a highlight band sweeps left to right, then it settles); it redraws in place and leaves no frames in the scrollback, and any key settles it at once while the key still goes to the input box. The settled frame is shown directly with `ui.animation: false`, `NO_COLOR` / a colorless terminal, a non-TTY, an embedding host (profile.host), a `CI` environment, a prompt given on the command line (`ama "…"`), a terminal shorter than 16 rows or content taller than one screen; the line interface, `-p`, RPC and ACP draw no startup header. `header` is a single line `✻ ama version · model · mode · /help` (the profile default); `silent` shows nothing. When `--resume` has no id, the model has no key, the session directory does not exist or project resources need trust, a small selection / input prompt appears before the interface starts, collapsing into one line on screen once answered.
 
+## Terminal program status (OSC 7501)
+
+The interactive interface reports its run state to the terminal with the [OSC 7501 Program Status Protocol](https://www.superlogical.com/rex/docs/build/program-status) (rev 0.3), so a supporting terminal can show "running / waiting for you / done / failed" in tabs, sidebars or notifications. Reports always carry `app=ama`; each report replaces that record as a whole.
+
+| When                                                     | Root record                                                                                                                                        |
+| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Startup, switching sessions (`/new` `/resume` `/fork`)   | `idle`                                                                                                                                             |
+| A turn starts                                            | `working`, msg is the current activity (Thinking / Replying / Running bash / Compacting context; throttled to 500 ms, unchanged values not resent) |
+| An approval needs a person (including sub-agents' ones)  | `blocked` `kind=permission`, msg is "tool · target"                                                                                                |
+| A plan awaits approval                                   | `blocked` `kind=question`                                                                                                                          |
+| A turn failed because the login expired (`auth_expired`) | `blocked` `kind=auth`, msg is the first line of the error; cleared when the next turn starts or the model changes                                  |
+| The approval / plan is handled                           | back to `working` (or whatever the turn ended with)                                                                                                |
+| A turn ends normally                                     | `done`; any key pressed in ama afterwards goes back to `idle`                                                                                      |
+| A turn fails                                             | `error`, msg is the first line of the error                                                                                                        |
+| The user interrupts (Esc etc.)                           | `idle`                                                                                                                                             |
+| Leaving interactive mode                                 | `clear` without an id (removes all of this program's records)                                                                                      |
+
+- Sub-agent tasks get child records `id=task/<short id>` with the task description as title: `working` (msg is the tool in use) → `blocked` while an approval waits → `done` when finished, `error` on failure or the turn limit, `idle` when interrupted; finished task records are cleared when the next main turn starts.
+- Exiting sends `clear`, not `done`: when the user quits, the result is already on screen and a lingering "done" record would only be noise.
+- `ui.programStatus`: `auto` (default) sends `OSC 7501 ; ?` and `CSI c` (DA1) at startup and only reports once the `?` reply arrives; if DA1 answers first or nothing arrives within 300 ms it stays silent. Both replies (late ones too) are swallowed by the input parser and never reach the input box. `on` sends without detecting (the spec allows it: conforming terminals ignore unknown OSCs). `off` neither detects nor sends. Changes take effect after a restart.
+- tmux: it drops unknown OSCs by default, and the spec does not cover multiplexers. tmux does not forward the outer terminal's reply to a passthrough query to the pane, so detection is unreliable and `auto` equals `off` inside tmux; to use it set `on` and `set -g allow-passthrough on` in tmux, and reports are wrapped in DCS passthrough (`ESC P tmux; … ESC \`).
+- Interactive interface only. The stdout of `-p`, RPC and ACP is data or protocol, so nothing is sent there; `-p` sends nothing even when stderr is a terminal: it is a one-shot process whose result is the exit code, the next prompt drops working records anyway, and a leftover done / error is only noise for scripted runs.
+
 ## In tmux / Armadra terminal nodes
 
 - Bracketed paste: enabled at startup; pasted multi-line content enters the input box as a whole (folded into a paste placeholder with the line count beyond 10 lines or 1 000 characters), and an Enter right after a paste sends directly, which suits writes from external programs.
-- Terminal capabilities are not queried, and mouse and the Kitty keyboard protocol are not enabled, so no replies get mixed into input; tmux ≥ 3.4 passes synchronized output through, and older versions display fine too.
+- Apart from program status detection (see the previous section; none inside tmux), terminal capabilities are not queried, and mouse and the Kitty keyboard protocol are not enabled, so no replies get mixed into input; tmux ≥ 3.4 passes synchronized output through, and older versions display fine too.
 - tmux's default prefix `C-b` is taken by the tmux client: to move tasks to the background press `C-b C-b` (`send-prefix` passes it through), or `↓` into the agent bar and press `b`; entering the bar uses `↓`, which the prefix does not affect.
 - When the window size changes the last screen is redrawn in full; history in the scrollback is unaffected.
 - Automatic fallback: non-TTY, `TERM=dumb`, `--no-tui` or a failed terminal initialization use line mode, with the same commands and approval prompts.
@@ -461,16 +517,17 @@ Requires memory to be enabled (`ama memory enable` or `--memory`, see [memory.md
 
 The `ui` section of `config.json` (settable at project level too):
 
-| Key               | Default       | Effect                                                                                                                                            |
-| ----------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ui.theme`        | `dark`        | `dark` / `light` / `auto`; auto only looks at `COLORFGBG` (no terminal query) and uses dark when unsure; configuring it explicitly is recommended |
-| `ui.ascii`        | auto-detected | ASCII glyphs (`›` → `>`, `⏺` → `*`, `⎿` → `L`, box lines → `+ - \|`, a 4-frame spinner)                                                           |
-| `ui.compact`      | `false`       | No blank lines between message blocks, no logo in the startup header                                                                              |
-| `ui.logo`         | `auto`        | The "AMA" logo in the startup header; `off` shows only the info column                                                                            |
-| `ui.animation`    | `true`        | `false`: the spinner stays still as `·` while running and redraws only when seconds change; the startup logo does not animate                     |
-| `ui.markdown`     | `true`        | `false`: assistant text is not rendered as Markdown                                                                                               |
-| `ui.showThinking` | `collapsed`   | See "Layout"                                                                                                                                      |
-| `ui.quietStartup` | `normal`      | See "Startup screen"                                                                                                                              |
+| Key                | Default       | Effect                                                                                                                                            |
+| ------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ui.theme`         | `dark`        | `dark` / `light` / `auto`; auto only looks at `COLORFGBG` (no terminal query) and uses dark when unsure; configuring it explicitly is recommended |
+| `ui.ascii`         | auto-detected | ASCII glyphs (`›` → `>`, `⏺` → `*`, `⎿` → `L`, box lines → `+ - \|`, a 4-frame spinner)                                                           |
+| `ui.compact`       | `false`       | No blank lines between message blocks, no logo in the startup header                                                                              |
+| `ui.logo`          | `auto`        | The "AMA" logo in the startup header; `off` shows only the info column                                                                            |
+| `ui.animation`     | `true`        | `false`: the spinner stays still as `·` while running and redraws only when seconds change; the startup logo does not animate                     |
+| `ui.markdown`      | `true`        | `false`: assistant text is not rendered as Markdown                                                                                               |
+| `ui.showThinking`  | `collapsed`   | See "Layout"                                                                                                                                      |
+| `ui.quietStartup`  | `normal`      | See "Startup screen"                                                                                                                              |
+| `ui.programStatus` | `auto`        | Terminal program status OSC 7501: `auto` / `on` / `off`, see "Terminal program status"                                                            |
 
 - **ASCII mode**: `AMA_ASCII=1` (or `ui.ascii: true`) forces it on, `AMA_ASCII=0` forces it off; auto-detection turns it on when the locale (`LC_ALL` > `LC_CTYPE` > `LANG`) is set but lacks UTF-8, with `TERM=linux`, or on Windows without `WT_SESSION` or `TERM_PROGRAM` (legacy conhost). Windows Terminal uses Unicode.
 - **Misaligned characters**: `⏺` (U+23FA), `⎿` and `▎` render two cells wide in some fonts (emoji fallback fonts in particular), while width is computed per wcwidth (one cell), causing misaligned columns or ghosting; switch to a monospace font or set `AMA_ASCII=1`.