@retasc/cli 1.2.0 → 1.2.2

package/dist/commands/claim.js

@@ -1,7 +1,8 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { basename, dirname, resolve, sep } from "node:path";
-import { resolveMcpConn, readMcpJson, mcpCall, parseClaimResult, planWorktree, isValidIssueId, } from "../lib/claim.js";
+import { resolveMcpConn, readMcpJson, mcpCall, parseClaimResult, planWorktree, isValidIssueId, normalizeIssueId, workspacePrefix, } from "../lib/claim.js";
+import { loadConfig } from "../config.js";
 function git(args, cwd) {
     return spawnSync("git", args, { encoding: "utf8", cwd });
 }
@@ -28,6 +29,50 @@ export async function claimAction(opts) {
         note("  (Looked at $RETASC_MCP_KEY and ./.mcp.json.)");
         process.exit(1);
     }
+    // RTSC-148: resolve the requested issue id up front — a positional (`claim 143`,
+    // `claim RTSC-143`) or --id, normalized to PREFIX-NN. An unresolvable reference
+    // fails HERE; it must never fall through to "claim whatever is next".
+    // A bare number expands against the WORKSPACE's prefix (whoami over this
+    // workspace's key — the key decides the org/project), falling back to the
+    // global config only if the server can't be asked.
+    let prefix;
+    let prefixResolved = false;
+    let requestedId;
+    for (const [label, raw] of [
+        ["issue", opts.issueArg],
+        ["--id", opts.id],
+    ]) {
+        // Only ABSENT skips — an empty string (e.g. `claim "$UNSET_VAR"`) must hit
+        // the loud-failure path below, not fall through to next_issue.
+        if (raw === undefined)
+            continue;
+        if (/^\d+$/.test(raw.trim()) && !prefixResolved) {
+            prefix = (await workspacePrefix(conn)) ?? loadConfig().defaultProjectPrefix;
+            prefixResolved = true;
+        }
+        const norm = normalizeIssueId(raw, prefix);
+        if (!norm) {
+            if (/^\d+$/.test(raw.trim()) && !prefix) {
+                note(`✗ "${raw}" is a bare number and the project prefix couldn't be resolved from this workspace.`);
+                note("  Use the full id (e.g. RTSC-" + raw.trim() + ").");
+            }
+            else {
+                note(`✗ "${raw}" doesn't look like an issue id (expected RTSC-NN or a bare number).`);
+            }
+            process.exit(1);
+        }
+        if (requestedId && requestedId !== norm) {
+            note(`✗ Conflicting issue ids: positional "${requestedId}" vs ${label} "${norm}". Pass just one.`);
+            process.exit(1);
+        }
+        requestedId = norm;
+    }
+    // --mine filters the next_issue pull; on a targeted claim it would be
+    // silently ignored — reject instead of letting the intent evaporate.
+    if (requestedId && opts.mine) {
+        note(`✗ --mine only applies when pulling the next issue; drop it to claim ${requestedId} directly.`);
+        process.exit(1);
+    }
     const makeWorktree = opts.worktree !== false;
     // Must be in a git repo to place the worktree. Resolve the *main* checkout so
     // worktrees are always siblings of it, even when claiming from another worktree.
