@armadra/agent 0.6.1 → 0.6.3

package/docs/en/providers.md

@@ -170,9 +170,11 @@ ama auth logout chatgpt                # siwc revokes the refresh token first, t
 | Quota              | only known when exceeded (429); set a weekly cap for ama under ChatGPT → Settings → Usage → App limits                                                                                                                  | response headers, `codex.rate_limits` events, `ama auth status` queries `wham/usage`                                                                                            |
 | Logout             | calls `revocation_endpoint`, then deletes locally                                                                                                                                                                       | deletes locally only                                                                                                                                                            |
 
-**Model list**: `chatgpt` has no built-in model table (`chatgpt/<slug>` accepts any slug). After a successful `ama auth login chatgpt`, ama calls the model list endpoint once (siwc `GET /v1/models`, codex `GET /models`; read-only, no usage consumed; failures are silent and the output suggests `ama models discover chatgpt` instead) and caches the slugs and display names available to the account, with the flavor and a timestamp, in `<dataDir>/models/discovered/chatgpt.json`; `ama models discover chatgpt` rewrites the cache and `ama auth logout chatgpt` deletes it. When the registry is assembled the cache is merged into providers whose model table is empty, with metadata filled from the models.dev snapshot, so the `/model` picker and `ama models list` show the models; slugs missing from the cache still work with `--model chatgpt/<slug>`.
+**Model list**: `chatgpt` has no built-in model table (`chatgpt/<slug>` accepts any slug). After a successful `ama auth login chatgpt`, ama deletes the old cache and calls the model list endpoint once (siwc `GET /v1/models`, codex `GET /models?client_version=…`; read-only, no usage consumed; failures are silent and the output suggests `ama models discover chatgpt` instead) and caches the slugs and display names available to the account, with the flavor and a timestamp, in `<dataDir>/models/discovered/chatgpt.json` — an empty list is written as well when no model comes back, so no cache from the other sign-in method is left behind; `ama models discover chatgpt` rewrites the cache and `ama auth logout chatgpt` deletes it. When the registry is assembled the cache is merged into providers whose model table is empty, and the context window, input modalities and reasoning efforts reported by the backend (codex reports them; siwc entries are read the same way when present) are cached and take precedence over the models.dev snapshot — the subscription backend's effective window (such as 272k) can be far smaller than the API window models.dev lists, and the compaction threshold follows the backend window; fields the backend leaves out (such as the output limit) come from models.dev, and when neither has a context window a conservative 128k is used. A cache written by an older version without windows keeps using models.dev until `ama models discover chatgpt` refreshes it. This way the `/model` picker and `ama models list` show the models; a cache whose flavor differs from the current sign-in counts as stale and is not merged (the picker suggests discovering again). Slugs missing from the cache still work with `--model chatgpt/<slug>`.
 
-The default channel of `chatgpt` is chosen at assembly time from the flavor of the auth.json entry; `provider/model@siwc|codex` can name it explicitly but must match the signed-in flavor (otherwise `chatgpt_flavor_mismatch`).
+**codex `client_version`**: the codex backend filters models by `client_version` (each model has a minimum client version; omitting the parameter is a 400), and ama sends a Codex CLI version (default `0.160.0`), not its own version. If codex returns no models at login or discover time, that version is most likely too old: set a newer Codex CLI version with `ama config set auth.chatgpt.codexClientVersion <version>` (user level) or the environment variable `AMA_CHATGPT_CODEX_CLIENT_VERSION` (takes precedence), then run `ama models discover chatgpt`. Inference requests carry no version.
+
+**The channel follows the sign-in method**: the default channel of `chatgpt` is chosen at assembly time from the flavor of the auth.json entry; on top of that every request picks the channel from the flavor of the token it uses — a model reference without `@channel` automatically uses the current sign-in method's channel (endpoint, channel headers such as `originator`, and the request-body allowlist all switch), so after `ama auth logout` and signing in the other way, a running session's next request goes to the new channel without a restart; when a session is resumed, the channel recorded in it does not count as explicit either. Only an explicit `provider/model@siwc|codex` that differs from the sign-in method reports `chatgpt_flavor_mismatch` (suggesting to drop `@channel` or switch the sign-in method).
 
 **Credentials**: a `{ "type": "oauth", … }` entry in auth.json (file mode 0600); `ama auth list` only shows `oauth · <flavor> · <plan>`. The access token is refreshed automatically when less than 5 minutes remain or a request returns 401; several ama processes (several nodes on the canvas) share one auth.json, and refreshes are serialized through `auth.json.lock` (re-read after taking the lock; if another process already refreshed, its token is used), so refresh-token rotation never knocks another process out. When refreshing fails permanently the entry is marked `needsLogin` (tokens are not deleted), requests report `auth_expired`, and you sign in again with `ama auth login chatgpt` as prompted. Raw tokens, codes and id_tokens never reach logs, sessions, events or errors. Logins of other applications (Codex CLI and others) are never read or imported.
 
@@ -184,12 +186,14 @@ The default channel of `chatgpt` is chosen at assembly time from the flavor of t
 | ---------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
 | `quota_exceeded` | siwc 429 `subscription_sharing_usage_limit_exceeded`; codex 429 `usage_limit_reached` / `usage_not_included` | no retry; carries the reset time and emits `quota_update` |
 | `auth_expired`   | a 401 still failing after one refresh, a permanently failed refresh, an entry marked `needsLogin`            | no retry; run `ama auth login chatgpt` again              |
-| `not_eligible`   | siwc 403 `subscription_sharing_user_not_eligible`                                                            | no retry, no re-login                                     |
+| `not_eligible`   | siwc 403 `subscription_sharing_user_not_eligible`                                                            | no retry, no re-login; see troubleshooting below          |
 | (as is)          | 503 and similar                                                                                              | the session layer's existing backoff retries              |
 
+**Troubleshooting `not_eligible`**: the account cannot share its plan usage with ama. Possible causes: the plan (sharing is offered to Plus / Pro only); a workspace account (Team / Enterprise / Edu may not offer it); a region restriction or a preview that has not rolled out yet — **the most likely cause when a Pro account still gets this error**. You can sign in with `ama auth login chatgpt --flavor codex` instead. A successful siwc login only means authorization passed; whether plan usage can be shared is only confirmed on the first request.
+
 **Usage**: subscription requests record `usage.cost = 0` with `billing: "subscription"`; `/session` lists "subscription usage" separately (requests, tokens, cache hit rate, no USD conversion) together with the latest quota; the `quota_update` event is forwarded as is over RPC and has the same name among host events.
 
