@rho-workspace/rho 0.5.5 → 0.5.7

package/docs/FRONTEND.md

@@ -1,6 +1,6 @@
 # Browser application
 
-Updated 2026-11-01. The frontend was reset at the user's request. Previous frontend
+Updated 2026-11-07. The frontend was reset at the user's request. Previous frontend
 plans, visual specifications, Paper references and appearance rulers have been
 removed from the working repository. Git retains their history; they do not govern
 this implementation. This document describes the current application, not another
@@ -10,6 +10,19 @@ prescriptive design system. How it changes next is decided by reviewing real run
 screens do not yet show. Avoid unnecessary secondary labels and descriptions: let the
 layout do the explaining.
 
+## The Agent's view of the sending tab
+
+Each message sent from the Agent panel carries that tab's page and, in Studio,
+its workspace ID, observed layout version and replay position. The service freezes
+a bounded view summary with the message; a retry keeps that original context.
+Under a Studio message, the workspace name records where it was sent from.
+An empty workspace has no views, even when the project contains files. An Agent can
+delete that empty layout through `composition.delete` and restore it through
+`composition.undo`. Deletion removes the sidebar entry and moves an observing tab
+to another workspace, or Overview if none remains. Project files and sessions are
+separate. The [Studio context episode](STUDIO-CONTEXT-EPISODE.md) records the original
+misunderstanding, the real OpenCode run and the limits of this summary.
+
 ## Starting from the work
 
 A person needs to find a project, work on its contents, ask an Agent for help and
