@synaplink/orqlaude 0.5.1 → 0.5.5

package/README.md

@@ -44,20 +44,55 @@ orqlaude is the thin layer that adds those things. It never spawns processes its
 npm install -g @synaplink/orqlaude   # CLI + MCP server
 ```
 
-In your project, add to `.mcp.json` (or copy `.mcp.json.template`):
+Then wire it into Claude Desktop's MCP config in one command:
+
+```sh
+cd /path/to/your/project
+orql setup
+```
+
+`orql setup` **patches** Claude Desktop's `claude_desktop_config.json` in place — adds an `orqlaude` MCP server entry pointed at this project's state dir, and **preserves every other server you have configured** (lm-studio, etc.) plus the entire `preferences` block. Writes a timestamped `.bak` before changing anything. Re-runs are idempotent — if the entry is already correct, it reports `already correct; nothing to do` and exits without touching the file.
+
+Flags:
+- `--state-dir <path>` override the default (which walks up from cwd for a `.git`)
+- `--config-path <path>` override Claude Desktop's config path
+- `--yes` skip prompts
+
+Fully quit and relaunch Claude Desktop after running. The `mcp__orqlaude__*` tools will then appear in your sessions.
+
+If you'd rather edit the config yourself, the entry should look like:
 
 ```json
 {
   "mcpServers": {
     "orqlaude": {
       "command": "npx",
-      "args": ["-y", "@synaplink/orqlaude"]
+      "args": ["-y", "-p", "@synaplink/orqlaude", "orqlaude-mcp"],
+      "env": {
+        "ORQLAUDE_STATE_DIR": "/absolute/path/to/your/project/.orqlaude"
+      }
     }
   }
 }
 ```
 
-Restart your Claude Code session. The `mcp__orqlaude__*` tools will appear.
+The `ORQLAUDE_STATE_DIR` env var is important — it pins state to a specific path so the MCP server (running with `cwd=/` on some hosts) and the Telegram bot (running in your project) share the same state file.
+
+## Spawning Agnets: which tool to use
+
+orqlaude itself doesn't spawn processes — it returns prompts and lets the orchestrator pick a spawn tool. Use them in this priority order:
+
+| Priority | Tool | Isolation | Visibility | When to use |
+|---|---|---|---|---|
+| **1** | `mcp__ccd_session__spawn_task` | git worktree per Agnet | Claude Desktop Code sidebar | **Default.** Worktree-isolated, sandbox-clean, the Agnet shows up as its own session you can switch into. |
+| 2 | Host's `Agent` tool (Claude Code built-in) | none — shares your cwd | tool-use only, not a separate session | Faster, no chip-click. **Loses worktree isolation** — Agnets may race on shared files. `claim_files` from the broker is your only collision signal. |
+| 3 | Shell out `claude -p --worktree …` | explicit `--worktree` flag | JSONL on disk — not in sidebar until Desktop restart | Headless / cron / non-Desktop hosts. |
+
+`next_task` returns a `spawn_strategies[]` array with ready-to-call args for each option, so the orchestrator can pick deliberately. **Picking by habit is the most common way to bypass orqlaude's isolation guarantees** — check the returned strategies and make a conscious choice.
+
+### Orphan detection
+
+If an Agnet is dispatched but doesn't call `mcp__orqlaude__checkin` within 60 s, `status()` flags it in `orphan_alerts[]`. Common cause: the orchestrator used a non-`ccd_session__spawn_task` path and the Agnet skipped (or never reached) the protocol footer that tells it to register.
 
 ## Tool reference
 
@@ -116,13 +151,13 @@ Without a running `orqlaude tg start`, `notify_user` queues silently, `request_u
 
 #### Streaming transport
 
-orqlaude streams via Telegram's `sendMessageDraft` endpoint (the native streaming preview API, intended for agent output). Drafts are ephemeral (~30s) and updates that share the same `draft_id` are animated client-side. When a stream ends, orqlaude follows up with a `sendMessage` to persist the final content as a normal chat message with a `✓` marker.
+orqlaude streams by opening a single Telegram message with `sendMessage`, then calling `editMessageText` on each append. The final `stream_to_user_end` does one more edit appending a `✓` marker.
 
