@visual-z/xeno 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # xeno changelog
 
+## 0.4.0 — 2026-10-09
+
+- Add the goal, evidence progress and Context Lens workbench through `/control`. Keep execution outcomes separate from verified acceptance and explain the sources retained in the actual model context.
+- Share one live Session between the TUI and the experimental `xeno-control/0.1` JSONL app server or private Unix socket. Expose initialization, thread/turn/item identity, snapshots, steering, cancellation and approval; include the interface guide in the package.
+- Report terminal state through OSC 7501 with capability detection, explicit opt-outs, private program identity and generic messages that exclude prompts and model output.
+- Preserve cancellation when a provider returns late. Deliver TUI steering and follow-ups into remotely started turns at their original boundaries, and return undelivered drafts after interruption.
+- Carry original request identity, command and artifact evidence, acceptance gaps and diagnostic progress across context cuts without requiring extra model bookkeeping.
+- Honor selected provider arguments, add official Grok OAuth, and preserve raw tool-call identity, response validation and measured usage/cache accounting across native provider workflows.
+
+## 0.3.0 — 2026-10-07
+
+- Replace the vendored Pi terminal UI with OpenTUI: a growing composer, command palette, model and login pickers, responsive status surfaces, terminal colours and bounded message rendering.
+- Keep inline image tags atomic through cursor movement, deletion, undo/redo, history and queued drafts; send only retained attachments and preview the image beside the cursor. Share bounded image decoding across drafts, messages and tool results.
+- Add plain-text mouse selection copying and optional daily version notices, with offline and non-interactive opt-outs.
+- Preserve tool admission and nested-call receipts, cancellable process ownership, deferred discovery, recoverable output and integration health handling. Code Mode is removed.
+- Strengthen file edit preconditions, workspace lifecycle and completion evidence; opening the editor no longer requires an eager workspace snapshot.
+- Require Bun 1.3.0 or newer for the native renderer. Existing session logs remain append-only.
+
 ## 0.2.1 — 2026-09-30
 
 - Handle Ctrl+C and termination signals while startup awaits resources or workspace snapshots, restoring the terminal before exit.

package/README.md

@@ -17,7 +17,7 @@ is ever summarized by a model, and nothing is ever rewritten in place.
 messages[]                             frozen system prefix + handoff + this node's events
 ```
 
-Version **0.2.1**. The on-disk session format will still change; `0.x` is that
+Version **0.4.0**. The on-disk session format will still change; `0.x` is that
 statement. Published as `@visual-z/xeno`; the license is `UNLICENSED` (readable and installable, no reuse granted).
 
 ## Install
@@ -47,11 +47,13 @@ Validation commands and current evidence are recorded in
 ## Harness capabilities
 
 - One live execution per session, with cancellation, draining, and explicit completion/stop/failure outcomes.
+- Evidence-backed goals, progress and Context Lens in `/control`, shared with the experimental JSONL app server and optional local control socket. See [`docs/app-server.md`](docs/app-server.md) for identity, events, approval, recovery and OSC 7501 status.
 - Stable work IDs with explicit unblock, reopen, and cancel operations. Verified completion still requires fresh executed evidence.
 - Shared schema validation and structured tool feedback. Reads return file versions; edits support an expected version and return a diff.
 - Writing branches start from the parent's working copy, including uncommitted files, in an isolated Git worktree. Adopt continues that checkout.
 - Independent readers and read-only branches run in a bounded window; writes and state changes are barriers. Results remain in request order.
 - `note(kind="pin", work_id, event, what)` links original observations; `supersedes` replaces an earlier reference. `history(work_id=...)`, `history(resource=...)`, and `history(events=[...])` locate or batch-read the originals.
+- Verified history projections use a bounded per-session cache. Original ancestry and sealed digests are checked before every hit; a lost cache is rebuilt from the log.
 
 Use `/new` or `--fresh` to start with the current tool protocol. Existing sessions
 keep their saved frozen schemas and concurrency policy. New sessions default to
@@ -78,6 +80,17 @@ authorized `--budget unlimited` on both `plan` and `run` records costs without a
 dollar ceiling; upstream errors stop the trial, with HTTP 402 marked as awaiting top-up.
 This checks a controlled configuration, not stock Pi or an official leaderboard.
 
+The new single-factor protocol separately compares tool profiles, the carried
+working set, and strict verification. It runs four isolated scenarios through
+real sessions and grades files, fresh command evidence, and pending human review.
+Use `bun scripts/eval-harness.ts smoke --output /absolute/new/eval-directory`,
+then `bun scripts/eval-harness.ts audit --output /absolute/new/eval-directory`.
+Smoke has no paid requests and reports synthetic usage. `plan` and `run` require
+the same explicit numeric `--budget`; inputs, source, schemas, model settings,
+and paired order are frozen before spending. Started directories cannot be
+replayed automatically. Failures and missing trials remain in the denominator,
+and unknown charges retain their reservation. Details are in `docs/benchmarks.md`.
+
 ## Usage
 
 ```
@@ -92,6 +105,8 @@ xeno [-m <model>] [--provider <name>] [--api-key <key>]
      [--system-prompt <text-or-file>] [--append-system-prompt <text>]
      [--no-context-files|-nc]
      [--tools names] [--exclude-tools names] [--no-tools]
+     [--tool-profile coding|readonly|research|data|full]
+     [--acceptance-file <contract.json>]
      [--allow-tools names] [--approve|--no-approve]
      [--theme <name|path>] [--use-theme <name>] [--no-themes]
      [--tui-mode regular|fullscreen]
