@retasc/cli 1.49.1 → 1.50.0

package/CHANGELOG.md

@@ -6,6 +6,23 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.50.0 (2026-09-11)
+
+- **RTSC-901** — `retasc plan`: which subscription pays for each of your agents, listed
+  and set one line per (agent, harness). Retasc cannot read this anywhere — no transcript
+  field, telemetry attribute or environment variable carries it, and the only machine
+  source sits behind the human's own keychain — so it is asked for once and kept.
+  The options are READ FROM THE SERVER on every run, never compiled in: a tier a vendor
+  ships this morning is on the list this afternoon, on the build you already have.
+- **RTSC-901** — `bind` asks the same question at setup, but only when `--runtime` was
+  STATED. That flag defaults to `claude-code`, which is a fine label for a row and the
+  wrong subject for this question: `retasc setup` wires every harness on the machine, so
+  asking "which Claude plan?" of someone setting up Codex records a fact about the wrong
+  product. Left unstated, the question falls to the first MCP handshake, which knows
+  which harness actually connected.
+- A non-interactive run answers nothing rather than defaulting. A plan nobody chose reads
+  on the Agents page exactly like one they did.
+
 ## 1.49.1 (2026-09-09)
 
 - **RTSC-879** — the proxy sends NO `Authorization` header when it has no key, instead of

package/dist/api.js

