@robota-sdk/agent-cli 3.0.0-beta.79 → 3.0.0-beta.81

package/README.md

@@ -21,16 +21,28 @@ AI coding assistant CLI built on Robota SDK. Loads AGENTS.md/CLAUDE.md for proje
 
 ```typescript
 import { createAgentRuntime } from '@robota-sdk/agent-framework';
-import { createAnthropicProvider } from '@robota-sdk/agent-provider';
+import { createAnthropicProvider } from '@robota-sdk/agent-provider-anthropic';
 
 const runtime = createAgentRuntime({
   cwd: process.cwd(),
   provider: createAnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY }),
+  // projectAccess: hostWorkspaceDecision,
 });
 const session = runtime.createSession({ permissionMode: 'bypassPermissions' });
-const response = await session.submit('Explain this codebase');
+
+// submit() is event-driven and resolves to void — drive output via listeners
+session.on('text_delta', (delta) => process.stdout.write(delta));
+session.on('complete', (result) => console.log(result.response));
+
+await session.submit('Explain this codebase');
 ```
 
+A bare `cwd` is provenance, not project authority. Without a host-issued
+`TWorkspaceProjectAccess` decision the runtime is observably Restricted and does not load project
+context, settings, memory, sessions, or logs. Embedders establish that decision through the
+framework `WorkspaceTrustService`; a path, boolean, or generic filesystem cannot substitute for it.
+Trusted composition is rejected when `cwd` resolves outside that authority's frozen workspace root.
+
 ## Prerequisites
 
 Node.js **22 or higher** is required. The TUI renderer ([ink 7.x](https://github.com/vadimdemedes/ink)) requires Node.js 22+.
@@ -51,10 +63,11 @@ volta install node@22
 
 ## Demo
 
-<!-- TODO: Add demo GIF here -->
-<!-- Run `pnpm demo:record` to capture a demo recording — see docs/DEMO-SCRIPT.md for instructions -->
+![robota reading a project file and explaining its entry point in the terminal](./docs/demo.gif)
 
-![Demo](./docs/demo.gif)
+Recorded from the real CLI with `pnpm --filter @robota-sdk/agent-cli demo:record`. The tools run for
+real; the model turns are replayed from a recorded session log so the recording needs no API key —
+see [docs/DEMO-SCRIPT.md](./docs/DEMO-SCRIPT.md).
 
 ## Installation
 
@@ -96,11 +109,19 @@ export ANTHROPIC_API_KEY=sk-ant-...
 ## Development Setup (Monorepo)
 
 ```bash
-# Build dependencies and CLI
-pnpm build:deps
-pnpm --filter @robota-sdk/agent-cli build
+# Build all packages, including the CLI and its web monitor
+pnpm build
 ```
 
+`pnpm build` runs each package's own build in dependency order. The CLI build runs `tsdown` and then
+copies the web monitor (`agent-cli-web/dist`) into `dist/web`. To see the published tarball, run
+`pnpm --filter @robota-sdk/agent-cli pack`.
+
+Standalone Bun binaries are written to `dist-bun` (`pnpm --filter @robota-sdk/agent-cli build:bun`) and
+`dist-bun-headless` (`build:bun:headless`). Native dependencies make these builds exact-host: each
+supported Linux x64/arm64, macOS x64/arm64, or Windows x64 binary must be compiled on its matching host,
+and a mismatched target is refused.
+
 ## Usage (Monorepo)
 
 ```bash
@@ -133,17 +154,401 @@ robota --max-turns <n>              # Limit agentic turns per interaction
 robota --goal "<objective>"         # Pursue an autonomous goal headlessly until satisfied or a bound
 robota --goal-max-iterations <n>    # Per-goal turn budget (default 25)
 robota --output-format <fmt>        # text | json | stream-json (print mode)
+robota --effort <level>             # auto | none | minimal | low | medium | high | xhigh | max
 robota --system-prompt <text>       # Replace system prompt (print mode)
 robota --append-system-prompt <text> # Append to system prompt (print mode)
 robota --model claude-sonnet-4-6     # Override provider model for this session
 robota --allowed-tools "Bash,Read"  # Whitelist specific tools
 robota --denied-tools "Bash,Write"  # Blacklist specific tools (denied > allowed)
+robota --screen-reader              # Screen-reader mode: no chrome, no motion, numbered menus, role labels
+robota --no-screen-reader           # Force it off for this run, whatever the env or settings say
+# Pacing (ms): ROBOTA_SCREEN_READER_STARTUP_QUIET_MS=900  ROBOTA_SCREEN_READER_PREPARK_MS=50  (0 disables either)
+robota --serve                      # Run as a headless runtime host over a loopback WS sidecar (used by the desktop GUI)
+robota mcp serve                   # Serve one session to a local MCP client over stdio
+robota mcp serve --http-token-file /absolute/private/path/mcp-token --http-port 8765
+                                  # Serve Streamable HTTP on 127.0.0.1; the token file must not exist
+robota mcp serve --http-public-url https://agents.example.com/robota/mcp --oauth-issuer https://auth.example.com \
+  --oauth-scopes mcp:use --oauth-allowed-subjects alice@example.com
+                                  # Serve remote HTTP behind a proxy, admitting OAuth access tokens
+robota trust status                 # Inspect canonical workspace trust
+robota trust --yes                  # Grant trust for the current Git workspace
+robota trust revoke --yes           # Revoke the current workspace grant
+robota usage                        # Show the last 7 days of personal usage from local session history
+robota usage --period 30d           # Show complete buckets for the last 30 calendar days
+robota usage --timezone UTC --format json # Emit the versioned JSON projection
+robota usage export --endpoint http://127.0.0.1:4318 # Send stored-usage Gauges to a loopback OTLP collector
+robota usage export --signal traces --endpoint http://127.0.0.1:4318 # Send recorded prompt/provider/tool spans
+robota usage export --signal logs --endpoint http://127.0.0.1:4318 # Send content-free completion events
+robota --safe-mode                  # Every customization off, to rule one out
 robota --reset                      # Delete user settings and exit
 robota --check-update               # Check npm for a newer CLI version and exit
 robota --disable-update-check        # Skip interactive startup update check for this run
 robota --version                    # Show version
+robota --reduced-motion             # Suppress animation for this run (colour is unaffected)
+robota --no-reduced-motion          # Allow animation, overriding a persisted reducedMotion
+```
+
+### Personal Usage
+
+`robota usage` reads local user and trusted-project session stores without starting a provider or
+requiring network access. It reports sessions, started turns, tokens, cost confidence, model/provider/
+surface/source breakdowns, privacy-safe activity counts, and coverage diagnostics. The project copy
+wins when the same session ID exists in both stores. Stored prompts, responses, paths, and tool
+payloads are never printed.
+
+Use `--period 7d` (the default) or `--period 30d`, choose an IANA timezone with `--timezone`, and use
+`--format json` for the external `schemaVersion: 1` projection. An empty store produces an empty
+report; a supplied store set containing no readable records exits with an error instead of silently
+reporting zero usage.
+
+`robota usage export` is a separate, explicit, one-shot network action over OTLP/HTTP JSON to a
+loopback collector (`127.0.0.1` or `[::1]`) only. The default `metrics` signal sends a current
+**Gauge snapshot** of stored session/turn counts, tokens, estimated known USD cost, and unknown-cost
+counts to `/v1/metrics`. Repeated exports are snapshots, not new usage to add together. Select
+`--signal traces` to send recorded prompt-root, provider-call, and tool spans to `/v1/traces`, or
+`--signal logs` to send recorded content-free completion events to `/v1/logs`. Repeating a logs export
+can resend the same events; a collector may retain duplicates. These signals use stored records;
+they are not live tracing, and legacy records may lack span/event coverage. No signal
+exports prompt or tool bodies, credentials, or a remote destination. An unreadable stored session,
+collector rejection, or network error fails the command without reporting success.
+
+Live prompt telemetry is a separate, opt-in Node CLI feature (interactive, print, serve, and MCP serve). Set
+`ROBOTA_TELEMETRY_ENABLED=1`, `ROBOTA_TELEMETRY_TRACES=otlp`,
+`ROBOTA_TELEMETRY_OTLP_PROTOCOL=http/protobuf`, and
+`ROBOTA_TELEMETRY_OTLP_ENDPOINT=https://collector.example` to send content-free prompt/provider/tool
+spans to the base URL's `/v1/traces`. `ROBOTA_TELEMETRY_OTLP_TRACES_ENDPOINT` overrides the base with
+an exact traces URL. Select `ROBOTA_TELEMETRY_METRICS=otlp` independently to send per-invoked-call
+delta counts, complete-usage token totals and price-table-estimated USD cost, plus observed prompt and
+tool-completion counts, to `/v1/metrics`;
+`ROBOTA_TELEMETRY_OTLP_METRICS_ENDPOINT` overrides that destination. Missing usage or prices are
+counted separately, never treated as zero cost. A truncated provider-event batch reports omissions
+and does not claim a complete usage/cost total. Metric datapoints omit session, turn, provider and
+model labels by default; set `ROBOTA_TELEMETRY_METRIC_ATTRIBUTES` to a comma list drawn from
+`session`, `provider` and `model` (canonical lower case, no duplicates) to add them, and only when
+metrics export over `otlp` or `console` — the setting is refused otherwise, and startup is refused
+for any token that is not exactly one of the three. `session` adds `robota.session.id` (the same key
+the trace spans use) to every metric datapoint of the batch. `provider`/`model` add
+`robota.provider.id`/`robota.model.id` only to provider-derived metrics (calls, tokens, cost, and the
+unpriced/usage-unavailable counts), splitting them into one datapoint per distinct id (or pair); a
+call with no id gets its own datapoint without that attribute. In `--serve`/`robota mcp serve`, how
+many distinct session ids appear is set by the connecting clients, not by the CLI; provider and model
+values come from whatever the host's provider configuration reports, not from a fixed catalog. Select
+`ROBOTA_TELEMETRY_LOGS=otlp` independently for content-free
+prompt/provider/tool completion events, plus a tool's own permission decision (allowed, denied, or
+hook-blocked), at `/v1/logs`; `ROBOTA_TELEMETRY_OTLP_LOGS_ENDPOINT`
+overrides that destination. Tool spans and logs carry a validated opaque call ID when available, and an
+invoked provider-call span and its completion log carry the provider's own request ID the same way when
+the adapter attested one; metric datapoints never use either as a label, though a permission-decision
+count by decision value is still reported on `/v1/metrics`. A permission decision has no duration of
+its own and never produces a trace span. Only confirmed invocations produce provider-completion events;
+omitted child counts remain visible on the prompt event. Plain HTTP is allowed only for loopback; URL credentials and query parameters
+are rejected. Export is bounded, best-effort, and does not delay or fail a turn; delivery failures
+produce a content-free stderr warning. These switches do not enable content capture,
+additional event kinds, or replay of stored traces. Ambient `OTEL_*` values alone do not enable them.
+
+Prompt, response and tool content is a separate opt-in on top of `ROBOTA_TELEMETRY_LOGS=otlp`.
+`ROBOTA_TELEMETRY_LOG_USER_PROMPTS=1` sends what you typed (never the expanded model input, such as
+`@file` contents), and `ROBOTA_TELEMETRY_LOG_ASSISTANT_RESPONSES=1` sends the assistant's final answer
+for the turn. `ROBOTA_TELEMETRY_LOG_TOOL_ARGUMENTS=1` sends the arguments of the turn's tool calls,
+allowed or denied, and `ROBOTA_TELEMETRY_LOG_TOOL_OUTPUT=1` sends the output of its allowed calls
+(empty for a tool that crashed). Tool arguments carry whatever the model passed: a `Write` or `Edit`
+call's arguments are the file content it writes. Each setting accepts exactly `0` or `1`.
+`ROBOTA_TELEMETRY_LOG_CONTENT_MAX_BYTES` bounds each item (an integer from 256 to 16384, default 2048)
+and is refused unless one of them is `1`. Content is captured only in the interactive terminal and
+only for turns you type yourself, the same turns prompt history records: goal and loop wakeups, peer
+and external messages, remote co-drivers, subagents and background work are never captured, and
+tool content covers only the calls that turn made itself — never a subagent's, a forked skill's or
+background work's, even through a tool they share. A hook-blocked call, an unknown tool, or a call
+stopped before its tool ran sends nothing. Print (`-p`, `--goal`), `--serve` and
+`robota mcp serve` refuse to start with a content setting at `1` rather than ignore it. It goes only to OTLP log records (`robota.content.captured`, joined to the prompt's trace and
+root span, with `robota.content.kind`, `robota.content.truncated`, `robota.content.original_bytes` and,
+for an interrupted turn's response, `robota.content.partial`) — never to spans, metrics or console
+output, so a content setting with `ROBOTA_TELEMETRY_LOGS=console` is refused. A tool item is joined to
+the call's tool span when the trace kept one (else the root span) and adds `robota.tool.call_id`,
+`robota.tool.name` and `robota.tool.outcome` (`success`, `failure` or `denied`). Arguments are
+rendered with values under secret-looking keys (`password`, `apiKey`, `accessTokens`, …) masked
+whole, and binary or base64 payloads replaced by their size. It is sent to the logs
+destination with its headers but in its own requests and queue: a content failure never delays or
+drops the content-free logs, and is reported on stderr like any other delivery failure. One turn's
+content is bounded in item count and total size, with room kept for the prompt and response, and is
+sent as a few requests of bounded size; what does not fit is dropped and counted by kind in a
+content-free `robota.content.omitted` record, sent last. When a request fails, the rest of that turn's
+content and every queued turn are dropped, so that count is lost too. Queued content can hold about
+12 MB in the worst case. Before sending, the CLI masks known credential shapes (vendor API keys, AWS keys, private-key blocks,
+JWTs, GitHub, Stripe, npm and GitLab tokens, bearer tokens, URL and `-u user:pass` credentials,
+`*_KEY`/`*_TOKEN`/`*_SECRET`/`*_PASSWORD=` values, JSON values whose name looks secret, and
+`Authorization`, `Proxy-Authorization`, `Cookie`, `Set-Cookie` and `X-…-Token`/`-Key`/`-Secret`/`-Auth`
+header lines, including indented ones and the `> ` lines `curl -v` prints), the literal secrets it knows of (settings keys and
+`env` values, every resolved provider key including one switched to mid-session, and collector header
+values), your workspace path (`<workspace>`, also inside `file://` URLs) and home directory (`~`),
+control characters, and a partial token left at the size cut. This
+masking is best effort: anything it does not recognise as a secret is sent as written — file
+contents, command output and a response that repeats them included. If the secrets cannot be
+read, that request carries no content at all.
+
+Static collector headers (for example an `Authorization` token) use
+`ROBOTA_TELEMETRY_OTLP_HEADERS` for the generic endpoint and `ROBOTA_TELEMETRY_OTLP_TRACES_HEADERS`,
+`ROBOTA_TELEMETRY_OTLP_METRICS_HEADERS` or `ROBOTA_TELEMETRY_OTLP_LOGS_HEADERS` for one signal, in
+OpenTelemetry's `name=value,name2=value2` form with percent-encoded values
+(`Authorization=Bearer%20abc123`). Headers are scoped to their destination: a signal that uses
+`ROBOTA_TELEMETRY_OTLP_ENDPOINT` sends the generic headers merged with its own, its own winning on the
+same name, while a signal with its own `ROBOTA_TELEMETRY_OTLP_<SIGNAL>_ENDPOINT` sends only its own
+headers. Unlike OpenTelemetry, generic headers are never sent to a per-signal endpoint. Startup is
+refused for malformed entries, empty names or values, duplicate names, reserved transport,
+content-negotiation, proxy, `sec-` or trace-propagation names, control characters other than tab, non-ASCII characters,
+oversized settings, headers no OTLP signal would send, and a per-signal endpoint without its own
+headers while another signal sends the generic ones. Header helpers and refresh are not supported.
+Console output, logs and resource attributes never contain headers, and errors name only the setting
+and entry position. The CLI removes every `ROBOTA_TELEMETRY_*` setting from its environment at
+startup, so shells, hooks, subagents and other child processes do not inherit them; the only
+handover is the supervised runtime that `session start` or `session view` launches, which receives
+them in its spawn environment. While telemetry is enabled, any other `ROBOTA_TELEMETRY_*` setting
+(for example client certificates, a locked destination or other content capture) stops startup with an
+error that names the setting but never prints its value, rather than exporting without it.
+Each signal also accepts `console` instead of `otlp` to write a content-free JSON diagnostic to stderr;
+console needs neither an endpoint nor a protocol and never includes collector credentials. Signals
+remain independent, and the Robota enable switch is still required.
+All enabled signals use the same per-process `service.instance.id` and the CLI's version and
+presentation mode as resource attributes. Ambient `OTEL_SERVICE_NAME` and other `OTEL_*` values
+cannot replace these fields.
+
+Trace context propagation is a further opt-in. `ROBOTA_TELEMETRY_PROPAGATE_TO` is a comma list of
+exact origins (`https://api.anthropic.com,https://gateway.example.com:8443`) that may receive a
+W3C `traceparent` on provider requests: `00-<prompt trace id>-<provider-call span id>-01`, where the
+span ID is the one the exported `robota.provider_call` span carries. The same list covers MCP servers
+reached over Streamable HTTP: a tool call to a server whose URL has a listed origin carries
+`00-<prompt trace id>-<tool span id>-01`, where the span ID is the one the exported tool span
+carries. Only the `tools/call` request and its cancellation carry it — never initialization,
+listing, list refreshes, notifications or the server's event stream — and stdio MCP servers receive
+nothing. It needs
+`ROBOTA_TELEMETRY_ENABLED=1` and `ROBOTA_TELEMETRY_TRACES=otlp` or `console`, and is inert while
+telemetry is off. Each entry must be exactly its own origin: `https`, or `http` only on loopback, with no
+path, trailing slash, query, credentials, wildcard or spelled-out default port; a scheme, port or
+subdomain difference is a different origin and gets nothing. An internationalized host must be listed
+in its punycode (`xn--`) form, and an origin with a trailing dot never matches; both fail closed
+(refused at startup or sent nothing). Malformed, duplicate or too many entries
+stop startup with an error that names only the setting and entry position. `tracestate` and `baggage`
+are never sent, the collector's origin is never trusted implicitly, and collector headers are never
+reused for provider requests. The Anthropic and OpenAI (Responses and Chat Completions) adapters
+propagate to their client's effective base URL, as do the OpenAI-compatible DeepSeek, Qwen (both its
+Chat Completions and Responses surfaces), and Gemma adapters, and Gemini propagates to
+`https://generativelanguage.googleapis.com` only — not with `GOOGLE_GEMINI_BASE_URL`,
+`GOOGLE_VERTEX_BASE_URL` or Vertex mode. Nothing is sent through a provider executor. When
+propagation is configured but the round's provider cannot propagate — an executor, or a client
+whose base URL cannot be read — the CLI writes one stderr line per provider naming only that
+provider. Only a prompt's own provider calls carry it: subagents, workers and background
+tasks do not inherit it.
+
+Listing a vendor's origin lets that vendor link its own request logs to your trace ID. A redirect
+followed by the SDK carries the header to the redirect target. A provider call whose span was omitted or
+dropped from export still sent its `traceparent`, so the vendor's parent span may be missing from your
+trace; `robota.omitted.provider_count` on the prompt span shows when that happened. Ambient
+`TRACEPARENT` and `OTEL_*` values are never adopted.
+
+`ROBOTA_TELEMETRY_PROPAGATE_TO_SUBPROCESSES` hands the prompt's trace to child processes through the
+`TRACEPARENT` environment variable. It is a comma list drawn from exactly `shell` and `hooks`, each at
+most once; it needs the same `ROBOTA_TELEMETRY_ENABLED=1` and exported traces, is inert while
+telemetry is off, works with or without `ROBOTA_TELEMETRY_PROPAGATE_TO`, and a malformed entry stops
+startup naming only the setting and entry position. With `shell`, each foreground `Bash`/`Shell`
+command runs with `00-<prompt trace id>-<tool span id>-01`, where the span ID is the one that call's
+exported tool span carries. With `hooks`, command hooks fired during a prompt — `UserPromptSubmit`,
+`PreToolUse`, `PostToolUse`, `PermissionDecision`, the model-call hooks, `Stop`, `StopFailure` and
+the `PreCompact` and `PostCompact` of an automatic compaction — run with `00-<prompt trace id>-<prompt span id>-01`, so
+their spans sit beside the provider and tool spans; a hook fired outside a prompt (`SessionStart`,
+`SessionEnd`, both hooks of `/compact`, background tasks, subagent worktrees) gets nothing. The value
+is only ever in the child's environment, never in a hook's stdin JSON. A `TRACEPARENT` that a hook
+group's own `env` sets wins, and the child then sees its environment unchanged; otherwise the ambient
+`TRACESTATE` is removed, because it belonged to a different parent. The `!` shell passthrough,
+background, managed and scheduled shells, the monitor UI launcher, a sandboxed shell, stdio MCP
+servers, and HTTP, prompt and agent hooks never receive it. Robota never modifies its own process
+environment, so while the setting is off every child sees exactly the ambient `TRACEPARENT` and
+`TRACESTATE` it would have seen anyway.
+
+Upgrading: an origin already listed for a provider now also sends `traceparent` to an MCP HTTP server
+at that exact origin. Remove the origin, or move the MCP server to a different origin, if that server
+should not link its logs to your trace.
+
+### Doctor
+
+`robota doctor` (aliases: `checkup`, `diagnose`) diagnoses configuration and runtime readiness
+before any session exists, so a broken configuration cannot make the diagnostic unreachable. It reports
+every settings layer in precedence order with its state and cause, the merged keys with the layer that
+contributed each, provider resolution and endpoint reachability, workspace trust, storage, plugins,
+skills, hooks and MCP declarations — naming the exact file and cause, never a credential. Exit code
+`0` means no check failed (warnings allowed); `1` means at least one did.
+
+```bash
+robota doctor                                   # full report
+robota doctor --repair settings.user.robota     # one allowlisted repair, asks [y/N] first
+robota doctor --repair storage.user --yes       # no prompt (required in a non-interactive shell)
+```
+
+Repairs are limited to an empty user settings file (rewritten as `{}`) and a missing or too-open
+user storage directory; everything else is reported with the path to fix. `/doctor` runs the same
+report inside a session, and `/doctor repair <check-id>` asks before writing.
+
+### MCP Servers
+
+#### Serve Robota to an MCP host
+
+Install `@robota-sdk/agent-cli`, configure a provider with `robota --configure`, and grant the
+intended project with `robota trust --yes` before starting a headless server. Resolve the actual
+executable (`command -v robota`) and use its **absolute path** in the host configuration. For an
+MCP client that supports a child-process working directory, configure:
+
+```json
+{
+  "mcpServers": {
+    "robota": {
+      "command": "/absolute/path/to/robota",
+      "args": ["mcp", "serve"],
+      "cwd": "/absolute/path/to/trusted/project"
+    }
+  }
+}
+```
+
+The host must launch the process in the intended project directory. Robota uses that inherited
+directory for its normal project-root, access and trust decision; an MCP `roots/list` value or an
+environment variable does not silently change it. For Claude Code, whose stdio server environment
+includes `CLAUDE_PROJECT_DIR`, a project-scoped launch command can select that directory explicitly:
+
+```sh
+claude mcp add --scope project --transport stdio robota -- \
+  /bin/sh -c 'cd "$CLAUDE_PROJECT_DIR" && exec /absolute/path/to/robota mcp serve'
+```
+
+The host receives the canonical runtime tool catalog plus `robota_submit`. Model-invocable commands
+appear only through their canonical `robota_command_*` names. Tools run through the session's normal
+permission and hook policy; denied or approval-requiring calls return MCP tool errors, never an
+interactive prompt on the protocol stream. The peer is a local process started by the user and can
+request actions within that session's admitted workspace and permissions. This mode starts no web
+server, WebSocket sidecar or TUI. Stdout carries only MCP messages; startup notices and failures go
+to stderr. Closing the host's stdin or sending SIGINT/SIGTERM shuts down the carrier and session.
+If the host reports a connection failure, run `robota trust status` and `robota doctor` separately in
+the same project directory, then inspect the host's captured stderr for configuration errors.
+
+The same session can also use an admitted external MCP tool while it serves the host. Its connected
+client tools appear in the served catalog under canonical names such as `probe__echo`; they still
+run through the session's normal permission policy. The server carrier and outbound client close
+independently. An embedding host can supply its own `IMCPActivationApprovalStore` through
+`startCli({ mcpApprovalStore })` before startup, along with an explicitly approved
+`mcpHttpTransportDeps` egress policy when needed. Neither capability comes from MCP settings or the
+remote caller. The ordinary `robota` executable supplies neither automatically.
+
+#### Serve Robota to a remote MCP client
+
+`--http-token-file` is for clients on the same machine: it binds only `127.0.0.1`, and its bearer
+is never accepted beyond loopback. To serve a client elsewhere, run Robota as an OAuth resource
+server behind an HTTPS reverse proxy. An authorization server you already run issues the access
+tokens; Robota only verifies them.
+
+```sh
+robota mcp serve \
+  --http-public-url https://agents.example.com/robota/mcp \
+  --oauth-issuer https://auth.example.com \
+  --oauth-scopes mcp:use \
+  --oauth-allowed-subjects alice@example.com \
+  --http-host 127.0.0.1 --http-port 8765 \
+  --trusted-proxy 127.0.0.1
+```
+
+- `--http-public-url` is the `https` address clients use. It is also the token audience and the
+  `resource` Robota advertises. Robota serves MCP at its path (`/robota/mcp` above) and the RFC 9728
+  protected-resource metadata at `/.well-known/oauth-protected-resource` followed by that path. The
+  proxy must forward both paths unchanged (do not strip the prefix) and must preserve the client's
+  `Host` header. Robota checks `Host` and `Origin` against the public URL, not the address it binds.
+- `--oauth-issuer`, `--oauth-scopes` and `--oauth-allowed-subjects` are all required. A token must
+  be an RFC 9068 access token from that issuer, addressed to the public URL, carrying every listed
+  scope, and issued to a listed subject. Every admitted client drives the same session, so name only
+  the people you would hand this terminal to.
+- `--http-host` defaults to `127.0.0.1`, which suits a proxy on the same machine. Robota binds any
+  other address only when all the flags above are present.
+- A request without a valid token receives `401` with
+  `WWW-Authenticate: Bearer resource_metadata="…"`, and a token missing a scope receives `403`
+  with `insufficient_scope`. The body is always empty. MCP clients that support authorization
+  use that challenge to discover the authorization server.
+- Failed requests are counted per client address. After too many failures in a minute, that
+  address receives `429`; a valid token is never throttled. The client address is read from
+  `X-Forwarded-For` only when the connection comes from a `--trusted-proxy` address (repeatable).
+- Each refusal is logged on stderr as a reason and an address class (`loopback`, `private`,
+  `public`), never the token or the address itself.
+- The server is stateless: it issues no `Mcp-Session-Id`, so there are no sessions to enumerate or
+  hijack.
+
+The settings described below configure Robota as an MCP **client**.
+
+Declare remote MCP servers under an `mcpServers` key in any layered settings file (managed, user, or
+project `.robota`/`.claude` settings) — the same precedence order every other setting uses. Each
+entry names a `"type": "http"` transport and a `url`; `${VAR}`/`${VAR:-default}` references in `url`,
+`headers`, and `env` are resolved from the process environment. Every declared server is
+**deny-by-default**: a server must be explicitly approved with `/mcp approve <serverId>` before its
+tools are connected. Use `/mcp` (or `/mcp list`) to see every declared server's admission status,
+and `/mcp reject`/`/mcp revoke` to withdraw approval. Only approved servers already known at startup
+are connected. Approval is in-memory for the ordinary executable, so `/mcp approve` mid-session
+records a decision for that session but does not connect the server in the running session or
+persist it across a restart. An embedding host can preserve approval state across starts by
+supplying the same store; it remains responsible for when to reconnect approved definitions.
+
+A remote server that declares `"oauth": {}` (optionally with `clientId`, `callbackPort`,
+`authServerMetadataUrl` and `scopes`) needs its own sign-in before a session can use it. Sign-in is
+per server, naming the server — inside a session with `/mcp login <server>`, or from a terminal:
+
+```bash
+robota mcp login files                 # opens your browser; tokens kept owner-only in ~/.robota/mcp-credentials
+robota mcp login files --no-browser    # prints the URL; paste back the address your browser was sent to
+robota mcp login files --client-secret # a pre-registered confidential client: asks for the secret
+robota mcp logout files                # deletes the stored tokens, then revokes them where the server allows
+```
+
+Use `--no-browser` when the browser runs on another machine (for example over SSH). After you
+approve, the browser is sent to a `http://127.0.0.1:<port>/callback` address that may not load; copy
+that full address and paste it at the prompt (the input is not echoed). It is accepted only if it is
+this sign-in's redirect address and carries its `state`, and only within the same five minutes the
+browser flow allows.
+
+`robota mcp logout <server>` always deletes that server's local credential, even when the
+authorization server cannot be reached or refuses to revoke the tokens; it then says, per token,
+whether it was revoked, and otherwise why not (by a short reason) or that the server offers no
+revocation. `/mcp` shows each OAuth server's sign-in state — `signed in`, `token expired, will
+refresh`, `sign-in required` or `signed out` — never a token, and for a server that needs a sign-in
+it names `/mcp login <server>` and `robota mcp login <server>` (the server's name appears in them
+only when it is a plain name that is safe to paste into any shell). `/mcp logout <serverId>` signs
+out of that one server from inside a session and stops the session sending the token it holds.
+
+`/mcp login <server>` signs in without leaving the session: it first shows the authorization URL,
+where you can choose to open your browser, paste the redirect instead, or cancel. When no browser
+can be opened — or with `/mcp login <server> --no-browser` — it asks for the redirect address in the
+session's own prompt (the input is not shown). Once signed
+in, a server that could not connect at startup is admitted as usual (it must be approved) and
+connected, and its tools are available from your next message; a server whose sign-in lapsed
+mid-session works again. A failed or cancelled sign-in changes nothing. A client secret is never
+typed into a session: for a pre-registered client that needs one, run
+`robota mcp login <server> --client-secret` in a terminal.
+
+### MCP Background Handoff
+
+A slow MCP tool call can be handed to a background task instead of blocking the turn. Configure it
+under an `mcp` key (beside `mcpServers`, in the same layered settings files):
+
+```json
+{
+  "mcp": {
+    "autoBackgroundMs": 120000,
+    "callTimeoutMs": 600000
+  }
+}
 ```
 
+- `autoBackgroundMs` (default 120000 ms): a tool call still running at this point is handed to a
+  `tool-invocation` background task; `/tasks` shows it like any other background task. `0` disables
+  the handoff.
+- `callTimeoutMs` (default 600000 ms): the tool call's own budget, enforced by the MCP client in
+  every mode — including print. `autoBackgroundMs` must be less than `callTimeoutMs`, or the handoff
+  is disabled with a warning.
+- The handoff applies to the interactive TUI and `robota --serve`. In print mode (`-p`) a slow MCP call always runs to completion in the
+  foreground, bounded by `callTimeoutMs`; a positive `autoBackgroundMs` is reported as ignored there.
+
 ### CLI Updates
 
 Robota can check npm for a newer `@robota-sdk/agent-cli` version:
@@ -214,18 +619,19 @@ Non-interactive/headless mode never prompts. Configure a provider ahead of time
 
 ## Built-in Tools
 
-The AI agent can invoke 8 local tools:
+The AI agent can invoke 9 distinct local tools (the runtime registers 10 tool names — `Bash` is the model-familiar alias of `Shell`):
 
-| Tool        | Description                                    | Primary Argument |
-| ----------- | ---------------------------------------------- | ---------------- |
-| `Bash`      | Execute shell commands                         | `command`        |
-| `Read`      | Read file contents with line numbers           | `filePath`       |
-| `Write`     | Write content to a file                        | `filePath`       |
-| `Edit`      | Replace a string in a file                     | `filePath`       |
-| `Glob`      | Find files matching a pattern                  | `pattern`        |
-| `Grep`      | Search file contents with regex                | `pattern`        |
-| `WebFetch`  | Fetch URL content as text                      | `url`            |
-| `WebSearch` | Search the internet (requires `BRAVE_API_KEY`) | `query`          |
+| Tool              | Description                                    | Primary Argument |
+| ----------------- | ---------------------------------------------- | ---------------- |
+| `Bash`            | Execute shell commands                         | `command`        |
+| `Read`            | Read file contents with line numbers           | `filePath`       |
+| `Write`           | Write content to a file                        | `filePath`       |
+| `Edit`            | Replace a string in a file                     | `filePath`       |
+| `Glob`            | Find files matching a pattern                  | `pattern`        |
+| `Grep`            | Search file contents with regex                | `pattern`        |
+| `WebFetch`        | Fetch URL content as text                      | `url`            |
+| `WebSearch`       | Search the internet (requires `BRAVE_API_KEY`) | `query`          |
+| `AskUserQuestion` | Ask the user structured questions mid-task     | `questions`      |
 
 > **WebSearch** requires a `BRAVE_API_KEY` environment variable. Without it, the tool returns a setup message instead of results. Get a free key at [brave.com/search/api](https://brave.com/search/api/) (2,000 queries/month free tier).
 
@@ -240,6 +646,95 @@ The AI agent can invoke 8 local tools:
 - Background subagents are real runtime jobs with transcripts and resumable task snapshots.
 - Explicit multi-agent requests use the `/agent` command module batch path through the SDK runtime.
 
+### Recap when you come back
+
+The TUI notices when you leave the terminal — by focus, where the terminal reports it (iTerm2,
+Kitty, WezTerm, Alacritty, Ghostty, VS Code, Windows Terminal, tmux with `focus-events on`), or
+after five minutes without a keystroke elsewhere — and on your return prints one line for the
+interval, or nothing if nothing happened:
+
+```
+While away 12m: 2 turns finished (1 wake) · 1 needs input · 1 failed
+```
+
+Every background row carries its state word beside the glyph (`working`, `needs-input`,
+`completed`, `failed`, `stopped`), the one-line headline, and for a sleeping `/schedule` a live
+`in 59s` countdown. `ROBOTA_FOCUS_EVENTS=0` turns focus reporting off (idle detection remains);
+`=1` requests it even where the TUI would not.
+
+### Prompt history
+
+`Ctrl+R` searches every prompt you have typed — in this session, in this project, or anywhere —
+the way a shell's reverse search does. Type to narrow the list (newest first, matches highlighted),
+`Ctrl+S` cycles the scope `all → session → project`, `Enter` or `Tab` puts the highlighted prompt back
+in the input, `Ctrl+E` runs it, `Esc` returns you to exactly the draft you had. Every key is
+rebindable in `~/.robota/keybindings.json` (context `history-search`, and `chat-input.history-search`
+for the opener).
+
+What is written, where, and how to turn it off: the interactive TUI appends each prompt you submit
+to `~/.robota/history.jsonl` (one JSON line — timestamp, session id, project root, text; readable by
+you only). Prompts are already kept verbatim in the session record; this file is a searchable index
+of them across sessions. `--serve` and print mode never write it. Set `"promptHistory": false` in
+`~/.robota/settings.json` to turn it off, or `ROBOTA_PROMPT_HISTORY=0` for one run (`=1` overrides
+the setting). Delete the file to forget everything.
+
+Searching the conversation itself needs no viewer: the TUI never switches to the alternate screen,
+so every message of a resumed session is in your terminal's own scrollback and search.
+
+### Themes
+
+`/theme` opens a picker: moving the highlight previews that theme in the live region — the input
+frame, the status bar and the overlay itself — so you judge a colour scheme against the thing it
+applies to rather than a swatch. `Enter` applies it, `Esc` leaves the previous one in place. The
+transcript above keeps the colours it was written in, because the terminal owns those lines once
+they are printed.
+
+Four built-ins ship: `dark` (what Robota has always looked like), `light`, and `dark-daltonized` /
+`light-daltonized`, which avoid the red/green distinction entirely — blue for "good", orange for
+"bad" — for the roughly 1 in 12 men with a colour-vision deficiency. The daltonized pair is checked
+mechanically: a test simulates protanopia and deuteranopia over the pairs whose difference in colour
+carries meaning and fails if any of them come too close.
+
+Without the picker: `/theme list` shows what is installed and what is active, `/theme <id>` switches,
+`/theme syntax on|off` toggles code-block highlighting, and `/theme motion on|off` toggles animation.
+All three persist to `~/.robota/settings.json` as the flat keys `theme`, `syntaxHighlighting` and
+`reducedMotion`.
+
+#### Writing your own
+
+Drop a `.json` file in `~/.robota/themes/` and it appears in the list as `custom:<file-name>`. The
+name becomes part of an id you type, so it may use up to 24 characters from letters, digits, `.`,
+`-` and `_` — a file named anything else is skipped with a line saying so, rather than listed as a theme no command can apply:
+
+```json
+{
+  "name": "Mine",
+  "base": "light",
+  "overrides": { "colors": { "text": { "accent": "#56b4e9" } } }
+}
+```
+
+`base` is any built-in and `overrides` is a sparse map over the same token paths the built-ins use —
+`colors`, `markdown`, `syntax` and `motion` — so you change the colours you care about and inherit
+the rest. Values use Ink's colour grammar: a chalk colour name, `#rgb`, `#rrggbb`, `ansi256(n)` or
+`rgb(r,g,b)`. A raw escape sequence is not in that grammar, so it cannot enter through a theme.
+
+A plugin ships themes the same way, in its own `themes/` directory; they are listed as
+`custom:<plugin>:<file-name>`, and the plugin's own name has to satisfy the same rule for the same
+reason. Both namespaces start with `custom:`, so a file can never take a
+built-in's name whatever it is called.
+
+A file is applied whole or not at all. An unknown token, a value that is not a colour, or JSON that
+does not parse skips the WHOLE file with the path that refused it — printed once at startup as
+`Skipped theme "mine.json": $.overrides.colors.text.accent: "nope" is not a colour …`, and shown in
+the picker as a row that carries the same reason and cannot be chosen. Its neighbours still load.
+
+Motion can also be decided per run: `--reduced-motion` / `--no-reduced-motion` beat
+`ROBOTA_REDUCED_MOTION=1|0`, which beats the setting. A run that pins it says so — `/theme motion on`
+reports that it saved the setting and that this run keeps what pinned it, rather than appearing to
+do nothing. `NO_COLOR`, `FORCE_COLOR=0`, a non-TTY stdout and screen-reader mode still win over
+every theme: no colour and no animation, exactly as before.
+
 ## Permission System
 
 Every tool call passes through a three-step permission gate:
@@ -262,7 +757,7 @@ Every tool call passes through a three-step permission gate:
 Use the `/permissions` slash command:
 
 ```
-> /permissions                    # Show current mode and session-approved tools
+> /permissions                    # Show mode, rules by settings file, approvals, recent denials
 > /permissions plan               # Switch to plan (read-only)
 > /permissions bypassPermissions  # Skip all prompts
 ```
@@ -293,6 +788,7 @@ Pattern syntax: `ToolName` matches any invocation; `ToolName(pattern)` matches o
 | Key        | Action                                                      |
 | ---------- | ----------------------------------------------------------- |
 | Enter      | Submit input                                                |
+| Ctrl+R     | Search prompt history (see "Prompt history")                |
 | ESC        | Abort current execution (graceful — saves partial response) |
 | Ctrl+C     | Exit process immediately                                    |
 | Up/Down    | Navigate visual lines in wrapped multi-line input           |
@@ -337,6 +833,20 @@ The CLI supports continuing, resuming, forking, and naming sessions.
 | `/resume`        | List recent sessions and resume one |
 | `/rename <name>` | Rename the current session          |
 
+### Moving to another directory (`/cd`)
+
+`/cd <directory>` continues the conversation in another directory. Robota starts again there, as if
+launched in that directory: its settings, trust decision, tools, skills and `AGENTS.md` apply, and the
+conversation resumes. The system prompt is kept as it was, so a provider's prompt cache survives. One
+message tells the model about the new directory and its project instructions.
+
+- `/cd` is refused while a turn is running or a background task is still running, and in a session
+  started with `--no-session-persistence`, which has no saved conversation to carry.
+- A restricted (untrusted) session stays restricted after a move. A trusted session takes the target
+  directory's own trust decision.
+- A `Cd(...)` deny rule keeps sessions out of a directory, for example
+  `"deny": ["Cd(/secrets/**)"]`.
+
 ### Session Name Display
 
 When a session has a name, it appears in three places:
@@ -345,31 +855,71 @@ When a session has a name, it appears in three places:
 - **Terminal title** — updated via ANSI escape sequences
 - **StatusBar** — displayed alongside activity, model, and context usage
 
+## Deep Links
+
+A `robota://open` link starts a session in a directory you have already trusted, with a prompt
+already in the composer and **not** submitted — you read it and press Enter, or clear it.
+
+```bash
+robota open 'robota://open?v=1&prompt=Summarize%20the%20README&cwd=/absolute/path/to/repo'
+```
+
+| Key      | Meaning                                                                                                              |
+| -------- | -------------------------------------------------------------------------------------------------------------------- |
+| `v`      | Contract version. Required, and must be `1`.                                                                         |
+| `prompt` | The text to prefill. At most 5,000 characters; it may not begin with `/`.                                            |
+| `cwd`    | Absolute path of the directory to open.                                                                              |
+| `repo`   | `owner/name` of an already-trusted local clone, when you do not want to name a path. `cwd` wins if both are present. |
+
+Everything else is refused, and a refusal discards the whole link, says which rule it broke, writes
+to stderr and exits non-zero without starting a session: an unknown key (so a link cannot carry
+`provider=`, `permission-mode=`, `plugin=` or any other configuration), a duplicate key, a missing
+or different `v`, a link over 8,192 characters, a prompt over 5,000, a prompt beginning with `/`
+(one Enter would otherwise run it as a command), a relative, UNC or `..`-bearing path, and a second
+link appended after the first (the argv shape a desktop handler can be made to produce). Your own
+flags still apply after the link; a trailing token that is neither a link nor a flag is currently
+discarded rather than refused — a CLI-wide gap tracked separately, not specific to links.
+
+The target must already be trusted — `robota trust --yes` in that directory — for `cwd=` exactly as
+for `repo=`. A link opens only what you have already approved; it never clones, never fetches, and
+never reads a repository you have not trusted. While the composer still holds exactly what the link
+supplied, the line `Prompt from an external link` sits below the input, and above 1,000 characters it
+adds the character count and asks you to read the whole thing before sending. Edit that text and the
+line goes: what is in the composer is then yours, and the label would be claiming otherwise.
+
+**Known limitations.** No URL scheme is registered with the operating system yet, so a browser
+cannot hand the link over: pass it to `robota open` yourself, or point your own handler at that
+command. Registering the scheme on macOS, Linux and Windows, and the HTTPS launcher that works
+around chat clients stripping custom schemes, are tracked separately.
+
 ## Slash Commands
 
 Typing `/` in the TUI opens an autocomplete popup. Arrow keys navigate, Tab inserts without executing, Enter executes. Subcommands (e.g., `/provider list`) show a nested submenu.
 
 ### Session & Context
 
-| Command                   | Description                                                            |
-| ------------------------- | ---------------------------------------------------------------------- |
-| `/clear`                  | Clear conversation history                                             |
-| `/compact [instructions]` | Compress context window                                                |
-| `/context`                | Context window details, reference inventory, and auto-compact controls |
-| `/cost`                   | Show session token usage and cost                                      |
-| `/resume`                 | List recent sessions and resume one                                    |
-| `/rename <name>`          | Rename the current session                                             |
-| `/rewind`                 | List, inspect, restore, or rollback edit checkpoints                   |
+| Command                   | Description                                                                                      |
+| ------------------------- | ------------------------------------------------------------------------------------------------ |
+| `/clear`                  | Clear conversation history                                                                       |
+| `/compact [instructions]` | Compress context window                                                                          |
+| `/context`                | Context window details, reference inventory, and auto-compact controls                           |
+| `/cost`                   | Show session token usage and cost                                                                |
+| `/effort [level]`         | Show or change model effort (`auto`, `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`) |
+| `/resume`                 | List recent sessions and resume one                                                              |
+| `/rename <name>`          | Rename the current session                                                                       |
+| `/cd <directory>`         | Move this conversation to another directory (see below)                                          |
+| `/rewind`                 | List, inspect, restore, or rollback edit checkpoints                                             |
 
 ### Providers & Settings
 
-| Command                  | Description                                                          |
+| Command | Description |
 | ------------------------ | -------------------------------------------------------------------- | ------- | -------------------------------------------------- |
 | `/provider [subcommand]` | Manage provider profiles: `list`, `switch`, `add`, `test`, `current` |
-| `/mode [mode]`           | Show or switch permission mode                                       |
-| `/permissions [mode]`    | Show permission rules or change permission mode                      |
-| `/settings`              | Open transport settings (enable/disable transports)                  |
-| `/language [lang]`       | Set response language (ko, en, ja, zh), saves and restarts           |
+| `/mode [mode]` | Show or switch permission mode |
+| `/permissions [mode]` | Show permission rules or change permission mode |
+| `/sandbox [mode]` | Show or change how shell commands are confined |
+| `/settings` | Open transport settings (enable/disable transports) |
+| `/language [lang]` | Set response language (ko, en, ja, zh), saves and restarts |
 | `/statusline [on         | off                                                                  | reset]` | Configure status-line fields (model, context, git) |
 
 ### Tools & Memory
@@ -383,6 +933,30 @@ Typing `/` in the TUI opens an autocomplete popup. Arrow keys navigate, Tab inse
 | `/skills [name]`       | List registered skills or activate one by name                       |
 | `/plugin [subcommand]` | Plugin management                                                    |
 
+### Git
+
+| Command                                                     | Description                                                                                          |
+| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `/git status`                                               | Branch plus the staged, unstaged and untracked paths                                                 |
+| `/git diff [--staged \| <rev> \| <a>..<b>] [-- <path> ...]` | Unstaged diff, staged diff, or a diff against one or two revisions (each revision is verified first) |
+| `/git commit [<subject>]`                                   | Commit the staged changes after a confirmation listing the message and the staged files              |
+
+`/git commit` operates on the staged set only — no `-a`, no paths. The subject must follow the
+Conventional Commits form `<type>[(scope)][!]: <description>`; the type list, the 72-character limit
+and a trailing period are warnings, not refusals. With nothing staged it says so, with the unstaged and
+untracked counts. Headless (`-p`) runs cancel the commit because no confirmation can be asked for.
+Other git flags are not accepted — `/shell git ...` remains the way to run arbitrary git.
+
+### Sessions on this host
+
+| Command                              | Description                               |
+| ------------------------------------ | ----------------------------------------- |
+| `/peers`                             | List the other live sessions on this host |
+| `/peers send <session-id> <message>` | Send a message to one of them             |
+
+See [Talking to another session](#talking-to-another-session) for the flow and what happens when the
+other session is busy.
+
 ### Utility
 
 | Command  | Description                                        |
@@ -391,7 +965,97 @@ Typing `/` in the TUI opens an autocomplete popup. Arrow keys navigate, Tab inse
 | `/reset` | Delete user settings and return to first-run state |
 | `/exit`  | Exit CLI                                           |
 
-Skill commands discovered from `.agents/skills/` and `.claude/commands/` appear alongside built-in commands.
+Skill commands from the CLI's ordered `.robota/skills/`, `.claude/skills/`, `.claude/commands/`, and
+`.agents/skills/` roots appear alongside built-in commands.
+
+## Talking to another session
+
+Two `robota` sessions running on the same host, as the same user, can see and address each other.
+Nothing crosses a machine boundary and nothing is configured — a session becomes discoverable by
+being alive and stops being discoverable when it exits.
+
+### Seeing who is there
+
+```
+/peers
+```
+
+With nothing else running:
+
+```
+No other live session is announced. Start a second session on this host, as this user,
+and it appears here.
+```
+
+That is a sentence rather than an empty list on purpose: "no one is there" and "discovery is not
+working" are different answers, and an empty list cannot tell you which one you got.
+
+With a second session up:
+
+```
+Live sessions:
+  b8319b98-bb7b-486c-a499-cf1585b39e61  (this session)
+  97ffafe3-f770-4877-90a4-bd86df6be010
+
+Send to one: /peers send <session-id> <message>
+```
+
+### Sending
+
+```
+/peers send 97ffafe3-f770-4877-90a4-bd86df6be010 rerun the failing suite
+```
+
+The message becomes a **turn** in the other session — the agent there answers it as if the operator
+had typed it. The sender is told which of four things happened, as a sentence:
+
+| Outcome                                                                  | What it means                                                                     |
+| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
+| `Delivered to <id>.`                                                     | It arrived and started.                                                           |
+| `<id> has the message; it is waiting behind work already running there.` | It arrived and is queued. Deliberately **not** reported as delivered.             |
+| `<id> had already seen that message.`                                    | A retry that the receiver recognised; it does not run twice.                      |
+| `Not delivered to <id>. <reason>`                                        | Nothing ran. The reason names the target, e.g. that no such session is announced. |
+
+The second row is the one worth knowing. Reporting a queued message as delivered would hide a wait
+the operator can otherwise see and act on.
+
+### What the receiving operator sees
+
+The message is attributed to the sender, not to whoever is sitting at the receiving terminal:
+
+```
+peer:b8319b98-bb7b-486c-a499-cf1585b39e61:
+  rerun the failing suite
+Robota:
+  …
+```
+
+Your own turns still read `You:`. The name in the label is **derived from the peer's session id** —
+it is not a display name the sender chose, because a name the transcript's reader trusts must not be
+picked by the party being named. It is display attribution only: nothing anywhere uses it to decide
+what a turn is allowed to do.
+
+### When the other session is busy
+
+A message arriving mid-turn joins that session's existing pending queue rather than interrupting or
+opening a second one. Three things follow from how that queue works:
+
+- **Consecutive messages from the same sender coalesce**, last one wins. That is right for a person
+  retyping and wrong for a peer saying two separate things. The replaced one is not swallowed: it
+  settles as refused with the reason `coalesced`, so the sender learns it never ran rather than
+  assuming both did. Tracked as `PEER-003`.
+- **Messages from different senders do not coalesce** — they queue in arrival order.
+- **The queue holds 32.** Beyond that a message settles as refused with the reason `dropped`.
+- **A cleared queue** — abort, cancel, or shutdown — settles the waiting entries with `cancelled`.
+
+In every case the submission that never became a turn says so. A message that arrived and was then
+displaced is a different thing from one that ran, and the sender is told which it got.
+
+### Limits
+
+- Same host, same user. There is no network path here.
+- A session that exits removes its own entry; a crashed one is reaped by the next session that looks.
+- Session ids are what you address. There are no aliases.
 
 ## Plugin Management
 
@@ -420,6 +1084,29 @@ Settings are merged in this order, from lowest to highest priority:
 5. `.claude/settings.json` (project, Claude Code compatible)
 6. `.claude/settings.local.json` (local, gitignored, Claude Code compatible)
 
+The two user layers are always host-owned. The four project layers participate only when the CLI host
+supplies trusted project access; Restricted composition does not probe them. Project writes require a
+separately approved settings writer for the same authority.
+
+### Workspace trust
+
+Robota admits project-controlled settings and executable contributions only after a host-owned grant
+for the canonical Git workspace identity. In a new or revoked workspace, interactive startup remains
+usable with project settings, hooks, plugins, skills, and provider overrides disabled. Headless startup
+fails closed until trust is granted:
+
+```bash
+robota trust status
+robota trust --yes
+robota trust revoke --yes
+```
+
+The grant survives process restart and is invalidated by repository replacement, revocation, or a
+trust-store error. Symlink aliases resolve to the canonical workspace; a different repository at the
+same textual path does not inherit the grant. `robota doctor` reports trust and endpoint provenance
+without printing credentials. If a lower-trust settings layer changes a provider endpoint without
+providing its own key, Robota removes the inherited key and reports `provider endpoint quarantined`.
+
 ```json
 {
   "defaultMode": "default",
@@ -480,17 +1167,17 @@ persisted default. The legacy single-provider shape remains supported:
 
 ## Context Discovery
 
-The CLI automatically discovers and loads:
+With trusted project access, the CLI discovers and loads:
 
-- **AGENTS.md** — walking up from cwd to filesystem root
-- **CLAUDE.md** — same walk-up discovery
+- **AGENTS.md** — walking only within the authenticated worktree root
+- **CLAUDE.md** — the same root-bounded discovery
 - **Project metadata** — from `package.json`, `tsconfig.json`
 
 All context is assembled into the system prompt.
 
 Ordinary prompts may also reference workspace-local files with path-like `@file` tokens, for
 example `@AGENTS.md` or `@docs/SPEC.md`. The CLI passes those prompts through unchanged; the SDK
-resolves bounded file content under the active `cwd`, sends the enriched prompt to the model, and
+resolves bounded file content through the accepted project reader, sends the enriched prompt to the model, and
 records a structured file-reference event in the session history.
 
 ## Memory Management
@@ -501,9 +1188,11 @@ records a structured file-reference event in the session history.
 
 ## Session Logging
 
-Session logs are written to `.robota/logs/{sessionId}.jsonl` in JSONL format by default, capturing structured events for diagnostics and replay. Background task lifecycle/progress events are logged there as they happen. Child-process subagents also write append-only transcripts to `.robota/logs/{sessionId}/subagents/{agentId}.jsonl`, including streaming text deltas while the local provider request is still running.
-
-Resumable session JSON is written to `.robota/sessions/{sessionId}.json` for the current project and includes messages, UI history, the exact system prompt, registered tool schemas, and background task snapshots. High-frequency streaming chunks stay in JSONL transcript files; the session JSON stores task state and transcript paths.
+Trusted composition writes project session logs and resumable records through authority-backed
+`session-logs` and `sessions` state facets. Restricted composition opens no project log path and uses
+the user session store instead. Session records include messages, UI history, the exact system prompt,
+registered tool schemas, and background task snapshots; high-frequency streaming chunks remain in
+the separately injected JSONL sink.
 
 ## Architecture
 
@@ -535,19 +1224,15 @@ bin.ts → cli.ts (arg parsing)
 
 ## Dependencies
 
-| Package                                      | Purpose                                    |
-| -------------------------------------------- | ------------------------------------------ |
-| `@robota-sdk/agent-framework`                | Session factory, query, config, context    |
-| `@robota-sdk/agent-core`                     | Types (TPermissionMode, TToolArgs)         |
-| `@robota-sdk/agent-transport` (`./headless`) | Headless runner for print mode (`-p`)      |
-| `ink` 7, `react` 19.2+                       | TUI rendering                              |
-| `ink-select-input`                           | Arrow-key selection (permission prompt)    |
-| `ink-spinner`                                | Loading spinner                            |
-| `chalk`                                      | Terminal colors                            |
-| `ink-text-input`                             | Base text input (extended by CjkTextInput) |
-| `marked`, `marked-terminal`                  | Markdown parsing and terminal rendering    |
-| `cli-highlight`                              | Syntax highlighting for code blocks        |
-| `string-width`                               | Unicode-aware string width (CJK support)   |
+| Package                       | Purpose                                                                       |
+| ----------------------------- | ----------------------------------------------------------------------------- |
+| `@robota-sdk/agent-framework` | Session factory, query, config, context                                       |
+| `@robota-sdk/agent-core`      | Types (TPermissionMode, TToolArgs)                                            |
+| `@robota-sdk/agent-framework` | Headless runner and registry for print mode (`-p`); terminal I/O is CLI-local |
+| `ink` 7, `react` 19.2+        | TUI rendering                                                                 |
+| `chalk`                       | Terminal colors                                                               |
+| `marked`, `marked-terminal`   | Markdown parsing and terminal rendering                                       |
+| `string-width`                | Unicode-aware string width (CJK support)                                      |
 
 ## Documentation