@@ -102,6 +117,33 @@ xeno [-m <model>] [--provider <name>] [--api-key <key>]
 ```
 
 - No prompt, a tty: interactive session.
+- `/state` shows the current request's execution outcome, command receipts,
+  verification state and diagnostic progress across segment cuts and restarts.
+  Short tasks need no `note` calls to associate evidence. Without a declared
+  acceptance contract, successful commands remain evidence rather than verified
+  task completion. Diagnostic novelty does not change the stall policy.
+- `/acceptance` shows declared command checks and human criteria. `/accept ID`
+  records your acceptance of a human criterion; subsequent edits invalidate it.
+  Use `--acceptance-file` or a trusted project's `.xeno/acceptance.json` with
+  `{ "version": 1, "id": "task", "criteria": [{ "id": "tests", "kind": "command", "description": "tests pass", "command": "bun test" }] }`.
+  The declaration is frozen in the session. A normal execution exit does not
+  imply that human acceptance has been granted.
+  A contract may additionally declare `targets`, each with `id`, `build`
+  (a command criterion ID), `artifacts: { paths, output_roots }`, and `entry`
+  (one of those artifact paths). Optional `interpreter` is an absolute executable
+  path; `args` are literal strings, `workdir` stays inside the workspace, and
+  `port` declares an IPv4 loopback listener. A human criterion binds to it with
+  `target: "ID"`. Enable the `target` tool explicitly with `--tools` or the
+  `full` profile; the default coding profile stays compact. Run the declared
+  build with its exact artifact plan, then `target({action:"start",target:"ID"})`.
+  `inspect` rechecks the owned instance, build inputs, artifact/executable identity
+  and port ownership. `/acceptance` shows the entry, build, PID and session;
+  `/accept ID` binds your decision to that observed instance. Rebuilds, changed
+  files, process exits or lost ownership require fresh acceptance. The first
+  implementation observes macOS executable identity with the system `lsof` and
+  Linux identity with `/proc`; port checks require system `lsof`. Missing OS
+  evidence remains unknown. It never adopts an existing server or proves visual
+  correctness automatically, and a resumed session cannot reattach an old PID.
 - A prompt, or `-p` / `--print`: one shot, then exit. `-p` puts only the
   assistant's final text on stdout; the banner, usage, thinking, and tool
   lines go to stderr. Piped stdin is appended after the command-line prompt.
@@ -131,8 +173,8 @@ Slash commands that exist in the session (from `/help`):
 ```
 /model [id]        search models, or switch (cuts a node)
 /models refresh    refresh ~/.xeno/models-cache.json; preserve models.json
-/login [provider]  choose a login method, or store an API key
-/login claude-pro|codex|github-copilot
+/provider [provider]  connect or manage an account, API key, gateway or local server
+/provider claude-pro|codex|github-copilot|grok
                    subscription login (first-party client credentials)
 /logout [provider] remove a stored credential
 /scoped-models     enable, disable and order models for cycling
@@ -203,13 +245,19 @@ credentials, native cloud protocols, and explicit coverage limits.
 ## Credentials
 
 Order: `--api-key`, `~/.xeno/auth.json`, `models.json` provider/model credentials,
-then the provider's environment variables. A failed explicit source does not
-fall through to another account. `/login codex` uses the `openai-codex` protocol;
+then the provider's environment variables. `/login` and `/connect` remain hidden
+aliases of `/provider`. Enter confirms the selected command argument; Tab inserts it.
+A failed explicit source does not
+fall through to another account. `/provider codex` uses the `openai-codex` protocol;
 ordinary OpenAI API models use `openai`.
 
-Interactive sessions can start with no key and wait for `/login`. `-p` and
+`/provider grok` uses official device authorization and refreshes the account token.
+Its model is `xai-grok/grok-build` on the official CLI inference proxy. xAI API keys
+remain on `xai`; credentials and rates are not shared between these accounts.
+
+Interactive sessions can start with no key and wait for `/provider`. `-p` and
 non-tty runs exit 1 and name `--api-key` or the variable; they do not mention
-`/login`.
+`/provider`.
 
 Keys in `auth.json` may be a literal, `!cmd`, or `$VAR`. The file is written
 mode `0600`.
@@ -231,19 +279,43 @@ Project trust (`/trust`, `--approve`) only decides whether to load
 It does not change what tools can do. `AGENTS.md` is loaded whether the
 project is trusted or not.
 
+New sessions default to the nine-tool `coding` profile: read, grep, find,
+write, edit, exec_command, write_stdin, history and note. `readonly`,
+`research` (with branch/resolve), `data` (with query) and `full` choose other
+builtin defaults. Extensions remain available; explicit `--tools` overrides
+the profile and exclusions apply last. Resumed sessions keep their frozen tools.
+
 `--tools` / `--exclude-tools` / `--no-tools` remove tools from the schema
-the model sees. `--allow-tools bash` lets bash run without asking, which
+the model sees. `--allow-tools exec_command` lets commands run without asking, which
 is what a CI job that has no tty has to pass explicitly. Without a tty,
 an `ask` is a deny that names that flag.
 
 ## Workspace data
 
