@retasc/cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Retasc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# retasc
+
+**The issue tracker AI agents pull work from.**
+
+Over [MCP](https://modelcontextprotocol.io), a heterogeneous fleet of agents atomically
+claims unblocked, prioritized tasks and runs in parallel — server-enforced, no collisions.
+Issues live in a persistent, multi-tenant store; agents reach them through one MCP endpoint.
+The `retasc` CLI signs you in, creates projects, mints agent API keys, and wires the MCP
+server into your agent in a single command.
+
+→ [retasc.com](https://retasc.com)
+
+## Install
+
+```sh
+npm i -g @retasc/cli
+```
+
+This installs the `retasc` command. Requires Node.js ≥ 18.
+
+## Quickstart
+
+```sh
+# 1. Sign in with GitHub (device flow)
+retasc login
+
+# 2. Create an org + project, mint an agent key, and wire it into your agent — one shot
+retasc init --org "Acme" --project "Acme" --prefix ACME
+
+# 3. Your agent (e.g. Claude Code) can now pull work over MCP
+```
+
+`retasc init` creates the org and project, mints an agent API key, and registers the Retasc
+MCP server with your agent (writing `.mcp.json` or registering with Claude Code). From then on
+your agent calls `next_issue` / `next_batch` to atomically claim the top unblocked, prioritized
+work — and several agents can run at once without ever claiming the same issue.
+
+## What the agent gets over MCP
+
+- **Atomic claim + lease/TTL + fencing** — concurrency control on work items, so no two agents
+  take the same issue. A claim is a lease; `heartbeat` keeps it alive, `checkpoint` records
+  progress, and a reclaimer frees stalled leases so the next agent resumes from the checkpoint.
+- **Dependency-graph-driven dispatch** — `next_issue`, `next_batch`, and effective priority. A
+  blocker inherits the urgency of everything it gates, so agents just take what the queue hands
+  them.
+- **A persistent, multi-tenant, identity-bearing store** of human-legible work.
+
+## Common commands
+
+| Command | What it does |
+|---------|--------------|
+| `retasc login` / `retasc logout` | Sign in / out (GitHub device flow) |
+| `retasc whoami` | Show the signed-in user and their orgs |
+| `retasc init …` | Create org + project, mint a key, wire the MCP — one shot |
+| `retasc org create` / `retasc project create` | Create orgs / projects |
+| `retasc key mint \| list \| rotate \| revoke` | Manage agent API keys |
+| `retasc mcp install` | Register the Retasc MCP server with your agent |
+| `retasc gate install` | Install a commit↔issue traceability gate in a repo |
+| `retasc config` | Show the resolved CLI config (paths + endpoints) |
+
+Run `retasc --help` or `retasc <command> --help` for the full set.
+
+## Links
+
+- Website — [retasc.com](https://retasc.com)
+- Issues — [github.com/Retasc/retasc/issues](https://github.com/Retasc/retasc/issues)
+
+## License
+
+MIT

package/dist/api.js

@@ -0,0 +1,33 @@
+import { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+import { loadConfig } from "./config.js";
+// Typed-ish references to the public management functions in convex/manage.ts.
+// The CLI is a standalone package, so we reference functions by name rather than
+// importing the parent's generated api.
+const fns = {
+    me: makeFunctionReference("manage:me"),
+    createOrg: makeFunctionReference("manage:createOrg"),
+    createProject: makeFunctionReference("manage:createProject"),
+    renameProjectPrefix: makeFunctionReference("manage:renameProjectPrefix"),
+    listKeys: makeFunctionReference("manage:listKeys"),
+    mintKey: makeFunctionReference("manage:mintKey"),
+    rotateKey: makeFunctionReference("manage:rotateKey"),
+    revokeKey: makeFunctionReference("manage:revokeKey"),
+};
+function client() {
+    const cfg = loadConfig();
+    const c = new ConvexHttpClient(cfg.deploymentUrl);
+    if (cfg.token)
+        c.setAuth(cfg.token);
+    return c;
+}
+export const api = {
+    me: () => client().query(fns.me, {}),
+    createOrg: (args) => client().mutation(fns.createOrg, args),
+    createProject: (args) => client().mutation(fns.createProject, args),
+    renameProjectPrefix: (args) => client().mutation(fns.renameProjectPrefix, args),
+    listKeys: (args) => client().query(fns.listKeys, args),
+    mintKey: (args) => client().action(fns.mintKey, args),
+    rotateKey: (args) => client().action(fns.rotateKey, args),
+    revokeKey: (args) => client().mutation(fns.revokeKey, args),
+};

package/dist/auth.js

@@ -0,0 +1,78 @@
+import { ConvexHttpClient } from "convex/browser";
+import { makeFunctionReference } from "convex/server";
+import { loadConfig, patchConfig } from "./config.js";
+// The GitHub OAuth App's PUBLIC client id (safe to ship — device flow needs no
+// secret). Baked in so `retasc login` works out-of-the-box; override via env.
+const GITHUB_CLIENT_ID = process.env.RETASC_GITHUB_CLIENT_ID ?? "Ov23linqRy875IU8OYTW";
+const DEVICE_CODE_URL = "https://github.com/login/device/code";
+const TOKEN_URL = "https://github.com/login/oauth/access_token";
+const GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+// Convex Auth's own public sign-in action. We call it with the "github-device"
+// credentials provider; it verifies the GitHub token server-side and returns a
+// session ({ tokens: { token, refreshToken } }).
+const signIn = makeFunctionReference("auth:signIn");
+async function postForm(url, body) {
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+        body: new URLSearchParams(body).toString(),
+    });
+    return res.json();
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Run the full GitHub device-flow login and persist the resulting Convex Auth
+ * session to ~/.retasc/config.json. Prints the user code + verification URL.
+ */
+export async function deviceLogin() {
+    if (!GITHUB_CLIENT_ID) {
+        throw new Error("GitHub client id not configured. Set RETASC_GITHUB_CLIENT_ID (the OAuth App's public Client ID).");
+    }
+    const start = await postForm(DEVICE_CODE_URL, {
+        client_id: GITHUB_CLIENT_ID,
+        scope: "read:user user:email",
+    });
+    if (!start.device_code) {
+        throw new Error(`GitHub device-flow start failed: ${JSON.stringify(start)}`);
+    }
+    console.log(`\n  Open: ${start.verification_uri}`);
+    console.log(`  Enter code: ${start.user_code}\n`);
+    console.log("  Waiting for authorization…");
+    // Poll GitHub for the access token.
+    let intervalMs = (start.interval || 5) * 1000;
+    const deadline = Date.now() + start.expires_in * 1000;
+    let githubToken = "";
+    while (Date.now() < deadline) {
+        await sleep(intervalMs);
+        const r = await postForm(TOKEN_URL, {
+            client_id: GITHUB_CLIENT_ID,
+            device_code: start.device_code,
+            grant_type: GRANT,
+        });
+        if (r.access_token) {
+            githubToken = r.access_token;
+            break;
+        }
+        if (r.error === "authorization_pending")
+            continue;
+        if (r.error === "slow_down") {
+            intervalMs += 5000;
+            continue;
+        }
+        throw new Error(`GitHub authorization failed: ${r.error_description ?? r.error}`);
+    }
+    if (!githubToken)
+        throw new Error("Timed out waiting for GitHub authorization.");
+    // Exchange the GitHub token for a Retasc (Convex Auth) session.
+    const cfg = loadConfig();
+    const convex = new ConvexHttpClient(cfg.deploymentUrl);
+    const res = await convex.action(signIn, {
+        provider: "github-device",
+        params: { githubToken },
+    });
+    const tokens = res?.tokens;
+    if (!tokens?.token) {
+        throw new Error("Sign-in did not return a session token.");
+    }
+    patchConfig({ token: tokens.token, refreshToken: tokens.refreshToken });
+}

package/dist/commands/claim.js

@@ -0,0 +1,174 @@
+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";
+function git(args, cwd) {
+    return spawnSync("git", args, { encoding: "utf8", cwd });
+}
+function gitOut(args, cwd) {
+    const r = git(args, cwd);
+    if (r.status !== 0)
+        return null;
+    return (r.stdout ?? "").trim();
+}
+/** stderr so --print-path / --json keep stdout machine-clean. */
+function note(msg) {
+    process.stderr.write(msg + "\n");
+}
+/**
+ * `retasc claim` / `retasc next`: atomically claim an issue over the workspace's
+ * own MCP key, then create + drop you into a correctly-named git worktree
+ * (`../<repo>-rtsc-NN` on branch `rtsc-NN/<slug>`). Makes isolation the path of
+ * least resistance (RTSC-38) so two sessions can't silently share a checkout.
+ */
+export async function claimAction(opts) {
+    const conn = resolveMcpConn({ mcpJson: readMcpJson() });
+    if (!conn.key) {
+        note("✗ No Retasc MCP key found. Run `retasc init` / `retasc mcp install`, or set RETASC_MCP_KEY.");
+        note("  (Looked at $RETASC_MCP_KEY and ./.mcp.json.)");
+        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.
+    let parentDir = opts.dir;
+    let repoName = "repo";
+    let inLinkedWorktree = false;
+    if (makeWorktree) {
+        const commonDir = gitOut(["rev-parse", "--git-common-dir"]);
+        const gitDir = gitOut(["rev-parse", "--git-dir"]);
+        if (!commonDir || !gitDir) {
+            note("✗ Not inside a git repository — can't create a worktree.");
+            note("  Re-run from the repo, or pass --no-worktree to just claim.");
+            process.exit(1);
+        }
+        // --git-common-dir always points at the MAIN checkout's .git; --git-dir
+        // diverges (.git/worktrees/<name>) only inside a linked worktree.
+        inLinkedWorktree = resolve(gitDir) !== resolve(commonDir);
+        const mainCheckout = dirname(resolve(commonDir)); // <main>/.git → <main>
+        repoName = basename(mainCheckout);
+        parentDir = parentDir ?? dirname(mainCheckout);
+    }
+    // --- claim over MCP ------------------------------------------------------
+    let claim;
+    try {
+        const result = opts.id
+            ? await mcpCall(conn, "claim_issue", { identifier: opts.id })
+            : await mcpCall(conn, "next_issue", opts.mine ? { mine: true } : {});
+        claim = parseClaimResult(result);
+    }
+    catch (e) {
+        const msg = String(e?.message ?? e);
+        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.`);
+        }
+        process.exit(1);
+    }
+    if (!claim.issueId) {
+        // Empty next_issue — never a silent stall.
+        note("· Nothing to claim right now.");
+        if (claim.ready !== undefined) {
+            note(`  ready: ${claim.ready ?? 0}  blocked: ${claim.blocked ?? 0}  claimed: ${claim.claimed ?? 0}`);
+        }
+        process.exit(0);
+    }
+    // The id flows into a git ref and a filesystem path — reject a malformed one.
+    if (!isValidIssueId(claim.issueId)) {
+        note(`✗ Server returned an unexpected issue id: ${JSON.stringify(claim.issueId)}`);
+        process.exit(1);
+    }
+    // claim_issue returns just the id — fetch the title so the slug is meaningful.
+    let title = claim.title;
+    if (!title) {
+        try {
+            const full = (await mcpCall(conn, "get_issue", { identifier: claim.issueId }));
+            title = full?.title;
+        }
+        catch {
+            note(`⚠ Couldn't fetch the title for ${claim.issueId} — branch slug falls back to "issue".`);
+        }
+    }
+    const issueId = claim.issueId;
+    if (!makeWorktree) {
+        note(`✓ Claimed ${issueId}${title ? ` — ${title}` : ""}.`);
+        if (claim.claimToken)
+            note(`  claim token: ${claim.claimToken}`);
+        if (opts.json) {
+            console.log(JSON.stringify({ issueId, title, branch: null, path: null, claimToken: claim.claimToken }, null, 2));
+        }
+        return;
+    }
+    const plan = planWorktree({ issueId, title: title ?? "", repoName, parentDir: parentDir });
+    // Defense in depth: the derived worktree must stay under the parent dir.
+    if (plan.path !== resolve(parentDir) && !plan.path.startsWith(resolve(parentDir) + sep)) {
+        note(`✗ Refusing to create a worktree outside ${parentDir}: ${plan.path}`);
+        process.exit(1);
+    }
+    if (inLinkedWorktree) {
+        note("⚠ You're inside a linked worktree. Worktrees are still placed beside the main checkout,");
+        note("  but claiming from the main checkout keeps things tidy.");
+    }
+    // Reuse an existing worktree for this issue rather than failing (resumable).
+    if (existsSync(plan.path)) {
+        note(`✓ Claimed ${issueId} — worktree already exists, reusing it.`);
+        finish(plan.path, plan.branch, issueId, title, claim.claimToken, opts);
+        return;
+    }
+    // Best-effort refresh of the base so the worktree starts from current origin.
+    const base = opts.base ?? "origin/main";
+    if (opts.fetch !== false) {
+        const remoteBranch = base.startsWith("origin/") ? base.slice("origin/".length) : null;
+        const f = remoteBranch ? git(["fetch", "origin", remoteBranch]) : git(["fetch", "origin"]);
+        if (f.status !== 0)
+            note(`⚠ git fetch failed (${(f.stderr || "").trim().split("\n")[0]}); using local ${base}.`);
+    }
+    const add = git(["worktree", "add", plan.path, "-b", plan.branch, base]);
+    if (add.status !== 0) {
+        const err = (add.stderr || add.stdout || "").trim().split("\n")[0];
+        note(`✗ git worktree add failed: ${err}`);
+        // The claim succeeded but the worktree didn't — make the held lease actionable.
+        note(`  ${issueId} is claimed (yours)${claim.claimToken ? `; claim token: ${claim.claimToken}` : ""}.`);
+        if (/already (exists|checked out|used by worktree)/i.test(err)) {
+            note(`  The branch already exists — attach without -b: git worktree add ${plan.path} ${plan.branch}`);
+        }
+        else {
+            note(`  Resolve the error and retry, or \`retasc release ${issueId}\` to return it to the pool.`);
+        }
+        process.exit(1);
+    }
+    note(`✓ Claimed ${issueId}${title ? ` — ${title}` : ""}`);
+    note(`  worktree: ${plan.path}`);
+    note(`  branch:   ${plan.branch}`);
+    finish(plan.path, plan.branch, issueId, title, claim.claimToken, opts);
+}
+/** Emit machine output / drop into the worktree per the chosen flags. */
+function finish(path, branch, issueId, title, claimToken, opts) {
+    if (opts.json) {
+        console.log(JSON.stringify({ issueId, title, branch, path, claimToken }, null, 2));
+        return;
+    }
+    if (opts.printPath) {
+        // Only the path on stdout, for `cd "$(retasc claim --print-path)"`.
+        console.log(path);
+        return;
+    }
+    if (opts.shell) {
+        const shell = process.env.SHELL || "/bin/sh";
+        note(`↳ entering ${path} (exit the shell to return)`);
+        const r = spawnSync(shell, { stdio: "inherit", cwd: path });
+        if (r.error) {
+            note(`✗ couldn't start ${shell}: ${r.error.message}`);
+            note(`  cd ${path}`);
+            process.exit(1);
+        }
+        if (typeof r.status === "number" && r.status !== 0)
+            process.exit(r.status);
+        return;
+    }
+    note("");
+    note(`  cd ${path}`);
+}

package/dist/commands/gate.js

@@ -0,0 +1,135 @@
+import { spawnSync } from "node:child_process";
+import { mkdirSync, writeFileSync, existsSync, chmodSync } from "node:fs";
+import { join, dirname } from "node:path";
+// Mirror the server's project-prefix rule (convex/manage.ts PREFIX_RE): 2–10
+// chars, A–Z/0–9, letter-first. The prefix is interpolated into a generated
+// bash hook and a YAML grep, so validating here keeps a stray value from
+// writing a broken (or hostile) gate into the customer's repo.
+const PREFIX_RE = /^[A-Z][A-Z0-9]{1,9}$/;
+/** commit-msg hook body requiring `<PREFIX>-NN` or `[no-issue]`. */
+export function hookTemplate(prefix) {
+    return `#!/bin/bash
+# Require a ${prefix} issue reference (${prefix}-NN) or [no-issue] in commit messages.
+# Installed by \`retasc gate install\`. Enable with: git config core.hooksPath .githooks
+# Note: git does not run hooks on a fresh clone — each developer opts in once.
+# The authoritative gate is the check-commit-message GitHub Action (CI).
+
+MSG=$(cat "$1")
+
+if echo "$MSG" | grep -qiE '(${prefix}-[0-9]+|\\[no-issue\\])'; then
+  exit 0
+fi
+
+echo ""
+echo "ERROR: Commit message must reference a ${prefix} issue (${prefix}-NN) or include [no-issue]."
+echo ""
+echo "Examples:"
+echo '  feat: add wave dispatch'
+echo ''
+echo '  ${prefix}-12'
+echo ''
+echo '  docs: fix typo in README [no-issue]'
+echo ""
+exit 1
+`;
+}
+/** GitHub Action enforcing the reference on PR title/body. */
+export function actionTemplate(prefix) {
+    return `name: Check commit message
+# Installed by \`retasc gate install\`. The authoritative commit↔issue gate:
+# runs in CI on every PR, no per-developer setup, can't be bypassed.
+on:
+  pull_request:
+    types: [opened, synchronize, edited]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check for ${prefix} issue reference
+        env:
+          PR_TITLE: \${{ github.event.pull_request.title }}
+          PR_BODY: \${{ github.event.pull_request.body }}
+        run: |
+          if printf '%s %s' "$PR_TITLE" "$PR_BODY" | grep -qiE '(${prefix}-[0-9]+|\\[no-issue\\])'; then
+            echo "✓ ${prefix} issue reference found"
+            exit 0
+          fi
+
+          echo "ERROR: PR must reference a ${prefix} issue (${prefix}-NN) in title or description, or include [no-issue]."
+          exit 1
+`;
+}
+/** Locate the git repo root, or null if cwd isn't inside a working tree. */
+function repoRoot() {
+    const r = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" });
+    if (r.error || r.status !== 0)
+        return null;
+    const root = r.stdout.trim();
+    return root || null;
+}
+/** Point core.hooksPath at .githooks (relative to the repo root). */
+function setHooksPath(root) {
+    const r = spawnSync("git", ["config", "core.hooksPath", ".githooks"], {
+        cwd: root,
+        encoding: "utf8",
+    });
+    return !r.error && r.status === 0;
+}
+function writeFile(path, body, mode) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, body, "utf8");
+    if (mode !== undefined) {
+        try {
+            chmodSync(path, mode);
+        }
+        catch {
+            /* best effort (e.g. Windows) */
+        }
+    }
+}
+/**
+ * Install the commit↔issue gate into the current repo, parameterized by `prefix`.
+ * Writes the requested layers (hook and/or Action) and enables the hook path.
+ */
+export function installGate(opts) {
+    if (!PREFIX_RE.test(opts.prefix)) {
+        throw new Error(`invalid prefix '${opts.prefix}' — must be 2–10 chars, A–Z/0–9, letter-first (e.g. RTSC)`);
+    }
+    const root = repoRoot();
+    if (!root) {
+        throw new Error("not a git repository — run `git init` first, then re-run from the repo root");
+    }
+    const { hook, action } = opts.layers;
+    if (!hook && !action) {
+        throw new Error("nothing to install — drop --no-hook/--no-action or pick at least one layer");
+    }
+    if (hook) {
+        const hookPath = join(root, ".githooks", "commit-msg");
+        const existed = existsSync(hookPath);
+        writeFile(hookPath, hookTemplate(opts.prefix), 0o755);
+        const enabled = setHooksPath(root);
+        console.log(`✓ ${existed ? "Updated" : "Wrote"} commit-msg hook (.githooks/commit-msg).`);
+        if (enabled) {
+            console.log("  Enabled: git config core.hooksPath .githooks");
+        }
+        else {
+            console.log("  ⚠ Could not set core.hooksPath — run: git config core.hooksPath .githooks");
+        }
+    }
+    if (action) {
+        const actionPath = join(root, ".github", "workflows", "check-commit-message.yml");
+        const existed = existsSync(actionPath);
+        writeFile(actionPath, actionTemplate(opts.prefix));
+        console.log(`✓ ${existed ? "Updated" : "Wrote"} GitHub Action (.github/workflows/check-commit-message.yml).`);
+    }
+    console.log("");
+    console.log(`Gate is keyed to prefix "${opts.prefix}" — commits/PRs need ${opts.prefix}-NN or [no-issue].`);
+    if (action) {
+        console.log("The Action is the authoritative gate (runs in CI, no per-developer setup).");
+    }
+    if (hook) {
+        console.log("The hook is local fast-feedback only: opt-in per clone (git won't auto-install it) and bypassable with --no-verify.");
+    }
+    console.log("\nCommit the written files so the gate ships with the repo.");
+}

package/dist/commands/mcp.js

@@ -0,0 +1,122 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+export const SERVER_NAME = "retasc";
+/** The MCP server entry we wire into an agent's config. */
+export function mcpServerEntry(url, key) {
+    return {
+        type: "http",
+        url,
+        headers: { Authorization: `Bearer ${key}` },
+    };
+}
+/** A copy-pasteable .mcp.json block (always shown as a fallback). */
+export function mcpConfigBlock(url, key) {
+    return JSON.stringify({ mcpServers: { [SERVER_NAME]: mcpServerEntry(url, key) } }, null, 2);
+}
+/**
+ * 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
+ * claimed issues' leases alive automatically. url+key go via env (not a header,
+ * since this is a spawned command). Harness-agnostic: any stdio MCP client works.
+ */
+export function mcpProxyEntry(url, key) {
+    return {
+        command: "retasc",
+        args: ["mcp-proxy"],
+        env: { RETASC_MCP_URL: url, RETASC_MCP_KEY: key },
+    };
+}
+/** Copy-pasteable watchdog block for Codex / OpenCode / any stdio MCP client. */
+export function mcpProxyConfigBlock(url, key) {
+    return JSON.stringify({ mcpServers: { [SERVER_NAME]: mcpProxyEntry(url, key) } }, null, 2);
+}
+/** Try `claude mcp add`. Returns true on success, false if claude is absent or errored. */
+function tryClaudeCli(url, key, scope) {
+    const args = [
+        "mcp", "add",
+        "--transport", "http",
+        "--scope", scope,
+        SERVER_NAME, url,
+        "--header", `Authorization: Bearer ${key}`,
+    ];
+    return runClaudeAdd(args);
+}
+/** Try `claude mcp add` for the stdio watchdog proxy (RTSC-44). */
+function tryClaudeCliWatchdog(url, key, scope) {
+    const args = [
+        "mcp", "add",
+        "--transport", "stdio",
+        "--scope", scope,
+        "--env", `RETASC_MCP_URL=${url}`,
+        "--env", `RETASC_MCP_KEY=${key}`,
+        SERVER_NAME, "--", "retasc", "mcp-proxy",
+    ];
+    return runClaudeAdd(args);
+}
+function runClaudeAdd(args) {
+    const r = spawnSync("claude", args, { encoding: "utf8" });
+    if (r.error)
+        return false; // ENOENT — claude not installed
+    if (r.status !== 0) {
+        // Surface why it failed but don't throw — we fall back to the file.
+        const msg = (r.stderr || r.stdout || "").trim();
+        if (msg)
+            console.error(`  (claude mcp add: ${msg.split("\n")[0]})`);
+        return false;
+    }
+    return true;
+}
+/** Merge a given server entry into ./.mcp.json (project scope on disk). */
+function writeProjectMcpJson(entry) {
+    const path = join(process.cwd(), ".mcp.json");
+    let doc = {};
+    if (existsSync(path)) {
+        try {
+            doc = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            doc = {};
+        }
+    }
+    doc.mcpServers = doc.mcpServers ?? {};
+    doc.mcpServers[SERVER_NAME] = entry;
+    writeFileSync(path, JSON.stringify(doc, null, 2) + "\n", "utf8");
+    return path;
+}
+/**
+ * Wire the Retasc MCP server into the user's agent. Prefers the `claude` CLI;
+ * falls back to writing ./.mcp.json. Always prints the manual block so the user
+ * can paste it into any other MCP client.
+ */
+export function installMcp(opts) {
+    const scope = opts.scope ?? "user";
+    // Watchdog mode (RTSC-44): wire the stdio proxy so claims stay alive automatically.
+    if (opts.watchdog) {
+        const viaClaude = tryClaudeCliWatchdog(opts.url, opts.key, scope);
+        if (viaClaude) {
+            console.log(`✓ Registered Retasc with the liveness watchdog (stdio proxy, scope: ${scope}).`);
+        }
+        else {
+            const path = writeProjectMcpJson(mcpProxyEntry(opts.url, opts.key));
+            console.log(`✓ Wrote watchdog MCP config to ${path}`);
+            console.log("  (Claude Code CLI not detected or unavailable — used .mcp.json instead.)");
+        }
+        console.log("\nWatchdog MCP config (Codex / OpenCode / any stdio MCP client):\n");
+        console.log(mcpProxyConfigBlock(opts.url, opts.key));
+        console.log("\nThe watchdog keeps your claims alive automatically — no per-claim heartbeats. If it ever isn't running you just fall back to the normal lease timeout (safe).");
+        return;
+    }
+    const viaClaude = tryClaudeCli(opts.url, opts.key, scope);
+    if (viaClaude) {
+        console.log(`✓ Registered MCP server "${SERVER_NAME}" with Claude Code (scope: ${scope}).`);
+    }
+    else {
+        const path = writeProjectMcpJson(mcpServerEntry(opts.url, opts.key));
+        console.log(`✓ Wrote MCP config to ${path}`);
+        console.log("  (Claude Code CLI not detected or unavailable — used .mcp.json instead.)");
+    }
+    console.log("\nMCP config block (for any other agent/client):\n");
+    console.log(mcpConfigBlock(opts.url, opts.key));
+    console.log(`\nYour agent can now reach Retasc at ${opts.url}.`);
+}