@algosuite/vo-mcp 0.2.0-beta.7 → 0.2.0-beta.71

package/README.md

@@ -1,11 +1,37 @@
 # @algosuite/vo-mcp
 
-Virtual Office MCP server — the open protocol surface that exposes VO's consensus and ratchet tool family to any MCP-capable LLM client (Claude Code, Claude Desktop, Cursor, Continue, Codex, etc.).
+> **Architecture mandate (ADR-004, 2026-08-16): thin runner, cloud brain.** This package must shrink to a thin executor + shim — spawn the agent, manage worktrees/pushes, hold credentials, carry the local half of the MCP transport. Prompt composition, routing, watcher/merge/repair decisions, policy tables and the consensus engine belong in `cloud-run/vo-control-plane` / `cloud-run/vo-moat-plane`, not here (this package is on the PUBLIC npm registry). Fixes may land here when that is the fastest way to unblock the loop, but every decision-making module in this bundle is migration debt: record it in the ADR-004 ledger and move it to the plane (HQ roadmap Phase 11). Do not add new decision logic here without a ledger row.
 
-**Status:** Phase 2. Stdio transport. **20 tools registered** (source of truth: `src/server.ts` `buildToolRegistry()`). The static-ratchet tools (`vo_check_assertion_strength`, `vo_check_ratchets`) run locally today; the consensus-routed tools fall back to `{ verdict: "unimplemented", ... }` until engine credentials are present; the heal-family, PR-admin, and session-state tools forward to the vo-control-plane admin proxy in cloud mode. `vo_review_merge` is a **read-only consensus pre-merge review** (the verify-before-act gate for the Command Center — never merges). The shape is stable; the institutional-knowledge content is loaded from closed packages.
+AlgoHQ MCP server — the open protocol surface that exposes HQ's consensus and ratchet tool family to any MCP-capable LLM client (Claude Code, Claude Desktop, Cursor, Continue, Codex, etc.).
+
+The live AlgoHQ whiteboard is available to every MCP client through
+`hq_whiteboard_post` and `hq_whiteboard_read`. Both use the scoped credential
+created by `vo-mcp login`; tenant/operator ownership is derived by the control
+plane and cannot be widened by tool input. The control plane admits scoped
+credentials only for operator IDs on its internal `HQ_WHITEBOARD_OPERATOR_IDS`
+allowlist; arbitrary self-serve tenants cannot read or write the shared fleet board.
+
+**Status:** Phase 2. Stdio transport. **26 tools registered** (source of truth: `src/server.ts` `buildToolRegistry()`). The static-ratchet tools (`vo_check_assertion_strength`, `vo_check_ratchets`) run locally today; the consensus-routed tools fall back to `{ verdict: "unimplemented", ... }` until engine credentials are present; the heal-family, PR-admin, session-state, and AlgoHQ whiteboard tools forward to the control plane in cloud mode. `vo_review_merge` is a **read-only consensus pre-merge review** (the verify-before-act gate for the Command Center — never merges). The shape is stable; the institutional-knowledge content is loaded from closed packages.
 
 This package is intentionally **shell-only**. Per `docs/handoffs/vo-mcp-server-2026-05-21.md` §C-1: tool *definitions* (schemas, names, descriptions) ship openly. Tool *implementations* that encode institutional knowledge (specific ratchet thresholds, consensus prompt content, architectural-defaults knowledge base) live behind the cloud or in closed companion packages.
 
+## Install and refresh client configuration
+
+`vo-mcp install` safely registers the same required `algohq` MCP server in
+Claude Desktop, Claude Code, and Codex (`~/.codex/config.toml`), then offers
+pairing and runner auto-start. Existing client settings and comments are
+preserved, and every changed config is backed up first.
+
+To refresh client configuration on an already-paired runner without touching
+its keychain credential or auto-start service, use the noninteractive form:
+
+```sh
+vo-mcp install --config-only
+```
+
+Restart the MCP clients and runner after updating, then use
+[AlgoHQ](https://algosuite.ai/algohq) to dispatch work.
+
 ## Tools
 
 | Name | Phase 1 status | Description |
@@ -44,7 +70,7 @@ pnpm test            # vitest run
 
 The integration test (`test/integration/stdio-roundtrip.test.ts`) spawns the built CLI, exchanges JSON-RPC over stdio, and asserts:
 
-- `initialize` + `tools/list` returns the 20 expected tools.
+- `initialize` + `tools/list` returns the 26 expected tools.
 - `vo_check_assertion_strength` runs end-to-end and writes a JSONL event line.
 - A repeat call with identical input hits the cache (`cache.hit = true`).
 - `vo_consensus_judgment` returns `unimplemented` and still writes its event line.

package/bin/vo-mcp

@@ -5,10 +5,11 @@
  * Usage:
  *   vo-mcp                                  # MCP stdio server (default)
  *   vo-mcp install                          # one-command installer
+ *   vo-mcp install --config-only            # refresh Claude + Codex MCP config only
  *   vo-mcp update                           # update MCP + runner package
  *   vo-mcp login                            # credential login (browser loopback)
  *   vo-mcp pair                             # device-code pairing (enter a code in the web)
- *   vo-mcp runner                           # agent runner daemon
+ *   vo-mcp runner                           # supervised agent runner
  *   vo-mcp runner --install-autostart       # register runner to start at login
  *   vo-mcp runner --uninstall-autostart     # remove auto-start registration
  */
@@ -31,9 +32,11 @@ if (command === 'install') {
     import('../dist/autostart-cli.js').then((m) => m.installAutostartCli());
   } else if (subcommand === '--uninstall-autostart') {
     import('../dist/autostart-cli.js').then((m) => m.uninstallAutostartCli());
-  } else {
-    // Bring-your-own runner daemon (bundled by scripts/bundle.mjs into dist/).
+  } else if (process.argv.includes('--once') || process.argv.includes('--status') || process.argv.includes('--version') || process.argv.includes('-v')) {
+    // Direct diagnostic/one-shot mode; remote maintenance uses the supervisor.
     import('../dist/runner-cli.js');
+  } else {
+    import('../dist/runner-supervisor.js');
   }
 } else {
   // Default: MCP stdio server