@rho-workspace/rho 0.5.6 → 0.5.7

package/dist/agent-connect.d.ts

@@ -12,14 +12,48 @@ export declare const connectLimits: {
 };
 export declare function mcpName(root: string): string;
 export declare function mcpCommand(connectionFile: string): string[];
+export declare function clientEntries(name: string, command: string[], root: string, env?: NodeJS.ProcessEnv): {
+    claude: string;
+    codex: string;
+    opencode: {
+        file: string;
+        merge: {
+            mcp: {
+                [name]: {
+                    type: string;
+                    command: string[];
+                    enabled: boolean;
+                };
+            };
+        };
+    };
+    dsh: {
+        file: string;
+        workspace: {
+            plugin: string;
+            minimumVersion: string;
+            guide: string;
+            mergeConfig: {
+                command: string;
+                args: string[];
+                connectionFiles: (string | undefined)[];
+            };
+            instructions: string;
+        };
+        append: string;
+    };
+};
+export declare const defaultStateDirectory: () => string;
+export declare function launcher(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): Promise<string[]>;
+export declare function commandLine(argv: string[], platform?: NodeJS.Platform): string;
 export declare function connectionInstructions(project: {
     id: string;
     root: string;
-}, stateDirectory: string): {
+}, stateDirectory: string): Promise<{
     request: string;
     prompt: string;
     command: string[];
-};
+}>;
 export declare function addToAgent(agent: OutsideAgent, binary: string, root: string, name: string, command: string[], limits?: {
     timeoutMs: number;
     outputBytes: number;

package/dist/agent-connect.js

@@ -1,7 +1,10 @@
 import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Fault } from '@rho-workspace/plugin-contracts';
+import { announced } from './running.js';
 export const outsideLabel = { 'claude-code': 'Claude Code', codex: 'Codex' };
 // The Agent's CLI is the protected resource: each `mcp` command runs for at most timeoutMs and
 // keeps at most outputBytes of what it printed; past either, it is stopped and the step fails
@@ -13,18 +16,68 @@ export function mcpName(root) {
 export function mcpCommand(connectionFile) {
     return [process.execPath, fileURLToPath(new URL('./cli.js', import.meta.url)), '--mcp', connectionFile];
 }
-// Paths are data in an argv array, never an interpolated shell command. Reading these
-// instructions starts nothing, grants no access and includes no credential bytes.
-export function connectionInstructions(project, stateDirectory) {
-    const command = [process.execPath, fileURLToPath(new URL('./cli.js', import.meta.url)), '--grant', path.join(stateDirectory, 'connection.json'), '--project-id', project.id];
-    const request = `Connect yourself to my existing Rho project ${JSON.stringify(path.basename(project.root))} so we can work on it together.`;
+// Ready entries for the clients whose own mechanism has been used with Rho, so an Agent need not
+// search its documentation for it: Claude Code's and Codex's `mcp add`, OpenCode's project
+// configuration and DeepSeek Harness's profile patch (no `dsh mcp` command exists). Each holds
+// the same name, command and arguments as `mcp`; any other client registers those itself.
+export function clientEntries(name, command, root, env = process.env) {
+    const quote = (value) => /^[A-Za-z0-9_./:@=-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+    const yaml = (value) => JSON.stringify(value);
+    return {
+        claude: ['claude', 'mcp', 'add', name, '--', ...command].map(quote).join(' '),
+        codex: ['codex', 'mcp', 'add', name, '--', ...command].map(quote).join(' '),
+        opencode: { file: path.join(root, '.opencode', 'opencode.json'), merge: { mcp: { [name]: { type: 'local', command, enabled: true } } } },
+        dsh: { file: path.join(env.DSH_HOME || path.join(os.homedir(), '.dsh'), 'profiles', 'desktop', 'cordis.patch.yml'),
+            workspace: { plugin: 'dsh-rho', minimumVersion: '0.1.6', guide: 'https://yulab-smu.top/Rho/docs/reference/deepseek-harness.html',
+                mergeConfig: { command: command[0], args: command.slice(1, -2), connectionFiles: [command.at(-1)] },
+                instructions: 'For conversations and process views, use the dsh-rho plugin. Merge this config into its existing entry, appending the connection file without removing other projects. The append entry below supplies MCP tools only; it does not observe Harness conversations.' },
+            append: ['- insert:', `    - id: ${yaml('mcp-' + name)}`, '      name: "@deepseek-ai/dsh-mcp-client"', '      config:', `        serverName: ${yaml(name)}`, '        transport: "stdio"',
+                `        command: ${yaml(command[0])}`, '        args:', ...command.slice(1).map(arg => `          - ${yaml(arg)}`)].join('\n') + '\n' },
+    };
+}
+// The state folder of a Rho started without --state-dir, which `rho --stop` and `rho connect`
+// also take without it.
+export const defaultStateDirectory = () => path.join(os.homedir(), 'Rho', 'state');
+// How a shell runs this Rho: `rho` when the first `rho` on PATH is this installation (npm's
+// link, or its .cmd shim on Windows), otherwise this Node with this cli.js.
+export async function launcher(env = process.env, platform = process.platform) {
+    const cli = fileURLToPath(new URL('./cli.js', import.meta.url)), real = await fs.realpath(cli).catch(() => cli);
+    for (const dir of (env.PATH ?? '').split(path.delimiter).filter(Boolean)) {
+        const candidate = path.join(dir, platform === 'win32' ? 'rho.cmd' : 'rho');
+        let target;
+        try {
+            if (platform === 'win32') {
+                const shim = (await fs.readFile(candidate, 'utf8')).match(/"%dp0%\\([^"]*?cli\.js)"/i);
+                target = shim ? await fs.realpath(path.resolve(dir, shim[1])).catch(() => null) : null;
+            }
+            else {
+                target = await fs.realpath(candidate);
+                await fs.access(candidate, fs.constants.X_OK).catch(() => { target = null; });
+            }
+        }
+        catch {
+            continue;
+        }
+        return target === real ? ['rho'] : [process.execPath, cli];
+    }
+    return [process.execPath, cli];
+}
+// A command line to read and paste: plain words as they are, anything else in double quotes.
+export function commandLine(argv, platform = process.platform) {
+    return argv.map(arg => /^[A-Za-z0-9_./:@=+,-]+$/.test(arg) ? arg : platform === 'win32' ? `"${arg}"` : `"${arg.replace(/(["\\$`])/g, '\\$1')}"`).join(' ');
+}
+// The prompt names the project and one command; `rho connect` tells the Agent the rest. It names
+// --state-dir only when `rho connect` would not find this Rho itself: a state folder other than
+// ~/Rho/state that no running note points to (a service started without the CLI). Reading
+// these instructions starts nothing, grants no access and includes no credential bytes.
+export async function connectionInstructions(project, stateDirectory) {
+    const found = path.resolve(stateDirectory) === path.resolve(defaultStateDirectory()) || await announced(stateDirectory);
+    const state = found ? [] : ['--state-dir', stateDirectory];
+    const command = [...await launcher(), 'connect', project.root, ...state];
+    const request = `Connect yourself to my Rho project ${JSON.stringify(path.basename(project.root))} so we can work on it together.`;
     const prompt = [request, '',
-        `Project folder: ${JSON.stringify(project.root)}. Project ID: ${project.id}. Rho is already running on this machine.`,
-        'Configure your own client using its supported MCP setup mechanism; inspect your own help or documentation if needed. Keep unrelated configuration, models and credentials intact. Use private local configuration, scoped to this project where supported, and keep connection settings out of version-controlled files. If you cannot run a local stdio MCP server, explain that limitation.',
-        'Run this program and argument array, appending --session and a stable name identifying your own Agent (1–128 characters from A–Z, a–z, 0–9, dot, underscore, colon, @ or hyphen). Reuse that name when retrying:',
-        JSON.stringify(command),
-        'Parse the JSON reply. Register a stdio MCP server using mcp.name, mcp.command and mcp.args exactly as returned. The connection files contain credentials: do not print their contents or put them in the project. Do not start another Rho service.',
-        'Reload your MCP tools if supported, or tell me to open a new session in the project folder. Then call rho_index through your configured client tools and verify scopeHint.projectId matches the project ID above. A direct protocol probe is useful diagnostics but does not prove your client loaded its tools. Report configuration and a successful tool call separately; do not claim connected before the call succeeds. If configuration or verification fails, report the actual error and continue from the same connection.',
+        'Rho is already running on this machine. Run this command with a short, stable name for yourself in place of NAME, and follow its reply:',
+        '', commandLine([...command, '--as', 'NAME']),
     ].join('\n');
     return { request, prompt, command };
 }

