daemon-api.md

# ACECode Daemon Web API

This document describes the HTTP and WebSocket protocol exposed by
`acecode daemon` / `acecode service` for the Web and Desktop frontends.

Source of truth for this document:

- Route registration: `src/apps/web/routes/routes_*.cpp`
- Shared response helpers: `src/apps/web/server_helpers.cpp`
- Frontend callers: `web/src/lib/api.js`, `web/src/lib/connection.js`,
  `web/src/lib/consoleDock.js`

`OPTIONS` routes are CORS preflight helpers and are not listed as first-class
endpoints below.

---

## 1. Connecting

### Starting the daemon

Run `acecode daemon` to start a detached daemon; `acecode daemon start` remains
an explicit compatibility alias. Without `--cwd`, the worker uses the directory
from which the command was invoked. `--cwd=<PATH>` selects another workspace.

### Runtime files

After the daemon starts, runtime files are written to `<data_dir>/run/`:

| File | Content |
|---|---|
| `daemon.pid` | numeric pid |
| `daemon.port` | numeric port |
| `daemon.guid` | UUID v4 |
| `heartbeat` | JSON `{pid, guid, timestamp_ms}` refreshed periodically |
| `token` | URL-safe daemon token |
| `desktop-managed.json` | Desktop-managed identity `{pid, guid, kind, protocol_version, acecode_version}` |
| `desktop-owner.json` | current Desktop owner `{pid, instance_id, timestamp_ms}` |

`<data_dir>` is `~/.acecode/` for standalone daemons and the platform service
data directory for installed services.

The native Desktop uses the reserved
`<data_dir>/run/desktop-shared/` directory. It verifies the process executable,
PID, GUID, heartbeat, port, health response, and Desktop protocol before
attaching to an existing process. A compatible process is reused; a verified
incompatible Desktop-managed generation is stopped and replaced. Standalone
CLI daemons use their normal runtime directory and are not reclaimed by this
Desktop lifecycle. Daemon-generation cleanup preserves `desktop-owner.json`;
the next Desktop instance overwrites that owner record before discovery, which
prevents a late old daemon teardown from erasing a rapid-relaunch handoff.

Closing the macOS Desktop window only hides it. Dock or menu-bar activation
shows the same window again. A real application quit either stops the managed
background process or releases it according to the global Desktop preference
“退出 ACECode 后继续运行后台进程”. The preference defaults to off, and changing
it affects the next application quit rather than immediately stopping the
current process.

### Bind and auth

The daemon always uses the canonical loopback bind `127.0.0.1`. Its fixed,
unconfigured port is `12399`; an explicit `config.web.port` overrides that
default, and `daemon --port=<N>` overrides both. It is fail-fast on a
daemon-port collision and never scans for another port. Existing configurations
that explicitly set `28080` continue to use `28080`.
Remote Web access uses a distinct supervised proxy process configured by
`config.web.remote_enabled` / `config.web.remote_port`.

| Bind | Token required? |
|---|---|
| Loopback (`127.0.0.1`, `localhost`, `::1`) | Optional for same-origin loopback requests |
| Proxy-originated (`127.0.0.2`; on macOS, where only 127.0.0.1 exists on lo0, one of the machine's own non-loopback IPv4 addresses) | Explicit token required |
| Non-loopback remote client | Explicit token required |

`daemon --require-local-token` removes the loopback exemption: every HTTP and
WebSocket request must present the token, including requests from `127.0.0.1`.
The Android app always starts the daemon this way, because on Android every
installed app shares the same loopback interface. Static front-end assets stay
public; the page bootstraps the token from `?token=` as the remote Web does.

Token locations:

- HTTP: `X-ACECode-Token: <token>`
- WebSocket: `?token=<token>`; browsers cannot set custom WS headers reliably

Auth failures return HTTP `401` with `{"error":"no token"}` or
`{"error":"bad token"}`. WebSocket handshakes are rejected.

### CORS

Loopback origins receive:

- `Access-Control-Allow-Origin: <origin>`
- `Access-Control-Allow-Headers: Content-Type, X-ACECode-Token`
- `Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS`

---

## 2. Common Shapes

### Error body

Most JSON errors are one of:

```json
{"error":"BAD_REQUEST","message":"human readable text"}
```

or:

```json
{"error":"human readable text"}
```

### Workspace

```json
{
  "hash": "16-char-cwd-hash",
  "cwd": "C:/repo",
  "name": "repo",
  "available": true
}
```

`__local__` is a compatibility workspace hash for the daemon cwd.

### Session summary

Session list endpoints return arrays of objects shaped like:

```json
{
  "id": "session-id",
  "active": true,
  "status": "idle",
  "workspace_hash": "abc123",
  "cwd": "C:/repo",
  "no_workspace": false,
  "title": "Investigate daemon routes",
  "title_source": "user",
  "summary": "latest user summary",
  "swarm_mode": "off",
  "created_at": "2026-07-04T01:23:45Z",
  "updated_at": "2026-07-04T01:25:00Z",
  "last_user_message_at": "2026-07-04T01:24:00Z",
  "last_turn_outcome": "completed",
  "provider": "openai",
  "model": "gpt-4.1",
  "model_name": "work-gpt",
  "model_preset": "work-gpt",
  "context_window": 128000,
  "deleted": false,
  "message_count": 12,
  "turn_count": 4,
  "worktree": {
    "name": "ses-session-id",
    "branch": "worktree-ses-session-id",
    "path": "C:/repo/.acecode/worktrees/ses-session-id"
  },
  "permission_mode": "default",
  "token_usage": null,
  "session_token_usage": null,
  "todos": [],
  "todo_summary": {"total":0,"pending":0,"in_progress":0,"completed":0,"cancelled":0},
  "archived": false,
  "attention_state": "read",
  "read_state": "read",
  "busy": false,
  "active_turn_id": "",
  "status_cursor": 0,
  "update_cursor": 0,
  "read_cursor": 0
}
```

Some fields are omitted when empty, especially `worktree`, `todos`, and token
usage. `remote_control_bound` is `true` only for the session bound by `/rc`.
A session bound by an IM channel conversation (QQ / Telegram, section 19) also
carries `"channel_bound": {"platform": "qq"}`; unbound sessions omit the field.
The sidebar shows the same computer icon for either, but `/rc`-specific
behavior keys only on `remote_control_bound`. For a managed-worktree session, top-level `cwd` intentionally remains
the workspace/session-storage root. `worktree.path` is the active absolute
working root used by file, Git, LSP, and path-reference surfaces.

### Token usage

```json
{
  "prompt_tokens": 44100,
  "completion_tokens": 2100,
  "total_tokens": 46200,
  "cache_read_tokens": 0,
  "cache_write_tokens": 0,
  "reasoning_tokens": 0,
  "has_data": true,
  "context_breakdown": {
    "system_prompt": 478,
    "project_rules": 4400,
    "skills": 5200,
    "builtin_tools": 9900,
    "mcp_tools": 2200,
    "conversation": 21000,
    "dynamic_context": 922,
    "has_data": true
  }
}
```

`context_breakdown` is optional and describes the latest provider prompt using
ACECode-side estimates. Its seven category values are proportionally reconciled
to the provider-reported `prompt_tokens`, but remain approximate rather than
provider-tokenizer or billing measurements. Older session metadata and usage
events can omit the object.

### Session event

Server event frames and replayed events use:

```json
{
  "type": "message",
  "seq": 42,
  "timestamp_ms": 1783152000000,
  "replayed": false,
  "session_id": "session-id",
  "workspace_hash": "abc123",
  "payload": {}
}
```

`payload.session_id`, `payload.workspace_hash`, and `payload.cwd` are injected
when known.

`replayed` is delivery provenance: it is `false` for live session events and
`true` for copies replayed from the event ring on reconnect. It is not added to
the stored event payload. Clients must require explicit `false` before applying
side effects such as an AI theme installation; history and catch-up frames only
update their transcript presentation.

---

### Embedded frontend encoding and caching

Embedded frontend resources negotiate gzip using `Accept-Encoding`. Compressed
responses include `Content-Encoding: gzip` and `Vary: Accept-Encoding`; clients
without gzip support (including explicit `gzip;q=0`) receive the original bytes
with the same content type and cache policy. SPA fallback follows the same rule.
Development `--static-dir` resources continue to be read from disk on each request.

Every static response carries a strong `ETag`. Embedded resources hash their
stored bytes once per process; the gzip representation appends `-gzip` so the
two representations a browser keeps under `Vary: Accept-Encoding` revalidate
independently. `--static-dir` resources derive the tag from file size and
modification time. A request whose `If-None-Match` matches (weak comparison,
`W/` prefix ignored, `*` accepted) receives `304 Not Modified` with no body and
the same `ETag`, `Cache-Control`, `Vary` and `Referrer-Policy` headers.

Cache policy depends on the path. Vite output under `/assets/` is named by
content hash, so it is served with `Cache-Control: public, max-age=31536000,
immutable`; a `?v=` query keeps the same immutable policy for any path.
Everything else (`index.html`, icons, themes, SPA fallback) is `no-cache`, which
makes browsers revalidate with the `ETag` on every navigation and skip the
download when nothing changed.

## 3. HTTP Endpoint Index

| Method | Path | Purpose |
|---|---|---|
| GET | `/api/health` | daemon liveness and capabilities |
| GET | `/api/model-pool-status` | model pool load snapshot |
| GET | `/api/usage` | token usage aggregation |
| GET | `/api/history` | input history by cwd |
| POST | `/api/history` | append input history |
| GET | `/api/workspaces` | list registered workspaces |
| POST | `/api/workspaces` | register cwd as workspace |
| PUT | `/api/workspaces/order` | persist visible workspace order |
| PUT | `/api/workspaces/:hash` | save the Edit Project dialog: name, icon, additional folders |
| DELETE | `/api/workspaces/:hash` | remove a local project from the list (hide; no files deleted) |
| POST | `/api/workspaces/pick-folder` | desktop native folder picker |
| GET | `/api/projects/defaults` | new-project default parent directory |
| POST | `/api/projects` | create and register a new project directory |
| POST | `/api/open-in-explorer` | open a folder or reveal a file in the OS file manager |
| GET | `/api/workspaces/:hash/draft` | read the workspace's single new-session draft |
| PUT | `/api/workspaces/:hash/draft` | replace the new-session draft without creating a session |
| DELETE | `/api/workspaces/:hash/draft` | clear only a matching submitted new-session draft |
| POST | `/api/workspaces/:hash/draft/attachments` | store pasted text for the new-session draft |
| GET | `/api/workspaces/:hash/draft/attachments/:attachment_id/blob` | download a new-session draft attachment |
| GET | `/api/workspaces/:hash/sessions` | list sessions in workspace; `limit=N` returns `{sessions,total,total_exact,has_more}` |
| POST | `/api/workspaces/:hash/sessions` | create workspace session |
| POST | `/api/workspaces/:hash/sessions/:id/resume` | resume workspace session |
| DELETE | `/api/workspaces/:hash/sessions/:id?purge=1` | permanently delete archived workspace session |
| PUT | `/api/workspaces/:hash/sessions/:id/archive` | archive workspace session |
| DELETE | `/api/workspaces/:hash/sessions/:id/archive` | unarchive workspace session |
| PUT | `/api/workspaces/:hash/sessions/:id/title` | set session title |
| GET | `/api/workspaces/:hash/sessions/:id/draft` | read composer draft |
| PUT | `/api/workspaces/:hash/sessions/:id/draft` | write composer draft |
| DELETE | `/api/workspaces/:hash/sessions/:id/todos` | clear session todos |
| GET | `/api/workspaces/:hash/opencode-import` | preview opencode import |
| POST | `/api/workspaces/:hash/opencode-import` | start opencode import job |
| GET | `/api/workspaces/:hash/opencode-import/:job_id` | poll opencode import job |
| GET | `/api/workspaces/:hash/pinned-sessions` | list pinned session ids |
| PUT | `/api/workspaces/:hash/pinned-sessions` | set pinned session ids |
| GET | `/api/no-workspace/pinned-sessions` | list pinned no-workspace task ids |
| PUT | `/api/no-workspace/pinned-sessions` | set pinned no-workspace task ids |
| GET | `/api/pinned-sessions/order` | read global cross-scope pin order |
| PUT | `/api/pinned-sessions/order` | set global cross-scope pin order |
| POST | `/api/session-batch` | pin/unpin/archive/unarchive/read/unread many sessions at once |
| GET | `/api/sessions` | compatibility session list |
| GET | `/api/desktop-office?session=<id>&workspace=<hash>` | recent five offices and selected root/agent runtime snapshot |
| GET | `/api/session-search/sessions?q=...&limit=N&cursor=...&request_id=...` | incremental global session catalog page |
| GET | `/api/session-search/user-messages?q=...&limit=N&request_id=...` | advance one bounded visible-user-message search batch |
| POST | `/api/session-search/requests/:request_id/cancel` | cancel/pause an incremental global search |
| POST | `/api/sessions` | compatibility session create |
| POST | `/api/sessions/:id/resume` | compatibility session resume |
| DELETE | `/api/sessions/:id` | destroy active session |
| DELETE | `/api/sessions/:id?purge=1` | permanently delete archived or sub-agent session |
| PUT | `/api/sessions/:id/archive` | archive compatibility session |
| DELETE | `/api/sessions/:id/archive` | unarchive compatibility session |
| PUT | `/api/sessions/:id/title` | set compatibility session title |
| GET | `/api/sessions/:id/draft` | read compatibility draft |
| PUT | `/api/sessions/:id/draft` | write compatibility draft |
| DELETE | `/api/sessions/:id/todos` | clear compatibility todos |
| GET | `/api/sessions/:id/messages` | transcript snapshot or event replay |
| GET | `/api/sessions/:id/runtime` | in-memory busy state and event cursor (live-state watchdog probe) |
| GET | `/api/sessions/:id/trajectory` | paged durable session trajectory and legacy projection |
| POST | `/api/sessions/:id/export-markdown` | open Save As and export the visible transcript as Markdown |
| POST | `/api/sessions/:id/messages` | queue user input |
| POST | `/api/sessions/:id/turn/steer` | append input to the matching active turn |
| POST | `/api/sessions/:id/turn/interrupt` | interrupt the matching active turn and start a priority replacement turn |
| POST | `/api/sessions/:id/turn/steer/send-now` | promote a not-yet-read steer to a priority turn and interrupt the active turn |
| POST | `/api/sessions/:id/turn/steer/withdraw` | withdraw a not-yet-read steer from the active turn |
| POST | `/api/sessions/:id/questions/interject` | resolve a pending AskUserQuestion with a free-form message and continue the same turn |
| POST | `/api/sessions/:id/attachments` | upload a session snapshot, create a Desktop source reference, or import a new-session draft attachment |
| GET | `/api/sessions/:id/attachments/:attachment_id/blob` | download attachment bytes |
| POST | `/api/sessions/:id/commands` | run daemon builtin slash command |
| POST | `/api/sessions/:id/side-question` | run isolated one-turn `/btw` question |
| POST | `/api/sessions/:id/follow-up-prompt` | generate one tool-free composer suggestion for a completed turn |
| POST | `/api/sessions/:id/side-chat/send` | send a side chat message to the main session (steer or new turn) |
| PUT | `/api/sessions/:id/expert` | switch the active session expert for subsequent turns |
| DELETE | `/api/sessions/:id/expert` | clear the persisted/UI expert binding without rebuilding live context |
| GET | `/api/experts` | list expert components for a workspace |
| POST | `/api/experts` | create a managed global expert component |
| GET | `/api/experts/capabilities` | list sanitized expert capability choices |
| GET | `/api/experts/:id` | read one expert component |
| GET | `/api/experts/:id/avatar` | read a contained expert avatar image, optionally for a fixed state |
| PUT | `/api/experts/:id` | update a managed global expert component |
| DELETE | `/api/experts/:id` | delete a managed global expert component |
| GET | `/api/sessions/:id/permissions` | read session permission mode |
| PUT | `/api/sessions/:id/permissions` | set session permission mode |
| GET | `/api/sessions/:id/model` | read session model state |
| POST | `/api/sessions/:id/model` | switch session model |
| POST | `/api/sessions/:id/reasoning` | set or reset session reasoning effort for the next model request |
| POST | `/api/sessions/:id/model/reload` | force reload the selected saved-model profile for one active session |
| POST | `/api/sessions/:id/fork` | fork a transcript prefix |
| POST | `/api/sessions/:id/file-checkpoints/:message_id/restore` | restore files to checkpoint |
| GET | `/api/sessions/:id/background-tasks` | list the session's background commands and background subagents |
| GET | `/api/sessions/:id/background-tasks/:task_id/output` | tail of a background command's output |
| POST | `/api/sessions/:id/background-tasks/:task_id/stop` | stop a running background task |
| POST | `/api/sessions/:id/background` | move the running foreground command / subagent wait to the background |
| GET | `/api/sessions/:id/outputs` | files the conversation produced (documents, spreadsheets, images) |
| GET | `/api/files` | list directory |
| GET | `/api/files/content` | read text file |
| GET | `/api/files/blob` | read previewable binary file |
| POST | `/api/files/export` | save a file through the native Save as dialog |
| GET / PUT | `/api/files/editable` | read or safely save a Desktop workspace text file |
| GET | `/api/fs/roots` | browsable roots for the Web path picker |
| GET | `/api/fs/list` | list any absolute directory for the Web path picker |
| GET | `/api/git/info` | git repo info for a workspace |
| POST | `/api/git/checkout` | switch branch (stash-aware) |
| GET | `/api/git/changes` | working tree changes vs base |
| GET | `/api/git/diff` | single-file patch vs base |
| GET | `/api/commands` | list slash commands |
| GET | `/api/skills/root` | resolve effective skills directory |
| GET | `/api/skills` | list registered skills |
| PUT | `/api/skills/:name` | enable or disable skill |
| GET | `/api/skills/:name/body` | read `SKILL.md` body |
| GET | `/api/hooks` | list hooks snapshot |
| POST | `/api/hooks/refresh` | reload hook registry |
| POST | `/api/hooks/:id/trust` | trust hook |
| POST | `/api/hooks/:id/disable` | disable hook |
| POST | `/api/hooks/:id/enable` | enable hook |
| GET | `/api/models` | list saved model profiles |
| POST | `/api/models` | add saved model profile |
| POST | `/api/config/model-order` | persist saved model order (`{names: string[]}`) |
| PUT | `/api/models/:name` | update saved model profile |
| DELETE | `/api/models/:name` | remove saved model profile |
| POST | `/api/models/probe` | probe provider model ids |
| POST | `/api/models/reasoning/refresh` | queue background reasoning metadata refresh for saved models |
| POST | `/api/models/test` | test an unsaved model with a short conversation |
| GET | `/api/models/catalog` | read local model catalog summary and reviewed recommendations |
| GET | `/api/models/catalog/:provider_id` | search one provider's local model catalog |
| POST | `/api/models/catalog/refresh` | explicitly refresh the models.dev registry when network refresh is enabled |
| GET | `/api/config/default-model` | read default saved model name |
| POST | `/api/config/default-model` | set default saved model |
| GET | `/api/copilot/auth` | read Copilot auth status |
| DELETE | `/api/copilot/auth` | delete saved GitHub token |
| POST | `/api/copilot/auth/device` | start GitHub device flow |
| POST | `/api/copilot/auth/device/poll` | poll device flow |
| GET | `/api/grok/auth` | read Grok Coding Plan auth status |
| DELETE | `/api/grok/auth` | delete saved xAI OAuth credentials |
| POST | `/api/grok/auth/device` | start xAI device flow |
| POST | `/api/grok/auth/device/poll` | poll one xAI device-flow tick |
| GET | `/api/ui/onboarding/desktop` | read Desktop guided-tour status |
| POST | `/api/ui/onboarding/desktop/dismiss` | dismiss the current Desktop guided-tour version |
| GET | `/api/config/ui-preferences` | read UI preferences |
| GET | `/api/config/desktop-multi-instance` | read global desktop multi-instance preference |
| PUT | `/api/config/desktop-multi-instance` | save global desktop multi-instance preference |
| PUT | `/api/config/ui-preferences` | write UI preferences |
| GET | `/api/themes` | built-in and dynamic workshop catalogues plus installed local AI themes |
| GET | `/api/themes/workshop/<key>/thumbnail` | authenticated proxy for a public workshop PNG thumbnail |
| POST | `/api/themes/first-run` | legacy compatibility: durably claim the one-time National Day startup attempt |
| POST | `/api/themes/import/preview` | validate a raw theme ZIP and return a read-only preview |
| POST | `/api/themes/import?sha256=<digest>` | import the same previewed ZIP after confirmation |
| GET | `/api/themes/job` | current theme download progress |
| POST | `/api/themes/job/cancel` | cancel the current theme download |
| GET | `/api/themes/<id>` | verified locally installed theme definition |
| POST | `/api/themes/<id>/install` | download a theme after size/hash confirmation |
| GET | `/api/themes/<id>/images/<kind>` | theme thumbnail or installed background |
| GET | `/api/themes/<id>/sounds/<name>` | an installed theme's declared `sound-<name>.ogg` recording (`audio/ogg`, not cached; 404 when the theme does not declare it) |
| POST | `/api/themes/<id>/export` | prepare a custom theme ZIP, optionally saving through the native picker |
| GET | `/api/themes/exports/<job_id>` | read theme export/packing progress |
| POST | `/api/themes/exports/<job_id>/cancel` | cancel the matching theme export job |
| GET | `/api/themes/exports/<job_id>/download` | download the completed, verified theme ZIP |
| DELETE | `/api/themes/<id>` | delete a custom theme and update the active preference when needed |
| GET | `/api/config/ui-locale` | read Desktop/WebUI locale preference |
| PUT | `/api/config/ui-locale` | write Desktop/WebUI locale preference |
| GET | `/api/config/custom-instructions` | read custom instructions |
| PUT | `/api/config/custom-instructions` | write custom instructions |
| GET | `/api/config/connectors` | read connector settings |
| GET | `/api/config/image-generation` | read sanitized image generation settings |
| GET | `/api/config/speech-recognition` | read authenticated speech settings, including the editable key |
| PUT | `/api/config/speech-recognition` | save speech settings and cancel active recognition |
| POST | `/api/config/speech-recognition/test` | test a draft configuration with one second of silent WAV |
| GET | `/api/speech-recognition` | read speech availability without connection details or credentials |
| POST | `/api/speech-recognition/transcriptions/<id>` | recognize a bounded raw PCM16 WAV body |
| DELETE | `/api/speech-recognition/transcriptions/<id>` | cancel a recognition request |
| GET | `/api/config/computer-use` | read computer control availability and pointer appearance |
| PUT | `/api/config/computer-use` | partially update the switch or pointer appearance |
| POST | `/api/config/computer-use/permissions` | explicitly request one macOS system permission |
| GET | `/api/config/summary-generation` | read summary-model override and available models |
| PUT | `/api/config/summary-generation` | save summary-model override for automatic session titles |
| PUT | `/api/config/image-generation` | save image generation settings and refresh the tool |
| POST | `/api/config/image-generation/test` | explicitly generate one standard-quality test image |
| GET | `/api/config/memory` | read memory settings (use memory, memory summarization, summary model) |
| PUT | `/api/config/memory` | patch memory settings; persists `config.json` and applies to this daemon's memory runtime |
| GET | `/api/memory?workspace=<hash>` | list global and workspace memory entries plus memory-summarization status |
| GET | `/api/memory/:scope/:name?workspace=<hash>` | read one entry with body |
| PUT | `/api/memory/:scope/:name?workspace=<hash>` | edit one entry (redacted, marked manual) |
| DELETE | `/api/memory/:scope/:name?workspace=<hash>` | delete one entry and record a tombstone |
| POST | `/api/memory/reset` | clear one scope (entries, index, inbox, archive) |
| GET | `/api/config/tool-rewrites` | read tool rewrite settings plus the built-in tool catalog |
| PUT | `/api/config/tool-rewrites` | replace tool rewrite settings, persist `tool_rewrites.json`, apply live |
| GET | `/api/agent-browser/top-sites?limit=N` | Agent Browser New Tab「推荐」: most visited sites (local clients only) |
| POST | `/api/agent-browser/visits` | record one Agent Browser page visit or its later title/favicon (local clients only) |
| POST | `/api/agent-browser/top-sites/dismiss` / `restore` | hide / un-hide one suggested site (local clients only) |
| GET | `/api/config/tool-preamble` | read the concrete progress text switch (work mode) |
| PUT | `/api/config/tool-preamble` | set the concrete progress text switch in `config.json`, push to active sessions |
| GET | `/api/config/image-compression` | read the 压缩图片 switch |
| PUT | `/api/config/image-compression` | set the 压缩图片 switch in `config.json`; applies to the next model request |
| GET | `/api/config/inline-visuals` | read the 可视化图表 switch |
| PUT | `/api/config/inline-visuals` | set the 可视化图表 switch in `config.json`; applies to the next system prompt |
| GET | `/api/config/sandbox` | read sandbox switches, filesystem lists, defaults and platform probe |
| PUT | `/api/config/sandbox` | save sandbox switches / lists to `config.json`, push to active sessions |
| GET | `/api/security/exec-rules` | list `<data_dir>/rules/*.rules` (managed files editable) |
| PUT | `/api/security/exec-rules` | rewrite the managed rules files, reload rules in active sessions |
| GET | `/api/security/audit` | audit log page with filters and cursor pagination |
| GET | `/api/security/audit/summary` | audit counts and recently blocked paths |
| GET | `/api/security/audit/export` | audit log as a JSONL or CSV attachment |
| DELETE | `/api/security/audit` | clear the audit log |
| PUT | `/api/config/connectors` | write connector settings |
| GET | `/api/config/default-permission-mode` | read default permission mode |
| PUT | `/api/config/default-permission-mode` | write default permission mode |
| GET | `/api/config/remote-web` | read remote Web proxy state and connection URLs |
| PUT | `/api/config/remote-web` | enable or disable remote Web mode |
| GET | `/api/config/upgrade` | read update service config |
| PUT | `/api/config/upgrade` | write update service config |
| GET / PUT | `/api/config/toolchains` | read or save Python, Node.js and C# directories |
| POST | `/api/config/toolchains/detect` | detect installed toolchain directories again |
| GET | `/api/console/config` | terminal configuration and launch-probe results |
| POST | `/api/console/config/detect` | probe and save the default terminal again |
| GET | `/api/config/data-dir` | current data directory, migration and backup status |
| POST | `/api/config/data-dir/migrate` | copy data to an empty directory; restart required |
| GET | `/api/config/data-dir/migration` | poll the background migration |
| POST | `/api/config/data-dir/cleanup` | keep or delete the previous data directory |
| POST | `/api/dialog/pick-folder` | select a folder without registering a project |
| POST | `/api/dialog/pick-file` | select a terminal program |
| GET | `/api/update/status` | check update availability |
| POST | `/api/update/start` | start explicit WebUI update job |
| GET | `/api/update/job` | read latest WebUI update job |
| GET | `/api/update/jobs/:id` | poll one WebUI update job |
| POST | `/api/update/jobs/:id/cancel` | cancel one WebUI update job before installation |
| GET | `/api/mcp` | read MCP config |
| GET | `/api/mcp/schema` | read MCP configuration JSON schemas |
| PUT | `/api/mcp` | validate, persist, and apply MCP config |
| POST | `/api/mcp/toggle` | validate and persist one server's enabled state |
| POST | `/api/mcp/reload` | validate/recover persisted config and apply it |
| GET | `/api/feedback/desktop/recent-sessions` | list sessions for feedback attachment |
| POST | `/api/feedback/desktop` | package and upload desktop feedback |
| GET | `/api/pty/shells` | list console shell choices |
| GET | `/api/pty` | list PTY sessions |
| POST | `/api/pty` | create PTY session |
| DELETE | `/api/pty/:id` | remove PTY session |
| POST | `/api/pty/:id/resize` | resize PTY |
| POST | `/api/pty/:id/title` | set PTY title |
| PUT | `/api/console/config` | write console shell config |
| GET | `/api/channels` | IM channel snapshots (QQ, WeChat, Feishu, DingTalk, Telegram, Discord, LINE); local clients only |
| POST | `/api/channels/:platform/enabled` | connect or disconnect a channel immediately |
| PUT | `/api/channels/:platform/credentials` | validate, then save channel credentials |
| POST / DELETE | `/api/channels/:platform/bind` | start or cancel scan-to-configure (QQ, WeChat) |
| POST | `/api/channels/:platform/owner-link` | one-time owner link (Telegram) or 6-digit owner code (Feishu, DingTalk, Discord, LINE) |
| POST | `/api/channels/telegram/remove-webhook` | remove a Telegram webhook after confirmation |
| POST | `/api/channels/:platform/requests/:id/{approve,reject}` | decide a pairing request |
| DELETE | `/api/channels/:platform/access/:principal` | revoke a contact or group |

`POST /api/config/model-order` requires authentication and a complete permutation of
the current model names returned by `GET /api/models`. Legacy profiles belonging
to disabled providers retain their positions and contents. It returns `{"ok": true}` on success, `400` for
malformed JSON or a non-string-array `names`, `409 MODEL_ORDER_CONFLICT` for a
duplicate, missing, or unknown name, and `500 PERSIST_FAILED` if saving fails.
The mutation reorders the latest profiles atomically without changing their
contents or `default_model_name`. `GET /api/models` returns the persisted order;
an unchanged order performs no write.

---

## 4. Health, Usage, and History

### `GET /api/health`

Returns daemon identity and frontend capabilities. Loopback requests remain
token-optional; non-loopback requests must authenticate before any metadata is
returned.

```json
{
  "guid": "ea86842a-fb1c-4242-b2b4-74be2aff1058",
  "pid": 18204,
  "port": 12399,
  "version": "0.5.10",
  "cwd": "C:/repo",
  "uptime_seconds": 423,
  "desktop_managed": true,
  "desktop_protocol_version": 1,
  "notifications": {
    "enabled": true,
    "on_question": true,
    "on_completion": true,
    "suppress_when_focused": true
  },
  "features": {
    "completed_turn_self_heal": {"enabled": true}
  },
  "console": {
    "available": true,
    "backend": "conpty"
  }
}
```

`desktop_managed` is `true` only for the daemon generation started for the
native Desktop. `desktop_protocol_version` is the attach/reuse compatibility
contract; Desktop verifies it together with the runtime identity before
reusing a process.

`console.backend` is `conpty`, `winpty`, `pipe`, or `posix`.

### `GET /api/model-pool-status`

No auth requirement. Used by the chat UI to show model pool load. A configured
provider `model` is pool-backed only when it exactly equals a returned
`modelPoolName`; no naming prefix is required.

```json
{
  "models": [
    {
      "modelPoolName": "DeepSeek-V4-Flash",
      "usageRate": 42,
      "maxWindowTokens": 150000,
      "effectiveContextWindow": 120000
    }
  ]
}
```

### `GET /api/usage`

Query parameters:

- `days`: optional, defaults to `30`
- `workspace`: optional workspace hash; `__local__` means daemon cwd
- `timezone_offset_minutes`: optional JS `Date#getTimezoneOffset()` value

Returns usage summary, daily buckets, model buckets, workspace buckets, and
metadata. Durable usage is forward-only; older session metadata is not
backfilled.

### `GET /api/history?cwd=<cwd>&max=N`

Returns an array of input history strings for `cwd`.

### `POST /api/history`

Body:

```json
{"text":"last prompt"}
```

Appends to the daemon cwd input history. Returns `204`. If input history is
disabled, the write is silently ignored.

---

## 5. Workspaces and Sessions

### `GET /api/desktop-office?session=<id>&workspace=<hash>`

只读桌面办公室快照，使用通用鉴权/CORS，响应 `Cache-Control: no-store`。
`session` 与 `workspace` 可省略；默认选最近办公室。选择子会话时返回它所属的根办公室。
显式选择不存在或已归档会话返回 `404`，并在可用时附带当前 `offices`。

绑定专家的条目保留 `expert_id`、`expert_member_id` 与 `expert` 展示信息，其中 `expert.avatar_identity` 是目录头像、子 agent 和办公室共用的稳定像素身份。引用式专家团成员使用被引用专家身份，主会话使用主理人身份；内嵌成员使用团队 ID 与成员 ID 的组合。`expert.avatar_url` 继续指向用户配置的头像（没有配置时为空）。这些字段不包含本地文件路径。

```json
{
  "offices": [{"id":"root","workspace_hash":"abc123","title":"Review", "last_user_message_at":"2026-10-06T10:00:00Z"}],
  "selected": {"id":"root","active":true,"status":"idle","last_turn_outcome":"completed","activity":{"known":true,"busy":false,"outcome":"completed","phase":"","tool":"","seq":42}},
  "agents": [{"id":"root"}],
  "activities": [{"id":"other","workspace_hash":"abc123","title":"等待30秒","status":"idle","attention_state":"unread","activity":{"outcome":"completed","reply":"30 秒已过。"}}],
  "complete": true,
  "connected": true
}
```

`offices` 最多五个：跨工作区按 `last_user_message_at` 降序，排除归档、子会话和没有真实用户输入的会话。打开会话、模型输出、隐藏提示及 agent 间消息不推进此时间；旧记录从 JSONL 逆向读取后缓存。目录或旧记录仍在加载时 `complete=false`，客户端可继续读取；空目录返回空数组及 `selected:null`。分叉继承保留消息的原始时间。

`selected` 和 `agents` 只传身份、标题、所属工作区、真实状态和当前上下文用量等展示字段；不含输入草稿、原始工具参数、工具输出或历史正文（下文 `activity.detail` / `activity.text` 两个有界展示片段除外）。`agents` 包含根会话和当前 daemon 已装载的直属/网状子会话；网状子会话的 `parent_session_id` 是树根，`agent_path` 保留实际层级。已成功结束的子会话可仍出现在原始快照中，由桌宠投影立即离座。标题/摘要限 240 UTF-8 字节。

`activities` 是陪伴宠物（回形针 / rover / 鲸鱼娘）的会话卡片来源，复刻 Codex Mini：所有正在运行的主会话，加上结果尚未读过（侧栏同一份 `attention_state=unread`）的主会话，跨工作区、不限最近五个；先按忙碌标志和缓存的已读记录筛选，只有入选的会话才完整序列化。当前 daemon 已不在内存的会话只从最近五个里补未读结果。条目字段同 `offices`，另带 `attention_state` 和 `activity`；客户端按 `last_user_message_at` 排序、最多显示 12 张。打开会话（`mark_session_read`）后该会话的完成卡片随下一次快照消失。`404` 响应同样附带 `activities`。

运行中条目的 `activity` 来自事件分发器维护的紧凑状态，不依赖有限的重放缓冲：`known`、`busy`、`turn_id`、`outcome`、`phase`、`label`、`tool`、`detail`、`text`、`reply`、`seq`、`compact_id`、`transfers`。`reply` 是最近一条助手正文回复的前 240 UTF-8 字节（工具消息不算），回合结束后保留、新回合开始清空，供完成卡片显示。待授权/待回答优先于工具和模型阶段；`outcome` 保留 `completed`/`aborted`/`error` 差别。`transfers` 最多保留 16 个带序号的 agent 间交接标识，不含消息内容。持久化 `last_turn_outcome` 使恢复后的完成主会话继续显示睡眠状态。

流式正文会把 `phase` 置为 `responding`（默认「用于编程」模式下服务端不发该进度，由 token 事件推断），推理片段对应 `reasoning`，`text` 是本段正文或推理最后不超过 160 UTF-8 字节的尾巴，换阶段或开始工具调用即清空；`detail` 是正在运行工具的一行调用预览（`display_override`，为空时取 `command_preview`），最多 120 字节，工具结束清空。桌宠页面在两次快照之间直接用 WebSocket 的 `token` / `reasoning` 事件按 `seq` 叠加实时文字（约 150ms 节流），快照追上后以快照为准。

`token_usage` 是最近请求上下文统计，配合 `context_window` 计算文件堆厚度；未知窗口不伪造比例。休眠会话可通过已有 model 端点补充窗口大小。该端点不会发起模型请求或改变会话运行状态。

### `GET /api/workspaces`

Returns `Workspace[]`. The registry is scanned before listing. If no registry
is available, the compatibility workspace may be returned.

When a workspace order has been saved, visible workspaces follow that order;
new workspaces are appended. Hidden workspaces retain their saved positions
without appearing in this response. The same order is used by the Desktop
workspace bridge and survives daemon restarts and loopback port changes.

### `PUT /api/workspaces/order`

Body and successful response:

```json
{"hashes":["workspace-hash-b","workspace-hash-a"]}
```

The request must contain every currently visible workspace hash exactly once.
The registry atomically saves the order in `projects/workspace_order.json`;
existing workspace markers and sessions are unchanged. Hidden hashes keep
their saved slots when visible workspaces are reordered. Errors:

- `400` malformed JSON, missing/non-array `hashes`, non-string, empty or duplicate hashes
- `409` `WORKSPACE_ORDER_CONFLICT` for unknown/hidden hashes or an incomplete visible list
- `500` save failure; the previously confirmed order remains intact
- `503` workspace registry unavailable

### `POST /api/workspaces`

Body:

```json
{"cwd":"C:/repo"}
```

Registers the cwd and returns `201` plus a `Workspace`. Errors:

- `400` bad JSON or missing `cwd`
- `503` workspace registry unavailable

`Workspace` objects from `GET`/`POST`/`PUT` also carry the Edit Project
fields: `icon` (`{"id","color"}` or `null` = default folder icon) and
`extra_folders` (absolute paths, possibly empty).

### `PUT /api/workspaces/:hash`

Saves the Web UI "Edit Project" dialog. The main folder (`cwd`) cannot be
changed. Body:

```json
{"name":"acecode","icon":{"id":"music","color":"blue"},"extra_folders":["D:/shared/lib"]}
```

`name` is required and trimmed. Omitting `icon` or `extra_folders` keeps the
stored value; `"icon": null` restores the default icon. `id`/`color` are opaque
keys from the Web icon table (`[a-z0-9-]`). Every additional folder must be an
existing absolute directory; the main folder and duplicates (case/separator
insensitive on Windows) are dropped silently; at most 32. The marker is re-read
from disk before writing so fields saved by another process (Desktop vs daemon
registry caches) survive. Returns `200` plus the updated `Workspace`. Errors:

- `400` `BAD_REQUEST` bad JSON, empty name, invalid icon, relative/missing folder
- `404` `WORKSPACE_NOT_FOUND` unknown hash or a marker whose `cwd` does not hash to `:hash`
- `500` `PERSIST_FAILED`
- `503` workspace registry unavailable

Additional folders take effect from the next agent turn: the system prompt's
`# Environment` lists them, file tools accept paths inside them, and the bash
sandbox adds them as writable roots. Sessions with a write boundary (worktree /
LOOP / inherited) keep folders that overlap the main checkout read-only.

### `DELETE /api/workspaces/:hash`

Web-mode counterpart of the Desktop `aceDesktop_removeWorkspace` bridge: sets
`desktop_visible=false` in the marker. Sessions, the marker's other fields and
all project files are kept. Returns `{"ok":true}`; `404` for unknown hashes.

### `POST /api/workspaces/pick-folder`

Desktop-only native folder picker. Returns a registered `Workspace` or `null`
when the user cancels. Errors:

- `501` native folder picker unavailable
- `503` registry or callback unavailable

### `GET /api/projects/defaults`

Returns the default parent used by the new-project modal:

```json
{"parent_dir":"C:/Users/me/.acecode/workspaces"}
```

This user-source root is a sibling of the internal hash-indexed
`<data-dir>/projects` metadata directory. The endpoint does not create the
directory; default project creation creates it on demand.

### `POST /api/projects`

Creates one empty child directory, registers that child as a visible workspace,
and returns `201` with the normal `Workspace` fields plus creation details.

```json
{
  "name": "demo-api",
  "parent_dir": "C:/Users/me/.acecode/workspaces",
  "project_dir": "C:/Users/me/.acecode/workspaces/demo-api"
}
```

`parent_dir` is optional. When omitted or empty, ACECode uses the parent from
`GET /api/projects/defaults` and creates that default parent on demand. A custom
parent must already exist, be absolute, and be a directory.

The returned object includes `hash`, `cwd`, `name`, `available`,
`requested_name`, `directory_name`, `parent_dir`, `project_dir`, and
`sanitized`. The cross-platform directory-name contract:

- trims surrounding ASCII whitespace and trailing dots/spaces;
- replaces ASCII control characters and `<>:"/\\|?*` with `-`;
- appends `-project` to Windows reserved device names such as `CON`, `NUL`,
  `COM1`, or a reserved base followed by an extension;
- truncates to 60 Unicode code points without splitting a code point;
- falls back to `project` when normalization would otherwise leave an empty or
  dot-only component.

Creation never adopts or overwrites an existing path. Errors:

- `400 PROJECT_BAD_REQUEST` malformed JSON or field types
- `400 PROJECT_NAME_REQUIRED` empty project name
- `400 PROJECT_PARENT_ABSOLUTE_REQUIRED` relative custom parent
- `400 PROJECT_PARENT_NOT_FOUND` missing custom parent
- `400 PROJECT_PARENT_NOT_DIRECTORY` custom parent is not a directory
- `409 PROJECT_ALREADY_EXISTS` target file or directory already exists
- `500 PROJECT_CREATE_FAILED` default-parent or child-directory creation failed
- `503` workspace registry unavailable

### `POST /api/open-in-explorer`

Body:

```json
{"path":"C:/repo"}
```

Opens an absolute directory in Explorer/Finder/xdg-open, or reveals an existing
regular file in its containing folder. Windows Explorer and macOS Finder select
the file; Linux opens the containing directory because there is no portable
freedesktop selection protocol. The desktop callback accepts any existing local
absolute regular file or directory that the daemon process can access; it does
not restrict the target to registered workspaces, the daemon cwd, or
ACECode-managed roots. Empty, relative, missing, and unsupported target types
remain invalid. Returns `{"ok":true}`. Returns `501` when the daemon has no
desktop callback.

On Windows the call runs on its own STA thread: files use
`SHOpenFolderAndSelectItems` (falling back to `explorer.exe /select` only when
it fails), directories use `ShellExecuteEx`. It returns once the Explorer
window is visible (typically 0.3–0.6 s, capped at about 2 s) and raises that
window if it opened behind the window that was in front when the request
started.

### `GET /api/workspaces/:hash/sessions?archived=1`

Returns `SessionSummary[]` for a workspace. Without `archived=1`, active and
unarchived disk sessions are returned. With `archived=1`, only archived disk
sessions are returned.

Listing reads session metadata only; it does not open JSONL transcripts to
backfill legacy summary or count fields.

`limit=N` (positive integer, capped at 10000) returns a compact page instead of
the raw array:

```json
{
  "sessions": [ { "id": "..." } ],
  "total": 42,
  "total_exact": true,
  "has_more": false
}
```

`sessions` is the newest N rows, ordered by `updated_at` descending — the same
order the unlimited list uses. Omitting `limit`, or passing `0`, keeps the
original array body and never adds the paging fields.

`updated_at` records persisted conversation activity. Resuming, switching, or
closing a session and saving metadata such as titles or model preferences do
not advance it; appending or replacing conversation history does.

A bounded page stops reading the project directory as soon as it has enough
rows, so it does not learn the exact post-filter count:

- `total_exact: true` — the whole directory was read; `total` is the exact
  count after archive and parent filters.
- `total_exact: false` — reading stopped early; `total` is an upper bound
  derived from the number of candidate metadata files (it still counts
  archived rows, sub-agent sessions, and rows already reported as active).
- `has_more` is authoritative in either case. **Clients deciding whether a
  workspace still has unloaded rows must read `has_more`**, not compare
  `sessions.length` against `total` — that comparison is wrong whenever
  `total_exact` is false.

This bound keeps legacy flat-list callers cheap: a workspace with
1400 sessions opens ~13 metadata files instead of all 1400, which on Windows is
the difference between roughly 7 s and a few ms per request.

### `GET /api/workspaces/:hash/session-sidebar` and `GET /api/session-sidebar`

The second route lists no-workspace sessions only. These opt-in sidebar routes
exclude archived sessions and background subagents, group scheduled executions
by their persisted `loop_execution.loop_id`, then paginate root items. Existing
flat session-list routes retain their original protocol.

- `limit=N`: maximum root items (0/omitted means all). History rows do not count.
- `expanded`: URL-encoded JSON array of stable node keys whose complete children
  should be included, e.g. `["loop:task-id"]`.
- `reveal=session-id`: include the root containing this session, increasing the
  requested root page when necessary, and expand that root for a history target.

Response: `{sessions, total, total_exact:true, has_more, sidebar_tree:true,
visible_roots}`. `total` and `visible_roots` count non-pinned roots, while
`sessions` is a flat array containing those roots, the children of expanded
roots, and separately pinned rows. Every non-pinned row adds `sidebar_key`,
`sidebar_parent_key` (empty for roots), `sidebar_child_count`, `sidebar_rank`
(within siblings), and `sidebar_expanded`.
Clients must not compare `sessions.length` with root totals.

Automatic group keys use `loop:<task-id>`; manual groups anchored to a detached
scheduled session use `group:<anchor-session-id>`. Real session keys always use
`session:<session-id>`. Every execution, including the newest, is a child.
Group headers are presentation nodes with `sidebar_group:true` and the stable
synthetic `id` `sidebar-group:<sidebar_key>`; never navigate to, subscribe to,
mark read, pin, or archive that ID as a session. Clicking a header only toggles it.
`sidebar_group_name` and `title` contain the task name when available (clients
use a localized scheduled-task fallback otherwise). `sidebar_latest_session_id`
identifies the member selected by newest creation time; its timestamps supply
the header time. A rename or navigation to older history never replaces the
task name. `sidebar_members` contains compact attention snapshots for all members,
including hidden ones, so clients can aggregate subsequent status events while
collapsed. Headers are never busy: unread members produce `unread`, otherwise
`read`, even if a member is running. Metadata parsing is cached by modification
time and size; neither transcripts nor hidden members' full summaries are read.

### `POST /api/workspaces/:hash/session-sidebar` and `POST /api/session-sidebar`

The same query parameters apply. Body:

```json
{"source":"session:older-run","target":"loop:task-id","placement":"inside"}
```

For a batch, replace `source` with `sources`, an ordered nonempty array of
distinct node keys. The entire batch is validated and saved atomically; a stale,
duplicate, selected destination or invalid member rejects the batch without
changing the layout. Relative source order is preserved for all placements.
An invalid `sources` type returns HTTP 409/`SIDEBAR_INVALID_SOURCES`.
The response reveals all moved nodes. The single-source body remains supported.

`placement` is `before`, `after`, or `inside`. Moves remain within the endpoint's
scope. Only a scheduled root with `loop_execution.loop_id` (the alarm marker)
can accept children, including an empty group or a detached scheduled execution.
Ordinary sessions may reorder or become children but cannot become parents.
A group header can only reorder at the root; a child cannot accept children.
Moving a single execution into a scheduled group detaches that execution from
its previous group; future executions still join their task's automatic group.
Dropping onto a detached scheduled root creates a manual group containing that
root's real session and the incoming child. Empty group headers disappear.
Self moves, stale targets, and third-level relationships return HTTP 409 with
`SIDEBAR_TARGET_CHANGED` or `SIDEBAR_TWO_LEVELS_ONLY`. An ordinary destination
parent returns 409/`SIDEBAR_SCHEDULED_PARENT_ONLY`; malformed bodies return 400.
Save failures return 500/`SIDEBAR_SAVE_FAILED`. Successful moves return the new
sidebar page and reveal the destination.

Relationships and sibling order are atomically persisted in the scope's
`sidebar_sessions.json`, separately from task provenance and subagent
`parent_session_id`. An explicit empty parent keeps a detached execution at the
root after reload and future runs. Missing or archived manual anchors promote
their remaining members; removing the newest automatic execution selects the
next member for header time without changing its task identity.
Reading a legacy layout that assigns children to an ordinary session promotes
those children to roots without changing their execution provenance.
Legacy scheduled-session parent keys are projected into manual groups with
the original parent execution included as a child. The next move persists the
canonical relationships and ordering using layout version 2.

### `POST /api/workspaces/:hash/sessions`

Creates a session in the workspace. Body fields are optional:

```json
{
  "model": "saved-model-name",
  "name": "saved-model-name",
  "permission_mode": "default",
  "permissionMode": "default",
  "reasoning_effort": "high",
  "initial_user_message": "hello",
  "auto_start": true,
  "no_workspace": false,
  "noWorkspace": false,
  "session_id": "20261110_083015_4f2a"
}
```

`model` and `name` are aliases. `permission_mode` and `permissionMode` are
aliases. `auto_start` defaults to `false`; it only starts a turn when an
`initial_user_message` is present. `session_id` lets the client choose the new
session's id (8-64 characters of `[A-Za-z0-9_-]`); the Web new-task page uses
it when Agent Browser pages were opened before the first message, so those
pages (owned by that reserved id) belong to the session as soon as it exists.
An invalid id returns `400 INVALID_SESSION_ID`; an id already used by an active
or on-disk session returns `409 SESSION_ID_EXISTS` and never reuses its
transcript. `POST /api/sessions` accepts the same body. Returns:

```json
{
  "session_id": "sid",
  "id": "sid",
  "workspace_hash": "abc123",
  "cwd": "C:/repo"
}
```

Errors include `404` unknown workspace, `409` workspace path unavailable,
`400` invalid permission mode, and `503` session client unavailable.

`reasoning_effort` is optional (`null` inherits the saved model default). A
string must be one of the enabled model's declared efforts; invalid or
unsupported values fail before a session or initial turn is created. The
override belongs to the new session and does not modify the saved model.

### `POST /api/workspaces/:hash/sessions/:id/resume`

Loads an existing disk session into the current daemon registry. Returns
`{"session_id","id","active":true,"workspace_hash","cwd"}`. Errors:

- `404` workspace or session not found
- `409` session is active in another live process, old incompatible PID data,
  or workspace path unavailable
- `503` session client unavailable

Workspace registration controls Desktop visibility, not whether a persisted
session can be opened. An exact 16-hex workspace hash that is absent from the
visible registry may be resolved read-only from
`projects/<hash>/workspace.json`, or from a hash-matching ordinary session
meta in that project directory. This fallback never registers the workspace
or changes `desktop_visible`; `/api/workspaces` therefore remains a list of
visible projects only.

### `DELETE /api/workspaces/:hash/sessions/:id?purge=1`

Permanently deletes an archived session from the specified workspace. The
daemon destroys any lingering in-memory registration, removes the session from
the user-message search index, then removes `<id>.jsonl`, the per-session
`<id>/` persisted-data directory, and `<id>.meta.json` last. Returns `204` only
after cleanup succeeds.

Sub-agent sessions (`spawn_subagent` tasks and every mesh agent of the tree)
have no lifecycle of their own: they cannot be archived or deleted separately
and live and die with their main session. Purging a main session first applies
the same cleanup to each of its child sessions (including children that exist
only in memory), then to the main session itself. A failure stops before the
main session is removed, so the operation stays retryable.

Guard rails and errors:

- `400` when `purge=1` is missing or the session id is invalid
- `404` when the workspace or session does not exist
- `409 {"error":"subagent sessions are deleted together with their main session"}`
  when the target is a sub-agent session; nothing is deleted
- `409 {"error":"session must be archived before permanent deletion"}` when
  the target is not archived
- `409` when the target is unexpectedly busy
- `409 {"error":"subagent session <id> is busy; abort it first"}` when one of
  the main session's child sessions is running a turn; nothing is deleted
- `500` when search-index or file cleanup fails; metadata is retained until
  the other known session data has been removed so the operation remains
  retryable
- `503` session client unavailable

### Global session search

`GET /api/session-search/sessions` reads a daemon-lifetime, per-project catalog
that is prewarmed in the background. It never synchronously rescans the whole
project store. The optional parameters are:

- `request_id`: client-generated id shared by metadata and content calls;
  required for explicit cancellation.
- `q`: server-side title, summary, workspace, id, and fuzzy-title filter.
- `limit`: `1..100`. An empty query is always capped at the 50 most recently
  updated sessions.
- `cursor`: opaque `generation:offset` value returned by a completed page.
  Pagination is offered only after the current catalog generation is complete.

The response uses a search-only DTO rather than the full session serializer:

```json
{
  "sessions": [
    {
      "id": "sid",
      "workspace_hash": "0123456789abcdef",
      "workspaceName": "repo",
      "workspace_cwd": "C:/repo",
      "workspace_visible": false,
      "no_workspace": false,
      "title": "Investigate search",
      "summary": "...",
      "updated_at": "2026-08-20T01:02:03Z"
    }
  ],
  "errors": [],
  "progress": {
    "scanned_projects": 120,
    "total_projects": 15864,
    "generation": 121,
    "complete": false,
    "paused": false
  },
  "next_cursor": null
}
```

The search DTO is limited to identity, display title/summary/time, workspace
navigation fields, and `active`/`busy`. It intentionally omits drafts, todos,
permission state, token usage, transcripts, and other full-session fields.
Clients should render every successful partial page immediately and poll again
while `progress.complete` is false. Once complete, `next_cursor` loads another
stable page. A cursor from an older generation returns
`409 {"error":"SESSION_SEARCH_CURSOR_STALE"}`; restart from the first page.

Workspace visibility and even the presence of `workspace.json` do not control
session inclusion. Workspace hash, name, cwd, and visibility are result
attributes. `no_workspace` sessions use an empty workspace hash. Archived
sessions and records with a non-empty `parent_session_id` are excluded. A
project-level read failure is reported in `errors` without suppressing valid
sessions from other projects.

`GET /api/session-search/user-messages?q=<query>&limit=<1..100>&request_id=<id>`
uses the same global boundary and existing per-project derived indexes. One
call advances only a small project batch with a short wall-clock budget. The
client repeats the call until `progress.complete` and renders accumulated
matches after every response:

```json
{
  "search_match": {
    "kind": "user_message",
    "score": 1200,
    "message_ordinal": 7,
    "snippet": "matching visible user text",
    "attachments": ["design.pdf"]
  }
}
```

The top-level response is:

```json
{
  "matches": [],
  "errors": [],
  "progress": {
    "scanned_projects": 32,
    "total_projects": 15864,
    "complete": false
  }
}
```

Only visible user-message text and attachment names are indexed; full
transcripts, hidden context, assistant messages, and tool results are not
returned. Empty queries return no matches, queries longer than 512 bytes
return `400`, and one failed project index does not block other projects.

`POST /api/session-search/requests/:request_id/cancel` is idempotent. It marks
all metadata/content work for that id cancelled, interrupts SQLite work at its
progress boundary, stops metadata/message enumeration at file or message
boundaries, and pauses catalog prewarming when no other search is attached.
Completed per-project shards remain cached, so a later search with a new id
resumes rather than starting over. A late content poll for a cancelled id
returns `409 {"error":"SESSION_SEARCH_CANCELLED"}`. UI close, Escape, backdrop,
query replacement, and unmount should abort the local HTTP request and call
this endpoint independently.

### Compatibility session routes

The following routes operate on the daemon compatibility workspace:

- `GET /api/sessions?archived=1`
- `POST /api/sessions`
- `POST /api/sessions/:id/resume`
- `DELETE /api/sessions/:id?purge=1`
- `PUT /api/sessions/:id/archive`
- `DELETE /api/sessions/:id/archive`
- `PUT /api/sessions/:id/title`
- `GET /api/sessions/:id/draft`
- `PUT /api/sessions/:id/draft`
- `DELETE /api/sessions/:id/todos`

`GET /api/sessions` returns `SessionSummary[]`, not a wrapper object. Both this
route and the workspace-scoped list read session metadata only; they do not
open JSONL transcripts to backfill legacy summary or count fields.

Sub-agent sessions (created by the `spawn_subagent` tool; their meta carries a
persisted `parent_session_id`) are excluded from session lists by default so
they never appear in the sidebar or the global search. Query them explicitly:

- `GET /api/sessions?parent=<session_id>` — only the sub-agent sessions spawned
  by that parent (background-tasks panel data source). The active part of the
  merge skips workspace filtering; the disk part still scans the requested
  workspace's project directory.
- `GET /api/workspaces/:hash/sessions?parent=<session_id>` — same semantics on
  the workspace-scoped route.

`SessionSummary` includes a `parent_session_id` field (empty string for normal
sessions).

Sessions created directly by the LOOP scheduler additionally include persisted
provenance:

```json
{"loop_execution":{"loop_id":"loop-id","run_id":"run-id"}}
```

The field is returned for active and inactive sessions and survives daemon
restart. Manually forked sessions do not inherit it.

The compatibility `POST /api/sessions` response includes:

```json
{
  "session_id": "sid",
  "id": "sid",
  "workspace_hash": "abc123",
  "cwd": "C:/repo",
  "no_workspace": false
}
```

Session create/resume failures that escape the registry as a generic
`std::exception` (for example a filesystem or encoding error while resolving
the workspace directory) return `500` with a JSON body instead of an empty
Crow error page, on both the compatibility and the workspace-scoped routes:

```json
{"error":"SESSION_CREATE_FAILED","message":"<exception text>","cwd":"E:/repo"}
```

Resume uses `"error":"SESSION_RESUME_FAILED"`. Invalid expert bindings keep
returning `400 {"error":"INVALID_EXPERT"}`. Any other route handler that lets an
exception escape returns `500 {"error":"INTERNAL_ERROR","message":"<exception
text>"}`; the same text is written to the daemon log as an `ERR` line, so a
bare `500 Internal Server Error` body no longer occurs for daemon-side
exceptions.

These responses follow the same loopback CORS policy as successful requests,
including errors handled by the global exception handler. A supported loopback
`Origin` receives `Access-Control-Allow-Origin` on the JSON error response;
cross-origin requests still require the daemon token.

On Windows, directory model settings saved by older versions remain readable
when the canonical UTF-8 setting is absent. An existing canonical file takes
priority even if malformed. New saves use the canonical location, while explicit
removal clears both canonical and applicable legacy copies so an old model
choice cannot become active again through compatibility lookup.

### Model-facing thread and workspace tools

Daemon, TUI, and headless runtimes expose the same in-process thread and
workspace tools to the model. They reuse the session/workspace registries and
storage directly; they do not call the daemon HTTP API:

| Tool | Behavior |
|---|---|
| `create_thread` | create a thread in the inherited or explicitly selected workspace and queue its initial prompt |
| `fork_thread` | fork completed persisted history into a new thread |
| `list_threads` | globally list pinned threads plus cursor-paginated recent threads |
| `read_thread` | read bounded, cursor-paginated turns from any workspace |
| `send_message_to_thread` | queue a follow-up prompt to a thread in any workspace |
| `wait_threads` | wait for up to eight targets across workspaces using event cursors |
| `set_thread_title` | rename a thread |
| `set_thread_pinned` | update the existing pinned-session state |
| `set_thread_archived` | archive or unarchive a thread (sub-agent threads cannot be archived) |
| `delete_thread` | permanently delete a main thread and all descendants (sub-agent threads are refused) |
| `repair_thread` | append a deterministic repair checkpoint to another thread |
| `create_workspace` | register an existing absolute directory as a visible workspace |

`list_threads`, `read_thread`, and `wait_threads` discover sessions across the
entire ACECode data directory, including hidden/unregistered workspaces and
workspace-free sessions. A caller cwd is not required. List rows include
`workspaceHash` (the storage project hash, also for workspace-free sessions),
`cwd`, `noWorkspace`, `workspaceName`, and `workspaceVisible` as metadata.
Child sessions retain `parentThreadId`. The list excludes archived sessions
unless `includeArchived:true`; explicit reads can access archived sessions.
All non-archived pins are returned in `pinnedThreads`, ordered by project hash
and then that project's persisted pin order. Only `threads` is subject to
`limit` (default 20, maximum 50). Pass `nextCursor` back as `cursor` to read
the next page; it is an offset into the current ordering, not a frozen snapshot.
`errors` reports incomplete project scans. `read_thread` and each `wait_threads`
target accept optional `workspaceHash` from the list for direct lookup and
disambiguation when the same `threadId` exists in multiple projects.
Other mutation tools retain their existing calling-workspace semantics.

`create_thread` accepts required `prompt`, optional `title`/`model`, and an
optional target: `workspaceHash` for a registered workspace, `cwd` for an
existing absolute directory, or `noWorkspace:true`. These three target forms
are mutually exclusive. An omitted target (`noWorkspace:false` also counts as
omitted) inherits the caller's workspace-free state or working directory.
Workspace-free threads receive independent cache directories and persist
`no_workspace:true`, so the no-workspace sidebar list can discover them.
Directory targets are registered as visible workspaces, preserving existing
names and other workspace preferences. An explicit `cwd` is canonicalized;
a workspace hash retains the registered workspace's directory identity.
Invalid target types, relative/missing/non-directory paths, unknown hashes,
and conflicting selectors fail without creating a thread or silently falling
back to the caller's directory.

For example, `create_thread({"cwd":"N:/Users/shao/test333","prompt":"哈哈哈"})`
returns `{"threadId":"...","title":"","status":"running","cwd":"...",
"workspaceHash":"...","noWorkspace":false}`. The returned `workspaceHash`
is the storage project hash, including for workspace-free threads, consistent
with `list_threads` and `read_thread`. If initial input delivery fails, the
new thread is destroyed and its files are removed from its actual project.

`send_message_to_thread` accepts optional `workspaceHash` from creation or
discovery. It locates threads globally and restores inactive targets using
their own cwd and workspace-free state. Ambiguous ids require a hash; an id
already active in another project is rejected to prevent misdelivery. A
successful result is `{"threadId":"...","delivery":"queued","workspaceHash":"..."}`.
This queues ordinary input; it does not answer or dismiss a pending user
question, and sending to the calling thread remains invalid.

`delete_thread` also removes search-index and pin records. It may target its
calling thread, including a cascade whose tree contains the caller. In that
case it records the canonical tool result and turn timing, emits the terminal
turn events, stops any later write tool calls in the same response, and only
then tears down and purges the calling thread. The returned payload includes
`"scheduled":true`; no later model turn runs in the deleted thread.

`repair_thread` does not invoke a model, replay tools, or rewrite visible
transcript rows. It reconstructs provider history, repairs malformed
tool-call/result structure, and prunes only complete old user turn groups while
preserving the current input.

`create_workspace({"path":"C:/repo"})` accepts only an existing absolute
directory, resolves it to a canonical path, and idempotently persists the same
visible workspace record used by `POST /api/workspaces`. It returns
`{"hash","cwd","name","available":true}`. It never creates the target
directory, switches the calling thread's cwd, or starts a thread/worktree.

Separately, an explicit pre-output provider context-overflow error triggers a
finite recovery sequence inside `AgentLoop`: one history-repair retry, then one
retry with an emergency request profile, then a terminal error. Partial model
output is never replayed, and ordinary rate-limit, server, timeout, and network
errors do not enter this recovery sequence.

### `DELETE /api/sessions/:id`

Destroys an active in-memory session: aborts the current turn, joins the worker
thread, and removes it from the registry. It does not delete disk history.
Returns `204`; returns `503` when the session client is unavailable.

`DELETE /api/sessions/:id?purge=1` is the compatibility form of the workspace
purge above, used by the archived-session settings page, with the same
semantics: only an archived main session is accepted, and it is deleted
together with its child sessions. The background-task panel has no archive or
delete action; `?parent=` listings return every child regardless of a legacy
`archived` flag, and child sessions never appear in the `?archived=1` list.
Guard rails:

- `409 {"error":"subagent sessions are deleted together with their main session"}`
  for a sub-agent session
- `409 {"error":"session must be archived before permanent deletion"}` for a
  non-archived main session
- `409 {"error":"session is busy; abort it first"}` while the target is
  running a turn
- `404` for a missing session, `500` for incomplete durable cleanup, and `503`
  when the session client is unavailable

### Archive, title, draft, and todos

New-session drafts use `GET/PUT/DELETE /api/workspaces/:hash/draft`, independently
of existing-session drafts. Use `__no_workspace__` for the separate no-workspace
draft. Unknown workspace hashes return `404`; the usual authentication and CORS
rules apply. Each workspace owns one `input_draft.json` in its project data
directory (no-workspace uses its cache root). Saving does not create a session,
metadata entry, or transcript, and drafts survive page and daemon restarts.

PUT takes `{"text":"...","composer_content":{...}}` with optional structured
content, using the same normalization as session drafts. GET/PUT return
`{"workspace_hash":"...","text":"...","composer_content"?:{...}}`.
DELETE takes the submitted draft in the same format, atomically clears only
when the stored content matches, and returns the current draft with
`"cleared":true/false`. Invalid input returns `400`; disk failures return `500`.
A stored draft this build cannot read (for example one written by a later
version with unknown part types) makes GET return `500`, while PUT and DELETE
log a warning and treat it as empty: PUT overwrites it and DELETE reports
`"cleared":false` without touching it.

The home composer autosaves in order and restores on entry. A late response
cannot replace newer edits; failed sends retain the draft. Structured references
are durable, but unsent browser File bytes keep their existing in-memory
lifetime: after reload an unavailable upload must be attached again. Pasted text
too large to stay inline is the exception: it is stored on the server as a
new-session draft attachment and survives reloads (below).

#### New-session draft attachments

`POST /api/workspaces/:hash/draft/attachments` stores one pasted-text file for
the new-session draft (`hash` may be `__no_workspace__`). The body is a snapshot
upload that must be pasted text:

```json
{"name":"pasted-text-20260924-101010.txt","mime_type":"text/plain",
 "data_base64":"...","origin":"pasted_text",
 "paste":{"chars":120000,"lines":2400,"part":1,"parts":2}}
```

`origin:"pasted_text"` is required and the MIME type must be `text/plain`;
`source_path`, `reference_only` and `from_workspace_draft` are rejected (`400`).
`paste` follows the session upload rules below. Returns `201 {"attachment":{...}}`
whose `blob_url` is
`/api/workspaces/:hash/draft/attachments/:attachment_id/blob`; that `GET` route
returns the raw bytes like the session blob route. The `blob_url` stored in the
attachment's own metadata file is session-shaped and is never served: clients
compute the workspace URL from the draft part's `store_scope` and `id`.

Storage: a real workspace uses `projects/<hash>/attachments/.workspace-draft/`.
No-workspace drafts use `attachments/.workspace-draft/` under the project data
directory of the no-workspace cache root, not the cache root itself (every
subdirectory there is read as a no-workspace session cwd). The owner name starts
with a dot, so it can never equal a session ID.

The draft references the file through an attachment part with
`"store":"workspace_draft"` and `"store_scope"`. Before sending, the client copies
it into the target session with `POST /api/sessions/:id/attachments`
`{"from_workspace_draft":{"workspace":"<store_scope>","id":"..."}}` and sends the
new session attachment ID. The scope comes from the part, not from the session:
a no-workspace draft may be sent into a real workspace. The message route never
accepts a draft attachment ID directly (`404`).

Cleanup: after a successful draft PUT, or a DELETE that cleared the draft, the
daemon removes draft attachments that the saved draft no longer references and
whose metadata file is older than 10 minutes. The age gate protects an upload
whose referencing draft save is still debounced or in flight. Failures are only
logged.

Workspace-scoped and compatibility paths share the same behavior:

| Method | Path shape | Body | Response |
|---|---|---|---|
| PUT | `.../sessions/:id/archive` | ignored | updated `SessionSummary`; `409` for a sub-agent session (children follow their main session) |
| DELETE | `.../sessions/:id/archive` | none | updated `SessionSummary` |
| PUT | `.../sessions/:id/title` | `{"title":"..."}` | updated `SessionSummary` |
| GET | `.../sessions/:id/draft` | none | `{"session_id","id","text"}` |
| PUT | `.../sessions/:id/draft` | `{"text":"...","composer_content":{...}}` (content optional) | `{"session_id","id","text","composer_content"?}` |
| DELETE | `.../sessions/:id/todos` | none | `{"session_id","id","workspace_hash","todos":[],"todo_summary":{...}}` |

Title writes trim whitespace and validate with `sanitize_title`.

A title write always reaches both representations of the session. The persisted
meta is updated, and a copy of the same session that is live in this daemon also
gets the new title even when it did not match the request's workspace (a
no-workspace session never matches one). Across daemons — Desktop runs one per
workspace and only the active one serves the UI — the write only lands on disk,
so a persisted `title_source` of `user`/`user-cleared` outranks a stale live
title, including an older manual title: session listings report the persisted
rename, and the daemon holding the stale copy adopts it instead of writing it
back on its next meta write. Only an explicit local title write that is
currently being committed outranks the disk snapshot.