-If the bot's Telegram server doesn't yet expose `sendMessageDraft` (older deployments), orqlaude falls back to a single `sendMessage` + repeated `editMessageText` per stream. The fallback is transparent — you don't need to do anything; the notifier flips a `transport: "edit"` flag on the stream and continues.
+(v0.5.1 briefly used `sendMessageDraft` for animated, ephemeral previews — reverted in v0.5.4 after that endpoint proved unreliable in the standard Bot API.)
 
 Limits to know:
 - A Telegram message tops out at 4096 chars. orqlaude caps stream content at 3800 to leave room for the title + completion marker; further appends are silently truncated.
-- The draft path throttles at 400 ms between updates per stream; the edit fallback throttles at 1.5 s (matching the Bot API rate limit for `editMessageText`).
+- Edits are rate-limited (~1/sec per message); orqlaude throttles to 1.5 s between edits per stream.
 - If you need to stream more than 4 kb of output, start a new stream when you're approaching the cap.
 
 ### Health
@@ -191,13 +226,15 @@ False positives are acceptable here — we surface concerns, we don't auto-kill.
 
 ## CLI
 
+Two binaries are installed: `orqlaude` and the short alias `orql`. Use whichever feels right.
+
 ```sh
-orqlaude list                   # every plan in this project
-orqlaude status <plan_id>       # refreshed status of one plan
-orqlaude show <plan_id>         # raw plan JSON
-orqlaude history --limit 50     # tail audit log
-orqlaude where                  # show resolved state dir
-orqlaude help
+orql list                       # every plan in this project
+orql status <plan_id>           # refreshed status of one plan
+orql show <plan_id>             # raw plan JSON
+orql history --limit 50         # tail audit log
+orql where                      # show resolved state dir
+orql help
 ```
 
 Read-only. For active orchestration, use the MCP from inside Claude Code.

package/dist/__tests__/desktop_config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/desktop_config.test.js

