@retasc/cli 1.46.0 → 1.48.0

package/CHANGELOG.md

@@ -6,6 +6,50 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 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
+  agent can paste, including the TOML one that did not exist.
+
+  A key is shown once, and until now that was all `key mint` printed. Anyone wiring a
+  host that cannot run our proxy (a claude.ai connector, Codex Cloud, CI) had to invent
+  the config, and for two of the six harnesses it was not inventable: `tomlBlock` emitted
+  only the stdio proxy shape, so Codex and Grok users had nothing correct to paste at all.
+  The new `tomlHttpBlock` fills that in, and all three blocks now print next to the key
+  while it is still on the screen.
+
+  The two TOML dialects are separate on purpose, and the reason is the dangerous part.
+  Verified against both real binaries: Codex reads `[mcp_servers.retasc.http_headers]`
+  and Grok reads `[mcp_servers.retasc.headers]`, and each loads the other's file without
+  a warning while ignoring the header. The result is a server that reports itself
+  enabled and configured, and returns UNAUTHORIZED on the first tool call.
+
+  The blocks also say, next to themselves, that a key belongs in a user-scope config or
+  a platform secret store and never in a tracked `.mcp.json`, which the repo's pre-commit
+  hook refuses anyway. Where a container DOES have an environment, the proxy with
+  `RETASC_MCP_KEY` set is still the better door: it renews leases for you.
+
 ## 1.46.0 (2026-09-08)
 
 - **RTSC-855** — `retasc doctor` and `retasc setup` now say whether the **Retasc Agent

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/mcp.js

@@ -4,6 +4,9 @@ import { join } from "node:path";
 import { resolveLauncher, launcherNote, portableLauncher, } from "../lib/launcher.js";
 import { VERSION } from "../version.js";
 import { hasClaudeLocalPlaceholder } from "../lib/binding.js";
+// The TOML dialects live with the rest of the TOML knowledge (harness.ts), not here:
+// the same file has to keep Codex's and Grok's config shapes straight for the proxy form.
+import { tomlHttpBlock } from "../lib/harness.js";
 export const SERVER_NAME = "retasc";
 /** Normalize a user-supplied scope string. `user` (global) is refused and
  * downgraded to `local`, loudly — per-folder binding is the only right way. */