+Opening a session does not snapshot the working directory. File tools save the
+original bytes before editing and record the observed result. `/back` restores
+only recorded paths, preserves unrelated files, and refuses conflicting external
+edits. Conversation-only navigation leaves files unchanged.
+
+Shell effects are not automatically reversible. Opt in for a new session with
+`--checkpoint-shell` to capture eligible Git files around commands. This uses a
+private index and object store without changing your staging area or HEAD. Git
+ignored paths, non-regular files, untracked files over 2 MiB, and effects outside
+the workspace are excluded. Capture is best effort; unavailable recovery does
+not prevent a conversation or change the command's exit result. A running process
+has a pending checkpoint until its exit is observed; overlapping writes make that
+checkpoint unavailable. Initial capture can take time.
+
+Verification observes a bounded source scope separately from file recovery.
+Unknown observations cannot certify a completion claim. Old snapshot logs remain
+readable; new file records and scope markers are appended without rewriting them.
+
 A session writes into the workspace:
 
 | Path | |
 |---|---|
 | `.xeno/sessions/<id>/` | node logs, handoffs, metadata journal, derived manifest, and observation artifacts |
-| `.xeno/blobs/` | content-addressed file snapshots used by `/back` |
+| `.xeno/blobs/` | content-addressed before/after file versions used by `/back` |
 
 That tree grows with every turn and every snapshot. There is no garbage
 collection yet. Dead branches from `/back` stay on disk.
@@ -297,16 +369,29 @@ Shipped, not planned:
   Repeated content, renamed completion claims and gate regressions do not reset
   the three-segment stop rule. This is an anti-stall heuristic, not proof of
   relevance or completion; [`research M.4`](docs/agent-harness-research.md) states its limits.
-- A terminal UI using the pinned Pi renderer, raw input, editor, autocomplete,
-  Markdown, searchable pickers and settings. Durable history is a pure log
-  projection across handoff boundaries. Includes tool diffs, historical folds,
-  Pi dark/light palettes, `keybindings.json`, `/settings` and `/hotkeys`.
+- A terminal UI using pinned OpenTUI, a native text editor, autocomplete,
+  Markdown, a command palette and searchable pickers. Durable history is a pure
+  log projection across handoff boundaries. Includes tool diffs, historical
+  folds, terminal colours, `keybindings.json`, `/settings` and `/hotkeys`.
 
 - Context files: `AGENTS.md` / `CLAUDE.md` and the override chain, plus
   `--system-prompt` / `--append-system-prompt` / `-nc`.
 - Skills (`~/.xeno/skills/`, `/skill:name`) and prompt templates
-  (`~/.xeno/prompts/`, `/name`). Untrusted projects do not load the
+  support progressive loading, user visibility, explicit tool intersections
+  and isolated `context: fork`. Unsupported execution fields are diagnosed.
+  Loaded instructions keep frozen source hashes and recoverable artifacts.
+  Templates use `~/.xeno/prompts/` and `/name`. Untrusted projects do not load
   project-level copies.
+- `/tasks` shows dependency readiness and claims. Long tasks can use
+  `note(kind="next", work_id="b", depends_on=["a"], ...)`, then
+  `claim_work` / `release_work`; these are scheduling intent, separate from
+  the `done` command proof. Ordinary short tasks do not need a graph.
+- `branch(background=true)` returns an owned task reference. `/branches`
+  lists its current capability; `/branches wait|cancel|status <node>` joins or
+  controls it without a model request. `resolve` exposes the same actions.
+  Restarted unfinished tasks remain unknown; sealed outcomes can be joined.
+- `/processes` separates the last logged observation from a live handle.
+  Session exit drains its own processes and archives unread output.
 - `/reload` refreshes local models, settings, keybindings, context files, skills,
   templates and themes without losing the draft or active model. A changed system
   prefix checkpoints first; unchanged resources do not create a new segment.
@@ -326,11 +411,15 @@ Shipped, not planned:
   `-e` tries a package for one invocation. Manifests, per-kind filters and trust
   feed the same resource inventory. Normal startup stays offline.
   See [package management](docs/packages.md).
-- `/login` for API keys and for Claude Pro/Max, Codex, and GitHub
-  Copilot subscription flows. See Known gaps.
+- `/provider` for API keys and for Claude Pro/Max, Codex, GitHub Copilot,
+  and official Grok account flows. See Known gaps.
 
 Images can be attached with `@path`, a dropped image path, or Ctrl+V (files,
-image, then text). `/attachments` removes draft images; queue recall and history
+image, then text). Pasted and dropped images become `[Image #N]` tags at the
+caret. Left/Right cross a whole tag; Backspace/Delete remove it in one step,
+and Undo restores it. Moving the caret next to a tag shows its preview above
+the input (filename and dimensions when image display is unavailable).
+`/attachments` remains available for removal; queue recall and history
 forks retain them. The log stores immutable blob references. Provider adapters
 load verified bytes for Anthropic, Chat Completions and Responses; text-only
 models receive a visible placeholder. Custom models declare `input: ["text", "image"]`
@@ -360,27 +449,30 @@ unblocking affects new submissions, preserving historical request prefixes.
 - **`/back` does not restore symlinks.**
 - **`.xeno/` is not collected.** Snapshots and abandoned session branches
   stay until you delete them.
-- **No telemetry, `/share`, auto-update, or `/compact`.** Those are
-  refusals (`docs/PI_PARITY.md` D15, D16), not backlog.
+- **No telemetry, `/share`, self-installing updates, or `/compact`.** Those
+  are refusals (`docs/PI_PARITY.md` D15, D16), not backlog. xeno does say
+  when a newer version is published, at most once a day and never installing
+  it; `docs/install.md` (Updates) lists what that request reveals and every
+  way to turn it off.
 
 `docs/TUI_ARCHITECTURE.md` describes the active interaction path and verification.
 `docs/PI_PARITY.md` records deliberate differences and remaining Pi features.
