@robota-sdk/agent-cli 3.0.0-beta.86 → 3.0.0-beta.88

package/README.md

@@ -2,10 +2,12 @@
 
 # @robota-sdk/agent-cli
 
-`robota` is an AI coding assistant for the terminal, and the reference app of Robota — a collection
-of TypeScript libraries for building AI agents. It reads your project, edits files and runs commands
-under a permission system you control, and works with Anthropic, OpenAI, Gemini, DeepSeek, Qwen and
-local OpenAI-compatible models.
+`robota` is the configurable terminal interface for Robota, assembled from the
+same TypeScript libraries you can embed. It is a coding-capable agent within the environment whose
+direction is [our agents developing and advancing our agents](../../VISION.md). Autonomous
+self-evolution remains an ambition; the behavior below describes the current CLI. It reads your
+project, edits files and runs commands under a permission system you control, and works with
+Anthropic, OpenAI, Gemini, DeepSeek, Qwen and local OpenAI-compatible models.
 
 The CLI is assembled from the same packages you can use in your own app: `@robota-sdk/agent-framework`
 for the session, `@robota-sdk/agent-ui-terminal` for the terminal UI, and one package per model
@@ -15,8 +17,6 @@ provider. To build your own agent rather than use this one, start with the
 > **Beta.** Behavior may change before the stable release. Please
 > [report issues](https://github.com/woojubb/robota/issues).
 
-![robota reading a project file and explaining its entry point in the terminal](./docs/demo.gif)
-
 ## Install
 
 Requires Node.js 22.12.0 or later.
@@ -35,7 +35,7 @@ Run `robota` inside a Git repository. It first asks whether to trust the folder:
 workspace can load the project's own settings, hooks, skills, plugins and MCP servers. Answer no and
 the session starts **Restricted**, with your user settings and the built-in tools only. The first
 time, it then walks you through choosing a provider and filling in its fields (model, base URL, API
-key), and saves the profile to `~/.robota/settings.json`.
+key), and saves the profile to `<configured-user-state-dir>/settings.json`.
 
 ```bash
 cd my-project
@@ -53,9 +53,9 @@ robota --configure-provider anthropic --type anthropic --model claude-sonnet-4-6
 robota trust --yes
 ```
 
-`robota init` writes a starter `AGENTS.md` and `.robota/settings.json` for the current project.
+`robota init` writes a starter `AGENTS.md` and `<configured-project-state-dir>/settings.json` for the current project.
 `robota --configure` reruns the interactive provider setup, and `robota --reset` deletes
-`~/.robota/settings.json`.
+`<configured-user-state-dir>/settings.json`.
 
 ## What you can do
 
@@ -63,7 +63,7 @@ robota trust --yes
 
 `robota` starts an interactive session. Type a request, or `/` to open the command menu (`/help`
 lists every command). `Esc` stops the current response, `Ctrl+R` searches the prompts you have typed
