@rho-workspace/rho 0.5.2 → 0.5.4

package/README.md

@@ -0,0 +1,94 @@
+# Rho
+
+Rho is an application container for an intelligent, composable workspace. People
+and Agents use the same functional components to act on real resources, inspect
+results and arrange the tools they need.
+
+The first release brings natural-language interaction, code/data/graphics and
+arranged views within one browser window into one workflow. It is distributed
+through npm and runs as a local service with a WebUI. An Agent can compose interfaces
+from registered components while the user continues editing and inspecting the
+same resources.
+
+## Architecture
+
+| Repository | Responsibility |
+| --- | --- |
+| [Rho-core](https://github.com/YuLab-SMU/Rho-core) | Optional managed execution, retained execution facts, activity observation and resident Host |
+| [Rho-plugins](https://github.com/YuLab-SMU/Rho-plugins) | Reusable document/code, file/artifact, runtime/object, requirement, table, media/chart and Agent capabilities; optional reusable domain adapters |
+| Rho | Component selection and assembly, local service, workspace layout, shared interaction and presentation; native windows in a later client |
+
+Components may expose CLI, Skills, MCP and UI entries as their consumers require.
+They retain their implementation, conditions and results across headless and
+application use. Agents use native tools normally; Rho connects shared workspace capabilities and
+uses Core only for selected managed operations or activity observation.
+
+A specific analysis workflow is project code or an acceptance example, not a
+plugin. The [plugin extraction plan](docs/PLUGIN-EXTRACTION.md) applies the
+[capability model](https://github.com/YuLab-SMU/Rho-plugins/blob/main/docs/PLUGIN-MODEL.md)
+to the backend. Version 0.4 independently packages eight selected capabilities and keeps workflow
+actions and recipes outside those packages; an ordinary R project and the original analysis use the same declared
+execution, dependency, resource and selection contracts.
+
+## Technology direction
+
+The first release is an npm launcher and local service with a React, TypeScript
+and Vite WebUI. The workspace lays out the owners' views in Rho's own tabs and
+splits, arranged by the Agent and the person through one conditional layout
+contract. Electron is reserved for a later desktop client that reuses the WebUI
+and component boundaries. Functional views use CodeMirror 6, AG Grid Community
+and ECharts.
+
+Install it with `npm install -g @rho-workspace/rho` on Node 22.22 or later, below 27, start
+`rho`, and connect an external Agent with `rho --grant`
+([Install and start](docs/HEADLESS.md#install-and-start)). Projects,
+files, execution records and workspaces are available through the local WebUI.
+The Agent uses the same scoped capabilities; a browser request copied to an external
+Agent is explicitly a handoff.
+
+The frontend was reconstructed on 2026-10-25 after withdrawing the earlier design
+plans and visual rules. See [Frontend](docs/FRONTEND.md) for the current interface,
+[Status](docs/STATUS.md) for executed checks and limits, and the
+[documentation index](docs/README.md) for backend and release information.
+
+## Set up with an Agent
+
+A person can ask Claude Code or Codex, in any language:
+
+> Read https://yulab-smu.top/Rho/doc/setup.md and follow its steps to install and configure Rho for me.
+
+or: 请阅读 https://yulab-smu.top/Rho/doc/setup.md 文档，按照步骤为我安装并配置 Rho。
+
+That page is [SETUP.md](SETUP.md). The Agent checks the machine, installs the npm package and
+starts Rho on `~/Rho/projects` and `~/Rho/state`. It then installs the Agent Skill in
+[skills/rho](skills/rho/SKILL.md) into its own skills folder, connects itself to the example
+project and says what is missing. The Skill teaches an Agent to install and connect Rho, call
+its tools without guessing, and run an analysis a person can follow. It is published beside the
+page at <https://yulab-smu.top/Rho/skills/rho/SKILL.md>.
+
+## Documentation
+
+<https://yulab-smu.top/Rho/> runs the real interface on the shipped example project,
+replaying a recorded session without a backend, and gives the sentence above for an Agent.
+The documentation is published at <https://yulab-smu.top/Rho/docs/>. The site is
+generated from this repository's `docs/` directory, which stays the only source of
+truth: every page names the file it came from and links to it.
+
+```sh
+npm run docs:dev      # assemble and serve locally
+npm run docs:build    # assemble, then build the static site into site/.vitepress/dist
+npm run docs:check    # fail if a document in docs/ is neither published nor withheld
+npm run pages:build   # front page, demo and documentation into site/.pages (add -- --home for the front page alone)
+npm run pages:check   # walk the demo and the front page in a browser
+npm run pages:capture # record the demo again from this checkout's service (after npm run build)
+```
+
+`@rho-workspace/rho` is published to npm. The registry entry for 0.5.2 carries no
+README, so its package page shows no description; from 0.5.3 the packer ships this README.
+
+For a new component view, start with [Plugin authoring](docs/PLUGIN-AUTHORING.md):
+generate a typed package, preview it independently and select its compiled entry
+through configuration without adding an application adapter.
+
+Contributions follow [Contributing](CONTRIBUTING.md); source is licensed under
+[AGPL-3.0](LICENSE).

package/dist/capabilities.d.ts

@@ -64,6 +64,33 @@ export declare const personFilesSkill: {
         description: string;
     };
 };
+export declare const analysisRunSkillDeclaration: {
+    id: string;
+    version: string;
+    content: string;
+    digest: string;
+    intent: string;
+    requires: string[];
+    example: {
+        method: string;
+        input: {
+            language: string;
+            code: string;
+            purpose: string;
+            changeId: string;
+            waitMs: number;
+        };
+    };
+    failureRecipes: {
+        kind: string;
+        message: string;
+        next: string;
+    }[];
+    verify: {
+        command: string;
+        description: string;
+    };
+};
 export declare const taskMapSkill: {
     id: string;
     version: string;

package/dist/capabilities.js

@@ -1,6 +1,7 @@
 import * as path from 'node:path';
 import { atomicJson, canonical, digest, now, readJson, requireThat, stateDirectory } from '@rho-workspace/plugin-contracts';
 import { operations } from './protocol.js';
+import { screenCheckSkill } from './screen-check-skill.js';
 export const capabilityLimits = { maxReceipts: 256 };
 // The umbrella Skill: what this application is, the order to work in, and the rules
 // that used to be discovered by failing. It names where the detail lives instead of
@@ -85,6 +86,77 @@ const personFiles = {
 };
 export const rhoWorkspaceSkill = { ...applicationSkill, digest: skillDigest };
 export const personFilesSkill = personFiles;
+// Written after five real analyses (bulk RNA-seq, snRNA-seq, GeoMx DSP, bulk plus a
+// metabolome, and a multi-omics cohort) ran through this application. None of them
+// finished unattended at the time: turns ended on a call limit or on a wait nothing
+// wakes, calls went into looking for what may be done rather than doing it, and results
+// were not always written before the turn ended. Several of those stops have since been
+// fixed in this application, so what follows is written as the practice that survived
+// them rather than as a workaround for one build's limits.
+const analysisRunContent = [
+    'A whole analysis has to survive interruption. Rho keeps no step cap and no wall time',
+    'by default, and a long analysis may still be stopped by the person or by the Agent',
+    'client, so write results as you go instead of holding them until the end.',
+    '',
+    '1. Spend calls on the analysis, not on discovery. Resolve the operations you will use',
+    '   once each (kernel.run, kernel.read, kernel.interrupt, resource.list) and reuse the',
+    '   contractRef you were given. In the runs behind this Skill one Agent spent 36',
+    '   capability.index calls in a single analysis and ended with only its quality-control',
+    '   table written.',
+    '2. Do not guess what a result reference contains. A refused read means the shape is',
+    '   wrong, not that the result is missing: resolve the operation that produced it and',
+    '   read the page or range it names instead of trying sibling paths.',
+    '3. Nothing wakes you later. No monitor, timer or event resumes your turn: a cell still',
+    '   running when you stop is left running for nobody, and ending your reply is not',
+    '   proof the analysis finished. Pass a waitMs long enough for the slowest step (a',
+    '   normalisation over 90,000 nuclei can take many minutes), or read the cell with',
+    '   kernel.read in your own next call.',
+    '4. Load once, build on it. A session keeps what a cell defines, so read the data in one',
+    '   cell and derive in the next. A service restart does not keep those objects: the code',
+    '   and its outputs stay, the values in memory do not, so keep a script that rebuilds',
+    '   what matters.',
+    '5. Prefer a few large cells to many small ones, and keep each short enough to finish. A',
+    '   cell that hangs costs time: interrupt it with kernel.interrupt and continue with the',
+    '   part that is cheap to redo.',
+    '6. Draw to an explicit device. In these runs a ggsave call in the shared session hung',
+    '   and the figure had to be redrawn with png() and dev.off(): open the device, plot,',
+    '   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.',
+    '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.',
+    '9. Say what did not reproduce, and why. When a published count cannot be matched, name',
+    '   the undefined choice (a threshold, a direction, a model) and compute the cheap',
+    '   alternatives beside your main one instead of tuning until it fits.',
+    '10. Report the state you actually reached. Say which outputs exist on disk, which cell',
+    '   was still running, and what a stopped turn left behind; the person continues from',
+    '   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,
+    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'],
+    example: {
+        method: 'kernel.run',
+        input: {
+            language: 'r',
+            code: 'counts <- read.csv("data/counts.csv", row.names = 1); dim(counts)',
+            purpose: 'Load the count matrix once and keep it for later cells',
+            changeId: 'load-counts',
+            waitMs: 120000
+        }
+    },
+    failureRecipes: [
+        { kind: 'not_found', message: 'Skill is not available in this project and session.', next: 'Read skill.list for the Skills this project and session expose; a Skill owned by a disabled plugin is not listed.' },
+        { kind: 'stale', message: 'Skill content digest changed.', next: 'Read the Skill again and apply the current text; do not act on a cached copy.' },
+        { kind: 'limit', message: 'Too many cells are waiting.', next: 'Wait for the running cell or interrupt it, then continue in a new cell with a new changeId.' }
+    ],
+    verify: { command: 'npm run test:notebook', description: 'Runs R and Python cells, keeps their output, plots and variables, interrupts and stops sessions, and keeps identity across a restart.' }
+};
+export const analysisRunSkillDeclaration = analysisRunSkill;
 const taskMapContent = [
     'Describe the whole task yourself: Rho fixes no closed list of kinds or states.',
     '',
@@ -240,7 +312,7 @@ export class Capabilities {
     }
     async skills(principal) {
         const state = await this.state();
-        const result = [rhoWorkspaceSkill, personFilesSkill, taskMapSkill];
+        const result = [rhoWorkspaceSkill, personFilesSkill, taskMapSkill, analysisRunSkill, screenCheckSkill];
         for (const descriptor of this.plugins.descriptors()) {
             const status = this.pluginStatus(descriptor.id, state);
             for (const skill of descriptor.skills ?? []) {

package/dist/cli.js

@@ -10,12 +10,39 @@ 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();
 }
+// A generic ACP agent is any program that speaks ACP v1 over stdio. Its command is either a
+// JSON argv array (safest for paths with spaces) or a simple command line.
+function parseAcpCommand(spec) {
+    const text = (spec ?? '').trim();
+    if (!text)
+        throw new Error('--agent-backend acp needs --acp-command: a JSON argv array such as \'["/usr/bin/node","/path/agent.js"]\', or a command line.');
+    if (text.startsWith('[')) {
+        let parts;
+        try {
+            parts = JSON.parse(text);
+        }
+        catch {
+            throw new Error('--acp-command is not valid JSON.');
+        }
+        if (!Array.isArray(parts) || !parts.length || parts.some(x => typeof x !== 'string'))
+            throw new Error('--acp-command JSON must be a non-empty array of strings.');
+        return { file: parts[0], args: parts.slice(1) };
+    }
+    const parts = (text.match(/"[^"]*"|'[^']*'|\S+/g) ?? []).map(p => p.replace(/^(["'])(.*)\1$/, '$2'));
+    if (!parts.length)
+        throw new Error('--acp-command is empty.');
+    return { file: parts[0], args: parts.slice(1) };
+}
 const usage = `Verify a read-only evidence package:
   rho --verify-evidence PATH
+Start Rho on ~/Rho/projects and ~/Rho/state, and say where it is and what is missing:
+  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] [--port 0] [--limits JSON_FILE] [--plugins documents,files,...] [--example on|off] [--open]
+  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]
 A narrower browser link (optional):
   rho --pair PRIVATE_CONNECTION_FILE [--root PROJECTS_RELATIVE_DIRECTORY] [--open]
+Add Rho to your own Claude Code or Codex for one project, as the project page's button does:
+  rho --grant PRIVATE_CONNECTION_FILE --project PROJECTS_RELATIVE_DIRECTORY --agent claude-code|codex
 Give an Agent access to one project, and the command that adds it to Claude Code:
   rho --grant PRIVATE_CONNECTION_FILE --project PROJECTS_RELATIVE_DIRECTORY [--session NAME]
 Serve that access to the Agent over MCP (stdio):
@@ -24,13 +51,27 @@ Observe an external ACP client (use this as its agent command):
   rho --acp /absolute/project --acp-agent claude|codex
 --example off starts Rho without the project it ships; a new state otherwise gets that project
 once, copied into the projects directory. --open opens the printed url in the default browser.
+Without --port a start takes the port this state's last start had, and a new one only when that
+port is taken; --port 0 always takes a new one.
 Opening that url on this machine needs no link, code or session credential; --pair makes a
 narrower, expiring link for one folder.
 PRIVATE_CONNECTION_FILE is the connectionFile the running service printed; it and every
 connection file are credentials.
 `;
-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' }, port: { type: 'string' }, limits: { type: 'string' }, plugins: { type: 'string' }, pair: { type: 'string' }, open: { type: 'boolean' },
-    grant: { type: 'string' }, project: { type: 'string' }, session: { type: 'string' }, mcp: { type: 'string' }, help: { type: 'boolean', short: 'h' } };
+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' }, session: { type: 'string' }, agent: { type: 'string' }, mcp: { type: 'string' }, 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) {
+    const e = error;
+    if (e?.cause?.code === 'ECONNREFUSED' && url)
+        process.stderr.write(`Rho is not running at ${url}. Start it with the same --state-dir, then run this again.\n`);
+    else if (e?.error?.message || e?.kind || e?.syscall)
+        process.stderr.write((e.error?.message ?? e.message) + '\n');
+    else
+        throw error;
+    process.exit(1);
+}
 let parsed;
 try {
     parsed = parseArgs({ options });
@@ -77,40 +118,84 @@ else {
             process.stderr.write('--grant needs --project, the project folder relative to the service root.\n\n' + usage);
             process.exit(2);
         }
+        if (values.agent !== undefined && !['claude-code', 'codex'].includes(values.agent)) {
+            process.stderr.write('Choose --agent claude-code or codex.\n');
+            process.exit(2);
+        }
+        if (values.agent !== undefined && values.session !== undefined) {
+            process.stderr.write('--agent names the session itself; leave out --session.\n');
+            process.exit(2);
+        }
         const { RhoClient } = await import('./client.js');
-        const client = await RhoClient.fromFile(path.resolve(values.grant));
-        const project = await client.call('project.open', { path: values.project });
-        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');
-        process.exit(0);
+        const client = await RhoClient.fromFile(path.resolve(values.grant)).catch(error => refuse(error));
+        try {
+            const project = await client.call('project.open', { path: values.project });
+            // The same as the project page's button: the grant that Agent keeps, then its own
+            // `mcp add`, recorded so the page shows it under that Agent.
+            if (values.agent) {
+                const connected = await client.call('session.connect', { projectId: project.id, agent: values.agent });
+                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');
+            process.exit(0);
+        }
+        catch (error) {
+            refuse(error, client.connection.url);
+        }
     }
     if (values.pair) {
         const { RhoClient } = await import('./client.js');
-        const client = await RhoClient.fromFile(path.resolve(values.pair));
-        const pairing = await client.call('session.browser.pair', values.root ? { path: values.root } : {});
-        const openUrl = link(client.connection.url, pairing.code);
-        process.stdout.write(JSON.stringify({ url: client.connection.url, openUrl, pairingCode: pairing.code, pairingExpiresAt: pairing.expiresAt }) + '\n');
-        if (values.open)
-            openBrowser(openUrl);
-        process.exit(0);
+        const client = await RhoClient.fromFile(path.resolve(values.pair)).catch(error => refuse(error));
+        try {
+            const pairing = await client.call('session.browser.pair', values.root ? { path: values.root } : {});
+            const openUrl = link(client.connection.url, pairing.code);
+            process.stdout.write(JSON.stringify({ url: client.connection.url, openUrl, pairingCode: pairing.code, pairingExpiresAt: pairing.expiresAt }) + '\n');
+            if (values.open)
+                openBrowser(openUrl);
+            process.exit(0);
+        }
+        catch (error) {
+            refuse(error, client.connection.url);
+        }
     }
-    if (!values.root || !values['state-dir']) {
+    // A person who runs `npx @rho-workspace/rho` with no arguments wants the application, not a
+    // usage page: start it on their own folders, say in plain words where it is, and open it when
+    // this is an interactive terminal. Every flagged start is unchanged, so scripts and
+    // acceptance runs keep the output they read.
+    const quickStart = !values.root && !values['state-dir'];
+    if (!quickStart && (!values.root || !values['state-dir'])) {
         process.stderr.write(usage);
         process.exit(2);
     }
+    let quickRoot = '', quickState = '';
+    if (quickStart) {
+        const { homedir } = await import('node:os');
+        quickRoot = path.join(homedir(), 'Rho', 'projects');
+        quickState = path.join(homedir(), 'Rho', 'state');
+        await fs.mkdir(quickRoot, { recursive: true });
+        await fs.mkdir(quickState, { recursive: true });
+    }
+    const projectsRoot = values.root ?? quickRoot, stateDirectory = values['state-dir'] ?? quickState;
     const limits = values.limits ? JSON.parse(await fs.readFile(values.limits, 'utf8')) : {};
     const allowed = new Set(['maxRequestBytes', 'maxEventBytes', 'eventRetention', 'maxSubscriptions', 'maxQueue', 'maxContexts', 'maxBindings', 'maxActivities', 'maxContextBytes', 'maxRetainedMetadataBytes', 'maxConcurrentActions', 'maxOperations', 'maxLogPageBytes', 'maxCodeBytes', 'maxReconciled', 'documents', 'resources', 'workspace', 'r', 'annotations', 'interactions', 'capabilityLimits', 'browser', 'nativeFolders', 'conversations', 'evidence', 'console']);
     if (Object.keys(limits).some(k => !allowed.has(k)))
         throw new Error('Unknown service budget in --limits file.');
     const { RhoService } = await import('./server.js'), { runtime } = await import('./runtime.js');
     const agentBackend = values['agent-backend'] ?? process.env.RHO_AGENT_BACKEND ?? 'claude-acp';
-    if (!['claude-acp', 'codex-acp', 'claude-cli'].includes(agentBackend))
-        throw new Error('Choose --agent-backend claude-acp, codex-acp or claude-cli.');
+    if (!['claude-acp', 'codex-acp', 'claude-cli', 'acp'].includes(agentBackend))
+        throw new Error('Choose --agent-backend claude-acp, codex-acp, claude-cli or acp.');
+    const acpCommand = agentBackend === 'acp' ? parseAcpCommand(values['acp-command'] ?? process.env.RHO_ACP_COMMAND) : undefined;
+    if (values.port !== undefined && !(/^\d+$/.test(values.port) && Number(values.port) <= 65535)) {
+        process.stderr.write('Choose --port 0 to 65535, or leave it out.\n');
+        process.exit(2);
+    }
     // A Core that cannot be used (none for this platform, a changed digest) is read by a person.
     const native = await runtime(values.core, values.rscript).catch(e => { process.stderr.write((e instanceof Error ? e.message : String(e)) + '\n'); process.exit(1); });
     // A person starting Rho sees the project it ships with; a composition that starts a service
@@ -118,7 +203,12 @@ else {
     if (values.example !== undefined && !['on', 'off'].includes(values.example))
         throw new Error('Choose --example on or off.');
     const example = values.example !== 'off';
-    const service = await new RhoService({ example, ...limits, root: path.resolve(values.root), stateDir: path.resolve(values['state-dir']), ...native, agentBackend: agentBackend, codex: values.codex ?? process.env.RHO_CODEX ?? 'codex', claude: values.claude ?? process.env.RHO_CLAUDE ?? 'claude', python: values.python ?? process.env.RHO_PYTHON, ssh: values.ssh ?? process.env.RHO_SSH, serverctl: values.serverctl ?? process.env.RHO_SERVERCTL, port: Number(values.port ?? 0), ...(values.plugins !== undefined ? { plugins: values.plugins ? values.plugins.split(',') : [] } : {}) }).start();
+    const service = await new RhoService({ example, ...limits, root: path.resolve(projectsRoot), stateDir: path.resolve(stateDirectory), ...native, agentBackend: agentBackend, acpCommand, codex: values.codex ?? process.env.RHO_CODEX ?? 'codex', claude: values.claude ?? process.env.RHO_CLAUDE ?? 'claude', python: values.python ?? process.env.RHO_PYTHON, ssh: values.ssh ?? process.env.RHO_SSH, serverctl: values.serverctl ?? process.env.RHO_SERVERCTL, port: values.port === undefined ? undefined : Number(values.port), ...(values.plugins !== undefined ? { plugins: values.plugins ? values.plugins.split(',') : [] } : {}) }).start().catch(async (error) => {
+        // Starting Rho again on a state it already runs on is the common refusal: say where it runs.
+        const held = error?.details?.stateDirectory;
+        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);
+    });
     // 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.
@@ -127,11 +217,46 @@ else {
             url: service.url, connectionFile: path.join(service.state.directory, 'connection.json'), apiVersion: '2.0',
             openUrl: service.url,
             startup: {
-                projects: path.resolve(values.root), state: path.resolve(values['state-dir']),
+                projects: path.resolve(projectsRoot), state: path.resolve(stateDirectory),
                 core: service.bridge.binary, rscript: service.bridge.rscript,
                 note: 'Open this url in a browser on this machine. Execution stays off until an Agent submits a run; project.doctor answers what is missing.'
             }
         } }) + '\n');
+    // What a person needs, after the machine line: where it is, and what is missing to work in it.
+    // A missing Agent or R does not stop the workspace; it decides what the person can do next.
+    if (quickStart) {
+        const say = (text) => process.stdout.write(text + '\n');
+        say('');
+        say('Rho is running. Open this address in a browser on this machine:');
+        say('  ' + service.url);
+        say('');
+        say('Projects folder: ' + quickRoot);
+        say('Service state:   ' + quickState);
+        say('');
+        const agentCommand = await import('@rho-workspace/plugin-agent/acp-command').catch(() => null);
+        // The selection the service itself got: an explicit flag, then the environment, then the name
+        // on PATH. Reporting "installed" for a client the person pointed at a missing path is worse
+        // than saying nothing.
+        const claudePath = values.claude ?? process.env.RHO_CLAUDE, codexPath = values.codex ?? process.env.RHO_CODEX;
+        const env = { ...process.env, ...(claudePath ? { CLAUDE_CODE_EXECUTABLE: claudePath } : {}), ...(codexPath ? { CODEX_PATH: codexPath } : {}) };
+        // An ACP agent named with --acp-command is the operator's own command; it is named, not checked.
+        if (acpCommand)
+            say('Agent: ' + acpCommand.file + ', named with --acp-command.');
+        else {
+            const missing = agentCommand ? agentCommand.missingClient(agentBackend === 'codex-acp' ? 'codex' : 'claude', env) : null;
+            say(missing
+                ? 'Agent: ' + missing + ' Until then folders can be opened and files read here; the Agent cannot run in them.'
+                : 'Agent: ' + (agentBackend === 'codex-acp' ? 'Codex' : 'Claude Code') + ' is installed; a conversation can start in any project.');
+        }
+        const hasR = await fs.access(service.bridge.rscript).then(() => true, () => false);
+        say(hasR
+            ? 'R: ' + service.bridge.rscript
+            : 'R: Rscript was not found. Reading, editing and viewing work; running R needs R installed (or --rscript).');
+        say('');
+        say('Stop it with Ctrl+C. Start it again with: npx @rho-workspace/rho');
+        if (process.stdout.isTTY)
+            openBrowser(service.url);
+    }
     if (values.open)
         openBrowser(service.url);
     let closing = false;