@retasc/cli 1.38.1 → 1.39.0

package/CHANGELOG.md

@@ -6,6 +6,46 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.39.0 (2026-08-30)
+
+- **RTSC-793** — `retasc setup` now wires Cursor, OpenCode and Gemini CLI too, bringing it
+  to six harnesses. Until this release those three could be installed and running on your
+  machine and `setup` would say nothing about them: it only ever named harnesses it already
+  knew, so an unsupported one was not reported as skipped, it was invisible, and the receipt
+  read as complete. That is the same silent half-install the previous release existed to end,
+  one harness over.
+  Each was admitted the same way the first three were, by checking a real installation rather
+  than a config format from memory. The check that decides it is whether the harness starts
+  its MCP server in the project directory, because the entry we write names no project and
+  works out the folder for itself; one that started somewhere else would resolve every folder
+  to the same wrong place with no symptom. All three passed.
+  Cursor is wired by editing `~/.cursor/mcp.json` directly, and carefully: that file is named
+  .json but Cursor accepts comments in it, so we splice our entry in textually and leave every
+  comment, every other server and everything else exactly where it was. OpenCode and Gemini
+  are wired through their own `opencode mcp add` and `gemini mcp add`, which is better than a
+  writer of ours when a harness ships one that works: their file format stays their business.
+  Note for Cursor users: it is `cursor-agent`, the agent, that gets the tools. The `cursor`
+  command is the editor launcher and is a different program.
+  Also fixed: the setup receipt could run a path into the word beside it, printing
+  `~/.codex/config.tomlupdated`, which read like a corrupted path in the one place whose job
+  is to say plainly that everything worked.
+
+## 1.38.2 (2026-08-30)
+
+- **RTSC-789** — `bind` keeps this folder's key instead of minting a new one on every run.
+  The guard meant to prevent that (RTSC-262) read the `--org-id`/`--project-id` flags, so it
+  only ever fired for a provisioning script. The canonical `npx @retasc/cli@latest bind`
+  leaves both undefined and could never reach it: pick the same org and the same project
+  from the menu and it minted anyway, leaving the old key live. The check now runs where
+  the target is known, after the pick, so how you got there stops mattering. A different
+  org or project still mints, as it must.
+  A kept key is resolved against the server before it is kept. `bind` clears a binding only
+  when the server answers `UNAUTHORIZED`, so a folder can reach the reuse branch holding a
+  key whose health is unknown: a 5xx, a proxy sign-in page, a refusal whose wording drifts.
+  Keeping one of those would have stranded the folder for good, since `doctor` sends that
+  exact state back to `bind`. It falls back to minting instead, which is the self-healing
+  the old mint-every-run was providing by accident.
+
 ## 1.38.1 (2026-08-28)
 
 - **RTSC-780 follow-up** — `retasc init` now sets a folder up the same way every other

package/dist/commands/bind.js

@@ -99,6 +99,55 @@ export function strandRecoveryHint(args) {
         `but has no project or key yet — re-run to finish:\n` +
         `    retasc bind --org-id ${orgId}`);
 }