@@ -0,0 +1,110 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { planPatch, buildOrqlaudeEntry, readDesktopConfig, writeDesktopConfigAtomic, findDesktopConfigPath, } from "../lib/desktop_config.js";
+/** v0.5.5: regression tests for the desktop_config patcher. */
+const STATE_DIR = "/Users/matthew/Documents/orqlaude/.orqlaude";
+test("planPatch with no existing config creates one + adds orqlaude entry", () => {
+    const result = planPatch(null, STATE_DIR);
+    assert.equal(result.action, "create-config");
+    assert.equal(result.before, null);
+    assert.equal(result.after.command, "npx");
+    assert.deepEqual(result.after.args, ["-y", "-p", "@synaplink/orqlaude", "orqlaude-mcp"]);
+    assert.equal(result.after.env?.ORQLAUDE_STATE_DIR, STATE_DIR);
+});
+test("planPatch with existing config but no orqlaude key adds it without touching others", () => {
+    const existing = {
+        mcpServers: {
+            "lm-studio": {
+                command: "npx",
+                args: ["-y", "@mzxrai/mcp-openai"],
+                env: { OPENAI_API_KEY: "lm-studio" },
+            },
+        },
+        preferences: { someFlag: true },
+    };
+    const result = planPatch(existing, STATE_DIR);
+    assert.equal(result.action, "create-server");
+    // Original is preserved
+    assert.deepEqual(result.config.mcpServers["lm-studio"], existing.mcpServers["lm-studio"]);
+    assert.deepEqual(result.config.preferences, { someFlag: true });
+    // New entry present
+    assert.equal(result.config.mcpServers["orqlaude"].env?.ORQLAUDE_STATE_DIR, STATE_DIR);
+});
+test("planPatch with correct orqlaude entry already present → noop", () => {
+    const existing = {
+        mcpServers: { orqlaude: buildOrqlaudeEntry(STATE_DIR) },
+    };
+    const result = planPatch(existing, STATE_DIR);
+    assert.equal(result.action, "noop");
+});
+test("planPatch with orqlaude entry at wrong state dir → update; preserve other env keys", () => {
+    const existing = {
+        mcpServers: {
+            orqlaude: {
+                command: "npx",
+                args: ["-y", "-p", "@synaplink/orqlaude", "orqlaude-mcp"],
+                env: { ORQLAUDE_STATE_DIR: "/old/path", CUSTOM_DEBUG_FLAG: "1" },
+            },
+        },
+    };
+    const result = planPatch(existing, STATE_DIR);
+    assert.equal(result.action, "update-server");
+    // New state dir applied
+    assert.equal(result.after.env?.ORQLAUDE_STATE_DIR, STATE_DIR);
+    // Custom env key preserved
+    assert.equal(result.after.env?.CUSTOM_DEBUG_FLAG, "1");
+});
+test("planPatch preserves top-level keys we don't recognize", () => {
+    const existing = {
+        mcpServers: {},
+        preferences: { x: 1 },
+        futureField: { whatever: true },
+    };
+    const result = planPatch(existing, STATE_DIR);
+    assert.equal(result.action, "create-server");
+    assert.deepEqual(result.config.preferences, { x: 1 });
+    assert.deepEqual(result.config.futureField, { whatever: true });
+});
+test("writeDesktopConfigAtomic creates a timestamped backup when the file exists", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "orqlaude-desktop-"));
+    const filePath = path.join(dir, "config.json");
+    await fs.writeFile(filePath, JSON.stringify({ original: true }, null, 2));
+    const { backupPath } = await writeDesktopConfigAtomic(filePath, { updated: true });
+    assert.ok(backupPath, "expected a backup path");
+    const backed = JSON.parse(await fs.readFile(backupPath, "utf8"));
+    assert.deepEqual(backed, { original: true });
+    const updated = JSON.parse(await fs.readFile(filePath, "utf8"));
+    assert.deepEqual(updated, { updated: true });
+});
+test("writeDesktopConfigAtomic creates parent dirs + no backup on fresh file", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "orqlaude-desktop-"));
+    const filePath = path.join(dir, "nested", "deep", "config.json");
+    const { backupPath } = await writeDesktopConfigAtomic(filePath, { fresh: true });
+    assert.equal(backupPath, null);
+    const got = JSON.parse(await fs.readFile(filePath, "utf8"));
+    assert.deepEqual(got, { fresh: true });
+});
+test("readDesktopConfig returns null for missing files; throws on malformed JSON", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "orqlaude-desktop-"));
+    const filePath = path.join(dir, "config.json");
+    assert.equal(await readDesktopConfig(filePath), null);
+    await fs.writeFile(filePath, "{ not valid json,,,");
+    await assert.rejects(() => readDesktopConfig(filePath), /Failed to parse/);
+});
+test("findDesktopConfigPath returns a platform-appropriate path", () => {
+    const p = findDesktopConfigPath();
+    assert.ok(p.endsWith("claude_desktop_config.json"), `got: ${p}`);
+    if (process.platform === "darwin") {
+        assert.ok(p.includes("Library/Application Support/Claude"), `got: ${p}`);
+    }
+    else if (process.platform === "win32") {
+        assert.ok(p.includes("Claude"), `got: ${p}`);
+    }
+    else {
+        assert.ok(p.includes(".config/Claude"), `got: ${p}`);
+    }
+});
+//# sourceMappingURL=desktop_config.test.js.map

package/dist/__tests__/desktop_config.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"desktop_config.test.js","sourceRoot":"","sources":["../../src/__tests__/desktop_config.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/v05.test.js

@@ -72,9 +72,13 @@ test("v0.5 schema: newPlan initializes userStreams empty", async () => {
     });
     assert.deepEqual(plan.userStreams, []);
 });