package/dist/answer-board.js

@@ -27,7 +27,7 @@ export function answerBoard(graph, turn, limits = boardLimits) {
         const from = byId.get(e.from), to = byId.get(e.to);
         if (!from || !to || to.kind !== 'file')
             continue;
-        const made = (from.kind === 'question' && (e.label === 'wrote' || e.label === 'edited' || e.label === 'changed meanwhile')) || (from.kind === 'run' && e.label === 'changed while it ran');
+        const made = (from.kind === 'question' && (e.label === 'wrote' || e.label === 'edited' || e.label === 'changed meanwhile' || e.label === 'reported result')) || (from.kind === 'run' && e.label === 'changed while it ran');
         // A file of no kind the project shows — an Agent's own settings, a cache — is no output of the work.
         if (!made || !to.category)
             continue;
@@ -48,7 +48,7 @@ export function answerBoard(graph, turn, limits = boardLimits) {
     };
     const madeBy = (o) => {
         const from = byId.get(o.edge.from);
-        return from.kind === 'run' ? 'Changed while ' + quote(from.command ?? from.title) + ' ran' : o.edge.label === 'changed meanwhile' ? 'Changed on disk during this message' : o.edge.label === 'edited' ? 'Edited by the Agent' : 'Written by the Agent';
+        return from.kind === 'run' ? 'Changed while ' + quote(from.command ?? from.title) + ' ran' : o.edge.label === 'reported result' ? 'Reported in the Agent’s answer' : o.edge.label === 'changed meanwhile' ? 'Changed on disk during this message' : o.edge.label === 'edited' ? 'Edited by the Agent' : 'Written by the Agent';
     };
     // Results the answer names lead, then the newest; a figure answers before a table does.
     const results = [...outputs.values()].filter(o => isResult(o.node))
@@ -80,7 +80,7 @@ export function answerBoard(graph, turn, limits = boardLimits) {
             continue;
         if (e.to === question.id && e.label === 'read')
             inputs.set(from.id, { node: from, why: 'Read by the Agent' });
-        else if (e.label === 'named' && runs.has(e.to) && !inputs.has(from.id))
+        else if (e.label === 'named' && (runs.has(e.to) || own.some(link => link.label === 'reported result') && byId.get(e.to)?.kind === 'run') && !inputs.has(from.id))
             inputs.set(from.id, { node: from, why: 'Named by ' + quote(byId.get(e.to).command ?? '') });
     }
     add('input', [...inputs.values()].sort((a, b) => Number(b.node.category === 'data') - Number(a.node.category === 'data') || a.node.at - b.node.at));

package/dist/bridge.js

@@ -59,10 +59,15 @@ const stopFile = (root) => path.join(root, '.rho', 'host.stop');
 // Each argument reaches cmd as a variable inside quotes, where neither its expansion nor & ^ ( )
 // apply, and a Windows path holds no quote; a backslash that would end up before the closing
 // quote (a drive root) is doubled, so it does not escape it.
+// R on Windows sets these locale categories from the environment, and Windows has no C.UTF-8: given
+// one, as an Agent's Git Bash gives LC_CTYPE, a run's R warned at startup and printed "3 × 2" as
+// "3 <U+00D7> 2". The Host's runs take the system's own locale instead, UTF-8 there.
+const posixUtf8 = /^(C|POSIX)\.UTF-?8$/i, rLocale = /^LC_(ALL|CTYPE|COLLATE|TIME|MONETARY)$/;
 function startOnWindows(binary, args, root) {
     const values = [binary, ...args].map(value => value.endsWith('\\') ? value + '\\' : value);
     const line = values.map((_, i) => `"%RHO_HOST_ARG${i}%"`).join(' ');
-    const env = { ...process.env, RHO_CORE_STOP_FILE: stopFile(root), ...Object.fromEntries(values.map((value, i) => ['RHO_HOST_ARG' + i, value])) };
+    const inherited = Object.entries(process.env).filter(([name, value]) => !(rLocale.test(name.toUpperCase()) && posixUtf8.test(value ?? '')));
+    const env = { ...Object.fromEntries(inherited), RHO_CORE_STOP_FILE: stopFile(root), ...Object.fromEntries(values.map((value, i) => ['RHO_HOST_ARG' + i, value])) };
     return spawn(path.join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'cmd.exe'), ['/d', '/v:off', '/s', '/c', `"${line}"`], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, windowsVerbatimArguments: true, env });
 }
 export class CoreBridge {

package/dist/browser-access.d.ts

@@ -12,6 +12,7 @@ export declare const localBrowserId = "browser:local";
 export declare const consoleMethods: string[];
 export declare const kernelMethods: string[];
 export declare const skillsMethods: string[];
+export declare const figureMethods: string[];
 export declare function localBrowserPrincipal(root: string): Principal;
 export declare class BrowserAccess {
     private state;

package/dist/browser-access.js

@@ -23,7 +23,7 @@ export const browserMethods = ['protocol.describe', 'protocol.validate', 'projec
     'action.submit', 'action.output', 'action.cancel',
     // The person's own layout commands (split, move, close, divider, undo), conditional on the
     // version they saw; protected views stay protected.
-    'composition.apply', 'composition.undo',
+    'composition.apply', 'composition.undo', 'composition.delete',
     // A chart's points: the same rows data.page already reads, bounded and read-only.
     'data.plot',
     // A run's script, outputs and provenance written as ordinary files in a new project folder.
@@ -37,7 +37,7 @@ export const browserMethods = ['protocol.describe', 'protocol.validate', 'projec
 // Only the person at this machine talks to a conversation Rho starts: it runs their own Claude
 // Code with their model credentials. Only they add Rho to their own Agent's configuration. A
 // narrower, expiring link never receives these.
-export const conversationMethods = ['agent.sessions.list', 'agent.sessions.read', 'session.instructions', 'session.connect', 'conversation.start', 'conversation.send', 'conversation.stop', 'conversation.decide', 'conversation.read', 'conversation.list', 'conversation.trash', 'conversation.restore', 'conversation.delete', 'conversation.permission', 'conversation.configure', 'conversation.settings.read', 'conversation.settings.update', 'conversation.settings.check', 'project.work.read', 'evidence.preview', 'evidence.export'];
+export const conversationMethods = ['agent.sessions.list', 'agent.sessions.read', 'session.instructions', 'session.connect', 'conversation.start', 'conversation.send', 'conversation.stop', 'conversation.decide', 'conversation.read', 'conversation.list', 'conversation.trash', 'conversation.restore', 'conversation.delete', 'conversation.permission', 'conversation.configure', 'conversation.settings.read', 'conversation.settings.update', 'conversation.settings.check', 'conversation.agents.add', 'conversation.agents.remove', 'project.work.read', 'evidence.preview', 'evidence.export'];
 // The person at this machine. A tab this service served is authorized by the request itself:
 // same origin, loopback only, no link, no code and no expiry. `--pair` stays an explicit,
 // narrower grant for a shared or subfolder-scoped tab.
@@ -47,10 +47,12 @@ export const consoleMethods = ['console.run', 'console.list', 'console.events',
 // The project's live R and Python sessions, which the person shares with their Agent.
 export const kernelMethods = ['kernel.run', 'kernel.read', 'kernel.events', 'kernel.inspect', 'kernel.plot', 'kernel.interrupt', 'kernel.stop', 'kernel.places', 'kernel.place.set', 'kernel.place.check', 'kernel.place.list', 'kernel.place.copy', 'kernel.servers', 'kernel.server.skill'];
 export const skillsMethods = ['skills.list', 'skills.read', 'skills.change', 'skills.undo'];
+// The figures the live R session drew: the person reads them and keeps the marks they ask about.
+export const figureMethods = ['figure.read', 'figure.select'];
 export function localBrowserPrincipal(root) {
     // The empty token hash can never match a request digest, so no header impersonates this
     // identity: it is chosen because the request carried no credential at all.
-    return { id: localBrowserId, kind: 'browser', tokenHash: '', projectRoot: root, methods: [...extensionMethods, ...browserMethods, ...conversationMethods, ...consoleMethods, ...kernelMethods, ...skillsMethods] };
+    return { id: localBrowserId, kind: 'browser', tokenHash: '', projectRoot: root, methods: [...extensionMethods, ...browserMethods, ...conversationMethods, ...consoleMethods, ...kernelMethods, ...skillsMethods, ...figureMethods] };
 }
 export class BrowserAccess {
     state;

package/dist/capabilities.d.ts

@@ -157,7 +157,7 @@ export declare class Capabilities {
         enabled: string[];
     }, author: string): Promise<{
         version: number;
-        enabled: ("media" | "r" | "agent" | "files" | "skills" | "documents" | "requirements" | "tables" | "charts" | "annotations" | "console" | "kernel")[];
+        enabled: ("media" | "r" | "files" | "agent" | "figures" | "skills" | "documents" | "requirements" | "tables" | "charts" | "annotations" | "console" | "kernel")[];
         receipt: CapabilityReceipt;
     }>;
     private pluginStatus;
@@ -192,7 +192,7 @@ export declare class Capabilities {
         }[];
         configuration: {
             version: number;
-            enabled: ("media" | "r" | "agent" | "files" | "skills" | "documents" | "requirements" | "tables" | "charts" | "annotations" | "console" | "kernel")[];
+            enabled: ("media" | "r" | "files" | "agent" | "figures" | "skills" | "documents" | "requirements" | "tables" | "charts" | "annotations" | "console" | "kernel")[];
             retainedReceipts: number;
             retainedFromVersion: number;
             maxReceipts: number;
@@ -213,13 +213,23 @@ export declare class Capabilities {
             effect?: "native" | "file" | "document" | "read" | "metadata" | undefined;
             method: string;
         }[];
-        skills: SkillDeclaration[];
+        skills: (SkillDeclaration & {
+            owner: string;
+        })[];
         agent?: {
             id: string;
             transport: string;
             modelLoop: string;
             contextDelivery: string;
             proactivePush: string;
+            mcp: {
+                entry: string;
+                transport: string;
+                tools: {
+                    name: string;
+                    description: string;
+                }[];
+            };
         } | undefined;
         version: string;
         unavailableActions: {
@@ -237,6 +247,8 @@ export declare class Capabilities {
             presentation?: import("@rho-workspace/plugin-contracts").EntryPresentation;
         }[];
         components: ({
+            uiPackage?: string | undefined;
+            uiPackageVersion?: string | undefined;
             pluginId: string;
             id: string;
             version: string;
@@ -262,8 +274,12 @@ export declare class Capabilities {
         })[];
         capabilities: string[];
     }>;
-    skills(principal: Principal): Promise<SkillDeclaration[]>;
-    readSkill(principal: Principal, skillId: string, expectedDigest?: string): Promise<SkillDeclaration>;
+    skills(principal: Principal): Promise<(SkillDeclaration & {
+        owner: string;
+    })[]>;
+    readSkill(principal: Principal, skillId: string, expectedDigest?: string): Promise<SkillDeclaration & {
+        owner: string;
+    }>;
     assertAvailable(method: string, principal: Principal): Promise<void>;
     isAvailable(method: string, state?: CapabilityState): Promise<boolean>;
 }

package/dist/capabilities.js

@@ -128,7 +128,9 @@ const analysisRunContent = [
     '   close it, and let the figure land in a file you name.',
     '7. Write each file once, complete, and save it to disk before you rely on it. One script',
     '   written in full and then run costs less than the same script edited piece by piece,',
-    '   and a file on disk is the only version that outlives a stop.',
+    '   and a file on disk is the only version that outlives a stop. Run it in the session',
+    '   with kernel.run (source() in R, exec() in Python), not from a shell: a figure file',
+    '   stays readable mark by mark only while it holds the bytes a Notebook cell saved.',
     '8. Check packages in one call, and do not install into a temporary library. Name what is',
     '   missing, and when you substitute a gene-set source or an annotation build, say so',
     '   beside the result, because that choice changes the numbers.',
@@ -140,7 +142,7 @@ const analysisRunContent = [
     '   that record rather than from a claim that the work is done.',
 ].join('\n');
 const analysisRunSkill = {
-    id: 'rho.analysis-run', version: '1.1', content: analysisRunContent,
+    id: 'rho.analysis-run', version: '1.2', content: analysisRunContent,
     digest: digest(analysisRunContent),
     intent: 'Run a whole analysis through the live sessions so a stop never loses the work.',
     requires: ['kernel.run', 'kernel.read', 'kernel.interrupt', 'resource.list'],
@@ -317,12 +319,12 @@ export class Capabilities {
     }
     async skills(principal) {
         const state = await this.state();
-        const result = [rhoWorkspaceSkill, personFilesSkill, taskMapSkill, analysisRunSkill, screenCheckSkill];
+        const result = [rhoWorkspaceSkill, personFilesSkill, taskMapSkill, analysisRunSkill, screenCheckSkill].map(skill => ({ ...skill, owner: 'rho' }));
         for (const descriptor of this.plugins.descriptors()) {
             const status = this.pluginStatus(descriptor.id, state);
             for (const skill of descriptor.skills ?? []) {
                 if (status.packagePresent && status.projectEnabled && status.dependenciesSatisfied && descriptor.operations.some(operation => this.authorized(principal, operation.method)))
-                    result.push(skill);
+                    result.push({ ...skill, owner: descriptor.id });
             }
         }
         return result;

package/dist/cli.js

@@ -8,6 +8,10 @@ import { spawn } from 'node:child_process';
 // A widened link is optional: the fragment carries a one-time code, which no request or Referer
 // sends and which the page redeems and removes. Opening the plain url needs no code at all.
 const link = (url, code) => url + '/#pair=' + code;
+// What Ctrl+C does, asked by another program: Windows has no signal one process can send to Rho
+// there, so `rho --stop` leaves this file in the state folder and the running launcher looks for it,
+// as Rho asks its Host to stop on Windows.
+const stopRequest = (stateDirectory) => path.join(stateDirectory, 'service.stop');
 function openBrowser(target) {
     const [command, args] = process.platform === 'darwin' ? ['open', [target]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '""', target]] : ['xdg-open', [target]];
     spawn(command, args, { stdio: 'ignore', detached: true }).on('error', () => process.stderr.write('Could not open a browser. Open openUrl from the output instead.\n')).unref();
@@ -43,8 +47,12 @@ Start Rho on ~/Rho/projects and ~/Rho/state, and say where it is and what is mis
   rho
 Start Rho:
   rho --root PROJECTS_DIRECTORY --state-dir SERVICE_STATE [--core ABSOLUTE_CORE_BINARY] [--rscript ABSOLUTE_RSCRIPT] [--python PYTHON] [--ssh SSH] [--serverctl SERVERCTL] [--claude CLAUDE_CODE_BINARY] [--codex CODEX_BINARY] [--agent-backend claude-acp|codex-acp|claude-cli|acp] [--acp-command JSON_ARGV] [--port PORT] [--limits JSON_FILE] [--plugins documents,files,...] [--example on|off] [--open]
+Stop the Rho running for a state folder (~/Rho/state without --state-dir), as Ctrl+C in its window does:
+  rho --stop [--state-dir SERVICE_STATE]
 A narrower browser link (optional):
   rho --pair PRIVATE_CONNECTION_FILE [--root PROJECTS_RELATIVE_DIRECTORY] [--open]
+Connect yourself, an Agent, to a project of the running Rho (what a setup prompt asks):
+  rho connect [PROJECT_FOLDER] --as NAME [--state-dir SERVICE_STATE] [--json]
 Add Rho to your own Claude Code or Codex for one project:
   rho --grant PRIVATE_CONNECTION_FILE --project PROJECTS_RELATIVE_DIRECTORY --agent claude-code|codex
 Give any MCP Agent access to one project and print its stdio MCP configuration:
@@ -80,7 +88,7 @@ async function harnessAcp() {
     return undefined;
 }
 const options = { example: { type: 'string' }, 'verify-evidence': { type: 'string' }, acp: { type: 'string' }, 'acp-agent': { type: 'string' }, root: { type: 'string' }, 'state-dir': { type: 'string' }, core: { type: 'string' }, rscript: { type: 'string' }, python: { type: 'string' }, ssh: { type: 'string' }, serverctl: { type: 'string' }, claude: { type: 'string' }, codex: { type: 'string' }, 'agent-backend': { type: 'string' }, 'acp-command': { type: 'string' }, port: { type: 'string' }, limits: { type: 'string' }, plugins: { type: 'string' }, pair: { type: 'string' }, open: { type: 'boolean' },
-    grant: { type: 'string' }, project: { type: 'string' }, 'project-id': { type: 'string' }, session: { type: 'string' }, agent: { type: 'string' }, mcp: { type: 'string' }, help: { type: 'boolean', short: 'h' } };
+    grant: { type: 'string' }, project: { type: 'string' }, 'project-id': { type: 'string' }, session: { type: 'string' }, agent: { type: 'string' }, mcp: { type: 'string' }, stop: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } };
 // A command that is refused says why and what to do. A service that is not running is the
 // common case for --grant and --pair; anything without a known reason keeps its stack.
 function refuse(error, url) {
@@ -102,6 +110,9 @@ if (process.argv[2] === 'plugin') {
         process.exitCode = 1;
     }
 }
+else if (process.argv[2] === 'connect') {
+    process.exitCode = await (await import('./connect-cli.js')).connectCli(process.argv.slice(3));
+}
 else {
     let parsed;
     try {
@@ -127,6 +138,55 @@ else {
         process.stdout.write(usage);
         process.exit(0);
     }
+    if (values.stop) {
+        const { lease } = await import('./state.js');
+        const directory = path.resolve(values['state-dir'] ?? path.join(os.homedir(), 'Rho', 'state'));
+        // The state's writer lock says whether a service runs there: a lock this command can take is free.
+        // A folder without a connection file was never a Rho state, and gets no lock file of its own.
+        const running = () => lease(directory).then(async (release) => { await release(); return false; }, (e) => { if (e?.kind === 'conflict')
+            return true; throw e; });
+        const asked = () => fs.access(stopRequest(directory)).then(() => true, () => false);
+        const connection = await fs.readFile(path.join(directory, 'connection.json'), 'utf8').then(text => JSON.parse(text)).catch(() => null);
+        if (!connection || !await running()) {
+            process.stderr.write(`Rho is not running for ${directory}.\n`);
+            process.exit(1);
+        }
+        await fs.writeFile(stopRequest(directory), '');
+        // The launcher takes the request within a second and then stops as on Ctrl+C: its output ends
+        // with the {"shutdown":…} line, and the lock is free once its state is written.
+        const since = Date.now();
+        while (await running()) {
+            if (Date.now() - since > 10000 && await asked()) {
+                await fs.rm(stopRequest(directory), { force: true });
+                process.stderr.write(`The Rho running for ${directory} did not take the stop request: it is a version without --stop. Stop it with Ctrl+C in its own window (Ctrl+Break on Windows).\n`);
+                process.exit(1);
+            }
+            if (Date.now() - since > 120000) {
+                process.stderr.write(`Rho for ${directory} is still stopping after two minutes. Its output ends with a {"shutdown":…} line once it has stopped.\n`);
+                process.exit(1);
+            }
+            await new Promise(resolve => setTimeout(resolve, 250));
+        }
+        // The lock is released before the launcher prints its report and ends, and on Windows the log
+        // it writes stays open until then: a start right after would find that file in use.
+        const pid = Number.isInteger(connection.pid) ? connection.pid : 0;
+        const alive = () => { try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (e) {
+            return e.code === 'EPERM';
+        } };
+        for (let i = 0; pid && alive(); i++) {
+            if (i === 40) {
+                process.stderr.write(`Rho for ${directory} has closed its state, but its process ${pid} has not ended after 10 s.\n`);
+                process.exit(1);
+            }
+            await new Promise(resolve => setTimeout(resolve, 250));
+        }
+        process.stdout.write(JSON.stringify({ stopped: { state: directory } }) + '\n');
+        process.exit(0);
+    }
     // The Agent's side of a grant: its MCP server reads the connection file and speaks on stdio,
     // so nothing else may write to stdout in this mode.
     if (values.acp) {
@@ -174,13 +234,8 @@ else {
                     process.stdout.write(JSON.stringify({ projectId: project.id, root: project.root, agent: values.agent, methods: connected.methods, granted: connected.granted, added: connected.added }) + '\n');
                     process.exit(0);
                 }
-                const session = values.session ?? 'claude-code';
-                const granted = await client.call('session.grant', { projectId: project.id, externalSessionId: session });
-                const { mcpCommand, mcpName } = await import('./agent-connect.js');
-                const command = mcpCommand(granted.connectionFile), name = mcpName(project.root);
-                const quote = (value) => /^[A-Za-z0-9_./:@=-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
-                process.stdout.write(JSON.stringify({ projectId: project.id, session, connectionFile: granted.connectionFile, methods: granted.methods.length,
-                    mcp: { name, command: command[0], args: command.slice(1) }, claude: ['claude', 'mcp', 'add', name, '--', ...command].map(quote).join(' ') }) + '\n');
+                const { grantReply } = await import('./connect-cli.js');
+                process.stdout.write(JSON.stringify(await grantReply(client, project, values.session ?? 'claude-code')) + '\n');
                 process.exit(0);
             }
             catch (error) {
@@ -249,6 +304,11 @@ else {
             const running = typeof held === 'string' ? await fs.readFile(path.join(held, 'connection.json'), 'utf8').then(text => String(JSON.parse(text).url), () => '') : '';
             return refuse(running ? Object.assign(error, { message: `Rho is already running for ${held} at ${running}. Open that url, or stop that service before starting it again.` }) : error);
         });
+        // A request left by a --stop that this state's earlier service never took is not for this start.
+        await fs.rm(stopRequest(service.state.directory), { force: true });
+        // Where `rho connect` finds this Rho without being given its state folder.
+        const { announce, withdraw } = await import('./running.js');
+        await announce({ stateDirectory: service.state.directory, url: service.url, pid: process.pid }).catch(() => { });
         // The narrow conclusion a person needs on one line: what was selected, where state
         // lives, and how to open it. It stays inside `ready` so a parser reading line one is
         // unaffected. Opening this url on this machine is the access; no link is minted.
@@ -301,11 +361,16 @@ else {
         }
         if (values.open)
             openBrowser(service.url);
-        let closing = false;
+        let closing = false, asked;
+        const stop = async () => { if (closing)
+            return; closing = true; clearInterval(asked); await withdraw(service.state.directory).catch(() => { }); const reports = await service.close(); process.stdout.write(JSON.stringify({ shutdown: reports }) + '\n'); };
         // Windows has no SIGTERM another process can send, and a console may pass on Ctrl+C turned off;
         // there Ctrl+Break on Rho's console (SIGBREAK) stops it in order too.
         for (const signal of ['SIGTERM', 'SIGINT', ...(process.platform === 'win32' ? ['SIGBREAK'] : [])])
-            process.on(signal, async () => { if (closing)
-                return; closing = true; const reports = await service.close(); process.stdout.write(JSON.stringify({ shutdown: reports }) + '\n'); });
+            process.on(signal, stop);
+        // A program with no console to share, such as an Agent that started Rho in the background on
+        // Windows, asks with rho --stop. Removing the request is what takes it.
+        asked = setInterval(() => { fs.rm(stopRequest(service.state.directory)).then(stop, () => { }); }, 500);
+        asked.unref();
     }
 }

package/dist/composition.d.ts

@@ -15,5 +15,5 @@ export declare class Compositions {
     private ancestors;
     private protect;
     read(id: string): Promise<any>;
-    transact(body: any, author: string, kind?: 'apply' | 'undo' | 'protect'): Promise<any>;
+    transact(body: any, author: string, kind?: 'apply' | 'undo' | 'protect' | 'delete'): Promise<any>;
 }

package/dist/composition.js

@@ -82,11 +82,11 @@ export class Compositions {
         requireThat((current?.version ?? 0) === body.expectedVersion, 'stale', 'Composition version changed. Missing receipts do not authorize replay.', { actualVersion: current?.version ?? 0, retainedFromVersion: current?.retainedFromVersion });
         const previous = current?.format === format ? current : { format, rootId: '', nodes: [] };
         let next = structuredClone(previous);
-        const snapshot = (c) => ({ rootId: c.rootId, nodes: c.nodes });
+        const snapshot = (c) => ({ rootId: c.rootId, nodes: c.nodes, ...(c.deleted ? { deleted: true } : {}) });
         let history = current?.history ?? [];
         if (kind === 'undo') {
             requireThat(history.length, 'condition', 'No retained layout transaction can be undone.');
-            next = { ...next, ...structuredClone(history.at(-1).snapshot) };
+            next = { ...next, deleted: false, ...structuredClone(history.at(-1).snapshot) };
             history = history.slice(0, -1);
             for (const n of next.nodes) {
                 const existing = previous.nodes.find((v) => v.id === n.id);
@@ -94,13 +94,23 @@ export class Compositions {
                     n.protected = existing?.protected ?? false;
             }
         }
+        else if (kind === 'delete') {
+            requireThat(current?.format === format && !current.deleted, 'condition', 'Choose an existing Studio workspace.');
+            requireThat(!body.compositionId.startsWith('conversation-'), 'condition', 'A conversation\'s Studio belongs to its conversation.');
+            requireThat(!current.nodes.some((n) => n.kind === 'view'), 'condition', 'Only an empty Studio workspace can be deleted. Close its views first; project files and sessions are separate.');
+            next.deleted = true;
+            history = [...history, { version: current.version, snapshot: snapshot(previous) }].slice(-this.limits.maxUndo);
+        }
         else if (kind === 'protect') {
+            requireThat(!current?.deleted, 'condition', 'This Studio workspace was deleted.');
             requireThat(typeof body.protected === 'boolean', 'invalid', 'Protection must be explicit.');
             const view = next.nodes.find((n) => n.id === body.viewId && n.kind === 'view');
             requireThat(view, 'not_found', 'View is not present.');
             view.protected = body.protected;
         }
         else {
+            requireThat(!current?.deleted || body.operations?.length === 1 && body.operations[0].op === 'replace', 'condition', 'Recreate a deleted Studio workspace with one conditional replacement, or undo its deletion.');
+            next.deleted = false;
             requireThat(Array.isArray(body.operations) && body.operations.length > 0 && body.operations.length <= this.limits.maxNodes, 'invalid', 'Supply a bounded atomic operation batch.');
             for (const op of body.operations) {
                 const node = next.nodes.find((n) => n.id === op.id);
@@ -162,7 +172,7 @@ export class Compositions {
         const availability = await this.validateViews(views, [...(previous.views ?? []), ...(kind === 'undo' ? current.history.flatMap((h) => h.snapshot.nodes.filter((n) => n.kind === 'view')) : [])]);
         const receipt = { changeId: body.changeId, author, version: (current?.version ?? 0) + 1, requestDigest, at: now(), kind };
         const receipts = [...(current?.receipts ?? []), receipt].slice(-this.limits.maxReceipts);
-        const result = { format, compositionId: body.compositionId, rootId: next.rootId, nodes: next.nodes, views, availability, version: receipt.version, author, acknowledgedAt: receipt.at, history, receipts, retainedFromVersion: receipts[0].version, undoRetainedFromVersion: history[0]?.version ?? receipt.version, receipt };
+        const result = { format, compositionId: body.compositionId, rootId: next.rootId, nodes: next.nodes, views, availability, ...(next.deleted ? { deleted: true } : {}), version: receipt.version, author, acknowledgedAt: receipt.at, history, receipts, retainedFromVersion: receipts[0].version, undoRetainedFromVersion: history[0]?.version ?? receipt.version, receipt };
         requireThat(Buffer.byteLength(JSON.stringify(result) + '\n') <= this.limits.maxBytes, 'limit', 'Composition byte budget reached; existing state is preserved.', { limit: 'maxBytes', maximum: this.limits.maxBytes });
         await atomicJson(file, result);
         return result;

package/dist/connect-cli.d.ts

@@ -0,0 +1,50 @@
+import { RhoClient } from './client.js';
+export declare const connectUsage = "Connect yourself, an Agent, to a project of the Rho running on this machine:\n  rho connect [PROJECT_FOLDER] --as NAME [--state-dir SERVICE_STATE] [--json]\nPROJECT_FOLDER is the project's folder (the current folder without it). NAME is a short, stable\nname for you, 1\u2013128 characters from A\u2013Z, a\u2013z, 0\u20139, dot, underscore, colon, @ or hyphen; use the\nsame name when you run this again. Without --state-dir, Rho finds the running Rho that holds the\nfolder; give --state-dir and its state folder when more than one does.\nThe reply says how to add Rho's MCP server to your client; --json prints it as JSON.\n";
+type Client = Pick<RhoClient, 'call'>;
+export type GrantReply = Awaited<ReturnType<typeof grantReply>>;
+export declare function grantReply(client: Client, project: {
+    id: string;
+    root: string;
+}, session: string): Promise<{
+    claude: string;
+    codex: string;
+    opencode: {
+        file: string;
+        merge: {
+            mcp: {
+                [x: string]: {
+                    type: string;
+                    command: string[];
+                    enabled: boolean;
+                };
+            };
+        };
+    };
+    dsh: {
+        file: string;
+        workspace: {
+            plugin: string;
+            minimumVersion: string;
+            guide: string;
+            mergeConfig: {
+                command: string;
+                args: string[];
+                connectionFiles: (string | undefined)[];
+            };
+            instructions: string;
+        };
+        append: string;
+    };
+    projectId: string;
+    session: string;
+    connectionFile: string;
+    methods: number;
+    mcp: {
+        name: string;
+        command: string;
+        args: string[];
+    };
+}>;
+export declare function connectText(reply: GrantReply, root: string): string;
+export declare function connectCli(args: string[]): Promise<number>;
+export {};