-before, and every key can be rebound in `~/.robota/keybindings.json` (see the
+before, and every key can be rebound in `<configured-user-state-dir>/keybindings.json` (see the
 [keybindings guide](../../content/guide/keybindings.md)).
 
 The agent works with file and shell tools (`Read`, `Write`, `Edit`, `Glob`, `Grep`, `Bash`),
@@ -154,7 +154,7 @@ any settings file:
 ```
 
 An `ask` rule asks even in `bypassPermissions`, and a few actions are never approved automatically
-in any mode: `rm` on the root, home or working directory, and writes into `.git`, `.robota`,
+in any mode: `rm` on the root, home or working directory, and writes into `.git`, `<configured-project-state-dir>`,
 `.claude`, `.agents` or shell and tool configuration files.
 
 Shell commands can also run inside an OS sandbox (bubblewrap on Linux, Seatbelt on macOS): `/sandbox`
@@ -162,7 +162,7 @@ switches between `auto-allow`, `regular` and `off`, and the `sandbox` settings k
 When something misbehaves, `robota --safe-mode` starts with instruction files, skills, plugins, hooks
 and MCP servers all off.
 
-Workspace trust is granted per Git worktree and kept in `~/.robota/workspace-trust.json`:
+Workspace trust is granted per Git worktree and kept in `<configured-user-state-dir>/workspace-trust.json`:
 
 ```bash
 robota trust status    # is this workspace trusted, and what would trust load? (--json: one line)
@@ -207,11 +207,11 @@ when the first is overloaded, `--effort <level>` sets model effort, and `--advis
 lets the model consult a second model. See [Providers](../../content/guide/providers.md) and
 [Local LLM setup](../../content/guide/local-llm.md).
 
-### Connect MCP servers, or serve Robota over MCP
+### Connect MCP servers, or serve the session over MCP
 
 Declare remote MCP servers under `mcpServers` in a settings file. A declared server is not connected
 until you approve it: `/mcp` shows each server's state, and `/mcp approve <server>` connects it in
-the running session and keeps the approval in `~/.robota/mcp-approvals.json` for later starts. A
+the running session and keeps the approval in `<configured-user-state-dir>/mcp-approvals.json` for later starts. A
 server that uses OAuth also needs a sign-in — `/mcp login <server>` in a session, or
 `robota mcp login <server>` in a terminal — and connects once you sign in.
 
@@ -223,7 +223,44 @@ server that uses OAuth also needs a sign-in — `/mcp login <server>` in a sessi
 }
 ```
 
-`robota mcp serve` does the reverse: it serves one Robota session to an MCP host over stdio (or over
+An HTTP or stdio definition can explicitly select `"protocolVersion": "2026-07-28"` for a stateless
+peer. Omit that field for the legacy handshake. Changing it requires approval again; unsupported values
+are refused rather than silently ignored. The selected version is visible in the definition details.
+Startup reports unavailable client-input, subscription and extension capabilities. Selecting this
+version does not enable distributed Skills or give the server any additional authority. Add
+`"skills": true` to explicitly opt that definition into a peer's advertised Skills extension;
+changing this selection requires fresh server approval. `/mcp skill-list <server>` reads metadata
+only. A local terminal or app user can review `/mcp skill-inspect <server> <uri>`, then copy its
+`/mcp skill-approve <server> <uri> <fingerprint>` command to consent to those exact instructions and
+frontmatter. `/mcp skill-withdraw <server> <uri>` withdraws that consent. JSON string arrays also
+accept opaque names and URIs containing spaces. Content decisions persist separately in
+`<configured-user-state-dir>/mcp-skill-approvals.json`, bound to the host origin, workspace and URI.
+Observed changed or removed manifests withdraw consent even if the peer later reverts them.
+Discovery returns an exact invocation name for each supported skill, or a reason its profile is
+unavailable. Invoke that name through the session's skill command. Instructions load only when
+the actual turn starts, under current content consent; ending or cancelling that turn closes its
+activation. A queued or cancelled request does not load instructions into another turn. Remote
+shell expressions remain instruction text and do not execute as local preprocessing. During an
+active execution, `/skill-read ["<invocation-name>", "<resource-uri>"]` reads a listed supporting
+file with fresh verification. A fork can read only files from its own activations; a nested SKILL.md remains
+supporting data until separately approved and activated.
+
+MCP calls recheck approval and the current source immediately before dispatch. Removing or
+replacing a definition, revoking approval, changing required workspace trust, or closing the
+composition refuses new calls through retained tools. Calls already dispatched keep their real
+outcome; revocation is not rollback. A changed configuration needs a fresh startup and approval
+rather than silently substituting a new connection into an existing tool chain. The startup host
+also exposes declarative contribution descriptors bound to configuration fingerprints, without
+credential values or an invented server version.
+
+| Surface                                    | Verified coverage                                                                      | Limit                                                   |
+| ------------------------------------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| Linux interactive, serve and print startup | Real admitted stdio calls; changed settings refused before another call                | Shared startup composition; not a rendered app UI trial |
+| Installed Linux bundle in serve startup    | Disable, uninstall and selected-revision update; durable approval rechecked at restart | Already dispatched calls settle; no rollback claim      |
+| Remote HTTP                                | Composition, transport admission and call routing regressions                          | No live account benchmark                               |
+| macOS and Windows                          | Repository CI build routes                                                             | No external-plugin pilot on those OSes                  |
+
+`robota mcp serve` does the reverse: it serves one agent session to an MCP host over stdio (or over
 authenticated HTTP with the `--http-*` and `--oauth-*` flags). Trust the project first, and give the
 host the absolute path of `robota` and the project directory:
 
@@ -243,10 +280,10 @@ See [MCP](../../content/guide/mcp.md).
 
 ### Add skills, commands, agents and plugins
 
-Skills and commands are Markdown files the CLI finds in `.robota/skills/`, `.claude/skills/`,
+Skills and commands are Markdown files the CLI finds in `<configured-project-state-dir>/skills/`, `.claude/skills/`,
 `.claude/commands/` and `.agents/skills/` — in a trusted project and under your home directory. Each
 one becomes a slash command (`/<name>`), and `/skills` lists them. Agent definitions are read from
-`.robota/agents/`, `.agents/agents/` and `.claude/agents/`. Plugins bundle these together with hooks,
+`<configured-project-state-dir>/agents/`, `.agents/agents/` and `.claude/agents/`. Plugins bundle these together with hooks,
 themes and MCP servers:
 
 ```text
@@ -259,11 +296,35 @@ See the [CLI guide](../../content/guide/cli.md) for skill frontmatter and plugin
 
 ### Use the graphical interface
 
-`robota --serve --open` starts a headless runtime for the current workspace, serves the Robota GUI
+`robota --serve --open` starts a headless runtime for the current workspace, serves the configured GUI
 on `127.0.0.1` and opens it in your browser. The Electron desktop app in this repository
 ([`apps/agent-app`](../../apps/agent-app/docs/README.md)) shows the same GUI over the workspace
 daemon; it is not published to npm. See [The GUI and the Desktop App](../../content/guide/gui.md).
 
+### Let other apps and services use the agent
+
+`robota --serve --http-port <port>` also serves the agent over HTTP on `127.0.0.1:<port>`, so another
+application or service can use it without a Robota client library. Every request presents the
+bearer you choose in `PRODUCT_HTTP_TOKEN` (at least 32 characters); the runtime removes it from its
+environment, so the commands it runs do not inherit it. A command running as the same OS user can
+still read the server's launch environment unless the OS sandbox confines it (or the server runs
+as a separate user), so enable the sandbox on a server. Reach the API from elsewhere through your own
+reverse proxy or tunnel: it binds loopback only.
+
+```bash
+PRODUCT_HTTP_TOKEN="$(openssl rand -hex 32)" robota --serve --http-port 8787
+```
+
+| Request | Does |
+| --- | --- |
+| `POST /submit` `{"prompt": "..."}` | Runs a turn and streams it as SSE (`text_delta`, `complete`, `error`); `409` while a turn is running |
+| `POST /command` `{"name": "help", "args": ""}` | Runs a slash command |
+| `POST /abort` · `POST /cancel-queue` | Aborts the running turn · drops the queued prompt |
+| `GET /messages` · `/context` · `/executing` · `/pending` | Reads the conversation and its state |
+
+No one can answer a permission prompt over HTTP, so a question no other client answers is denied;
+choose the permission mode and rules the server runs under.
+
 ### Reach other sessions and your other devices
 
 `/peers` lists the other live `robota` sessions on this machine, and `/peers send <session-id>
@@ -289,26 +350,26 @@ robota eval <definition> # run an evals-as-code definition; exits 1 on a metric
 Settings are merged from these files, lowest priority first. The two user files always apply; the
 four project files apply only in a trusted workspace.
 
-| File                          | Scope                                   |
-| ----------------------------- | --------------------------------------- |
-| `~/.robota/settings.json`     | user                                    |
-| `~/.claude/settings.json`     | user (Claude Code-compatible)           |
-| `.robota/settings.json`       | project, committed                      |
-| `.robota/settings.local.json` | project, local to this machine          |
-| `.claude/settings.json`       | project (Claude Code-compatible)        |
-| `.claude/settings.local.json` | project, local (Claude Code-compatible) |
-
-Other files the CLI keeps under `~/.robota/`:
-
-| Path                   | Contents                                                                |
-| ---------------------- | ----------------------------------------------------------------------- |
-| `workspace-trust.json` | workspaces you have trusted                                             |
-| `sessions/`            | saved sessions (a trusted project may keep them in `.robota/sessions/`) |
-| `history.jsonl`        | prompts you typed, for `Ctrl+R` (`"promptHistory": false` turns it off) |
-| `keybindings.json`     | key bindings                                                            |
-| `themes/`              | your own `/theme` themes                                                |
-| `plugins/`             | installed plugins (a project may have its own `.robota/plugins/`)       |
-| `mcp-credentials/`     | OAuth tokens for MCP servers, readable by you only                      |
+| File                                                 | Scope                                   |
+| ---------------------------------------------------- | --------------------------------------- |
+| `<configured-user-state-dir>/settings.json`          | user                                    |
+| `~/.claude/settings.json`                            | user (Claude Code-compatible)           |
+| `<configured-project-state-dir>/settings.json`       | project, committed                      |
+| `<configured-project-state-dir>/settings.local.json` | project, local to this machine          |
+| `.claude/settings.json`                              | project (Claude Code-compatible)        |
+| `.claude/settings.local.json`                        | project, local (Claude Code-compatible) |
+
+Other files the CLI keeps under `<configured-user-state-dir>/`:
+
+| Path                   | Contents                                                                                       |
+| ---------------------- | ---------------------------------------------------------------------------------------------- |
+| `workspace-trust.json` | workspaces you have trusted                                                                    |
+| `sessions/`            | saved sessions (a trusted project may keep them in `<configured-project-state-dir>/sessions/`) |
+| `history.jsonl`        | prompts you typed, for `Ctrl+R` (`"promptHistory": false` turns it off)                        |
+| `keybindings.json`     | key bindings                                                                                   |
+| `themes/`              | your own `/theme` themes                                                                       |
+| `plugins/`             | installed plugins (a project may have its own `<configured-project-state-dir>/plugins/`)       |
+| `mcp-credentials/`     | OAuth tokens for MCP servers, readable by you only                                             |
 
 ## Use it from code
 
@@ -320,6 +381,195 @@ A subagent runs in a child process that starts your entry script again with a wo
 settles (the worker ends the process). So call `startCli()` from the script Node started, and put
 nothing before it that must not run once per subagent.
 
+### Hosted task-worker execution
+
+The library also exports `HostedOrganizationControl` and `createHostedOrganizationGateway` for
+the owner-hosted company backend. This composition requires an anchored `OrganizationLedger`,
+an `OrganizationAudit`, provider-backed worker inventory and named detection, containment,
+assessment and recovery owners. The gateway serves the configured admission endpoints and
+OpenAI model endpoints; its worker ingress has no policy, approval or recovery routes.
+Each model-only grant has a distinct owner-issued task token and runtime binding. The logical task
+root survives grant rotation; provider inventory and gateway admission pin its current binding. Issuer signing
+capabilities, upstream credentials, policy, audit and private payload storage stay outside workers.
+Sign task access with the exported `hostedWorkerAccessBytes` and provision E2B workers with an
+`organization` binding; `createE2BOrganizationInventory` enumerates all pages, including paused
+workers, and rechecks ownership before deletion. Owner stop methods persist withdrawal first,
+abort affected broker calls, and wait for descendant provider cleanup; unresolved cleanup is
+reported to the incident owners.
+
+`HostedOrganizationPayloads` stores bounded request/response bytes in an owner-only directory;
+the durable journal and audit retain digests rather than these bodies. Install
+`createHostedOrganizationModelAction` with a fixed provider endpoint/model, owner-selected
+reservation, input/output bounds and explicit upstream idempotency support. A mandatory trusted
+`countInputTokens` port counts the exact immutable upstream input before dispatch; input plus the
+owner-selected output cap must fit the token and conservative cost reservation.
+`createHostedOrganizationInputTokenCounter` connects a fixed private counting endpoint through an
+owner-selected encoder. A Responses counter does not establish exact Chat token counts; select a
+verified counter for that surface. The counting service must be read-only and covered by the
+owner's pricing assumptions. The gateway buffers
+the upstream result until durable settlement, then returns JSON or OpenAI stream events.
+Configure the worker's OpenAI profile with `options: { durableOperations: true }`: one operation
+identity survives SDK retries, and missing identities are refused. Unknown provider outcomes
+retain reservations and require asset-owner reconciliation; this adapter never retries upstream.
+The private payload store retains digest-bound operation claims for recovery. Owner code may
+load those claims with `operation` and call `reconcileExternalOperation` with confirmed asset-owner
+evidence. Reconciliation charges the entire retained reservation and cannot restore revoked
+authority; the worker gateway exposes no reconciliation route.
+Broker supervisory token/cost observations report settled usage; pending reservations remain
+enforced by the hierarchical ledger. Local process and wire tests establish these software paths,
+while physical containment, provider billing and independent remote custody require deployment
+measurements.
+
+Hosted posture requires current signed admission for a separate task worker and company broker.
+The installed E2B executor runs the stock CLI inside that worker. The runtime forwards arguments,
+input and output and owns cancellation, credential expiry and provider deletion; it does not run
+task tools against its own filesystem. Direct `--api-key` configuration is refused.
+
+`PRODUCT_HOSTED_RUNTIME_CONFIG` selects an owner-controlled version-3 deployment file. It retains
+`identity`, `epoch`, `worker`, `broker`, `snapshot`, `lifetimeMs` and `probeTimeoutMs`, and requires
+`limits: { sessions, modelCalls, modelTokens, costMicros }` with nonnegative safe integer ceilings.
+Version-2 deployments and proofs are refused because they cannot attest current accounting.
+The worker and broker answer version-3 admission challenges with the configured limits; worker
+proofs carry `usage: null`, while broker proofs carry cumulative usage in that same four-counter
+shape. The broker measures registered sessions and provider calls outside the worker for the
+current identity and epoch. Counts and micro-cost units come from its trusted instrumentation,
+not CLI output, model messages or a checkpoint. Both attestations sign the fixed tuple returned by
+the exported `hostedAdmissionBytes`, binding limits and accounting to the current challenge,
+identity, root, epoch and checkpoint. The issuer must validate requested limits against owner policy
+before attesting them.
+
+`HostedRuntimeController.status()` exposes the latest verified observations to the owner. The
+controller checks them before executor allocation, during admission refresh and after short
+executions before reporting success. Invalid, regressing, unavailable or over-limit observations
+refuse admission or stop and release owned execution. Runtime ceilings supervise observed totals;
+the broker's per-request reservations must bound new model calls and their maximum token/cost
+usage before dispatch. Supervisory polling does not replace those reservations or establish an
+invoice hard cap. The broker must retain cumulative accounting across controller restart/resume;
+recovered task content cannot reset it. Actual provider charges and cleanup remain separately
+measured operational evidence.
+
+The operator supplies `PRODUCT_E2B_API_KEY` to the runtime and sets
+`PRODUCT_HOSTED_WORKER_EXECUTION_CONFIG` to an absolute owner-only JSON file. Its version-1 shape is:
+
+```json
+{
+  "version": 1,
+  "templateId": "operator-pinned-template",
+  "nodeExecutable": "/usr/local/bin/node",
+  "workspaceRoot": "/workspace",
+  "entrypoint": { "path": "/opt/agent/cli.mjs", "digest": "<sha256>" },
+  "productConfig": { "path": "/opt/agent/product.env", "digest": "<sha256>" },
+  "access": {
+    "version": 1,
+    "identity": {
+      "tenant": "...",
+      "task": "...",
+      "rootTask": "...",
+      "actor": "...",
+      "runtime": "..."
+    },
+    "worker": "...",
+    "broker": "...",
+    "epoch": 1,
+    "endpoint": "https://company-broker.example/v1",
+    "token": "<task-scoped-broker-token>",
+    "issuedAt": 0,
+    "expiresAt": 0,
+    "signature": "<broker-ed25519-base64url-signature>"
+  }
+}
+```
+
+The broker signs the fixed tuple encoded by `hostedWorkerAccessBytes` in the implementation.
+Access must match the admission's identity, resources and epoch, use the admitted broker origin,
+and expire within both admission and sixty seconds of issuance. This executor ends execution at
+expiry; it does not renew credentials. The template's CLI and product environment artifacts must
+match their pinned digests. The product artifact accepts only CLI product metadata variables.
+Provider metadata must match task ownership and the template, with public traffic disabled and
+outbound access limited to the broker hostname and no attached volumes. The resource must already
+be running, with timeout deletion and auto-resume disabled; connecting a paused memory image is
+refused. These checks do not establish measured cloud containment.
+
+An owner backend can call `provisionE2BTaskWorker` before issuing admission. It creates the
+operator-selected clean template with closed networking, no worker credentials or volumes, and
+an exclusive new workspace. It returns the resource, workspace root, operation ID, checkpoint
+reference, optional conversation artifact receipt and an idempotent `release()` operation. The management capability stays in this
+owner-side SDK composition. After the receipt, the owner signs current worker/broker admission
+and task access for the returned resource and configures that workspace in the execution input.
+
+For recovery, supply an owner-approved `{ id, digest }` reference and the matching UTF-8 JSON bytes
+in `checkpoint`. The manifest has `version: 1`, `id`, the source `identity`, `epoch`, `worker`, and
+`files: [{ path, base64 }]`. Paths are relative regular workspace files; private HOME/TMPDIR and link or memory records
+are not accepted. Owner authority journals stay outside this workspace. The source must belong
+to the same tenant/task/root and precede the current epoch and runtime. File bytes are read back
+and compared before the owner receives a successful result. Treat recovered project content as
+untrusted; current profile, policy and credentials come from the clean operator composition.
+For conversation recovery, use manifest `version: 2` with the same fields and `session` containing
+an existing versioned session-record envelope (`{ schemaVersion, record }`). Only the conversation,
+name, selector and timestamps survive. Saved system messages/prompts, message metadata, tool schemas,
+VM state, goals, background jobs, loops, memory references and branch pointers do not restore;
+current composition rebuilds execution and authority. Display history is rebuilt from the projected
+conversation; saved events are not imported. The record's cwd becomes the fresh workspace.
+Pass the returned `resumeSession: { id, path, digest }` in the private worker execution input and
+invoke `--resume <id>` (or `--continue`, optionally with `--fork-session`). The default executor
+verifies the receipt and copies the projected record into the current product artifact's selected
+private user session store before CLI startup. It refuses an existing destination, mismatched
+selector/digest, malformed record or a user state root inside recovered project files. No saved
+settings, trust decision or credential is imported. A resume without this receipt refuses execution.
+
+The default executor accepts this filesystem checkpoint only when signed current admission and
+provider metadata agree on its digest, fresh identity/epoch and source resource. It does not
+restore provider memory snapshots or reconnect the checkpoint source. Setup failures delete
+verified allocations; unknown creation/ownership and unresolved deletion return
+`E2BWorkerProvisioningError` with reconciliation identifiers. The external owner must retain and
+reconcile those outcomes rather than retry or report cleanup as successful.
+
+The worker receives a closed environment with private HOME/TMPDIR, product configuration and the
+scoped broker token through the OpenAI-compatible provider interface. Management and upstream
+credentials stay outside the worker. Interactive input uses a PTY; input EOF requests the stock
+CLI's Ctrl-C shutdown. For `--serve`, include `serve: { port, workerPort, token }` in the private
+execution input. `port` selects the runtime's IPv4 loopback ingress (`0` assigns a free port);
+`workerPort` selects the worker daemon port. Generate a fresh, unpredictable owner client `token`
+of 32–256 URL-safe characters and connect to the printed runtime URL with `?token=<token>`.
+The runtime validates the client token, Host and Origin, then carries binary WebSocket traffic
+through an owned provider command to the pinned worker loopback listener. It replaces client
+headers and credentials with a separate per-launch worker token. The owner token and provider
+management capability stay in the runtime. Stopping execution closes the listener and clients
+and deletes the worker. This local ingress does not provide remote desktop pairing or TLS.
+Credential renewal requires broker integration; this executor still ends at its signed access expiry.
+
+Embedders can override the installed executor with `hostedRuntimeExecutorFactory`. It receives
+`(admission, signal, invocation)` with immutable captured arguments and returns `run`, `stop` and
+`release`. The adapter owns authenticated communication, input/output and trusted usage reporting;
+stop and release settle only after cleanup. Missing or invalid authority refuses execution without
+entering local host adapters. CLI flags request behavior and never confer company authority.
+
+## Remote desktop owner composition
+
+Use `HostedDesktopWorkerPort.connect({ endpoint, token, worker, control })` with the owner's private
+runtime loopback ingress. It discovers and pins the actual worker session; retain this carrier across
+desktop reconnects. Create `HostedDesktopAuthorization` with the public HTTPS URL, pinned issuer,
+current `HostedOrganizationControl`, and owner-selected bindings containing `id`, `user`, `client`,
+the discovered `session`, and the same `worker`. Give `HostedDesktopGateway` the owner's HTTPS server,
+that authorization, a `HostedDesktopAuthorityStore` and a binding-ID-to-worker-port map. The store uses
+a private existing directory and an independently held organization ledger anchor; `create: true` is only
+for first creation. Store loss, rollback or an uncertain anchor acknowledgment refuses access.
+
+The issuer signs a short-lived asymmetric JWT with exact `sub`, `client_id`, `tenant`, `task`, `session`,
+`workload` and `epoch` binding claims, unique `jti`, `iat`, and `exp`. Ordinary credentials have the public
+URL as audience and `desktop:pair desktop:drive` scopes. A separate operator credential has
+`<publicUrl>/approval` as audience and `desktop:approve` scope. Credentials expire within two minutes;
+pairing grants at most one minute and never extends current company authority. Reconnect uses new JWTs,
+withdraws the previous connection and preserves the pinned worker session. Issuer/JWK outages and current
+grant withdrawal close active access. `gateway.revoke(bindingId)` is an owner-only withdrawal API.
+
+Remote traffic requires TLS and the pinned Host/Origin. TLS termination requires explicitly selected
+proxy IPs with matching HTTPS forwarding headers; arbitrary proxy headers are refused. The renderer
+cannot switch tasks/sessions, execute slash commands, change settings, or approve permissions. The
+main-process operator channel binds Allow once/Deny to the currently pending operation digest and
+rejects replay. Run all authority stores and gateway/control composition outside the task worker.
+These local integration checks do not establish deployed cloud containment or operational latency.
+
 ## Work on the CLI in this repository
 
 ```bash
@@ -340,5 +590,5 @@ pnpm cli:trust        # trust this repository for the source CLI
 
 ## License
 
-Robota is dual-licensed under the [GNU AGPL-3.0](../../LICENSE) or a
+This package is dual-licensed under the [GNU AGPL-3.0](../../LICENSE) or a
 [commercial license](../../COMMERCIAL.md). See [LICENSING.md](../../LICENSING.md).

package/bin/{robota.cjs → agent.cjs}

@@ -8,7 +8,7 @@ const REQUIRED_NODE_MAJOR = 22;
 const nodeMajor = parseInt(process.versions.node.split('.')[0], 10);
 if (nodeMajor < REQUIRED_NODE_MAJOR) {
   process.stderr.write(
-    '\n  Robota requires Node.js ' +
+    '\n  This CLI requires Node.js ' +
       REQUIRED_NODE_MAJOR +
       ' or higher.\n' +
       '  Current version: ' +