-test("TelegramApi.sendMessageDraft rejects draft_id=0 (v0.5.1)", async () => {
+test("TelegramApi has the expected post-v0.5.4 surface", async () => {
+    // v0.5.4 removed sendMessageDraft after sendMessage proved unreliable in
+    // the standard Bot API. Confirm it's no longer exported.
     const { TelegramApi } = await import("../telegram/api.js");
     const api = new TelegramApi("test:token");
-    await assert.rejects(() => api.sendMessageDraft(123, 0, "hi"), /must be a non-zero integer/);
+    assert.equal(typeof api.sendMessage, "function");
+    assert.equal(typeof api.editMessageText, "function");
+    assert.equal(api.sendMessageDraft, undefined);
 });
 //# sourceMappingURL=v05.test.js.map

package/dist/__tests__/v05.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"v05.test.js","sourceRoot":"","sources":["../../src/__tests__/v05.test.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"v05.test.js","sourceRoot":"","sources":["../../src/__tests__/v05.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/v052.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/v052.test.js

@@ -0,0 +1,53 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { StateStore, newPlan, findPlan } from "../lib/state.js";
+/** v0.5.2: orphan detection on dispatched-but-unregistered Agnets. */
+async function tmpStore() {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "orqlaude-v052-"));
+    return { store: new StateStore(dir), dir };
+}
+test("orphan: task dispatched > 60s ago with no spawnedSessionId is detectable", async () => {
+    const { store } = await tmpStore();
+    let planId = "";
+    await store.update((s) => {
+        const p = newPlan("root", 100_000, [
+            { title: "T1", prompt: "p", tldr: "tl" },
+            { title: "T2", prompt: "p", tldr: "tl" },
+        ]);
+        p.tasks[0].status = "dispatched";
+        p.tasks[0].startedAt = Date.now() - 120_000; // 2 min ago
+        // Task 1 has no spawnedSessionId — orphan.
+        p.tasks[1].status = "dispatched";
+        p.tasks[1].startedAt = Date.now() - 30_000; // 30s ago, NOT orphan yet
+        p.tasks[1].spawnedSessionId = "registered";
+        planId = p.id;
+        s.plans[p.id] = p;
+    });
+    const plan = await store.read((s) => findPlan(s, planId));
+    const ORPHAN_MS = 60_000;
+    const orphans = plan.tasks.filter((t) => t.status === "dispatched" &&
+        !t.spawnedSessionId &&
+        t.startedAt &&
+        Date.now() - t.startedAt > ORPHAN_MS);
+    assert.equal(orphans.length, 1);
+    assert.equal(orphans[0].title, "T1");
+});
+test("orphan: dispatched < 60s ago is NOT yet an orphan", async () => {
+    const { store } = await tmpStore();
+    await store.update((s) => {
+        const p = newPlan("root", 100_000, [{ title: "T", prompt: "p", tldr: "tl" }]);
+        p.tasks[0].status = "dispatched";
+        p.tasks[0].startedAt = Date.now() - 10_000; // 10s ago
+        s.plans[p.id] = p;
+    });
+    const plan = await store.read((s) => Object.values(s.plans)[0]);
+    const orphans = plan.tasks.filter((t) => t.status === "dispatched" &&
+        !t.spawnedSessionId &&
+        t.startedAt &&
+        Date.now() - t.startedAt > 60_000);
+    assert.equal(orphans.length, 0);
+});
+//# sourceMappingURL=v052.test.js.map

package/dist/__tests__/v052.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"v052.test.js","sourceRoot":"","sources":["../../src/__tests__/v052.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/v053.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/v053.test.js

@@ -0,0 +1,89 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { StateStore, newPlan, planForSession, unclaimedTaskById } from "../lib/state.js";
+/**
+ * v0.5.3: regression tests for checkin conflict detection. We test the
+ * underlying state lookup primitives rather than the MCP tool itself —
+ * the conflict-detection branches in broker.ts use exactly these helpers.
+ */
+async function tmpStore() {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "orqlaude-v053-"));
+    return new StateStore(dir);
+}
+test("v0.5.3: session bound to task A cannot be retargeted by passing task B's id", async () => {
+    const store = await tmpStore();
+    let planId = "";
+    let taskAId = "";
+    let taskBId = "";
+    await store.update((s) => {
+        const p = newPlan("root", 100_000, [
+            { title: "A", prompt: "a", tldr: "a" },
+            { title: "B", prompt: "b", tldr: "b" },
+        ]);
+        p.tasks[0].status = "dispatched";
+        p.tasks[0].spawnedSessionId = "session-X";
+        p.tasks[1].status = "dispatched";
+        planId = p.id;
+        taskAId = p.tasks[0].id;
+        taskBId = p.tasks[1].id;
+        s.plans[p.id] = p;
+    });
+    // Caller session X is already bound to task A. If they pass task_id=B,
+    // planForSession should return A — not silently switch them to B.
+    const result = await store.read((state) => {
+        const found = planForSession(state, "session-X");
+        return found ? { taskId: found.task.id, title: found.task.title } : null;
+    });
+    assert.ok(result, "session should be found");
+    assert.equal(result.taskId, taskAId);
+    assert.notEqual(result.taskId, taskBId);
+});
+test("v0.5.3: task already claimed by another session cannot be re-claimed via task_id", async () => {
+    const store = await tmpStore();
+    let taskId = "";
+    await store.update((s) => {
+        const p = newPlan("root", 100_000, [{ title: "T", prompt: "p", tldr: "tl" }]);
+        p.tasks[0].status = "running";
+        p.tasks[0].spawnedSessionId = "first-session";
+        taskId = p.tasks[0].id;
+        s.plans[p.id] = p;
+    });
+    // A different session calls checkin with that task_id.
+    // unclaimedTaskById should return undefined because the task IS claimed.
+    const target = await store.read((state) => unclaimedTaskById(state, taskId));
+    assert.equal(target, undefined);
+});
+test("v0.5.3: spawn_cli util discovers git root via .git directory", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "orqlaude-git-root-"));
+    await fs.mkdir(path.join(dir, ".git"));
+    await fs.mkdir(path.join(dir, "nested", "deeper"), { recursive: true });
+    const { findGitRoot } = await import("../lib/spawn_cli.js");
+    const real = await fs.realpath(dir);
+    assert.equal(findGitRoot(path.join(real, "nested", "deeper")), real);
+});
+test("v0.5.3: telegram_status returns 'unconfigured' when no config file exists", async () => {
+    const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "orqlaude-tg-status-"));
+    const { probeTelegramStatus } = await import("../lib/telegram_status.js");
+    // Override HOME so it can't find a real config.
+    const realHome = process.env.HOME;
+    const fakeHome = await fs.mkdtemp(path.join(os.tmpdir(), "orqlaude-fakehome-"));
+    process.env.HOME = fakeHome;
+    try {
+        const status = await probeTelegramStatus(stateDir);
+        // We can't be certain the user has no real config — but the path under
+        // a freshly-minted fake HOME doesn't exist, so status should be
+        // unconfigured.
+        assert.equal(status.status, "unconfigured");
+        assert.equal(status.hasToken, false);
+    }
+    finally {
+        if (realHome)
+            process.env.HOME = realHome;
+        else
+            delete process.env.HOME;
+    }
+});
+//# sourceMappingURL=v053.test.js.map