-Pi's editor supports undo, not redo; an old `editor.redo` binding is diagnosed
-as unsupported rather than silently accepted. Ctrl+- invokes Pi undo.
+The native editor supports undo (Ctrl+_ or Ctrl+/) and redo (Ctrl+Shift+Z).
+Registered image tags move and delete as whole units and share text undo history.
 Ctrl+Z suspends the CLI on POSIX; `fg` restores the terminal and unsent draft.
 
-`/settings tuiMode fullscreen` uses Pi's alternate-screen viewport, transcript
-search (Ctrl+Shift+F), prompt navigation (Ctrl+Up/Down), mouse scrolling and text
-selection. `/settings fullscreenExitOutput resume-hint` leaves a resume command
-when exiting; `transcript` prints the conversation. Switching modes preserves
-the editor, history and undo. Scrollbar, wheel speed, copy-on-select, editor
-padding, autocomplete rows, cursor, output padding and double-Escape behavior
-are configurable in `/settings`.
+Fullscreen is the default. Ctrl+P opens commands, Ctrl+L selects a model,
+PgUp/PgDn scroll, and Ctrl+Home/End jump to the start or latest messages.
+Ctrl+O expands tools, Ctrl+T expands thinking, and Ctrl+B toggles the sidebar.
+Mouse selection copies plain text when `fullscreenCopyOnSelect` is enabled;
+Ctrl+X copies a selection or the last reply. Exiting restores the terminal and
+prints the conversation and a resume command. The composer stays at the bottom
+and grows with the draft; pickers and forms use the same input area.
 
 `/settings theme` previews built-in and custom themes from the config directory's
 `themes/`. Escape restores the prior theme. Custom files reload after valid edits;
-`auto` follows terminal light/dark changes and `system` derives Pi's palette from
-terminal color replies. Pi's namespaced action IDs work in `keybindings.json`
+`auto` follows terminal light/dark changes. Built-in themes keep the terminal's
+background and derive readable accents from its colour replies. Namespaced action IDs work in `keybindings.json`
 alongside existing xeno names; an empty array disables an action in its own scope.
 
 ## Why this shape
@@ -575,10 +667,10 @@ Every path below was checked with `test -f` on this checkout.
 | `runtime/benchmark.ts` | actual Session trials, bounded spending and cache diagnostics |
 | `runtime/loop.ts` | orchestration; every judgement delegates to a pure function in core |
 | `runtime/auth.ts` / `oauth.ts` | credential order and subscription flows |
-| **`src/vendor/pi-tui/`** | unmodified Pi terminal and component library, pinned in `VENDOR.md` |
-| **`src/tui/`** | Pi input, component and theme adapters; no harness imports |
-| `tui/markdown.ts` / `toolview.ts` / `statusline.ts` / `tree.ts` | display |
-| **`src/apps/`** | `cli.ts` — Pi main-screen UI for TTY, clean print/JSON output otherwise |
+| **`src/tui/`** | OpenTUI view components and pure display helpers; no harness imports |
+| `tui/ui/composer.ts` / `atomic-draft.ts` / `messages.ts` / `screen.ts` | native editing, atomic image tags, messages and layout |
+| **`src/apps/`** | `cli.ts` — OpenTUI for TTY, clean print/JSON output otherwise |
+| `apps/ui/app.ts` / `project.ts` / `status-model.ts` | controller, transcript projection and status facts |
 | `apps/startup.ts` / `shell.ts` / `commands.ts` | flags, session, slash commands |
 
 ## Properties the tests pin

package/docs/app-server.md