@@ -52,8 +97,8 @@ export async function claimAction(opts) {
     // --- claim over MCP ------------------------------------------------------
     let claim;
     try {
-        const result = opts.id
-            ? await mcpCall(conn, "claim_issue", { identifier: opts.id })
+        const result = requestedId
+            ? await mcpCall(conn, "claim_issue", { identifier: requestedId })
             : await mcpCall(conn, "next_issue", opts.mine ? { mine: true } : {});
         claim = parseClaimResult(result);
     }
@@ -62,9 +107,9 @@ export async function claimAction(opts) {
         note(`✗ ${msg}`);
         // Re-claiming an issue you already hold is the "resume my own work" case —
         // point at the worktree instead of leaving the user stuck on the error.
-        if (opts.id && /ALREADY_CLAIMED/.test(msg) && makeWorktree) {
-            note(`  ${opts.id} is held. If it's your session, resume in ${parentDir}/${repoName}-${opts.id.toLowerCase()}`);
-            note(`  or \`retasc release ${opts.id}\` first.`);
+        if (requestedId && /ALREADY_CLAIMED/.test(msg) && makeWorktree) {
+            note(`  ${requestedId} is held. If it's your session, resume in ${parentDir}/${repoName}-${requestedId.toLowerCase()}`);
+            note(`  or \`retasc release ${requestedId}\` first.`);
         }
         process.exit(1);
     }

package/dist/index.js

@@ -414,12 +414,19 @@ function addClaimFlags(cmd) {
         .option("--print-path", "Print only the worktree path on stdout (for `cd \"$(…)\"`)")
         .option("--json", "Emit the claim + worktree as JSON");
 }
+// RTSC-148: `claim` takes the issue as a positional too (`retasc claim 143` /
+// `retasc claim RTSC-143`). Excess arguments are rejected loudly on both
+// commands — Commander otherwise silently drops an undeclared positional, which
+// turned "claim this specific issue" into "claim whatever is next".
 addClaimFlags(program
     .command("claim")
-    .description("Claim an issue (--id, or the next unblocked) and drop into a fresh worktree.")).action((opts) => claimAction(opts).catch(fail));
+    .description("Claim an issue (RTSC-NN, a bare number, --id, or the next unblocked) and drop into a fresh worktree.")
+    .argument("[issue]", "Issue to claim, e.g. RTSC-143 or 143 (defaults to the next unblocked)")
+    .allowExcessArguments(false)).action((issue, opts) => claimAction({ ...opts, issueArg: issue }).catch(fail));
 addClaimFlags(program
     .command("next")
-    .description("Claim the next unblocked issue and drop into a fresh worktree (alias of `claim`).")).action((opts) => claimAction(opts).catch(fail));
+    .description("Claim the next unblocked issue and drop into a fresh worktree (alias of `claim`).")
+    .allowExcessArguments(false)).action((opts) => claimAction(opts).catch(fail));
 // --- branch hygiene (close the worktree+branch claim opened) ----------------
 program
     .command("tidy")

package/dist/lib/claim.js

