@algosuite/vo-mcp 0.2.0-beta.2 → 0.2.0-beta.20

package/README.md

@@ -1,153 +1,178 @@
-# @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.).
-
-**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.
-
-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.
-
-## Tools
-
-| Name | Phase 1 status | Description |
-| --- | --- | --- |
-| `vo_check_assertion_strength` | Implemented (stub ratchet) | Score a test file's assertions 0-100 with per-assertion findings. |
-| `vo_check_hollow_test` | Stub | Detect tests that pass without verifying product truth. |
-| `vo_verify_answer` | Stub | Semantic-equivalence comparison of expected vs observed. |
-| `vo_consensus_judgment` | Stub + logging skeleton | Submit a prompt to multiple models, return synthesized verdict. **Logs every call** (V1 launch gate #7). |
-| `vo_architecture_review` | Stub | Senior-architect review of a diff against project defaults. |
-
-All tools follow the same response envelope:
-
-```jsonc
-{
-  "tool": "vo_check_assertion_strength",
-  "schema_version": 1,
-  "cache": { "hit": false, "key": "<sha256 hex>" },
-  "payload": { /* tool-specific */ }
-}
-```
-
-## V1 launch gates implemented in Phase 1
-
-- **Gate #7 — consensus-call logging.** Every tool invocation appends a JSONL line to `~/.claude/vo-mcp-events.jsonl` (override with `$VO_MCP_EVENTS_PATH`). Schema is locked: see `src/types.ts` `ConsensusCallEvent`. `per_model_verdicts` and `synthesized_verdict` are empty/null in the scaffold; the schema shape is the deliverable.
-- **Gate #8 — content-hash cache.** Every tool invocation computes `sha256(canonicalize(tool_input))`. Repeat calls with the same canonicalized input return the cached envelope with `cache.hit = true`. Backed by sqlite at `~/.claude/vo-mcp-cache.db` (override with `$VO_MCP_DB_PATH`).
-
-## Building & testing
-
-```sh
-cd packages/vo-mcp
-pnpm install
-pnpm run build       # tsc -p tsconfig.json
-pnpm run typecheck   # tsc --noEmit
-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.
-- `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.
-
-## Running the server
-
-The CLI is a stdio MCP server. Don't run it interactively; register it in your MCP client.
-
-### Claude Desktop / Claude Code
-
-Add to `~/.claude/mcp_settings.json` (Claude Desktop) or your Claude Code config:
-
-```jsonc
-{
-  "mcpServers": {
-    "vo": {
-      "command": "node",
-      "args": ["<absolute-path>/packages/vo-mcp/dist/cli.js"],
-      "env": {
-        // Optional overrides — defaults shown below
-        // "VO_MCP_EVENTS_PATH": "/path/to/events.jsonl",
-        // "VO_MCP_DB_PATH": "/path/to/cache.db"
-      }
-    }
-  }
-}
-```
-
-### Cursor
-
-Cursor reads MCP servers from its global config (Settings → Features → MCP). Add an entry:
-
-```jsonc
-{
-  "mcpServers": {
-    "vo": {
-      "command": "node",
-      "args": ["<absolute-path>/packages/vo-mcp/dist/cli.js"]
-    }
-  }
-}
-```
-
-After saving, restart Cursor. The tools appear under the `@vo` namespace in the chat composer's tool picker.
-
-### Continue
-
-Continue reads MCP servers from `~/.continue/config.json` under the `experimental.modelContextProtocolServer` (or v2 `mcpServers`) section, depending on the Continue release on your machine. Verify the current shape against Continue's docs; the launch command itself is the same:
-
-```jsonc
-{
-  "command": "node",
-  "args": ["<absolute-path>/packages/vo-mcp/dist/cli.js"]
-}
-```
-
-> **Cross-vendor smoke.** A captured cross-vendor smoke now exists — see
-> [`CROSS_VENDOR_SMOKE.md`](./CROSS_VENDOR_SMOKE.md). Run `pnpm run smoke:cross-vendor`
-> to drive the built server through the full MCP lifecycle under each vendor's
-> real client parameters (protocol-version negotiation, capabilities, client
-> identity, schema validity) and reproduce the recorded transcripts. That doc
-> also carries the operator checklist for capturing real Cursor/Continue/Codex
-> GUI sessions. The integration test in this package exercises the generic
-> single-version stdio surface that any MCP-spec-compliant client uses.
-
-## Environment variables
-
-| Var | Default | Purpose |
-| --- | --- | --- |
-| `VO_MCP_EVENTS_PATH` | `~/.claude/vo-mcp-events.jsonl` | Where consensus-call event lines are appended. |
-| `VO_MCP_DB_PATH` | `~/.claude/vo-mcp-cache.db` | sqlite cache file for content-hash cache. |
-| `VO_CONTROL_PLANE_URL` | _(unset → cloud off)_ | vo-control-plane base URL. Set together with the admin token to activate **cloud mode** — the admin-proxy tools (concierge dispatch, heal/PR families) forward to vo-control-plane instead of returning `unimplemented` stubs. |
-| `VO_CONTROL_PLANE_ADMIN_TOKEN` | _(unset → cloud off)_ | Bearer token vo-control-plane validates. Required with the URL above; setting only one is a configuration error. |
-| `VO_ADMIN_CALLABLES_READONLY` | `false` | When truthy (`1`/`true`), cloud mode runs **read-only**: read-only tools (concierge dispatch + the list/get diagnostics) forward, but the heal/PR **write** tools (merge, reject, trigger-heal, …) stay gated to their stubs. Lets you expose concierge without exposing destructive admin actions. |
-
-## Adding a new tool (Phase 2+)
-
-1. Create `src/tools/<tool>.ts` exporting:
-   - `TOOL_NAME` constant
-   - `description` (writes the discovery copy that cross-vendor clients show)
-   - `inputSchema` (JSON Schema for MCP `tools/list`)
-   - `handle<Tool>(deps, rawInput)` (validate input, hit cache, call backend, log event, return `jsonContent(envelope)`)
-2. Add it to `buildToolRegistry()` in `src/server.ts`.
-3. Add tests under `test/tools/<tool>.test.ts`.
-4. Update this README's tool table and `EXTRACTION_AUDIT.md`.
-
-The tool handler MUST:
-
-- Hash the canonicalized input via `deps.cache.keyFor(TOOL_NAME, rawInput)`.
-- Read the cache before any expensive work; return cached envelope with `cache.hit = true` if present.
-- Append a `ConsensusCallEvent` via `deps.events.append(buildBaseEvent(...))` on every invocation.
-- Sanitize inputs before logging (`sanitizeExcerpt` is applied automatically in `buildBaseEvent`).
-- Return a `ToolResultEnvelope<TPayload>` JSON-encoded in a single text content block.
-
-## Hard rules (handoff §C)
-
-This package complies with:
-
-1. **Open shell, closed content.** Stub ratchet client lives here; real thresholds load from `@algosuite/ratchets-generic` in Phase 2 (see `EXTRACTION_AUDIT.md`).
-2. **Cross-vendor by design.** No Claude-specific assumptions; tool schemas are MCP-spec compliant.
-3. **Content-hash cache every consensus call.** Implemented at `src/cache/sqlite-cache.ts`.
-4. **Log every consensus call.** Implemented at `src/logging/events-writer.ts`.
-5. **TypeScript strict, zero `any`, zero `@ts-ignore`.**
-6. **No PII in logs.** `sanitizeExcerpt` strips JWTs, sk- keys, bearer tokens, and email addresses before logging.
-
-See `EXTRACTION_AUDIT.md` for what's stub, what's real, and where the moat lives.
+# @algosuite/vo-mcp
+
+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 |
+| --- | --- | --- |
+| `vo_check_assertion_strength` | Implemented (stub ratchet) | Score a test file's assertions 0-100 with per-assertion findings. |
+| `vo_check_hollow_test` | Stub | Detect tests that pass without verifying product truth. |
+| `vo_verify_answer` | Stub | Semantic-equivalence comparison of expected vs observed. |
+| `vo_consensus_judgment` | Stub + logging skeleton | Submit a prompt to multiple models, return synthesized verdict. **Logs every call** (V1 launch gate #7). |
+| `vo_architecture_review` | Stub | Senior-architect review of a diff against project defaults. |
+
+All tools follow the same response envelope:
+
+```jsonc
+{
+  "tool": "vo_check_assertion_strength",
+  "schema_version": 1,
+  "cache": { "hit": false, "key": "<sha256 hex>" },
+  "payload": { /* tool-specific */ }
+}
+```
+
+## V1 launch gates implemented in Phase 1
+
+- **Gate #7 — consensus-call logging.** Every tool invocation appends a JSONL line to `~/.claude/vo-mcp-events.jsonl` (override with `$VO_MCP_EVENTS_PATH`). Schema is locked: see `src/types.ts` `ConsensusCallEvent`. `per_model_verdicts` and `synthesized_verdict` are empty/null in the scaffold; the schema shape is the deliverable.
+- **Gate #8 — content-hash cache.** Every tool invocation computes `sha256(canonicalize(tool_input))`. Repeat calls with the same canonicalized input return the cached envelope with `cache.hit = true`. Backed by sqlite at `~/.claude/vo-mcp-cache.db` (override with `$VO_MCP_DB_PATH`).
+
+## Building & testing
+
+```sh
+cd packages/vo-mcp
+pnpm install
+pnpm run build       # tsc -p tsconfig.json
+pnpm run typecheck   # tsc --noEmit
+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 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.
+
+## Running the server
+
+The CLI is a stdio MCP server. Don't run it interactively; register it in your MCP client.
+
+### Claude Desktop / Claude Code
+
+Add to `~/.claude/mcp_settings.json` (Claude Desktop) or your Claude Code config:
+
+```jsonc
+{
+  "mcpServers": {
+    "vo": {
+      "command": "node",
+      "args": ["<absolute-path>/packages/vo-mcp/dist/cli.js"],
+      "env": {
+        // Optional overrides — defaults shown below
+        // "VO_MCP_EVENTS_PATH": "/path/to/events.jsonl",
+        // "VO_MCP_DB_PATH": "/path/to/cache.db"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Cursor reads MCP servers from its global config (Settings → Features → MCP). Add an entry:
+
+```jsonc
+{
+  "mcpServers": {
+    "vo": {
+      "command": "node",
+      "args": ["<absolute-path>/packages/vo-mcp/dist/cli.js"]
+    }
+  }
+}
+```
+
+After saving, restart Cursor. The tools appear under the `@vo` namespace in the chat composer's tool picker.
+
+### Continue
+
+Continue reads MCP servers from `~/.continue/config.json` under the `experimental.modelContextProtocolServer` (or v2 `mcpServers`) section, depending on the Continue release on your machine. Verify the current shape against Continue's docs; the launch command itself is the same:
+
+```jsonc
+{
+  "command": "node",
+  "args": ["<absolute-path>/packages/vo-mcp/dist/cli.js"]
+}
+```
+
+> **Cross-vendor smoke.** A captured cross-vendor smoke now exists — see
+> [`CROSS_VENDOR_SMOKE.md`](./CROSS_VENDOR_SMOKE.md). Run `pnpm run smoke:cross-vendor`
+> to drive the built server through the full MCP lifecycle under each vendor's
+> real client parameters (protocol-version negotiation, capabilities, client
+> identity, schema validity) and reproduce the recorded transcripts. That doc
+> also carries the operator checklist for capturing real Cursor/Continue/Codex
+> GUI sessions. The integration test in this package exercises the generic
+> single-version stdio surface that any MCP-spec-compliant client uses.
+
+## Environment variables
+
+| Var | Default | Purpose |
+| --- | --- | --- |
+| `VO_MCP_EVENTS_PATH` | `~/.claude/vo-mcp-events.jsonl` | Where consensus-call event lines are appended. |
+| `VO_MCP_DB_PATH` | `~/.claude/vo-mcp-cache.db` | sqlite cache file for content-hash cache. |
+| `VO_CONTROL_PLANE_URL` | _(unset → cloud off)_ | vo-control-plane base URL. Set together with the admin token and tenant ID to activate **cloud mode** — the admin-proxy tools (concierge dispatch, heal/PR families) forward to vo-control-plane instead of returning `unimplemented` stubs. |
+| `VO_CONTROL_PLANE_ADMIN_TOKEN` | _(unset → cloud off)_ | Bearer token vo-control-plane validates. Required with the URL and tenant ID above; setting only some is a configuration error. |
+| `VO_TENANT_ID` | _(unset → cloud off)_ | Tenant UUID. Required with the control-plane URL and admin token above to enable cloud mode. Interactive agents (Claude Code, Cursor, Codex, Continue) auto-allocate their session on first report and appear on the live fleet whiteboard. |
+| `VO_ADMIN_CALLABLES_READONLY` | `false` | When truthy (`1`/`true`), cloud mode runs **read-only**: read-only tools (concierge dispatch + the list/get diagnostics) forward, but the heal/PR **write** tools (merge, reject, trigger-heal, …) stay gated to their stubs. Lets you expose concierge without exposing destructive admin actions. |
+
+## Adding a new tool (Phase 2+)
+
+1. Create `src/tools/<tool>.ts` exporting:
+   - `TOOL_NAME` constant
+   - `description` (writes the discovery copy that cross-vendor clients show)
+   - `inputSchema` (JSON Schema for MCP `tools/list`)
+   - `handle<Tool>(deps, rawInput)` (validate input, hit cache, call backend, log event, return `jsonContent(envelope)`)
+2. Add it to `buildToolRegistry()` in `src/server.ts`.
+3. Add tests under `test/tools/<tool>.test.ts`.
+4. Update this README's tool table and `EXTRACTION_AUDIT.md`.
+
+The tool handler MUST:
+
+- Hash the canonicalized input via `deps.cache.keyFor(TOOL_NAME, rawInput)`.
+- Read the cache before any expensive work; return cached envelope with `cache.hit = true` if present.
+- Append a `ConsensusCallEvent` via `deps.events.append(buildBaseEvent(...))` on every invocation.
+- Sanitize inputs before logging (`sanitizeExcerpt` is applied automatically in `buildBaseEvent`).
+- Return a `ToolResultEnvelope<TPayload>` JSON-encoded in a single text content block.
+
+## Hard rules (handoff §C)
+
+This package complies with:
+
+1. **Open shell, closed content.** Stub ratchet client lives here; real thresholds load from `@algosuite/ratchets-generic` in Phase 2 (see `EXTRACTION_AUDIT.md`).
+2. **Cross-vendor by design.** No Claude-specific assumptions; tool schemas are MCP-spec compliant.
+3. **Content-hash cache every consensus call.** Implemented at `src/cache/sqlite-cache.ts`.
+4. **Log every consensus call.** Implemented at `src/logging/events-writer.ts`.
+5. **TypeScript strict, zero `any`, zero `@ts-ignore`.**
+6. **No PII in logs.** `sanitizeExcerpt` strips JWTs, sk- keys, bearer tokens, and email addresses before logging.
+
+See `EXTRACTION_AUDIT.md` for what's stub, what's real, and where the moat lives.

package/bin/vo-mcp

@@ -1,38 +1,44 @@
-#!/usr/bin/env node
-/**
- * vo-mcp CLI dispatcher.
- *
- * Usage:
- *   vo-mcp                                  # MCP stdio server (default)
- *   vo-mcp install                          # one-command installer
- *   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 --install-autostart       # register runner to start at login
- *   vo-mcp runner --uninstall-autostart     # remove auto-start registration
- */
-
-const command = process.argv[2];
-const subcommand = process.argv[3];
-
-if (command === 'install') {
-  import('../dist/install-cli.js');
-} else if (command === 'login') {
-  import('../dist/login-cli.js');
-} else if (command === 'pair') {
-  import('../dist/pair-cli.js');
-} else if (command === 'set-key') {
-  import('../dist/set-key-cli.js');
-} else if (command === 'runner') {
-  if (subcommand === '--install-autostart') {
-    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/).
-    import('../dist/runner-cli.js');
-  }
-} else {
-  // Default: MCP stdio server
-  import('../dist/cli.js');
-}
+#!/usr/bin/env node
+/**
+ * vo-mcp CLI dispatcher.
+ *
+ * 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                           # supervised agent runner
+ *   vo-mcp runner --install-autostart       # register runner to start at login
+ *   vo-mcp runner --uninstall-autostart     # remove auto-start registration
+ */
+
+const command = process.argv[2];
+const subcommand = process.argv[3];
+
+if (command === 'install') {
+  import('../dist/install-cli.js');
+} else if (command === 'update') {
+  import('../dist/update-cli.js');
+} else if (command === 'login') {
+  import('../dist/login-cli.js');
+} else if (command === 'pair') {
+  import('../dist/pair-cli.js');
+} else if (command === 'set-key') {
+  import('../dist/set-key-cli.js');
+} else if (command === 'runner') {
+  if (subcommand === '--install-autostart') {
+    import('../dist/autostart-cli.js').then((m) => m.installAutostartCli());
+  } else if (subcommand === '--uninstall-autostart') {
+    import('../dist/autostart-cli.js').then((m) => m.uninstallAutostartCli());
+  } 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
+  import('../dist/cli.js');
+}

package/dist/autostart-cli.js

@@ -12,7 +12,16 @@ function installWindowsAutostart(runnerCommand, log, env) {
   const appData = env["APPDATA"] ?? join(homedir(), "AppData", "Roaming");
   const startupDir = join(appData, "Microsoft", "Windows", "Start Menu", "Programs", "Startup");
   mkdirSync(startupDir, { recursive: true });
-  const launcherPath = join(startupDir, "vo-runner.cmd");
+  const launcherPath = join(startupDir, "vo-runner.vbs");
+  const legacyCmdPath = join(startupDir, "vo-runner.cmd");
+  if (existsSync(legacyCmdPath)) {
+    try {
+      unlinkSync(legacyCmdPath);
+      log(`  Removed legacy minimized .cmd launcher: ${legacyCmdPath}`);
+    } catch (error) {
+      log(`\u26A0 Could not remove legacy launcher ${legacyCmdPath} (${error instanceof Error ? error.message : String(error)}); remove it manually to avoid a double start`);
+    }
+  }
   if (existsSync(launcherPath)) {
     const existing = readFileSync(launcherPath, "utf8");
     if (existing.includes("vo-mcp runner")) {
@@ -24,27 +33,31 @@ function installWindowsAutostart(runnerCommand, log, env) {
     copyFileSync(launcherPath, backupPath);
     log(`  Backed up existing launcher to: ${backupPath}`);
   }
-  const launcherContent = `@echo off
-REM Auto-start launcher for vo-mcp runner
-REM Created by vo-mcp autostart installer
-start /min cmd /c "${runnerCommand}"
+  const hiddenCommand = `cmd /c ${runnerCommand} >> "%USERPROFILE%\\.claude\\vo-runner.log" 2>&1`.replace(/"/g, '""');
+  const launcherContent = `' Auto-start launcher for vo-mcp runner
+' Created by vo-mcp autostart installer
+CreateObject("WScript.Shell").Run "${hiddenCommand}", 0, False
 `;
   writeFileSync(launcherPath, launcherContent, "utf8");
   log(`\u2713 Installed Windows auto-start launcher`);
   log(`  Path: ${launcherPath}`);
-  log(`  The runner will start minimized at next login.`);
+  log(`  The runner will start hidden at next login.`);
 }
 function uninstallWindowsAutostart(log, env) {
   const appData = env["APPDATA"] ?? join(homedir(), "AppData", "Roaming");
   const startupDir = join(appData, "Microsoft", "Windows", "Start Menu", "Programs", "Startup");
-  const launcherPath = join(startupDir, "vo-runner.cmd");
-  if (!existsSync(launcherPath)) {
+  const launcherPaths = [join(startupDir, "vo-runner.vbs"), join(startupDir, "vo-runner.cmd")];
+  let removedAny = false;
+  for (const launcherPath of launcherPaths) {
+    if (!existsSync(launcherPath)) continue;
+    unlinkSync(launcherPath);
+    removedAny = true;
+    log(`\u2713 Removed Windows auto-start launcher`);
+    log(`  Path: ${launcherPath}`);
+  }
+  if (!removedAny) {
     log(`\u2713 Auto-start launcher not found (already removed)`);
-    return;
   }
-  unlinkSync(launcherPath);
-  log(`\u2713 Removed Windows auto-start launcher`);
-  log(`  Path: ${launcherPath}`);
 }
 async function installMacAutostart(runnerCommand, log) {
   const launchAgentsDir = join(homedir(), "Library", "LaunchAgents");
@@ -117,6 +130,79 @@ async function uninstallMacAutostart(log) {
   log(`\u2713 Removed launchd plist`);
   log(`  Path: ${plistPath}`);
 }
+async function installLinuxAutostart(runnerCommand, log, env) {
+  const home = env["HOME"]?.trim() || homedir();
+  const unitDir = join(home, ".config", "systemd", "user");
+  mkdirSync(unitDir, { recursive: true });
+  const unitPath = join(unitDir, "vo-runner.service");
+  if (existsSync(unitPath)) {
+    const existing = readFileSync(unitPath, "utf8");
+    if (existing.includes(runnerCommand) || existing.includes("vo-mcp runner")) {
+      log(`\u2713 Auto-start is already configured (systemd user unit)`);
+      log(`  Path: ${unitPath}`);
+      return;
+    }
+    const backupPath = `${unitPath}.backup-${Date.now()}`;
+    copyFileSync(unitPath, backupPath);
+    log(`  Backed up existing unit to: ${backupPath}`);
+  }
+  const logFile = join(home, ".claude", "vo-runner.log");
+  const errFile = join(home, ".claude", "vo-runner-error.log");
+  mkdirSync(join(home, ".claude"), { recursive: true });
+  const unit = `[Unit]
+Description=AlgoHQ Code Runner (vo-mcp)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=/bin/sh -lc '${runnerCommand}'
+Restart=on-failure
+RestartSec=10
+StandardOutput=append:${logFile}
+StandardError=append:${errFile}
+
+[Install]
+WantedBy=default.target
+`;
+  writeFileSync(unitPath, unit, "utf8");
+  log(`\u2713 Installed systemd user unit`);
+  log(`  Path: ${unitPath}`);
+  if (process.env["VITEST"]) {
+    log(`  (test mode: skipping systemctl enable)`);
+    return;
+  }
+  try {
+    const { execSync } = await import("node:child_process");
+    execSync("systemctl --user daemon-reload", { stdio: "ignore" });
+    execSync("systemctl --user enable --now vo-runner.service", { stdio: "ignore" });
+    log(`\u2713 Enabled + started vo-runner.service (starts at login)`);
+    log(`  Logs: ${logFile}`);
+  } catch {
+    log(`\u26A0 Could not enable via systemctl (enable it manually):`);
+    log(`  systemctl --user daemon-reload && systemctl --user enable --now vo-runner.service`);
+  }
+}
+async function uninstallLinuxAutostart(log, env) {
+  const home = env["HOME"]?.trim() || homedir();
+  const unitPath = join(home, ".config", "systemd", "user", "vo-runner.service");
+  if (!existsSync(unitPath)) {
+    log(`\u2713 Auto-start unit not found (already removed)`);
+    return;
+  }
+  if (!process.env["VITEST"]) {
+    try {
+      const { execSync } = await import("node:child_process");
+      execSync("systemctl --user disable --now vo-runner.service", { stdio: "ignore" });
+      log(`\u2713 Disabled + stopped vo-runner.service`);
+    } catch {
+      log(`\u26A0 Could not disable via systemctl (continuing anyway)`);
+    }
+  }
+  unlinkSync(unitPath);
+  log(`\u2713 Removed systemd user unit`);
+  log(`  Path: ${unitPath}`);
+}
 async function installAutostart(opts = {}) {
   const log = opts.log ?? ((m) => console.error(m));
   const env = opts.env ?? process.env;
@@ -126,9 +212,11 @@ async function installAutostart(opts = {}) {
     installWindowsAutostart(runnerCommand, log, env);
   } else if (plat === "darwin") {
     await installMacAutostart(runnerCommand, log);
+  } else if (plat === "linux") {
+    await installLinuxAutostart(runnerCommand, log, env);
   } else {
     log(`\u2717 Auto-start is not supported on platform: ${plat}`);
-    log(`  Supported platforms: win32 (Windows), darwin (macOS)`);
+    log(`  Supported platforms: win32 (Windows), darwin (macOS), linux (Linux)`);
   }
 }
 async function uninstallAutostart(opts = {}) {
@@ -139,9 +227,11 @@ async function uninstallAutostart(opts = {}) {
     uninstallWindowsAutostart(log, env);
   } else if (plat === "darwin") {
     await uninstallMacAutostart(log);
+  } else if (plat === "linux") {
+    await uninstallLinuxAutostart(log, env);
   } else {
     log(`\u2717 Auto-start is not supported on platform: ${plat}`);
-    log(`  Supported platforms: win32 (Windows), darwin (macOS)`);
+    log(`  Supported platforms: win32 (Windows), darwin (macOS), linux (Linux)`);
   }
 }