-**Overrides** (for tests or a future own client): `auth.chatgpt.clientId` / `issuer` / `originator` / `redirectPorts` (user level and profile only), environment variables `AMA_CHATGPT_CLIENT_ID`, `AMA_CHATGPT_ISSUER`, `AMA_CHATGPT_BASE_URL` (changes the address of the current flavor's channel).
+**Overrides** (for tests or a future own client): `auth.chatgpt.clientId` / `issuer` / `originator` / `codexClientVersion` / `redirectPorts` (user level and profile only), environment variables `AMA_CHATGPT_CLIENT_ID`, `AMA_CHATGPT_ISSUER`, `AMA_CHATGPT_BASE_URL` (changes the address of the current flavor's channel), `AMA_CHATGPT_CODEX_CLIENT_VERSION`.
 
 **Embedding hosts**: with a profile ama never starts an interactive login; when `chatgpt` is used and the login has expired the request reports `auth_expired`, and the host guides the user to run `ama auth login chatgpt --paste` in a terminal. Hosts never read, store or forward tokens; they only consume `quota_update` and `auth_expired` / `quota_exceeded`.
 

package/docs/en/rpc.md

@@ -171,7 +171,18 @@ After a session switch the server re-subscribes to events and sends `session_sta
 - Errors: `invalid_arguments` (out-of-range parameters, `before` not a turn id on this branch, `before` together with
   `since`) and `task_not_found`.
 
-43 commands in total; their names are the keys of `RpcCommandMap`.
+### Background sub-agents (wave 7)
+
+| Command           | Parameters | `data`                                                                                                                                                                                                                   |
+| ----------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `background_task` | `taskId?`  | `{ backgrounded: string[] }`: the task ids actually moved. Without `taskId`, every running foreground task; an empty list for finished, already-background or unknown tasks; a non-string `taskId` → `invalid_arguments` |
+
+A moved foreground task is not interrupted: its `task` call returns at once with `tool_execution_end` (the result text starts with
+`[task tN] Moved to the background`, `details.status: "running"`), followed by `subagent_background`; when the task ends you get
+`subagent_end` as usual and, once the parent session is idle, the notification message with `origin: "task"`. Same semantics as
+`Ctrl+B` in the interactive UI.
+
+44 commands in total; their names are the keys of `RpcCommandMap`.
 
 ## Events
 
@@ -216,13 +227,14 @@ There is also the non-session event `{"type":"notification","level":"info"|"warn
 
 Sub-agents started by `task` / `task_ctl` (ama sub-sessions and external agents share the same events, see [agents.md](../agents.md), Chinese):
 
-| Event             | Fields                                                                                                                                                                                                       |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `subagent_start`  | `taskId`, `parentToolCallId`, `agent`, `runner` (`ama` / `claude` / `codex` / `acp:<program>`), `description`, `background`, `model?`, `sessionFile?`, `cwd`; sent again when the same `taskId` is continued |
-| `subagent_update` | `taskId`, `kind: tool \| text \| turn`, `toolName?`, `textDelta?` (merged over ≥ 250 ms), `turn`, `usage?`                                                                                                   |
-| `subagent_end`    | `taskId`, `status: completed \| failed \| aborted \| max_turns \| interrupted`, `usage?`, `cache?`, `outputFile?`, `worktree?: { branch, changed }`                                                          |
+| Event                 | Fields                                                                                                                                                                                                                      |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `subagent_start`      | `taskId`, `parentToolCallId`, `agent`, `runner` (`ama` / `claude` / `codex` / `acp:<program>`), `description`, `background`, `model?`, `sessionFile?`, `cwd`; sent again when the same `taskId` is continued                |
+| `subagent_update`     | `taskId`, `kind: tool \| text \| turn`, `toolName?`, `textDelta?` (merged over ≥ 250 ms), `turn`, `usage?`                                                                                                                  |
+| `subagent_background` | `taskId`, `parentToolCallId`, `reason: user \| timeout \| host` (a foreground task moved to the background: by hand in the interactive UI, when `subagents.autoBackgroundAfterMs` elapses, or by an RPC / SDK call; wave 7) |
+| `subagent_end`        | `taskId`, `status: completed \| failed \| aborted \| max_turns \| interrupted`, `usage?`, `cache?`, `outputFile?`, `worktree?: { branch, changed }`                                                                         |
 
-Approvals of sub-sessions and external agents are sent to this connection as `permission_request` as usual, with an optional `context` marking the origin (since wave 6, approvals of this session's own tool calls also carry `context.toolCallId`, the id of the tool call that triggered the approval, which traces use to compute approval wait time; external agent requests do not carry it): `depth` (1 = from a task sub-agent), `taskId` (the originating task), `origin` (permission requests from external agents: `agent`, `sessionId` (the external CLI's own session id), `toolCall: { title, kind, locations?, inputSummary? }`, `options`). Dialogs use it to show `[task:<agent>]` or `[claude · session abc1]`. For external agent requests `toolName` is `agent:<id>` and the answer applies to this one request only ("allow for this session" is remembered by the external agent itself); the first run of an external agent in a session additionally gets one confirmation with `toolName: "task"`, `input: { agent, mode, note }` (`context.taskId`). `test/fixtures/rpc/external.out.jsonl` is the golden record of the three approvals of `task(agent="acp:ama")` (the task tool, the first run, the child ama's bash), updated by `src/agents/external-rpc.test.ts` with `UPDATE_GOLDEN=1`. After a background task completes, the parent session receives a user message with `origin: "task"` (`<task-notification …>…</task-notification>`) and starts a new turn as usual. Task and type lists are returned by `get_tasks` / `get_agents` (shapes `TaskInfo` / `AgentInfo`; empty without the task tool), with data from the current session's `taskRegistryView(sessionId)` / `sessionAgents(sessionId)` (`src/agent/subagent-registry.ts`). `get_agents` also includes external agents (`installed` / `version` come from PATH and a `--version` probe, cached asynchronously when the session is created and refreshed when external tasks end or host injections change; before the cache is ready there is only the type catalog, see `cachedAgentInfos` in `src/agents/external.ts`). `test/fixtures/rpc/subagent.out.jsonl` is the golden record of a foreground `task(agent="explore")` plus `get_tasks` / `get_agents` (keeping only responses, `tool_execution_*`, `subagent_*` and `agent_settled`), updated by `src/agent/subagent-rpc.test.ts` with `UPDATE_GOLDEN=1`.
+Approvals of sub-sessions and external agents are sent to this connection as `permission_request` as usual, with an optional `context` marking the origin (since wave 6, approvals of this session's own tool calls also carry `context.toolCallId`, the id of the tool call that triggered the approval, which traces use to compute approval wait time; external agent requests do not carry it): `depth` (1 = from a task sub-agent), `taskId` (the originating task), `origin` (permission requests from external agents: `agent`, `sessionId` (the external CLI's own session id), `toolCall: { title, kind, locations?, inputSummary? }`, `options`). Dialogs use it to show `[task:<agent>]` or `[claude · session abc1]`. For external agent requests `toolName` is `agent:<id>` and the answer applies to this one request only ("allow for this session" is remembered by the external agent itself); the first run of an external agent in a session additionally gets one confirmation with `toolName: "task"`, `input: { agent, mode, note }` (`context.taskId`). `test/fixtures/rpc/external.out.jsonl` is the golden record of the three approvals of `task(agent="acp:ama")` (the task tool, the first run, the child ama's bash), updated by `src/agents/external-rpc.test.ts` with `UPDATE_GOLDEN=1`. After a background task completes, the parent session receives a user message with `origin: "task"` (`<task-notification …>…</task-notification>`) and starts a new turn as usual. Task and type lists are returned by `get_tasks` / `get_agents` (shapes `TaskInfo` / `AgentInfo`; empty without the task tool), with data from the current session's `taskRegistryView(sessionId)` / `sessionAgents(sessionId)` (`src/agent/subagent-registry.ts`). `get_agents` also includes external agents (`installed` / `version` come from PATH and a `--version` probe, cached asynchronously when the session is created and refreshed when external tasks end or host injections change; before the cache is ready there is only the type catalog, see `cachedAgentInfos` in `src/agents/external.ts`). `test/fixtures/rpc/subagent.out.jsonl` is the golden record of a foreground `task(agent="explore")` plus `get_tasks` / `get_agents` (keeping only responses, `tool_execution_*`, `subagent_*` and `agent_settled`), updated by `src/agent/subagent-rpc.test.ts` with `UPDATE_GOLDEN=1`. `test/fixtures/rpc/background.out.jsonl` is the golden record of `background_task` moving a running foreground `task` to the background, the task ending and its notification turn, updated by `src/modes/rpc/rpc-background.test.ts`.
 
 ### Throughput telemetry (wave 5)
 

package/docs/en/sessions.md

@@ -51,7 +51,9 @@ Top 5 tool calls
 | Errors / retries | Assistant messages with `stopReason: "error"`; `context_edit{reason:"retry"}` (failed attempts removed by automatic retry)                                                                                                                                                                                                                                                            |
 | Channel          | The `channel` of the latest `model_change` with the same provider / model as the request                                                                                                                                                                                                                                                                                              |
 
-`task` sub-sessions are separate files and count under their own cwd.
+`task` sub-sessions are separate files and count under their own cwd. The notification message a parent session receives when a
+background task finishes (`origin: "task"`) also starts a turn and counts under the parent; when `-p` waits for background tasks,
+those notification turns are written to the same session file.
 
 ### Performance and index
 

package/docs/en/tui.md

@@ -15,16 +15,12 @@ Running `ama` directly in a terminal (stdin / stdout both TTYs, `TERM` not `dumb
 The visual spec (colors, glyphs, screen-by-screen mockups) is in [tui-design.md](../tui-design.md) (Chinese). Hierarchy is expressed by indentation: column 0 holds the user `›`, the tool `⏺` and notice symbols, column 2 the result connector `⎿`, column 4 the tool output; the structure stays readable without colors (`NO_COLOR`, `capture-pane` without `-e`).
 
 ```
-╭──────────────────────────────────────────────────────────────╮
-│ ✻ ama 0.3.0                                                  │   ← startup header (normal)
-│                                                              │
-│ Model   anthropic/claude-sonnet-4-5 · thinking medium        │
-│ Dir     ~/Projects/demo · trusted (trust.json)               │
-│ Mode    Accept edits · preset default                        │
-│ Loaded  AGENTS.md · 2 Skills                                 │
-│                                                              │
-│ /help commands · Shift+Tab mode · Ctrl+O expand tool output  │
-╰──────────────────────────────────────────────────────────────╯
+ ▄███▄  ██▄   ▄██  ▄███▄    ama 0.6.2                     ← startup header (normal)
+██▀ ▀██ ███▄ ▄███ ██▀ ▀██   anthropic/claude-sonnet-4-5@messages · thinking medium
+███████ ██ ▀█▀ ██ ███████   ~/Projects/demo · trusted (trust.json)
+██   ██ ██     ██ ██   ██   Accept edits · preset default
+▀▀   ▀▀ ▀▀     ▀▀ ▀▀   ▀▀   AGENTS.md · 2 Skill
+                            /help commands · Shift+Tab mode · Ctrl+O expand tool output
 
 › read the README                                  ← user message (continuation lines indented 2)
 
@@ -44,23 +40,26 @@ 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)
 ────────────────────────────────────────────────
 tps: 100 tok/s • 546 tok / 5.5s (avg 100 · ttft 1.4s)    ↑12k ↓1.2k · cache 80% ♨ · [-]   ← rate line (full)
-Accept edits     claude-opus-5-5 medium | Ctx 3.0% | proj ⎇ main 5ae9e54 (+12,-3) | $0.26 | 2h24m
+Accept edits     claude-opus-5-5 medium | Ctx 3.0% | 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)
 ```
 
 - **User messages**: start with `›`, continuation lines indented 2 columns; steers while running are marked `↳ steer`, messages queued after this turn `↳ after`, and messages injected by the host (the Armadra canvas) `↳ host` (the `origin` in the session file stays steer / followUp / host).
 - **Thinking blocks**: `ui.showThinking` = `collapsed` (default: "thinking…" → "thinking · 1.2k tokens", `Ctrl+O` expands it to an indented body of at most 60 lines) / `full` (always expanded) / `hidden`.
 - **Tool calls**: titled `⏺ tool name summary`; `⏺` is the accent color while running, green on success, red on failure. The second line after `⎿` is the result summary: lines read, `N changes · +a −b`, `exit 0 · 2.1s · 48 lines`, matches and files, `N inner calls · M lines of script output`, `sub-agent · running 1m05s` / `done · 1m42s · ↑28k ↓4.1k`; while running the summary line carries a spinner in the same frame as the bottom and the seconds. Bodies show the first 3 lines folded; `edit` shows a diff (first 12 lines, with line numbers at ≥ 60 columns); running `bash` scrolls its last 8 lines. `Ctrl+O` expands / folds everything (thinking blocks included). Inner calls of a codemode script hang under the outer call (folded, only the titles and summaries of the latest 5 are listed).
 - **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.
-- **Status bar**: always the last line, with the mode always on the far left. 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).
+- **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.
+- **Status bar**: the mode is always on the far left; 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)**: `tps: <rate> tok/s • <output tokens> tok / <elapsed> (avg <session average> · ttft <time to first token>)`. 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; in ASCII `•` becomes `*`. The right side holds usage items: `↑` input (including cache reads and writes) `↓` output · cache · re-billing · queue count · codemode · tool preset (when not default) · host status, with `[-]` at the end hinting that it folds. Only chat requests count (compaction summaries, warming and the classifier do not). When narrow, these drop in order: output / elapsed, codemode, queue count, tokens, cache, re-billing, preset, host status, avg, ttft; `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> (+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.
-  - **`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; when narrow, these drop in order: 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.
+  - **`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.
+  - **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. A window that is not 5 hours / 7 days is labelled with its actual length. `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.
+  - **`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 model item shows `main model → fallback model` (the fallback in yellow); 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`, `−` → `-`, `♨` → `~`.
+  - 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`, `−` → `-`, `♨` → `~`, `↻` → `@`.
 - **Exit**: a session summary line and the resume command are appended at the end of the message area and stay in the terminal scrollback:
 
 ```
@@ -117,26 +116,27 @@ Trade-offs: the status bar shows the latest hit rate (the session total lives in
 
 ## Keys
 
-| Key                      | Effect                                                                                                                                                                                                                        |
-| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Enter                    | Send; while running = steer (inserted into the current turn)                                                                                                                                                                  |
-| Alt+Enter                | While running, queue after this turn (followUp); when idle, same as Enter                                                                                                                                                     |
-| Shift+Enter / Ctrl+J     | New line                                                                                                                                                                                                                      |
-| Esc                      | Interrupt: queued messages go back into the input box, then the current run stops; closes completion first when it is open                                                                                                    |
-| Esc Esc (idle)           | Empty input: open the rewind list (same as `/rewind`); with text: clear it and save it into input history                                                                                                                     |
-| Alt+↑                    | Recall the last queued message                                                                                                                                                                                                |
-| Shift+Tab / Tab          | Cycle permission modes Manual → Accept edits → Plan → Auto → Bypass permissions (Tab only on an empty input with completion closed, otherwise still completion; entering Bypass asks to confirm, see "Entering Bypass" below) |
-| Ctrl+O                   | Expand / fold tool output and thinking blocks                                                                                                                                                                                 |
-| Ctrl+L / Ctrl+T          | Pick model / thinking level                                                                                                                                                                                                   |
-| Ctrl+G                   | Bottom info line two lines (full) ↔ one line (compact), this session only                                                                                                                                                     |
-| Ctrl+V                   | Paste an image from the clipboard: saved in the data directory, `@<path>` inserted at the cursor (same as `/paste`)                                                                                                           |
-| Ctrl+C                   | Clear the input; on an empty input, press again within 1.5 seconds to quit (exit code 130)                                                                                                                                    |
-| Ctrl+D                   | Quit on an empty input                                                                                                                                                                                                        |
-| Tab                      | Complete                                                                                                                                                                                                                      |
-| ↑ / ↓                    | Browse history on a single line (`<data dir>/history`, 500 entries)                                                                                                                                                           |
-| Ctrl+B / ↓ (empty input) | Enter the agent bar (when there are sub-agent tasks; with text Ctrl+B still moves the cursor left, use ↓ in tmux), see "Sub-agents" (from wave 6 W6-A)                                                                        |
-
-Keys can be overridden in `~/.config/ama/keybindings.json`: keys are action ids (`app.interrupt`, `app.rewind`, `app.message.followUp`, `app.statusLine.toggle`, `app.paste.image`, `app.agents.focus`, `tui.editor.newLine` …), values are a key or an array of keys, and an empty array disables the action. `app.rewind` is the key double-pressed while idle (Esc by default, at most 800 ms apart).
+| Key                  | Effect                                                                                                                                                                                                                        |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Enter                | Send; while running = steer (inserted into the current turn)                                                                                                                                                                  |
+| Alt+Enter            | While running, queue after this turn (followUp); when idle, same as Enter                                                                                                                                                     |
+| Shift+Enter / Ctrl+J | New line                                                                                                                                                                                                                      |
+| Esc                  | Interrupt: queued messages go back into the input box, then the current run stops (with foreground sub-agent tasks; background tasks keep running, as the hint says); closes completion first when it is open                 |
+| Esc Esc (idle)       | Empty input: open the rewind list (same as `/rewind`); with text: clear it and save it into input history                                                                                                                     |
+| Alt+↑                | Recall the last queued message                                                                                                                                                                                                |
+| Shift+Tab / Tab      | Cycle permission modes Manual → Accept edits → Plan → Auto → Bypass permissions (Tab only on an empty input with completion closed, otherwise still completion; entering Bypass asks to confirm, see "Entering Bypass" below) |
+| Ctrl+O               | Expand / fold tool output and thinking blocks                                                                                                                                                                                 |
+| Ctrl+L / Ctrl+T      | Pick model / thinking level                                                                                                                                                                                                   |
+| Ctrl+G               | Bottom info line two lines (full) ↔ one line (compact), this session only                                                                                                                                                     |
+| Ctrl+V               | Paste an image from the clipboard: saved in the data directory, `@<path>` inserted at the cursor (same as `/paste`)                                                                                                           |
+| Ctrl+C               | Clear the input; on an empty input, press again within 1.5 seconds to quit (exit code 130)                                                                                                                                    |
+| Ctrl+D               | Quit on an empty input                                                                                                                                                                                                        |
+| Tab                  | Complete                                                                                                                                                                                                                      |
+| ↑ / ↓                | Browse history on a single line (`<data dir>/history`, 500 entries)                                                                                                                                                           |
+| ↓ (empty input)      | Enter the agent bar (whenever there are sub-agent tasks); with text it still moves down / through history and hints once, see "Sub-agents"                                                                                    |
+| Ctrl+B               | When foreground sub-agent tasks (or a `task_ctl wait`) block the turn, move them all to the background, whatever is in the input box; otherwise cursor left. In tmux press `C-b C-b`, see "Sub-agents"                        |
+
+Keys can be overridden in `~/.config/ama/keybindings.json`: keys are action ids (`app.interrupt`, `app.rewind`, `app.message.followUp`, `app.statusLine.toggle`, `app.paste.image`, `app.agents.focus`, `app.tasks.background`, `tui.editor.newLine` …), values are a key or an array of keys, and an empty array disables the action. `app.rewind` is the key double-pressed while idle (Esc by default, at most 800 ms apart).
 
 ## Rewind
 
@@ -315,12 +315,17 @@ Sub-agents started by the `task` tool ([agents.md](../agents.md), Chinese) fold
 ⏺ task check test coverage gaps in src/tui
   ⎿ ⠋ explore · running 1m05s · 3 turns · read grep bash · ↑12k ↓3.4k
 ⏺ task background review
-  ⎿ done · 0.0s
+  ⎿ started in the background
     ↳ t2 explore · running 40s · 1 turn · read
+⏺ task scan
+  ⎿ moved to the background · 12s
+    ↳ t3 explore · running 30s · 2 turns · grep
 ```
 
-- The status line shows the type (external agents show a runner such as `claude (claude)`), status and elapsed time, turns, the latest 3 tools and usage; after a foreground task ends it is replaced by the result summary. A background task's (`background: true`) tool call returns immediately, with an extra follow-up status line below (refreshed every second while running); when it completes, the `<task-notification>` the model receives shows in the message area as a single line (e.g. "↳ sub-agent notification: t2 explore done · 7 turns · see /tasks for output"), plus a yellow notice on failure or stop.
-- `/tasks`: focus the agent bar (below); `/tasks <id>` opens that task's sub-agent view directly; `/tasks stop <id>` stops it. With `ui.agentBar: "off"` (the default in embedding hosts) `/tasks` is still the task picker (newest on top, Enter shows the output, running tasks can be stopped). Line mode: `/tasks` lists, `/tasks <id>` shows output, `/tasks stop <id>` stops.
+- The status line shows the type (external agents show a runner such as `claude (claude)`), status and elapsed time, turns, the latest 3 tools and usage; after a foreground task ends it is replaced by the result summary. A background task's tool call (background is the default in the interactive UI, see [agents.md](../agents.md) "foreground and background", Chinese) returns immediately; the summary line says "started in the background", with an extra follow-up status line below (refreshed every second while running). A foreground task moved to the background shows "moved to the background · elapsed" with the same follow-up line (the explanation meant for the model is hidden; `Ctrl+O` shows it). A task moved by the auto timeout (`subagents.autoBackgroundAfterMs`) or by the host also gets a one-line notice; when it completes, the `<task-notification>` the model receives shows in the message area as a single line (e.g. "↳ sub-agent notification: t2 explore done · 7 turns · see /tasks for output"), plus a yellow notice on failure or stop.
+- `/tasks`: focus the agent bar (below); `/tasks <id>` opens that task's sub-agent view directly; `/tasks stop <id>` stops it; `/tasks bg [id]` moves it to the background (without an id: every blocking foreground task, same as `Ctrl+B`). With `ui.agentBar: "off"` `/tasks` is still the task picker (newest on top, Enter shows the output, running tasks can be stopped). Line mode: `/tasks` lists, `/tasks <id>` shows output, `/tasks stop <id>` stops, `/tasks bg [id]` moves to the background (typed while running it is still a command, not a steer).
+- Moving to the background (`Ctrl+B`, key action `app.tasks.background`): while the main turn waits for a foreground task (`task` with `background: false`, the `-p` default, or `task_ctl wait`), press it and the tool call returns at once, the task keeps running, the main turn carries on and you can keep sending messages; when the task ends the `<task-notification>` arrives and opens a turn as usual. The hint says "Moved to the background: t2; you'll be notified when it finishes". With nothing to move, `Ctrl+B` falls through to the editor (cursor left) and is not swallowed. tmux's default prefix is `C-b`: in tmux press `C-b C-b` (default `send-prefix`) to pass it to ama, or press `b` in the agent bar; you can also rebind it in `keybindings.json`.
+- Esc interrupts only the foreground: Esc while running stops the main turn and the sub-tasks still in the foreground; tasks already in the background keep running, and the hint says "Interrupted (background task t2 keeps running; Esc doesn't affect it)".
 - `/agents`: the available types: name, runner, source (built-in / user / project / profile / host), external agents marked installed with a version or not installed, plus a one-line description.
 - Notices reported by external agents themselves (budget exhausted, timeout, mode downgrade …) show in the message area as a single line `[claude · t3] …`.
 
@@ -335,11 +340,13 @@ Above the status line (below the hint line) the bar lists sub-agent tasks, one l
 1 more
 ```
 
-- States: queued (the concurrency pool is full) / running (elapsed time, turns, latest tool) / awaiting approval (the approval dialog currently holds its request) / done / failed / stopped (plus out of turns and interrupted); `⏺` is the accent color while running, green when done, red on failure, yellow / dim otherwise; `*` in ASCII.
+- States: queued (the concurrency pool is full) / running (elapsed time, turns, latest tool) / awaiting approval (the approval dialog currently holds its request, or it is docked in the bar; the row is yellow) / done / failed / stopped (plus out of turns and interrupted); `⏺` is the accent color while running, green when done, red on failure, yellow / dim otherwise; `*` in ASCII.
 - When it shows: while any task is queued, running or awaiting approval; tasks that ended in this session and have not been looked at in the view stay until viewed, at most 10 minutes. Tasks already finished when a session is resumed are not shown (`/tasks` lists them).
-- Entering: `Ctrl+B` with an empty input box (whenever there are tasks), or `↓` (while the bar is visible) — tmux's default prefix swallows `Ctrl+B`, so use `↓` there; with text in the input box `Ctrl+B` still moves the cursor left and `↓` still moves down / through history. The key action is `app.agents.focus`, configurable in `keybindings.json`.
-- In the bar: `↑` `↓` select (lists every task of the session, the window scrolls along; `↑` on the first item returns to the input box), Enter opens the sub-agent view, Esc / `Ctrl+B` return to the input box; typing returns to the input box with the text filled in. The last line is a key hint.
-- Embedding hosts (with a profile) default to `ui.agentBar: "off"`: no bar, and `Ctrl+B` / `↓` go to the editor as usual.
+- Entering: press `↓` with an empty input box and no completion open, whenever the session has tasks (even after the bar has collapsed, same as `/tasks`); the same inside and outside tmux. It works while a turn runs too; the `↓ Agent bar` at the end of the running line is the reminder. The key action is `app.agents.focus` (only `down` by default), configurable in `keybindings.json`.
+- When the key does not get you in, a one-line hint shows for 3 seconds: text in the input box — "Input is not empty; clear it and press ↓ for the Agent bar" (once per draft, with the cursor on the last line; `↓` still moves down); the bar is off — "Agent bar is off (ui.agentBar); use /tasks"; no tasks — "No sub-agent tasks yet". While browsing input history with `↑` `↓`, `↓` only steps through history.
+- `Ctrl+B` does not enter the bar; it moves foreground tasks to the background (above). For the old "`Ctrl+B` enters the bar", set `"app.agents.focus": ["down", "ctrl+b"]` in `keybindings.json` and rebind `app.tasks.background`.
+- In the bar: `↑` `↓` select (lists every task of the session, the window scrolls along; `↑` on the first item returns to the input box), Enter opens the sub-agent view (a docked approval of the selected task pops up right away), `b` / `Ctrl+B` moves the selected foreground task to the background (a one-line hint when it is not running in the foreground), `x` stops the selected task (the first press hints "Press x again to stop t2"; it stops only on a second press within 1.5 seconds), Esc returns to the input box; other letters return to the input box with the text filled in. The last line is the key hint `↑↓ select · Enter open · b background · x stop · Esc back`; narrow screens drop the `b` / `x` items.
+- Embedding hosts (with a profile) no longer turn the bar off by default; a host that shows sub-tasks itself and does not want the bar sets `ui.agentBar: "off"` in its profile (see [host-api.md](host-api.md) "Embedding in Armadra"). With the bar off it is not shown, and `↓` with tasks points to `/tasks`.
 
 ### Sub-agent view
 
@@ -360,8 +367,17 @@ t2 explore · running 1m05s · 3 turns · ↑12k ↓3.4k · Esc back · /tasks s
 - The body follows live: for ama sub-agents it shows every message and tool call of the sub-session (rendered like the message area); when the sub-session handle has been released (at most 16 are kept) or the session was resumed, the sub-session file is loaded read-only and live events are attached when the task runs again. External agents (claude / codex / ACP) show the live output held in this process's memory (text, thinking, tool start / end, turns, notices; at most 2000 items / 1 MB, never written to disk); after ama restarts only one line remains, saying to use the original CLI's resume <session id> for the full text.
 - With an empty input box: `↑` / PgUp scroll up (pausing follow, with "follow paused · End to resume" at the bottom), `↓` / PgDn scroll down, End (or `f` while paused) resumes following; `←` `→` switch to the previous / next task; Esc returns to the main screen. With text in the input box, Esc clears it first.
 - Enter sends the input to this sub-agent (recorded in the sub-session as a user message with `origin: "direct"`, see [session-format.md](../session-format.md), Chinese): ama sub-agent running → delivered when its current turn ends; external agent running or task still queued → continued after this run ends; finished → continued in the background (like `task_ctl send`; the main session receives the `<task-notification>` as usual when it completes). A line at the bottom reports the result. The parent session's model does not know you talked to the sub-agent directly; the result comes back through the completion notification.
-- Nothing is interrupted from the view: Esc only goes back. To stop the task use `/tasks stop <id>`, which also works in the view's input box (the only command the view accepts).
-- When the viewed task waits for approval the title says "awaiting approval", and the approval dialog pops up over the view as usual (with the `[task:<type>]` origin).
+- Nothing is interrupted from the view: Esc only goes back. To stop the task use `/tasks stop <id>`; to move it to the background use `Ctrl+B` or `/tasks bg [id]`. Both work in the view's input box (the only commands the view accepts).
+- When the viewed task waits for approval the title says "awaiting approval", and the approval dialog pops up over the view as usual (with the `[task:<type>]` origin); if its approval is docked in the bar, opening the view pops it up.
+
+### Docked approvals of background tasks
+
+When a background task (including one moved to the background) needs approval, it does not interrupt what you are doing:
+
+- While the main session is running, the input box has a draft, or another overlay is open, no dialog pops up; the request is **docked**: the task's row in the agent bar says "needs approval" (yellow) and the running line shows `↓ handle approval`; the sub-task waits meanwhile.
+- It pops up on its own once the main session is idle, the input box is empty and no overlay is open; entering the bar, selecting it and pressing Enter (opening the view) pops it up immediately.
+- If the main session or a foreground task asks for approval while one is docked: approvals are serialized, so the docked one pops up first and theirs follow; the main session's approvals are never held back.
+- Approvals of foreground tasks and of the main session pop up immediately as before; timeouts (deny after 10 minutes by default), aborts and unattended rules are unchanged. RPC clients receive `permission_request` as usual and decide how to present it.
 
 Origin labels on approval boxes:
 
@@ -413,12 +429,13 @@ Requires memory to be enabled (`ama memory enable` or `--memory`, see [memory.md
 
 ## Startup screen
 
-`ui.quietStartup` / `--quiet-startup`: `normal` shows a boxed startup header: title, 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; below 56 columns or with `ui.compact` the box is dropped and each item takes one line. `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.
+`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.
 
 ## 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.
+- 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.
 
@@ -430,8 +447,9 @@ The `ui` section of `config.json` (settable at project level too):
 | ----------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `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 box around the startup header                                                                           |
-| `ui.animation`    | `true`        | `false`: the spinner stays still as `·` while running and redraws only when seconds change                                                        |
+| `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"                                                                                                                              |
@@ -505,29 +523,29 @@ tui.setFocus(editor);
 tui.start();
 ```
 
-| Export                                                                    | Purpose                                                                                                                                                                                  |
-| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Component`, `Focusable`, `CURSOR_MARKER`                                 | The component contract: `render(width)` returns lines (each with visible width ≤ width), `handleInput?(data)`, `invalidate()`; the focused component emits `CURSOR_MARKER` at the cursor |
-| `TUI`                                                                     | Root container and differential rendering (main screen, synchronized output): `addChild`, `start` / `stop`, `requestRender`, `setFocus`, `addInputListener`, `showOverlay`               |
-| `ProcessTerminal`, `MemoryTerminal`, `VirtualScreen`                      | A real terminal (raw mode, bracketed paste); an in-memory terminal and a VT screen (tests, frame goldens)                                                                                |
-| `Container`, `Text`, `TruncatedText`, `Markdown`, `Box`, `Card`, `Spacer` | Basic components; `Card` is a left-bar card, `Box` accepts `borderColor`                                                                                                                 |
-| `Loader`                                                                  | Running indicator: `setVerb(verb, extras, { elapsed })`, `frame` / `onFrame` (changes glyph in the same frame as other components), `animation: false`                                   |
-| `Editor`, `EditorBuffer`, `PasteStore`                                    | Multi-line editor (history, the `AutocompleteProvider` completion interface, paste folding)                                                                                              |
-| `SelectList`                                                              | Filterable selection list: groups, badges, number keys, `stacked`, `currentValue` (✓), `footer` key hints                                                                                |
-| `KeyValue`, `Meter`                                                       | Two-column aligned key-value table (`wrap` wraps aligned to the value column); a meter (`levelColor` threshold coloring)                                                                 |
-| `compositeOverlays`, `OverlayOptions`                                     | Overlay compositing (centered / bottom-anchored)                                                                                                                                         |
-| `createTheme`, `plainTheme`, `detectCapabilities`, `Theme`                | Themes and color capability detection (`NO_COLOR`, 16 / 256 / truecolor); 14 semantic colors, `resolveThemeName("auto")`                                                                 |
-| `Theme.glyphs`, `UNICODE_GLYPHS`, `ASCII_GLYPHS`, `detectAscii`           | Glyph tables (`›` `⏺` `⎿` `✻` `▎`, box lines, spinner frames …) with ASCII fallback; `createTheme(name, { ascii })`                                                                      |
-| `Keybindings`, `DEFAULT_KEYBINDINGS`, `loadKeybindingsFile`               | Action id → keys, overridden by `keybindings.json`                                                                                                                                       |
-| `parseKey`, `matchesKey`, `StdinBuffer`                                   | Key sequence parsing and Esc timeout splitting (`AMA_TUI_ESC_TIMEOUT`)                                                                                                                   |
-| `visibleWidth`, `truncateToWidth`, `wrapTextWithAnsi`, `sliceByColumn` …  | Width computation and truncation aware of ANSI and wide characters                                                                                                                       |
+| Export                                                                    | Purpose                                                                                                                                                                                                                           |
+| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Component`, `Focusable`, `CURSOR_MARKER`                                 | The component contract: `render(width)` returns lines (each with visible width ≤ width), `handleInput?(data)`, `invalidate()`; the focused component emits `CURSOR_MARKER` at the cursor                                          |
+| `TUI`                                                                     | Root container and differential rendering (main screen, synchronized output): `addChild`, `start` / `stop`, `requestRender`, `setFocus`, `addInputListener`, `showOverlay`                                                        |
+| `ProcessTerminal`, `MemoryTerminal`, `VirtualScreen`                      | A real terminal (raw mode, bracketed paste); an in-memory terminal and a VT screen (tests, frame goldens)                                                                                                                         |
+| `Container`, `Text`, `TruncatedText`, `Markdown`, `Box`, `Card`, `Spacer` | Basic components; `Card` is a left-bar card, `Box` accepts `borderColor`                                                                                                                                                          |
+| `Loader`                                                                  | Running indicator: `setVerb(verb, extras, { elapsed, optional })` (`optional` extras are dropped whole when the line does not fit), `frame` / `onFrame` (changes glyph in the same frame as other components), `animation: false` |
+| `Editor`, `EditorBuffer`, `PasteStore`                                    | Multi-line editor (history, the `AutocompleteProvider` completion interface, paste folding)                                                                                                                                       |
+| `SelectList`                                                              | Filterable selection list: groups, badges, number keys, `stacked`, `currentValue` (✓), `footer` key hints                                                                                                                         |
+| `KeyValue`, `Meter`                                                       | Two-column aligned key-value table (`wrap` wraps aligned to the value column); a meter (`levelColor` threshold coloring)                                                                                                          |
+| `compositeOverlays`, `OverlayOptions`                                     | Overlay compositing (centered / bottom-anchored)                                                                                                                                                                                  |
+| `createTheme`, `plainTheme`, `detectCapabilities`, `Theme`                | Themes and color capability detection (`NO_COLOR`, 16 / 256 / truecolor); 14 semantic colors, `resolveThemeName("auto")`                                                                                                          |
+| `Theme.glyphs`, `UNICODE_GLYPHS`, `ASCII_GLYPHS`, `detectAscii`           | Glyph tables (`›` `⏺` `⎿` `✻` `▎`, box lines, spinner frames …) with ASCII fallback; `createTheme(name, { ascii })`                                                                                                               |
+| `Keybindings`, `DEFAULT_KEYBINDINGS`, `loadKeybindingsFile`               | Action id → keys, overridden by `keybindings.json`                                                                                                                                                                                |
+| `parseKey`, `matchesKey`, `StdinBuffer`                                   | Key sequence parsing and Esc timeout splitting (`AMA_TUI_ESC_TIMEOUT`)                                                                                                                                                            |
+| `visibleWidth`, `truncateToWidth`, `wrapTextWithAnsi`, `sliceByColumn` …  | Width computation and truncation aware of ANSI and wide characters                                                                                                                                                                |
 
 ## Testing
 
 Frame goldens all live in `test/fixtures/tui/`; `MemoryTerminal` reconstructs the screen (without color, verifying only layout and glyphs):
 
 - `src/modes/interactive/interactive-mode.test.ts`: a complete read-file run at 80x24 and 40x24 (startup, input, tool running, finish, `Ctrl+O` expand, exit summary) → `run-*.txt`; approvals, cache notices and more.
-- `src/modes/interactive/interactive-frames.test.ts`: startup headers (`startup-normal-*`, `header-quiet-*`), tool hierarchy (`tools-*`), notices (`notices-*`), running verbs (`loader-verbs-*`), the `/session` panel (`panel-session-*`), a whole run in ASCII mode (`ascii-run-*`).
+- `src/modes/interactive/interactive-frames.test.ts`: startup headers (`startup-normal-*`, `header-quiet-*`; logo variants and the animation in `startup-logo.test.ts` / `startup-logo-*`), tool hierarchy (`tools-*`), notices (`notices-*`), running verbs (`loader-verbs-*`), the `/session` panel (`panel-session-*`), a whole run in ASCII mode (`ascii-run-*`).
 - Wave 5 (W5-U): `plan-dialog.test.ts` (`plan-dialog-*`: four options, execution mode, feedback, external editor, ASCII, 40 columns), `approval-origin.test.ts` (`approval-origin-*`, `approval-task-agent-*`, `approval-first-run-*`, `approval-task-external-*` and the first-run merge), `subagent-view.test.ts` (`subagent-view-*`), `tasks-panel.test.ts` (`tasks-picker-*`, `tasks-output-*`, `agents-panel-*`), `harness-notices.test.ts` (`harness-notices-*`), `interactive-w5.test.ts` (plan → approval → execution, `/plan`, background tasks into `/tasks`, Ctrl+V; `interactive-plan-*`, `interactive-tasks-*`).
 - `src/tui/tui-frames.test.ts`: component level (conversation, Markdown, editor placeholder / multi-line / paste / completion); `status-widths.txt` of `status-bar.test.ts`; approvals and mode pickers in `approval-dialog.test.ts` and `pickers.test.ts`.
 

package/docs/host-api.md

@@ -159,4 +159,8 @@ interface WarmDecision {
 
 ## 嵌入 Armadra
 
-Armadra 用 profile 启动 ama：`ama --profile <path>`，profile 的 `host` 指向它的适配器（`ama-armadra.cjs`），另带 instructions、skillDirs、hooksFile、authFile、sessionDir、`trustProject`。适配器在 `ARMADRA_NODE_ID` 缺失时返回 `undefined`，同一个 profile 在画布外退化为普通 ama。契约细节见 Armadra 仓库 [docs/design/coordinator-agent.md](https://github.com/yovinchen/Armadra/blob/main/docs/design/coordinator-agent.md)。
+Armadra 用 profile 启动 ama：`ama --profile <path>`，profile 的 `host` 指向它的适配器（`ama-armadra.cjs`），另带 instructions、skillDirs、hooksFile、authFile、sessionDir、`trustProject`。适配器在 `ARMADRA_NODE_ID` 缺失时返回 `undefined`，同一个 profile 在画布外退化为普通 ama。
+
+有 profile 时的界面缺省：`ui.quietStartup: "header"`、`ui.statusLine: "compact"`（最后一行是状态栏，宿主按 `·` 解析）。Agent 栏（`ui.agentBar`）不再缺省关闭，与独立终端一样是 `auto`；宿主自己展示子任务、不要栏时在 profile 的 `config` 指向的配置文件里写 `{ "ui": { "agentBar": "off" } }`。
+
+契约细节见 Armadra 仓库 [docs/design/coordinator-agent.md](https://github.com/yovinchen/Armadra/blob/main/docs/design/coordinator-agent.md)。

package/docs/providers.md

@@ -185,14 +185,27 @@ ama auth logout chatgpt                # siwc 先撤销 refresh token 再删本
 | 配额     | 只在超限（429）时可知；在 ChatGPT → 设置 → Usage → App limits 给 ama 设周上限                                                                       | 响应头、`codex.rate_limits` 事件、`ama auth status` 查 `wham/usage`                                                                                   |
 | 登出     | 调 `revocation_endpoint` 撤销，再删本地                                                                                                             | 只删本地                                                                                                                                              |
 
-**模型列表**：`chatgpt` 没有内置模型表（`chatgpt/<slug>` 任意接受）。`ama auth login chatgpt` 成功后自动调一次模型
-列表接口（siwc `GET /v1/models`、codex `GET /models`，只读、不消耗额度；失败静默，改提示 `ama models discover chatgpt`），
-把账户可用的 slug 与显示名连同 flavor、时间戳缓存到 `<dataDir>/models/discovered/chatgpt.json`；`ama models discover
-chatgpt` 也重写这份缓存，`ama auth logout chatgpt` 删掉它。组装注册表时缓存并入模型表为空的供应商，元数据用 models.dev
-快照补全，`/model` 选择器、`ama models list` 照常列出；缓存里没有的 slug 仍可 `--model chatgpt/<slug>` 使用。
-
-`chatgpt` 的缺省渠道在组装时按 auth.json 条目的 flavor 决定；`provider/model@siwc|codex` 可显式指定，但必须与登录的
-flavor 一致（否则报 `chatgpt_flavor_mismatch`）。
+**模型列表**：`chatgpt` 没有内置模型表（`chatgpt/<slug>` 任意接受）。`ama auth login chatgpt` 成功后先删旧缓存，再调一次
+模型列表接口（siwc `GET /v1/models`、codex `GET /models?client_version=…`，只读、不消耗额度；失败静默，改提示
+`ama models discover chatgpt`），把账户可用的 slug 与显示名连同 flavor、时间戳缓存到
+`<dataDir>/models/discovered/chatgpt.json`——返回 0 个也写空表，免得残留另一种登录方式的缓存；`ama models discover
+chatgpt` 也重写这份缓存，`ama auth logout chatgpt` 删掉它。组装注册表时缓存并入模型表为空的供应商，后端给的上下文窗口、
+输入模态、推理强度（codex 后端给；siwc 条目带了也取）存进缓存并优先于 models.dev 快照——订阅后端的生效窗口（如 272k）
+可能远小于 models.dev 记的 API 版窗口，压缩阈值按后端窗口算；后端没给的字段（输出上限等）用 models.dev 补，两边都没有
+上下文窗口时按保守缺省 128k。旧版本写的缓存不含窗口就照旧用 models.dev，重新 `ama models discover chatgpt` 即刷新。`/model` 选择器、
+`ama models list` 照常列出；缓存的 flavor 与当前登录不符时视为过期、不并入（选择器提示重新发现）。缓存里没有的 slug
+仍可 `--model chatgpt/<slug>` 使用。
+
+**codex 的 `client_version`**：codex 后端按 `client_version` 过滤模型（每个模型有最低客户端版本，不带参数报 400），
+ama 发的是 Codex CLI 的版本号（缺省 `0.160.0`），而不是 ama 自己的版本。登录或 discover 时 codex 返回 0 个模型，多半是
+这个版本过旧：用 `ama config set auth.chatgpt.codexClientVersion <版本>`（用户级）或环境变量
+`AMA_CHATGPT_CODEX_CLIENT_VERSION`（优先）设成较新的 Codex CLI 版本，再 `ama models discover chatgpt`。推理请求不带版本号。
+
+**渠道跟随登录方式**：`chatgpt` 的缺省渠道在组装时按 auth.json 条目的 flavor 决定；此外每次请求按当次 token 所属的
+flavor 选渠道——模型引用没写 `@渠道` 时自动用当前登录方式的渠道（端点、`originator` 等渠道头、请求体白名单一起换），
+所以运行中的会话在 `ama auth logout` 后换另一种方式登录，下一次请求就走新渠道，不用重启；恢复会话时，会话里记录的渠道
+也不算显式。只有显式写了 `provider/model@siwc|codex` 且与登录方式不符时才报 `chatgpt_flavor_mismatch`（提示去掉
+`@渠道` 或换登录方式）。
 
 **凭据**：auth.json 的 `{ "type": "oauth", … }` 条目（文件 0600），`ama auth list` 只显示 `oauth · <flavor> · <计划>`。
 access token 剩余不到 5 分钟或请求返回 401 时自动刷新；多个 ama 进程（画布上的多个节点）共享一个 auth.json，刷新经
@@ -214,15 +227,19 @@ developer 消息（前缀依然稳定）。compat `toolsInNamespace: true` 时
 | ---------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------- |
 | `quota_exceeded` | siwc 429 `subscription_sharing_usage_limit_exceeded`；codex 429 `usage_limit_reached` / `usage_not_included` | 不重试；附重置时间并发 `quota_update` |
 | `auth_expired`   | 401 刷新一次仍失败、刷新永久失败、条目 `needsLogin`                                                          | 不重试；重新 `ama auth login chatgpt` |
-| `not_eligible`   | siwc 403 `subscription_sharing_user_not_eligible`                                                            | 不重试、不重登                        |
+| `not_eligible`   | siwc 403 `subscription_sharing_user_not_eligible`                                                            | 不重试、不重登；排查见下              |
 | （原样）         | 503 等                                                                                                       | 走会话层现有的退避重试                |
 
+**`not_eligible` 排查**：账户不能把套餐额度共享给 ama。可能的原因：账户套餐（额度共享只对 Plus / Pro 开放）；工作空间
+账户（Team / Enterprise / Edu 可能未开放）；地区受限或预览期尚未开放——**Pro 账户仍报此错时最可能是这一条**。可以改用
+`ama auth login chatgpt --flavor codex`。siwc 登录成功只说明授权通过，能否共享额度要到首次请求才能确认。
+
 **用量**：订阅请求 `usage.cost = 0` 并标 `billing: "subscription"`；`/session` 单列「订阅用量」（请求数、token、
 缓存命中率，不折算美元）与最近一次配额；事件 `quota_update`（RPC 原样转发，宿主事件同名）。
 
-**覆盖**（测试或将来换自有客户端用）：`auth.chatgpt.clientId` / `issuer` / `originator` / `redirectPorts`（只认用户级
-与 profile），环境变量 `AMA_CHATGPT_CLIENT_ID`、`AMA_CHATGPT_ISSUER`、`AMA_CHATGPT_BASE_URL`（改当前 flavor 渠道的
-地址）。
+**覆盖**（测试或将来换自有客户端用）：`auth.chatgpt.clientId` / `issuer` / `originator` / `codexClientVersion` /
+`redirectPorts`（只认用户级与 profile），环境变量 `AMA_CHATGPT_CLIENT_ID`、`AMA_CHATGPT_ISSUER`、`AMA_CHATGPT_BASE_URL`
+（改当前 flavor 渠道的地址）、`AMA_CHATGPT_CODEX_CLIENT_VERSION`。
 
 **嵌入宿主**：有 profile 时 ama 不发起交互式登录；用到 `chatgpt` 而登录失效时请求报 `auth_expired`，由宿主引导用户
 在终端执行 `ama auth login chatgpt --paste`。宿主不读、不存、不转发 token，只消费 `quota_update` 与

package/docs/rpc.md

@@ -159,7 +159,17 @@
 - 整个 `data` 都经过脱敏；节点里只有 id、时间、计数与用量，正文只在 `previews` 里。运行中没有结果的工具标 `running`。
 - 错误：`invalid_arguments`（参数越界、`before` 不是本分支的回合 id、`before` 与 `since` 同用）、`task_not_found`。
 
-合计 43 条命令，名字即 `RpcCommandMap` 的键。
+### 后台子 Agent（第七波）
+
+| 命令              | 参数      | `data`                                                                                                                                                                     |
+| ----------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `background_task` | `taskId?` | `{ backgrounded: string[] }`：实际转了后台的 `taskId`。不给 `taskId` = 全部前台运行中任务；已结束、已在后台或不存在的任务回空表；`taskId` 不是字符串 → `invalid_arguments` |
+
+被转的前台任务不中断，其 `task` 调用立即以 `tool_execution_end` 返回（结果文本以 `[task tN] Moved to the background` 开头，
+`details.status: "running"`），随后发 `subagent_background`；任务结束时照常 `subagent_end`，父会话空闲后收到 `origin: "task"`
+的通知消息。语义与交互界面的 `Ctrl+B` 相同，见 [agents.md](agents.md)「前台与后台」。
+
+合计 44 条命令，名字即 `RpcCommandMap` 的键。
 
 ## 事件
 
@@ -204,11 +214,12 @@
 
 `task` / `task_ctl` 起的子 Agent（ama 子会话与外部 Agent 同一组事件，见 [agents.md](agents.md)「子 Agent」）：
 
-| 事件              | 字段                                                                                                                                                                                     |
-| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `subagent_start`  | `taskId`、`parentToolCallId`、`agent`、`runner`（`ama` / `claude` / `codex` / `acp:<程序>`）、`description`、`background`、`model?`、`sessionFile?`、`cwd`；同一 `taskId` 续聊时再发一次 |
-| `subagent_update` | `taskId`、`kind: tool \| text \| turn`、`toolName?`、`textDelta?`（≥ 250 ms 合并）、`turn`、`usage?`                                                                                     |
-| `subagent_end`    | `taskId`、`status: completed \| failed \| aborted \| max_turns \| interrupted`、`usage?`、`cache?`、`outputFile?`、`worktree?: { branch, changed }`                                      |
+| 事件                  | 字段                                                                                                                                                                                     |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `subagent_start`      | `taskId`、`parentToolCallId`、`agent`、`runner`（`ama` / `claude` / `codex` / `acp:<程序>`）、`description`、`background`、`model?`、`sessionFile?`、`cwd`；同一 `taskId` 续聊时再发一次 |
+| `subagent_update`     | `taskId`、`kind: tool \| text \| turn`、`toolName?`、`textDelta?`（≥ 250 ms 合并）、`turn`、`usage?`                                                                                     |
+| `subagent_background` | `taskId`、`parentToolCallId`、`reason: user \| timeout \| host`（前台任务转后台：交互界面手动、`subagents.autoBackgroundAfterMs` 到时、RPC / SDK 调用；第七波）                          |
+| `subagent_end`        | `taskId`、`status: completed \| failed \| aborted \| max_turns \| interrupted`、`usage?`、`cache?`、`outputFile?`、`worktree?: { branch, changed }`                                      |
 
 子会话与外部 Agent 的审批照常以 `permission_request` 发给本连接，`context`（可选）标出来源（第六波起本会话工具调用的审批也带
 `context.toolCallId`——触发审批的工具调用 id，轨迹据此算审批等待；外部 Agent 的请求不带）：
@@ -225,7 +236,8 @@
 只有类型目录，见 `cachedAgentInfos`，`src/agents/external.ts`）。
 `test/fixtures/rpc/subagent.out.jsonl` 是一次前台 `task(agent="explore")` 加 `get_tasks` / `get_agents` 的黄金记录（只保留
 响应、`tool_execution_*`、`subagent_*` 与 `agent_settled`），由
-`src/agent/subagent-rpc.test.ts` 用 `UPDATE_GOLDEN=1` 更新。
+`src/agent/subagent-rpc.test.ts` 用 `UPDATE_GOLDEN=1` 更新。`test/fixtures/rpc/background.out.jsonl` 是前台 `task` 运行中
+`background_task` 转后台、随后任务结束并投递通知回合的黄金记录，由 `src/modes/rpc/rpc-background.test.ts` 更新。
 
 ### 速率遥测（第五波）
 

package/docs/sessions.md

@@ -46,7 +46,8 @@ packy/deepseek-v4-flash         1     3     1  4.6k   980      2k       0   30.8
 | 错误 / 重试 | `stopReason: "error"` 的 assistant；`context_edit{reason:"retry"}`（自动重试剔除的失败尝试）                                                                                                                          |
 | 渠道        | 最近一条 `model_change` 与请求同 provider / model 时取它的 `channel`                                                                                                                                                  |
 
-`task` 子会话是独立文件，按它自己的 cwd 计入。
+`task` 子会话是独立文件，按它自己的 cwd 计入。后台任务完成后父会话里的通知消息（`origin: "task"`）同样开启一个回合，
+按父会话计入；`-p` 等后台任务时（见 [agents.md](agents.md)「前台与后台」）这些通知回合也写进同一个会话文件。
 
 ### 性能与索引