+/**
+ * The key this folder should KEEP rather than replace (RTSC-789).
+ *
+ * `bind` used to mint on every run. The guard that was supposed to stop that
+ * (RTSC-262) sat in `preflight` and read `args.orgId && args.projectId`, so it
+ * only fired for `retasc bind --org-id X --project-id Y` — the provisioning-script
+ * path it was written for. The canonical command is a bare `bind`, which leaves
+ * both undefined, so the branch was unreachable for almost every real run: pick
+ * the same org and the same project from the menu and it minted anyway. Fourteen
+ * keys in one org, three of them the same agent on the same project, and the old
+ * ones stay live — two were carrying 89 and 283 sessions.
+ *
+ * So the check moves to where the target is actually KNOWN, after the interactive
+ * pick, and asks the only question that matters: does this folder already hold a
+ * key for this exact (org, project)? Flags are irrelevant to that.
+ *
+ * A DIFFERENT org or project still mints.
+ *
+ * This names a CANDIDATE, not a decision. It reads the keystore and nothing else,
+ * so it cannot know whether the key still works — and "`preflight` already cleared
+ * anything the server refused" is not true enough to lean on: that clearing fires
+ * only on a literal UNAUTHORIZED, and every other failure walks straight past it.
+ * The caller resolves the candidate before keeping it.
+ */
+export function reusableKey(existing, target, read = getBinding) {
+    if (!existing?.workspaceId)
+        return null;
+    const cur = read(existing.workspaceId);
+    if (!cur?.key)
+        return null;
+    return cur.orgId === target.orgId && cur.projectId === target.projectId ? cur.key : null;
+}
+/**
+ * The binding as the AGENT will see it, or null when the server won't confirm it.
+ *
+ * One place, because two callers need the same answer for different reasons: the
+ * receipt prints it, and the reuse decision above depends on it. Every failure is
+ * the same answer here — "the server did not confirm this key" — so the caller
+ * decides what that means rather than parsing an error a second time.
+ */
+async function describeBinding(url, key) {
+    try {
+        const b = await resolveBinding(url, key);
+        return { org: clean(b.org.name), prefix: clean(b.project.prefix), name: b.project.name };
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * "This folder is already bound — replace it?" (RTSC-262/RTSC-91)
  *
@@ -423,14 +472,37 @@ export async function completeWorkspaceSetup(args) {
     const note = launcherNote(launcher);
     if (note)
         console.log(note);
-    // --- mint a key for THIS (org, project) and wire the watchdog into THIS folder
-    const minted = (await api.mintKey({
-        orgId,
-        projectId: projectId,
-        agentName: opts.agent,
-        runtime: opts.runtime ?? "claude-code",
-        keyName: prefix ? `${prefix} key` : undefined,
-    }));
+    // --- keep this folder's key if it already names this (org, project), else mint
+    //
+    // A key is only kept once the SERVER agrees it works. `preflight` clears a binding
+    // only on a literal UNAUTHORIZED, so a folder reaches here holding a key of unknown
+    // health whenever that check failed some other way — a 5xx, a proxy page, a refusal
+    // whose wording drifts off the regex. Keeping such a key silently would strand the
+    // folder permanently: `doctor` tells people in exactly that state to re-run `bind`,
+    // and `bind` is this path, so it would answer "✓ bound" forever and never heal. The
+    // mint-on-every-run this issue removes was doing that healing by accident; it stays,
+    // on purpose, as the fallback.
+    //
+    // The check is not extra work — it IS the receipt's confirmation call, hoisted, and
+    // `bound` carries the answer down to the card. The mint path resolves once below,
+    // exactly as before.
+    const candidate = reusableKey(existing, { orgId, projectId: projectId });
+    let bound = candidate ? await describeBinding(cfg.mcpUrl, candidate) : null;
+    // A key that answers for a DIFFERENT project is not this folder's key, whatever the
+    // keystore says its ids were. Compared only when the target's prefix is known (a
+    // bare --project-id never listed one), because a guess would reject good keys.
+    if (bound && prefix && bound.prefix !== clean(prefix))
+        bound = null;
+    const reused = bound !== null;
+    const minted = reused
+        ? { key: candidate }
+        : (await api.mintKey({
+            orgId,
+            projectId: projectId,
+            agentName: opts.agent,
+            runtime: opts.runtime ?? "claude-code",
+            keyName: prefix ? `${prefix} key` : undefined,
+        }));
     // The key is named in the receipt card below, not here — one mention, in the place
     // that says where it went (RTSC-673).
     // RTSC-92: the secret stays OUT of the repo. Store it in the home keystore
@@ -460,21 +532,24 @@ export async function completeWorkspaceSetup(args) {
     // (RTSC-673). Resolved rather than echoed from what we just sent: this is the last
     // chance to notice a folder bound to something other than what was asked for, and a
     // card built from our own inputs could never show that.
-    let bound = null;
-    try {
-        const b = await resolveBinding(cfg.mcpUrl, minted.key);
-        bound = { org: clean(b.org.name), prefix: clean(b.project.prefix), name: b.project.name };
-    }
-    catch {
-        /* binding written; whoami confirmation is best-effort — fall back to what we sent */
-    }
+    //
+    // A reused key was already resolved above, and that answer is the one that decided to
+    // keep it — so only a freshly minted key is left to confirm. Still best-effort here:
+    // the binding is written and a key we just minted is live by construction, so a
+    // network fault at this point is about the confirmation, not about the key.
+    if (!bound)
+        bound = await describeBinding(cfg.mcpUrl, minted.key);
     const orgLabel = bound?.org ?? clean(args.orgLabel ?? "");
     const pfx = bound?.prefix ?? clean(prefix ?? "");
     console.log("\n" +
         card(`✓ This folder is bound to ${orgLabel} / ${pfx}`, [
             { label: "Org", value: orgLabel },
             { label: "Project", value: bound?.name ? `${pfx} ${DOT} ${bound.name}` : pfx },
-            { label: "Agent key", value: `${minted.key.slice(0, 14)}…`, note: "never leaves ~/.retasc" },
+            {
+                label: "Agent key",
+                value: `${minted.key.slice(0, 14)}…`,
+                note: reused ? "kept, not replaced" : "never leaves ~/.retasc",
+            },
             { label: "MCP wired", value: marker.where, note: "secret-free, safe to commit" },
             ...(wired.wired.length
                 ? [

package/dist/commands/setup.js

@@ -66,8 +66,12 @@ export function runSetup(opts) {
 export function printSetup(r) {
     if (!r.wired.length && !r.failed.length) {
         console.log("No MCP harness found on this machine.");
-        console.log("Install Claude Code, Codex or Grok and run `retasc setup` again, or bind a folder\n" +
-            "with `retasc bind` and paste the config block it prints into your own client.");
+        // Named from the registry rather than a hand-kept list: RTSC-780 shipped three and
+        // RTSC-793 added three more, and a sentence naming only the original three would have
+        // told a Cursor user to install Codex.
+        console.log(`Install one of ${HARNESSES.map((h) => h.label).join(", ")} and run \`retasc setup\` again,\n` +
+            "or bind a folder with `retasc bind` and paste the config block it prints into your\n" +
+            "own client.");
         return;
     }
     console.log("\n" +

package/dist/lib/card.js

@@ -50,8 +50,14 @@ export function card(title, rows, footer) {
         // A note sits in a third column, so the values stay in one scannable rail. Without a
         // note the value simply runs on — padding it anyway would leave a trench of spaces
         // in the middle of the card.
+        //
+        // The value is fitted one column NARROWER than its rail so a gutter always survives.
+        // `fit` pads to exactly VALUE, so a value of exactly that width, or one ellipsed to
+        // it, butted straight against the note: `~/.codex/config.tomlupdated`. It read as a
+        // corrupted path in the one surface whose job is to say calmly that this worked
+        // (RTSC-793 — RTSC-780's three rows all happened to be shorter).
         const body = r.note
-            ? `${fit(r.label, LABEL)}${fit(r.value, VALUE)}${r.note}`
+            ? `${fit(r.label, LABEL)}${fit(r.value, VALUE - 1)} ${r.note}`
             : `${fit(r.label, LABEL)}${r.value}`;
         out.push(line(body));
     }

package/dist/lib/harness.js

@@ -13,10 +13,16 @@
 // with cwd set to the project directory, so the proxy can resolve the folder itself.
 //
 // Adding a harness is one entry in HARNESSES. Deliberately NOT populated from theory:
-// each entry here was checked against a real installation. Cursor, Windsurf, Gemini CLI,
-// OpenCode and VS Code all have a known config shape and belong here, but writing an
-// unverified serializer into somebody's global agent config is not a thing to ship on a
-// guess — they go in as each is confirmed.
+// every entry here was checked against a real installation, and the check that gates
+// admission is the cwd one — a harness whose stdio server does not start in the project
+// directory cannot use the `auto` marker at all, because one global entry would then
+// resolve every folder to the same wrong place, silently.
+//
+// Verified so far: Claude Code, Codex, Grok (RTSC-780), then Cursor, OpenCode and Gemini
+// CLI (RTSC-793), each confirmed by wiring a probe server that logs process.cwd() and
+// running the harness from two different directories. Windsurf and VS Code are NOT
+// candidates: they are editors, not agent harnesses, and were dropped from RTSC-780's
+// original map rather than left sitting in it forever.
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
@@ -147,22 +153,186 @@ function tomlHarness(id, label, path, bin) {
         },
     };
 }
-// --- JSON (./.mcp.json in the folder) ---------------------------------------
-/** Merge the retasc entry into a `{ mcpServers: {…} }` document, leaving every
- *  other server and unknown key byte-for-byte where it was. */
-export function mergeMcpServers(before, entry) {
-    let doc = {};
-    if (before.trim()) {
-        try {
-            doc = JSON.parse(before);
+// --- JSONC (Cursor) ---------------------------------------------------------
+// `~/.cursor/mcp.json` is named .json and is NOT parsed as JSON: cursor-agent reads a
+// file containing `// comments` without complaint (verified against a real install,
+// RTSC-793). So the same rule the TOML splice follows applies here — this is the user's
+// own config, and a JSON.parse/JSON.stringify round-trip would silently delete every
+// comment in it and reflow the rest.
+//
+// Hence a textual splice, and hence the small JSONC scanner below rather than a parser
+// dependency. It only ever has to find one member and replace its value; everything it
+// does not understand it steps over untouched, which is exactly the property we want
+// from something editing a file we did not write.
+/** Step over whitespace and JSONC comments, returning the next index that is neither. */
+function skipTrivia(text, i) {
+    for (;;) {
+        while (i < text.length && /\s/.test(text[i]))
+            i++;
+        if (text.startsWith("//", i)) {
+            const nl = text.indexOf("\n", i);
+            i = nl === -1 ? text.length : nl + 1;
+            continue;
         }
-        catch {
-            doc = {};
+        if (text.startsWith("/*", i)) {
+            const end = text.indexOf("*/", i + 2);
+            i = end === -1 ? text.length : end + 2;
+            continue;
+        }
+        return i;
+    }
+}
+/** `i` points at the opening quote. Returns the index just past the closing quote. */
+function endOfString(text, i) {
+    i++;
+    while (i < text.length) {
+        if (text[i] === "\\")
+            i += 2;
+        else if (text[i] === '"')
+            return i + 1;
+        else
+            i++;
+    }
+    return i;
+}
+/** `i` points at the first character of a value. Returns the index just past it.
+ *  Nesting is tracked so an object value containing commas ends in the right place. */
+function endOfValue(text, i) {
+    i = skipTrivia(text, i);
+    if (text[i] === '"')
+        return endOfString(text, i);
+    if (text[i] === "{" || text[i] === "[") {
+        let depth = 0;
+        while (i < text.length) {
+            const c = text[i];
+            if (c === '"') {
+                i = endOfString(text, i);
+                continue;
+            }
+            if (c === "/" && (text[i + 1] === "/" || text[i + 1] === "*")) {
+                i = skipTrivia(text, i);
+                continue;
+            }
+            if (c === "{" || c === "[")
+                depth++;
+            else if (c === "}" || c === "]") {
+                depth--;
+                if (depth === 0)
+                    return i + 1;
+            }
+            i++;
         }
+        return i;
     }
-    doc.mcpServers = doc.mcpServers ?? {};
-    doc.mcpServers[SERVER_NAME] = entry;
-    return JSON.stringify(doc, null, 2) + "\n";
+    while (i < text.length && !/[,}\]\s]/.test(text[i]))
+        i++;
+    return i;
+}
+/**
+ * The members of the object whose `{` is at `open`, with the span of each value.
+ *
+ * `advance` is load-bearing, not defensive tidiness. `endOfValue` stops AT its
+ * terminator set, so on a character already in that set (a stray `]`) it returns the
+ * index it was handed, and a loop that trusted it would spin forever. That input is not
+ * exotic: this parses a file a human hand-edits, and a dropped bracket is the ordinary
+ * way one gets malformed. `retasc setup` hanging with no output, taking `bind` and the
+ * whole of onboarding with it, is a far worse failure than any misparse — so every path
+ * through this loop moves at least one character, and a document we cannot understand
+ * ends as a document we scanned to the end of.
+ */
+function membersOf(text, open) {
+    const members = [];
+    let i = open + 1;
+    const advance = (next) => (next > i ? next : i + 1);
+    for (;;) {
+        i = skipTrivia(text, i);
+        if (i >= text.length || text[i] === "}")
+            return { members };
+        if (text[i] === ",") {
+            i++;
+            continue;
+        }
+        if (text[i] !== '"') {
+            i = advance(endOfValue(text, i));
+            continue;
+        }
+        const start = i;
+        const keyEnd = endOfString(text, i);
+        const name = text.slice(start + 1, keyEnd - 1);
+        const j = skipTrivia(text, keyEnd);
+        if (text[j] !== ":") {
+            i = advance(keyEnd);
+            continue;
+        }
+        const valueStart = skipTrivia(text, j + 1);
+        const valueEnd = endOfValue(text, valueStart);
+        members.push({ name, start, valueStart, valueEnd });
+        i = advance(valueEnd);
+    }
+}
+/** The first top-level `{`, or -1 if this document has no root object. */
+function rootObject(text) {
+    const i = skipTrivia(text, 0);
+    return text[i] === "{" ? i : -1;
+}
+/**
+ * Put `value` at `mcpServers.<name>`, leaving every comment, every other server and
+ * every unknown key exactly where they were.
+ *
+ * Three cases, in the order they are cheapest to be sure about: no usable document at
+ * all (write a fresh one), a document with no `mcpServers` (insert the whole object),
+ * and a document that already has one (replace our member's value, or insert it).
+ */
+export function spliceJsonServer(text, name, value) {
+    const indent = (s, by) => s.split("\n").join(`\n${by}`);
+    const root = rootObject(text);
+    if (root === -1) {
+        return `{\n  "mcpServers": {\n    ${JSON.stringify(name)}: ${indent(value, "    ")}\n  }\n}\n`;
+    }
+    const { members } = membersOf(text, root);
+    const servers = members.find((m) => m.name === "mcpServers");
+    if (!servers) {
+        const block = `"mcpServers": {\n    ${JSON.stringify(name)}: ${indent(value, "    ")}\n  }`;
+        // A trailing comma is only correct if something follows; an empty root gets neither.
+        const sep = members.length ? ",\n  " : "\n  ";
+        const head = members.length ? text.slice(0, members[0].start) : text.slice(0, root + 1);
+        const tail = members.length ? text.slice(members[0].start) : text.slice(root + 1);
+        return members.length
+            ? `${head}${block}${sep}${tail}`
+            : `${head}${sep}${block}\n${tail}`;
+    }
+    // `mcpServers` present but not an OBJECT. Scanning on would treat the rest of the
+    // document as its members and splice our entry one character into a number or a
+    // string, writing a corrupt file over a config we were handed intact — the one
+    // outcome this whole textual approach exists to prevent. We own this key, and a
+    // non-object here is already meaningless to every harness that reads it, so replace
+    // the value wholesale and leave the rest of the document alone.
+    if (text[servers.valueStart] !== "{") {
+        const fresh = `{\n    ${JSON.stringify(name)}: ${indent(value, "    ")}\n  }`;
+        return text.slice(0, servers.valueStart) + fresh + text.slice(servers.valueEnd);
+    }
+    const inner = membersOf(text, servers.valueStart);
+    const mine = inner.members.find((m) => m.name === name);
+    if (mine) {
+        return text.slice(0, mine.valueStart) + indent(value, "    ") + text.slice(mine.valueEnd);
+    }
+    const at = servers.valueStart + 1;
+    const insert = `\n    ${JSON.stringify(name)}: ${indent(value, "    ")}${inner.members.length ? "," : ""}`;
+    return text.slice(0, at) + insert + text.slice(at);
+}
+/** True when `mcpServers.<name>` is already present — the receipt's "updated" vs "new". */
+export function hasJsonServer(text, name) {
+    const root = rootObject(text);
+    if (root === -1)
+        return false;
+    const servers = membersOf(text, root).members.find((m) => m.name === "mcpServers");
+    if (!servers || text[servers.valueStart] !== "{")
+        return false;
+    return membersOf(text, servers.valueStart).members.some((m) => m.name === name);
+}
+/** Our entry, in the shape Cursor reads: command + args + env. */
+export function jsonServerValue(entry) {
+    return JSON.stringify({ command: entry.command, args: entry.args, env: entry.env }, null, 2);
 }
 // --- Claude Code ------------------------------------------------------------
 /**
@@ -217,11 +387,139 @@ const claudeCode = {
         return { ok: true, path: "Claude Code (user scope)", replaced: had.status === 0 };
     },
 };
+// --- Cursor -----------------------------------------------------------------
+/**
+ * `cursor-agent`, NOT `cursor`.
+ *
+ * They are two different binaries and only one of them is a harness: `cursor` is the
+ * VS Code-style IDE launcher (`--diff`, `--merge`, `--goto`), while `cursor-agent` is
+ * the agent, and `cursor-agent mcp login` names `.cursor/mcp.json` or `~/.cursor/mcp.json`
+ * as where it reads servers from. Detecting on `cursor` would report a harness we had
+ * not wired anything usable into.
+ *
+ * The one adapter here that writes its own file: `cursor-agent mcp` offers login, list,
+ * enable and disable, but no `add`.
+ */
+const cursor = {
+    id: "cursor",
+    label: "Cursor",
+    configPath: () => join(home(), ".cursor", "mcp.json"),
+    detect: () => existsSync(join(home(), ".cursor")) || onPath("cursor-agent"),
+    install(entry) {
+        const p = join(home(), ".cursor", "mcp.json");
+        const before = readIfExists(p);
+        try {
+            writeConfig(p, spliceJsonServer(before, SERVER_NAME, jsonServerValue(entry)));
+        }
+        catch (e) {
+            return { ok: false, reason: String(e?.message ?? e) };
+        }
+        return { ok: true, path: p, replaced: hasJsonServer(before, SERVER_NAME) };
+    },
+};
+// --- harnesses with their own `mcp add` -------------------------------------
+/**
+ * OpenCode and Gemini both ship the thing Claude Code ships and Codex, Grok and Cursor
+ * do not: a supported command for this. Each was checked against a real install
+ * (RTSC-793) for the three properties that decide whether calling it beats writing the
+ * file ourselves, and both have all three: it preserves comments and key order, it
+ * leaves other servers and unknown keys alone, and re-adding the same name REPLACES
+ * rather than failing (so `runSetup` on every bind stays idempotent).
+ *
+ * Given that, shelling out is strictly better than a serializer of ours: their config
+ * format is theirs to change, and a format change breaks our writer silently while
+ * their own command keeps working.
+ *
+ * `replaced` is read from the file rather than from what the command prints, so the
+ * receipt does not depend on anybody's wording staying put.
+ */
+function addCommandHarness(opts) {
+    return {
+        id: opts.id,
+        label: opts.label,
+        configPath: opts.configPath,
+        // Gated on RETASC_HOME for the same reason Claude Code is: this shells out to a
+        // command that resolves the REAL home, so a test home has to stop it at DETECTION.
+        // An undetected harness is never installed into.
+        detect: () => !process.env.RETASC_HOME && onPath(opts.bin),
+        install(entry) {
+            const before = readIfExists(opts.configPath());
+            const r = spawnSync(opts.bin, opts.args(entry), { encoding: "utf8" });
+            if (r.error)
+                return { ok: false, reason: r.error.message };
+            if (r.status !== 0) {
+                const msg = (r.stderr || r.stdout || "").trim().split("\n").pop() || `exited ${r.status}`;
+                return { ok: false, reason: msg };
+            }
+            return {
+                ok: true,
+                path: opts.configPath(),
+                replaced: before.includes(`"${SERVER_NAME}"`),
+            };
+        },
+    };
+}
+/** `~/.config/opencode/`, XDG-aware — OpenCode honours XDG_CONFIG_HOME, so resolving it
+ *  to `~/.config` unconditionally would name the wrong file in the receipt. */
+function opencodeConfig() {
+    const xdg = process.env.XDG_CONFIG_HOME || join(home(), ".config");
+    return join(xdg, "opencode", "opencode.jsonc");
+}
+/**
+ * `opencode mcp add <name> --env K=V -- <command> <args...>`.
+ *
+ * The `--` is required: without a URL or a command after it, `add` refuses. Note the
+ * stored shape is unlike every other harness here — the key is `mcp` rather than
+ * `mcpServers`, it carries `"type": "local"`, `command` is ONE array of command plus
+ * args, and env is spelled `environment`. A generic mcpServers writer would produce a
+ * file OpenCode ignores, which is the other half of why this one shells out.
+ */
+const opencode = addCommandHarness({
+    id: "opencode",
+    label: "OpenCode",
+    bin: "opencode",
+    configPath: opencodeConfig,
+    args: (entry) => [
+        "mcp", "add", SERVER_NAME,
+        ...Object.entries(entry.env).flatMap(([k, v]) => ["--env", `${k}=${v}`]),
+        "--", entry.command, ...entry.args,
+    ],
+});
+/**
+ * `gemini mcp add -s user -t stdio -e K=V <name> <command> <args...>`.
+ *
+ * Scope `user`, for the reason the whole marker exists: one entry, correct in every
+ * folder. The default is `project`, which would write a `.gemini/` into whichever
+ * directory `retasc setup` happened to run in.
+ *
+ * Two Gemini quirks, neither ours to fix but both worth knowing before someone reports
+ * them as our bug. `gemini mcp list` reports a freshly added server as `Disabled` and
+ * `gemini mcp enable <name>` answers `Server not found` for it — yet the server does
+ * start and connect on a real run, so `list` is not a verification signal. And Gemini
+ * gates on trusted folders: in an untrusted directory it refuses to start and NO MCP
+ * server loads, which looks exactly like a failed install.
+ */
+const gemini = addCommandHarness({
+    id: "gemini",
+    label: "Gemini CLI",
+    bin: "gemini",
+    configPath: () => join(home(), ".gemini", "settings.json"),
+    args: (entry) => [
+        "mcp", "add",
+        "-s", "user",
+        "-t", "stdio",
+        ...Object.entries(entry.env).flatMap(([k, v]) => ["-e", `${k}=${v}`]),
+        SERVER_NAME, entry.command, ...entry.args,
+    ],
+});
 // --- the registry -----------------------------------------------------------
 export const HARNESSES = [
     claudeCode,
     tomlHarness("codex", "Codex", () => join(home(), ".codex", "config.toml"), "codex"),
     tomlHarness("grok", "Grok", () => join(home(), ".grok", "config.toml"), "grok"),
+    cursor,
+    opencode,
+    gemini,
 ];
 /** Every harness actually present on this machine. */
 export function detectHarnesses(list = HARNESSES) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.38.1",
+  "version": "1.39.0",
   "description": "Retasc CLI — the issue tracker AI agents pull work from. Sign in with GitHub or Google, create projects, mint agent API keys, and wire your agent to the Retasc MCP server in one command.",
   "type": "module",
   "bin": {