@@ -16,6 +16,12 @@ const fns = {
     createProject: makeFunctionReference("manage:createProject"),
     renameProjectPrefix: makeFunctionReference("manage:renameProjectPrefix"),
     listKeys: makeFunctionReference("manage:listKeys"),
+    // RTSC-901 — the roster (for the agent rows and their plans) and the plan catalogue.
+    // The catalogue is fetched on every run and never cached to disk: a list cached in
+    // the client is the release-shaped list this issue exists to avoid.
+    listOrgMembers: makeFunctionReference("manage:listOrgMembers"),
+    listPlanCatalogue: makeFunctionReference("plans:listCatalogue"),
+    setMemberPlan: makeFunctionReference("plans:setMemberPlan"),
     mintKey: makeFunctionReference("manage:mintKey"),
     rotateKey: makeFunctionReference("manage:rotateKey"),
     revokeKey: makeFunctionReference("manage:revokeKey"),
@@ -210,6 +216,9 @@ export const api = {
     createProject: (args) => withAuth(() => client().mutation(fns.createProject, args)),
     renameProjectPrefix: (args) => withAuth(() => client().mutation(fns.renameProjectPrefix, args)),
     listKeys: (args) => withAuth(() => client().query(fns.listKeys, args)),
+    listOrgMembers: (args) => withAuth(() => client().query(fns.listOrgMembers, args)),
+    listPlanCatalogue: (args) => withAuth(() => client().query(fns.listPlanCatalogue, args)),
+    setMemberPlan: (args) => withAuth(() => client().mutation(fns.setMemberPlan, args)),
     mintKey: (args) => withAuth(() => client().action(fns.mintKey, args)),
     rotateKey: (args) => withAuth(() => client().action(fns.rotateKey, args)),
     revokeKey: (args) => withAuth(() => client().mutation(fns.revokeKey, args)),

package/dist/commands/bind.js

@@ -604,6 +604,45 @@ export async function completeWorkspaceSetup(args) {
     // the only reader of this output, and it is the one that has to tell the human to
     // restart. A setup that finished but never says so is indistinguishable from one that
     // failed. The "what now" suggestions stay TTY-only — those are for a person browsing.
+    // RTSC-901 — which plan pays for this agent. Asked ONCE, here, because this is the
+    // moment the agent row exists and a person is already at the keyboard.
+    //
+    // Three things this must not do, all of them worse than not knowing: block a
+    // non-interactive run (`select` returns null and we move on), ask again when this
+    // human already answered for this runtime (the roster hands back an inherited plan,
+    // so `plan` is set and the row is skipped), or fail the bind. The bind is the
+    // critical path and the plan is a nicety on top of it, so ANY failure here is
+    // swallowed — a missing plan costs a line on the Agents page, a failed bind costs
+    // the whole setup.
+    //
+    // Placed before the receipt so the last thing on screen is still the next step.
+    //
+    // ONLY WHEN THE RUNTIME WAS STATED. `--runtime` defaults to claude-code, which is a
+    // fine LABEL for a row and a bad subject for this question: `retasc setup` wires
+    // every harness on the machine, so asking "which Claude plan?" of someone setting up
+    // Codex records a fact about the wrong product, and a wrong plan is worse than none.
+    // Unstated, the question goes to the first handshake instead — `setup_status` reaches
+    // the same `askHuman` payload with the harness that actually connected.
+    if (isInteractive() && opts.runtimeStated) {
+        try {
+            const [roster, catalogue] = await Promise.all([
+                api.listOrgMembers({ orgId }),
+                api.listPlanCatalogue({ orgId }),
+            ]);
+            const runtime = opts.runtime ?? "claude-code";
+            const unanswered = roster.filter((m) => m.isAgent && m.mine && m.canSetPlan && m.runtime === runtime && !m.plansByClass?.[m.planBucket]);
+            // Exactly one, or we do not know which this bind created — and asking about the
+            // wrong agent records a fact under the wrong name.
+            if (unanswered.length === 1) {
+                const { askAndSet } = await import("./plan.js");
+                const cat = catalogue;
+                await askAndSet(orgId, unanswered[0], cat.byClass, { otherId: cat.otherId, declinedId: cat.declinedId });
+            }
+        }
+        catch {
+            // Never let this cost the bind. `retasc plan` asks the same question later.
+        }
+    }
     console.log(`\n${NEXT_STEP}\n`);
     if (isInteractive())
         console.log(`${whatNow(pfx, emptyProject)}\n`);

package/dist/commands/plan.js

@@ -0,0 +1,205 @@
+import { api } from "../api.js";
+import { ask, isInteractive, select } from "../lib/prompt.js";
+// Every value below came off the wire, and `cli/src/lib/text.ts` is the repo's rule
+// for that: an agent name or a plan label carrying \x1b[ can move the cursor, clear
+// the line and rewrite the rows above it. That matters most HERE, because this
+// command prints a list and then asks a question the reader answers by number, and
+// `mintKey` stores `agentName` and `runtime` verbatim — so any member of the org can
+// choose what lands on an owner's terminal.
+import { clean } from "../lib/text.js";
+// Nothing about plans is compiled in here — not the list, and not the two terminal
+// answers either. `cli/src/lib/outcome.ts` records why the CLI cannot import
+// `convex/lib`, and a mirrored copy of the vocabulary would be a second thing to keep
+// in step. So the ids come from the catalogue payload and the runtime class comes off
+// the roster row, both resolved server-side.
+/** What an agent nobody has answered for prints. Not a plan, so not from the server. */
+const NOT_SET = "Not set";
+// RTSC-901 — `retasc plan`: which plan pays for each of your agents.
+//
+// Retasc cannot see this. No hook payload, transcript field or telemetry attribute
+// carries the plan or the usage gauge, and the only machine source is an undocumented
+// per-account endpoint that needs the human's own credential. Retasc does not ask an
+// agent to read a credential store, so the fact is asked for and a person answers it.
+//
+// The options are READ FROM THE SERVER on every run, never compiled in. That is the
+// whole design: a tier a vendor shipped this morning is on this list this afternoon,
+// on the build you already have.
+/** The `retasc plan` list, and the picker when an agent is named. */
+export async function planAction(opts) {
+    const me = await api.me();
+    let orgId = opts.orgId;
+    if (!orgId) {
+        if (me.orgs.length === 0)
+            throw new Error("You're not a member of any org yet.");
+        if (me.orgs.length > 1) {
+            const list = me.orgs.map((o) => `  ${o.id}  ${o.name}${o.slug ? ` (${o.slug})` : ""}`);
+            throw new Error(`Several orgs — pass --org-id <id>:\n${list.join("\n")}`);
+        }
+        orgId = me.orgs[0].id;
+    }
+    const [roster, catalogue] = await Promise.all([
+        api.listOrgMembers({ orgId: orgId }),
+        api.listPlanCatalogue({ orgId: orgId }),
+    ]);
+    // Yours first. An owner can set anyone's, but the question this command answers is
+    // almost always about the machine it is being run on.
+    const agents = roster
+        .filter((m) => m.isAgent)
+        .sort((a, b) => Number(b.mine) - Number(a.mine) || a.name.localeCompare(b.name));
+    if (agents.length === 0) {
+        console.log("No agents in this org yet. Run `retasc setup` to wire one up.");
+        return;
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(agents.flatMap((m) => classesOf(m).map((cls) => ({
+            id: m.id,
+            name: m.name,
+            runtime: m.runtime,
+            runtimeClass: cls,
+            plan: m.plansByClass?.[cls] ?? null,
+            canSet: m.canSetPlan,
+        }))), null, 2));
+        return;
+    }
+    const chosen = opts.agent
+        ? agents.find((m) => m.id === opts.agent || m.name.toLowerCase().includes(opts.agent.toLowerCase()))
+        : null;
+    if (opts.agent && !chosen) {
+        throw new Error(`No agent matching "${clean(opts.agent)}". Run \`retasc plan\` to see them.`);
+    }
+    if (!chosen) {
+        // ONE LINE PER (agent, harness), which is the unit an answer fills and the unit
+        // the Dash's Agents page draws. Listing one line per MEMBER read the plan for the
+        // runtime the member was BOUND as and nothing else, so an agent running both
+        // Claude Code and Codex showed one of them here and the other only in the Dash —
+        // and the terminal could not set the one it did not show.
+        console.log("");
+        for (const m of agents) {
+            for (const cls of classesOf(m)) {
+                const own = m.plansByClass?.[cls] ?? null;
+                const plan = own?.label ?? NOT_SET;
+                const tag = own?.inherited ? "  (from your other agent)" : "";
+                // Inlined rather than hoisted to a local: `plan901.test.ts` reads THIS file and
+                // requires every wire value to be cleaned at its print site, and a local hides
+                // which wire value the interpolation is carrying.
+                console.log(`  ${clean(m.name).padEnd(28)} ${clean(classLabel(m, cls)).padEnd(14)} ${clean(plan)}${tag}`);
+            }
+        }
+        const unset = agents.reduce((n, m) => n + (m.canSetPlan ? classesOf(m).filter((c) => !m.plansByClass?.[c]).length : 0), 0);
+        console.log("");
+        if (unset > 0)
+            console.log(`  ${unset} without a plan. Set one with \`retasc plan --agent <name>\`.`);
+        console.log("  You can also set these in the Dash under Agents.");
+        return;
+    }
+    if (!chosen.canSetPlan) {
+        throw new Error(`"${clean(chosen.name)}" is not yours to set. An owner or admin can set anyone's.`);
+    }
+    const cat = catalogue;
+    // A member can host several harnesses, and they are separate accounts with separate
+    // plans. Picking the agent is therefore not enough to know what is being answered —
+    // so when there is more than one, that is its own question, asked first.
+    const classes = classesOf(chosen);
+    let cls = classes[0];
+    if (classes.length > 1) {
+        const picked = await select(`\n${clean(chosen.name)} runs ${classes.length} harnesses. Which one?`, classes.map((c) => ({
+            id: c,
+            label: clean(classLabel(chosen, c)),
+            note: chosen.plansByClass?.[c] ? `Currently ${clean(chosen.plansByClass[c].label)}` : "No plan recorded",
+        })));
+        if (picked === null)
+            return;
+        cls = picked;
+    }
+    await askAndSet(orgId, {
+        ...chosen,
+        // The catalogue to offer. `unknown` is the bucket for a harness we cannot place,
+        // and it has no catalogue — so the picker is `other` and `declined`, which is
+        // the same answer the server gives for a null class.
+        planClass: cls === "unknown" ? null : cls,
+        runtimeName: classLabel(chosen, cls),
+        // Send the WIRE runtime for the member's own harness and the CLASS for a
+        // sibling. Both file under the same key, but the wire value is also recorded on
+        // an `other` answer as the restock signal's record of which harness said it, and
+        // "codex-mcp-client" teaches more there than "codex". For a sibling harness the
+        // roster does not tell us the wire value, so the class is the honest best.
+        runtime: cls === chosen.planBucket ? chosen.runtime : cls,
+    }, cat.byClass, { otherId: cat.otherId, declinedId: cat.declinedId });
+}
+/** The harness classes this agent should be answered for. `planClasses` is the
+ *  server's set, built from the member's own session keys; the bound runtime is the
+ *  fallback for a Dash loaded against an older backend. */
+function classesOf(m) {
+    const list = m.planClasses ?? [];
+    return list.length > 0 ? list : [m.planBucket];
+}
+/** What to call one of an agent's harnesses. The member's own runtime keeps its full
+ *  name ("Claude Code"); a sibling harness is named by its class, which is all the
+ *  roster knows about it. */
+function classLabel(m, cls) {
+    if (cls === m.planBucket && m.runtimeName)
+        return m.runtimeName;
+    return CLASS_NAMES[cls] ?? cls;
+}
+/** Class -> display name. Small and local: these are the eight buckets in
+ *  `convex/lib/runtime.ts`, and the CLI cannot import it (see `lib/outcome.ts`). A
+ *  class not here prints as itself, which is the same rule `runtimeLabel` follows. */
+const CLASS_NAMES = {
+    claude: "Claude Code",
+    codex: "Codex",
+    opencode: "OpenCode",
+    gemini: "Gemini",
+    cursor: "Cursor",
+    grok: "Grok",
+    ci: "CI",
+    unknown: "Unreported",
+};
+/**
+ * Put the list to the human and record what they pick.
+ *
+ * Exported so `retasc setup` asks the identical question through the identical code.
+ * Two copies of a question drift into two questions.
+ */
+export async function askAndSet(orgId, agent, byClass, 
+/** `otherId` / `declinedId`, straight from the catalogue payload. */
+ids) {
+    if (!isInteractive())
+        return false;
+    const options = (agent.planClass && byClass[agent.planClass]) || [];
+    const name = clean(agent.runtimeName || "this runtime");
+    const who = clean(agent.name);
+    const choices = [
+        // The catalogue is ours, but it is still served: clean it like anything else.
+        ...options.map((o) => ({ id: o.planId, label: clean(o.label), note: o.note ? clean(o.note) : null })),
+        // Always last, always present. The catalogue is knowingly incomplete, so there has
+        // to be somewhere for the plan we have not heard of to go — and on a runtime we do
+        // not know at all, these two ARE the list.
+        { id: ids.otherId, label: "Something else", note: "A plan that is not listed" },
+        { id: ids.declinedId, label: "Not shared", note: "Nothing is recorded, and you will not be asked again" },
+    ];
+    const heading = options.length > 0
+        ? `\nWhich plan pays for ${who}'s ${name} usage?`
+        : `\nRetasc has no plan list for ${name} yet. Which plan pays for ${who}?`;
+    const picked = await select(heading, choices);
+    if (picked === null)
+        return false;
+    let label;
+    if (picked === ids.otherId) {
+        label = await ask("Plan name, as it is billed: ");
+        if (!label.trim()) {
+            console.log("Nothing typed, so nothing recorded. Run `retasc plan` when you know it.");
+            return false;
+        }
+    }
+    // `agent.runtime` is what the CALLER decided this answer is about: the member's wire
+    // runtime for its own harness, the class for a sibling. It used to be the member's
+    // bound runtime unconditionally, so choosing the Codex line wrote the Claude key —
+    // the answer vanished from the row that asked for it and appeared on one that had
+    // not. `planStorageClassOf` maps a class to itself, so both spellings file alike.
+    const res = await api.setMemberPlan({ orgId, memberId: agent.id, runtime: agent.runtime ?? "", planId: picked, label });
+    console.log(`\n  ${who}: ${clean(res.label)}`);
+    // Both doors, every time. A person told once where to change something will not
+    // remember; a person told at the moment they answer knows they are not locked in.
+    console.log("  Change it any time with `retasc plan`, or in the Dash under Agents.\n");
+    return true;
+}

package/dist/index.js

@@ -231,7 +231,16 @@ program
     // at exit 0 instead of thrown. Structured output an agent cannot act on, or a door
     // that leads to a thrown Error, is each worse than neither.
     .option("--json", "Report machine-readable outcomes (for an agent driving setup)")
-    .action(async (opts) => {
+    .action(async (opts, cmd) => {
+    // RTSC-901 — was the runtime STATED, or is it the default sitting there?
+    //
+    // `--runtime` labels the agent row and defaults to claude-code, which is right for
+    // the label: most binds are Claude Code and a row needs a name. It is NOT right as
+    // the subject of the plan question. `retasc setup` wires every harness on the
+    // machine, so the folder rarely has one provider, and asking "which Claude plan?"
+    // of someone setting up Codex records a fact about the wrong product. When the
+    // flag was not stated, the plan question is left to the handshake, which knows.
+    opts.runtimeStated = cmd.getOptionValueSource("runtime") === "cli";
     // BEFORE requireLogin: the whole point is a machine that has never signed in. The
     // token is the authorization, and asking for a session here would refuse every
     // caller this flag exists for.
@@ -596,6 +605,19 @@ program
 // RTSC-780 — the once-per-machine half of setup. `bind` runs this itself the first
 // time, so most people never type it; it exists on its own for the second harness
 // installed after a bind, and for re-running after an upgrade moved the launcher.
+// RTSC-901 — which plan pays for each agent. Asked once at setup and changeable here
+// forever after, which is the other half of the promise the setup receipt makes.
+program
+    .command("plan")
+    .description("Show or set which plan pays for each of your agents.")
+    .option("--org-id <id>", "Org, when you're in more than one")
+    .option("--agent <nameOrId>", "Set the plan for one agent")
+    .option("--json", "Machine-readable")
+    .allowExcessArguments(false)
+    .action(async (opts) => {
+    const { planAction } = await import("./commands/plan.js");
+    await planAction(opts);
+});
 program
     .command("setup")
     .description("Detect the MCP harnesses on this machine and wire Retasc into each, once.")

package/dist/lib/prompt.js

@@ -36,3 +36,43 @@ export async function confirm(question, assumeYes) {
     const a = (await ask(`${question} [y/N] `)).toLowerCase();
     return a === "y" || a === "yes";
 }
+/**
+ * Ask a human to PICK, by number, never to type a name (RTSC-901).
+ *
+ * Typing is how a plan called "Max 20x" gets recorded as "max20", "Max20x" and
+ * "MAX 20X" across three machines and then fails to group. Numbers make the common
+ * answer mechanical and leave typing for the case that genuinely needs it, which is
+ * an option this list does not have.
+ *
+ * Returns the chosen `id`, or `null` when there is nobody to ask: a non-interactive
+ * run SKIPS the question rather than blocking a script or guessing an answer. A
+ * question nobody answered has to stay unanswered — that is the difference between
+ * "not asked" and a wrong fact recorded forever.
+ *
+ * Enter alone takes `defaultId` when one is given, so the common path is one keypress.
+ */
+export async function select(question, choices, defaultId) {
+    if (!isInteractive() || choices.length === 0)
+        return null;
+    stdout.write(`${question}\n`);
+    for (let i = 0; i < choices.length; i++) {
+        const c = choices[i];
+        const mark = c.id === defaultId ? " (default)" : "";
+        stdout.write(`  ${String(i + 1).padStart(2)}. ${c.label}${mark}\n`);
+        if (c.note)
+            stdout.write(`      ${c.note}\n`);
+    }
+    // Three tries, then give up rather than loop at someone. A person who has typed
+    // nonsense three times is not going to type a number on the fourth, and a CLI that
+    // will not let go of the terminal is worse than an unanswered question.
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const raw = await ask(defaultId ? `Number [${choices.findIndex((c) => c.id === defaultId) + 1}]: ` : "Number: ");
+        if (!raw && defaultId)
+            return defaultId;
+        const n = Number(raw);
+        if (Number.isInteger(n) && n >= 1 && n <= choices.length)
+            return choices[n - 1].id;
+        stdout.write(`  Pick a number between 1 and ${choices.length}.\n`);
+    }
+    return null;
+}

package/package.json

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