@@ -0,0 +1,84 @@
+# 会话控制接口与 TUI 工作台
+
+状态：实验性 `xeno-control/0.1`。TUI 和适配器共用一个 `SessionControl`、一个实际 Session 和同一份 append-only 日志。协议借鉴 Codex App Server 的生命周期，**不声明与 Codex v2 wire format 兼容**。没有新增模型调用、第二个执行进程或独立目标数据库。
+
+## 从源码使用
+
+```bash
+bun run agent app-server schema
+bun run agent app-server --model openai-codex/gpt-6-luna
+bun run agent --control-socket /tmp/xeno-control-private/control.sock
+```
+
+第一条只打印版本、请求参数 schema、通知清单及限制，不加载模型凭证。第二条用 stdin/stdout 双向 JSONL；诊断在 stderr。启动会话仍采用原有的凭证、工具权限、`--session` / `--continue` 和 `--acceptance-file` 参数。提示从 `turn/start` 提交，不能作为位置参数。结构化模式不构造 TUI，也不发送 OSC。
+
+第三条正常启动 TUI，Unix socket 连接到它当前的同一个会话。父目录必须由当前用户拥有且权限为 0700；不存在时自动创建，socket 为 0600。已有路径拒绝覆盖。这里没有 TCP、Web 面板或远程认证服务。每个适配器都是具有当前用户本地控制能力的客户端，可启动工具和答复审批。
+
+## 初始化与恢复
+
+每行一个 JSON 对象；省略 `jsonrpc`。请求必须有字符串或安全整数 `id`，响应返回相同 `id` 及 `result` 或 `error`。只有 `initialized` 是客户端无 id 通知。所有其他方法必须等初始化完成。
+
+```json
+{"id":1,"method":"initialize","params":{"clientInfo":{"name":"my-adapter","version":"0.1"}}}
+{"method":"initialized"}
+```
+
+读取 initialize 的 `result.threadId` 和 `result.streamId` 后，提交：
+
+```json
+{"id":2,"method":"thread/subscribe","params":{"threadId":"<returned-threadId>"}}
+{"id":3,"method":"turn/start","params":{"threadId":"<returned-threadId>","input":"Inspect the failing test and report the evidence."}}
+```
+
+通知可以早于对应请求响应，客户端应按 request id 关联响应。`thread/subscribe` 先订阅，再返回快照；应先缓存这期间的通知，拿到快照后只应用同一 streamId 且 sequence 大于快照 sequence 的通知。sequence 是控制器生命周期内递增的通知序号，包含瞬时输出，不能作为持久日志地址。
+
+- `threadId` 是规范化绝对 session 目录路径的 SHA-256。同路径冷恢复保持身份；移动或复制目录会改变身份，不是可携带 UUID。
+- `streamId` 每个活控制器生成一次。重启会变化；`turnId` 等于这一轮原始 user event ID；steering 引用这个请求，不另开目标。
+- `item/completed` 在持久 append 成功后发送 `{node,id,type}`。完整事件通过 `item/read` 读取，唯一地址是 node + event id。
+- 断线、序号跳跃或 streamId 改变：重新初始化、订阅，消费返回快照，再分页读 `item/list` / `item/read`。可给订阅传 `after:{streamId,sequence}`；游标与当前快照不同就返回 `resyncRequired:true`。
+- 不保存、重放瞬时文本 delta，不重放命令。控制请求不具备幂等重试保证；丢失 `turn/start` 响应时先查看当前 turn 和日志，不能盲目重发。
+- TUI 切换 Session 后，旧 threadId 拒绝继续控制，适配器应建立新连接重新初始化。当前协议没有多会话列表、创建或切换方法。
+
+## 方法与事件
+
+`app-server schema` 输出的 `methods` 是实际入参验证器共用的 schema；目前不是所有响应类型的完整 JSON Schema/生成式 SDK。
+
+| 方法 | 除 threadId 外的参数 | 结果 / 作用 |
+|---|---|---|
+| `thread/read` | 无 | 当前目标、执行、进展、上下文和待审批快照 |
+| `thread/subscribe` | 可选 after | 订阅通知并返回快照及 resyncRequired |
+| `turn/start` | input | 开始唯一执行，返回 turnId；忙时拒绝 |
+| `turn/steer` | turnId, input | 排队，在原有模型/工具边界消费；最多 32 项 |
+| `turn/interrupt` | turnId | 取消并清理当前执行；完成由 turn/completed 确认 |
+| `approval/respond` | turnId, approvalId, choice | once / command / tool / deny；过期身份拒绝 |
+| `acceptance/accept` | requestId, criterionId | 只在 idle 显式批准本请求已声明的人验条件 |
+| `context/read` | focus，可选 offset / limit | messages / omitted / history 来源分页，不改模型输入 |
+| `item/list` | 可选 after:{node,event} / limit | 当前活动路径的日志身份分页 |
+| `item/read` | node, event | 当前活动路径上的完整日志事件 |
+
+分页 limit 为 1–100，默认 50。切换路径后旧游标可能失效，应重新获取快照。完整单条事件超过帧上限会报错；此版本不提供大事件分块下载。
+
+通知包括 `turn/started`、`turn/event`（原有 LoopEvent 的瞬时进展）、`item/completed`、`turn/completed`、`turn/error`、`turn/steeringQueued`、`approval/request`、`approval/resolved`、`thread/statusChanged`。每条带 threadId / streamId / sequence，活动 turn 存在时带 turnId。`turn/completed.steeringUndelivered` 明确没有消费的排队输入；客户端不能将“已入队”显示为“已执行”。provider 抛错时仍从持久日志读取 outcome，错误通知不透出原始 provider 报文。
+
+日志是事实来源。观察者得到独立副本，修改或抛错不能改变执行。刷新 idle 快照沿原有验收观察边界重新检查工作区，可能追加失效证据；这不提交提示或调用模型。活动目标和快照游标采用同一个已发布事件边界；切段期间无法一致读取时返回刷新错误。
+
+## 审批、断连与限制
+
+审批是同一个权限请求；TUI 或适配器答复后另一端的待审批状态同时结束。取消清理审批承诺，不允许晚到 provider 响应覆盖取消状态或继续执行工具。stdio 是独立会话的主控制连接：EOF/关闭会拒绝审批并取消执行。Unix socket 客户端断开只撤掉该观察者，TUI 继续拥有当前审批与执行。
+
+输入单帧上限 1 MiB，每连接最多排队 32 请求，输出缓冲上限 2 MiB，socket 最多 32 客户端；这些是传输容量假设，不是模型策略阈值。超限断开或返回有界错误。错误码：`-32600` envelope、`-32601` 未知方法、`-32602` 参数、`-32700` JSON、`-32000` 生命周期/执行冲突、`-32001` 传输容量、`-32002` 响应过大。快照本身过大时使用分页 inspector；超大目标详情需要后续协议扩展。
+
+## TUI 与终端状态
+
+常驻 Goal 区展示原始目标、验收状态、执行状态和观察/重试数。`/control` 打开同一会话的面板：Tab 切 Goal / Progress / Context Lens，左右键切上下文来源/省略事件/handoff 恢复引用，上下键翻阅，R 刷新，I 取消，A 选择当前声明的人验条件。远程开始的普通 turn 会更新当前 TUI，并可在面板取消。TUI 输入的 steering 在同一 turn 的原有边界消费，followup 等原 turn 释放后执行；远程取消也把未发送内容归还编辑器。既有隔离 skill / shell 保留各自执行入口，当前协议不新增远程 skill/shell 方法。
+
+无验收合同保持 `unverified`；模型结束 `model_end` 不等于目标 `verified`。Progress 的观察、产物、验收、新诊断和原样重试均带日志来源；数量不是完成百分比。Context Lens 复用实际 dispatch 的投影，只过滤检查视图，不修改 frozen prefix、handoff 或消息。
+
+OSC 7501 遵循 [Program Status Protocol](https://www.superlogical.com/rex/docs/build/program-status) 的状态、身份及 UTF-8 base64 消息语法：
+
+- `XENO_PROGRAM_STATUS=auto`（默认）：TTY 探测成功后才发送状态；未回复时只有一次探测，不发送报告。
+- `XENO_PROGRAM_STATUS=1`：显式开启；`0`：关闭。管道始终关闭；auto 在 tmux/screen 内关闭，可用 1 显式覆盖。
+- running → working，审批/认证/提问 → blocked + kind，取消 → idle，失败 → error。结束使用 done，同时固定消息明确是否通过目标合同；待人验保持 blocked。
+- 不发送用户提示、模型输出、凭证或假百分比。每进程只操作自己的 `xeno-<pid>` 记录；退出清理瞬时记录，保留规范要求可留存的 done/error。
+
+自动验证包含真实 TUI、真实 Unix socket、CLI JSONL 与 PTY 探测；不等同于作者在所有终端上的视觉验收。配对实验及真实历史语料统计见[研究报告](research/session-control-evaluation-2026-10-08.md)。

package/docs/install.md

@@ -16,7 +16,7 @@ The entry point is `src/apps/cli.ts` with `#!/usr/bin/env bun`. The
 process uses Bun APIs (`Bun.file`, `Bun.spawn`, `Bun.spawnSync`,
 `for await (const line of console)`). Those are why the runtime is Bun.
 
-`engines.bun` is `>=1.1.0`. This checkout was run on **Bun 1.3.10**.
+`engines.bun` is `>=1.3.0` (required by the OpenTUI renderer, D20). This checkout was run on **Bun 1.3.10**.
 Node is untested. That is a fact about this tree, not a promise that
 Node support is coming.
 
@@ -30,16 +30,14 @@ cd xeno
 bun install
 ```
 
-`bun install` pulls the provider SDK, Pi text layout/Markdown dependencies,
-syntax highlighting, Mermaid, Photon image processing, and TypeScript tooling.
+`bun install` pulls the provider SDKs, OpenTUI and its platform renderer,
+Markdown, syntax highlighting, Mermaid, Photon image processing, and TypeScript tooling.
 The exact versions are in `package.json` and `bun.lock`.
 
-Pi native helpers for macOS, Linux X11 and Windows (arm64/x64) ship with the
-package. They are pinned upstream builds with matching source and hashes;
-startup does not download or compile them. Missing platform support uses the
-clipboard command fallbacks. The packaged macOS helper was load-tested on
-this machine; Linux/Windows payloads and routing are checked without claiming
-native device acceptance.
+OpenTUI supplies the native renderer through its platform dependencies.
+Clipboard integration uses terminal OSC 52 and platform commands; the old
+vendored Pi native helpers are no longer packaged. Release package checks run
+on macOS arm64; they do not establish Linux or Windows device acceptance.
 
 Run the CLI without linking:
 
@@ -68,10 +66,49 @@ Each invocation starts a new session. `xeno -c` continues the newest one;
 and nothing is deleted. Resume restores the saved model. An explicit
 `--model` switches at a checkpoint while keeping the original log intact.
 
-Startup loads resources and establishes a workspace snapshot before the editor
-opens. Slow initialization shows its current stage; Ctrl+C cancels startup and
-restores the terminal. Snapshots cover the selected workspace, so start inside
-the intended project or pass `--workspace <path>`.
+Startup loads resources and opens or restores the session. Workspace snapshots
+are deferred until file tools need them, so opening an editor does not scan the
+whole project. Slow initialization shows its current stage; Ctrl+C cancels it
+and restores the terminal. Start inside the intended project or pass
+`--workspace <path>`.
+
+## Updates
+
+xeno says when a newer version is published. It never installs one: the
+notice names the command, and you run it.
+
+```
+xeno 0.4.0 is available (you have 0.3.0)
+  bun add -g @visual-z/xeno@latest
+```
+
+The command follows where this copy is installed: `bun add -g` under
+`~/.bun/install/global/`, `npm i -g` under an npm global prefix
+(`…/lib/node_modules/`, or `…\npm\node_modules\` on Windows). Anywhere else
+the notice points to this file. A checkout updates with `git pull`.
+
+- **Request.** `GET https://registry.npmjs.org/-/package/@visual-z%2fxeno/dist-tags`
+  (an 18-byte answer). If that fails, `GET …/@visual-z%2fxeno/latest`.
+  `npm_config_registry` replaces the host. The timeout is 3 seconds.
+- **What the registry learns.** Your IP address, the time, the package name
+  and Bun's default `User-Agent` (`Bun/<version>`). No identifier, no query
+  string, nothing from your session.
+- **How often.** At most once every 24 hours. The time and the version seen
+  are kept in `~/.xeno/update-check.json`. A failed attempt is recorded too,
+  so a closed network is not retried on every start.
+- **When.** In the background after the editor opens. Startup never waits for
+  it, and quitting cancels it. A version found during a session is shown only
+  while that session is still empty. Otherwise it waits for the next start,
+  so it never interrupts a turn.
+
+Nothing is sent when any of these holds:
+
+- `--offline` or `XENO_OFFLINE=1`
+- `XENO_NO_UPDATE_CHECK` or `NO_UPDATE_NOTIFIER` is set (to anything but empty, `0` or `false`)
+- `"updateCheck": false` in `settings.json` (*Check for updates* in `/settings`)
+- `CI` or `CONTINUOUS_INTEGRATION` is set, by the same rule
+- the run is not the interactive app: `-p`, `--mode json`, `--export`, `--list-models`, `models --refresh`, package and `config` commands, `--version`
+- xeno runs from a checkout: its package root is not under `node_modules`, or has a `.git` (`bun src/apps/cli.ts`, `bun run agent`, `bun link`)
 
 ## Credentials
 
@@ -129,6 +166,7 @@ settings.json     theme, thinking, defaults
 trust.json        which directories may load project settings
 models.json       optional user provider/model configuration
 models-cache.json generated catalog cache (written by `xeno models --refresh`)
+update-check.json when the last update check ran, and the newest version it saw
 keybindings.json  optional
 prompts/ skills/  optional
 ```

package/docs/providers.md

@@ -1,9 +1,30 @@
 # 供应商、模型目录与自定义配置
 
-xeno 内置 Pi 0.99.1 和 OpenCode 所用 Models.dev 的固定源并集：226 个供应商、7,501 个模型条目。同一个模型在不同供应商下分别计数。目录保留能力与已知价格；未提供的价格显示未知，不用零补全。
+xeno 内置 Pi 0.99.1 和 OpenCode 所用 Models.dev 的固定源并集，另加 Grok 官方账户代理入口：227 个供应商、7,502 个模型条目。同一个模型在不同供应商下分别计数。目录保留能力与已知价格；未提供的价格显示未知，不用零补全。
 
 来源固定为 Pi `1b347794e2a630e4359f2584f4eea388145d0ddf`、OpenCode `2fa3363c924c5c3e367b84a87ae478296a0ed59b`，Models.dev JSON SHA256 `7345de7358c471e78ac756aed556cd804677cd0d8748b71edc3931225440158f`。SDK 固定为 `@earendil-works/pi-ai@0.99.1`；引入它是为了复用维护中的原生协议和签名处理，避免在 xeno 重写十套 SDK。SDK 仅在 runtime；原有 TUI vendor 的版本与升级方式独立。
 
+## 最快的接入：`/provider`
+
+在交互界面输入 `/provider`（`/provider <provider>` 直达；`/login`、`/connect` 是兼容别名）。一个列表里包含全部接入方式。Enter 执行选中的命令或参数，Tab 只插入补全；文件引用只插入，不提交提示：
+
+- **账户**：Claude Pro/Max、ChatGPT Plus/Pro（Codex）、GitHub Copilot、Grok 官方账户，走浏览器或设备码登录。
+- **API key**：选择目录中的供应商（Anthropic、OpenAI、Gemini、DeepSeek、OpenRouter、Kimi、智谱、硅基流动、通义、豆包等，可搜索），粘贴 key（掩码显示；`$MY_KEY` 读取环境变量）。
+- **＋ Custom endpoint…**：OpenAI Chat Completions / OpenAI Responses / Anthropic Messages / Gemini 兼容地址，或 Ollama、LM Studio。填 base URL（粘贴完整的 `…/chat/completions`、`…/v1/messages` 会自动截断）、ID 和 key 后，xeno 用这个 key 向端点列出模型（OpenAI `GET /models`；Anthropic `GET /v1/models`；Gemini `GET /v1beta/models`），勾选要启用的模型后保存。
+- **⚙ Manage connected…**：重新列出并选择模型、更换 key 或断开。
+
+`/model` 只显示已接入且凭据可用的模型，最近使用的排在最前。保存位置与手写配置相同：key 在 `~/.xeno/auth.json`（0600），端点和启用的模型在 `~/.xeno/models.json` 的 `providers.<id>`。
+
+## Grok 官方账户
+
+输入 `/provider grok`，xeno 打开官方确认网页并显示 user code；在浏览器批准后，当前会话直接取得凭据。Esc 取消会中止轮询，取消后返回的 token 不会写入。过期时自动刷新，刷新响应未轮换 refresh token 时保留原值；失败会明确要求重新登录。
+
+账户存为 `auth.json` 的 `xai-grok`（0600），模型身份为 `xai-grok/grok-build`，请求走 `https://cli-chat-proxy.grok.com/v1`。`xai` 仍表示 `XAI_API_KEY` 与 `https://api.x.ai/v1`；两个身份不共享凭据或计费账户。也可显式提供 `GROK_ACCESS_TOKEN`，但环境 token 没有 refresh token，不能自动刷新。账户代理地址不能覆盖到其它服务。
+
+采用官方 RFC 8628 设备授权（`https://auth.x.ai/oauth2/device/code` 与 `/oauth2/token`）；只申请推理及刷新所需 scopes，`referrer` 与 User-Agent 标识 xeno。协议所需 `X-XAI-Token-Auth` 与模型路由头遵循官方代理合同。依据：[Grok Build 企业认证](https://docs.x.ai/build/enterprise)、[官方授权源码](https://github.com/xai-org/grok-build/tree/main/crates/codegen/xai-grok-login/src)、[官方代理调用示例](https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-shell/README.md)。
+
+`grok-build` 是官方代理别名，不能把 API 模型的价格、上下文长度或可选 effort 套给它。当前保守暴露文本/工具调用，价格未知、effort 选择关闭；实际账户权限由官方服务决定。设备授权启动已实测返回 200，授权后的推理/刷新有受控 HTTP 验证；没有替用户完成真实账户批准或调用付费模型。
+
 ## 目录和选择
 
 ```sh
@@ -114,7 +135,7 @@ xeno models --refresh
 | `anthropic-messages` | Anthropic、支持 Messages 的网关；API key 或已有 Claude OAuth |
 | `openai-completions` | Chat Completions 兼容端点 |
 | `openai-responses` | OpenAI Responses；每次发完整投影，`store: false` |
-| `openai-codex-responses` | ChatGPT 订阅端点；`/login codex` 或 `OPENAI_CODEX_ACCESS_TOKEN` |
+| `openai-codex-responses` | ChatGPT 订阅端点；`/provider codex` 或 `OPENAI_CODEX_ACCESS_TOKEN` |
 | `azure-openai-responses` | Azure key + resource/base URL；支持 `AZURE_RESOURCE_NAME` / `AZURE_API_KEY` 别名 |
 | `google-generative-ai` | Gemini 原生 API，Google/Gemini API key |
 | `google-vertex` | Vertex API key，或 `auth: "ambient"` + ADC；项目和位置必需 |
@@ -124,7 +145,7 @@ xeno models --refresh
 
 Vertex 可配置 scoped `env`：`GOOGLE_APPLICATION_CREDENTIALS`、`GOOGLE_CLOUD_PROJECT`、`GOOGLE_CLOUD_LOCATION`；也接受 OpenCode 的 `GOOGLE_VERTEX_PROJECT` / `GOOGLE_VERTEX_LOCATION`。Bedrock 使用 `AWS_PROFILE`、`AWS_REGION` 等 SDK 环境设置；resource/project/location 不会被当成 API key。需要端点模板的服务必须提供对应变量，例如 Cloudflare 的 account/gateway。
 
-旧 `auth.json` 中存于 `openai` 的 Codex OAuth 可由 `openai-codex` 兼容读取；显式原生条目优先，普通 OpenAI API key 不共享到订阅协议。新的 `/login codex` 写入 `openai-codex`。其他 Pi 专属订阅登录流程不冒充已接入；可按协议配置 key/token。
+旧 `auth.json` 中存于 `openai` 的 Codex OAuth 可由 `openai-codex` 兼容读取；显式原生条目优先，普通 OpenAI API key 不共享到订阅协议。新的 `/provider codex` 写入 `openai-codex`。其他 Pi 专属订阅登录流程不冒充已接入；可按协议配置 key/token。
 
 ## 可配置参数与边界
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visual-z/xeno",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "license": "UNLICENSED",
   "type": "module",
   "description": "Segmented append-only agent log with pure context and handoff projections",
@@ -12,13 +12,15 @@
     "README.md",
     "CHANGELOG.md",
     "docs/install.md",
-    "docs/providers.md"
+    "docs/providers.md",
+    "docs/app-server.md"
   ],
   "engines": {
-    "bun": ">=1.1.0"
+    "bun": ">=1.3.0"
   },
   "repository": {
-    "type": "git"
+    "type": "git",
+    "url": "git+https://github.com/visual-z/xeno.git"
   },
   "scripts": {
     "test": "bun test",
@@ -37,8 +39,8 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.127.0",
     "@earendil-works/pi-ai": "0.99.1",
+    "@opentui/core": "0.5.14",
     "@silvia-odwyer/photon-node": "0.3.4",
-    "get-east-asian-width": "1.6.0",
     "grok-mermaid": "0.2.3",
     "highlight.js": "10.7.3",
     "marked": "18.0.11"

package/src/apps/app-server.ts

@@ -0,0 +1,28 @@
+import { CONTROL_SCHEMA } from "../core/control-protocol.ts";
+import { sessionControl } from "../runtime/session-control.ts";
+import { ControlJsonl } from "./control-transport.ts";
+import { interactiveHooks } from "./shell.ts";
+import type { App } from "./startup.ts";
+
+/** Owns stdin/stdout only. Startup diagnostics use stderr; terminal UI is never constructed. */
+export async function runAppServer(app: App): Promise<void> {
+  const control = sessionControl(app.session);
+  await interactiveHooks.bindExtensions(app);
+  app.askSlot.current = request => control.ask(request);
+  const stop = () => { process.stdin.destroy(); if (control.activeTurnId) control.interrupt(control.activeTurnId); };
+  const peer = new ControlJsonl(() => control, text => {
+    if (process.stdout.writableLength + Buffer.byteLength(text) > CONTROL_SCHEMA.limits.outputBytes) stop();
+    else process.stdout.write(text);
+  }, stop, true);
+  const signal = () => { process.exitCode = 130; stop(); };
+  process.once("SIGINT", signal); process.once("SIGTERM", signal); process.stdout.on("error", stop);
+  try {
+    for await (const chunk of process.stdin) peer.feed(typeof chunk === "string" ? Buffer.from(chunk) : chunk as Uint8Array);
+    await peer.drained();
+  } finally {
+    peer.close(); stop();
+    await control.whenIdle().catch(() => {});
+    await app.session.dispose(); await app.extensions?.dispose(); delete app.askSlot.current;
+    process.off("SIGINT", signal); process.off("SIGTERM", signal); process.stdout.off("error", stop);
+  }
+}