@@ -111,6 +124,20 @@ inspect what happened. The application gives those actions direct places:
   the reader is there, also when it is shown again or resized. Only the reader's own
   wheel, touch, keys or scroll bar take it off the end
   ([episode](SIMULATED-PROJECT-EPISODE.md#the-notebook)).
+- **Figures.** An R plot built with ggplot2 (directly or by a package on it) is drawn in the
+  cell and in the Plots view from its figure record. Pointing at a mark shows its row;
+  click, Shift/⌘-click or drag selects, Esc clears, and the rows behind the selection are
+  listed by layer. **Ask the Agent** keeps the selection and opens the Agent panel with it
+  attached to the next message; the chip's × detaches it. Marks the Agent pointed at appear
+  as an amber chip above the plot with its note, shown on the plot when the person has
+  nothing selected. A plot nothing described stays a picture; one that failed says why
+  under it ([episode](FIGURES-EPISODE.md)). A ggplot a cell saved with `ggsave` is drawn the
+  same way wherever its file is shown with the bytes the cell saved: on the answer board, in
+  the Results & figures file view and Studio's media view, and under the cell, which names
+  the file ([episode](SAVED-FIGURES-EPISODE.md)). Layers that draw the same rows count the
+  selection once. Pages drawn with base graphics and ComplexHeatmaps are drawn and selected
+  the same way; heatmap cells keep their colour while others are selected, and a selection
+  outlines them ([episode](DRAWN-FIGURES-EPISODE.md)).
 - **Two forms.** Notebook | Console switches how the same sessions read: as a notebook (above)
   or as a console, one transcript as R or Python print it at a terminal. Each cell is its code
   after the prompt (`>`/`+` in R, `>>>`/`...` in Python, a new statement at the prompt) and what
@@ -249,24 +276,39 @@ inspect what happened. The application gives those actions direct places:
 - **Files** opens documents, browses the project's folder and the source folders it
   works in, and filters the current folder. A source folder is named as the person
   named it and opens one level at a time, the same way any other folder does.
-- **Agent** (the sidebar row) has three tabs. Conversations lists those started in Rho
-  by day, searchable and by Agent: each row its title, model, effort, messages, state,
-  context use and cost, with Continue, export as Markdown and the trash; opened, its
-  facts beside what its latest messages did (the files changed and looked at, each
-  shown in place when chosen, the commands and the answer). The trash restores or
-  deletes. Runs follow when there are any, with their execution records, output,
-  repair context and exports. Agents shows Claude Code and Codex: version, whether
-  asked, the default, model, settings, Claude Code's own model names and the providers
-  with their models. Outside Rho adds Rho to the person's own Claude Code or Codex with
-  one button (`session.connect`) and shows three steps in the state Rho observes:
-  access to this project, Rho in that Agent, its first call; Other ACP clients gives
-  the `rho --acp` commands. Core-backed Claude Code/dsh activity streams, native errors
-  and observed output files sit below in a section read only while it is open
-  ([activity episode](AGENT-ACTIVITY.md), [Agents and conversations](AGENT-PAGE-EPISODE.md),
-  [Agents outside Rho](AGENT-PANEL-EPISODE.md#agents-outside-rho)).
+- **Agent** (the sidebar row) has two tabs. Conversations lists every session in
+  the project folder by day, searchable and by Agent: Rho's conversations, Claude
+  Code and Codex sessions read from the Agents' own records, and observed Harness
+  conversations. Each row names where the session started (Terminal, VS Code, Codex
+  app, Script…) and whether another window has it open now, and offers Continue,
+  the terminal resume command, Markdown export and the trash
+  ([session continuity](SESSION-CONTINUITY-EPISODE.md)). Agents is one list of
+  the project's Agents in one row design, whatever way each works here: the Agents
+  this service can start (a radio for new conversations, the model and folded
+  settings; one not found on this computer is greyed out), and the Agents connected
+  from their own windows. A window sits under the Agent it belongs to, named by its
+  MCP client's own name (`clientInfo`) or else by the session name the Agent chose;
+  each window shows its name, a waiting, verified, refused or ended state, what its
+  grant allows and its last call. Marks and Agent names come from the Agent icons
+  plugin, by the words of the name an Agent gave; a name it does not know shows
+  its initial. Below the list, one setup prompt is for the person's own local
+  MCP client. The prompt names the project and gives one `rho connect` command,
+  whose reply tells the Agent how to configure its own client. Reading or copying grants no
+  access. Copy failure leaves selectable text; request failure
+  offers retry. ACP observations and Host activity remain under a disclosure
+  ([connection episode](AGENT-CONNECT-EPISODE.md)). Conversation rows retain title,
+  model, effort, messages, state, usage, cost and their files, commands and answers;
+  the trash restores or deletes. Runs follow when present
+  ([Agents and conversations](AGENT-PAGE-EPISODE.md)).
 - **Project settings** manages source folders and explicitly checks available tools.
+- **Work from other windows** feeds the same Graph, Console, answer board
+  and session Studio through `agent.sessions.read`. File links in a native answer are
+  reported results; current bytes are not labelled historical. A continued native session
+  is listed once. Notebook cells join its timeline by exact cell IDs in their receipts,
+  not by assuming every call on one connection belongs to that conversation. The
+  [external work episode](EXTERNAL-WORK-EPISODE.md) records the actual Harness check.
 - **Studio** shows how a conversation's work was done. The sidebar lists under Studio
-  each session started in Rho, newest first (eight, then All sessions), and then the
+  each recorded Agent session, newest first (eight, then All sessions), and then the
   person's own workspaces; the Studio bar names the one shown. A session is titled by its
   section of the project notes, else by the Agent's title, else by its first message.
   The **project notes** (`project-notes.md` at the project root) are one Markdown file
@@ -567,13 +609,18 @@ four messages through `web/agent-work.tsx`, the same step model as the panel.
 `web/agent-settings.tsx` keeps one copy of `conversation.settings.read` per tab for
 the Agents tab and the panel's settings menu (`web/settings-menu.tsx`);
 asking an Agent what it offers (`conversation.settings.check`) is always the
-person's click.
+person's click. The Agents tab adds an ACP Agent (`conversation.agents.add`) when the
+person clicks Add on one found installed, types its command, or clicks Use in Rho on an
+Agent connected from its own window whose command Rho knows; an added Agent's settings
+show its command and Remove from Rho. An Agent that offers no settings says so in the
+message box rather than offering to ask.
 Shared notes opens `project-notes.md` in the existing Documents owner. A failed work read keeps the previous
 view and offers Refresh. The cursor invalidates the read model; individual sources
 and resources retain their own versions. See the [observed loop](ACP-EPISODE.md#shared-workspace-loop).
 External ACP sessions use the same work surface with their own source identity,
-plans, usage and read-only latest reply. Their input and permission choices stay
-in the original client. The visible Overview rereads external projections every
+plans, usage and read-only latest reply there. Their permission choices stay in the
+original client; the Agent panel continues such a session in the folder once no
+other window holds it. The visible Overview rereads external projections every
 1.5 seconds; it does not start a collector, Agent or Host. Turn cancellation keeps
 unfinished tool outcomes unknown and does not claim all native processes exited.
 
@@ -607,7 +654,10 @@ A conversation's messages, steps and endings belong to the service's record, not
 the tab. The tab keeps only an unsent message per conversation and the identity of
 a message being sent. When the reply to a send is lost, Retry sends that same message
 once; when the service refuses it, the words go back into the box. A session started
-elsewhere has no message box in Rho: its input stays in its own window.
+elsewhere opens in the same panel with its history, its turns marked with where they
+were sent, and its next message continues that session. While another window holds
+it, the box is disabled with where it is open and a link to continue a copy; Rho
+reloads a session whose record changed after its own last message.
 
 The palette and responsive dialogs use native dialog focus containment and Escape.
 Typography, color and layout are implemented in the three CSS files under `web/`.

package/docs/HEADLESS.md

@@ -40,7 +40,7 @@ The selected baseline is macOS arm64, Node 22.22.3 (engine range
 `>=22.22.0 <27`; the suite and the installed check also passed on Node 24.22.2 and
 26.13.0), npm 10.9.8, Python 3 with `fcntl`, and Rscript 4.5.2. Windows x64
 was checked with Node 22.23.4 and Rscript 4.5.1; its writer lock needs no Python, and
-there `rho.cmd` starts Rho and Ctrl+Break on its console stops it in order.
+there `rho.cmd` starts Rho, and Ctrl+Break on its console or `rho --stop` stops it in order.
 The unsigned npm package `@rho-workspace/rho` contains Plugins and one digest-checked Core
 binary for each of macOS arm64, Linux x64 and arm64 and Windows x64; CI installs it on each.
 R and any project-selected packages are external prerequisites, and so are the Agent
@@ -89,6 +89,17 @@ the state that named the old address is rewritten to the new one, keeping its to
 port named, never replaced. A second start on a state that is already running is
 refused with the running service's address.
 
+`rho --stop [--state-dir DIR]` (`~/Rho/state` without the flag) stops the service that
+holds that state as Ctrl+C does, from any program. On Windows no signal reaches a
+console program from another process, so an Agent that started Rho in the background
+had no orderly way to stop it ([episode](WINDOWS-SETUP-EPISODE.md)). The command leaves
+`service.stop` in the state folder, which the running launcher takes within half a
+second, then waits until the state's writer lock is free and the process that served
+it, named in `connection.json`, has ended. It prints `{"stopped":{"state":…}}`, and the
+service's own output ends with its `{"shutdown":…}` line. It exits 1 when nothing holds
+that state, or when the service there is an earlier version that never takes the
+request (after 10 s, removing it). A start removes a request no service took.
+
 `--port`, `--rscript`, `--core`, `--plugins` and `--limits` are explicit
 operator selections; `RHO_RSCRIPT`, `RHO_CORE_BINARY` and `RHO_PYTHON` select
 equivalent runtimes. A Core override is outside bundled digest verification.
@@ -132,38 +143,89 @@ Exact Host and supplied Origin are checked. The bearer credential is project
 scoped for external callers. CLI shutdown stops only Hosts started by this
 service and reports confirmation separately. Existing Hosts keep their owner.
 
-### Connect Claude Code or Codex
+### Connect your own Agent
 
-The running service's operator connection adds Rho to the person's own Claude Code
-or Codex for one project, as the project page's "Add to …" button does:
+The project's **Agent → Agents** tab offers one prompt for any Agent
+that can configure and run a local stdio MCP server. The prompt names the project
+and gives one command:
 
 ```sh
-rho --grant /absolute/service-state/connection.json --project PROJECT_FOLDER --agent claude-code|codex
+rho connect "/absolute/project folder" --as NAME
 ```
 
-It gives that Agent its own grant to the project (kept when it still reaches the
-service), runs that Agent's `mcp remove` and `mcp add` on this machine — Claude Code's
-with `-s local` in the project folder, Codex's for every folder — and records it, so the
-page shows it under that Agent. The JSON reply names the project, its root, the number
-of granted methods, whether a new grant was made, and what was added (`name`, `scope`,
-`at`). A session that was already open does not have the tools; a new one does.
+The Agent puts a short, stable name for itself in place of `NAME`.
+
+Each Rho started from the command line writes a note in `~/Rho/running/`: its state
+folder, address and process ID, with no credential. It removes the note when it
+stops, and a note whose process is gone is ignored. `RHO_RUNNING_DIR` moves that
+folder.
+
+Without `--state-dir`, `rho connect` asks each running Rho with a note, and the Rho
+on `~/Rho/state`, which of them holds the folder. It refuses when more than one does.
+The prompt adds `--state-dir` only for a Rho that has no note and does not use
+`~/Rho/state`, such as one started by a program rather than the CLI.
+
+When the first `rho` on the service's PATH is not this installation, or cannot run,
+the prompt starts the command with this Node and `cli.js` instead. The build marks
+`dist/cli.js` executable, so a source checkout linked onto PATH keeps working.
+
+`rho connect` finds the innermost project holding the folder, grants it to the named
+Agent and tells the Agent the rest in its reply:
+
+- the MCP server to add, and the ready entries below;
+- to keep the entry private and out of version control;
+- to call `rho_index` and check the project ID.
+
+`--json` prints the `--grant` reply instead. The command refuses, without a grant:
 
-Without `--agent`, the same connection grants one project to one Agent session and
-prints how Claude Code starts that session's MCP server:
+- a missing or placeholder name (exit 2);
+- a folder that is not a project, or a state folder no Rho has used (exit 1);
+- a folder that more than one running Rho holds (exit 1);
+- no running Rho, naming the last address it knows (exit 1).
+
+`session.instructions` is a read-only operation for the local browser or operator.
+It returns the prompt and the command, without credential contents. Reading or
+copying starts no Agent, grants no access and edits no client configuration. The
+Agent uses its own supported configuration mechanism and writes its own entry; the
+ready entries only spare it the search. The [connection episode](AGENT-CONNECT-EPISODE.md)
+records the actual clients checked and the limits.
+
+The running service's operator connection also grants one project to a named Agent
+directly, which setup prompts gave before `rho connect`:
 
 ```sh
-rho --grant /absolute/service-state/connection.json --project PROJECT_FOLDER [--session NAME]
+rho --grant /absolute/service-state/connection.json \
+  --project-id EXISTING_PROJECT_ID --session my-agent
 ```
 
-`--project` is the folder relative to `--root`; `--session` defaults to
-`claude-code`, the session `--agent claude-code` uses, and `--session codex` is the one
-`--agent codex` uses. When the service is not running, both forms say so and exit 1. The JSON reply names the project, the private session connection
-file, the number of granted methods (the server default), an `mcp` entry
-(`name`, `command`, `args`) for an MCP configuration file, and the equivalent
-`claude mcp add rho-<folder> -- … --mcp <file>` command. `rho --mcp FILE` serves
-that grant on stdio with the four tools `rho_index`, `rho_resolve`, `rho_call` and
-`rho_read`; nothing else writes to stdout in that mode. Every connection file is a
-credential. `rho --help` prints the usage; an unknown option exits 2 with it.
+`--project-id` selects an already registered project, including one chosen outside
+the service's projects folder. The older `--project PROJECT_FOLDER` form remains
+available for a folder relative to `--root`; select exactly one form. Choose a
+stable session name for each Agent and reuse it on retry. Without `--session`, the
+legacy default is `claude-code`.
+
+The JSON reply supplies `mcp.name`, `mcp.command` and `mcp.args` for the Agent to
+register in its own client. `rho --mcp FILE` serves that project grant on stdio with
+`rho_index`, `rho_resolve`, `rho_call` and `rho_read`. Connection files are credentials;
+keep their contents out of prompts and projects. The reply also holds ready entries
+for the clients whose own mechanism has been used with Rho: `claude` and `codex`
+(their `mcp add` commands), `opencode` (the project's `.opencode/opencode.json` and
+the entry to merge) and `dsh` (the DeepSeek Harness profile patch and the entry to
+append). The bridge sends its MCP client's `clientInfo` name and version as
+`x-rho-client`; Rho keeps it with the grant and shows it as `client` in the
+snapshot's `agents`, ignoring anything that is not short printable text.
+
+Repeating the same grant keeps a valid credential with the same project, methods
+and profile; changing scope, expired access or stale connection data requires a
+fresh one. A client may need to reload its tools or open a new session. A saved
+entry alone does not verify a connection: call `rho_index` in that client and check
+its project scope. The page observes grants and actual calls separately and does
+not claim that an old successful call means the Agent is online now.
+
+The existing `--agent claude-code|codex` shortcut and `session.connect` remain
+available. They use those clients' own `mcp add` commands (Claude Code in the project
+folder, Codex in user configuration). They are no longer the page's setup workflow.
+A stopped service is reported with exit 1; an unknown CLI option exits 2 with usage.
 
 Agent 0.4.11 provides persistent Claude and Codex ACP entries and retains each
 tool step's human title, ACP category and one identifying input (command, file path,
@@ -204,6 +266,26 @@ settings name one; a model without Auto runs in Accept edits with the adapter's
 Codex's adapter already opens in its own auto-review mode. ACP cancellation confirms the
 turn, not every native job.
 
+Any other Agent that speaks ACP v1 runs through the generic driver, with no adapter of its
+own. `conversation.agents.add` adds one for new conversations in every project, given its
+program (on `PATH` or a path) and arguments, such as `["hermes", "acp"]`. Rho starts it
+once in the project, as `conversation.settings.check` does: a session is opened, what the
+Agent offers is read and the session is removed; no message is sent. The Agent is kept as
+`acp:<name>` only when it answered; otherwise the reply is the Agent's error, or the last
+line it printed when it exited first. `conversation.settings.read` lists the added Agents
+(`added`) and, from `PATH`, the Agents with a known ACP command that are installed and not
+added (`installed`; Agent's `knownAcpAgents`). `conversation.agents.remove` takes one out
+of new conversations. Each conversation records the command it started with, so it
+continues with the same Agent. `--acp-command '<argv JSON>'` / `RHO_ACP_COMMAND` still
+names one ACP Agent at start (`acp`); without it, `dsh acp` is used when Harness's `acp`
+profile is installed. A Harness session in the folder continues only through Harness's own
+ACP command, named at start or added. See the [episode](AGENTS-IN-RHO-EPISODE.md).
+
+| Protected resource | Configuration and default | Exhaustion |
+| --- | --- | --- |
+| Added Agents, kept in the service's Agent settings | `conversations.maxAddedAgents` 16 | Adding another is refused until one is removed. |
+| Starting an Agent to add it | `conversations.connectTimeoutMs` 60 s; one start per command at a time | The start ends; nothing is added and the reason is returned. |
+
 For an external ACP client, select this command as that client's Agent executable:
 
 ```sh
@@ -279,7 +361,8 @@ const check = await rho.call('requirements.check', {
 | `context.create/read` | Exact buffer/version/range, declared selected entities, a media rectangle with page and pixels/points, or one run (`run: {operationId}`): its state, exit, stop, the last 8 KiB of retained stderr with its byte offset and Core's truncation flag, the script reference, args and declared files. |
 | `session.grant`, `binding.open/close/list/activity` | Operator-selected method grant, external binding metadata and bounded tool receipts. Agent grants include the read-only `project.entries` and no other `project.*` method. |
 | `session.connect` | The person at this machine only: grants Claude Code or Codex access to one project and runs that Agent's own `mcp add` (`claude mcp add -s local` in the project folder, `codex mcp add`) with the project-scoped connection. A grant that still reaches this service is kept; a new one the Agent refuses is removed. Each CLI call: 20 s and 8 KiB of output, then stopped with what it printed. |
-| `conversation.start/send/stop/read/permission` | Only the browser on this machine. Original message identities, retained text/tool steps and one selected Agent session. New conversations use the selected Claude or Codex ACP connection. Cancel is confirmed by the original prompt response; lost transport keeps an unknown outcome. Reads and reconnect never replay a prompt. Native permission choices are scoped to the original pending request. Limits are in `conversationLimits` and `--limits`. |
+| `conversation.start/send/stop/read/permission` | Only the browser on this machine. Original message identities, retained text/tool steps and one selected Agent session. New conversations use the selected Claude or Codex ACP connection; `continue: {session, copy}` instead loads a session listed by `agent.sessions.list` under its own native ID, or forks it, and is refused while another process holds that session. Cancel is confirmed by the original prompt response; lost transport keeps an unknown outcome. Reads and reconnect never replay a prompt. Native permission choices are scoped to the original pending request. Limits are in `conversationLimits` and `--limits`. |
+| `agent.sessions.list/read` | Only the browser on this machine; excluded from Agent grants. Claude Code and Codex sessions in the project folder read from their own records, and observed Harness conversations, each with where it started, whether another window holds it now and its resume command. Reading starts no Agent and is bounded (`nativeSessionLimits` in the Agent plugin). |
 | `composition.put/read/apply/undo`, `view.close` | Registered entry/version, props and binding checks; `apply`/`undo` are conditional tree transactions with receipts ([Collaboration](COLLABORATION.md#composition-and-selection)). Uninstalled UI is explicitly unavailable. `rho.action` (version `1`, no bindings) is Rho's own form for one proposed action: props `{title, action, actionVersion, operationId, input, repairOf?}`, and the action must be registered at that version. |
 | `workspace.save/export/restore` | Drafts/undo, bytes/provenance, selections and composition intent; native execution is not replayed. |
 | `action.export` | One run as ordinary files in a new project folder (default `exports/<operationId>`): `script/` holds the code that ran, from the run's own record; `outputs/` holds each declared file as the run left it; `provenance.json` and `PROVENANCE.md` give the run, script digest, arguments, inputs, each file's SHA-256 and whether it matches the inventory the run wrote. A declared file that was not written, or no longer matches that inventory, is named and left out, and the export says `partial`. When the script has unsaved changes the call must say `unsaved: "include"` (written as `<name>.unsaved.<ext>`, marked as never run) or `"leave"`. Runs nothing; never writes into an existing folder. |
@@ -425,6 +508,7 @@ RHO_CORE_BINARY=/absolute/rho-core npm run recovery
 RHO_CORE_BINARY=/absolute/rho-core npm run agent
 npm run pack:local -- --core darwin-arm64=/absolute/mac/rho-core \
   --core linux-x64=/absolute/linux-x64/rho-core --core linux-arm64=/absolute/linux-arm64/rho-core \
+  --core win32-x64=/absolute/win32-x64/rho-core.exe \
   --core-source /absolute/Rho-core --plugins /absolute/Rho-plugins
 node scripts/install-acceptance.mjs /absolute/rho-workspace-rho-0.5.2.tgz \
   /absolute/ordinary-project /absolute/paired-project
@@ -460,6 +544,25 @@ records source commits/trees, build-input and lock hashes, binary/package digest
 and platform, plus each selected plugin tarball identity. It does not build Core, sign or publish to a registry. Direct
 packing of the development source-linked root is rejected.
 
+Each Core is built as CI's `core` job in [`ci.yml`](../.github/workflows/ci.yml) builds it.
+Check out the Core commit that `components.json` selects with LF line endings
+(`git config --global core.autocrlf false` before cloning). Core compiles
+`docs/ACTIVITY.md` and `docs/MANAGED-RUN.md` in byte for byte, and under Git for
+Windows' default a fresh clone gave a Core whose contract text ended its lines in CRLF
+where CI's has LF. Core keeps those two files LF itself from `8ef933a`, and the packer
+records them among Core's build inputs. Then run
+`CARGO_PROFILE_DEV_DEBUG=0 cargo build --locked --target TARGET`: on Windows, TARGET is
+`x86_64-pc-windows-msvc` (MSVC Build Tools) and the binary is
+`target/x86_64-pc-windows-msvc/debug/rho-core.exe`. A Core built on another machine is
+not CI's: it names that machine's Cargo registry folder, under the builder's user
+folder, 78 times. To carry the accepted Cores instead, take CI's `core-PLATFORM`
+artifacts or the published package's `vendor/core/PLATFORM/` binaries, and add
+`--core-composition` with the composition that records them (the package's
+`vendor/composition.json`); the packer refuses a binary whose digest it does not record. On Windows, `npm ci` in Rho-plugins also
+unpacks the Agent adapters' optional platform clients (Codex 462 MiB, the Claude Agent
+SDK 284 MiB), which the package leaves out. In one run that took 14.5 of its 15
+minutes ([#112](https://github.com/YuLab-SMU/Rho/issues/112)).
+
 
 ## Native artifact intake (phase 1)
 

package/docs/THIRD-PARTY-PLUGINS.md

@@ -7,9 +7,10 @@ or becoming a base dependency. The first consumer is the optional
 Its scientific implementation remains in sclet and its objects remain in the
 project's shared R session. See the [observed episode](THIRD-PARTY-PLUGINS-EPISODE.md).
 
-This is source functionality after Rho 0.5.4, not a new npm release. Build the
-current checkout with `npm run build` and use `node dist/cli.js` in place of
-`rho` until a distribution containing it is installed.
+Runtime package installation is included in Rho 0.5.5. User-configured remote
+markets are source functionality after 0.5.6. Build the current checkout with
+`npm run build` and use `node dist/cli.js` in place of `rho` for that new path
+until a distribution containing it is installed.
 
 ## Install and manage
 
@@ -55,6 +56,69 @@ selection. Both preserve native tasks, R sessions, project files and receipts.
 Package revisions are retained in the service's `plugins/versions` directory;
 remove is not a disk-purge command. Closing a view only releases its renderer.
 
+## Remote plugin markets
+
+In **Plugins → Third-party plugins → Plugin markets**, add an HTTPS JSON index.
+The plugin search above includes its titles, descriptions, package ids and
+keywords. Rho retains the index locally; opening the page, searching and listing
+do not fetch it again or install its packages. **Refresh** explicitly reads the
+source again. A failed refresh displays its error and keeps the last successful
+index available. **Remove** removes the source, keeping installed plugins and
+their recorded market keywords searchable.
+
+The [YuLab Rho index](https://raw.githubusercontent.com/YuLab-SMU/Rho/main/site/market/rho.json)
+includes Semantic figures, discoverable by `ggtree`, `clusterProfiler`, `dotplot`
+and `cnetplot`. It is an optional source; add it explicitly:
+
+```sh
+rho plugin market add https://raw.githubusercontent.com/YuLab-SMU/Rho/main/site/market/rho.json
+rho plugin market list
+rho plugin market install MARKET_ID yulab.semantic-figures
+rho plugin market refresh MARKET_ID
+rho plugin market remove MARKET_ID
+```
+
+Use the id returned by `add` or `list` for `MARKET_ID`. The ordinary
+`--connection FILE` option selects a running service. The browser and CLI use
+the same saved sources. Agents can read cached indexes with `extension.list`;
+adding, refreshing, removing sources and installing packages remain local-person
+operations through `extension.market.change` and `extension.install`.
+
+Publishers can host a static file matching the [actual index](../site/market/rho.json):
+
+```json
+{
+  "apiVersion": 1,
+  "title": "My lab's Rho plugins",
+  "plugins": [{
+    "id": "lab.my-plugin",
+    "title": "My plugin",
+    "version": "0.1.0",
+    "description": "What this plugin does",
+    "source": "@my-lab/rho-plugin@0.1.0",
+    "repository": "https://github.com/my-lab/rho-plugin",
+    "needs": "Required tools or data",
+    "keywords": ["analysis", "visualization"]
+  }]
+}
+```
+
+Each index selects one version per plugin id. `keywords` is optional; the other
+fields shown are required. Package sources use an exact npm version matching
+`version`, or `git+https://…#FULL_40_CHARACTER_COMMIT:package/path`. The package's
+actual plugin id and version must match before installation selects it. Install
+binds the source to the index digest the person selected; a changed or removed
+index refuses a stale install. The installed package records its market URL,
+title, index digest and keywords alongside its own source and runtime-tree digest.
+
+Index URLs use HTTPS without credentials, queries or fragments. Explicit loopback
+HTTP supports local development. Redirects, authenticated indexes, automatic
+refresh/update and tarball entries in markets are not supported in this pass;
+direct package installation still accepts tarballs. An index is publisher metadata,
+not a signature or proof of package validity. This Rho `apiVersion: 1` index is
+separate from the [Harness index](../site/market/index.json); the formats are not
+interchangeable. See the [observed market episode](PLUGIN-MARKETS-EPISODE.md).
+
 ## Create a package
 
 ```sh
@@ -141,6 +205,10 @@ output.textContent = receipt.state === 'completed'
   ? receipt.value.greeting : receipt.error;
 ```
 
+The frame follows the page's own height from 200 to 900 px, so let the page flow
+rather than fill the viewport; a taller page scrolls inside the frame. The page
+`create` generates shows a labelled form, a result and a failure state to start from.
+
 Pass a third argument to `rho.call` to retain an explicit original changeId.
 The default generates one per deliberate call. A stale digest is refused; reopen
 the view after an update. Several views may be declared and selected in the plugin
@@ -174,6 +242,8 @@ and obtained receipts, or records an unknown result after an interrupted call.
 
 | Protected resource | Default configuration |
 | --- | --- |
+| Configured market sources / entries in each index | `maxMarkets: 16`, `maxMarketEntries: 128` |
+| Each downloaded index / request duration | `maxMarketBytes: 262144`, `marketTimeoutMs: 10000` |
 | Installed selections / retained revisions | `maxPlugins: 32`, `maxVersions: 128` |
 | Admitted runtime tree | `maxFiles: 20000`, `maxPackageBytes: 134217728` |
 | Skill/view bytes | `maxContentBytes: 524288` |
@@ -181,6 +251,8 @@ and obtained receipts, or records an unknown result after an interrupted call.
 | Concurrent calls / delegated calls per invocation | `maxRunning: 4`, `maxDelegations: 32` |
 | Worker / each install subprocess | `timeoutMs: 30000`, `installTimeoutMs: 180000` |
 
+Market limits refuse an initial add or retain the previous index after a failed
+refresh. The byte limit also checks streamed responses without a Content-Length.
 The tree-size check applies after npm staging; it is not a disk quota on npm/Git.
 A timed-out worker does not prove a delegated native task stopped. Observe its
 original identity. Retention limits refuse rather than silently evict identities;

package/node_modules/@rho-workspace/plugin-agent/README.md

@@ -347,6 +347,11 @@ observation of the original identity, never replacement work. A refused connecti
 transport failure whose outcome is known: nothing reached the service, so the call
 returns `unavailable` naming the address and saying nothing ran (`delivered: false`).
 
+Since 0.4.31 each call also carries `x-rho-client`: the name and version the MCP
+client gave in its own `initialize` (`clientInfo`), each URL-encoded and at most 128
+characters, joined by `/`. A client that gives no name sends no header. The
+application uses it to say which Agent a connection belongs to; it grants nothing.
+
 The pure `./layered-contract` entry defines the four tool inputs and Agent note
 props. `./layered` provides the bounded complete-object cache and caller checks;
 it owns no second registry, native loop or task scheduler. Before execution it
@@ -429,3 +434,32 @@ local storage and observation work; they do not limit the native Agent.
 `test/external-session.test.mjs` checks identity, prefix conflicts, omissions,
 missing outcomes, redaction, project containment, retained failure and pagination.
 The Rho application records its separate real Harness/browser acceptance.
+
+### Native Claude Code and Codex sessions
+
+Agent 0.4.30 exports `native-sessions`. `listNativeSessions(root, nativeSources(env))`
+lists the Claude Code and Codex sessions whose recorded working folder is `root`,
+read from the Agents' own records: `CLAUDE_CONFIG_DIR` (or `~/.claude`)
+`/projects/<folder>/<id>.jsonl` and `CODEX_HOME` (or `~/.codex`)
+`/sessions/**/rollout-*.jsonl`. Each summary keeps the native session ID, title,
+times, turn counts, where it started (Claude Code's `entrypoint`, Codex's
+`originator`), whether another process holds it now (Claude Code's live
+`sessions/<pid>.json` with a running PID, Codex's `thread-writer-locks/<id>.lock`)
+and the terminal resume command. `readNativeSession` streams one record into the
+same turn shape as `readExternalSession`, with each turn's tools, results and
+reply. Reading starts no Agent, takes no lock and writes nothing.
+`nativeSessionLimits` names the budgets: 64 sessions per listing, 4,096 files
+scanned per Claude Code folder and across Codex's sessions, 256 KiB read from each end of a file for a summary, at most 256 MiB
+streamed from the end for a read, 200 turns, 256 tools per turn, and the text and
+tool field limits above. Sidechains, injected reminders and local command output
+are excluded. A recorded interruption is stopped. A last turn without an end record
+is running while its file was written in the last minute; after that it is completed
+when it has a reply and no unanswered tool, and unknown otherwise.
+
+To continue such a session, the application passes its ID as `sessionId` (ACP
+`session/load`). `forkFrom` instead asks the Agent for a separate copy through
+`session/fork`; the connection is refused before sending when the Agent does not
+advertise fork, or returns the same ID. `acpEnvironment` drops inherited Claude Code
+session markers (`CLAUDECODE`, `CLAUDE_CODE_CHILD_SESSION` and related variables):
+a Claude Code started under them saves no transcript, so its session could not be
+listed or continued anywhere else.

package/node_modules/@rho-workspace/plugin-agent/dist/acp-command.d.ts

@@ -7,6 +7,38 @@ export declare function acpCommand(agent: AcpAgent): {
  * optional dependencies that an application need not install, so name the selected
  * executable, else the one already named in the environment, else the client on PATH. */
 export declare function acpEnvironment(agent: AcpAgent, env: NodeJS.ProcessEnv, executable?: string): NodeJS.ProcessEnv;
+export declare function withoutSessionMarkers(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** The file a shell runs for `program`: the program itself when it names a path, else the first
+ * runnable match on PATH. On Windows a copied environment keeps the variable's own case (Path),
+ * and a program is a file with an extension PATHEXT names (claude.exe, an npm codex.cmd). */
+export declare function locate(program: string, env: NodeJS.ProcessEnv): string | null;
 /** Why the adapter could not start the person's client, or null when its executable is
  * there. The adapters report a missing client only as a closed connection. */
 export declare function missingClient(agent: AcpAgent, env: NodeJS.ProcessEnv): string | null;
+/** Agents that serve ACP through a command of their own: the program a person installs and the
+ * arguments that make it an ACP Agent, as the ACP registry (github.com/agentclientprotocol/registry,
+ * read 2026-11-07) gives them or as Rho has run them. Rho starts any of these as it starts a
+ * command the person names; the list only lets it find them. */
+export interface KnownAcpAgent {
+    id: string;
+    name: string;
+    program: string;
+    args: string[];
+}
+export declare const knownAcpAgents: KnownAcpAgent[];
+/** The known Agents installed on this computer, each with the file its command starts. Finding
+ * them reads PATH (and Harness's profile folder) and starts nothing: whether one answers as an
+ * ACP Agent is known only once it is started. */
+export declare function installedAcpAgents(env?: NodeJS.ProcessEnv): {
+    id: string;
+    name: string;
+    command: {
+        file: string;
+        args: string[];
+    };
+}[];
+/** The known Agent a command starts, when it starts one with its ACP arguments. */
+export declare function knownAcpAgent(command: {
+    file: string;
+    args: string[];
+}): KnownAcpAgent | null;