### `GET /api/sessions/:id/messages?since=N`

When `since=0` or omitted **and no pagination/navigation parameters are present**, returns a full snapshot object:

```json
{
  "events": [],
  "messages": [],
  "busy": false,
  "active_turn_id": "",
  "event_seq": 128,
  "event_epoch": "1b2c3d4e-0000-4000-8000-123456789abc",
  "title": "Investigate daemon routes",
  "title_source": "generated",
  "summary": "latest user summary",
  "turn_count": 4,
  "permission_mode": "default",
  "token_usage": null,
  "session_token_usage": null,
  "todos": [],
  "todo_summary": {},
  "goal": null
}
```

Hidden file checkpoints, compact checkpoints, and hidden goal context messages
are filtered from `messages`.

`event_seq` / `event_epoch` (present while the session is loaded) are the session
event dispatcher's current `seq` and instance id; see
[`GET /api/sessions/:id/runtime`](#get-apisessionsidruntime).

Pagination uses the same snapshot fields and filtering. The query parameters are:

| Parameter | Meaning |
|---|---|
| `limit` | Positive decimal record count; default 200, clamped to 1000. Returns the latest page. |
| `before` | Opaque cursor from the previous page; reads immediately older records. |
| `after` | Opaque cursor; reads only records appended after the previous response. |
| `from_position` | Explicit search navigation: decimal JSONL byte position, returning the continuous interval up to `before` or EOF. |
| `from_ordinal` | Legacy search navigation: resolves a zero-based ordinal over successfully parsed JSONL records, including hidden checkpoints, then returns that interval. |
| `workspace` | Existing workspace hash hint, also supported by paged requests. |

Paged responses add `has_more`, `after`, `turn_truncated`, and `before` when
`has_more` is true. Each message adds `message_position` (a decimal string to
avoid JavaScript integer precision loss) and `history_cursor`. A backward page
contains at least `limit` records where available, extending back to a visible
user message within 4 times the limit. If that boundary cannot be reached, only
`limit` records are returned and `turn_truncated` is true. Results are chronological.
An `after` response can contain zero messages; retain the existing transcript and
advance its cursor. Older pages do not replace the current live state or after cursor.

Malformed cursors/numbers, zero/negative limits, combining `before` and `after`,
combining position and ordinal, or combining pagination with `since>0` return
400 `BAD_REQUEST` before opening the transcript. Missing sessions return 404.
Cursor validation checks the file identity, line boundary and record fingerprint:
append preserves validity; rewrite/replacement returns 409 `HISTORY_CURSOR_STALE`.
On 409 discard the old cursors and request a fresh tail page. Reads use a fixed
file-size snapshot and retry once if the file is replaced during the read.

The default web/grid loading path requests `limit=200`. Earlier history is loaded
on demand, external-session polling uses `after`, and completion self-healing
reads only a bounded tail (plus one older page if the user-turn anchor is absent).
Full export, fork and explicit session references keep the legacy full read.

Conversation error messages (`role: "error"`) are persisted as transcript-only
records with `metadata.transcript_only: true`, a unique `uuid`, and a timestamp.
Their `id` is that UUID in both history and `message` events; original text and
`metadata.provider_error` details are preserved. Clients reconcile these errors
by ID, so history/event overlap produces one card while separate identical
failures remain separate cards. Legacy unmarked error events retain sequence
identity because their content-derived IDs can repeat. These records are visible
after switching sessions, refresh, and restart, but are excluded from provider
history and compaction input. Errors lost by older versions are not backfilled.

Visible system messages may include `metadata.system_notice` with
`{ "version": 1, "code": "goal_started", "params": { "goal": { ... } } }`.
The stable event code and structured parameters describe the notice; Web and
Desktop localize its title and fixed detail fields at render time. The original
`content` remains the fallback for older clients and diagnostics. Existing
metadata (for example `transcript_only`, `goal_audit` and `compact_notice_id`)
is preserved. Unknown codes or versions must retain the full fallback text.
Creating a goal emits one visible audit message containing the complete goal
snapshot, rather than a separate overview followed by a start notice. System
notices start collapsed independently of the general message-collapse setting;
unrelated notices are never folded into tool activity summaries.

`context_preserved_waiting` means a request below 40,000 estimated tokens was
rejected for context size and is being retried with its history and tools intact.
These requests do not lower the learned budget or enter automatic compaction,
history pruning, or a reduced request profile. Automatic compaction applies a
40,000-token floor to its final trigger; `context_threshold_lowered.params.threshold`
reports that final trigger rather than the underlying learned window. Explicit
manual compaction remains available below the floor.

Compact checkpoints are append-only. Version 2 records the Codex-shaped
replacement model history together with `window_number`, `first_window_id`,
`previous_window_id`, and `window_id`. Resume and fork start from the newest
valid checkpoint and replay only its suffix. A fork preserves the inherited
replacement history but resets its latest inherited checkpoint to a fresh
UUIDv7 window zero, so later compactions form a fork-local chain. Version 1
checkpoints without window metadata remain readable. Visible transcript rows
before compaction are not removed.

Pre-turn automatic compaction estimates the pending user input for threshold
purposes but compacts only already-recorded model history; the input is appended
exactly once after the compact attempt. Normal request construction keeps mutable
session/time/CWD, hook, plan, and todo context as separate user-role items and
inserts them before the last real user message (or fallback summary), so it never
rewrites the compact summary prefix or trails a mid-turn summary.

Non-streaming provider failures carry structured `ProviderErrorInfo`. Retryable
non-context failures keep the same immutable compaction request and retry
without a count limit. Local delays start at one second, double to a maximum of
twenty minutes, honor valid `Retry-After` guidance up to the same cap, and wake
promptly on cancellation. History trimming is reserved for explicitly
classified context-window overflow and resets the transient backoff sequence;
a generic HTTP 413 or ambiguous payload-size message is terminal and does not
delete items.

When `since>0`, returns an event array directly:

```json
[
  {"type":"message","seq":43,"timestamp_ms":1783152000000,"payload":{}}
]
```

If the requested sequence predates the in-memory replay ring, the array can be
empty. A paged frontend can reload `limit=200`; legacy full-history clients can fall back to `since=0`.

### `GET /api/sessions/:id/runtime`

Lightweight probe used by the Web/Desktop live-state watchdog. Reads memory only
(no transcript IO) and is safe to call while a turn is running.

```json
{
  "session_id": "20261019-101010-abcd",
  "active": true,
  "busy": false,
  "active_turn_id": "turn-uuid",
  "event_seq": 128,
  "event_epoch": "1b2c3d4e-0000-4000-8000-123456789abc"
}
```

- `active` is false (and `busy` false, cursor fields omitted) when the session is
  not loaded in this daemon; unknown ids also return this shape with 200.
- `event_seq` is the current highest event `seq`; `event_epoch` identifies the
  event dispatcher instance. `seq` restarts at 1 when the daemon restarts or the
  session runtime is rebuilt, so a cursor is only comparable within one epoch.
- The frontend probes when a live transcript still shows a running turn but has
  received no event for 20 s (4 s after the page becomes visible). If the server
  is idle, or `event_seq` is ahead of the page, or the epoch changed / seq
  regressed, it reloads the tail page, settles the runtime state from the server
  and resubscribes with `replay_from_start` from the reconciled cursor. A quiet
  but healthy turn (busy, same `seq`) is left untouched.

### `GET /api/sessions/:id/trajectory`

Returns model-invisible diagnostic records for exactly one session. The route
uses the normal daemon authentication and session/workspace scope checks. Pass
`workspace=<hash>` for a workspace session when its id is not globally unique;
omit it for a no-workspace session.

Query parameters:

| Name | Default | Meaning |
|---|---:|---|
| `after` | `0` | return recorded events whose monotonic `sequence` is greater than this cursor |
| `legacy_after` | `0` | offset into confirmed facts projected from the canonical transcript |
| `limit` | `250` | page size for each source, clamped to `1..1000` |
| `workspace` | empty | optional workspace hash scope |

```json
{
  "schema_version": 1,
  "session_id": "20260815-113921-a520",
  "workspace_hash": "...",
  "no_workspace": false,
  "source": "mixed",
  "records": [
    {
      "schema_version": 1,
      "sequence": 42,
      "timestamp_ms": 1786783204730,
      "type": "tool_end",
      "source": "recorded",
      "payload": {}
    }
  ],
  "next_after": 42,
  "legacy_next_after": 3,
  "has_more": false,
  "recorded_has_more": false,
  "legacy_has_more": false,
  "legacy_total": 3,
  "missing_capabilities": ["ttft", "tool_timing"],
  "diagnostics": {
    "malformed_complete_records": 0,
    "ignored_partial_tail": false,
    "recovered_unterminated_record": false
  }
}
```

`source` is `recorded`, `legacy`, `mixed`, or `empty`. Recorded events come
from `<project_dir>/<session_id>/trajectory.jsonl`; legacy records have
`sequence: null`, a `legacy_index`, and never infer missing timestamps,
request payloads, TTFT, tool schemas, or tool durations. `missing_capabilities`
names those unavailable facts. The two cursors are independent and must both
be retained by paged or polling clients. Malformed complete JSONL records and
an incomplete crash tail are skipped and reported in `diagnostics` without
affecting the canonical transcript.

### `POST /api/sessions/:id/export-markdown`

Exports the current session's visible transcript as a UTF-8 Markdown file. This
endpoint is available only when the desktop native save-file picker is enabled.
After resolving the session, the daemon opens the platform Save As dialog with
a filesystem-safe `<session-title>.md` filename prefilled. The user can edit the
filename and destination; the daemon writes to the confirmed full path. The
optional body identifies the workspace when the session id is not globally
unique:

```json
{
  "workspace_hash": "..."
}
```

On success, the response is:

```json
{
  "ok": true,
  "cancelled": false,
  "filename": "session-title.md"
}
```

If the user cancels Save As, the response is `{"ok":true,"cancelled":true}` and
no file is created. Native dialogs provide their normal overwrite confirmation;
paths returned without an extension receive `.md`. Hidden goal context, compact
checkpoints, and file checkpoints are excluded from the export. The endpoint
does not mutate the session. Errors use `400` for invalid JSON or destination
paths, `404` for unknown sessions/workspaces, `501` when the native picker is
unavailable, `503` when its callback is unavailable, and `500` for picker, file
creation, or write failures.

### Ordered composer content

Messages, turn steering/interruption and session draft writes accept optional
`composer_content`. Its editor-independent version 1 schema preserves the order
of text and references:

```json
{"version":1,"parts":[
  {"type":"text","text":"Use "},
  {"type":"skill","name":"review","token":"[$review](C:/skills/review/SKILL.md)","path":"C:/skills/review/SKILL.md"},
  {"type":"text","text":" with "},
  {"type":"attachment","key":"local-1","id":"att-...","name":"notes.txt","kind":"file"},
  {"type":"text","text":" and "},
  {"type":"path","path":"src/apps/cli/main.cpp","token":"@src/apps/cli/main.cpp","directory":false}
]}
```

Required fields are shown above except `skill.path` and `path.directory`, which
are optional. Attachments may also carry optional `mime_type` and `path` strings.
`key` identifies an occurrence across upload reconciliation; `id` identifies the
uploaded resource. Draft placeholders may omit `id`; submitted messages must
include each attachment's ID in the regular `attachments` payload, and the daemon
must successfully load that record from the target session. Display name, kind,
MIME and path are then hydrated from those verified records. Client preview URLs
and unknown fields are stripped.

The limit is 4096 parts and one shared 2 MiB budget for all declared string
fields, including pasted text (drafts and messages use the same budget). Path/token fields
allow 64 KiB, names 16 KiB, MIME 1024 bytes, kind 64 bytes and key/id 256 bytes.
Unknown versions/types, invalid field types or unresolved attachment identities
return HTTP 400. Canonical text concatenates text parts and path/skill tokens;
attachment parts contribute no text. Messages normally derive their text from
this structure; the compatibility `text` is retained when `session_references`
requires its existing display projection. Skills activate through the existing
explicit-mention mechanism; their visual order does not define execution order.

Pasted text uses two part shapes that the Web composer shows as the same card:

- **Inline block** `{"type":"pasted_text","key":"...","text":"..."}`. `key` is
  optional (at most 256 bytes); `text` must be a string without NUL, and an empty
  block is dropped. It is **not** part of the canonical (editor) text, so draft
  responses, `restored_prompt` and input history never contain it. The message
  body is the *submission text*: text parts, path/skill tokens and inline blocks
  in part order, where each inline block is separated from neighbouring non-empty
  pieces by a blank line (`"\n\n"`). Examples: `[text "A", pasted "B"]` →
  `"A\n\nB"`; `[pasted "A", text "B", pasted "C"]` → `"A\n\nB\n\nC"`; a single
  block → its text. When the first non-empty piece is a pasted block (nothing was
  typed before it), the message never triggers skill or OpenCode slash-command
  expansion, whatever the pasted text starts with. The Web client keeps inline
  blocks at or below 256 KiB in total and turns larger pastes into files.
- **File-backed block**: an ordinary `attachment` part with an optional
  `paste` descriptor `{"title","chars","lines","part","parts"}`. `title` is a
  string of at most 1024 bytes (counted in the budget); `chars` and `lines` are
  non-negative integers; `part`/`parts` appear together for a paste split into
  several files, with `1 <= part <= parts <= 1024`. Other descriptor keys are
  dropped. The text lives in the uploaded file and reaches the model as the usual
  attachment file reference.

A home (new-session) draft attachment may also carry
`"store":"workspace_draft"` with `"store_scope"` set to the draft's workspace
hash or `__no_workspace__` (`[A-Za-z0-9_]{1,128}`, required whenever `store` is
present; no other `store` value is accepted). A submitted message resolves every
attachment part against the session's verified records, which removes
`store`/`store_scope` and keeps `paste`.

The sanitized structure is persisted as `metadata.composer_content` and returned
in live message events and history. Provider `content_parts` retain their existing
contract. Legacy messages and clients without this field remain supported.

Draft GET/PUT responses return optional `composer_content`; PUT derives its text
from the content and saves both atomically. A text-only PUT or explicit null
clears the structured draft. Forking a structured user prompt returns
`restored_composer_content` plus `restored_attachments`, copies referenced uploads
into the new session with new IDs, and saves the restored structured draft. For
such a prompt `restored_prompt` (and the new session's plain draft text) is the
canonical editor text, without inline pasted blocks, which are restored only
through `restored_composer_content`.
Structured attachment references in the retained history are also copied and
remapped, including their provider content parts and preview records; recalling
those messages does not depend on the source session's attachment storage.

### `POST /api/sessions/:id/messages/retry`

Retries the trailing user message, or the last user message of a manually
stopped turn, in an idle live session. Body:

```json
{"expected_user_message_id":"persisted-user-message-id"}
```

The request accepts only this field. The backend verifies the full visible
transcript and model history end with that user message, with no active or
queued work. It checks again when the worker starts. Hidden bookkeeping
records do not count as transcript messages; assistant (including empty
messages), tool, system and error messages prevent ordinary retry.

A completed manual stop persists a transcript-only system message with
`metadata.user_aborted: true`, `metadata.turn_id`, and `metadata.retry_user_message_id`. If that
marker is the final visible transcript entry, the backend may retry its
specified last user message even after partial assistant output or tool
results. A stop request alone, an interjection, or plain interruption text
does not grant this exception. Later visible events invalidate it.
Already streamed text is saved as an assistant message with
`metadata.transcript_only: true` and `metadata.interrupted_output: true`, so
history reloads retain it without sending incomplete output/tool calls back
to the provider.

The original message, attachments and context are reused. If model history
still ends with that user, no user record is appended. If an aborted turn
already has assistant/tool records, they are preserved and the original
structured user content is appended with a new identity, without expanding
skills again or creating adjacent user messages. The stop marker is never
sent to the model. Returns `202 {"queued":true,"user_message_id":"..."}`;
malformed requests return `400`, and unavailable sessions, stale message IDs
or active/queued work return `409`. This endpoint does not create or resume a
session, expand commands, or accept new input.

### `POST /api/sessions/:id/messages`

Queues a user input turn. Body:

```json
{
  "text": "Explain this code",
  "client_message_id": "queued-session-id-1",
  "attachments": [{"id":"att-..."}],
  "contexts": [
    {
      "type": "selection",
      "label": "README.md:23-24",
      "text": "selected text",
      "source": {
        "path": "C:/repo/README.md",
        "start_line": 23,
        "end_line": 24,
        "line_count": 2
      }
    }
  ]
}
```

`attachments` may contain strings or objects with an `id` field. `contexts`
with `type:"selection"` are sanitized and expanded into model-visible context
while preserving the user's original display text. Other context objects are
passed as browser context content parts.

`swarm_mode` (optional) switches the session-level swarm mode before the input
is queued: `"star"`, `"mesh"` or `"off"`; legacy clients may send `true` (=
`"star"`) or `false` (= `"off"`). Any other value returns `400` with
`swarm_mode must be "star", "mesh" or false`. The mode is sticky: omitting the
field keeps the session's current mode, and the accepted value is also recorded
as `metadata.swarm_mode` on that user message. Leaving `"mesh"` while agents of
the session's mesh tree are still running (or hold undelivered follow-up tasks)
returns `409` with the reason; so does posting directly to a mesh sub-agent
(`direct input is not allowed for mesh swarm sub-agents`). A successful switch
emits `session_updated {"swarm_mode"}`. See `docs/subagents.md` §9.

`client_message_id` is an optional non-empty string (maximum 256 bytes) used by
Desktop ordinary and queued-input handoff. When accepted, it is preserved as
`metadata.client_message_id` on the canonical user message so an optimistic
local item can reconcile with persistence and WebSocket replay. It does not
deduplicate backend execution; callers that omit it retain the existing behavior.

If the text is a skill slash command for the session workspace, the daemon
expands it to the skill invocation prompt and records `metadata.display_text`.
Skill and OpenCode command expansion is skipped when the message has
`attachments` or `contexts`, except when every attachment is a stored pasted-text
attachment (`metadata.origin == "pasted_text"`, read from the session's records):
such a file is the user's own material, so `/<skill> args` expands the same way
whether a paste stayed inline or became a file. Expansion is also skipped when
the first non-empty composer piece is an inline pasted block.
Returns `202 {"queued":true}`.

### `POST /api/sessions/:id/turn/steer`

Appends structured user input to the currently running regular agent turn.
The request accepts the same `text`, `attachments`, `contexts`, and optional
`client_message_id` fields as the ordinary messages endpoint, plus the required
turn identity:

```json
{
  "text": "Keep the public API stable",
  "client_message_id": "queued-session-id-1",
  "expected_turn_id": "initial-user-message-uuid"
}
```

The expected id must equal `active_turn_id` from a session summary, the initial
messages snapshot, or the latest `busy_changed` event. The equality check and
FIFO enqueue happen atomically. Accepted input is committed as a normal visible
user message at the next model-request boundary, remains in the same busy turn,
and preserves structured content and `client_message_id`.

Acceptance is not the durable commit acknowledgement. A successful request
returns `202`:

```json
{
  "accepted": true,
  "turn_id": "initial-user-message-uuid",
  "client_message_id": "queued-session-id-1"
}
```

Clients should keep pending UI until the canonical user `message` event with
the matching `metadata.client_message_id` arrives. If the turn terminates
before commit, its terminal busy event lets the client restore that pending
input.

Errors use structured codes: `400 EXPECTED_TURN_ID_REQUIRED` or
`INVALID_TURN_INPUT`, `404 UNKNOWN_SESSION`, `409 NO_ACTIVE_TURN`,
`TURN_NOT_STEERABLE`, or `TURN_MISMATCH`, and
`429 TURN_STEER_QUEUE_FULL`. A mismatch response includes the current
`active_turn_id`.

### `POST /api/sessions/:id/turn/interrupt`

Interrupts the matching active regular turn and atomically promises the input
as a new high-priority regular turn. The request body and validation rules are
the same as `/turn/steer`, including required `expected_turn_id` and optional
structured attachments, contexts, and `client_message_id`:

```json
{
  "text": "Stop and use the new constraint now",
  "client_message_id": "queued-session-id-2",
  "expected_turn_id": "initial-user-message-uuid"
}
```

Unlike soft steer, acceptance sets the current provider/tool abort flag instead
of waiting for the current response to finish. The server queues the replacement
before requesting abort and runs it ahead of ordinary queued worker tasks. Thus,
if acceptance races natural completion, the operation is either rejected with
no new message or accepted with exactly one future user turn; the client never
needs to resend it after `busy=false`.

Success returns `202` after both the replacement turn and interrupt request have
been committed in memory:

```json
{
  "accepted": true,
  "interrupting": true,
  "turn_id": "initial-user-message-uuid",
  "client_message_id": "queued-session-id-2"
}
```

The old turn finishes with outcome `aborted`, emits a visible system notice
`[Interjected]` (`metadata.turn_interrupt=true`), records a hidden model-visible
`<turn_aborted>` marker, and does not pause an active goal. Manual stop still
uses `[Interrupted]`. The replacement user message is the durable acknowledgement
and carries the matching `metadata.client_message_id`. Pending UI should remain
in an interrupting state across the short old-turn `busy=false` transition until
that message arrives.

The endpoint uses the same structured error codes as `/turn/steer`. Existing
clients that want same-turn delivery at the next model boundary should continue
using `/turn/steer`; Desktop/Web interjection and `/turn` use this immediate
endpoint.

### `POST /api/sessions/:id/turn/steer/send-now`

"Send now" for input accepted by `/turn/steer` that the model has not read
yet. The body names the steer by its `client_message_id` and carries the
required `expected_turn_id`:

```json
{"client_message_id": "queued-session-id-1", "expected_turn_id": "initial-user-message-uuid"}
```

While that steer is still pending, every pending steer of the turn (in FIFO
order, this one included) is promised as a high-priority turn exactly like
`/turn/interrupt` does, and the active turn is aborted. No new input is added,
so the message is committed once. Success returns `202`
`{"accepted": true, "interrupting": true, "turn_id": "...", "client_message_id": "..."}`.
If the model already read it, or it was discarded when the turn ended, the
response is `409 STEER_NOT_PENDING` and nothing changes. Other errors match
`/turn/steer`.

### `POST /api/sessions/:id/turn/steer/withdraw`

Removes a pending steer (`{"client_message_id": "..."}`) from the active turn
without touching the turn. Success returns `200`
`{"accepted": true, "withdrawn": true, "turn_id": "...", "client_message_id": "..."}`;
a steer that was already read or is no longer pending returns
`409 STEER_NOT_PENDING`.

Web/Desktop use these for the composer: while a turn is running, Enter sends
the message as a soft steer (`/turn/steer`) and shows it at the end of the
transcript until the canonical user message arrives; its bubble offers
"send now" and withdraw. Ctrl+Enter keeps the client-side queue (sent after
the turn), and Ctrl+Alt+Enter forks the whole session
(`POST /fork` with `whole: true`) and sends the message there. A steer that is
still unread when the turn ends (stop or error) goes back to the client queue.

### `POST /api/sessions/:id/questions/interject`

Resolves a pending `question_request` with a free-form user message instead of
an answer. This is what Desktop/Web sends when the user types into the composer
while an AskUserQuestion picker is open, and what the remote-control channel
sends for plain (non-`/aq`) text while a question is pending. The body is the
`/turn/steer` shape plus the required `request_id` of the pending question;
`expected_turn_id` is optional and validated when present:

```json
{
  "text": "Neither, use the built-in client",
  "request_id": "question-request-uuid",
  "client_message_id": "queued-session-id-3",
  "expected_turn_id": "initial-user-message-uuid"
}
```

Acceptance is atomic with the question: the question closes with
`question_closed` `reason:"interjected"`, its tool result becomes a successful
`[User interjected] …` message telling the model the user's real instruction
follows, and the input is committed as a same-turn visible user message
immediately after that tool result (`metadata.turn_steer=true`,
`metadata.question_interjection=true`, `metadata.question_request_id`). The
turn is not aborted and no replacement turn is created; the model simply
continues from the interjection at the next model boundary. Success returns
`202`:

```json
{
  "accepted": true,
  "turn_id": "initial-user-message-uuid",
  "request_id": "question-request-uuid",
  "client_message_id": "queued-session-id-3"
}
```

If the question is no longer pending (already answered from another client,
timed out, or closed), the endpoint returns `409 NO_PENDING_QUESTION` and the
input is **not** committed; clients should fall back to the ordinary send or
queue path. `400 QUESTION_REQUEST_ID_REQUIRED` is returned when `request_id`
is missing. All other codes match `/turn/steer`.

### `POST /api/sessions/:id/follow-up-prompt`

Requests an optional next user message for an active, idle session. The body is
`{"completion_key":"<user_message_uuid>:<completed_at_ms>"}`, using the latest
persisted `turn_timing` record with `status: "completed"`. Loading/running,
aborted and failed turns are ineligible. The server checks the identity both
before and after generation and returns `409 STALE_COMPLETION` if it changed.
Invalid keys return 400; unknown active sessions return 404.

A successful response is `{"completion_key":"...","prompt":"Run the tests."}`.
The prompt can be empty when context or a usable model answer is unavailable.
Generation uses bounded recent visible messages, the summary-model fallback
chain (with the current session model as context), a separate tool-free provider
request and a 15-second model budget. It does not call tools, append messages,
change the main provider or start a turn. No transcript/provider text is included
in errors. Before calling this endpoint, clients wait for successful current-session
draft restoration and skip that completion if there is unsent text (including
whitespace), structured draft content, attachments or context. Clearing that draft
does not backfill a skipped request; historical chat messages do not count as drafts.
Clients deduplicate by backend/workspace/session/completion for their
application lifetime, ignore stale responses and only turn the suggestion into
draft content after explicit acceptance. Existing side-question and task-card
endpoints keep their behavior.

### `POST /api/sessions/:id/side-question`

Runs one isolated `/btw` or `/side` side question against the active session's
latest thread-safe provider-facing context snapshot. The registry primes this
snapshot when a new session is configured and refreshes it after persisted
history/worktree state is restored, so the endpoint can be used before the
session's first main provider request:

```json
{"question":"Why did the current approach choose a mutex?"}
```

The question is single-turn (no side history) but runs the same read-only tool
loop as streaming side chat below: the model may call only `file_read`, `grep`,
`glob` and `lsp`, under the same checks, until it answers in text. Providers
that run their own tools (the native Codex app-server) are rejected with
`503 SIDE_QUESTION_PROVIDER_UNAVAILABLE`. It does not append the question or
answer to the main agent history, JSONL transcript, hooks, goals, event stream,
or busy lifecycle. Success:

```json
{
  "question": "Why did the current approach choose a mutex?",
  "answer": "It protects the snapshot while the main worker publishes it.",
  "tools_used": ["file_read src/engine/agent/side_question/side_question_service.cpp"]
}
```

`tools_used` lists each read-only call as `<tool> <path or pattern>`; it is
empty when the model answered from context alone.

Errors use structured codes:

- `400 INVALID_SIDE_QUESTION`: `question` is missing, empty, not a string, or
  exceeds 16,000 UTF-8 bytes.
- `404 UNKNOWN_SESSION`: the target session is not active.
- `409 SIDE_QUESTION_CONTEXT_NOT_READY`: the registry could not publish a safe
  provider-facing context snapshot (an internal lifecycle invariant failure,
  not a prompt for the user to send a main-chat message first).
- `503 SIDE_QUESTION_PROVIDER_UNAVAILABLE`: the session has no current model.
- `502 SIDE_QUESTION_FAILED`: the provider call failed, returned no answer, or
  attempted a tool call.

Optional `worktree` field for the **first** message of a session (openspec
`add-webui-git-session-pill`):

```json
{"text": "...", "worktree": {"create": true, "base": "master"}}
```

Before enqueuing, the daemon creates (or fast-resumes) a worktree named
`ses-<session id>` based on `base` (a local branch; empty
falls back to the default `origin/<default-branch>` baseline) via the same
machinery as the `EnterWorktree` tool, then switches the session cwd into it.
The accepted response exposes the working root immediately:

```json
{
  "queued": true,
  "worktree": {
    "name": "ses-session-id",
    "branch": "worktree-ses-session-id",
    "path": "C:/repo/.acecode/worktrees/ses-session-id"
  }
}
```

Ordinary message submissions without worktree creation keep returning
`202 {"queued":true}`.

Session storage location does not move. Failures abort the request without
enqueuing: `404` unknown session, `409` session busy, `400` session already
has messages / already in a worktree / invalid or missing base branch,
`500` git errors.

### Private streaming side chat over WebSocket

Web/Desktop floating side chat opens its own connection to the existing
`/ws/sessions/<id>?token=...` endpoint using the same authentication rules. This
connection does not send `hello` and does not subscribe to main-session events.
The synchronous HTTP endpoint and TUI `/btw` and `/side` remain single-turn but
use the same read-only tools.

Start a request with:

```json
{
  "type": "side_chat_start",
  "payload": {
    "session_id": "session-id",
    "request_id": "unique-request-id",
    "question": "How does that affect the next request?",
    "history": [
      {"role": "user", "content": "Why use a mutex?"},
      {"role": "assistant", "content": "It protects the context snapshot."}
    ]
  }
}
```

`request_id` must contain 1–128 UTF-8 bytes. Legacy text-only `question` is
limited to 16,000 UTF-8 bytes. Rich clients also supply `input`, using the main
input contract: `text`, `attachments` (stored attachment IDs), `contexts`,
`session_references`, and `composer_content`. Input objects are bounded to 2 MiB;
resolved current text is bounded to 256 KiB. Attachment-only input is valid.
The shared main-input parser resolves ownership-checked file/image attachments
and session references without submitting a main turn. Worktree intent and raw
resolved `content_parts`/metadata are rejected.

Optional `history` contains at most 200 messages and 256 KiB of resolved text,
alternating `user`/`assistant` pairs. A historical user message may include its
original `input`; the server resolves it through the same parser, preserving
images for follow-ups. Assistant messages accept only text role/content. Tool
and system messages and other additional message fields are rejected.

Optional `model_name` selects a saved profile for this side request; optional
`reasoning_effort` uses the profile's supported settings. The provider is owned
by the side request and never installed into the main session. Invalid or
unavailable choices return `SIDE_CHAT_MODEL_UNAVAILABLE`. Omitting `model_name`
preserves the legacy main-provider snapshot behavior. Queued clients snapshot
the model and rich input at submission time.
Clients include successful answers and nonempty stopped answers in subsequent
history; failed or empty stopped turns stay local to the floating transcript.

The model receives the latest safe main context snapshot, detached side-chat
instructions, the supplied side history, and the new question. Its tool list
contains only the read-only built-in tools `file_read`, `grep`, `glob` and
`lsp` that the session has registered and its expert capability policy allows
(model-facing names follow tool rewrites); `bash`, write tools, sub-agents and
MCP tools are never offered. The daemon runs those calls itself and feeds the
results back until the model answers in text (at most 8 tool steps). Each call
passes configured Deny rules, the main session's path validation, and the
dangerous-path check; anything that would need a confirmation prompt is refused,
because side chat has no confirmation channel. Reads never update the main
agent's read baseline or unchanged-read cache. A reply that writes a tool call
as plain text is discarded (`side_chat_reset`) and the model is asked to retry;
the markup is never shown. Side messages do not mutate main history,
transcript, hooks, goals, busy state, or the session event stream. Responses go
only to the requesting connection:

```json
{"type":"side_chat_delta","payload":{"request_id":"unique-request-id","delta":"Text fragment"}}
{"type":"side_chat_tool","payload":{"request_id":"unique-request-id","call_id":"call_1","name":"file_read","target":"src/apps/cli/main.cpp","status":"running"}}
{"type":"side_chat_reset","payload":{"request_id":"unique-request-id"}}
{"type":"side_chat_done","payload":{"request_id":"unique-request-id","answer":"Complete or stopped partial answer","cancelled":false}}
{"type":"side_chat_error","payload":{"request_id":"unique-request-id","code":"SIDE_CHAT_FAILED","message":"Provider error"}}
```

`side_chat_tool` reports one read-only call: `running` before execution, then
`success` or `error` with the same `call_id`. `name` is the native tool name and
`target` a short path or pattern for display. Text after a tool call starts a
new model step; the daemon prefixes it with a blank line so the accumulated
answer stays readable Markdown.

`side_chat_reset` discards the provisional text of the current model step
(provider retry, or a step that wrote a tool call as text). Text received before
that step's preceding `side_chat_tool` frames stays. `side_chat_done` includes
the authoritative accumulated answer. On error, clients retain already received
text for display but exclude the failed turn from follow-up context.

#### Sending to the main session

The streaming side chat model also has a `send_to_main_session(message)` tool,
for when the user asks it to pass something to the main agent (the main agent
cannot see the side conversation). Nothing is delivered until the user
confirms. The tool call first reports `side_chat_tool` (`running`), then:

```json
{"type":"side_chat_send_request","payload":{"request_id":"unique-request-id","send_id":"send-…","call_id":"call_1","message":"Drafted message"}}
```

The client answers on the same connection, with the possibly edited text:

```json
{"type":"side_chat_send_decision","payload":{"request_id":"unique-request-id","send_id":"send-…","decision":"send","message":"Edited message"}}
{"type":"side_chat_send_decision","payload":{"request_id":"unique-request-id","send_id":"send-…","decision":"cancel"}}
```

The tool waits until it gets an answer or the side request ends (stop or
disconnect). Then the daemon delivers the message and reports the outcome to
both the window and the model:

```json
{"type":"side_chat_send_result","payload":{"request_id":"unique-request-id","send_id":"send-…","status":"steered","message":""}}
```

`status` is `steered` (the main session was running a turn; the message is
added to that turn and read at its next model step, without interrupting it),
`started` (the main session was idle and starts a new turn), `queued` (the main
session is busy with work that does not accept steering; the message runs as
its next turn), `cancelled` (the user declined), or `unknown_session` /
`unavailable` with `message` explaining why. Decisions with an unknown
`send_id` or for a finished request are ignored; malformed ones return
`INVALID_SIDE_CHAT_SEND`.

The delivered message is a user message in the main session. Its model-facing
content starts with a line noting it came from the user's side chat;
`metadata.display_text` holds the text as sent and `metadata.side_chat` is
`true`, which the Web UI shows as "From side chat". The same delivery is
available without a model call, for the side window's "send to main session"
action on an answer:

```text
POST /api/sessions/:id/side-chat/send   {"message": "…"}
200 {"delivery": "steered" | "started" | "queued"}
400 INVALID_SIDE_CHAT_SEND · 404 UNKNOWN_SESSION · 503 SIDE_CHAT_SEND_UNAVAILABLE
```

Send `{"type":"side_chat_stop","payload":{"request_id":"unique-request-id"}}`
to cancel only that side request, including its retry backoff. The terminal
`side_chat_done` then has `cancelled: true` and preserves generated text.
Closing the connection also cancels the request. At most one side request may
run per connection; another start returns `SIDE_CHAT_BUSY`. Stop messages with
an unmatched request ID are harmless. Clients should wait for the terminal
frame before sending another turn or close the finished connection.

Other structured errors include `INVALID_SIDE_CHAT`, `UNKNOWN_SESSION`,
`SESSION_REGISTRY_UNAVAILABLE`, `SIDE_CHAT_UNAVAILABLE`,
`SIDE_QUESTION_CONTEXT_NOT_READY`, and `SIDE_QUESTION_PROVIDER_UNAVAILABLE`.
`SIDE_CHAT_PROVIDER_UNSUPPORTED` means the current provider cannot guarantee
tool-free calls. In particular, the native Codex app-server provider owns its
own tool runtime and is rejected before invocation; selecting a supported
model enables side chat. Its main-session behavior remains unchanged.
An older daemon returns its ordinary unknown-message error; clients must show
that error and release the composer instead of simulating streaming.

### `POST /api/sessions/:id/attachments`

Uploads bytes into the session attachment store. Body:

```json
{
  "name": "screenshot.png",
  "mime_type": "image/png",
  "data_base64": "..."
}
```

Desktop may instead create a metadata-only reference for an ordinary local
file. The server canonicalizes `source_path`, verifies that it is a regular
non-image file, and records its actual size without reading or copying its
bytes. There is no 25 MiB snapshot limit for this form:

```json
{
  "name": "large.pdf",
  "mime_type": "application/pdf",
  "source_path": "C:/docs/large.pdf",
  "reference_only": true
}
```

A snapshot upload may be marked as pasted text with `"origin":"pasted_text"`
and an optional `"paste":{"chars","lines","part","parts"}` (non-negative
integers; `part`/`parts` together, `1 <= part <= parts <= 1024`; other keys
dropped). The MIME type must then be `text/plain`. The record's `metadata` gets
`"origin":"pasted_text"` and `"pasted_text":{...}`. Any other `origin`, `paste`
without `origin`, or `origin` on a `reference_only` request returns `400`.

To import a new-session draft attachment (see "New-session draft attachments"),
send only `{"from_workspace_draft":{"workspace":"<hash or __no_workspace__>","id":"att-..."}}`.
The pasted-text file is copied into this session under a new ID, keeping its
metadata. Combining it with `data_base64`, `source_path`, `reference_only`,
`origin` or `paste`, or a malformed value, returns `400`; an unknown workspace,
attachment or missing file returns `404`.

Returns `201`:

```json
{
  "attachment": {
    "id": "att-...",
    "session_id": "sid",
    "name": "screenshot.png",
    "kind": "image",
    "mime_type": "image/png",
    "path": "...",
    "blob_url": "/api/sessions/sid/attachments/att-.../blob",
    "size_bytes": 12345
  }
}
```

For a source reference, `path` and `blob_url` are empty, and `metadata`
contains the canonical `source_path` plus `"storage":"source_reference"`.
Raster images cannot use `reference_only`; they continue through the snapshot
upload and image-normalization path.

### `GET /api/sessions/:id/attachments/:attachment_id/blob`

Returns raw attachment bytes with the stored MIME type and
`Cache-Control: private, max-age=3600`. Metadata-only source references have
no blob and return `404` from this endpoint.

### `POST /api/sessions/:id/commands`

Runs daemon-owned builtin slash commands. Body:

```json
{"command":"compact","args":"","display_text":"/compact"}
```

`command` can also be slash text like `"/compact"`. Supported commands are
the daemon builtin commands accepted by `parse_builtin_command_request`:
`init`, `compact`, `goal`, `plan`, `lsp`, `sandbox`, `memory`, `rc` and
`remote-control`. Skill slash commands must use
`POST /api/sessions/:id/messages`.

`memory` runs the same text implementation as the TUI `/memory`
(`dispatch_memory_command`): `list [--scope=global|workspace] [--type=<t>]`,
`view <name>`, `forget <name>` (records a tombstone), `flush`, `off`, `on`
and `reload`. The result is emitted as a session system message with notice code
`memory_status`; `edit` only points to Settings > Personalization > Memory.
`/memory flush` returns immediately and, when memory summarization is on, a
second system message with code `memory_flush_done` reports the processed
observations and changed entries.

Returns `202 {"queued":true,"command":"compact"}`. Errors:

- `400 {"error":"unsupported command","command":"..."}`
- `404 {"error":"unknown session"}`
- `500 {"error":"command failed"}`

### `PUT /api/sessions/:id/expert`

Switches the selected expert component for the active session without creating
or navigating to another conversation. Body:

```json
{"expert_id":"reviewer","draft_text":"Please review the active change"}
```

The expert is resolved against the session workspace. Its prompt context and
component-scoped Skills are queued on the same worker as chat turns. An
in-flight turn therefore finishes with its existing expert; the switch is
persisted and applies before the next subsequently queued turn. `draft_text`
is optional. When present (including an empty string), the expert binding and
composer draft are persisted at that same queue boundary; omitting it preserves
the current draft.

Success returns the selected expert definition plus queue state:

```json
{
  "expert": {"id":"reviewer","display_name":"Code Reviewer"},
  "accepted": true,
  "queued": false,
  "pending": false,
  "busy": false,
  "applied": true,
  "effective_boundary": "applied",
  "control_sequence": 17,
  "receipt": {
    "sequence": 17,
    "expert_id": "reviewer",
    "state": "applied",
    "applied": true,
    "effective_boundary": "applied"
  },
  "draft_text": "Please review the active change"
}
```

For compatibility the selected expert's fields are also present at the top
level. `busy` is derived from the authoritative worker-queue receipt, not only
from the loop's transient busy flag. When a turn was already active or queued,
`pending` and `queued` are true, `applied` is false, and
`effective_boundary` is `next_turn`; that turn keeps its old prompt, Skill
registry, MCP scope, built-in-tool scope, and draft. An idle switch normally
returns `applied`; `queued_control` means the control was accepted but did not
finish within the bounded synchronous wait. All expert contexts and an
optional draft change together before any later queued chat turn. A control
callback that ran but failed to persist is not reported as applied.

Errors:

- `400` when `expert_id` is missing, `draft_text` is not a string, or the
  component is unavailable.
- `404` when the active session does not exist.
- `500` when the expert Skill context cannot be prepared or the atomic
  binding/draft update cannot be persisted.

### `DELETE /api/sessions/:id/expert`

Clears the active session's persisted expert ID and the expert chip shown by
real composers:

```json
{"detached":true,"expert_id":"","context_retained":true}
```

This is deliberately a metadata-only detach. It does not enqueue an AgentLoop
control, rebuild the system prompt or capability registries, alter the current
provider context, or invalidate KV cache. Expert instructions and capability
state that were already loaded may therefore remain effective until another
normal lifecycle boundary. A detach also supersedes any older expert switch
still queued behind an in-flight turn, so that switch cannot restore the UI
binding afterward. The current composer draft is preserved.

Errors:

- `404` when the active session does not exist.
- `500` when the cleared binding cannot be persisted.

### `GET /api/sessions/:id/permissions`

Returns the active or persisted session permission mode:

```json
{"mode":"default","description":"Prompt for write/exec tools"}
```

For a session that is not loaded yet, the persisted meta is looked up by id.
Optional `?workspace=<hash>` limits that lookup to one project; without it the
daemon searches its own cwd, every registered project and no-workspace
sessions. Unknown sessions return `404`.

### `PUT /api/sessions/:id/permissions`

Body:

```json
{"mode":"yolo"}
```

Canonical modes are `default`, `auto`, `plan`, and `yolo`. Legacy inputs
`accept-edits` and `acceptEdits` normalize to `auto` in configuration, persisted
session metadata, and responses. Switching to
`yolo` also resolves any open permission prompt with allow. Returns the same
shape as `GET`.

### `POST /api/sessions/:id/fork`

Copies a source session prefix into a new session and resumes it into the current
daemon. For a user message, the prefix ends before `at_message_id`; its plain text
is returned in `restored_prompt` for editing in the new session. For an assistant
message, the prefix includes the selected message and no prompt is returned.
It does not start a new turn. `fork_anchor_role` identifies the selected message's
role. Empty prompt text omits `restored_prompt`; attachments are not restored.

Body:

```json
{"at_message_id":"msg-123","title":"optional title"}
```

`{"whole": true}` copies the whole session instead (no `at_message_id`); the
copy ends at the last complete conversational message, so tool calls of a
running turn that have no results yet are not carried over. `fork_message_id`
and `fork_anchor_role` are then empty.

Response:

```json
{
  "session_id": "new-sid",
  "title": "Fork title",
  "forked_from": "source-sid",
  "fork_message_id": "msg-123",
  "fork_anchor_role": "user",
  "restored_prompt": "Original prompt to edit",
  "workspace_hash": "abc123",
  "cwd": "C:/repo",
  "no_workspace": false
}
```

### `POST /api/sessions/:id/file-checkpoints/:message_id/restore`

Restores workspace files to the checkpoint captured for that user turn. Chat
history is not rewound. Refuses while the session is busy.

Response:

```json
{
  "ok": true,
  "session_id": "sid",
  "message_id": "msg-123",
  "files_changed": 3,
  "errors": []
}
```

### Background tasks

Each loaded session owns a background task registry (`src/adapters/tool/background_tasks.hpp`).
Entries come from `bash` with `run_in_background` / `monitor`, from foreground commands moved
to the background (timeout, a steered user message, or `POST /background`), and from
`spawn_subagent(wait=false)` / subagent waits that were moved to the background. A finished
task posts a user-role notice with `metadata.background_task` into the session mailbox: a
running turn receives it at its next model boundary, an idle session starts a new turn.
A session that is not loaded has no background tasks; daemon shutdown or session
destruction kills running background commands.

Task object (`background_task_to_json`):

```json
{
  "id": "bg_3f2a91c0",
  "kind": "shell",
  "state": "running",
  "origin": "timeout",
  "title": "npm run build",
  "command": "npm run build",
  "cwd": "C:/repo",
  "output_file": "C:/repo/.acecode/tmp/session-sid/background/bg_3f2a91c0.log",
  "started_at_ms": 1789000000000,
  "last_output_at_ms": 1789000004000,
  "output_bytes": 2048
}
```

- `kind`: `shell` or `agent` (an agent task's `id` is the child session id, also in
  `child_session_id`).
- `state`: `running`, `completed`, `failed` (non-zero exit or launch error), `stopped`
  (`stop_reason`: `user`, `limit`, `shutdown`).
- `origin`: `requested`, `timeout`, `user_message`, `user_request`.
- Finished shell tasks add `exit_code` and `ended_at_ms`; `monitor: true` marks commands
  whose new output lines are also delivered while they run.

#### `GET /api/sessions/:id/background-tasks`

`{"session_id": "sid", "tasks": [task...]}`; an unloaded session returns an empty list.

#### `GET /api/sessions/:id/background-tasks/:task_id/output?tail=N`

`{"task": {...}, "output": "..."}` with up to `tail` bytes (default 16384, max 65536) of
the cleaned output, starting at a whole line. `404` for an unknown session or task.

#### `POST /api/sessions/:id/background-tasks/:task_id/stop`

Kills a background command's process tree, or interrupts a background subagent's turn.
`200 {"ok": true, "task_id": "..."}`; `409 {"error": "..."}` when the task is not running.
The final state arrives as a `background_task` event and a completion notice.

#### `POST /api/sessions/:id/background`

Asks the running foreground `bash` command or blocking subagent wait to hand its work to
the background registry without interrupting it. `200 {"ok": true, "busy": bool}`; `busy`
is false when no turn was running (the request has no effect then).

### Session outputs

#### `GET /api/sessions/:id/outputs[?workspace=<hash>]`

Files this conversation produced for the user to look at: documents, spreadsheets,
images, media, archives. Code changes are not outputs; they belong to the change views.
The summary panel's Outputs group is the consumer. Sources and filtering rules are in
[session-outputs.md](session-outputs.md).

```json
{
  "session_id": "sid",
  "outputs": [
    {
      "path": "C:\\work\\docs\\plan.md",
      "relative": "docs/plan.md",
      "source": "write",
      "size": 1820,
      "modified_ms": 1794300000000
    }
  ],
  "has_more": false
}
```

- Derived from the session JSONL (plus the JSONL of its subagent sessions) and checked
  against the disk on every request: files that no longer exist are omitted. The scan
  is incremental per file, so polling is cheap.
- Ordered by file modification time, newest first, at most 50; `has_more` is true when
  more exist.
- `path` is absolute. For files inside a session folder it is spelled with that folder's
  own form (the one the client already knows as the workspace cwd) and `relative` is the
  path below that folder with forward slashes; outside every session folder `relative`
  is empty.
- `source`: `write` (`file_write`), `patch` (`apply_patch` added file), `shell` (found
  after a `bash` command finished).
- Works for sessions that are not loaded: `workspace` is the same lookup hint as on the
  history route. An unknown session returns an empty list, not `404`.

---

## 6. Opencode Import and Pins

### `GET /api/workspaces/:hash/opencode-import`

Previews importable opencode sessions:

```json
{
  "available": true,
  "count": 2,
  "source_database": "...",
  "error": "",
  "sessions": [
    {
      "id": "opencode-id",
      "title": "Title",
      "directory": "C:/repo",
      "provider": "openai",
      "model": "gpt-4.1",
      "archived": false,
      "time_created_ms": 0,
      "time_updated_ms": 0,
      "time_archived_ms": 0,
      "message_count": 10,
      "part_count": 20,
      "source_database": "..."
    }
  ]
}
```

### `POST /api/workspaces/:hash/opencode-import`

Starts an async import. Body is optional:

```json
{"session_ids":["opencode-id-1","opencode-id-2"]}
```

Returns `202` job status:

```json
{
  "job_id": "job-id",
  "workspace_hash": "abc123",
  "state": "pending",
  "imported": 0,
  "total": 2,
  "failed": 0,
  "skipped": 0,
  "current_title": "",
  "error": "",
  "session_ids": []
}
```

### `GET /api/workspaces/:hash/opencode-import/:job_id`

Polls the same status object. Returns `404` for unknown workspace or job.

### `GET /api/workspaces/:hash/pinned-sessions`

Returns:

```json
{"workspace_hash":"abc123","cwd":"C:/repo","session_ids":["sid-1"]}
```

The daemon prunes ids that no longer exist or are archived.

### `PUT /api/workspaces/:hash/pinned-sessions`

Body:

```json
{"session_ids":["sid-1","sid-2"]}
```

Normalizes, prunes, persists, and echoes the same shape as `GET`.

### `GET /api/no-workspace/pinned-sessions`

Returns the ordered pin state for main sessions created without a workspace:

```json
{
  "no_workspace": true,
  "pin_scope": "__no_workspace__",
  "session_ids": ["task-1"]
}
```

The state is stored under the no-workspace cache root. The daemon prunes ids
that are missing, archived, workspace-owned, or background child sessions.

### `PUT /api/no-workspace/pinned-sessions`

Body:

```json
{"session_ids":["task-1","task-2"]}
```

Normalizes, prunes, persists, and echoes the same shape as `GET`.

### `GET /api/pinned-sessions/order`

Returns the global ordering across registered workspaces and no-workspace
tasks. No-workspace items use the reserved `__no_workspace__` pin scope; this
value is not a workspace registration or a session `workspace_hash`:

```json
{
  "items": [
    {"workspace_hash":"__no_workspace__","session_id":"task-1"},
    {"workspace_hash":"abc123","session_id":"sid-1"}
  ]
}
```

### `PUT /api/pinned-sessions/order`

Body:

```json
{"items":[{"workspace_hash":"abc123","session_id":"sid-1"}]}
```

Normalizes, prunes unavailable pinned items, persists, and echoes the same
shape as `GET`.

### `POST /api/session-batch`

Applies one sidebar action to many sessions in a single request. Each pin file,
the global pin order and each workspace attention file are written at most
once. Items are processed independently: a failing item does not stop the
others, and the response is `200` with per-item results. Only a malformed
request (unknown action, empty or oversized `items`, invalid id) returns `400`.

Body:

```json
{
  "action": "pin",
  "items": [
    {"session_id":"sid-1","workspace_hash":"abc123"},
    {"session_id":"task-1","no_workspace":true},
    {"session_id":"sid-2","workspace_hash":"abc123","cursor":42}
  ]
}
```

- `action`: `pin`, `unpin`, `archive`, `unarchive`, `read` or `unread`.
- `items`: 1–500 entries in visible sidebar order. `session_id` must match
  `[A-Za-z0-9_-]{1,128}`. No-workspace tasks set `no_workspace:true` (the pin
  scope `__no_workspace__` is also accepted as `workspace_hash`). Duplicate
  scope + id pairs are ignored. `cursor` is used only by `read`, with the same
  meaning as the WebSocket `mark_session_read` cursor.

Semantics:

- `pin` inserts sessions that are not yet pinned at the top in request order
  (the first item ends up first) and leaves already pinned sessions where they
  are, both in the scope pin list and in the global order. Sessions that cannot
  be pinned (missing, archived, subagent) fail with `session cannot be pinned`.
- `unpin` removes the items from their scope lists and the global order.
- `archive` / `unarchive` follow the single-item archive routes, including the
  subagent `409` rule (reported as a per-item error). Archived sessions are
  removed from pin lists and the global order in the same request.
- `read` / `unread` follow the WebSocket `mark_session_read` /
  `mark_session_unread` messages and still broadcast `session_status` for
  sessions whose state changed.

Response:

```json
{
  "action": "pin",
  "succeeded": 2,
  "failed": 1,
  "results": [
    {"session_id":"sid-1","workspace_hash":"abc123","no_workspace":false,"ok":true},
    {"session_id":"task-1","workspace_hash":"","no_workspace":true,"ok":true},
    {"session_id":"gone","workspace_hash":"abc123","no_workspace":false,"ok":false,
     "error":"session cannot be pinned"}
  ],
  "pinned_scopes": [
    {"pin_scope":"abc123","session_ids":["sid-1","sid-0"]},
    {"pin_scope":"__no_workspace__","session_ids":["task-1"]}
  ],
  "pinned_order": {"items":[{"workspace_hash":"abc123","session_id":"sid-1"}]}
}
```

`pinned_scopes` and `pinned_order` are present when pins changed (`pin`,
`unpin`, `archive`). Archive results carry `session` (the updated session meta,
same shape as the single archive route); read/unread results carry `status`
(the `session_status` payload).

---

## 7. Files

Directory listing validates `cwd` against the daemon cwd and registered
workspace cwds. Authenticated text and binary file-detail requests may resolve
any local file path readable by the daemon process: `cwd` must be absolute,
while `path` may be relative to `cwd` or an absolute target. The target is
canonicalized before the existing file checks run. This preview-only behavior
does not make an external parent directory listable via `/api/files` and does
not authorize Git or other workspace routes for that directory.

### `GET /api/files?cwd=<abs>&path=<rel>&show_hidden=1&show_noise=1`

Lists direct children:

```json
[
  {"name":"src","path":"src","kind":"directory","modified_ms":1783152000000},
  {"name":"README.md","path":"README.md","kind":"file","size":1234}
]
```

`show_hidden=1` includes dot-prefixed entries. `show_noise=1` additionally
includes directories normally hidden from the SidePanel tree such as `.git`,
`node_modules`, `build`, and `target`; the TUI/Desktop `@` path-reference picker
uses both flags so a bare `@` reflects the complete direct contents of the
current cwd. Enumeration remains non-recursive and all returned paths are still
canonicalized within the allowed cwd.

### `GET /api/files/content?cwd=<abs>&path=<rel-or-abs>`

Returns `text/plain; charset=utf-8` file content. Error status examples:

- `400` missing parameters or a non-absolute/invalid `cwd`
- `404` not found
- `415` binary or too large
- `500` IO error

For any workspace or no-workspace session, `cwd` may be the file's containing
directory and `path` its basename. A caller may also keep its current absolute
`cwd` and pass an absolute `path` elsewhere on the local machine. The endpoint
does not require either target to be a registered workspace, but still requires
daemon authentication and remains subject to the 5 MiB text cap, binary sniff,
filesystem permissions, and read-only response behavior.

### `POST /api/files/export`

Authenticated request `{ "cwd": "<abs>", "path": "<rel-or-abs>" }`.
Uses the same path resolution as file preview, including allowed absolute
files outside the workspace. Requires the native file save picker (501 when
unavailable). The picker suggests the original filename and allows all file
types; the destination comes exclusively from the user's native dialog.
Copies current bytes without encoding conversion or a JavaScript size cap.
Returns `{ "ok": true, "cancelled": false, "filename": "..." }`, or
`{ "ok": true, "cancelled": true }` without writing when cancelled.
Missing sources return 404; invalid destinations return 400; picker/read/write
failures return 500. Saving to the same file is a successful no-op.

### `GET /api/files/blob?cwd=<abs>&path=<rel-or-abs>[&download=1]`

With `download=1`, accepts any file type and returns the original bytes as
`application/octet-stream` with `Content-Disposition: attachment`. Authentication,
path resolution, and the existing 20 MiB limit remain the same. Without this
flag, the preview MIME allowlist remains unchanged.

Returns raw bytes for browser-native preview types:

- images: `png`, `jpg`, `jpeg`, `gif`, `webp`, `bmp`, `ico`, `svg`
- documents: `pdf`, `docx`, `xlsx`, `xlsm`, `pptx`

The route caps preview bytes at 20 MB and sets `X-Content-Type-Options:
nosniff`. It uses the same arbitrary-local-path resolution and authentication
boundary as the text-content endpoint; the external parent directory remains
unavailable to `/api/files` and Git routes.

### `GET /api/files/editable?cwd=<abs>&path=<rel-or-abs>`

Desktop-only authenticated read endpoint for the file editor. Unlike the
read-only `/api/files/content` preview route, both `cwd` and the resolved file
must stay inside a registered workspace (including its current worktree). The
target must be an existing regular text file no larger than 5 MiB.

The response returns normalized UTF-8/LF editor text plus the metadata needed
for a lossless save:

```json
{
  "text": "# Notes\n",
  "read_id": "...",
  "encoding": "utf-8",
  "line_ending": "crlf",
  "has_bom": true,
  "size": 12
}
```

### `PUT /api/files/editable`

Safely replaces the same Desktop workspace file. The JSON body is
`{"cwd":"<abs>","path":"<rel-or-abs>","text":"...","read_id":"..."}`.
The server revalidates the workspace boundary and current file bytes before
writing. If the file changed after the matching GET, it returns `409` without
overwriting either version. A successful write preserves the detected
encoding, BOM, and dominant line-ending style, uses the common safe-write
path, invalidates Git snapshots, and clears the Agent file-read baseline so a
later Agent edit must read the human-authored version first. This route is not
registered on standalone Web daemons.

### `GET /api/fs/roots`

Browsable roots for the Web path picker (openspec `add-web-path-picker`). The
picker is the browser-side replacement for the native folder and file dialogs
that only a Desktop-launched daemon can show. It browses the daemon host's own
filesystem, so every path below is a path on the machine running the daemon.

```json
{
  "host": "DESKTOP-SHAO",
  "os": "windows",
  "home": "C:/Users/shao",
  "roots": [
    {"path": "C:/", "label": "Windows", "drive_type": "fixed",
     "total_bytes": 511000000000, "free_bytes": 195000000000}
  ],
  "quick": [
    {"kind": "home", "path": "C:/Users/shao"},
    {"kind": "desktop", "path": "C:/Users/shao/Desktop"},
    {"kind": "projects", "path": "C:/Users/shao/.acecode/workspaces"}
  ],
  "workspaces": [
    {"hash": "0123456789abcdef", "name": "acecode", "path": "N:/Users/shao/acecode"}
  ]
}
```

`roots` lists every logical drive on Windows (`drive_type` is `fixed`,
`removable`, `remote`, `cdrom`, or `ramdisk`; remote drives carry no label or
capacity because probing a disconnected mapped drive can block), `/` on POSIX
(`drive_type: "root"`), plus the direct children of `/Volumes` on macOS
(`drive_type: "volume"`). `label`, `total_bytes`, and `free_bytes` are omitted
when unavailable. `quick` entries of kind `desktop` and `projects` appear only
when those directories exist. `os` is `windows`, `macos`, or `linux`. All
paths use forward slashes; drive roots keep their trailing slash (`C:/`).

### `GET /api/fs/list?path=<abs>&show_hidden=1`

Lists the direct children of any absolute directory readable by the daemon
process. Unlike `/api/files`, there is no workspace whitelist: any
authenticated client (loopback without a token, or a remote client with a valid
token) may browse the whole filesystem. The route is read-only and logs every
listing with its path.

```json
{
  "path": "C:/Users",
  "parent": "C:/",
  "truncated": false,
  "entries": [
    {"name": "shao", "path": "C:/Users/shao", "kind": "dir",
     "modified_ms": 1783152000000, "hidden": false, "link_target": "N:/Users/shao"},
    {"name": "desktop.ini", "path": "C:/Users/desktop.ini", "kind": "file",
     "size": 174, "modified_ms": 1783152000000, "hidden": true}
  ]
}
```

- `path` is the request path after lexical normalization only (`\` becomes
  `/`, `..` segments fold, the drive letter is upper-cased, a trailing slash is
  dropped except on a root). Junctions and symlinks are **not** resolved:
  browsing `C:/Users/shao` on a machine where that directory is a junction to
  `N:/Users/shao` keeps returning `C:/Users/shao/...` paths, matching what the
  native dialog returns so the same directory registers the same workspace
  hash.
- `parent` is empty when `path` is a drive or filesystem root.
- Entries are sorted directories first, then case-insensitively by name.
  Directory entries never carry `size`. `link_target` is present for junction
  or symlink directories whose target can be read. Noise directories such as
  `node_modules` or `build` are **not** filtered.
- Hidden entries (dot-prefixed, or carrying the Windows HIDDEN or SYSTEM
  attribute) are omitted unless `show_hidden=1`; when included they carry
  `hidden: true`.
- At most 5000 entries are returned; `truncated: true` marks a longer
  directory.

Errors: `400 {"error":"path must be absolute"}` for an empty or relative
`path`; `404 {"error":"not found"}` and `404 {"error":"not a directory"}`;
`403 {"error":"permission denied"}` when the daemon cannot read the directory;
`500 {"error":"io error"}` otherwise. Error bodies may add a `detail` string.

### `GET /api/git/info?cwd=<abs>`

Returns git repository info for a workspace cwd (openspec `add-git-context`).
`cwd` must be an allowed workspace path (same whitelist as `/api/files`);
unknown cwd yields `400 {"error":"unknown workspace"}`.

Non-repo cwd (or `config.git_context.enabled=false`):

```json
{"is_repo": false}
```

Git repository:

```json
{
  "is_repo": true,
  "branch": "master",
  "default_branch": "master",
  "default_base": "origin/master",
  "branches": ["dev", "master"],
  "remote_branches": ["origin/dev", "origin/master"],
  "dirty": false
}
```

- `branch` is `"HEAD"` when detached.
- `default_base` is the verified `origin/<default_branch>` ref, or an empty
  string when no such locally fetched remote-tracking ref exists.
- `branches` contains local branch short names. `remote_branches` contains
  locally available remote-tracking short names and omits symbolic aliases
  such as `origin/HEAD`; collecting either list performs no network fetch.
- `dirty` reflects tracked changes only (`status --porcelain -uno`);
  untracked files do not set it.
- All git subprocesses are read-only, use `--no-optional-locks`, and honor
  `config.git_context.timeout_ms` (timeout degrades to `{"is_repo": false}`
  semantics for the failing fields rather than erroring).

### `POST /api/git/checkout`

Body `{"cwd": "<abs>", "branch": "<local branch>", "stash": false}`
(openspec `add-webui-git-session-pill`). Safety gates, in order:

- `400` unknown workspace / git context disabled / invalid branch name
- `409 {"error":"busy"}` — any session of that workspace has a turn running;
  no git mutation happens
- `409 {"error":"dirty","files":[...]}` — tracked changes exist and `stash`
  is not true; the client should confirm with the user then retry with
  `stash: true`
- `stash: true` runs `git stash push --include-untracked -m "ACECode
  auto-stash"` before checkout (untracked files are preserved in the stash)
- `409 {"error":"checkout failed","detail":...}` — git refused (conflicts);
  stashed changes stay in the stash
- `200 {"ok":true,"branch":...}` — success; cached gitStatus prompt
  snapshots of that workspace's sessions are invalidated

### `GET /api/git/changes?cwd=<abs>&base=<ref>`

Working tree (including uncommitted changes) vs `base`
(openspec `redesign-sidepanel-git-changes`). `base` must be `HEAD` or an
allowlist-safe ref name that resolves via `rev-parse --verify`; anything else
is `400 {"error":"invalid base"}`.

```json
{
  "branch": "master",
  "base": "origin/master",
  "files": [
    {"path":"src/a.cpp","status":"M","additions":95,"deletions":36},
    {"path":"new.txt","status":"A"},
    {"path":"img.png","status":"M","binary":true}
  ],
  "total_additions": 314,
  "total_deletions": 47,
  "total_count": 5,
  "truncated": false
}
```

- Combines `diff --numstat` + `diff --name-status` (joined by path; renames
  reported at the new path) plus untracked files (status `A`, no counts).
- The list caps at 200 entries; `truncated: true` with the full
  `total_count` when exceeded. Totals always reflect the full diff.
- `504 {"error":"git timeout"}` when git exceeds 2× `git_context.timeout_ms`.

### `GET /api/git/diff?cwd=<abs>&path=<rel>&base=<ref>`

Single-file unified patch (`git diff <base> -- <path>`); untracked files get
a synthesized new-file patch via `diff --no-index`. `path` is canonicalized
and prefix-checked against `cwd` (`400` outside the workspace). Patches over
1 MB return `413 {"error":"diff too large"}`. Response: `{"patch": "..."}`.

---

## 8. Commands, Skills, and Hooks

### `GET /api/commands?workspace=<hash>`

Skill entries include `path` and `mention` (the canonical linked explicit-skill
reference) for stable inline selection; `/api/skills` includes the same fields
for filesystem-backed entries.

Returns builtin slash commands. A non-empty `workspace` hash also returns
project commands plus merged workspace/global skills. An explicitly empty
query (`/api/commands?workspace=`) represents no-workspace input and returns an
empty `commands` array plus enabled global skills only:

```json
{
  "builtins": [
    {"name":"init","description":"Analyze this codebase and generate (or improve) AGENTS.md"},
    {"name":"compact","description":"Compress conversation history"},
    {"name":"goal","description":"Create, view, pause, resume, edit, or clear the thread goal"},
    {"name":"plan","description":"Enter plan mode or start planning a described task"},
    {"name":"remote-control","description":"...","aliases":["rc"]}
  ],
  "skills": [
    {"name":"my-skill","description":"..."}
  ]
}
```

A builtin's aliases are listed in its optional `aliases` array instead of as
separate entries; the slash picker shows one row per command and appends the
alias in parentheses only when the typed query matches that alias (for example
`remote-control (rc)`). `POST /api/sessions/:id/commands` still accepts both
the name and its aliases.

For backward compatibility, omitting the `workspace` query entirely returns
the builtin-only response and omits both `commands` and `skills`.

### Expert components

`GET /api/experts?workspace=<hash>` returns:

```json
{
  "experts": [
    {
      "id": "code-reviewer",
      "version": "1.0.0",
      "type": "agent",
      "display_name": "Code Reviewer",
      "profession": "Review engineer",
      "description": "Reviews changes before delivery.",
      "avatar_url": "/api/experts/code-reviewer/avatar?workspace=abc123",
      "state_avatar_urls": {
        "working": "/api/experts/code-reviewer/avatar?workspace=abc123&state=working",
        "needs_attention": "/api/experts/code-reviewer/avatar?workspace=abc123&state=needs_attention",
        "idle": "/api/experts/code-reviewer/avatar?workspace=abc123&state=idle"
      },
      "default_init_prompt": "Review the active change.",
      "tags": ["开发", "质量"],
      "expertise": ["架构审查", "回归风险"],
      "quick_prompts": ["Review this change", "Check tests"],
      "created_at": "2026-07-25T09:00:00Z",
      "updated_at": "2026-07-25T09:05:00Z",
      "capabilities": {
        "skills": ["review-checklist"],
        "mcp_servers": ["github"],
        "tools": ["file_read", "AskUserQuestion"]
      },
      "lead_agent_id": "lead",
      "member_agent_ids": [],
      "references_existing_experts": false,
      "lead_expert_id": "",
      "member_expert_ids": [],
      "agents": [
        {
          "id": "lead",
          "display_name": "Code Reviewer",
          "profession": "Review engineer"
        }
      ],
      "source": "global",
      "managed_global": true
    }
  ],
  "diagnostics": [],
  "workspace_hash": "...",
  "cwd": "C:/repo",
  "global_root": "C:/Users/me/.acecode/experts"
}
```

`GET /api/experts/:id?workspace=<hash>` returns the same definition and adds
the selected Agent's `instructions` plus a `state_avatars` object containing
only safe package-relative paths for the configured `working`,
`needs_attention`, and `idle` images. List responses intentionally omit
instructions and `state_avatars`. Neither response exposes the package root,
resolved avatar filesystem paths, or Skill-root paths. `avatar_url` is empty
when no main avatar is configured. `state_avatar_urls` contains each state
that has an effective image: the configured state image, or the main avatar
when that state is not configured.

Definitions and their `agents` also include `avatar_identity`, a stable key for
the shared virtual-office pixel portrait. Clients use it when `avatar_url` is
empty. Session expert presentation carries the corresponding selected member's
identity and custom avatar URL, so spawning a new session does not change the
expert's pixel appearance. Built-in experts use pixel portraits; user-supplied
image and state-image endpoints keep their existing behavior.

`GET /api/experts/:id/avatar?workspace=<hash>` serves the main avatar.
Appending `&state=working`, `&state=needs_attention`, or `&state=idle` serves
that state image and falls back to the main avatar if the state file becomes
unavailable during the read. Unknown state names return
`400 INVALID_AVATAR_STATE`. The endpoint serves only PNG, JPEG, GIF, WebP,
BMP, or ICO images contained inside the resolved expert package (maximum
8 MiB), returns `404` for missing, escaped, unsupported, or oversized files,
and preserves GIF response bytes with `Content-Type: image/gif`.

`POST /api/experts?workspace=<hash>` creates a managed global component;
`PUT /api/experts/:id?workspace=<hash>` updates one. Both accept the fields
above using snake-case request names. A single expert supplies
`instructions` (or a `lead` object). A team supplies one
`lead_expert_id` and a non-empty `member_expert_ids` array referencing
installed single experts. Both types may supply `state_avatars` with any of
the three fixed state keys and existing package-relative image paths. Omitting
`state_avatars` preserves all state-avatar data; a supplied object
authoritatively replaces the three known keys, and an empty object clears
their references while retaining image files and unknown manifest extension
keys. Workspace-sourced packages are read-only through these routes. Updates
merge managed fields into the existing package and keep avatar configuration,
packaged Skills, resources, and unknown manifest fields, including unknown
nested Agent and `teamInfo` fields. The managed
capability keys are authoritative on update: an omitted key means inherit, an
empty array means allow none, and a non-empty array is an exact allowlist;
unknown keys under `capabilities` are preserved. The
`DELETE /api/experts/:id?workspace=<hash>` route removes only a managed global
package.

Creating an ID shadowed by a workspace package returns
`409 WORKSPACE_EXPERT_READ_ONLY`; creating an existing managed global ID
returns `409 EXPERT_ALREADY_EXISTS`. Updating or deleting a workspace-sourced
package also returns `409 WORKSPACE_EXPERT_READ_ONLY`.

Expert definitions and create/update payloads also support `sampling`:
`{"temperature":0.3,"top_p":0.95,"top_k":20,"min_p":0}`. Each key is optional.
Updates that omit `sampling` preserve the stored preset; `null` or `{}` clears it.
For a single expert, the response includes its lead's effective preset; explicit
updates replace that complete preset, removing any package-authored lead override.
Team updates change team defaults and leave referenced experts' presets intact.
Unknown sampling keys, invalid types and out-of-range values are rejected. Generic
ranges match saved models; actual provider/protocol support is checked when the
expert is selected or a session is created. A team's preset supplies defaults;
each referenced expert's preset overrides its fields. The `agents[].sampling`
response describes the effective expert preset for that member. Session-local
sampling supplied by `spawn_subagent` or `agent_spawn` has highest priority and
is persisted independently of saved model settings. Expert switching publishes
the new sampling settings at the same control boundary as the role; an
incompatible switch keeps the existing role and provider.

Each of `capabilities.skills`, `capabilities.mcp_servers`, and
`capabilities.tools` is independently optional:

- missing key: inherit all capabilities available under global policy;
- empty array: allow none of that capability class;
- non-empty array: exact-name expert allowlist. For known installed Skills and
  configured MCP servers, this explicit list overrides the daemon-global
  allowed/disabled default.

Unknown or temporarily unavailable IDs remain persisted so the editor can
show the saved choice and its unavailable state. A referenced expert team
does not merge capability lists; every member executes under that member
expert's own scopes. The manifest's top-level `skills` field remains package
content metadata and is not the capability selection field. Expert precedence
does not bypass tool permission approval, permission/Plan/Dangerous mode,
sandboxing, credentials, or runtime availability, and it does not synthesize
an uninstalled Skill, unconfigured MCP server, or unregistered local tool.

`GET /api/experts/capabilities?workspace=<hash>` returns the read-only,
runtime-backed selection catalog:

```json
{
  "skills": [
    {
      "id": "review-checklist",
      "description": "Review checklist",
      "source": "project",
      "available": true,
      "globally_enabled": true,
      "default_enabled": true,
      "expert_selectable": true,
      "configurable": true,
      "status": "available",
      "disabled_reason": ""
    }
  ],
  "mcp_servers": [
    {
      "id": "github",
      "description": "",
      "transport": "stdio",
      "available": true,
      "globally_enabled": true,
      "default_enabled": true,
      "expert_selectable": true,
      "configurable": true,
      "runtime_available": true,
      "status": "connected",
      "disabled_reason": "",
      "tool_count": 3
    }
  ],
  "tools": [
    {
      "id": "file_write",
      "description": "Write a file",
      "available": true,
      "globally_enabled": true,
      "default_enabled": true,
      "expert_selectable": true,
      "status": "available",
      "disabled_reason": "",
      "configurable": true,
      "read_only": false
    }
  ]
}
```

`default_enabled` drives inherited checkbox state. `expert_selectable` may
remain true when `globally_enabled` and `available` are false, which lets an
expert explicitly enable a known Skill or configured MCP server. Dispatching
such an expert can start that MCP server without changing its global disabled
default; inheriting sessions continue to filter it out. MCP entries expose only
server ID, safe transport, runtime state, and tool count; command lines,
arguments, environment variables, URLs, headers, authorization tokens, and
connection error text are never returned. Tool IDs are exact registered
built-in names; MCP tools are selected by their exact owning server ID instead
of by parsing a qualified tool name.

### `GET /api/skills/root?workspace=<hash>`

Returns the effective skill directory:

```json
{
  "path": "C:/repo/.acecode/skills",
  "source": "project_acecode",
  "global_path": "C:/Users/me/.acecode/skills",
  "workspace_hash": "abc123",
  "cwd": "C:/repo"
}
```

With default scanning, `source` is `project_acecode`, `project_agent`, or
`global_acecode`, and `global_path` points at the active ACECode data
directory's `skills` folder. With custom scan paths, `path` is the first
configured project root (or the first global root if none), `global_path`
is the first global root, and `source` is `project_configured` or
`global_configured`. An unconfigured scope returns an empty path. Custom
roots are not created by this request.

### `GET /api/config/skill-paths`

Returns `{ "paths": [".acecode/skills", "${ACECODE_DATA_DIR}/skills"],
"default_paths": [...], "customized": true }` (illustrative custom list).
`paths` is the editable effective list; defaults honor legacy
`skills.reuse_opencode` and `skills.external_dirs`.

### `PUT /api/config/skill-paths`

Body: `{ "paths": [".acecode/skills", "~/.codex/skills"] }`.
Persists `skills.scan_paths` and refreshes daemon and existing session
skill registries (session prompt snapshots apply at the control boundary).
Returns the same shape as GET. Requires normal API authorization; returns
400 for invalid input, 500 for persistence failure, and 409 during data
directory migration. Failed validation/persistence leaves active paths intact.

- Missing/null `skills.scan_paths` preserves legacy scanning exactly.
  PUT `{ "paths": null }` restores this default behavior.
- An explicit list replaces all ordinary defaults and legacy external roots;
  an empty list disables ordinary scanning without deleting skills.
- Entries are searched in list order; first skill name wins. Each relative
  entry expands from the selected workspace through ancestors, excluding HOME
  (or up to the filesystem root if HOME is not an ancestor). Global entries
  remain global when no workspace is selected.
- Absolute paths, `~`, and `${ENV}` are supported. `${ACECODE_DATA_DIR}` resolves
  to the active data directory; `${XDG_CONFIG_HOME}` / `${XDG_CACHE_HOME}` fall
  back to `~/.config` / `~/.cache`. Unset other variables are skipped.
- Expert package skill roots retain priority. Allow/disable/platform policies
  and seed installation locations are unchanged.

### `GET /api/skills?workspace=<hash>`

Returns an array, not a wrapper:

```json
[
  {
    "name": "skill-name",
    "command_key": "/skill-name",
    "description": "...",
    "category": "custom",
    "enabled": true,
    "source": "project"
  }
]
```

The list is a full rescan of the workspace's project scan roots plus the
global scan roots, so disabled skills keep their real `description` and
`source`. `source` is `"project"` (discovered under the workspace's project
chain — `.acecode/skills` / `.agent/skills` walking up to, but not
including, HOME) or `"global"` (user-global roots and
`config.skills.external_dirs`). `workspace` is optional; without it the
daemon's compatibility workspace (its own cwd) is used.

When `skills.scan_paths` is configured, the same ordered resolution used by
runtime discovery determines duplicate selection; relative entries are
classified as project roots and absolute entries as global roots.

Only discovered skills are listed. A skill whose `SKILL.md` was deleted or
whose directory is outside the effective scan scope disappears on refresh,
even if its name remains in `config.skills.disabled`. Listing does not prune
disable preferences: a skill restored later (or discovered in another
workspace) still appears with `enabled:false`.

### `PUT /api/skills/:name?workspace=<hash>`

Body:

```json
{"enabled":false}
```

Returns `{"name":"skill-name","enabled":false}`.

`workspace` is optional and only affects the "known skill" validation: the
daemon's global registry only scans the daemon cwd's project chain, so
toggling a project skill that belongs to another workspace requires passing
that workspace's hash (the handler rescans that workspace's cwd to find the
skill). The disabled list itself is global config either way.

### `GET /api/skills/:name/body`

Returns `text/markdown; charset=utf-8` containing `SKILL.md`. Returns `404`
when the skill is not enabled/registered.

### Hook routes

| Method | Path | Behavior |
|---|---|---|
| GET | `/api/hooks` | returns current hook registry snapshot |
| POST | `/api/hooks/refresh` | reloads hook trust store and hook registry |
| POST | `/api/hooks/:id/trust` | persists trust for the hook definition |
| POST | `/api/hooks/:id/disable` | disables hook unless it is managed |
| POST | `/api/hooks/:id/enable` | enables hook |

Mutating hook routes return the refreshed hook registry snapshot. Managed hooks
cannot be disabled and return `409 {"error":"HOOK_MANAGED"}`.

---

## 9. Models and Managed Provider Auth

### `GET /api/models`

返回所有运行时已启用的模型配置。该路由要求通过 Web 认证，响应包含 `api_key`
原值和 `has_api_key` 布尔值，供编辑表单默认遮罩回填；调用方必须把整个响应视为
敏感数据，日志与错误消息仍不得包含密钥。高级字段有值时会原样返回，包括
`endpoint_mode`、`api_protocol`、`max_output_tokens`、`capabilities_source`、`reasoning`、
`sampling`、`request_headers`、`context_window` 与 `stream_timeout_ms`。

返回前会检查 `config.json`：内容与上次读取不同（例如用户直接手改了文件）时，先把
`saved_models`、`default_model_name` 与 `default_permission_mode` 读进运行中的 daemon，
模型列表有结构变化就推进 saved-model revision，已打开的会话在下一条消息前换用新配置。
文件不是合法 JSON 或校验失败时只记一次日志，保留当前配置。输入框的「刷新模型列表」
按钮依赖这一点：点一次就能看到磁盘上的新配置。

### `POST /api/models`

新增模型配置。请求体为 saved model draft，例如：

```json
{
  "name": "gateway-gpt",
  "provider": "openai",
  "model": "gpt-4.1",
  "base_url": "https://example.com/v1",
  "api_key": "{env:OPENAI_API_KEY}",
  "endpoint_mode": "base_url",
  "max_output_tokens": 32768,
  "request_headers": {"X-Team":"acecode"},
  "context_window": 128000,
  "stream_timeout_ms": 600000,
  "capabilities": ["vision", "tool_use", "reasoning"],
  "capabilities_source": "catalog",
  "reasoning": {
    "supported": true,
    "mandatory": false,
    "default_enabled": true,
    "enabled": true,
    "supported_efforts": ["low", "medium", "high"],
    "default_effort": "medium",
    "effort": "high",
    "supports_max_tokens": false
  },
  "sampling": {"temperature": 1, "top_p": 0.95, "top_k": 20, "min_p": 0}
}
```

`sampling` 是可选的采样参数对象，四个键都可省略或为 `null`（视为未设置）：
`temperature` ∈ [0, 2]、`top_p` ∈ (0, 1]、`top_k` 为正整数、`min_p` ∈ [0, 1]。
未设置的键不会出现在发往模型服务的请求体里，沿用服务端默认值；整个对象省略或
没有任何已设置的键时，请求体与不支持该功能的版本完全一致。支持范围按 Provider /
API 协议区分：OpenAI Chat Completions 四个都发送（`top_k` / `min_p` 是 vLLM、
SGLang 等推理服务的扩展字段，官方 OpenAI 接口会拒绝）；Responses 只支持
`temperature` / `top_p`；Anthropic 支持 `temperature`（上限 1）、`top_p`、`top_k`，
不支持 `min_p`；Copilot / Grok 托管 Provider 不接受采样参数。越界值或当前 Provider /
协议不支持的键返回 `INVALID_SAMPLING`，托管 Provider 返回 `UNSUPPORTED_MODEL_OPTION`。
响应只返回已设置的键。

`api_protocol` 仅适用于 `provider:"openai"`，接受 `chat_completions` 或
`responses`；省略时，目录身份 `models_dev_provider_id:"acemodel"` 使用 Responses，
其他 OpenAI 配置继续使用 Chat Completions。模型设置的 **API 协议** 下拉框可
选择 Responses，保存和连接检测使用同一协议。`base_url` 模式下 Responses 会向
基础地址追加 `/responses`；`full_url` 模式直接使用给定 URL。协议由该字段决定，
不会根据 URL 或模型名称自动推断。更新时省略该字段保留原值，传 `null` 清除并恢复
该 Provider 的默认协议（ACEModel 为 Responses）；切换到其他 Provider 会清除该字段，其他 Provider 显式传入
则返回 `UNSUPPORTED_MODEL_OPTION`，未知协议值返回 `INVALID_API_PROTOCOL`。

Responses 的自动工具选择使用 `tool_choice.type:"allowed_tools"` 和 `mode:"auto"`，
允许列表仅包含本次提供的 ACECode 函数工具；模型仍可直接回答，不会被强制调用工具。
没有工具的请求显式发送 `tool_choice:"none"`，压缩请求已有的禁用工具策略保持不变。
兼容网关须支持该标准字段；拒绝时不会退回不受限制的 `auto`。
网关额外注入的托管生图、搜索等工具不属于 ACECode 本地执行链路；若仍返回未支持的
输出类型（如 `image_generation_call`），会明确报错，不再丢弃结果后显示文字成功。
生图应调用已配置的 `image_generate`，才能走本地成本确认、附件保存和展示流程。

返回包含 `api_key` 原值的模型配置。校验错误使用 `BAD_JSON`、`BAD_REQUEST` 或
`SavedModelEditError` 字符串；持久化失败会回滚内存并返回
`500 PERSIST_FAILED`。

### `PUT /api/models/:name`

更新模型配置并可重命名。省略 `api_key` 会保留原密钥；传入非空
`api_key` 会替换密钥。只有允许无认证的端点才接受
`clear_api_key:true`，否则请求失败。`credential_source_name` 可复用另一份
配置的凭据，但仅在 runtime provider、规范化 Base URL 和
`models_dev_provider_id` 完全兼容时允许；HTTP/HTTPS 默认端口会规范化，URL
路径仍区分大小写。

省略 `base_url`、`context_window`、`stream_timeout_ms`、`capabilities`、
`endpoint_mode`、`api_protocol`、`max_output_tokens`、`capabilities_source`、`reasoning`、
`sampling` 或 `request_headers` 会保留原值。显式空 `request_headers` 会清空请求头；
`sampling` 传入时整体替换（旧值中未出现的键会被清掉），传 `null` 或 `{}` 清除全部
采样参数，切换到其他 Provider 时同样清除；其余高级字段传 `null` 时按各字段合同清除。外部登录器留下的 legacy `readonly:true` 只是
兼容元数据，不阻止编辑。响应包含 `api_key` 原值与 `has_api_key`，并仅允许经
Web 认证的调用方读取。

### `DELETE /api/models/:name`

Removes a saved model profile. If a busy active session is using the profile,
returns `409 MODEL_IN_USE`. On success:

```json
{"ok":true}
```

### `POST /api/models/reasoning/refresh`

认证后将全部已保存且可使用 OpenAI 兼容 `/models` 探测的连接加入后台同步队列，立即返回 `202 {"accepted":true}`，不等待远端请求。同一端点、凭据、请求头和目录身份的模型合并探测；完整聊天 URL、Anthropic 和受管 Provider 不套用此协议。

Web/Desktop 服务启动后自动执行一次；模型新增或编辑保存成功后自动排队同步该模型。同步不阻塞启动、保存或界面操作；失败、缺失模型及缺失/非法声明静默保留已有配置，不自动重试。

有效声明只更新推理档位、默认值及对应能力标记，保留用户显式 `enabled`、仍有效的 `effort` 与预算设置，以及其他模型字段。请求过程中被编辑、重命名或删除的条目不接受旧响应。无实际变化时不写入配置。

持久化成功后发布模型版本并在安全边界刷新会话，同时向已认证 WebSocket 连接广播：

```json
{"type":"model_profiles_updated","payload":{"names":["ACEModel-moonlight"]}}
```

事件不包含密钥或远端错误。客户端收到事件或连接恢复后重读本地列表和会话模型状态；模型设置的刷新按钮调用此接口，无需进入探测弹窗重新选择模型。

### `POST /api/models/test`

Tests one OpenAI-compatible or Anthropic model using the current unsaved draft.
Requires the same authentication as model management. Accepts the model mutation
fields (`provider`, `model`, `base_url`, `api_key`, `request_headers`,
`endpoint_mode`, and supported advanced options). The display `name` is optional
and ignored, so a conflicting or unfinished preset name does not block testing.

```json
{"provider":"openai","model":"example-model","base_url":"https://example.com/v1","api_key":"example-key"}
```

For a new model, `credential_source_name` reuses a compatible saved credential
inside the daemon. For editing, `original_name` identifies the existing profile
and applies update semantics, including retaining an omitted API key. Validation
and merging happen on a private configuration snapshot. No configuration,
default-model setting, session history, or probe cache is saved.

The daemon sends one user message, `Reply with OK.`, with no tools or history.
It uses the existing Provider implementation and request options, with a timeout
of at most 30 seconds and no automatic retry. Multiple selections are tested
sequentially by the UI; a failure stops that batch.

Success requires non-whitespace visible reply text and no Provider error:

```json
{"ok":true}
```

Invalid drafts return `400` with a model validation code. Provider failures
return `502` with `MODEL_TEST_NETWORK`, `MODEL_TEST_HTTP_ERROR`,
`MODEL_TEST_EMPTY_REPLY`, or `MODEL_TEST_FAILED`; timeouts return
`504 MODEL_TEST_TIMEOUT`. An upstream HTTP status may be included as
`upstream_status`. Replies, credentials, exception text and raw upstream bodies
are never included in this endpoint's response.

### `POST /api/models/probe`

Probes provider model ids. OpenAI-compatible providers call upstream
`GET /models`; Copilot uses saved GitHub auth; `provider:"grok"` uses the
daemon-managed xAI OAuth credentials and the fixed Grok Build `/v1/models`
endpoint. Anthropic model ids are entered manually and are not probed. Grok
catalog parsing accepts the official `id`、`model`、`modelId` and `_meta`
fallback shapes, ignores hidden entries, preserves first-seen order, and
deduplicates model ids.

ACEModel 官方端点的内置 `starrylight`、`moonlight` 和 `aurora`
优先使用上游 `/models` 返回的有效最大上下文字段。Daemon 会将该值
原样写入 `model_context_windows`，不按本地默认值截断；字段缺失、无效
或无法解析时，才从内置目录回填 `250000` Token。探测和本地探测缓存响应
还会返回 `model_capabilities`，确保三个内置模型继续使用目录声明的
`["vision", "tool_use"]`，不会因重新探测丢失默认能力。

Success:

```json
{
  "models": ["gpt-4.1"],
  "model_context_windows": {"gpt-4.1": 1047576},
  "model_capabilities": {"gpt-4.1": ["vision", "tool_use"]},
  "model_reasoning": {"gpt-4.1": null}
}
```

#### Explicit reasoning discovery contract

An OpenAI-compatible upstream, including ACEModel, can declare controllable
reasoning in each `GET /models` entry:

```json
{
  "id": "gpt-6-astra",
  "reasoning": {
    "supported_efforts": ["low", "medium", "high", "xhigh", "max"],
    "default_effort": "high"
  }
}
```

`supported_efforts` must be a nonempty array of distinct values from `minimal`,
`low`, `medium`, `high`, `xhigh`, `max`. `default_effort` is optional and, when
present, must belong to that list. ACECode does not infer reasoning from model
names or fill in undeclared levels. Missing, empty, or invalid declarations
produce `null`, including after a previously valid declaration is removed.

Both fresh and cached probe responses contain a `model_reasoning` entry for
every returned model. Valid declarations are normalized to the saved-model
reasoning shape, with `supported:true`, `default_enabled:true`, the declared
efforts and default, and `supports_max_tokens:false`. Model settings use this
metadata to select “推理”; an ACEModel without a valid declaration is unchecked
and has no composer control. Custom models begin with reasoning disabled;
explicitly checking “推理” initializes an editable `low`, `medium`, `high` list.

Enabled generic OpenAI-compatible Chat Completions requests send
`reasoning_effort` only when an explicit or declared default effort exists.
Disabling reasoning or omitting its configuration omits that request field.
Existing Anthropic and OpenRouter request encodings remain provider-specific.

Errors include `COPILOT_AUTH_REQUIRED`, `GROK_AUTH_REQUIRED`,
`GROK_AUTH_EXPIRED`, `GROK_MODELS_UNREACHABLE`, `GROK_MODELS_HTTP_ERROR`,
`GROK_MODELS_BAD_JSON`, `INVALID_REQUEST_HEADER`, `PROBE_FAILED`,
`PROBE_HTTP_ERROR`, and `PROBE_BAD_JSON`.

### `GET /api/models/catalog`

只读取当前本地注册表，不触发网络请求。返回固定顶层结构：

```json
{
  "catalog": {
    "source": "bundled",
    "version": 1,
    "updated_at": "2026-08-10T00:00:00Z",
    "freshness": "bundled"
  },
  "providers": [
    {
      "id": "openai",
      "name": "OpenAI",
      "runtime_provider": "openai",
      "base_url": "https://api.openai.com/v1",
      "doc": "https://platform.openai.com/docs",
      "auth_mode": "required",
      "endpoint_editable": false,
      "model_input": "catalog",
      "api_key_env": "OPENAI_API_KEY",
      "models_dev_provider_id": "openai",
      "group": "native",
      "endpoint_modes": ["base_url"]
    }
  ]
}
```

`catalog.version` 是非负整数。`auth_mode` 只会是 `required`、`optional`、
`none` 或 `managed`。Custom OpenAI-compatible Provider 明确支持
`endpoint_modes:["base_url","full_url"]`，并要求 API Key 或兼容的
`credential_source_name`。一等自营 Provider `acemodel`（展示名 ACEModel）
返回 `default_api_protocol:"responses"`，模型设置新增和批量新增时采用该默认值，
用户可在 **API 协议** 中修改；已有明确协议选择在加载及安装器升级时保持。
ACEModel 使用与 OpenAI 相同的 OpenAI-compatible 字段，固定 Base URL 为
`https://ge.bigjuan.xyz/aceapi/v1`，`group` 为 `custom`（Web 再按 id 提到「自营模型」），查询时返回内置
`starrylight`、`moonlight` 与 `aurora`，三者本地回退 `context_window` 均为 `250000`，且默认返回 `capabilities:["vision","tool_use"]`；模型探测得到的有效服务器值优先。Copilot 与 Grok Coding Plan 使用 `managed`，分别由
ACECode 的 GitHub/xAI 设备登录与固定受管端点负责认证。普通 `xai` Provider
仍保留为 OpenAI-compatible API Key 接入；只有目录 id `grok` 使用 Coding Plan。

### `GET /api/models/catalog/:provider_id`

从指定 Provider 的本地目录进行大小写不敏感搜索。可选查询参数为 `q` 和
`limit`；默认最多返回 50 项，服务端硬上限为 100，完全匹配模型 ID 的结果优先，
其余结果稳定排序。返回结构：

```json
{
  "provider_id": "openrouter",
  "models": [
    {
      "id": "openai/gpt-4.1",
      "name": "GPT-4.1",
      "context_window": 1047576,
      "max_output_tokens": 32768,
      "capabilities": ["vision", "tool_use"],
      "reasoning": {
        "supported": false,
        "mandatory": false,
        "default_enabled": false,
        "supported_efforts": [],
        "supports_max_tokens": false
      },
      "deprecated": false,
      "input_modalities": ["text", "image"],
      "output_modalities": ["text"],
      "knowledge_cutoff": "2024-06",
      "pricing": {"input": 2.0, "output": 8.0}
    }
  ],
  "limit": 50
}
```

目录模型使用 `id`；只有推荐模板使用 `model_id`。`supported_efforts` 只会包含
`minimal`、`low`、`medium`、`high`、`xhigh`、`max`；上游的 `none` 只表示
reasoning 可关闭，`default`、`null` 等非规范值不会进入响应。

### `POST /api/models/catalog/refresh`

显式触发 models.dev 网络刷新；普通目录读取永不隐式访问网络。只有
`models_dev.allow_network=true` 时允许调用，否则返回 `403`。下载结果必须通过
最小结构校验，并至少包含 50 个 Provider、1000 个模型；下载、解析或阈值校验
失败时返回错误并继续使用最后一份有效注册表，不会安装部分结果。成功后返回与
`GET /api/models/catalog` 相同的目录摘要结构。

### `GET /api/config/default-model`

Returns:

```json
{"name":"saved-model-name"}
```

### `POST /api/config/default-model`

Body:

```json
{"name":"saved-model-name"}
```

The name must exist in `saved_models`. Success returns:

```json
{"default_model_name":"saved-model-name"}
```

### `GET /api/sessions/:id/model?workspace=<hash>`

Returns current session model state:

```json
{
  "name": "saved-model-name",
  "provider": "openai",
  "model": "gpt-4.1",
  "context_window": 128000,
  "deleted": false
}
```

The state also includes `models_dev_provider_id`, `reasoning` (the effective
saved-model reasoning options, or `null`), and `reasoning_effort` (the session
override string, or `null` when inheriting the saved model default). Clients
show a depth control only for enabled reasoning with a nonempty effort list.
Budget-only reasoning and managed Copilot/Grok providers have no effort control.

This GET is side-effect free. It reports the current public model state (and
may mark a saved-model name as deleted), but it never reconstructs or replaces
the session Provider.

### `POST /api/sessions/:id/model/reload`

Forces the requested active session to re-resolve its selected saved-model
profile and compare the effective Provider construction inputs. Like every
ordinary message send, it first reloads `config.json` when the file's bytes
changed since the last check, so hand edits (for example a new API key) are
picked up without a daemon restart. A successful
request returns HTTP 200 with the existing public model-state shape nested in
an outcome envelope:

```json
{
  "outcome": "reloaded",
  "model_state": {
    "name": "gateway",
    "provider": "openai",
    "model": "gpt-5",
    "context_window": 128000,
    "deleted": false
  },
  "warning": "session metadata could not be persisted"
}
```

`outcome` is one of:

- `reloaded`: effective construction inputs changed and a new Provider was
  published for future turns;
- `already_current`: the selected profile resolves to the Provider already in
  use; model state such as `context_window` may still be refreshed;
- `unresolvable`: the selected name was deleted, renamed away, or is a
  session-local ad-hoc profile. The existing Provider and model state remain in
  use; deletion is not a live connection revocation.

`warning` is omitted when empty. A warning is sanitized and non-fatal: for
example, Provider publication can succeed even when best-effort session
metadata persistence fails. Pre-publication construction or revalidation
failure returns `500 MODEL_RELOAD_FAILED` and preserves the old Provider,
state, and applied revision. Unknown sessions return 404; a server without a
session registry returns 503.

The operation is scoped to the named active session. It does not change the
workspace, cwd model override, configured default model, or any other session.

### `POST /api/sessions/:id/model`

Body:

```json
{"name":"saved-model-name"}
```

Switches the active session to that saved model profile and returns model
state. Returns `404` when the session is not active in the registry.

Changing to a different saved model clears the previous reasoning override.
Reloading the same model retains a still-supported override; disabling the
capability or removing that effort clears it.

### `POST /api/sessions/:id/reasoning`

Body:

```json
{"effort":"high"}
```

Use `{"effort":null}` to restore the saved model's defaults. Success returns
the standard session model state. The selected string must occur in the
current model's enabled `reasoning.supported_efforts`. This operation changes
only the named session: other sessions, saved profiles and workspace defaults
are unaffected. The override is persisted, restored on resume and inherited
by a fork. An explicit effort takes precedence over the saved reasoning token
budget; resetting the override restores that budget as well as the default.

Active turns and queued input accept changes. Each model request captures its
own provider snapshot: an in-flight request keeps its existing effort and is
not interrupted; the next request that captures its provider after the update
uses the new effort, including subsequent requests within the same turn.
Multiple successful changes before that boundary use the latest selection.
Failed persistence restores the prior provider and effort before another
request can capture them. Malformed bodies,
non-null selections for unsupported models and undeclared efforts return
`400 INVALID_REASONING_EFFORT`;
unknown sessions return `404 SESSION_NOT_FOUND`, unavailable model profiles
return `409 MODEL_UNAVAILABLE`, and update failures return
`500 REASONING_UPDATE_FAILED`.

### Copilot auth routes

| Method | Path | Response |
|---|---|---|
| GET | `/api/copilot/auth` | `{"provider":"copilot","has_token":true,"authenticated":true}` |
| DELETE | `/api/copilot/auth` | deletes saved GitHub token, returns auth false |
| POST | `/api/copilot/auth/device` | starts GitHub device flow |
| POST | `/api/copilot/auth/device/poll` | polls one device-flow tick |

`POST /api/copilot/auth/device` response:

```json
{
  "status": "pending",
  "provider": "copilot",
  "device_code": "...",
  "user_code": "ABCD-1234",
  "verification_uri": "https://github.com/login/device",
  "interval": 5,
  "expires_in": 900,
  "expires_at_unix_ms": 1783152000000
}
```

Polling success returns `status:"authenticated"`. Pending, slow-down, and
failure states return `status`, `error`, `message`, and
`interval_delta_seconds`.

### Grok Coding Plan auth routes

| Method | Path | Response |
|---|---|---|
| GET | `/api/grok/auth` | `{"provider":"grok","authenticated":true}` |
| DELETE | `/api/grok/auth` | deletes `~/.acecode/grok_auth.json`, returns auth false |
| POST | `/api/grok/auth/device` | starts xAI Device OAuth |
| POST | `/api/grok/auth/device/poll` | polls exactly one device-flow tick |

`POST /api/grok/auth/device` response:

```json
{
  "status": "pending",
  "provider": "grok",
  "authenticated": false,
  "device_code": "...",
  "user_code": "ABCD-EFGH",
  "verification_uri": "https://accounts.x.ai/activate",
  "verification_uri_complete": "https://accounts.x.ai/activate?user_code=ABCD-EFGH",
  "interval": 5,
  "expires_in": 1800,
  "expires_at_unix_ms": 1783152000000
}
```

轮询终态为 `authenticated`、`expired` 或 `failed`；`slow_down` 会返回
`interval_delta_seconds`，前端应在原 interval 上累加。凭据保存到
`~/.acecode/grok_auth.json`，写入使用受限权限和原子替换。到期前 60 秒自动刷新；
上游返回 401 时只强制刷新并重放一次，refresh token 轮换会立即持久化。

所有 Grok auth 状态、轮询、模型探测和错误响应都不得包含 `access_token`、
`refresh_token`、账号 email 或 user id。`device_code` 只在设备授权开始响应及随后
浏览器提交的轮询请求中出现；daemon 日志与错误消息会脱敏认证字段。

---

## 10. Config, MCP, Update, and Feedback

### `GET /api/ui/onboarding/desktop`

Returns the backend-owned Desktop guided-tour version and whether that version
has been dismissed:

```json
{"guide_version":1,"dismissed":false}
```

The state is stored in `~/.acecode/state.json`, not browser storage, so it
survives Desktop loopback-port changes and Edge compatibility profiles.

### `POST /api/ui/onboarding/desktop/dismiss`

Idempotently marks the current Desktop guided-tour version as dismissed and
returns the same payload with `dismissed:true`. A state-file write failure
returns HTTP `500` with `error:"PERSIST_FAILED"`.

### `GET /api/config/desktop-multi-instance`

读取当前用户全局配置中的 `desktop.allow_multiple_instances`，返回
`{"enabled": false}`（默认关闭）。接口要求认证，并设置 `Cache-Control: no-store`。
每次从磁盘读取，其他桌面实例保存后的选择会在下次读取时生效。

### `PUT /api/config/desktop-multi-instance`

请求体为 `{"enabled": true}` 或 `{"enabled": false}`，成功返回已持久化的同形响应。
使用跨进程配置锁，重新读取最新配置后只变更多进程选项；内存状态在保存成功后更新。
非法 JSON 返回 `400 BAD_JSON`，缺少布尔字段返回 `400 BAD_REQUEST`，读写失败返回
`500 CONFIG_FAILED`。未通过认证的请求遵循公共认证规则。

该开关只影响以后启动的 `acecode-desktop`，不停止当前实例。主实例继续持有单实例锁，
允许启动的附加实例使用各自的后台运行目录；每个壳内部仍由一个 daemon 服务多个工作区。
开发者页在设置面板内依次输入 `↑↑↓↓←→←→BABA` 后显示，解锁本身不改变开关。

### `GET /api/config/ui-preferences`

Returns:

```json
{
  "show_acecode_avatar": false,
  "theme": "system",
  "color_theme": "blue",
  "font_size": "medium",
  "sidebar_session_time": true,
  "message_auto_collapse": true,
  "theme_variant": "",
  "theme_effects": true,
  "theme_sounds": true,
  "subagent_avatar_style": "geometric"
}
```

`theme` accepts `system`, `light`, or `dark`; `color_theme` accepts `blue`,
`orange`, or `eva-01`; and `font_size` accepts `small`, `medium`, or `large`. These values
are stored in `~/.acecode/config.json`, so Desktop restores them even when its
managed daemon uses a different loopback port. The avatar preference is kept
for compatibility and is always normalized to `false`.

`message_auto_collapse` is a boolean, defaulting to `true` for new and legacy
configurations. When `false`, main and subagent conversations display messages
without activity/turn folding; individual tool calls remain collapsible.
The preference is persisted and included in the Desktop appearance bootstrap.

`theme_variant` selects a variant inside the active theme package (see
[themes.md](themes.md#hud-外观与多风格)). It is empty or 1-24 lowercase ASCII
letters/digits joined by single hyphens; empty means the package's first
variant, and an ID the active theme does not declare also falls back to it.
`theme_effects` (default `true`) turns the motion of HUD-chrome themes on or
off and does not follow the OS reduced-motion setting. `theme_sounds` (default
`true`) is the title bar's mute button for themes that declare sound effects.
All three are persisted, included in the Desktop appearance bootstrap, and
rejected with `400` when malformed.

`subagent_avatar_style` is `geometric` (default, a generated petal rosette) or
`pixel` (the Agent Office character): the portrait drawn for sub-agents that
have no expert attached (Settings > Appearance). It is persisted, included in
the Desktop appearance bootstrap, and any other value is rejected with `400`; a
config file without the key or holding an unknown value loads as `geometric`.

### `PUT /api/config/ui-preferences`

Body:

```json
{"theme":"dark","color_theme":"orange","font_size":"large"}
```

The body may contain one or more supported fields. Every supplied field is
validated before mutation; omitted fields keep their current values. Legacy
`{"show_acecode_avatar":false}` requests remain valid. On success the endpoint
persists the configuration and echoes the complete normalized response shown
above; a write failure returns `500` with `error:"PERSIST_FAILED"` and restores
the in-memory values.

Selecting `eva-01` requires verified local resources. Otherwise the request
returns `409` with `error:"THEME_NOT_INSTALLED"` without changing any preference.
EVA uses its package's fixed light palette. The stored `theme` preference is
preserved for switching back to an ordinary theme; OS color-scheme changes
cannot override EVA. Its background image is used only on the new-task home.

### Downloadable themes

Local ZIP import uses authenticated `POST /api/themes/import/preview` with
`Content-Type: application/zip` and the original ZIP body (maximum 16 MiB).
It returns `theme`, `package_sha256`, `package_bytes`, and a PNG `thumbnail_url`
data URI without installing. After explicit UI confirmation, send the same body
to `POST /api/themes/import?sha256=<package_sha256>`. The daemon revalidates the
archive and digest, then uses the existing atomic local install. Changed bytes
return `409/THEME_IMPORT_CHANGED`; conflicting installed versions are preserved.
Applying the imported theme is a separate normal UI preference operation and
depends on the user's checkbox. These local APIs do not contact the workshop.

All theme endpoints require the normal daemon authentication. Theme files live
in `themes/` beside the daemon configuration, independently of application
updates. The application bundles only the small card thumbnail and three
preview swatches; it does not bundle or automatically download the full EVA
theme. See [theme packaging](themes.md) for the independent publish layout.

`GET /api/themes?refresh=1` refreshes `upgrade.base_url + "themes/catalog-v2.json"`,
falling back to `themes/catalog.json` when the expanded catalogue returns HTTP
404 or 410. The legacy EVA-only public catalogue remains available to old clients.
The expanded catalogue supports `national-day-2026` and `eva-01`; entries are
validated independently and installation resolves the requested ID.
Each catalogue operation resolves the current update server, including changes
made through `PUT /api/config/upgrade`, without a daemon restart. Cached metadata
is scoped to its source server. Already started downloads retain the resource
URL and integrity metadata captured when they were confirmed.
Without `refresh`, the daemon uses the cached catalogue when available. The
response contains `schema_version:1`, `themes`, `offline`, and `job`. Each entry
has `id`, `version`, three `swatches`, `installed`, `installed_version` (empty
when no valid installation exists), `update_available` (a newer semantic
version is available), and `package`/`thumbnail`
descriptors containing a relative `path`, exact `bytes`, and lowercase `sha256`.
The API also includes `package.url` and `thumbnail.url`, resolved against the
configured update server. Error responses and failed jobs include
`error_path` with the actual catalogue/archive URL or failing local path.
An unavailable server falls back to its own cached catalogue with `offline:true`;
without a cache for that server and without any installed themes it returns
`503/THEME_CATALOG_UNAVAILABLE`. If local AI themes exist, they remain visible:
the response contains `offline:true`, a `catalog_error` object, an EVA descriptor
with `available:false` and no remote package, followed by the local entries.
Installed National Day resources are also reported and remain usable offline.
Clients disable the unavailable download without hiding installed local themes.

Local entries have `source:"local"`, `installed:true`, `name`, `mode`, `version`,
`installed_version`, three `swatches`, `update_available:false` and thumbnail
metadata whose URL uses the authenticated `/api/themes/<id>/images/thumbnail`
endpoint. Their IDs match `^ai-[a-z0-9]+(?:-[a-z0-9]+)*$` and are at most 64
characters. Definitions accept light or dark mode and all 28 HEX tokens. The
definition and image routes work offline. Built-in IDs cannot be overwritten.

Workshop discovery reads every public `/api/themes?page=N` page from the update
host at its effective port plus 10000 (82 → 10082, 1234 → 11234), retaining the
HTTP/HTTPS scheme and clearing the update path. `source:"workshop"` entries use
dynamic `ai-*` IDs, names, versions, swatches and a content-addressed `key`.
Each ID appears once, at its highest public semantic version, merged with local
`installed`, `installed_version` and `update_available` state. `package` includes
the exact bytes, SHA-256 and a daemon-constructed workshop download URL.
The thumbnail proxy accepts only a 64-character hex key and constructs the
resource URL from the current configured host; remote arbitrary URLs are ignored.

`refresh=1` updates both catalogues. Workshop failure returns `workshop_error`
without reusing old remote offers; installed themes remain as local entries.
Workshop installs recheck the public list and the confirmed package metadata,
then reuse the local import validation and atomic transaction. A withdrawn theme
cannot be newly installed; an existing installation remains usable offline.
Settings refreshes discovery on open, window focus and update-source changes.
Deleting an installed workshop theme leaves its public offer available to install
again. Pending/rejected submissions are never advertised by the public API.

Schema version 1 definitions may also include an `appearance` object:

```json
{"appearance":{"logo_color":"#9B6DFF","home_title_color":"#F5F0FF","extend_to_titlebar":true}}
```

All members are optional. `logo_color` and `home_title_color` accept only
`#RRGGBB`; `extend_to_titlebar` accepts only a JSON boolean. Unknown members,
null, non-object appearance and wrong member types are rejected. Omitting the
object preserves legacy behavior: original logo colors, `colors.fg` for the
homepage heading, no extension for custom themes and the existing extension
and white right-side controls for EVA. Explicit members override defaults.
Dark themes with extension enabled use white right-side title-bar controls
while the homepage wallpaper is visible. Full definitions and exported ZIPs
preserve the optional object; the 28-member `colors` object is unchanged.

Additional optional `appearance` members are `home_background_color`,
`session_background_color`, and `user_message_background_color` (all `#RRGGBB`),
and `home_composer_opacity`, `home_background_opacity`,
`session_background_opacity`, `user_message_background_opacity` (finite JSON
numbers from 0 to 1, where 1 is opaque). Defaults remain 0.95 for the home
composer and 1 for artwork. Artwork overlays use the corresponding background
color, falling back to `colors.bg` or `colors.accent-bg` for user messages.
These controls never reduce text opacity or replace the original three settings.

Optional top-level `session_background` and `user_message_background` descriptors
use the same byte-count/SHA-256 schema as `background`, with fixed paths
`session-background.png` and `user-message-background.png`. Only declared files
may be present. Their authenticated image routes use `images/session-background`
and `images/user-message-background`; all returned images are PNG. The latter
applies only to user-sent message bubbles, never assistant replies.

`POST /api/themes/<id>/install` requires the exact metadata displayed by the
confirmation dialog:

```json
{"confirm_download":true,"version":"1.0.0","bytes":2220741,"sha256":"<catalogue SHA-256>"}
```

Missing or mismatched consent returns `409/THEME_CONFIRMATION_REQUIRED` and
starts no download. The accepted response and `GET /api/themes/job` contain
`id`, `version`, `state`, `bytes_downloaded`, `bytes_total`, and `automatic`. States are
`idle`, `downloading`, `installing`, `completed`, `cancelled`, or `failed`;
failure adds an `error` code. Only one installation runs per daemon; a second
request returns `409/THEME_DOWNLOAD_BUSY`. `POST /api/themes/job/cancel`
requests cancellation, which is observed through job polling. The frontend
shows this progress and any retry action inside the theme card, even after
closing and reopening Settings. A later theme selection revokes automatic
application of an earlier download.

`POST /api/themes/first-run` is authenticated and blocked during configuration
migration. It atomically creates `themes/.national-day-2026-attempted` and returns
`{"id":"national-day-2026","claimed":true}` only to the first claimant; later
requests return `claimed:false`. It neither downloads nor changes appearance.
The marker persists across failures, process restarts and application upgrades.
当前 Web/Desktop 客户端恢复外观后不再调用此接口，也不自动下载或应用国庆节主题。
新配置使用蓝色和跟随系统的明暗模式，已有配置保留已保存的主题。接口继续保留，
兼容旧版客户端；以下自动任务行为仅适用于仍调用此接口的旧版启动流程。

After restoring canonical appearance preferences, a legacy Web/Desktop client
can automatically install the National Day package using the same exact integrity
metadata with `automatic:true`, or reuse a valid installation. Automatic jobs
retain that flag so every observing client suppresses their failure notifications.
Application follows successful resource preparation. A later explicit theme
choice wins, and persistence failures silently roll back the original appearance.
The automatic `PUT /api/config/ui-preferences` includes `expected_appearance`
containing the initial GET response. The server compares it under the configuration
lock before writing; a changed snapshot returns `409/APPEARANCE_CHANGED` without
modifying preferences. This also protects later choices made in another window.
Manual downloads continue to require confirmation and display normal errors.

The daemon verifies archive bytes, SHA-256, allowed ZIP entries, the fixed
palette schema, and all declared images before publishing an installed version. An
interrupted download does not alter the active preference; a damaged local
installation can be repaired by confirming and downloading it again.
`GET /api/themes/eva-01` returns the validated installed `theme.json` without
network access, or `404/THEME_NOT_INSTALLED`. `GET
/api/themes/eva-01/images/thumbnail` remains available for clients needing a
server preview; Appearance uses its bundled thumbnail without calling it.
`.../images/background` is available only after installation.
Both image responses are PNGs. Applying an installed theme requires no
redownload, including after an offline restart.

### Custom theme export and deletion

Only installed local `ai-*` themes support export and deletion. Blue, orange,
and the downloadable built-in EVA theme reject both operations. These routes
require normal daemon authentication and preserve the existing EVA download
job independently of theme export progress.

`POST /api/themes/<id>/export` accepts `{ "native_save": false }` by default.
With `native_save:true`, the daemon immediately opens the existing native
Save As picker with a ZIP filename. Only a picker-selected path may become a
native output target; request-supplied arbitrary destination paths are not
supported. Cancelling the picker returns
`{ "state":"cancelled", "cancelled":true }` without starting packaging.
An unavailable native picker returns `501/THEME_NATIVE_SAVE_UNAVAILABLE`.

An accepted job returns `job_id`, `id`, `version`, `filename`, `state`,
`progress` (null or a real fraction from 0 to 1), `reused`, and `native_saved`.
States are `preparing`, `compressing`, `saving`, `completed`, `cancelled`,
and `failed`. Clients poll `GET /api/themes/exports/<job_id>` and cancel via
`POST /api/themes/exports/<job_id>/cancel`. Failed jobs include `error`,
`message`, and `error_path`. A valid existing ZIP matching the installed
resources is reused; missing or stale archives are rebuilt with libzip's
actual progress/cancellation callbacks. Native completion means the selected
file was written; Web completion means the ZIP is ready for download.
Cancellation can initially return a working snapshot. Clients must resolve the
terminal state and preserve a later confirmed `completed/native_saved:true`
result, even if the cancel request failed; a file already committed must not be
reported as cancelled. The same rule applies when Web file writing has committed.

New archive caches use `themes/exports/<id>/<version>.zip`. Legacy flat
`<id>-<version>.zip` caches remain readable only after verifying their embedded
theme ID, version, and resources; deletion also checks this ownership instead
of treating a filename prefix as sufficient proof.

`GET /api/themes/exports/<job_id>/download` returns the completed ZIP as
`application/zip` with an attachment filename, `no-store`, and `nosniff`.
Clients may use an authenticated Blob download, without placing daemon
credentials in a download URL. The ZIP contains `theme.json`, `background.png`,
and `thumbnail.png`, plus any declared `session-background.png` and
`user-message-background.png` (three to five root files). Unknown, cancelled, failed, or
unfinished jobs cannot download a partial package.

`DELETE /api/themes/<id>` returns `{id,deleted:true,ui_preferences}`. Deleting
the configured active theme persists `color_theme:"blue"`; deleting another
theme preserves the configured selection. The theme files and matching
application-owned exports are isolated before preference persistence and are
restored if that commit fails. User-saved exports, original input images,
drafts, and other themes remain untouched. Invalid IDs, out-of-root paths,
symlink/reparse redirects, and conflicting operations are rejected. Preference
writes also validate local theme availability under the same transaction
ordering, so a stale queued selection cannot restore a deleted ID.
If post-commit quarantine cleanup cannot finish, deletion remains successful
and the response includes `cleanup_pending:true` and `cleanup_message`; clients must not restore
the deleted card or report that the deletion itself failed.

Representative theme-management errors:

| HTTP / code | Meaning |
|---|---|
| `400/THEME_INVALID_ID` | invalid custom theme identifier |
| `403/THEME_BUILTIN_PROTECTED` | built-in theme export/deletion is forbidden |
| `404/THEME_EXPORT_NOT_FOUND` | unknown or expired export job |
| `409/THEME_BUSY` | a conflicting theme export or transaction is active |
| `409/THEME_EXPORT_NOT_READY` | the export is not complete or was cancelled/failed |
| `409/THEME_CHANGED` | the installed theme or validated archive changed |
| `422/THEME_UNSAFE_PATH` | a theme path or filesystem redirection is unsafe |
| `500/PERSIST_FAILED` | appearance persistence failed; isolated files are restored |
| `501/THEME_NATIVE_SAVE_UNAVAILABLE` | no native Save As capability is available |

### AI theme workflow tool

The built-in `theme_create` tool is registered for daemon and TUI sessions.
`palette` accepts `name`, `mode`, all 28 `colors`, optional `appearance`, and
optionally `draft_id` to revise a draft. Each palette call replaces the whole
proposal; omitting `appearance` removes a previous override. It persists the
draft under `themes/drafts`, then uses the
native question channel for explicit palette approval. `prototype` accepts
`draft_id`, `background_path`, `preview_path`, and optional
`session_background_path` / `user_message_background_path`; it decodes and
copies all supplied images before asking for prototype approval. Each prototype
call replaces the complete image set, so omitting an optional path removes that
region from the draft. Its approved digest covers every supplied image.
`preview_path` may be a screenshot of the local HTML in ACECode Browser; neither
HTML nor SVG paths are accepted as image inputs. A draft is owned by its creating
session, and an update invalidates earlier approvals. Headless mode, deny
policy, unattended goals, cancellation, timeout and custom feedback never count
as approval. No `confirmed` input can bypass these gates.
The palette and prototype approvals cover explicit appearance members as well
as colors. A draft without appearance retains the original digest algorithm,
so already approved legacy drafts remain resumable. Adding, changing or
removing appearance invalidates previous approvals. Draft status and installed
definitions retain the confirmed object; installation retries also compare it.
Invalid palette appearance returns `422/THEME_INVALID_APPEARANCE` before
replacing a draft or requesting approval.

`install` accepts only `draft_id`, verifies approved checksums, generates the
thumbnail and three-to-five-file ZIP, and publishes the immutable version and installed
pointer. Successful tool output includes `installed_path` and `package_path`
(under `themes/exports`); metadata includes
`theme_created:{id,version,name,apply:true}`. The current live UI can refresh and
apply this theme. Repeating installation of the same draft returns the same
theme. Prior themes and the ordinary appearance mode preference remain intact.
`status` reads a draft, or lists the caller's drafts when `draft_id` is omitted.
Results include `draft_id`, `stage`, and `next_action` for resuming after an
interruption. No status call generates images or records user approval.

### `GET /api/config/ui-locale`

Returns the persisted fixed-copy locale preference:

```json
{"locale":"auto"}
```

Supported values are `auto`, `zh-CN`, and `en-US`. `auto` resolves Chinese
system locales to `zh-CN` and all other system locales to `en-US`. A legacy
configuration with no `ui.locale` remains `zh-CN`; a newly generated
configuration explicitly writes `auto`.

### `PUT /api/config/ui-locale`

Body:

```json
{"locale":"en-US"}
```

The route validates the canonical value, persists `ui.locale`, and echoes the
stored preference. Invalid values return HTTP `400` with
`error:"INVALID_UI_LOCALE"`; a persistence failure restores the previous
in-memory value and returns HTTP `500` with `error:"PERSIST_FAILED"`.

### `GET /api/config/remote-web`

Returns configured intent plus the currently effective daemon/proxy state. Because
`connections` contains bearer-token URLs, the route uses normal daemon auth
and always sends `Cache-Control: no-store`.

```json
{
  "enabled": true,
  "configured_enabled": true,
  "effective_enabled": true,
  "configured_bind": "127.0.0.1",
  "effective_bind": "0.0.0.0",
  "daemon_bind": "127.0.0.1",
  "daemon_port": 12399,
  "proxy_bind": "0.0.0.0",
  "proxy_pid": 4242,
  "proxy_state": "running",
  "proxy_ipv6": true,
  "error": "",
  "applying": false,
  "port": 28081,
  "connections": [
    {
      "host": "ACE-PC",
      "kind": "computer_name",
      "url": "http://ACE-PC:28081/?token=<encoded-token>"
    },
    {
      "host": "192.168.1.20",
      "kind": "network_address",
      "url": "http://192.168.1.20:28081/?token=<encoded-token>"
    }
  ]
}
```

The current computer name is the first/default connection candidate when it is
a valid hostname. Active non-loopback interface addresses follow it and match
the proxy listener's available IP address families. Unspecified, loopback, multicast,
and link-local destinations are omitted; `0.0.0.0` is never returned as a
destination. Multiple Wi-Fi, Ethernet, VPN, or VM adapter addresses may be
present. An empty `connections` array means neither a usable computer name nor
an address was discovered.

### `PUT /api/config/remote-web`

Body:

```json
{"enabled":true}
```

Enabling starts a separate ACECode reverse-proxy child and waits until its
external listener is ready before persisting `web.remote_enabled:true`.
Disabling persists false and stops only that child. Crow remains continuously
bound to `127.0.0.1:web.port`, preserving the daemon PID, token, sessions,
consoles, and active Agent work. A local page receives the mutation response
without listener downtime. A page opened through the remote proxy naturally
disconnects when it disables that proxy.

`web.remote_port:0` first tries the port adjacent to `web.port`, then falls back
to an OS-selected wildcard port. A non-zero value is fixed: a collision returns
HTTP `502` with `error:"REMOTE_WEB_PROXY_START_FAILED"` and the newly enabled
intent is not persisted. The actual external port is always returned as `port`.
If a configured proxy later exits, `configured_enabled` stays true while
`effective_enabled` becomes false, `proxy_state` is `failed`, and `error`
contains a sanitized diagnostic.

Legacy configurations that set a non-loopback `web.bind` without an explicit
`web.remote_enabled` are loaded as remote-enabled and normalized to the
loopback daemon plus proxy representation on the next save.

Enabling while the daemon is in dangerous mode returns HTTP `409` with
`error:"DANGEROUS_MODE_REMOTE_WEB_FORBIDDEN"` and does not change the
configuration.

### Shared settings write semantics

Saved-model/default-model writes and the custom-instructions,
default-permission, desktop-notification, remote-Web, and upgrade routes share the same
typed mutation path as the TUI settings center. A write acquires the process
and interprocess config lock, reloads the latest canonical `config.json`,
patches only the requested field or domain, validates it, and atomically
replaces the file. This prevents a concurrent TUI/Desktop/daemon write to an
unrelated setting from being overwritten. Validation or replacement failure
leaves the previous canonical file and caller-confirmed in-memory state intact.
Mutation diagnostics redact credential-bearing model fields and headers.

### `GET /api/config/custom-instructions`

Returns:

```json
{"text":"custom prompt text"}
```

### `PUT /api/config/custom-instructions`

Body:

```json
{"text":"custom prompt text"}
```

The text is byte-limited by `kCustomInstructionsMaxBytes`. Existing sessions
pick up changes on later turns through the daemon config pointer.

### Summary generation settings

`GET /api/config/summary-generation` returns `enabled` (default `false`),
`model_name` (a saved model name), `configured` (whether that saved model exists),
and `models` (available `{name, provider, model}` records). No model credentials
are included. Reads and writes require the normal API authentication and return
`Cache-Control: no-store`.

`PUT /api/config/summary-generation` accepts a partial object containing only
`enabled` (boolean) and `model_name` (string). An empty model name enables automatic
selection; an existing removed reference can be retained. Newly submitted unknown
model names and invalid patches return `400 BAD_REQUEST`; malformed JSON returns
`400 BAD_JSON`. Atomic persistence failures return `500 PERSIST_FAILED` and do
not change the live configuration. Unrelated settings are preserved by reloading
the latest disk configuration inside the config mutation lock.

When enabled, subsequent automatic-title attempts use this model before all
session, workspace, default and legacy `session_title.model_name` selections.
Each daemon title request captures its configuration before running. A removed
summary model gives `configured: false` and generation silently tries the last
successful conversation model, then contextual/default/other saved models. Failed
requests also use this fallback; a successful replacement is reused until the
preferred configuration changes or the replacement fails. Runtime success records
contain opaque connection identities, not credentials or transcript content.
The same recovery policy applies to home intent generation and enabled memory
summaries (which retain their own preferred-model setting).
Disabling retains `model_name` and restores
the previous title-resolution behavior, including the legacy override. This
setting does not change the conversation model or disable automatic titles.

### Computer use settings

`GET /api/config/computer-use` returns `enabled` (default `false`),
`supported` (Windows or macOS 14+), `platform` (`windows`, `macos`,
or `linux`), `pointer_style` (`ace` by default, or `plain`), and `pointer_color`
(default `#2563eb`). `PUT` accepts any subset of boolean `enabled`,
`pointer_style`, and `pointer_color`; omitted fields keep their current values.
Colors must be six-digit `#RRGGBB` and are normalized to lowercase. Both
endpoints require authentication and return the persisted settings plus live `availability`.
Malformed JSON returns `400 BAD_JSON`, invalid fields return `400 BAD_REQUEST`,
and enabling on another platform returns `400 COMPUTER_USE_PLATFORM_UNSUPPORTED`.
Persistence errors return `500 PERSIST_FAILED` without changing the live switch.
Pointer appearance can be saved while the tool is disabled and never enables it
implicitly. The WebUI synchronizes the current theme accent color outside the
settings panel too. Changes apply on the helper's next request without ending
its session lease or invalidating an existing observation.

On macOS, `availability` contains `supported`, `minimum_macos` (`14.0`),
`helper_available`, `helper_path`, `accessibility`, `screen_recording`, and `ready`.
Each permission is `granted`, `required`, or `unknown`; both must be granted for
`ready: true`. Missing helpers, unsupported systems, failed probes and timeouts
include an `error` code. Non-macOS permission states are `not_required`.
`enabled` remains the saved user intent and does not imply system authorization.
GET, PUT and readiness refreshes never request system permission.

Authenticated `POST /api/config/computer-use/permissions` accepts exactly one
field: `{"permission":"accessibility"}` or `{"permission":"screen_recording"}`.
It prompts from the actual helper process and opens the relevant macOS settings
pane when needed, then returns settings with refreshed `availability`. It never
changes `enabled`. Only invoke it following a user permission-button action.
Invalid bodies return `400 COMPUTER_USE_INVALID_PERMISSION`; HTTP 200 does not
imply permission was granted. Probe/OS errors are reported in `availability.error`.

Enabling registers the `computer_*` tools for subsequent model requests;
disabling unregisters them and terminates the active desktop helper. An
in-flight handler also checks the live gate, so stale calls cannot bypass a
disabled setting. The UI reconciles uncertain save outcomes with a fresh GET.
Window observations and PNG attachment metadata include a `cursor` object:
`visible`, and when visible, `source` (`agent` or `system`), `x`, `y`,
`hotspot_x`, `hotspot_y`, `width`, and `height`. All dimensions use that
screenshot's pixels, including when the native window image was resized.
See [Computer Use](computer-use.md) for native capabilities and platform limits.

### Speech recognition settings and dictation

All speech endpoints use normal API authentication/CORS and `Cache-Control: no-store`.
`GET /api/config/speech-recognition` returns `enabled` (default false), `protocol`
(`sensevoice`, `openai`, or `whisper_cpp`), `base_url`, `model`, `api_key`,
`language` (default `auto`), `timeout_ms` (default 120000),
`max_recording_seconds` (default 60), `use_proxy` (default false), `configured`,
and `generation`. The key is returned for the authenticated password editor;
never log or cache this response. The availability endpoint returns only
`enabled`, `configured`, both time limits, and `generation`.

`PUT` accepts partial updates. An omitted key is preserved; an empty key clears
it. Both HTTP and HTTPS service URLs are accepted, including custom ports
1–65535; credentials, whitespace, query strings and fragments are rejected.
Timeout must be 5000–600000 ms and maximum recording length 1–300 seconds.
An empty URL is a valid incomplete draft. OpenAI-compatible configuration also
requires a model ID before the microphone becomes available. Invalid input
returns 400 `SPEECH_INVALID_CONFIG`; failed persistence returns 500 `PERSIST_FAILED`
without changing live state. Successful writes merge the disk configuration,
increment the generation, cancel active transcription and return the new snapshot.

The settings UI has no separate Save button. Toggles and selects save immediately;
text/number inputs save on blur or Enter, with remaining edits flushed when
collapsing or leaving settings. Writes are serialized per connection and preserve
newer edits; failures retain the draft and offer retry. The connection-test button
waits for successful automatic saving before testing the current configuration.

`POST /api/config/speech-recognition/test` accepts a partial settings object,
overlays it on saved settings without saving/enabling them, and transcribes one
second of silence. Its timeout is capped at 30 seconds. Success is `{"ok":true}`;
an empty transcript is a valid test result. No recognition runs while merely
loading or saving settings.

`POST /api/speech-recognition/transcriptions/<id>` takes an `audio/wav` body:
canonical 44-byte WAV header, 16 kHz mono PCM16, bounded by the configured
duration and 20 MiB. The ID must contain 1–64 ASCII letters, digits, `_` or `-`.
At most one dictation is active per daemon. Success returns
`{"status":"ok","text":"..."}` or `{"status":"no_speech","text":""}`.
`DELETE` is idempotent and returns `{"cancelled":true}`. Cancellation and daemon
shutdown stop forwarding and suppress late transcripts. A configuration change
invalidates requests admitted under an earlier generation.

Errors include 409 `SPEECH_NOT_CONFIGURED` / `SPEECH_CANCELLED`, 429 `SPEECH_BUSY`,
413/422 `SPEECH_INVALID_AUDIO`, 503 `SPEECH_NOT_READY`, 504 `SPEECH_TIMEOUT`, and
502 `SPEECH_CONNECTION_FAILED`, `SPEECH_AUTH_FAILED`, `SPEECH_INVALID_RESPONSE`
or `SPEECH_UPSTREAM_FAILED`. Upstream bodies and credentials are never echoed.
The backend forwards in-memory multipart audio to SenseVoice
`/api/transcriptions` (`audio`), OpenAI-compatible `/v1/audio/transcriptions`
(`file`, `model`) or whisper.cpp `/inference` (`file`). HTTP services work
without certificates; browser microphone permission separately requires a
secure context. See [Speech recognition](speech-recognition.md).

### Image generation settings

`GET /api/config/image-generation` returns `enabled`, `source` (`inline` or
`saved_model`), `saved_model_name`, `base_url`, `api_key` (the stored inline key),
`has_api_key` (whether an inline key is stored), `configured` (whether the selected
connection resolves, regardless
of the enabled flag), `models` (`standard`, `high`, `ultra`), `default_quality`,
`timeout_ms`, and `connections` (reusable saved connections with `name` and
`has_api_key`). Only OpenAI-compatible base-URL connections are reusable;
chat-only full endpoint URLs are excluded. As with model settings, the inline
key is returned after normal API authentication so the password field can be
prefilled and revealed with its eye button. Reusable connections never include
their credentials. Do not log or cache settings responses.

The default image API URL comes from `constants::ACEMODEL_API_BASE_URL` in
`src/base/utils/constants.hpp`, shared with the ACEModel model catalog. The frontend
uses the returned URL. Saving the default leaves the URL out of the sparse
config, so later default changes apply together; custom URLs remain explicit.

`PUT /api/config/image-generation` accepts a partial update of the editable
fields. Omit `api_key` to preserve it, provide a nonempty value to replace it,
or send `"api_key":""` to clear it. URLs must use HTTPS, or loopback HTTP,
without embedded credentials, query parameters or fragments. Timeout is clamped
to 30,000–600,000 ms. Invalid input returns 400; persistence failure returns 500
without altering live settings. The write reloads and merges the on-disk config
before persisting, preserving unrelated changes. Success returns the same
settings snapshot and refreshes the shared image tool immediately. Existing
requests retain their configuration snapshot; subsequent calls use the saved
configuration. Editing/deleting a reused model connection also refreshes the tool.

The settings UI saves edited fields on blur, saves toggles/selects immediately,
and flushes remaining changes when collapsing or leaving settings. Writes are
serialized per connection, and responses preserve newer input. Reopening waits
for pending writes before reading the saved configuration and refilling the key.
There are no Save/Cancel buttons; failures retain the draft and offer retry.

`POST /api/config/image-generation/test` accepts
`{"confirm_cost":true,"config":{...partial settings...}}`. The cost flag is
required. The supplied draft overlays the saved config without persisting it or
enabling the tool. It generates exactly one image using the `standard` mapping,
even if the default quality is higher or the tool is disabled. The UI labels this
action **Generate test image** and explains that it consumes credits before it
can be triggered. Loading or saving never invokes the image provider; the UI
waits for pending automatic saves before starting a test.

Success returns `image_data_url`, `width`, `height`, `quality:"standard"`, and
`model` for a settings-only preview. These image bytes are not stored in session
history or logs. A concurrent test returns 409 `IMAGE_TEST_BUSY`; incomplete
configuration returns 400 `IMAGE_NOT_CONFIGURED`; upstream failures return 502
`IMAGE_QUOTA_ERROR` or `IMAGE_TEST_FAILED` without echoing provider error bodies.
All endpoints use normal API authentication/CORS and `Cache-Control: no-store`.

### Memory settings and entries (`openspec unify-memory-system`)

Memory has two scopes: **global** (`<data_dir>/memory/`, the user's personal
preferences) and **workspace** (`<data_dir>/projects/<hash>/memory/`, the same
hash as the workspace's session storage). The `workspace` query parameter must
be a registered workspace hash (`404 {"error":"UNKNOWN_WORKSPACE"}` otherwise);
without it the workspace scope is reported as unavailable. Every route returns
`503 {"error":"UNAVAILABLE"}` when the daemon has no memory runtime.

`GET /api/config/memory` returns:

```json
{"enabled":true,"max_index_bytes":8192,
 "summary":{"enabled":false,"model_name":"","idle_minutes":30,"max_session_age_days":7},
 "summary_available":true}
```

`enabled` is "use memory" (inject the per-session memory snapshot and offer
`memory_read` / `memory_write`). `max_index_bytes` is the per-scope injection
budget. `summary.enabled` turns memory summarization on (default off);
`summary.model_name` is a saved model name, empty meaning "the model each
session last used". `PUT /api/config/memory` accepts a patch of the same shape
and goes through `set_memory_settings` (unknown model, `idle_minutes` outside
5–1440 or `max_session_age_days` outside 1–90 → `400 BAD_REQUEST`). Other
ACECode processes pick the change up from `config.json` within one minute.

`GET /api/memory?workspace=<hash>` rescans disk and returns
`{enabled, scopes:{global:{available,dir,entries[]}, workspace:{...}}, status}`.
Each entry is `{scope,name,description,type,created_at,updated_at,source,source_sessions}`
(`source` is `manual` or `summary`; legacy entries without provenance report
`manual`). `status` is `{summary_enabled, global_inbox, workspace_inbox,
last_extraction_ms, last_consolidation_ms, last_error, last_error_ms}`.

`GET /api/memory/:scope/:name` adds `body` and `path`. `PUT` takes
`{description, body, type?}`, writes through the store (secrets redacted to
`[REDACTED]`, `updated_at` refreshed, source becomes `manual` so summarization
leaves the entry alone) and returns the entry plus `redactions`. `DELETE`
removes the entry and its index line and records a tombstone (90 days) so
summarization cannot recreate the same name or title. `POST /api/memory/reset`
takes `{scope, workspace}` and clears that scope's entries, index, inbox and
archive; the other scope is untouched.

### Tool rewrite settings

Settings > Tools > 工具重写. Renames built-in tools as the model sees them: the
tool list sent to the provider, `tool_calls[].function.name` in replayed
history, the system prompt, tool descriptions and the error/guard texts tools
emit all use the rewritten name. Internal ids (session JSONL, permissions,
hooks payloads, TUI/Web rows) stay native. Inbound calls are accepted under
either name. Startup applies the one-time default migration described below;
users can subsequently disable or customize rewriting.

The data is **not** part of `config.json`. It lives in
`<data_dir>/tool_rewrites.json` next to `config.json`, shared by the daemon,
the TUI and headless mode, and is loaded once at startup before tool
registration:

```json
{ "version": 1, "enabled": true, "write_file_default_applied": true,
  "rewrites": { "TodoWrite": "todowrite", "file_edit": "edit", "file_read": "read", "file_write": "write_file" } }
```

On the first successful startup migration per data directory, disabled or
missing settings become enabled and `file_write` is mapped to `write_file`.
Other existing mappings are retained; missing settings use the built-in seed
with this one replacement. Already-enabled settings keep all mappings as-is.
Both cases atomically persist `write_file_default_applied:true` with the
settings. Later startups respect user changes, including disabling rewriting
or changing/removing the mapping. The existing legacy `tool-rewrites.json`
filename remains supported. Unreadable/invalid files are not overwritten;
migration conflicts or write failures log a warning, retain the previous
settings and allow retry at the next startup.

`GET /api/config/tool-rewrites` re-reads the file and returns `enabled`,
`rewrites` (`{native: public}`), `defaults` (the built-in seed: `file_read -> read`,
`file_write -> write`, `file_edit -> edit`, `TodoWrite -> todowrite`), `path`,
`tools` (Builtin-source tools registered in this daemon, sorted by name, each
`{name, description, read_only}`) and, only when the file could not be read or validated,
`warning`. This read-only endpoint does not run migration: a missing file
reads as `enabled:false` with the seed rewrites until successful startup migration.

`PUT /api/config/tool-rewrites` takes `{enabled, rewrites}` and replaces the
editable settings. Every successful save also records migration completion,
independently of client-supplied metadata, so an explicit disable is preserved
on restart. Entries with an empty value or a value equal to the key are
dropped. Rules: every value matches `^[A-Za-z0-9_-]{1,64}$`, values are unique,
a value never equals another registered tool name or another rewrite key.
Violations return 400 `{error:"BAD_REQUEST", message}` without touching the
file or the live mapping; write failures return 500 `PERSIST_FAILED`. Success
writes the file atomically, publishes the mapping to the process so the next
model request uses it, and returns the same shape as GET. Hook matchers accept
the rewritten names as aliases of the native tool while a rewrite is active.

### Agent Browser New Tab suggestions (most visited sites)

The Desktop Agent Browser's empty page lists suggested sites the way Codex
Desktop's New Tab does. WebView2 / WKWebView expose no browsing history, so the
WebUI reports visits and the daemon keeps them in
`<data_dir>/agent_browser_top_sites.json` (`{version, sites:[{url, title?,
favicon?, visit_count, last_visit_ms}], blocked:[url]}`, at most 200 sites and
200 dismissed URLs). Browsing history is private: all four routes return 403
`{error:"LOCAL_ONLY"}` to anything but a direct loopback client (the remote Web
proxy's `127.0.0.2` source included); writes return 409
`DATA_DIR_MIGRATION_ACTIVE` while a data directory migration runs.

- `POST /api/agent-browser/visits` `{url, title?, favicon?, new_visit?=true}`.
  Only `http(s)` URLs are accepted (400 `BAD_URL` otherwise); the `#fragment` is
  dropped. `new_visit:true` counts a navigation; `false` only fills in the title
  or favicon of an existing entry. Favicons are `http(s)` URLs or `data:image/`
  URLs up to 64 KiB; anything else is ignored. Returns `{ok, changed}`.
- `GET /api/agent-browser/top-sites?limit=N` (default 4, max 12) returns
  `{sites:[{url, title, favicon?}]}`, dismissed URLs excluded, ordered by
  `visit_count × recency weight` (1.0 within 4 days, 0.7 within 14, 0.5 within
  31, 0.3 within 90, else 0.1). An empty title falls back to the host.
- `POST /api/agent-browser/top-sites/dismiss` / `restore` `{url}` hide or un-hide
  one suggestion; later visits do not un-hide it.

### Tool preamble / concrete progress text (`openspec add-tool-preamble`)

Settings > General > Work mode: "适合日常工作" (daily) turns it on, "用于编程"
(coding) turns it off; off by default. The config key is still
`agent_loop.tool_preamble.enabled`. When on, the loading text only says what the
agent is doing right now, in present progressive and without tool arguments
(arguments stay on the tool rows), and the vague "正在推理" / "正在等待模型响应"
labels no longer appear. Nothing is asked of the model: every label is produced
by the daemon, in this priority order:

1. **Reasoning bold title** of the current model step: the first `**bold**` span
   of the provider's reasoning summary (OpenAI Responses / Codex app-server /
   Gemini summaries start with one). Valid for that step only. There is no
   first-sentence fallback (raw chains of thought start with "The user wants me
   to…").
2. **Tool template** for the batch, from native tool names:
   `正在读取 3 个文件`, `正在搜索代码`, `正在运行 2 条命令`, `正在修改文件`, …;
   same-kind calls are counted, two kinds are joined with 并, three or more take
   the first two plus 等; MCP and unknown tools become `正在调用工具`.
3. **Context label**: `正在分析你的请求` at the start of a turn; after a batch,
   one based on that batch's first tool kind (`正在分析文件内容`,
   `正在分析搜索结果`, `正在分析命令输出`, `正在检查修改结果`, …); `正在撰写回复`
   once visible text starts streaming.

Delivery: the daemon rewrites the `label` of `model_waiting`, `reasoning`,
`preamble` (bold title just appeared), `responding` (new phase, text started),
`tool_planning` and `tool_running` frames and clears their `detail`
(command preview, byte counts, fragment counts); `permission_waiting`,
`question_waiting`, `compacting` and `model_retry` keep their own labels. Every
rewritten frame carries `preamble: {title, source, kind}` with `source` one of
`reasoning` / `template` / `context` and `kind` `read` / `write` / `""`
(derived from the tool kinds; reserved for a future read/write visual effect).
Each `tool_start` of the batch carries `preamble`, `preamble_source` and
`preamble_kind`; its own `args` / `display_override` are unchanged, so tool rows
keep showing arguments. `metadata.tool_preamble = {source, title, kind}` is
persisted on the `assistant` message that carries the `tool_calls`, as a record
only. There is no `tool_preamble` event.

Older builds asked the model to emit `<text_preamble>` tags; those tags may still
be present in persisted assistant `content`. They are always stripped from
`token` and `message` frames (on or off), never used as labels, and clients strip
them when rendering history.

`GET /api/config/tool-preamble` returns `{enabled}`.
`PUT /api/config/tool-preamble` is a patch: `{enabled: bool}`. A non-boolean
`enabled` returns 400 `BAD_REQUEST` with `message`; legacy `mode` /
`sidecar_model` / `sidecar_wait_ms` keys are ignored. Success writes
`agent_loop.tool_preamble` to `config.json`, pushes the new config to every
active session and returns the GET shape.

### Image compression

Settings > General > 压缩图片 (default on). While on, images sent to a model
are compressed with grok-build's limits (at most 1.5 MB, long side 2000 px,
2,408,448 pixels; PNG and JPEG candidates, the long side shrinks by a quarter
until one fits; Computer Use screenshots keep their size), and each compressed
image is preceded by a note naming its original and compressed size. Stored session
attachments are not modified; the compressed bytes are cached next to the
snapshot (`<snapshot>.model-v1.json` / `.bin`). Once a request body reaches its
cap minus 3 MiB (50 MiB for OpenAI-compatible protocols, 30,000,000 bytes for
Anthropic), the oldest images become file references until the body is at half
the cap, and later requests keep removing the same images until the body grows
to the trigger again.

`GET /api/config/image-compression` returns `{enabled}`.
`PUT /api/config/image-compression` is a patch: `{enabled: bool}`. A non-boolean
`enabled` returns 400 `BAD_REQUEST` with `message`. Success writes
`image_compression` to `config.json`, applies to the next model request in this
daemon and returns the GET shape. Other daemons pick the change up before their
next message send.

### Inline visuals

Settings > General > 可视化图表 (default on). While on, the static system prompt
of daemon sessions tells the model it may write top-level ```` ```visual ````
code blocks (an SVG or HTML fragment) that Web / Desktop draw in a sandboxed
frame while the reply streams. Turning it off only removes that part of the
prompt; visual blocks already in a transcript still render, and the mermaid
part of the guidance is not affected. See [inline-visuals.md](inline-visuals.md).

`GET /api/config/inline-visuals` returns `{enabled}`.
`PUT /api/config/inline-visuals` is a patch: `{enabled: bool}`. A body that is
not an object, or a non-boolean `enabled`, returns 400 `BAD_REQUEST` with
`message`; invalid JSON returns 400 `BAD_JSON`. Success writes `inline_visuals`
to `config.json` (omitted while it is the default), applies to the next request
in this daemon and returns the GET shape. Other daemons pick the change up
before their next message send.

### Security center (`openspec add-security-center`)

Settings > Coding > Security Center is a UI over the sandbox model from
`align-codex-sandboxing` plus a process-wide audit store. Nothing here changes
how permissions are decided; it only exposes the switches, the lists, the
managed rules files and the decision log.

`GET /api/config/sandbox` returns:

```json
{
  "enabled": true, "network_access": false, "deny_defaults": true,
  "filesystem": { "read": [], "write": ["D:/shared/out"], "deny": ["~/.ssh", "**/.env"] },
  "windows_backend": "restricted-token", "writable_roots": [], "exclude_tmpdir": false,
  "defaults": { "deny": ["~/.ssh", "~/.aws", "~/.gnupg", "~/.netrc", "~/.docker/config.json", "~/.kube", ":acecode_home/config.json"] },
  "platform": { "os": "windows", "backend": "restricted-token", "available": true, "reason": "",
                "network_enforced": false, "network_best_effort": true, "read_isolation": false }
}
```

`platform` is the live backend probe. `read_isolation` is `false` on the
Windows restricted-token backend: `filesystem.read` and `filesystem.deny`
only stop writes there. `PUT /api/config/sandbox` accepts any subset of
`enabled`, `network_access`, `deny_defaults` and `filesystem.{read,write,deny}`
(each list replaces the stored list). Entries are trimmed and de-duplicated;
`~`, `~/path`, `:workspace_roots[/sub]`, `:tmpdir[/sub]` and
`:acecode_home[/sub]` are accepted verbatim, everything else must be an
absolute path, and wildcards are only allowed in `deny`. Violations return 400
`{error:"BAD_REQUEST", field, message}` without touching the config. Success
writes `config.json`, queues `set_sandbox_config` on every active session
(serialized with turns, so an in-flight turn keeps its policy until it ends)
and returns the GET shape plus `refreshed_sessions`.

`GET /api/security/exec-rules` scans `<data_dir>/rules/*.rules` and returns
`{dir, managed:["default.rules","default.sandboxed.rules"], files:[{name, path,
managed, scope:"global"|"sandboxed", exists, error, rules:[{pattern, display,
decision, justification}]}]}`. The two managed files are listed even when they
do not exist. `pattern` items are strings or string arrays (alternatives);
`display` is `git status|diff`. `error` is the parse error that makes the
loader skip the whole file. `PUT /api/security/exec-rules` takes
`{files:{"default.rules":[{pattern, decision, justification?}], "default.sandboxed.rules":[...]}}`
and rewrites those files completely (comments and `match` / `not_match` are
dropped). Only the two managed files are writable; the sandboxed file only
holds `allow` rules; an `allow` rule whose whole pattern is on the banned
prefix list (the same list `allow_remember` uses) or whose first token is an
interpreter, shell, `rm`, `sudo` or similar is rejected. Each file is re-parsed
before it is written; success reloads the rules in every active session and
returns the GET shape plus `refreshed_sessions`.

`GET /api/security/audit?category=&decision=&since_ms=&before_id=&q=&limit=`
returns `{entries, has_more, total, next_before_id?}` newest first. `category`
is one of `command` (bash), `file` (file_write / file_edit / apply_patch),
`tool` (other tools that needed confirmation), `sandbox` (a sandboxed run was
denied; `target` is the denied path) or `rule` (remembered rules and session
grants). `decision` is `allow`, `allow_session`, `allow_scoped`,
`allow_remember`, `deny`, `forbidden` or `blocked`; `source` on each entry is
`auto`, `rule`, `session`, `user`, `hook`, `headless`, `goal`, `sandbox` or
`none`. `q` is a substring match on target / reason / tool, `limit` is 1..500
(default 100), `before_id` continues from a previous page. Entries look like:

```json
{ "id": 42, "ts_ms": 1758070000000, "category": "command", "decision": "allow", "source": "auto",
  "reason": "known_safe", "tool": "bash", "target": "git status", "session_id": "20260917-...",
  "cwd": "N:/proj", "sandbox": "workspace-write", "detail": { "mode": "auto", "command_kind": "known_safe" } }
```

Read-only tools that are auto-allowed are not recorded. The store keeps the
newest 20000 entries in `<data_dir>/security/audit.sqlite3` (shared by the
daemon, TUI and headless mode). `GET /api/security/audit/summary` returns
`{total, by_decision, by_category, last_ts_ms, blocked_paths:[{path, count,
last_ts_ms}], path, max_entries}`. `GET /api/security/audit/export?format=jsonl|csv`
accepts the same filters as the list and answers with an attachment
(`Content-Disposition: attachment; filename="acecode-audit-<stamp>.<ext>"`).
`DELETE /api/security/audit` clears the log. All audit routes return 503
`AUDIT_UNAVAILABLE` when the process could not open the store.

### `GET /api/config/connectors`

Returns:

```json
{"connectors":[]}
```

### `PUT /api/config/connectors`

Body:

```json
{"connectors":[]}
```

Parses connector config, persists, and echoes `{"connectors":[...]}`. Changing
`enabled` never launches an authentication helper.

Automatic connector authentication is gated by the versioned
`connector_first_start_auth_v1` flag in the daemon runtime `state.json`. The
first daemon startup that durably claims this flag launches each enabled
connector's `hooks.on_startup` helper once; later daemon startups never launch
automatic connector authentication. The claim is persisted before any helper
starts. If it cannot be persisted, helpers are skipped. Helper threads are
joined before daemon teardown.

For configuration compatibility, `hooks.on_enable`, `hooks.on_auth_error`, and
`auth_error_scope` are still parsed and serialized, but they are inert: neither
a settings toggle nor an HTTP 400/401 model response executes them.

### `GET /api/config/default-permission-mode`

Returns the permission mode used by newly-created sessions:

```json
{"mode":"accept-edits","description":"Auto-allow file edits, prompt for bash"}
```

### `PUT /api/config/default-permission-mode`

Body:

```json
{"mode":"accept-edits"}
```

Persists the default and updates the in-memory session registry default.

### `GET /api/config/upgrade`

Returns:

```json
{"base_url":"https://example.com/acecode/","auto_update":false}
```

### `PUT /api/config/upgrade`

Body:

```json
{"base_url":"https://example.com/acecode"}
```

Accepts a partial object containing `base_url` and/or boolean `auto_update`.
Normalizes and validates a non-empty HTTP(S) base URL and preserves omitted
fields. Automatic installation defaults to false, including for old configs.

### `GET /api/update/status`

For Windows MSIX/AppX installations, returns `status: "store_managed"` and
`update_available: false` before contacting the configured self-update server.
This is not an "up to date" result: the client should direct the user to
Microsoft Store's Library. No ZIP URL or target version is provided.
`POST /api/update/start` cannot create a self-update job for this installation.


Checks the update manifest and returns:

```json
{
  "status": "available",
  "update_available": true,
  "current_version": "0.5.10",
  "latest_version": "0.5.11",
  "target": "windows-x64",
  "manifest_url": "https://example.com/manifest.json",
  "package_file": "acecode.zip",
  "package_url": "https://example.com/acecode.zip",
  "package_size": 123456,
  "releases": [
    {
      "version": "0.5.11",
      "published_at": "2026-07-20T08:00:00Z",
      "notes": "1. 新增版本更新记录。\n2. 优化升级稳定性。"
    },
    {
      "version": "0.5.10",
      "published_at": "2026-07-12T08:00:00Z",
      "notes": "修复 Desktop 自动重启问题。"
    }
  ]
}
```

`releases` preserves manifest order and contains only release metadata; package
lists, hashes, and URLs are not duplicated into each entry. Legacy entries with
missing notes are returned with `notes: ""`. `http_status` and `error` are
included when present.

`status` can also be `up_to_date`, `no_compatible_package`, `invalid_config`,
`unsupported_target`, `manifest_unavailable`, or `manifest_invalid`.
`no_compatible_package` means the manifest contains a newer semantic version but
does not publish a package for this client's updater-capability target; it is not
an up-to-date result. Linux keeps the user-facing `target` as `linux-x64` or
`linux-arm64` while matching packages through the internal `updater-v1` target.

Manifest checks and package transfers do not use a fixed total request timeout.
Transport, HTTP, and file-write failures are still reported normally.

Checks and upgrades append flushed JSON diagnostic records to the ACECode data
directory's `logs/upgrade_YYYY_MM_DD_PID.log` (UTC date). Each attempt has an
`operation_id`; GUI precheck, worker, and installer records share that id, and
GUI records also include `job_id`. Records include phase, elapsed milliseconds,
versions, paths, HTTP/transport status, download byte counts, checksum values,
file backup/replacement and rollback results, and the terminal outcome. Download
progress is sampled at most once every five seconds. URL credentials, queries,
and fragments are redacted; configuration objects and response bodies are not
logged. Logs survive cancellation, retries, and process restart. Desktop restart
preflight, shutdown, and replacement launch remain in `logs/desktop-<date>.log`.
User-triggered diagnostic feedback bundles (TUI `/feedback` and
`POST /api/feedback/desktop`) merge every upgrade log written during the last
three days (72 hours by file modification time) into one
`logs/upgrade.log.tail.txt` entry, concatenated oldest to newest so the entry
reads as a timeline. The existing log-tail size limit applies to the merged
result, dropping the oldest records first. When no upgrade log was written in
that window the entry is absent; older logs are not used as a fallback.

Check and job responses include `log_path` when a log was created, and
`log_error` if diagnostics are unavailable or incomplete. Logging failures do
not change the upgrade outcome. Failure text includes the underlying error and
available log path so existing clients can display actionable diagnostics.

Check and job responses are always valid UTF-8 JSON. Operating-system and
transport error text (which Windows reports in the ANSI code page, for example
GBK on Chinese systems) is converted to UTF-8 where it is produced, and local
paths are reported in UTF-8. Any byte that still is not valid UTF-8 is replaced
with U+FFFD instead of failing the request, so a failed job with such text in
`error` keeps polling successfully.

### `POST /api/update/start`

An optional JSON body `{"automatic":true}` marks an automatic installation.
It is rejected with `409 AUTO_UPDATE_DISABLED` unless the persisted setting
is enabled, checked again after the manifest request. Empty bodies keep manual
behavior. Jobs return `automatic` and `automatic_failures` (0–3). The latter
counts consecutive automatic installation failures for the same target in the
current daemon lifetime; successful installation or a new target resets it.
Precheck and progress-query failures are not installation failures.

The GUI keeps the startup check and then checks every independently randomized
10–120 minutes regardless of this setting. Automatic check failures are silent
and preserve the last valid status. Automatic installation does not open a
dialog or restart the app. Success shows `更新已完成，重启后生效`; failure is
silent until three consecutive failures change the sidebar label to `更新失败`.
Manual retry remains available. Progress transport errors retry without
synthesizing a failed installation.

Checks for an update and starts one daemon-managed background update job. The
job reuses the normal upgrade engine without creating a console window. Returns
`202`:

```json
{
  "started": true,
  "job_id": "20260712-120000-abcd",
  "state": "pending",
  "phase": "checking",
  "current_version": "0.6.8",
  "target_version": "0.6.9",
  "bytes_downloaded": 0,
  "bytes_total": 33554432,
  "percent": 0,
  "restart_required": false,
  "cancel_requested": false,
  "can_cancel": true
}
```

Returns `409 NO_UPDATE` when the running version is already current. Returns
`409 NO_COMPATIBLE_PACKAGE` when newer releases exist but the service has no
package for this updater-capability target; the nested status object includes
`status: "no_compatible_package"`, `latest_version`, the physical `target`, and
an actionable `error`.

Other precheck failures retain HTTP `409` and the existing `NO_UPDATE` code for
compatibility, but `message` now contains the specific check failure and log
location. The response includes top-level `log_path` and the detailed `status`
object. Failure to create the worker thread returns `500 UPDATE_START_FAILED`
with diagnostic `message` and failed `job`.

Returns `409 UPDATE_IN_PROGRESS` when another job is pending or running. The
response includes that job under `job`, so another WebUI tab can attach to it.

When the daemon already holds a successful job with `restart_required: true`,
returns `202` with that same job and `started: false`, without fetching or
installing another package. This remains true while the old daemon still
reports its previous version. Failed and cancelled jobs remain retryable.

Package installation verifies the staged backend's `--version` output against
the selected release with a bounded direct child process. Flat Windows/Linux
packages also verify the installed backend before reporting success; a failed
post-copy verification rolls back the installation. Version mismatch, timeout,
invalid output and unsuccessful probe exit fail the job with an actionable error.

On macOS, a daemon running from `ACECode.app/Contents/MacOS/acecode-daemon`
installs a complete
`ACECode.app` update ZIP rather than copying files into `Contents/MacOS`. Before
replacement, the daemon requires an absolute, canonical, real `ACECode.app`
with a real, writable containing directory, a strict nested Apple signature, bundle
identifier `dev.acecode.desktop`, the selected manifest version, and the same
Developer Team ID and designated signing requirement as the installed app.
Custom folders are supported as well as `~/Applications` and `/Applications`;
App Translocation, symlinked paths, and apps nested in another `.app` are rejected.
Read-only or otherwise unwritable locations require moving the app to a writable
folder or installing manually; the updater does not elevate privileges. This does
not change the separate personal-install destination policy.

### `GET /api/update/job`

Returns the latest update job retained by the daemon. This lets a reloaded page
recover an active, completed, or failed dialog. Returns `404
UPDATE_JOB_NOT_FOUND` before any job has been started.

### `GET /api/update/jobs/:id`

Returns structured progress for one update job. `state` is `pending`, `running`,
`succeeded`, `cancelled`, or `failed`; `phase` is `checking`, `downloading`,
`verifying`, `extracting`, `installing`, `complete`, or `cancelled`.
`cancel_requested` records an accepted cooperative cancellation request, while
`can_cancel` is true only while the active job can still stop without replacing
installed files. A successful job sets
`restart_required` to `true` because the current daemon and desktop shell remain
the already-running version until ACECode is fully restarted. Failed jobs
include `error` and may be retried with a new `POST /api/update/start`.

### `POST /api/update/jobs/:id/cancel`

Requests cooperative cancellation of an active update job. Returns `202` after
the request is accepted. Downloading stops and temporary package/staging files
are removed before the job enters the `cancelled` terminal state. A cancelled
job keeps `restart_required: false`.

The endpoint returns `409 UPDATE_NOT_CANCELLABLE` after the job reaches the
`installing` phase, because interrupting file replacement could leave an
incomplete installation. Repeating the request for the same already-cancelled
job is idempotent and returns `200`; an unknown job returns `404
UPDATE_JOB_NOT_FOUND`.

In the native desktop shell, a successful job asks whether to restart now. The
restart-now action uses the in-process desktop bridge to bypass close-to-tray,
stop the shell's managed daemon processes and tray resources, release the
single-instance guard, and launch the newly installed desktop executable.
Upgrade restart always stops and waits for the managed backend, including when
background continuation is enabled; it does not change that saved preference.
A failed backend shutdown prevents replacement launch. On startup, Desktop
reuses an owned backend only if its application version and executable
installation match, recovering old backends preserved by earlier releases.
Choosing restart later leaves the current process running. Normal browser and
Edge-app compatibility clients do not own the desktop lifecycle, so they show
manual full-exit-and-relaunch guidance instead of an automatic restart action.
For a successful macOS bundle update, `backup_dir` identifies the retained
`.ACECode-<UUID>.previous.app` beside the running installation. Existing backups
are not deleted or overwritten; retained backups require manual cleanup when no
longer needed. The updater lock is opened without following symlinks and must be
a regular, singly linked file owned by the current user.

### `GET /api/mcp`

Reads global `mcp_servers` by default. Add `?workspace=<registered-workspace-hash>`
to read only that project's `.acecode/mcp.json` entries. The same optional query
applies to PUT, toggle, and reload. Unknown workspaces return `404`; filesystem
paths are not accepted as workspace identifiers. `auth_token` is not returned.
All MCP endpoints require the server's normal authentication and return
`Cache-Control: no-store`.

```json
{
  "server-name": {
    "transport": "stdio",
    "command": "node",
    "args": ["server.js"],
    "env": {},
    "url": "",
    "sse_endpoint": "/sse",
    "headers": {},
    "timeout_seconds": 30
  }
}
```

### `PUT /api/mcp`

Replaces the selected scope's server map. The body is an object keyed by server
name, without a `mcp_servers` wrapper. Project files on disk use the wrapper;
project definitions override matching global names only in that project,
including disabled definitions. An empty project map removes those overrides.

The raw body must pass the ACECode configuration JSON Schema before any
persistence, in-memory publication, or runtime update. Omitted `auth_token`
fields preserve previously saved tokens for the same server; an explicit empty
string clears a token. Successful writes reconcile the runtime when available:

```json
{"saved":true,"reload_required":false,"applied":true}
```

Without a runtime, saving still succeeds with `applied:false` and
`reload_required:true`. Persistence failures return `500` without publishing the
candidate to application configuration. Invalid JSON or schema violations
return `400` with the complete schema and JSON Pointer diagnostics:

```json
{
  "error": "MCP_CONFIG_INVALID",
  "message": "MCP configuration failed schema validation",
  "errors": [{"path": "/example/command", "message": "must be string"}],
  "schema": {"$schema": "http://json-schema.org/draft-07/schema#", "title": "ACECode MCP server configuration"},
  "specification_url": "https://modelcontextprotocol.io/specification/2026-07-28/schema"
}
```

The schema above is abbreviated for documentation; responses include all
validation rules. Diagnostics do not echo rejected configuration values.

### `GET /api/mcp/schema`

Returns `schema` (the server map accepted by PUT) and `document_schema` (the
project file wrapper). These are ACECode client configuration schemas; the
linked MCP specification describes protocol messages. Validation works offline.

### `POST /api/mcp/toggle`

Body: `{"name":"example","enabled":false}`. Both fields are required with
their declared types. The complete resulting scope is validated and saved
before updating runtime state. Unknown names return `404`. Success:

```json
{"name":"example","enabled":false,"applied":true,"retained_for_expert":false}
```

An explicitly selected expert may retain its server connection after disabling
the default. Retention is scoped to the exact global/project owner.

### `POST /api/mcp/reload`

Re-reads the selected persisted configuration, validates it, and reconciles its
runtime registrations and session capability policies. Invalid external edits
restore the validated `<config-file>.mcp-last-good` snapshot and archive the
invalid input. Global recovery replaces only `mcp_servers`; project recovery
affects only that project file. If no valid snapshot exists, returns the schema
error and starts no servers from the invalid configuration. Returns `503` when
no runtime is available. Success:

```json
{"reloaded":true}
```

### `GET /api/feedback/desktop/recent-sessions?limit=N`

Returns recent sessions for optional feedback attachment. `limit` defaults to
`20` and is clamped to `1..100`.

```json
{"sessions":[{"id":"sid","session_id":"sid","title":"...","workspace_hash":"abc123"}]}
```

Sessions that belong to no workspace (the sidebar task list) are included with
`workspace_hash: ""` and `no_workspace: true`; submit them with the same empty
hash.

### `POST /api/feedback/desktop`

Windows MSIX/AppX installations require an HTTPS feedback endpoint. If the
configured service uses HTTP, this endpoint returns `502 UPLOAD_FAILED` with
an HTTPS requirement message before uploading the package. The retained local
package path is reported as for other upload failures. Unpackaged installations
retain the existing configurable HTTP/HTTPS behavior.


Body fields are optional strings:

```json
{
  "feedback_text": "Settings page froze",
  "session_id": "sid",
  "workspace_hash": "abc123"
}
```

`workspace_hash` scopes the session lookup to one workspace. When it is empty,
the daemon searches every registered workspace and then the no-workspace session
cache, so a session without a workspace attaches its transcript like any other.

The package carries the newest rotated Desktop shell log (`desktop-<date>.log`)
and the daemon log (`daemon-<date>.log`) that serves the request. Each is
truncated to its last 512 KiB and stored as `logs/desktop.log.tail.txt` /
`logs/daemon.log.tail.txt`. A runtime with no log file present is skipped
silently, so a browser-only deployment uploads the daemon log alone. Desktop
feedback does not attach `tui-<date>.log`; terminal `/feedback` instead carries
`tui-<date>.log` plus the daemon log and does not attach the Desktop log. Upgrade diagnostics
(`upgrade-<date>-<pid>.log`, one file per process) are handled as a window
rather than a single newest file: every upgrade log modified within the last
three days (72 hours) is merged oldest-first into `logs/upgrade.log.tail.txt`,
truncated as a whole to the same 512 KiB tail; with no upgrade activity in that
window the entry is omitted. If `session_id` is empty, the package contains
those logs only. When a session is selected, the package also carries that
session's request trajectory (`<project_dir>/<session_id>/trajectory.jsonl`:
every model request's full messages and tool list, plus each response's text,
tool calls and usage) as `session/<session_id>.trajectory.jsonl`. It keeps the
newest 4 MiB, starting at the first complete line after the cut so every packed
line is valid JSON; a single record larger than the cap keeps its partial tail.
A missing trajectory file is skipped without failing the upload. `feedback.json`
records it under `trajectory` (`entry_name`, `path`, `available`, `size_bytes`,
`tail_bytes`, `truncated`), and `included_files` lists the entry right after the
session JSONL when it was packed. Terminal `/feedback` attaches the active
session's trajectory the same way. The upload target is derived from `upgrade.base_url`.

Success:

```json
{
  "ok": true,
  "package_filename": "acecode-feedback-desktop-....zip",
  "log_included": true,
  "log_tail_bytes": 4312,
  "logs": [
    {
      "entry_name": "logs/desktop.log.tail.txt",
      "path": "/home/u/.acecode/logs/desktop-2026-06-18.log",
      "available": true,
      "tail_bytes": 1200
    },
    {
      "entry_name": "logs/daemon.log.tail.txt",
      "path": "/home/u/.acecode/logs/daemon-2026-06-18.log",
      "available": true,
      "tail_bytes": 3112
    }
  ],
  "included_files": ["logs/desktop.log.tail.txt","logs/daemon.log.tail.txt","feedback.json"],
  "selected_session_id": null,
  "workspace_hash": ""
}
```

`log_included` is true when at least one log made it into the archive, and
`log_tail_bytes` is the sum across all of them; `logs[]` reports each requested
source, including the ones that were unavailable. Upgrade log files merged into
`logs/upgrade.log.tail.txt` each get their own `logs[]` row sharing that
`entry_name`; a row's `tail_bytes` is what that file contributed after the
merged tail was truncated (0 when the cap dropped it entirely while
`available` stays true), and `included_files` lists the merged entry once. The
same array is mirrored into the archive's `feedback.json` under `logs`.

`feedback_text` accepts at most 10,000 Unicode code points, including spaces and
line breaks. Oversized text returns HTTP 400 with `FEEDBACK_TOO_LONG` before any
logs are collected, package is created, or upload is attempted.

Other errors include `SESSION_NOT_FOUND`, `PACKAGE_FAILED`, and `UPLOAD_FAILED`.

---

## 11. Console PTY

PTY endpoints are loopback-only because they execute shell input without the
agent tool permission gate. Non-loopback requests return `403` even with a
token.

### `GET /api/pty/shells`

Returns detected shell choices and the configured default:

```json
{
  "shells": [
    {"id":"powershell","label":"PowerShell","available":true,"needs_path":false,"path":"C:/Program Files/PowerShell/7/pwsh.exe","configured_path":"","probed":true,"usable":true,"probe_error":""}
  ],
  "default": "powershell"
}
```

The response also includes `resolved: {id,family,program,console_command,usable,fallback_reason}`.
`available` describes file discovery; `usable` reflects an actual launch probe when
`probed` is true. Unprobed choices are checked when selected. The default and new
PTY sessions use the same resolved terminal as the Agent's command tool.

### `PUT /api/console/config`

Body:

```json
{"default_shell":"powershell","shell_path":"C:/mytool/pwsh.exe"}
```

Both fields are optional. `shell_path` applies to the selected `default_shell`;
an empty path restores automatic discovery. Non-empty paths must be absolute
regular files and pass a launch probe. Unknown types, wrong JSON types, missing
files, WSL bash for the Git Bash type, and failed probes return `400` without
changing either the saved config or runtime. Persistence failures return `500`.
The legacy `git_bash_path` field remains accepted. Returns the same payload as
`GET /api/pty/shells`; running terminals retain their original process.

### Settings environment endpoints

These endpoints use the normal authenticated API access policy.

- `GET /api/config/toolchains` returns `{toolchains:[{id,label,dir,exists,anchor,applied}]}`,
  where `id` is `python`, `node` or `csharp`. `PUT` accepts a partial object of
  those directory strings. Empty clears a directory; non-empty values must be
  existing absolute directories. Validation errors return `400` with
  `INVALID_FIELD`, `DIRECTORY_NOT_ABSOLUTE` or `DIRECTORY_NOT_FOUND` and leave
  the complete previous configuration unchanged. Successful saves update the
  process PATH for subsequently launched tools, hooks, MCP servers and terminals.
- `POST /api/config/toolchains/detect` searches the original process PATH, skipping
  Windows Store aliases. Found directories replace those fields; missing tools
  preserve existing choices. It returns the same list plus `detected:{python,node,csharp}`.
- `GET /api/console/config` returns `{default_shell,shell_paths,resolved,candidates}`.
  Each candidate includes `id,label,family,available,needs_path,probed,usable,program,
  detected_path,configured_path,probe_error`. `POST /api/console/config/detect`
  reruns launch probes, persists a usable resolution and returns the same shape.
  Candidates depend on the host platform. Windows tries PowerShell 7, Windows
  PowerShell, Git Bash and cmd; POSIX uses the login shell and available alternatives.
- `POST /api/dialog/pick-folder` and `POST /api/dialog/pick-file` return `{path}`,
  or JSON `null` when cancelled. Native picker support must be enabled by the host;
  otherwise the response is `501 {error:"PICKER_UNAVAILABLE",message}` and the UI
  accepts a manually entered path.

### Data directory migration

`GET /api/config/data-dir` returns `effective_dir`, `default_dir`, `redirect_active`,
`redirect_target`, `migrated_at_ms`, `cleanup_pending` and `migration` (null or the
job below). Existing backups add `previous_dir` and `previous_size_bytes`. After
restart, a pending backup larger than 100 MiB also adds
`cleanup:{previous_dir,size_bytes}`. `previous_size_bytes` is the old directory's
footprint at migration time: every enumerated file plus the excluded entries and
skipped Agent Browser caches listed below, which stay in the old directory until it
is cleaned up (it is not the copied byte count).

`POST /api/config/data-dir/migrate` accepts `{target:"<absolute path>"}` and returns
`202` with a job containing `state`, `target`, `copied_bytes`, `total_bytes`,
`skipped_files`, `error`, `restart_required`, `started_at_ms` and `finished_at_ms`.
`skipped_files` counts Agent Browser profile files that could not be copied (see
below); when it is greater than zero the Agent Browser may need to sign in again
after restart. Poll
`GET /api/config/data-dir/migration`; states are `running`, `done` or `failed`.
Before any job has started the poll endpoint returns `404 MIGRATION_NOT_FOUND`.

Target validation returns `400` with `TARGET_REQUIRED`, `TARGET_NOT_ABSOLUTE`,
`TARGET_SAME_AS_CURRENT`, `TARGET_INSIDE_CURRENT`, `TARGET_CONTAINS_CURRENT`,
`TARGET_NOT_A_DIRECTORY`, `TARGET_NOT_EMPTY` or `TARGET_NOT_WRITABLE`. Paths are
compared after canonicalization. A busy Agent returns `409 SESSIONS_BUSY` with an
additional sorted `busy_sessions:[<session id>, ...]` field, another
live daemon returns `409 OTHER_INSTANCES_ACTIVE`, and open console terminals return
`409 CONSOLES_ACTIVE`. Every refusal of the migrate and cleanup routes is logged as
`[data-dir] migration refused: <CODE> ...` / `[data-dir] cleanup refused: <CODE> ...`
with the busy session ids, the blocking `daemon.pid` (`pid=<n> file=<path>
legacy=<yes|no>`, `legacy` meaning it lives under `projects/*/run`), the running
console ids or the rejected target.

A `daemon.pid` under `run/**` or `projects/*/run/**` blocks migration (and cleanup
delete of the previous directory) only when its process is alive, is not the
current process, and PID reuse is not proven. Reuse is proven, with the same rule
the Desktop daemon pool uses, when the live process image is not ACECode or the
process started more than 2 seconds after the heartbeat recorded in that run
directory; such pid files are ignored and logged at INFO. An unreadable process
identity without a usable heartbeat still blocks (fail-closed). This keeps stale
pid files left under the legacy `projects/*/run` directories from blocking
migration forever once Windows reassigns their PID to an unrelated process.

The job pauses the scheduler and copies through a private staging directory,
excluding top-level `run/`, `tmp/`, `edge-app-profile/` (the Edge `--app` profile of
webapp compatibility mode, recreated on every launch), the redirect pointer, lock
files and `cache/no-workspace/<id>/.acecode/tmp` (the scratch `ACECODE_TMPDIR` of
no-workspace sessions; other files in that session directory are copied). Once the
old directory is deleted, history references to those scratch files (including
Agent Browser screenshots) no longer resolve. SQLite databases use online backups,
including committed WAL transactions; after a database is snapshotted its `-wal`,
`-shm` and `-journal` files are not copied, because a hot journal next to a
consistent snapshot would roll it back. Symlinks are
preserved (internal targets follow the new root); inability to preserve them fails
the copy. Source changes and a newly occupied target abort publication; the error
names the changed or new entry by its relative path. Failure
removes only private staging, preserves the source and existing target files,
and re-enables writes. A pointer-write failure retains the copied target for recovery.
The staging directory is a sibling of the target named `.acecode-mig-<8 hex>`.

`agent_browser/webview2` (the Desktop Agent Browser profile, open and written for
the whole Desktop lifetime; installations that already had the legacy
`agent-browser/webview2` keep that name, and both are recognized) is copied
best-effort: it is enumerated separately and
tolerates entries vanishing mid-walk, skips rebuildable caches (`Cache`,
`Code Cache`, `GPUCache`, `GrShaderCache`, `GraphiteDawnCache`, `DawnCache`,
`DawnGraphiteCache`, `DawnWebGPUCache`, `ShaderCache`, `Crashpad`) and `lockfile` /
`LOCK`, snapshots SQLite files with a 500 ms busy timeout and falls back to a raw
copy, and counts a file in `skipped_files` only when that also fails (a file that
disappeared is not counted). The subtree is excluded from the source-change
recheck. Data written after the snapshot is lost, so the worst case is signing in
to the Agent Browser again; ACECode's own data is never copied best-effort.

On Windows, migration and cleanup perform file IO (enumeration, stat, directory
creation, copy, rename and recursive removal) through extended-length `\\?\` paths,
so files beyond `MAX_PATH` (260 characters) can be copied and deleted. Extended
paths never appear in responses, the redirect pointer or logs. SQLite databases are
still opened by their normal path unless it reaches 240 characters. The ACECode
runtime is not long-path aware: a copied file whose final path reaches 260
characters may be unreadable at runtime, and completion logs a warning with the
count and one sample path.

Success atomically publishes the copied directory, writes `data_dir.redirect.json`
in the platform default data directory, and sets `restart_required:true`. The
current process continues reading the old root; new turns and authenticated
mutations are rejected with `409 DATA_DIR_MIGRATION_ACTIVE` until restart.

`POST /api/config/data-dir/cleanup` accepts `{action:"keep"}` or `{action:"delete"}`.
Both acknowledge the cleanup prompt and return updated directory status. Delete
requires a restart into the new root, verifies the recorded old directory is not
the active root or its ancestor, and refuses a still-running old daemon. When the
backup is the default directory, its redirect pointer is preserved. Failures
return `409 NO_MIGRATION`, `409 SESSIONS_BUSY`, `500 CLEANUP_FAILED` or
`500 PERSIST_FAILED`; invalid actions return `400 INVALID_ACTION`.

### `POST /api/pty`

Body:

```json
{"cwd":"C:/repo","title":"Terminal","shell":"powershell","owner_id":"session:abc"}
```

`shell` is a shell id from `/api/pty/shells`. The daemon enforces a 16-session
limit and returns `429` when exceeded.

`owner_id` identifies the conversation (`session:<id>`) or temporary new-chat
state (`draft:<id>`), independently of `cwd`. It is limited to 512 bytes.
Omitting it preserves the legacy unowned terminal behavior.

Session info:

```json
{
  "id": "pty-1",
  "owner_id": "session:abc",
  "title": "Terminal 1",
  "shell": "C:/Windows/System32/WindowsPowerShell/v1.0/powershell.exe",
  "cwd": "C:/repo",
  "status": "running",
  "pid": 12345,
  "backend": "conpty",
  "exit_code": 0
}
```

`exit_code` appears only when `status == "exited"`.

### `GET /api/pty`

Optional `owner_id` query parameter filters by owner. Omitted means all terminals;
an explicit empty value selects legacy unowned terminals. The WebUI always sends
the current owner and never attaches legacy terminals to an arbitrary conversation.

Returns:

```json
{"backend":"conpty","sessions":[]}
```

### `POST /api/pty/transfer-owner`

```json
{"from_owner":"draft:unique-id","to_owner":"session:new-session-id"}
```

Moves a new-chat draft's terminals to the newly created conversation without
restarting processes, clearing buffers or disconnecting subscribers. Late creates
with the old draft owner follow the transfer. Identical retries return `204`;
invalid owner prefixes, an already occupied target or a conflicting prior transfer
return `409`. A malformed body returns `400`. Existing conversation-to-conversation
transfers are rejected. Uses the same loopback/auth checks as all PTY endpoints.

### `DELETE /api/pty/:id`

Kills/removes the PTY session. Returns `204` or `404`.

### `POST /api/pty/:id/resize`

Body:

```json
{"cols":120,"rows":30}
```

`cols` and `rows` must be in `2..1000`. Returns `204`.

### `POST /api/pty/:id/title`

Body:

```json
{"title":"npm run dev"}
```

Used by the frontend to persist xterm OSC title changes. Returns `204`.

---

## 12. Session WebSocket

Route:

```text
WS /ws/sessions/:route?token=<token>
```

The frontend currently connects to `/ws/sessions/_multiplex`. The route
parameter is not the session id; sessions are bound by JSON messages after the
socket opens.

### Server event envelope

Session events are JSON objects:

```json
{
  "type": "token",
  "seq": 1,
  "timestamp_ms": 1783152000000,
  "session_id": "sid",
  "workspace_hash": "abc123",
  "payload": {}
}
```

Most session event frames include a per-session `seq` and `timestamp_ms`.
The exceptions are pending `permission_request` and `question_request`
snapshot frames sent immediately after `subscribe_ack`. These replay frames
intentionally have no `seq` so clients do not advance or warn on the reconnect
cursor. Clients should de-duplicate both interaction types by
`payload.request_id` and retain resolved tombstones until the owning turn is
terminal so a delayed snapshot cannot reopen a closed request.

Each active session retains at most 1024 replay events and an estimated 8 MiB
of event payload/container storage. The oldest retained events are evicted when
either limit is reached. A single event larger than the byte budget is delivered
live but is not retained for replay. `since` only replays retained events; it does
not guarantee recovery of older or oversized frames. Load the session history
through REST when a complete persisted transcript is needed.

Session event `type` values from `SessionEventKind`:

- `token`
- `reasoning`
- `agent_progress`
- `message`
- `tool_start`
- `tool_update`
- `tool_end`
- `permission_request`
- `permission_closed`
- `question_request`
- `question_closed`
- `usage`
- `transcript_replace`
- `goal_updated`
- `goal_cleared`
- `todo_updated`
- `background_task` — `{"task": {...}}` when a background command or background subagent
  starts, finishes or changes state (see "Background tasks")
- `session_updated`
- `busy_changed`
- `done`
- `error`

`session_updated` carries the session's display-title fields, which are the
only source clients may use for a session's name. A rename or a generated title
sends `{"title", "title_source"}`. After each visible user message is persisted
the daemon sends `{"summary"}`: the latest user message's display text
(`metadata.display_text` when present, otherwise `content`) collapsed to one
line and truncated to 80 UTF-8 bytes plus `...`. The same three fields appear in
session listings and in the `GET .../messages?since=0` snapshot. A swarm-mode
switch sends `{"swarm_mode"}` (`"off" | "star" | "mesh"`); session listings and
the messages snapshot carry the current `swarm_mode` too, plus `agent_path`
(`/root/...`) for mesh sub-agents. Clients show
`title` when it is non-empty (ignoring generated titles that start with
`[Error]`) and `summary` otherwise, in both the session list and the chat
header; they must not derive a title from message bodies.

Each tool call is also mirrored by two display-only `message` events that are
never persisted: role `tool_call` (content `[Tool: <name>] <arguments>`) before
the result is collected, and role `tool_result` (the displayed output) after it.
Both carry `metadata.tool_call_id`, `metadata.tool_index` and
`metadata.tool_name`, matching the `tool_start` / `tool_end` payloads of the same
call, and their `id` is distinct per call even when two calls have identical
content. Clients pair these rows with the structured tool by `tool_call_id`, and
de-duplicate replayed rows against history (the persisted `assistant.tool_calls`
and role `tool` result) by the same id rather than by content.

For a successful `task_complete` call, the `tool_end` payload also includes
`message_id`, the canonical id of the persisted tool-role result. Live and
trajectory/replay records use the same id so clients can attach copy, fork, and
other message actions to the completion summary without relying on its
synthetic display id.

The same `tool_end` payload (and the persisted role `tool` result's `metadata`)
carries the normalized "next step" box in `metadata.wrap_up`:

```json
{"recap": "Fixed the null check; nothing committed.", "box": true,
 "ask": "Commit now?", "actions": [{"label": "Commit"}, {"label": "Not now"}],
 "blocked": false}
```

`recap` is the turn summary (also the `summary` metric of `tool_summary`).
`box`, `ask` and `actions` are present only when the box shows a question: a
non-empty `ask` with a valid first reply button, or `blocked: true`. At most two
buttons are kept, the first is the recommendation, and labels that start with
`/` or `!` or carry invisible characters are dropped. Clients send a clicked
label as an ordinary user message. The result `output` is a short receipt for
the model, not text for the user; older sessions without `wrap_up` keep using
the summary metric.

Completed tool text above the per-result limit (30,000 bytes for Bash, 50,000
bytes for other tools) is saved under the session's `tool-results` directory
before `tool_end` or the result message is broadcast. Their output contains the
existing `<persisted-output>` file reference and a 2,000-byte preview. Structured
file-diff hunks, metadata and attachments remain available. The aggregate
model-context budget still applies later. As with the existing result budget,
if storage fails the original completed result is retained rather than discarded;
the preview reduction is therefore not guaranteed during storage failures.

`tool_end.hunks[]` entries carry `old_start`, `old_count`, `new_start`,
`new_count` and `lines[]`. A multi-file result (the `apply_patch` tool used by
GPT / Codex models) additionally sets `file` (absolute path), `additions` and
`deletions` on every hunk so clients can group hunks per file; single-file
results from `file_edit` / `file_write` omit these keys and clients keep using
`summary.object` as the file name. `apply_patch` results also expose
`metadata.files[]` with `path`, `type` (`add` | `update` | `delete` | `move`),
optional `move_path` / `from_path`, `additions` and `deletions`. The same hunk
shape is persisted under the tool message's `metadata.tool_hunks`.

The start of a regular agent turn includes
`{"busy":true,"turn_id":"initial-user-message-uuid"}`. That id stays stable
across tool calls, model retries, and accepted steering input. For the terminal
transition, `busy_changed` includes the turn-wide usage summary:

```json
{
  "busy": false,
  "outcome": "completed",
  "turn_id": "initial-user-message-uuid",
  "usage": {
    "prompt_tokens": 44100,
    "completion_tokens": 2100,
    "total_tokens": 46200,
    "cache_read_tokens": 32000,
    "cache_write_tokens": 0,
    "reasoning_tokens": 500,
    "has_data": true
  }
}
```

The following `done` frame repeats the same `outcome`, `turn_id`, and `usage`.
The summary adds every accounted model step in the turn, including tool-call
round trips. It is not another incremental delta to add to preceding `usage`
or `model_step_finish` events. `has_data` is true only when at least one model
step was accounted and every included step used provider-reported usage; if
ACECode estimated any included step, counts still include that estimate but
`has_data` is false. `context_breakdown`, when present, is also summed across
included steps.

Other busy cycles such as compaction may omit `outcome`, `turn_id`, and
`usage`. Clients should only treat `completed` as a successful turn.

Transient pure-sampling failures use `agent_progress` rather than transcript
messages. While waiting, the payload is:

```json
{
  "phase": "model_retry",
  "label": "网络暂时不可用，等待重试",
  "retry_attempt": 12,
  "retry_delay_ms": 1200000,
  "retry_at_ms": 1783153200000,
  "retry_max_attempts": 0
}
```

Non-positive `retry_max_attempts` means the count is unbounded (current providers
use `0`; older events may contain `-1`). Small rejected requests use 5, 10, 20,
40, then 60-second waits, with no retry-count limit. Immediately before the
next attempt, another `agent_progress` frame changes `phase` back to
`model_waiting` (or `compacting`) and sets `retry_delay_ms` to zero. The retry
wait is cancellable through the existing abort/stop path. A replay also emits
`transcript_replace` so provisional text, reasoning, usage, and tool-call
fragments from the failed attempt disappear without becoming conversation
history.

`transcript_replace` is for retry/recovery cleanup. Normal compact success
appends visible marker messages and a hidden checkpoint instead.

Visible messages belonging to one compact operation carry lifecycle metadata:

```json
{
  "transcript_only": true,
  "compact_notice": true,
  "compact_notice_id": "019f85aa-3a00-7000-8000-000000000005",
  "compact_notice_stage": "progress|checkpoint|summary|warning|error",
  "compact_notice_complete": false
}
```

Manual and automatic compaction reuse one UUIDv7 `compact_notice_id`. Only the
terminal warning of a successful operation sets `compact_notice_complete` to
`true`; failures remain incomplete. Clients may therefore show incoming details
while the operation runs and replace a completed group with one expandable
`Context compacted` row without changing append-only transcript persistence.

### Client messages

All client frames are JSON:

```json
{"type":"subscribe","payload":{"session_id":"sid","since":42}}
```

| Type | Payload | Behavior |
|---|---|---|
| `hello` | `{session_id,since}` | legacy bind; ack is `hello_ack` |
| `subscribe` | `{session_id,since}` | subscribes one session; ack is `subscribe_ack` (its payload adds `event_seq` / `event_epoch` while the session is loaded); may then send child status discovery and seq-less pending permission/question snapshots |
| `unsubscribe` | `{session_id}` | unsubscribes; ack is `unsubscribe_ack` |
| `status_subscribe` | `{workspace_hash}` or `{session_id}` | subscribes workspace attention status and sends snapshot |
| `status_unsubscribe` | `{workspace_hash}` | unsubscribes; ack is `status_unsubscribe_ack` |
| `mark_session_read` | `{session_id,workspace_hash,cursor}` | persists read cursor; ack is `mark_session_read_ack` |
| `mark_session_unread` | `{session_id,workspace_hash}` | rewinds the read cursor just before the latest output (a session with no output yet gets `update_cursor=1`), persists it and broadcasts `session_status`; a later `mark_session_read` restores `read`. A busy session still reports `in_progress` until its turn ends. Ack is `mark_session_unread_ack` with the same status payload |
| `user_input` | `{session_id,text}` | queues plain user input |
| `decision` | `{session_id,request_id,choice}` | responds to permission request; `choice` is `allow`, `deny`, `allow_session`, `allow_scoped`, or `allow_remember` |
| `question_answer` | `{session_id,request_id,cancelled,answers}` | responds to AskUserQuestion |
| `abort` | `{session_id}` | requests cancellation of the current turn; completion is confirmed by terminal events |
| `ping` | `{}` | replies `{"type":"pong"}`. The Web client pings after 20 s without any frame and reconnects when nothing arrives within 10 s of a ping |

`decision` uses `choice`, not `decision`, in the payload.

Sending `abort` does not mean the turn has already ended. Clients keep the
turn busy while showing a stopping state, then settle it on the matching
`busy_changed(false)` or `done` event. Terminal `turn_id` values must not end
a different active turn. The persisted `user_aborted` message confirms the
same termination notice even when tool messages arrive in between; older
records without `turn_id` are matched only within their user-turn boundary.
Queued input remains visible during cancellation. Previously queued messages
pause on a user stop; an explicit send or resume during stopping is honored
after completion. A client that cannot send the stop request must report the
failure and allow retry rather than displaying a completed stop.

For `bash`, `permission_request.args` retains the original tool arguments and
adds a server-generated `permission` object:

```json
{
  "command": "pnpm install",
  "sandbox_permissions": "require_escalated",
  "justification": "Install dependencies using the shared cache.",
  "permission": {
    "reason": "escalation_requested",
    "request": "require_escalated",
    "sandbox": "full-access",
    "always_allow_prefix": "pnpm install",
    "proposed_prefix_rule": "pnpm install",
    "scoped_write_root": "/home/u/.cache/pnpm",
    "denied_path": "/home/u/.cache/pnpm/store.lock",
    "classification": "unknown"
  }
}
```

`reason` can be `dangerous_command`, `escalation_requested`,
`additional_permissions_requested`, `unknown_command_without_sandbox`,
`rule_prompt`, `default_mode`, or `plan_mode`. `request` echoes the model's
`sandbox_permissions` value (`use_default`, `with_additional_permissions`, or
`require_escalated`; the legacy `with_escalated_permissions=true` maps to
`require_escalated`). `sandbox` describes the approved execution boundary:
`full-access`, `workspace-write`, or `read-only`. An empty `always_allow_prefix`
means no session approval can be remembered. Shell interpreters and opaque
scripts do not acquire broad session approval. Remembered sandbox approvals
never become full access when a backend becomes unavailable.

Optional fields only appear when the corresponding choice is available:

- `additional_permissions` (`{read:[],write:[],network:bool}`) lists what a
  `with_additional_permissions` request asks for; `allow_session` then keeps
  those grants for the session instead of remembering a command prefix.
- `scoped_write_root` is offered on escalation requests when the previous
  sandboxed run was denied on a known path outside the deny list; `allow_scoped`
  grants write access to only that directory for the session and runs the
  command inside the `workspace-write` sandbox.
- `denied_path` is the path extracted from that previous denial, for display.
- `proposed_prefix_rule` is the prefix `allow_remember` appends to the global
  rules file (`<data_dir>/rules/default.rules` for approvals that leave the
  sandbox, `default.sandboxed.rules` otherwise). It is absent for interpreters,
  `rm`, `sudo`, and other banned prefixes.

Clients that send `allow_scoped` or `allow_remember` for a request that did not
offer them are treated as `allow` and `allow_session` respectively.

Denied sandboxed runs return `metadata.sandbox_violation`
(`{reason, path?, snippet}`) alongside `metadata.sandbox_denied`; `reason` is
one of `operation_not_permitted`, `permission_denied`, `read_only_file_system`,
`access_denied`, `policy_denied`, `failed_to_write_file`, or `sigsys`.

The built-in `sandbox` command supports empty args (status), `off`, and `on`
through the existing session command endpoint. It is session-local and does not
save configuration. See [sandbox.md](sandbox.md) for rules and platform limits.

Each `permission_request` is followed by exactly one sequenced
`permission_closed` event with `{request_id,choice,reason}` when it stops being
actionable. `choice` is `allow`, `deny`, `allow_session`, `allow_scoped`, or
`allow_remember`; `reason` is `decision`, `permission_mode_change`, `abort`, or
`timeout`. A timeout still
emits the existing `error` event with `reason:"permission_timeout"` after the
close event.

`question_answer.answers[]` entries are:

```json
{
  "question_id": "q1",
  "selected": ["option-id"],
  "custom_text": "free form"
}
```

Completed AskUserQuestion results carry UI-only
`metadata.ask_user_question_result` in `tool_end` events and persisted tool
messages. Successful answers contain ordered `items` with `question` and
`answer` text. Explicit rejection contains `{"cancelled":true,"items":[]}`;
its `success` remains `false` and its provider-visible output remains
`[Error] User declined to answer questions.`. Clients can use this namespaced
marker to retain cancellation feedback after reloading history. A generic
tool's unrelated `metadata.cancelled` flag is not question-result metadata.
A question resolved by a free-form interjection carries
`{"interjected":true,"items":[]}` with `success:true`; its provider-visible
output starts with `[User interjected]` and the interjection itself is the
next persisted user message.

#### AskUserQuestion answer policy (`agent_loop.question_policy`)

`question_request` / `question_closed` behavior depends on the configured
answer policy (`config.agent_loop.question_policy`, or the
`--question-policy` CLI override):

- `ask` (default): `question_request` is emitted and the turn blocks until
  `question_answer` arrives (or the turn is aborted). Unchanged behavior.
- `deny`: no `question_request` is emitted at all. The tool returns an
  automatic answer instructing the model to decide autonomously.
- `timeout`: `question_request` is emitted normally; if no `question_answer`
  arrives within `question_timeout_seconds`, the daemon closes the question
  with `question_closed` `reason:"timeout"` and the tool auto-adopts the
  first (recommended) option of each question. A `question_answer` arriving
  after the timeout is ignored (unknown `request_id`).

YOLO affects tool permission confirmations only; it does not change the
question policy, so `AskUserQuestion` remains interactive in YOLO. While an
active `/goal` is running, each question uses a per-call 30-second timeout
regardless of the configured timeout value, then auto-adopts the first
(recommended) option.

`question_closed.reason` values: `answered`, `cancelled`, `aborted`,
`timeout`, `interjected` (resolved through
`POST /api/sessions/:id/questions/interject`). Frontends must dismiss the
question modal on any `question_closed` for the pending `request_id`.

When more than one session is subscribed, session-targeted messages should
include `payload.session_id`.

### Acks and status messages

Subscribe ack:

```json
{
  "type": "subscribe_ack",
  "session_id": "sid",
  "workspace_hash": "abc123",
  "payload": {"session_id":"sid","workspace_hash":"abc123","cwd":"C:/repo"}
}
```

For a subagent session, both the ack envelope and payload include the additive
`parent_session_id` field:

```json
{
  "type": "subscribe_ack",
  "session_id": "child-sid",
  "parent_session_id": "parent-sid",
  "payload": {
    "session_id": "child-sid",
    "parent_session_id": "parent-sid",
    "workspace_hash": "abc123",
    "cwd": "C:/repo"
  }
}
```

Subscribing to a parent session also registers it for status delivery. The
server sends current `session_status` frames for that parent's child sessions
after the ack, and future child status broadcasts are delivered through the
parent subscription even when there is no workspace subscription. Child status
envelopes and payloads include `parent_session_id`; unrelated parent
subscriptions do not receive them.

Workspace status snapshot:

```json
{
  "type": "session_status_snapshot",
  "timestamp_ms": 1783152000000,
  "workspace_hash": "abc123",
  "payload": {
    "workspace_hash": "abc123",
    "sessions": [
      {
        "session_id": "sid",
        "workspace_hash": "abc123",
        "cwd": "C:/repo",
        "state": "read",
        "attention_state": "read",
        "read_state": "read",
        "busy": false,
        "cursor": 0,
        "update_cursor": 0,
        "read_cursor": 0
      }
    ]
  }
}
```

Attention payloads, session lists and snapshots also include `manual_unread`
(boolean, default `false` for legacy state). Explicit unread sets it and explicit
read clears it, including while a turn is running. Read cursors and this flag are
persisted for workspace and no-workspace sessions. Restoring the currently open
chat after a restart does not consume manual unread; actively opening the chat
or explicitly marking it read does. Windows Desktop uses the same global unread
root-task count for the taskbar badge and the tray icon's lower-right red dot.

Live attention updates use `type:"session_status"` with the same payload shape
for one session.

### Reconnect strategy

1. Store the highest processed `seq` per session, together with the
   `event_epoch` from the last `subscribe_ack` / `hello_ack`.
2. Reconnect and send `subscribe` with `since:<lastSeq>`.
3. The daemon replays buffered events with `seq > since`, then sends the ack.
   Replayed events always arrive before the ack, so the ack's `event_seq` is never
   lower than any replayed frame.
4. If the ack's `event_epoch` differs from the stored one, or the stored `seq` is
   greater than the ack's `event_seq`, the stored cursor belongs to a dispatcher
   instance that no longer exists: reset it to 0 and reconcile the transcript from
   `GET /api/sessions/:id/messages` before trusting `seq` ordering again.
   Otherwise every new event would be dropped as already seen.
5. If the replay gap is too old, fall back to
   `GET /api/sessions/:id/messages?since=0`.

Live delivery does not depend on `since`; only replay does.

Seq-less pending `permission_request` and `question_request` snapshots do not
affect the reconnect cursor; handle them by `request_id`.

---

## 13. PTY WebSocket

Route:

```text
WS /ws/pty/:id?cursor=N&token=<token>
```

This socket is loopback-only. Unlike the session socket, it is a raw byte
transport, not JSON envelopes.

Server to client:

- Binary frames are PTY output bytes.
- Frames whose first byte is `0x00` are UTF-8 JSON control frames, such as
  `{"cursor":123}` after backlog replay or `{"exit_code":0}` on exit.

Client to server:

- Text or binary frames are written verbatim to PTY stdin.

Each PTY session keeps a 2 MB rolling output buffer with a monotonic byte
cursor. `cursor=N` replays from that offset; `cursor=-1` skips backlog.
Resize uses `POST /api/pty/:id/resize`, not the WebSocket.

---

## 14. Scheduled tasks

Scheduled tasks (Chinese UI: “定时任务”, internal identifier: LOOP) is a daemon-owned scheduler. It persists to
`<acecode_dir>/scheduled_loops.sqlite3` and continues running without an open
browser. Clients configure friendly period/interval/once fields; the compiled
schedule expression is internal and is never returned by the API.

The daemon also registers the deferred built-in `create_scheduled_task` tool.
Loading the `scheduled-task` skill exposes it only in that conversation's model
requests. It shares request validation and persistence with the manual form.
The tool asks for execution permission before saving (YOLO is the recommended
choice; `default` is also available). Cancelled, unanswered, or automatically
timed-out choices do not create a task. Success returns `created`, `task`, and
`schedule_summary`; the task includes `id` and `next_run_at_ms`. The creating
conversation can finish immediately; execution follows the scheduler's policy.

Routes (all use the normal daemon auth and CORS rules):

| Method | Route | Purpose |
|---|---|---|
| `GET` | `/api/loops` | List LOOP definitions |
| `POST` | `/api/loops` | Create a LOOP (`201`) |
| `GET` | `/api/loops/:id` | Read one LOOP |
| `PUT` | `/api/loops/:id` | Replace one LOOP |
| `DELETE` | `/api/loops/:id` | Delete one LOOP and its run history |
| `PUT` | `/api/loops/:id/enabled` | Enable/disable with `{"enabled":true}` |
| `GET` | `/api/loops/:id/runs?limit=N` | Recent run history (`1..500`) |
| `POST` | `/api/loops/:id/run` | Run once immediately using saved execution options (`202`, run object) |

`POST /api/loops/:id/run` requires authentication and accepts an empty JSON object.
It preserves the schedule, next scheduled time and enabled state, including for disabled
or expired tasks. The scheduler owns execution and records it in the usual run history.
An active execution of the same task returns `409 LOOP_BUSY`; another active scheduled
task in the same workspace returns `409 WORKSPACE_BUSY`. Missing tasks return `404`,
an unavailable scheduler returns `503` (or `501` when unsupported by the server).

Each item returned by `GET /api/loops` includes a nullable `latest_run` field.
When present, it is the newest run-history object for that LOOP, including its
current `status` and timestamps. Clients may poll this route to refresh running,
waiting, completed, missed, and failed states without keeping the details panel
open.

Create/update body:

```json
{
  "name": "Daily code review",
  "prompt": "Review recent changes and run relevant tests.",
  "workspace_hash": "0123456789abcdef",
  "workspace_cwd": "C:/repo",
  "model_name": "gpt-5.5-codex",
  "permission_mode": "yolo",
  "use_worktree": false,
  "auto_archive_old_sessions": false,
  "auto_delete_old_sessions": false,
  "keep_recent_sessions": 3,
  "enabled": true,
  "schedule": {
    "kind": "period",
    "period": "workdays",
    "weekdays": [],
    "hour": 9,
    "minute": 0,
    "valid_from_ms": null,
    "valid_until_ms": null
  }
}
```

`workspace_hash` and `workspace_cwd` must either both be present and resolve to
the same registered workspace, or both be empty for a no-workspace LOOP.
`use_worktree` is a boolean and defaults to `false` for new definitions. LOOP
databases upgraded from the pre-option schema preserve existing definitions as
`true`; clients editing a definition should return the value they read.

`auto_archive_old_sessions` / `auto_delete_old_sessions` (booleans, default
`false`) and `keep_recent_sessions` (integer `1..100`, default `3`) control the
sessions earlier runs left behind. Both switches on is `400
CONFLICTING_SESSION_CLEANUP`; an out-of-range count is `400
INVALID_KEEP_RECENT_SESSIONS`. With either switch on, every launched run (due
or manual) afterwards walks this LOOP's run history newest first and keeps the
first `keep_recent_sessions` sessions that are still visible in the sidebar
(the new run's session included). Older visible sessions are archived, or
permanently deleted together with their sub-agent sessions. Pinned and already
archived sessions are excluded from the count. A visible running session counts
toward the limit. Pending work or a live external writer defers cleanup until
a later run. Deletion also checks the descendants. After a LOOP changes
workspace, each run's session is looked up in its original project, using that
project's pins. Sessions of other LOOPs and ordinary chats are never considered.
Databases from before these options read all three as their defaults.

Supported schedules are:

- `period`: `period` is `daily`, `workdays`, or `weekly`; weekly additionally
  uses `weekdays` (`0=Sunday ... 6=Saturday`), plus `hour` and `minute`.
- `interval`: `interval_value`, `interval_unit` (`minutes`, `hours`, `days`),
  and `anchor_ms`.
- `once`: `once_at_ms`.

`timezone_offset_minutes` is optional and defaults to the daemon's current
local offset. `valid_from_ms` / `valid_until_ms` are optional for every kind.
Raw Cron/dialect values are deliberately absent from public responses.

Run statuses are `scheduled`, `running`, `waiting_user`, `completed`, `failed`,
and `missed`. Missed occurrences are recorded and never queued or caught up.
Common reasons include `daemon_offline`, `workspace_busy`,
`daemon_interrupted`, `model_unavailable`, and `workspace_unavailable`. A due
LOOP is also recorded as `missed/workspace_busy` if another LOOP run for the
same workspace is active.

Creation, update, and re-enable return `409 SCHEDULE_CONFLICT` when two enabled
LOOPs in the same workspace have a future occurrence at the same minute. The
payload includes `conflict.loop_id`, `loop_name`, and `first_conflict_at_ms`.
No-workspace LOOPs are exempt.

Execution creates an ordinary visible session with `loop_execution` provenance.
When `use_worktree` is `false`, the task runs directly in the selected workspace.
When it is `true` and the workspace is a Git repository, the daemon creates an
isolated worktree; creation failure fails the run and never falls back to direct
writes. Non-Git workspaces run directly. LOOP never merges, rebases, pushes, or
removes a worktree; the final assistant response asks the user whether to merge
only when a worktree was actually created.

Permission behavior is per LOOP session: `default` preserves normal blocking
permission and AskUserQuestion prompts; `yolo` skips all tool permission prompts
but keeps AskUserQuestion interactive. LOOP Yolo may read outside the active work
root, but direct file writes and statically detectable shell writes outside that
root are rejected by the execution boundary without opening a permission prompt.

Sub-agents spawned from a LOOP session inherit the same execution boundary and
`loop_execution` provenance. Sub-agents spawned from any worktree session share
the parent's worktree (`worktree_session.inherited=true` in their metadata) and
use it as their write root; `EnterWorktree` / `ExitWorktree` refuse inside them.
Run history objects carry `workspace_touched`: paths that appeared as new or
changed in the main checkout, outside the run's worktree, between run start and
run end (detected with `git status --porcelain`). It is empty when no worktree
was created, when git could not be queried, or when nothing outside the worktree
changed. A non-empty list means some write bypassed the tool-level boundary (for
example through a shell script); the run still completes and the UI shows a
warning. `spawn_subagent` / `wait_subagent` tool results append the same
detection for one sub-agent as `metadata.workspace_touched`.

Error codes include `LOOP_UNAVAILABLE` (`501`), validation codes such as
`INVALID_MODEL` / `INVALID_WORKSPACE` (`400`), `SCHEDULE_CONFLICT` (`409`), and
SQLite subsystem failures (`503`).

---

## 15. Static Web App

The daemon also serves the built frontend:

- `GET /` serves the SPA entry.
- `GET /<path>` up to four path segments serves static files or falls back to
  the SPA entry.
- `/api/*` and `/ws/*` never fall back to the SPA; unmatched API/WS paths are
  `404`.
- Static responses send `Referrer-Policy: no-referrer`, so a bootstrap
  `?token=` URL is not propagated as a referrer.
- Static responses send an `ETag` and answer a matching `If-None-Match` with
  `304`; `/assets/*` (content-hashed Vite output) is `immutable`, everything
  else is `no-cache`. See "Embedded frontend encoding and caching" in section 2.

---

## 16. HTTP Status Summary

| Status | Meaning |
|---|---|
| 200 | OK |
| 201 | Created |
| 202 | Accepted/queued |
| 204 | No content |
| 400 | Bad JSON, missing field, validation failure |
| 401 | Missing or bad daemon token |
| 403 | PTY non-loopback access |
| 404 | Unknown route, workspace, session, attachment, skill, or job |
| 409 | Conflict, busy session, active writer, no update, model in use |
| 415 | File preview unsupported, binary, or too large |
| 429 | PTY session limit |
| 500 | Persistence, command, package, restore, or internal failure |
| 501 | Feature unavailable or not implemented |
| 502 | Upstream probe, upload, or auth exchange failure |
| 503 | Required daemon subsystem unavailable |

---

## Windows desktop taskbar badge bridge

The embedded Windows desktop exposes `window.aceDesktop_setTaskbarBadge(payload)`
as a native bridge, separate from the daemon HTTP/WS API. It resolves to JSON
with an `ok` boolean. Browser, Edge app, and non-Windows hosts do not expose it.

For a visible badge, pass an integer `count` greater than zero and `background`,
`foreground`, and `outline` colors in `#RRGGBB` format. Counts above 99 display
`99+`. Passing `{ "count": 0 }` restores the original ACECode window icons.
Malformed input leaves the current icons unchanged and returns `ok: false`.

The frontend counts distinct unread main tasks from full workspace status
snapshots and workspace-free session lists. Windows subscribes status for all
registered workspaces, including collapsed projects, while task lists remain
lazy-loaded. Read acknowledgements and authoritative list refreshes remove read,
archived, and deleted tasks; running and child tasks do not contribute. Badge
colors come from the resolved theme tokens and update with theme changes.

## Task suggestions and session continuation

The Web/Desktop chat shows durable, source-session-scoped suggestion cards.
The daemon exposes `suggest_task(title, description, prompt)` and
`dismiss_task_suggestion(suggestion_id)` to the agent. Proposing a side task
only stores an offer; accepting it is a user action through the HTTP API.
The prompt should identify an independent finding, its evidence, scope, and
verification steps. There are at most three pending side-task offers per source;
duplicate and dismissed offers retain their identity across reloads.

All routes use the existing daemon authentication and CORS rules. Mutations
are rejected while data-directory migration is active.

| Method | Path | Request / result |
|---|---|---|
| GET | `/api/sessions/:source/suggestions` | `{suggestions, source_busy, workspace_busy, worktree_available}` |
| POST | `/api/sessions/:source/suggestions/:id/accept` | Exactly `{"location":"worktree"}` or `{"location":"current_branch"}`; returns `{suggestion}` |
| POST | `/api/sessions/:source/suggestions/:id/dismiss` | Returns `{suggestion}`; never stops an already started target |

Suggestion records contain `id`, `source_session_id`, `kind` (`side_task` or
`context_handoff`), `title`, `description`, `status`, and, after acceptance,
`location` and `target_session_id`. A started record includes `target_session`
for navigation. The states are `pending`, `queued`, `starting`, `started`,
`failed`, and `dismissed`. Accept returns HTTP 202 while startup is pending or
has failed and HTTP 200 for an already started target. Read the returned status
and `error`; a 202 response is not proof that model execution has begun.
Invalid request envelopes return 400; conflicting state/location returns 409;
an unavailable source or a host without this feature returns 404.

Acceptance durably reserves the target ID before provisioning. Repeated clicks
and failed-start retries reuse that ID and the selected location. Closing the
card or browser does not drive startup. Queued offers can be cancelled; startup
already in progress cannot be dismissed. A completed start can be hidden or
opened from the source card.

`worktree` pins the source's committed Git HEAD at acceptance. It does not copy
dirty or untracked source files, and missing Git/commit state fails without
falling back to the current checkout. `current_branch` uses the source session's
actual working directory, including an existing worktree. It waits for the
source's safe execution boundary and known work in other sessions sharing that
directory. This startup coordination does not lock the directory against later
manual user actions or external processes.

The optional top-level configuration `task_suggestion_compact_threshold`
defaults to 3 successful compactions; 0 disables continuation suggestions.
Accepted values are integers from 0 through 1000. It applies to newly created
or restored session loops. Automatic and manual completed checkpoints count;
repair/fallback checkpoints and failed attempts do not. The count survives
resume; an explicitly forked context starts a new count. Dismissing a
continuation offer suppresses it for that source session.

A continuation uses `current_branch` and a fresh session with a structured
reference to the source session. At the safe boundary the daemon captures a
bounded handoff containing the latest compaction summary, subsequent updates,
current goal/todos, and the source's execution configuration. The new model
does not receive the whole old transcript. It can retrieve supporting history
through the session reference. Once the first input is accepted, the old
session's automatic goal continuation is paused; queued user messages are not
discarded. The original history remains available.

## 17. Process Exit Codes

| rc | Where | Meaning |
|---|---|---|
| 0 | any | Normal exit |
| 1 | various CLI | Generic failure |
| 2 | `worker.cpp` | preflight bind check rejected |
| 3 | `worker.cpp` / `server.cpp` | Crow `app.run()` failed, usually port in use |
| 4 | `worker.cpp` | failed to write runtime file |
| 5 | `cli.cpp foreground` | config validation failed |
| 6 | `cli.cpp start` | another daemon already running |
| 7 | `cli.cpp start` | detached spawn failed |
| 8 | `cli.cpp start` | detached worker did not write pid in time |
| 9 | `cli.cpp stop` | terminate pid did not complete |
| 10 | `cli.cpp` / `service_win.cpp` | unknown subcommand |
| 11 | `cli.cpp` / `service_win.cpp` | missing subcommand |
| 21 | `service_win.cpp` | `--service-main` invoked outside SCM |
| 22 | `service_win.cpp` | `StartServiceCtrlDispatcher` failed |
| 24 | `service_win.cpp` | access denied, admin required |
| 25-33 | `service_win.cpp` | other SCM API failures |
| 64 | `main.cpp` | `--service-main` on non-Windows |
| 65 | `main.cpp` | `service` subcommand on non-Windows |

---

## 18. WhatsApp Channels

The daemon also hosts the optional WhatsApp channel runtime. Its control plane
is a separate private loopback listener, not a route on this Web API. See
[WhatsApp channels](channels.md#whatsapp) for standalone CLI configuration and management. The descriptor
`channels/whatsapp/owner.json` in the ACECode data directory contains protocol
version 1, PID, port and an owner token. `POST /channels` requires the
`X-ACECode-Channels-Token` header even on loopback and rejects browser Origin
headers. JSON operations are `status`, `qr`, `on`, `off`, `reconnect`, `pending`,
`approve` (pairing code), `allow`/`revoke` (JID), `sessions`, `show`, `send`, `file`
and `stop` (session ID). Do not publish this descriptor or its QR output.

`ping` reports protocol version 1. Configuration is not a daemon API operation:
legacy `setup_*` requests are rejected. `acecode channels` saves configuration
without checking or contacting running instances. Saved logins require no bridge;
first-time pairing uses an isolated, temporary pairing-only bridge and closes it
before completion. It never starts a host, creates an agent session, acquires the
runtime account lock or asks the user to stop an existing owner.
The main TUI has no channel command or surface.

On daemon/Desktop startup, configuration is read once. Disabled instances do not
claim ownership. The first enabled runtime claims the account lock and connects.
Later enabled runtimes remain standby without launching bridges until ownership
is released; takeover refreshes history but retains startup settings. Settings
in `config.json` are independent of owner-written `state.json`, including writes
from older binaries. Explicit CLI runtime commands never start
a missing host. `acecode channels status` can read saved settings without one;
its `host_running` field distinguishes offline configuration from a live owner.

## 19. IM Channels (QQ, WeChat, Feishu, DingTalk, Telegram, Discord, LINE)

`openspec add-desktop-im-channels`. The daemon hosts native channels for QQ
(official bot, API v2 WebSocket gateway), WeChat (`weixin`, Tencent iLink bot,
long polling), Feishu / Lark (`feishu`, long-connection WebSocket), DingTalk
(`dingtalk`, Stream mode), Telegram (Bot API long polling), Discord (gateway
WebSocket) and LINE (`line`, Messaging API webhooks through a dedicated local
listener). Platform names in paths are exactly these keys. Each platform keeps
its data under `<data_dir>/channels/<platform>/`: `config.json`
(enabled flag, credentials, owner, approved contacts and groups; written only by
these endpoints, owner-only permissions) and `state.json` (session bindings,
sessions created per IM conversation, de-duplication receipts, Telegram update
offset). A corrupt file blocks that platform with state `error`; it is never
reset silently. WhatsApp (section 18) is unaffected and is not managed here.

All routes accept only direct local clients. Requests forwarded by the remote
Web proxy (source `127.0.0.2`, or a local non-loopback address on macOS) or from any other address return
`403 {"error":"LOCAL_ONLY"}` even with a valid token. Errors use
`{"error": CODE, "message": text}`: `400 CHANNEL_ERROR` or `BAD_REQUEST`
(messages are user-facing Chinese text without credentials),
`404 UNKNOWN_PLATFORM`, and `503 UNAVAILABLE` when the daemon has no channel host.
Mutating routes return the full `GET /api/channels` snapshot unless noted.

### `GET /api/channels`

```json
{
  "platforms": [
    {
      "platform": "telegram",
      "configured": true,
      "enabled": true,
      "state": "connected",
      "detail": "",
      "retry_stopped": false,
      "account": "123456",
      "display_name": "@ace_bot",
      "extra": {"username": "ace_bot", "privacy_mode": true, "link": "https://t.me/ace_bot"},
      "credential_hint": "****wxyz",
      "owner": "user:42",
      "contacts": [
        {"principal": "user:42", "kind": "user", "name": "Me", "owner": true, "approved_at_ms": 1790000000000}
      ],
      "pending": [
        {"id": "a1b2c3d4", "kind": "user", "name": "Alice", "principal": "user:7",
         "label": "Telegram 私聊", "expires_in_s": 512}
      ],
      "owner_window": false,
      "bindings": [
        {"key": "[\"telegram\",\"123456\",\"private\",\"42\"]", "label": "Telegram 私聊",
         "chat": "42", "sender": "42", "session_id": "sid", "no_workspace": true,
         "cwd": "...", "workspace_hash": "", "sent": 3, "failed": 0, "dropped": 0}
      ]
    }
  ],
  "binds": {"qq": {"platform": "qq", "phase": "idle"}, "weixin": {"platform": "weixin", "phase": "idle"}}
}
```

- `state`: `unconfigured`, `disabled`, `connecting`, `connected`, `retrying`,
  `failed` (`retry_stopped=true` after authentication failure, ban or another
  fatal close; turning the switch on again reconnects), `standby` (another
  ACECode process owns the account lock; `hosted_by_pid` names it, and this
  process takes over after that owner exits), `stopped`, or `error` (corrupt
  data files; `detail` gives the reason).
- `credentials_public` lists the saved credential fields: non-secret values as
  stored (AppID, Client ID, bot ids, Feishu `domain`, LINE `public_url`) and
  secrets masked to their last four characters. `credential_hint` is the mask of
  the platform's first secret field. QQ snapshots also carry `app_id`. QQ `extra`
  reports `held` (outputs waiting for the contact's next message after the
  passive and active reply windows were exhausted) and `markdown`.
- Telegram `extra.webhook=true` means `getUpdates` is blocked by a configured
  webhook; call `remove-webhook` after the user confirms.
- Principals are `user:<id>`, `group:<id>`, and `member:<group>:<member>`
  (only QQ scopes group member ids to the group). On WeChat only private chats
  exist; on Discord a guild channel (or thread) is the "group".
- The page shows only a one-line status. Failure reasons, privacy mode, held
  outputs, bindings and send counts are written to the daemon log under
  `[channels/<platform>]`.

### `POST /api/channels/:platform/enabled`

Body `{"enabled": true|false}`. The switch persists immediately and connects or
disconnects without a separate save. Enabling an unconfigured platform returns
`400`. Disabling keeps credentials, contacts and bindings.

### `PUT /api/channels/:platform/credentials`

Accepted fields per platform: QQ `app_id`, `app_secret`; Feishu `app_id`,
`app_secret`, `domain` (`feishu` or `lark`); DingTalk `client_id`,
`client_secret`, `robot_code`; Telegram `token`; Discord `token`; LINE
`channel_id`, `channel_secret`, `access_token` (optional long-lived token),
`public_url` (optional). WeChat has no manual credentials (scan only). Values
are trimmed strings of at most 512 bytes; unknown fields are rejected. An empty
or missing required field keeps the saved value (the page only knows the masked
hint); an empty optional field such as `public_url` clears it. The merged
credentials are validated online first (QQ access-token exchange, Feishu tenant
token, DingTalk access token, Telegram `getMe`, Discord `/users/@me` plus
`/applications/@me`, LINE token issue plus `/v2/bot/info`); failure returns
`400` and saves nothing. Validation may add derived non-secret fields (Discord
`bot_id` and `application_id`, LINE `bot_id`). On success the platform
reconnects if it is on. Switching to a different bot account drops bindings of
the old bot, and on platforms whose user ids are scoped per bot (QQ, WeChat,
Feishu, DingTalk, LINE) also clears the owner and approved contacts.

### `POST /api/channels/:platform/bind` and `DELETE /api/channels/:platform/bind`

Scan-to-configure for `qq` and `weixin` (other platforms return `404`). Starts
the flow and returns `{"platform":<p>,"phase":"starting"}`; a second start while
any scan is running returns `400`. Progress is pushed as `channels_bind` events
(below). `DELETE` cancels and returns the current bind state. Cancellation,
failure and timeout leave the existing configuration untouched. On success the
credentials are saved (QQ: AppID and the locally decrypted AppSecret; WeChat:
bot token, bot id and API base), the scanning user becomes owner when the
service reports them (WeChat always does; on QQ otherwise the first private
sender within 10 minutes does), and the platform turns on.

### `POST /api/channels/:platform/owner-link`

Requires a connected bot and no owner yet. Telegram returns
`{"link":"https://t.me/<bot>?start=<code>","expires_in_s":600}`; the first user
who opens the link and sends `/start <code>` becomes owner. Feishu, DingTalk,
Discord and LINE return `{"code":"123456","expires_in_s":600}`; the first user
who sends exactly these six digits in a private chat with the bot becomes owner,
and that message is not passed to a session. Codes are single-use; while a code
is outstanding, ten wrong six-digit guesses in private chats invalidate all
outstanding codes. QQ and WeChat return `400` (owners come from scanning).

### `POST /api/channels/telegram/remove-webhook`

Calls Telegram `deleteWebhook` and resumes polling. Only call it after the user
confirms; it replaces whatever other service registered the webhook.

### `POST /api/channels/:platform/requests/:id/approve|reject`

Decides a pending pairing request (requests expire after 10 minutes; an
expired or unknown id returns `400`). Approving a private user while the
platform has no owner makes that user the owner. Approval applies from the
contact's next message; the message that triggered the request is not replayed.

### `DELETE /api/channels/:platform/access/:principal`

The principal is percent-encoded in the path (for example
`member%3AG1%3AM1`). Revoking removes it from the approved list (clearing the
owner if it matches), drops its pending requests, and aborts the running turn
of every session bound to it.

### WebSocket events

Channel events are sent only to WebSocket connections opened by direct local
clients, using the envelope `{"type", "timestamp_ms", "payload"}` without a
session id:

| Type | Payload |
|---|---|
| `channels_state` | one platform snapshot, same shape as an item of `platforms` |
| `channels_bind` | `{"platform":"qq"/"weixin", "phase", "qr_url"?, "refreshes"?, "error"?, "account"?, "owner_bound"?}`; phase is `starting`, `waiting`, `completed`, `failed`, `cancelled` or `timed_out` |
| `channels_request` | `{"platform","id","kind","name","label"}` for a new pairing request; Desktop shows a system notification |

`qr_url` is the QR code content for the phone; it is never logged.

### Plugin platforms

`openspec add-channel-platform-plugins`. Platforms registered from
`<data_dir>/connectors/*/channel-platform.json` at daemon startup appear in
`GET /api/channels` after the built-in platforms and use the same routes; the
plugin protocol is in [channel-platform-plugin.md](channel-platform-plugin.md).
Their snapshot items add:

```json
{
  "platform": "example",
  "plugin": true,
  "label": "Example IM",
  "account_model": "self",
  "login_required": false,
  "configured": true,
  "group_watch": {"groups": ["g1"], "poll_interval_s": 120, "prefix": "", "prompt": ""},
  "bindings": [
    {"key": "...", "label": "Example IM 群聊", "chat": "g1", "sender": "me", "session_id": "sid",
     "delegate": true, "chat_name": "Project group"}
  ]
}
```

`configured` is always true (plugins have no credentials); `POST .../enabled`
starts or stops the plugin process. `group_watch` is present only when the
manifest declares `watched_groups`. Bindings with `delegate: true` are group
delegate sessions; they have no outbound projection. Session list rows bound to
any platform carry `channel_bound: {"platform", "label"}`.

### `PUT /api/channels/:platform/settings`

Body `{"groups": [..] | "one\nper line", "poll_interval_s": 30..86400,
"prefix": "<=32 chars, no line breaks", "prompt": "<=4000 chars"}`. At most 20
group IDs (letters, digits and `- _ . : @ + / = $`). Missing fields take their
defaults. Saving unbinds groups that were removed (their sessions lose
`channel_delegate`), refreshes the delegate prompt of the others and, when the
group list changed, sends `configure` to a running plugin. Platforms without
`watched_groups` return 400.

### `POST /api/channels/:platform/login`

Forwards `action("login")` to the plugin (up to 120 s). Built-in platforms
return 400; a stopped plugin returns 400 `通道未连接`.

## Session loading diagnostics

- `POST /api/diagnostics/session-open` accepts `session_id`, nonnegative
  `elapsed_ms`, `history_requests`, and `history_bytes`. Success is 204;
  malformed measurements return 400 `BAD_REQUEST`. Only these fields are
  logged. Web/Desktop reports once after first content paint and drops failures.
- `GET /api/diagnostics/sessions` returns `workspaces`, `sample_limit: 5`,
  and `cancelled`. Each registered visible workspace is identified by hash and
  display name, with `session_count`, `total_bytes`, `largest_bytes`,
  `errors`, and up to five `samples` from its largest canonical JSONL files.
  Samples contain session id, file/sample bytes, and per-category record count,
  bytes and fraction. Categories: user, assistant, tool, compact_checkpoint,
  file_checkpoint, turn_net_diff, other. No message content, session title,
  workspace path or referenced file path is returned.
- `POST /api/diagnostics/transcript-stall` records why a live page went out of
  sync. Body: required `kind` (`stall_probe` | `seq_reset` | `heartbeat_timeout`)
  and optional allowlisted fields: `session_id`, `reason`, `action`, `trigger`,
  `client_epoch`, `server_epoch`, `client_active_turn_id`, `server_active_turn_id`,
  `ws_state`, `visibility` (tokens of `[A-Za-z0-9-_:.]`, bounded length);
  `ms_since_event`, `client_last_seq`, `server_event_seq`, `ws_ms_since_message`,
  `heartbeat_timeouts`, `ms_since_forced_reconnect` (finite, non-negative);
  `server_busy`, `server_active`, `client_running` (booleans). Unknown fields are
  dropped; any invalid value rejects the whole report with 400. Success (204) logs
  one `[transcript-stall]` warning. Clients drop failures.
- HTTP diagnostics cooperatively stops on shutdown or after ten seconds and
  returns the partial report with `cancelled: true`.
  `acecode diagnose sessions` uses the same statistics and supports Ctrl+C
  cancellation (partial JSON, exit status 130).
- Synchronous load, resume, history, list, pins and status-snapshot operations log
  elapsed milliseconds and transcript/metadata/pin-state bytes, opened files and
  parsed records under `[session-load]`. Nested reads count toward their request.
  Operations over 500ms are warnings; others are debug records. File enumeration
  and OS metadata queries are not counted as content reads.

### Recovery event replay and duplicate subscriptions

The multiplex WebSocket `subscribe` payload accepts optional
`replay_from_start: true` together with `session_id` and `since`. This explicitly
replays all retained events after `since`, including event 1 when `since=0`.
Legacy subscriptions with `since=0` remain live-only. An existing subscription
is replaced only for this explicit replay request. The frontend requests it when
a disk session becomes live, and buffers events arriving during its first REST
load so that an older disk snapshot cannot discard recovery events.
Repeated `status_subscribe` for the same connection/workspace does not send a
second snapshot; clients resubscribe once after reconnect.

## 20. iOS Simulator (macOS)

Backs the `ios_simulator` / `ios_simulator_build` tools, Settings > Tools > iOS Simulator and the live simulator panel. On other platforms `status.supported` is `false` and the other routes report an unavailable Xcode. All routes use the normal daemon authentication. See [ios-simulator.md](ios-simulator.md).

| Route | Purpose |
|---|---|
| `GET /api/ios-simulator/status[?refresh=1]` | `{supported, enabled, config:{xcode_path, stream_fps, stream_scale, stream_quality}, helper:{installed, running, developer_dir, sandboxed, sandbox_note}, sessions:{<session_id>:<udid>}, xcode:{installs[], selected, selected_source, configured_path, configured_error, error, xcode_select_path, core_simulator_version}, device_consent:{<udid>:{name, granted_at}}}`. `refresh=1` reruns discovery including Spotlight. |
| `PUT /api/config/ios-simulator` | Body: any of `enabled`, `xcode_path` (`""` = automatic), `stream_fps` (5–60), `stream_scale` (0.25–1), `stream_quality` (0.3–0.95). Saves config.json (sparse), applies it and (un)registers the tools; returns the status. `400 {error:"XCODE_INVALID", message}` for an unusable Xcode path. |
| `POST /api/ios-simulator/xcode/inspect` | `{path}` → `{ok:true, install}` or `{ok:false, message}`. Accepts `…/Xcode.app` or `…/Xcode.app/Contents/Developer`. |
| `GET /api/ios-simulator/devices[?session=<id>]` | `{devices:[{udid, name, state, booted, runtime, runtime_version, platform, device_type, available, allowed, sessions[]}], error, session_device?}`. |
| `POST /api/ios-simulator/devices/<udid>/boot`, `/shutdown` | simctl boot (waits for boot completion) / shutdown; returns `{devices}`. |
| `POST /api/ios-simulator/devices/<udid>/consent` | `{allowed, name}` grants or revokes the agent's permission to control that simulator. |
| `GET /api/ios-simulator/devices/<udid>/screenshot` | Full-resolution PNG, turned to the interface orientation. |

`WS /ws/ios-simulator/<udid>?token=…[&frames=0]` (token rules as `/ws/sessions`). `frames=0` opens the socket for input and status only (no JPEG stream); the Desktop shell uses it while it draws the screen natively.

- Server → client text: `{type:"device", device:{udid, name, state, runtime, device_type, product_family, point_width, point_height, scale, rotation, hid_transport}}`, `{type:"ended", reason}`, `{type:"error", message}`.
- Server → client binary: `u32le json_length | {type:"frame", seq, width, height, rotation} | JPEG`. Frames are sent when the screen content changes, at most `stream_fps` per second, already turned to the interface orientation. All viewers of one device share one helper stream.
- Client → server text: `{type:"touch", phase:"down"|"move"|"up", x, y, edge?}` (device points in the frame's orientation), `{type:"button", name}` (`home`, `lock`, `side_button`, `siri`, `volume_up`, `volume_down`), `{type:"key", name}` (e.g. `return`, `cmd+a`), `{type:"type", text}` (keyboard), `{type:"text", text}` (paste; non-ASCII goes through the simulator pasteboard), `{type:"frames", enabled}` (start / stop this socket's JPEG stream; while stopped, touches are bounded by the larger screen side and the helper turns them to the current orientation). Panel input does not require device consent: consent gates the agent, not the user.

`helper.sandboxed` is true while the helper runs inside its Seatbelt profile; `sandbox_note` explains an unconfined helper (`ACECODE_IOS_SIM_SANDBOX=0`, no `sandbox-exec`, or the profile could not be applied).

Tool results of `ios_simulator` carry `metadata.ios_simulator = {action, udid, name, runtime, point_width, point_height, rotation}`; the web UI opens the panel on `attach` and closes it on `detach`.

Runtime-generated names use underscore separators. Existing hyphen-named data remains accessible; see [运行数据命名](runtime_file_naming.md).

## 主页意图提示

`GET /api/home/intent-prompts` 返回当前进程缓存；`POST /api/home/intent-prompts`
接收 `{ "force": false }`，到期时生成建议。`force: true` 用于 Ctrl+Y 调试刷新。
两者均遵循标准认证。响应包含 `suggestions`、`model`、`refreshing`、`error`、
`generated`、`generated_at_ms` 和 `next_refresh_at_ms`。并发 POST 合并，`refreshing: true`
时客户端可短暂读取状态直至完成，不重复 POST。常规刷新检查周期为 30 分钟。

`generated: true` 表示当前主会话活动已成功生成过建议（包含空建议）。仅当主会话
成功记入新的真实用户提问或助手可见回复时重置为 false；工具、思考、元数据修改、
草稿和历史读取/恢复/重写不重置。自动 POST 同时检查截止时间和该状态；已生成时
不扫描会话、不调用模型，仅返回缓存并将下次检查推迟 30 分钟。此状态与缓存共用
进程生命周期，多窗口共享；`force: true` 可主动绕过时间与活动限制。生成过程中
到达的新消息仍保持待生成，失败保留旧建议及旧成功版本。

建议包含 `category`（writing / exploration / execution / thinking）、`title`、
`description`、`prompt`、`source_session_id`、`workspace: {hash,cwd,name,noWorkspace}`。
来源是最近真实用户活动的最多 5 个非运行、非归档主会话；最多返回 4 条建议。
后端绑定工作区，不采信模型输出的路径。点击只预填草稿及选择工作区。

模型优先使用 `summary_generation.model_name`，未选择时采用最近成功生效的
会话模型（元数据 `model_activated_at_ms`；旧记录按最后用户消息兼容）。
摘要模型已选择但无效不静默回退。`MODEL_UNAVAILABLE`、`TIMEOUT`、
`GENERATION_FAILED`、`INVALID_RESPONSE` 均保留旧结果。推断不创建会话、不调用工具。