package/dist/__tests__/v053.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"v053.test.js","sourceRoot":"","sources":["../../src/__tests__/v053.test.ts"],"names":[],"mappings":"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"}

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import path from "node:path";
 import readline from "node:readline/promises";
 import { stdin, stdout } from "node:process";
 import { StateStore } from "./lib/state.js";
@@ -10,6 +11,8 @@ import { runBot } from "./telegram/bot.js";
 import { resolveStateDir } from "./lib/state_dir.js";
 import { style, styleStatus, banner } from "./lib/style.js";
 import { agnetLabel } from "./lib/agnet.js";
+import { findDesktopConfigPath, readDesktopConfig, planPatch, writeDesktopConfigAtomic, } from "./lib/desktop_config.js";
+import { existsSync } from "node:fs";
 /**
  * orqlaude CLI — read-only inspection of state + audit log + Telegram setup
  * and run.
@@ -40,6 +43,8 @@ async function main() {
             return await cmdHistory(parseLimit(rest));
         case "where":
             return cmdWhere();
+        case "setup":
+            return await cmdSetup(rest);
         case "tg":
             return await cmdTg(rest);
         default:
@@ -51,6 +56,10 @@ async function main() {
 function printHelp() {
     console.log(banner());
     console.log("");
+    console.log(style.bold(style.cream("Setup")));
+    console.log(`  ${style.coral("orql setup")} ${style.sand("[--state-dir PATH] [--yes]")}`);
+    console.log(`                                  Wire orqlaude into Claude Desktop's MCP config (idempotent, preserves other servers)`);
+    console.log("");
     console.log(style.bold(style.cream("Inspection")));
     console.log(`  ${style.coral("orqlaude list")}                   List every plan in this project`);
     console.log(`  ${style.coral("orqlaude status")} ${style.sand("<plan_id>")}       Refreshed status of one plan`);
@@ -154,6 +163,115 @@ async function cmdShow(planId) {
         return 1;
     }
 }
+// ---- setup -----------------------------------------------------------------
+/**
+ * Detect a sensible default state dir for the current shell. Walks up from
+ * cwd for a `.git`; falls back to cwd.
+ */
+function defaultStateDir() {
+    let dir = process.cwd();
+    for (let i = 0; i < 10; i++) {
+        if (existsSync(path.join(dir, ".git"))) {
+            return path.join(dir, ".orqlaude");
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return path.join(process.cwd(), ".orqlaude");
+}
+async function cmdSetup(args) {
+    console.log(banner());
+    console.log("");
+    console.log(style.bold(style.cream("Setup")));
+    console.log("Wires orqlaude into Claude Desktop's MCP config.");
+    console.log("");
+    // Parse flags
+    const stateDirIdx = args.indexOf("--state-dir");
+    const overrideStateDir = stateDirIdx !== -1 ? args[stateDirIdx + 1] : null;
+    const yes = args.includes("--yes") || args.includes("-y");
+    const configPathIdx = args.indexOf("--config-path");
+    const configPath = configPathIdx !== -1 ? args[configPathIdx + 1] : findDesktopConfigPath();
+    console.log(`  ${style.sand("config:")}    ${configPath}`);
+    // 1. Read existing config (preserve everything we don't own).
+    let existing;
+    try {
+        existing = await readDesktopConfig(configPath);
+    }
+    catch (err) {
+        console.error("");
+        console.error(style.crimson(`✗ ${err.message}`));
+        return 1;
+    }
+    if (!existing) {
+        console.log(`  ${style.sand("status:")}    ${style.crimson("config file does not exist — will create")}`);
+    }
+    else {
+        const otherServerCount = Object.keys(existing.mcpServers ?? {}).filter((k) => k !== "orqlaude").length;
+        const orqEntry = existing.mcpServers?.orqlaude;
+        const has = orqEntry ? style.coral("orqlaude entry present") : style.sand("no orqlaude entry yet");
+        console.log(`  ${style.sand("status:")}    ${has}, ${otherServerCount} other server(s) preserved`);
+    }
+    // 2. Pick state dir.
+    let stateDir = overrideStateDir;
+    if (!stateDir) {
+        const suggested = defaultStateDir();
+        if (yes) {
+            stateDir = suggested;
+        }
+        else {
+            const rl = readline.createInterface({ input: stdin, output: stdout });
+            const answer = (await rl.question(`\n  ${style.coral("?")} state dir (where plans/audit live) [${suggested}]: `)).trim();
+            rl.close();
+            stateDir = answer || suggested;
+        }
+    }
+    stateDir = path.resolve(stateDir);
+    // 3. Compute patch.
+    const plan = planPatch(existing, stateDir);
+    console.log("");
+    console.log(style.bold(style.cream("Plan")));
+    switch (plan.action) {
+        case "noop":
+            console.log(`  ${style.coral("✓")} already correct; nothing to do`);
+            return 0;
+        case "create-config":
+            console.log(`  ${style.coral("→")} create ${configPath} with one server (orqlaude → ${stateDir})`);
+            break;
+        case "create-server":
+            console.log(`  ${style.coral("→")} add orqlaude entry (→ ${stateDir}); preserve existing servers + preferences`);
+            break;
+        case "update-server":
+            console.log(`  ${style.coral("→")} update orqlaude entry`);
+            console.log(`        ${style.sand("before:")}  ${JSON.stringify(plan.before)}`);
+            console.log(`        ${style.sand("after:")}   ${JSON.stringify(plan.after)}`);
+            break;
+    }
+    // 4. Confirm + write.
+    if (!yes) {
+        const rl2 = readline.createInterface({ input: stdin, output: stdout });
+        const ans = (await rl2.question(`\n  ${style.coral("?")} apply? [Y/n] `)).trim().toLowerCase();
+        rl2.close();
+        if (ans && ans !== "y" && ans !== "yes") {
+            console.log(style.crimson("  ✗ cancelled"));
+            return 1;
+        }
+    }
+    const { backupPath } = await writeDesktopConfigAtomic(configPath, plan.config);
+    console.log("");
+    console.log(style.bold(style.coral("Done.")));
+    console.log(`  ${style.sand("config:")}    ${configPath}`);
+    if (backupPath)
+        console.log(`  ${style.sand("backup:")}    ${backupPath}`);
+    console.log(`  ${style.sand("state dir:")} ${stateDir}`);
+    console.log("");
+    console.log(style.dim("Next steps:"));
+    console.log(style.dim("  1. Fully quit Claude Desktop (Cmd-Q on macOS) and relaunch."));
+    console.log(style.dim("  2. Open a session in this project. Call `mcp__orqlaude__ping` — it should report state_dir_source:'env'."));
+    console.log(style.dim("  3. (Optional) Set up the Telegram bot: `orql tg setup`."));
+    return 0;
+}
 function cmdWhere() {
     console.log(banner());
     console.log("");