@@ -29,6 +32,47 @@ export function mcpServerEntry(url, key) {
 export function mcpConfigBlock(url, key) {
     return JSON.stringify({ mcpServers: { [SERVER_NAME]: mcpServerEntry(url, key) } }, null, 2);
 }
+/**
+ * Every direct-form block, labelled with the harnesses that read it (RTSC-864).
+ *
+ * The direct form is for a host that cannot spawn our proxy at all, such as a claude.ai
+ * connector, Codex Cloud or a hosted OpenCode, where an HTTP URL and a bearer key is the
+ * only door. Two config languages and three dialects, because `tomlHttpBlock` documents
+ * that Codex and Grok silently ignore each other's header key.
+ *
+ * Printed by `key mint` in the same breath as the key itself, and NOT only when some
+ * install failed: the key is shown once, so every form a person might have to paste it
+ * into has to be on the screen while it is still readable. Sending them to a doc after
+ * the one credential they were given has scrolled away is how a key gets re-minted.
+ */
+export function directFormBlocks(url, key) {
+    return [
+        "Remote-key config, for a host that cannot run a local process",
+        "(claude.ai connectors, Codex Cloud, CI, any hosted agent):",
+        "",
+        "  JSON, for Claude Code, Cursor, OpenCode and Gemini CLI:",
+        "",
+        mcpConfigBlock(url, key),
+        "",
+        "  TOML, for Codex (~/.codex/config.toml):",
+        "",
+        tomlHttpBlock(url, key, "codex"),
+        "",
+        "  TOML, for Grok (~/.grok/config.toml):",
+        "",
+        tomlHttpBlock(url, key, "grok"),
+        "",
+        // The hook is not a style preference and the reason belongs next to the block that
+        // would trip it: a committed key is readable by everyone who ever clones the repo,
+        // and stays readable in git history after it is deleted.
+        "These blocks carry a live credential. Put them in the harness's own user-scope",
+        "config or the platform's secret store, never in a tracked `.mcp.json`. Retasc's own",
+        "repo refuses one at pre-commit, because a key committed once stays readable in git",
+        "history long after it is deleted.",
+        "Where the host DOES give you an environment, prefer the proxy with `RETASC_MCP_KEY`",
+        "set as a secret: it keeps your leases alive for you.",
+    ].join("\n");
+}
 /**
  * The stdio server entry that runs the liveness watchdog proxy (RTSC-44). The
  * harness spawns `retasc mcp-proxy`, which forwards to the remote MCP and keeps
@@ -223,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

@@ -5,7 +5,7 @@ import { Command } from "commander";
 import { VERSION } from "./version.js";
 import { selfCommand, versionStamp } from "./lib/launcher.js";
 import { loadConfig, patchConfig, saveConfig, configPath, isLoggedIn } from "./config.js";
-import { installMcp, noteRuntimeIsALabel, normalizeScope } from "./commands/mcp.js";
+import { installMcp, noteRuntimeIsALabel, normalizeScope, directFormBlocks } from "./commands/mcp.js";
 import { runSetup, printSetup } from "./commands/setup.js";
 import { installGate, resolveGatePrefix } from "./commands/gate.js";
 import { claimAction, releaseAction } from "./commands/claim.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,11 +388,25 @@ 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.)");
+        // RTSC-864: every paste form, now, while the key is still on the screen. A hosted
+        // agent or a container is the reason most people run this command at all, and
+        // until now it printed a bare key and left them to invent the config, which for
+        // Codex and Grok was not inventable, since no direct-form TOML block existed.
+        const cfg = loadConfig();
+        console.log("");
+        console.log(directFormBlocks(cfg.mcpUrl, res.key));
         if (opts.install) {
-            const cfg = loadConfig();
             console.log("");
             noteRuntimeIsALabel(opts.runtime);
             installMcp({ url: cfg.mcpUrl, key: res.key, scope: normalizeScope(opts.scope), watchdog: true });

package/dist/lib/harness.js

@@ -166,6 +166,36 @@ export function tomlBlock(entry) {
         env,
     ].join("\n");
 }
+/** The header table key each dialect actually reads. */
+const HTTP_HEADER_TABLE = {
+    codex: "http_headers",
+    grok: "headers",
+};
+/**
+ * The DIRECT-form `[mcp_servers.retasc]` block: talk to the remote MCP over HTTP with a
+ * bearer key, no local process (RTSC-864).
+ *
+ * The TOML counterpart of `mcpConfigBlock`, and the block that did not exist: `tomlBlock`
+ * above emits only the stdio proxy shape, so a Codex or Grok user on a host that cannot
+ * spawn a process (claude.ai connectors, Codex Cloud, a hosted OpenCode) had nothing
+ * correct to paste and no way to tell that from the JSON form.
+ *
+ * The key is written literally, exactly as the JSON block writes it, because the host
+ * this is pasted into is the one that has no environment for us to read. Both tools can
+ * take the key from the environment instead where there IS one (Codex:
+ * `bearer_token_env_var = "RETASC_MCP_KEY"`; Grok expands `${RETASC_MCP_KEY}` inside a
+ * header value), so prefer that, and never paste either form into a file the repo tracks.
+ */
+export function tomlHttpBlock(url, key, dialect) {
+    return [
+        `[mcp_servers.${SERVER_NAME}]`,
+        `url = ${JSON.stringify(url)}`,
+        `enabled = true`,
+        ``,
+        `[mcp_servers.${SERVER_NAME}.${HTTP_HEADER_TABLE[dialect]}]`,
+        `Authorization = ${JSON.stringify(`Bearer ${key}`)}`,
+    ].join("\n");
+}
 function tomlHarness(id, label, path, bin, skills) {
     return {
         id,

package/package.json

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