@retasc/cli 1.47.0 → 1.48.1

package/CHANGELOG.md

@@ -6,6 +6,49 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.48.1 (2026-09-08)
+
+- **RTSC-878** — `retasc doctor` no longer condemns the entry `retasc setup` writes. Its
+  machine-global check dated from RTSC-91, when every top-level `mcpServers.retasc` carried
+  a key or a workspace id and so routed every unbound folder to one org; presence alone was
+  a correct test for that. RTSC-780 then made one global entry mandatory, the keyless `auto`
+  marker, which carries no identity at all, and the check was never taught the difference.
+  Doctor therefore printed `✗ GLOBAL Retasc server registered` at the marker and offered
+  `claude mcp remove -s user retasc` as the fix, which strips Retasc from every folder
+  without a binding of its own. It cost a customer a day.
+- The check now reads the entry's identity: `RETASC_WORKSPACE=auto` with no key resolved is
+  reported as correct and named, so someone who just ran `setup` can see that what it wrote
+  is what belongs there. Every other shape stays illegal, including a keyless entry that
+  names a real `ws_` workspace, which still routes every unbound folder to one binding.
+- The exemption is not granted on the sentinel alone. `parseServerEntry` reads
+  `RETASC_WORKSPACE` before it looks for a key in an `Authorization` header or in
+  `RETASC_MCP_KEY`, so an entry carrying both the `auto` sentinel and a real credential
+  parses as an innocent keyless marker; judging the parse alone would have exempted a live
+  machine-global registration pointing every unbound folder at that key's org. The raw
+  entry is examined too, and anything carrying credential material or a `url` of its own
+  stays illegal whatever its `env` claims.
+
+## 1.48.0 (2026-09-08)
+
+- **RTSC-859** — `retasc key mint --hosted`: a key now says at mint what it is for.
+  `workspace` (the default, and what every bind door says explicitly) expects the local
+  watchdog; `hosted` is for a cloud agent or CI that will never have one.
+
+  Why: a workspace key sent raw to the server with no proxy is two things at once and the
+  server cannot tell which, a hosted agent working as documented or a laptop whose config
+  went stale. Both got the same advice on every claim, run `bind`, which a hosted agent
+  cannot do. With `kind` on the row, a hosted key is told the one true thing (renew your
+  own leases) and shows "no folder (hosted)" on the Agents page as a fact rather than a
+  gap; a workspace key with no runner gets the firm remedy, because for that row it is
+  true. A key that said nothing, which includes every key minted before this and any bare
+  `key mint` since, keeps the old hedged text, since nothing on the row can say which it
+  is. `--hosted` and `--install` are refused together: one wires a local watchdog, the
+  other says there will never be one.
+
+  `retasc mcp install --no-watchdog` is not deprecated (it writes exactly a hosted
+  deployment's config) but now says, once, that a key used that way should be minted
+  `--hosted`.
+
 ## 1.47.0 (2026-09-08)
 
 - **RTSC-864** — `retasc key mint` now prints every remote-key config block a hosted

package/dist/commands/bind.js

@@ -515,6 +515,9 @@ export async function completeWorkspaceSetup(args) {
             projectId: projectId,
             agentName: opts.agent,
             runtime: opts.runtime ?? "claude-code",
+            // RTSC-859 — bind is the folder door, so this is a workspace key, and the row
+            // says so rather than leaving it to the server's default.
+            kind: "workspace",
             // RTSC-810 — named after the FOLDER, the leaf only, exactly as the setup-token
             // door has done since RTSC-532: the Keys list is the folder map (`client-a →
             // ENG`), and the old prefix-plus-"key" name told nobody which folder held it.

package/dist/commands/doctor.js

@@ -1,6 +1,6 @@
 import { loadConfig } from "../config.js";
 import { claudeConfigPath, isNetworkError, readGlobalBinding, readLocalBinding, readShadowedBinding, resolveBinding, sameIdentity, } from "../lib/binding.js";
-import { getBinding } from "../lib/keystore.js";
+import { AUTO_WORKSPACE, getBinding } from "../lib/keystore.js";
 import { gitCommonDir } from "../lib/gitRepo.js";
 import { detectHarnesses } from "../lib/harness.js";
 import { runsOk } from "../lib/launcher.js";
@@ -16,8 +16,9 @@ import { clean } from "../lib/text.js";
 // binding, which teaches people to distrust everything else it says. When both
 // exist, we report the claude-local one (what Claude Code actually runs;
 // local > project) and warn if a shadowed folder marker disagrees. The
-// illegal-global check is presence-based and never prints an all-clear it
-// can't prove (unreadable config ≠ no global server).
+// illegal-global check reads the entry's IDENTITY, not merely its presence
+// (RTSC-878), and never prints an all-clear it can't prove (unreadable config
+// ≠ no global server).
 const ok = (m) => console.log(`  ✓ ${m}`);
 const warn = (m) => console.log(`  ! ${m}`);
 const bad = (m) => console.log(`  ✗ ${m}`);
@@ -48,6 +49,65 @@ export function launcherVerdict(local, probe = runsOk) {
         shown: clean([local.command, ...probeArgs].join(" ")),
     };
 }
+/**
+ * RTSC-878: is the machine-global entry a real registration, or the marker `setup` writes?
+ *
+ * The old rule was presence alone, and it was correct when it was written (RTSC-91): every
+ * top-level `mcpServers.retasc` then carried a key or a workspace id, so any of them routed
+ * every unbound folder on the disk to one org. RTSC-780 changed that world by making ONE
+ * global entry mandatory, the keyless `auto` marker, which carries no identity at all: the
+ * proxy resolves the folder it was spawned in and the org still comes from the folder.
+ *
+ * Doctor kept the old rule and so told people to delete what `retasc setup` had just
+ * installed. Following that advice strips Retasc from every folder without a binding of its
+ * own, and it happened to a real customer before this was fixed.
+ *
+ * The test is the marker's OWN sentinel rather than a shape heuristic: `RETASC_WORKSPACE`
+ * is `auto` and no key resolved from it. Workspace ids are `ws_`-prefixed uuids
+ * (`keystore.ts`), so `auto` can never be one, and an entry naming a real workspace stays
+ * illegal exactly as before.
+ *
+ * The sentinel alone is NOT enough, and this is the trap the exemption has to survive.
+ * `parseServerEntry` reads `RETASC_WORKSPACE` BEFORE it looks for a key in an
+ * `Authorization` header or in `RETASC_MCP_KEY`, so an entry that carries BOTH the `auto`
+ * sentinel and a real credential parses as an innocent keyless marker. That shape is a
+ * live machine-global registration pointing every unbound folder at whatever org its key
+ * names, which is the exact fault this check exists to catch, and it is not theoretical:
+ * `lib/harness.ts` records an agent hand-writing a machine-global entry with an inline key.
+ * So the raw entry is examined too, and anything carrying credential material or its own
+ * endpoint is illegal no matter what its `env` claims.
+ */
+export function globalVerdict(global) {
+    if (global.status === "none")
+        return "clear";
+    if (global.status === "unreadable")
+        return "unreadable";
+    const b = global.binding;
+    if (b && b.workspaceId === AUTO_WORKSPACE && !b.key && isBareMarker(global.raw))
+        return "auto";
+    return "illegal";
+}
+/**
+ * Does the entry as written carry nothing but the `auto` sentinel?
+ *
+ * Deliberately a DENYLIST of credential-bearing and endpoint-bearing fields rather than an
+ * exact-shape match: `setup` may add a field to the marker later (it already grew `env`
+ * once), and an exemption that broke on every such addition would be reverted rather than
+ * updated. What must never be exempt is an entry that can reach a server on its own terms:
+ * a key in `env`, a key in a header, or a `url` of its own.
+ */
+function isBareMarker(raw) {
+    if (!raw || typeof raw !== "object")
+        return false;
+    const e = raw;
+    if (e.url !== undefined)
+        return false;
+    if (e.headers !== undefined)
+        return false;
+    if (e.env && typeof e.env === "object" && e.env.RETASC_MCP_KEY !== undefined)
+        return false;
+    return true;
+}
 /**
  * RTSC-498: macOS is the only platform this CLI is tested on. That was true and written
  * down nowhere, which left someone on Linux or Windows unable to tell their own mistake
@@ -192,22 +252,34 @@ export async function doctorAction() {
     }
     // 2) The safety check: any illegal machine-global Retasc server?
     const global = readGlobalBinding();
-    if (global.status === "none") {
+    // Pulled out once: the verdict below is computed from the same entry, and reading it
+    // through the union again inside a branch loses the `present` narrowing.
+    const entry = global.status === "present" ? global.binding : undefined;
+    const verdict = globalVerdict(global);
+    if (verdict === "clear") {
         ok("no illegal global Retasc server.");
     }
-    else if (global.status === "unreadable") {
+    else if (verdict === "auto") {
+        // RTSC-878: the entry `retasc setup` writes, and the one state doctor used to
+        // condemn. Named rather than passed over in silence: someone who just ran `setup`
+        // should see that the thing it wrote is the thing that is supposed to be there.
+        ok("machine-wide Retasc entry is the keyless `auto` marker `retasc setup` writes;\n" +
+            "    it names no org, so every folder still resolves its own binding.");
+    }
+    else if (verdict === "unreadable") {
         warn("could not parse Claude Code's config — cannot verify there is no global Retasc server\n" +
             "    (a local-scope binding for this folder would be invisible too).");
     }
     else {
         // Name the org it points at when we can: "leaks across orgs" is abstract,
-        // "every unbound folder gets org X" is what makes someone act. Presence
-        // alone is the finding — a keyless entry is still an illegal registration —
-        // and if the network already failed above, don't burn another timeout.
+        // "every unbound folder gets org X" is what makes someone act. A keyless entry
+        // that names a WORKSPACE is still illegal (it routes every unbound folder to that
+        // one binding); only the identity-free `auto` marker above is not. If the network
+        // already failed above, don't burn another timeout.
         let points = "";
-        if (global.binding?.key && !networkDown) {
+        if (entry?.key && !networkDown) {
             try {
-                const b = await resolveBinding(global.binding.url || cfg.mcpUrl, global.binding.key);
+                const b = await resolveBinding(entry.url || cfg.mcpUrl, entry.key);
                 points = ` It points at org "${clean(b.org.name)}".`;
             }
             catch {

package/dist/commands/mcp.js

@@ -267,6 +267,15 @@ export function installMcp(opts) {
         console.log("Two things it does not cover, both safe (they fall back to the normal 30-minute lease timeout): if the proxy stops, renewal stops; and a claim made elsewhere — another terminal, direct HTTP MCP, or a previous proxy before a restart — is renewed by nobody. Heartbeat or checkpoint those yourself.");
         return;
     }
+    // RTSC-859 — this is the direct HTTP form, no watchdog, which is exactly a HOSTED
+    // deployment's shape. It is the correct config for one (RTSC-864 documents it), and it
+    // is NOT deprecated. But the key it wires does not know what it is for unless it was
+    // minted `--hosted`, and a workspace key used this way is told on every claim to go
+    // and wire the watchdog it is deliberately running without. Say so once, here, where
+    // the choice is being made, rather than warning on every claim afterwards.
+    console.log("\nNo watchdog: nothing on a machine will renew this key's claims. If this key runs " +
+        "from a cloud agent or CI, mint it with `retasc key mint --hosted` so Retasc knows " +
+        "and stops advising it to run `bind`; a hosted key is expected to heartbeat itself.");
     const res = tryClaudeCli(opts.url, opts.key, scope);
     if (res.ok) {
         console.log(`✓ Registered MCP server "${SERVER_NAME}" with Claude Code (scope: ${scope}).`);

package/dist/index.js

@@ -365,10 +365,22 @@ key
     .option("--agent <name>", "Agent member name (default: auto, \"{you}'s {runtime}\")")
     .option("--runtime <runtime>", "Label for this agent in the Dash (claude-code | codex | grok | …). Does NOT choose where MCP config is written — `retasc setup` wires every harness on the machine.", "claude-code")
     .option("--name <label>", "Key label")
+    // RTSC-859 — say at mint that this key will never have a local runner. Without it
+    // the server cannot tell a cloud agent working as documented from a laptop whose
+    // config went stale, and hands both the same advice: run `bind`, which a hosted
+    // agent cannot.
+    .option("--hosted", "This key runs somewhere with no local install (a cloud agent, CI): never told to run bind, never mistaken for a stale setup")
     .option("--install", "Also wire the key into your agent via MCP")
     .option("--scope <scope>", "MCP install scope if --install: local | project", "local")
     .action(async (opts) => {
     requireLogin();
+    // RTSC-859 — the two flags contradict each other. `--install` wires a local watchdog;
+    // `--hosted` declares there will never be one. Accepting both produced a row the Dash
+    // labelled "no local watchdog" for a laptop that was running one, silenced its
+    // stale-CLI nudge, and had the proxy's `name_workspace` refused on every start.
+    if (opts.hosted && opts.install) {
+        fail(new Error("--hosted and --install contradict each other: --install wires a local watchdog, --hosted says this key will never have one. Pick one."));
+    }
     try {
         const res = (await api.mintKey({
             orgId: opts.orgId,
@@ -376,6 +388,14 @@ key
             agentName: opts.agent,
             runtime: opts.runtime,
             keyName: opts.name,
+            // RTSC-859 — said only when the caller actually said something. `--hosted` is
+            // the word for a cloud agent or CI. `--install` wires the watchdog right here, so
+            // that key is a workspace key by construction. A BARE `key mint` says nothing:
+            // it is the documented hosted path (RTSC-864, llms.txt) AND the manual-wiring
+            // path, and stamping `workspace` on it sent every cloud agent minted that way a
+            // firm "re-run bind in that folder" for a folder that never existed. Absent keeps
+            // the honest hedge, which is exactly right for a key we know nothing about.
+            ...(opts.hosted ? { kind: "hosted" } : opts.install ? { kind: "workspace" } : {}),
         }));
         console.log(`✓ Minted key: ${res.key}`);
         console.log("  (Shown once — store it now.)");

package/dist/lib/binding.js

@@ -213,7 +213,7 @@ export function readGlobalBinding() {
     const raw = doc?.mcpServers?.retasc;
     if (!raw)
         return { status: "none" };
-    return { status: "present", binding: parseServerEntry(raw, "global") };
+    return { status: "present", binding: parseServerEntry(raw, "global"), raw };
 }
 /** Two per-folder bindings are the SAME binding if they agree on workspace id
  *  (canonical form) or on the literal key (legacy forms). Anything else — or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.47.0",
+  "version": "1.48.1",
   "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": {