@@ -5,6 +5,10 @@
 import { readFileSync, existsSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { resolveConn } from "./keystore.js";
+// Tool-payload extraction lives in the shared tolerant parser (RTSC-143);
+// re-exported so existing importers of this module keep working.
+import { toolResult } from "./toolresult.js";
+export { toolResult };
 const DEFAULT_MCP_URL = "https://mcp.retasc.com/mcp";
 /**
  * Resolve the agent API key + MCP URL the same way the workspace's MCP wiring does,
@@ -56,6 +60,36 @@ export function slugFromTitle(title, max = 50) {
 export function isValidIssueId(id) {
     return typeof id === "string" && /^[A-Za-z][A-Za-z0-9]*-\d+$/.test(id);
 }
+/**
+ * Normalize a user-typed issue reference (`143`, `rtsc-143`, `RTSC-143`) to the
+ * canonical `PREFIX-NN` form. A bare number needs `defaultPrefix` (from the
+ * logged-in project) to be resolvable. Returns null when the input can't be an
+ * issue id — the caller decides how to fail loudly (RTSC-148: a typo must never
+ * silently fall through to `next_issue`).
+ */
+/**
+ * The workspace's project prefix, asked of the server over the workspace's own
+ * key (`whoami`). Org/project routing IS the key — the global config's prefix
+ * may belong to a different workspace, so this is the authoritative source for
+ * expanding a bare issue number. Best-effort: undefined on any failure.
+ */
+export async function workspacePrefix(conn, fetchImpl = fetch) {
+    try {
+        const who = (await mcpCall(conn, "whoami", {}, fetchImpl));
+        const p = who?.project?.prefix;
+        return typeof p === "string" && p ? p : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function normalizeIssueId(input, defaultPrefix) {
+    const s = input.trim();
+    if (/^\d+$/.test(s)) {
+        return defaultPrefix ? `${defaultPrefix.toUpperCase()}-${s}` : null;
+    }
+    return isValidIssueId(s) ? s.toUpperCase() : null;
+}
 /**
  * Derive the branch + sibling worktree path from an issue, matching the CLAUDE.md
  * convention: branch `rtsc-NN/<slug>`, worktree dir `../<repo>-rtsc-NN`.
@@ -84,16 +118,6 @@ export function parseClaimResult(result) {
     const title = typeof r.issue === "object" ? r.issue?.title : undefined;
     return { issueId, title, claimToken: r.claimToken };
 }
-/** The tool payload (JSON inside result.content[0].text), or the raw result. */
-export function toolResult(resp) {
-    try {
-        const t = resp?.result?.content?.[0]?.text;
-        return t ? JSON.parse(t) : resp?.result;
-    }
-    catch {
-        return resp?.result;
-    }
-}
 /**
  * Call one MCP tool over JSON-RPC with the agent key. Throws on transport errors
  * and on tool errors (isError) — surfacing the server's message (CLAIM_LOST,

package/dist/lib/session.js

@@ -0,0 +1,93 @@
+// Session-key adoption core (RTSC-143) — the mint call the proxy runs on startup
+// (RTSC-50), extracted here so the retry + failure behavior is unit-testable with
+// a stubbed fetch. Fail-soft stands: a broken mint must never take the MCP down —
+// but the fallback must be LOUD, because on the shared workspace key concurrent
+// sessions collapse into one server-side identity and the per-session claim fence
+// (RTSC-49/50) is silently inert.
+import { toolResult } from "./toolresult.js";
+// Out-of-band ids are negative so they never collide with the harness's (the
+// same convention as the proxy's heartbeat ids; announceBinding uses -1001).
+const MINT_RPC_ID = -1000;
+// The mint runs BEFORE the proxy serves `initialize`, so a hung server must not
+// stall startup past the harness's MCP timeout — that would turn "degraded
+// identity" into "no Retasc tools at all", the exact failure fail-soft exists
+// to avoid. Two attempts fit comfortably inside a ~30s harness budget.
+const MINT_TIMEOUT_MS = 5_000;
+const FALLBACK_CONSEQUENCE = "concurrent sessions will be indistinguishable to the server and the " +
+    "per-session claim fence is OFF for this session. Restart the session to retry.";
+/**
+ * Mint a per-session key, retrying once (a startup network blip must not demote
+ * the whole session's identity). Never throws. On double failure, emits an
+ * unmissable multi-line warning stating the consequence and returns {ok:false}
+ * so the caller can keep flagging the degraded state (e.g. on whoami).
+ */
+export async function mintSessionKey(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const warn = opts.warn ?? ((msg) => process.stderr.write(`[retasc] ${msg}\n`));
+    const retryDelayMs = opts.retryDelayMs ?? 500;
+    for (let attempt = 1; attempt <= 2; attempt++) {
+        try {
+            const res = await fetchImpl(opts.url, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${opts.key}`,
+                    "Content-Type": "application/json",
+                    Accept: "application/json",
+                },
+                body: JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: MINT_RPC_ID,
+                    method: "tools/call",
+                    params: { name: "mint_session_key", arguments: { label: opts.label } },
+                }),
+                signal: AbortSignal.timeout(MINT_TIMEOUT_MS),
+            });
+            const text = await res.text();
+            // A non-2xx (revoked key → 401, server error → 5xx) must not masquerade
+            // as "no key in response" — surface the status so a dead key is obvious.
+            if (!res.ok) {
+                const snippet = text ? `: ${text.slice(0, 120).replace(/\s+/g, " ").trim()}` : "";
+                warn(`mint_session_key attempt ${attempt} failed (HTTP ${res.status})${snippet}`);
+            }
+            else {
+                const r = toolResult(text ? JSON.parse(text) : null, warn);
+                if (r && typeof r === "object" && typeof r.key === "string") {
+                    return { ok: true, key: r.key, session: r.session };
+                }
+                warn(`mint_session_key attempt ${attempt} returned no key`);
+            }
+        }
+        catch (e) {
+            warn(`mint_session_key attempt ${attempt} failed: ${String(e?.message ?? e)}`);
+        }
+        if (attempt === 1 && retryDelayMs > 0) {
+            await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+        }
+    }
+    warn("WARNING: could not mint a per-session key (retried once).");
+    warn(`WARNING: continuing on the SHARED WORKSPACE KEY — ${FALLBACK_CONSEQUENCE}`);
+    return { ok: false };
+}
+/**
+ * The warning content block appended to whoami responses when the session is
+ * running on the workspace-key fallback — so the AGENT sees the degraded state,
+ * not just whoever reads the MCP log files.
+ */
+export const MINT_FALLBACK_NOTICE = "⚠ Retasc watchdog: this session could not mint a per-session key and is using " +
+    `the shared workspace key — ${FALLBACK_CONSEQUENCE}`;
+/**
+ * Append MINT_FALLBACK_NOTICE to a whoami response when degraded. Defensive on
+ * purpose: anything unexpected about the shape (error response, missing/non-array
+ * content) leaves the response untouched — a malformed notice must never break
+ * the protocol stream this rides on.
+ */
+export function appendFallbackNotice(toolName, resp, degraded) {
+    if (!degraded || toolName !== "whoami")
+        return;
+    const result = resp?.result;
+    if (result?.isError)
+        return; // don't decorate an error response
+    if (Array.isArray(result?.content)) {
+        result.content.push({ type: "text", text: MINT_FALLBACK_NOTICE });
+    }
+}

package/dist/lib/toolresult.js

@@ -0,0 +1,94 @@
+// Tolerant MCP tool-result parsing (RTSC-143) — pure, shared by proxy.ts and
+// lib/claim.ts (previously two silent near-identical copies). The RTSC-91 footer
+// regression survived unnoticed because a payload of `{json}\n\n— footer` failed
+// JSON.parse and the parser silently handed back the raw result envelope —
+// downstream code (lease tracking, claim parsing) then quietly misbehaved. This
+// parser (a) recovers the JSON prefix when the text has trailing non-JSON, and
+// (b) says so, so a shape regression is visible in MCP logs instead of vanishing.
+/** Pure core: classify + extract the payload from a JSON-RPC tools/call response. */
+export function parseToolResult(resp) {
+    const result = resp?.result;
+    const text = result?.content?.[0]?.text;
+    if (typeof text !== "string" || !text)
+        return { kind: "raw", value: result };
+    try {
+        return { kind: "json", value: JSON.parse(text) };
+    }
+    catch {
+        /* fall through to prefix recovery */
+    }
+    // Never RECOVER from an error response: error text is prose that may embed
+    // JSON-looking fragments (issue ids, tokens), and a recovered fragment would
+    // flow into lease tracking as if the call had succeeded.
+    if (!result?.isError) {
+        const recovered = parseJsonPrefix(text);
+        if (recovered)
+            return { kind: "recovered", value: recovered.value };
+    }
+    return { kind: "raw", value: result, unparseable: true };
+}
+const MAX_PREFIX_ATTEMPTS = 16;
+/**
+ * "Strip trailing junk after the top-level JSON value". Fast path: JSON.parse
+ * errors name the offending position (V8/JSC), which for a value-plus-footer is
+ * exactly where the junk starts. Fallback: a bounded backward scan for the
+ * payload's closing `}`/`]`. Either way a candidate is only accepted when the
+ * discarded tail is NOT itself JSON-like — concatenated JSON values (NDJSON
+ * style) are a shape break where silently dropping the second value would be
+ * worse than the raw fallback.
+ */
+function parseJsonPrefix(text) {
+    if (!/^\s*[{[]/.test(text))
+        return undefined; // only object/array payloads
+    const accept = (end) => {
+        if (/^\s*[{[]/.test(text.slice(end)))
+            return undefined; // tail is more JSON — refuse
+        try {
+            return { value: JSON.parse(text.slice(0, end)) };
+        }
+        catch {
+            return undefined;
+        }
+    };
+    try {
+        JSON.parse(text);
+    }
+    catch (e) {
+        const m = /position\s+(\d+)/i.exec(String(e?.message ?? e));
+        if (m) {
+            const hit = accept(Number(m[1]));
+            if (hit)
+                return hit;
+        }
+    }
+    let end = text.length;
+    for (let attempt = 0; attempt < MAX_PREFIX_ATTEMPTS; attempt++) {
+        const close = Math.max(text.lastIndexOf("}", end - 1), text.lastIndexOf("]", end - 1));
+        if (close < 0)
+            return undefined;
+        const hit = accept(close + 1);
+        if (hit)
+            return hit;
+        end = close; // that candidate wasn't the payload's end — try the previous one
+    }
+    return undefined;
+}
+function warnStderr(msg) {
+    process.stderr.write(`[retasc] ${msg}\n`);
+}
+/**
+ * The tool payload (JSON inside result.content[0].text), or the raw result.
+ * Drop-in for the old silent copies, except a degraded parse now WARNS (stderr —
+ * stdout may be the MCP channel): callers that only care about the value keep
+ * their one-liner, and a server shape regression is at least visible in logs.
+ */
+export function toolResult(resp, warn = warnStderr) {
+    const p = parseToolResult(resp);
+    if (p.kind === "recovered") {
+        warn("tool result had trailing non-JSON text — recovered the leading JSON payload");
+    }
+    else if (p.unparseable) {
+        warn("tool result text is not JSON — falling back to the raw result envelope");
+    }
+    return p.value;
+}

package/dist/proxy.js

@@ -9,6 +9,8 @@ import { createInterface } from "node:readline";
 import { hostname } from "node:os";
 import { applyObservation, heartbeatRequest, isClaimLost, } from "./lib/watchdog.js";
 import { resolveConn } from "./lib/keystore.js";
+import { toolResult as parseTool } from "./lib/toolresult.js";
+import { mintSessionKey, appendFallbackNotice } from "./lib/session.js";
 // RTSC-92/98: resolve the workspace key via the SHARED resolver, so the proxy and
 // the direct commands (claim/tidy/done) can never diverge. The proxy carries its
 // binding in its own env (RETASC_MCP_KEY legacy, or RETASC_WORKSPACE → keystore).
@@ -21,6 +23,9 @@ let hbSeq = -1; // out-of-band heartbeat ids are negative — never collide with
 // Per-session key (RTSC-50): starts as the workspace key; on startup we mint a
 // session key and switch to it so this session is distinguishable from others.
 let activeKey = KEY;
+// Set when session-key minting failed and we fell back to the workspace key —
+// whoami responses get a warning block appended so the agent sees the degraded state.
+let sessionKeyFallback = false;
 // stderr only: stdout is the MCP channel and must carry ONLY protocol messages.
 function log(msg) {
     process.stderr.write(`[retasc-watchdog] ${msg}\n`);
@@ -42,30 +47,20 @@ async function postRemote(body) {
  * Auto-adopt a per-session key (RTSC-50). Mint one bound to our identity and use
  * it for the rest of the session, so concurrent sessions of the same agent are
  * distinguishable. Fail-soft: if minting is unavailable (older server, error),
- * keep using the workspace key — no worse than before.
+ * keep using the workspace key — no worse than before — but LOUDLY (RTSC-143),
+ * because on the shared key the per-session claim fence is inert.
  */
 async function adoptSessionKey() {
     if (!KEY)
         return;
     const label = process.env.RETASC_SESSION_LABEL || `${hostname()}#${process.pid}`;
-    try {
-        const resp = await postRemote({
-            jsonrpc: "2.0",
-            id: -1000,
-            method: "tools/call",
-            params: { name: "mint_session_key", arguments: { label } },
-        });
-        const r = toolResult(resp);
-        if (r && typeof r === "object" && typeof r.key === "string") {
-            activeKey = r.key; // switch to the session key
-            log(`adopted session key "${r.session ?? label}"`);
-        }
-        else {
-            log("mint_session_key unavailable — using the workspace key");
-        }
+    const outcome = await mintSessionKey({ url: MCP_URL, key: KEY, label, warn: log });
+    if (outcome.ok) {
+        activeKey = outcome.key; // switch to the session key
+        log(`adopted session key "${outcome.session ?? label}"`);
     }
-    catch (e) {
-        log(`session-key mint failed (${String(e?.message ?? e)}) — using the workspace key`);
+    else {
+        sessionKeyFallback = true;
     }
 }
 /**
@@ -81,7 +76,7 @@ async function announceBinding() {
             method: "tools/call",
             params: { name: "whoami", arguments: {} },
         });
-        const r = toolResult(resp);
+        const r = toolResult(resp, "whoami");
         if (r?.org && r?.project) {
             log(`bound → org "${r.org.name}" / project ${r.project.prefix}`);
         }
@@ -90,15 +85,11 @@ async function announceBinding() {
         /* announcement is best-effort */
     }
 }
-// The tool result payload — the JSON inside result.content[0].text — or the raw result.
-function toolResult(resp) {
-    try {
-        const t = resp?.result?.content?.[0]?.text;
-        return t ? JSON.parse(t) : resp?.result;
-    }
-    catch {
-        return resp?.result;
-    }
+// The tool result payload — shared tolerant parser (RTSC-143), warning through
+// our stderr logger (tool-labeled, so a busy MCP log names which call degraded)
+// when it had to recover a JSON prefix or fall back raw.
+function toolResult(resp, tool) {
+    return parseTool(resp, (msg) => log(tool ? `${tool}: ${msg}` : msg));
 }
 async function handleLine(line) {
     const trimmed = line.trim();
@@ -126,13 +117,16 @@ async function handleLine(line) {
         }
         return;
     }
-    // Watch tools/call traffic for claims/releases (request args + result).
+    // Watch tools/call traffic for claims/releases (request args + result), and
+    // flag the workspace-key fallback on whoami so the AGENT sees the degraded
+    // state (RTSC-143) — the startup stderr warning only reaches the MCP logs.
     if (msg.method === "tools/call" && resp) {
         applyObservation(leases, {
             toolName: msg.params?.name,
             args: msg.params?.arguments,
-            result: toolResult(resp),
+            result: toolResult(resp, msg.params?.name),
         });
+        appendFallbackNotice(msg.params?.name, resp, sessionKeyFallback);
     }
     // Relay the response (requests have an id; notifications don't).
     if (resp != null && msg.id !== undefined) {
@@ -143,7 +137,7 @@ async function heartbeatAll() {
     for (const [issueId, token] of [...leases]) {
         try {
             const resp = await postRemote(heartbeatRequest(hbSeq--, issueId, token));
-            if (isClaimLost(toolResult(resp))) {
+            if (isClaimLost(toolResult(resp, "heartbeat"))) {
                 leases.delete(issueId);
                 log(`lease for ${issueId} is gone — stopped tracking`);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retasc/cli",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Retasc CLI — sign in with GitHub, create projects, mint agent API keys, and wire your agent to the Retasc MCP server in one command.",
   "type": "module",
   "bin": {