@retasc/cli 1.34.1 → 1.35.0

package/CHANGELOG.md

@@ -6,6 +6,29 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.35.0 (2026-08-25)
+
+- **RTSC-709** — `retasc issue show` and `retasc issue list` read the queue from a
+  terminal. `tidy` and `done` both reason about issue status, and until now a human asked
+  to accept their verdict had no way to see that status without opening the Dash. Both
+  default to the current `rtsc-NN/` branch's issue, `list` takes the same filters the MCP
+  surface does (status, priority, label, author, assignee, SLA, limit), and both take
+  `--json`.
+- **RTSC-709** — `retasc checkpoint` and `retasc check-claim` close the claim lifecycle.
+  `claim`, `next`, `release` and `done` all existed, so a human could take work, hand it
+  back and finish it, but could not record progress on it or answer the question
+  `workflow.md` says to settle at runtime: is anything actually renewing my lease?
+  `check-claim` prints the last renewal time and exits non-zero when you do not hold the
+  issue, so a script can branch on it.
+- **RTSC-709** — `done` reads the issue back before it closes it. It was one word that
+  closed an issue with no read path to confirm first, and it closed one whose PR was still
+  open and unreviewed. It now prints the id, the title, the status transition and whether
+  the branch is merged, and asks before closing on a TTY. `--dry-run` shows the readback
+  and the teardown plan without touching anything, `-y` skips the prompt, and a non-TTY
+  still closes, so scripts are unchanged.
+- **RTSC-709** — `cli/README.md` now records which MCP tools are deliberately Dash-and-MCP-only,
+  and why, so their absence from the CLI reads as a decision rather than an oversight.
+
 ## 1.34.1 (2026-08-25)
 
 - **RTSC-741** — a rejected write no longer costs you the lease. The watchdog decided

package/README.md

@@ -57,6 +57,10 @@ Run `retasc whoami` (shows this folder's binding) or `retasc doctor` (checks it)
   them.
 - **A persistent, multi-tenant, identity-bearing store** of human-legible work.
 
+The CLI speaks the same lease: `retasc claim`, `retasc checkpoint`, `retasc check-claim`,
+`retasc release` and `retasc done` are the human forms of the tools an agent calls, over
+this folder's own key. A person and an agent working the same queue see the same rows.
+
 ## Common commands
 
 | Command | What it does |
@@ -72,8 +76,52 @@ Run `retasc whoami` (shows this folder's binding) or `retasc doctor` (checks it)
 | `retasc gate install` | Install a commit↔issue traceability gate in a repo |
 | `retasc config` | Show the resolved CLI config (paths + endpoints) |
 
+Working an issue from the terminal:
+
+| Command | What it does |
+|---------|--------------|
+| `retasc claim [issue]` / `retasc next` | Claim an issue (or the next unblocked one) and drop into a fresh worktree |
+| `retasc issue show [issue]` | Show one issue in full (defaults to the current `rtsc-NN/` branch's issue) |
+| `retasc issue list` | List issues, filtered by status, priority, label, author, assignee or SLA state |
+| `retasc checkpoint [issue]` | Record a handoff note on your claimed issue, and renew its lease |
+| `retasc check-claim [issue]` | Does this session still hold the lease, and is anything renewing it? |
+| `retasc release <issue>` | Hand a claim back to the queue. Leaves your worktree and branch alone |
+| `retasc done` | Close the issue and tear down its worktree + branch (asks first; `--dry-run` previews) |
+| `retasc tidy` | Reconcile `rtsc-NN/*` branches against issue status; reap the done + merged ones |
+
 Run `retasc --help` or `retasc <command> --help` for the full set.
 
+## What the CLI deliberately does not do
+
+The MCP server exposes 49 tools. The CLI has commands for 27 of them, and the gap is a decision
+rather than a backlog (RTSC-709). The CLI's job is to sign you in, set up a workspace, and
+let a **human** take, track and close a piece of work at a terminal. Everything else is for
+the **agent** (over MCP, where it already is) or the **Dash** (where a person can see it).
+
+So these have no CLI command, on purpose:
+
+| Area | Tools | Why not here |
+|------|-------|--------------|
+| Comments | `save_comment`, `list_comments`, `retract_comment` | A thread is something you read, not something you page through a terminal. Agents comment over MCP; people comment in the Dash |
+| Attachments | `save_attachment`, `list_attachments`, `get_attachment`, `get_attachment_file`, `save_attachment_file`, `prepare_attachment_upload`, `obsolete_attachment` | Binary in, binary out. The Dash previews them; a terminal can only tell you they exist. `retasc proxy` already serves these for your agent, which is who attaches things |
+| Dependency graph | `add_relation`, `remove_relation` | Editing the graph is planning work, and planning wants the whole graph in front of you |
+| Labels | `save_label`, `list_labels` | Org-wide taxonomy, set once in the Dash |
+| Wave dispatch | `next_batch` | It claims N issues at once for a fleet. One human at one terminal takes one issue: that is `retasc claim` |
+| Queue diagnosis | `queue_status` | The Dash queue view is this, with the graph drawn |
+| Member state | `suspend_member`, `reactivate_member` | Owner administration, next to the rest of it in the Dash |
+| Projects | `get_project`, `list_projects` | A workspace is bound to exactly one project (`retasc whoami` says which). Listing the others is a Dash question |
+| Connectors | `list_connectors`, `revoke_connector` | OAuth-shaped setup, done where the OAuth happens |
+
+Two more are reachable but not as their own command, which is also deliberate:
+
+- **`heartbeat`** — `retasc checkpoint` renews the lease and leaves the note that makes a
+  handoff resumable. A bare renewal with nothing to say is the watchdog's job, and
+  `retasc bind` wires that up for you.
+- **`get_issue`** — it is what `retasc issue show` and `retasc tidy` call.
+
+If you want any of the above from a terminal anyway, say so in an issue: the point of this
+list is that their absence is a choice we wrote down, not one nobody has noticed.
+
 ## Links
 
 - Website — [retasc.com](https://retasc.com)

package/dist/commands/claim.js

@@ -1,7 +1,7 @@
 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, normalizeIssueId, workspacePrefix, } from "../lib/claim.js";
+import { resolveMcpConn, readMcpJson, mcpCall, parseClaimResult, planWorktree, isValidIssueId, normalizeIssueId, resolveIssueRef, } from "../lib/claim.js";
 import { loadConfig } from "../config.js";
 function git(args, cwd) {
     return spawnSync("git", args, { encoding: "utf8", cwd });
@@ -35,8 +35,10 @@ export async function claimAction(opts) {
     // 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;
+    // RTSC-709: the expansion rule itself now lives in lib/claim.ts (`resolveIssueRef`),
+    // shared with `issue show` / `checkpoint` / `check-claim`. The cache keeps this loop to
+    // a single `whoami` when both forms are passed, exactly as the inline version did.
+    const prefixCache = { fallback: () => loadConfig().defaultProjectPrefix };
     let requestedId;
     for (const [label, raw] of [
         ["issue", opts.issueArg],
@@ -46,26 +48,16 @@ export async function claimAction(opts) {
         // 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).`);
-            }
+        const resolved = await resolveIssueRef(conn, raw, prefixCache);
+        if (resolved.error) {
+            note(`✗ ${resolved.error}`);
             process.exit(1);
         }
-        if (requestedId && requestedId !== norm) {
-            note(`✗ Conflicting issue ids: positional "${requestedId}" vs ${label} "${norm}". Pass just one.`);
+        if (requestedId && requestedId !== resolved.id) {
+            note(`✗ Conflicting issue ids: positional "${requestedId}" vs ${label} "${resolved.id}". Pass just one.`);
             process.exit(1);
         }
-        requestedId = norm;
+        requestedId = resolved.id;
     }
     // --all-lanes widens the next_issue pull; on a targeted claim it would be
     // silently ignored — reject instead of letting the intent evaporate.

package/dist/commands/issue.js

@@ -0,0 +1,163 @@
+import { spawnSync } from "node:child_process";
+import { resolveMcpConn, readMcpJson, mcpCall, resolveIssueRef, isValidIssueId, } from "../lib/claim.js";
+import { issueIdFromBranch } from "../lib/tidy.js";
+import { loadConfig } from "../config.js";
+import { issueView, issueListView, claimStatusView } from "../lib/format.js";
+// RTSC-709 — the read half of the claim lifecycle.
+//
+// The CLI could claim work, release it and close it, but never SHOW it. That gap is
+// load-bearing in two places: `retasc tidy` gives a verdict per branch derived from issue
+// status, and `retasc done` writes a terminal status, and a human judging either had to
+// open the Dash to see what they were judging. `checkpoint` and `check-claim` are the same
+// gap on the lease: you could take a lease and hand it back, but not record progress on it
+// or ask whether anything was still renewing it.
+//
+// Everything here is a thin pass to the MCP tool of the same name over the workspace's own
+// key, so the CLI and the agent read exactly the same rows. The formatting lives in
+// lib/format.ts, pure and pinned by tests.
+/** The workspace's MCP connection, or a message naming how to get one. */
+function conn() {
+    const c = resolveMcpConn({ mcpJson: readMcpJson() });
+    if (!c.key) {
+        throw new Error("No Retasc MCP key found for this folder.\n" +
+            "  Run `retasc bind` here (or `retasc mcp install`), or set RETASC_MCP_KEY.");
+    }
+    return c;
+}
+function currentBranch() {
+    const r = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8" });
+    return r.status === 0 ? (r.stdout ?? "").trim() || null : null;
+}
+/**
+ * The issue this command is about: what was typed, or the one the current `rtsc-NN/`
+ * branch is for.
+ *
+ * The branch fallback is the same one `retasc done` uses, and it is the form that matters
+ * in a worktree: you are standing in the checkout for exactly one issue, and naming it
+ * again is a chance to name the wrong one.
+ */
+async function targetIssue(c, raw) {
+    if (raw !== undefined) {
+        const cache = { fallback: () => loadConfig().defaultProjectPrefix };
+        const resolved = await resolveIssueRef(c, raw, cache);
+        if (resolved.error !== undefined)
+            throw new Error(resolved.error);
+        return resolved.id;
+    }
+    const branch = currentBranch();
+    const fromBranch = branch ? issueIdFromBranch(branch) : null;
+    if (!fromBranch || !isValidIssueId(fromBranch)) {
+        throw new Error("Which issue? Pass one (e.g. RTSC-42), or run this from its `rtsc-NN/` branch.");
+    }
+    return fromBranch;
+}
+// --- issue show / issue list ------------------------------------------------
+export async function issueShowAction(opts) {
+    const c = conn();
+    const identifier = await targetIssue(c, opts.issueArg);
+    const issue = (await mcpCall(c, "get_issue", { identifier }));
+    console.log(opts.json ? JSON.stringify(issue, null, 2) : issueView(issue));
+}
+// A local copy of the server's `STATUS` union (convex/schema.ts), kept so a typo fails
+// here with the list in it instead of as a validator error from the wire. It is drift-
+// guarded: convex/cliStatusDrift709.test.ts fails if the two ever disagree.
+const STATUSES = ["todo", "doing", "blocked", "review", "done", "canceled"];
+const SLA_STATES = ["ok", "warning", "breaching", "breached"];
+export async function issueListAction(opts) {
+    const args = {};
+    if (opts.status) {
+        // Comma-separated because the server takes one status or many, and a filter you can
+        // only pass one value to is the reason someone goes back to the Dash.
+        const wanted = opts.status.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+        const bad = wanted.filter((s) => !STATUSES.includes(s));
+        if (bad.length) {
+            throw new Error(`Unknown status: ${bad.join(", ")}. Pick from ${STATUSES.join(" | ")}.`);
+        }
+        args.status = wanted.length === 1 ? wanted[0] : wanted;
+    }
+    if (opts.priority !== undefined) {
+        const p = Number(opts.priority);
+        // NaN would reach the server as `null` and silently widen the filter to everything.
+        if (!Number.isInteger(p) || p < 0 || p > 4)
+            throw new Error("--priority takes 0..4 (0 = none, 1 = urgent).");
+        args.priority = p;
+    }
+    if (opts.sla) {
+        const s = opts.sla.trim().toLowerCase();
+        if (!SLA_STATES.includes(s)) {
+            throw new Error(`Unknown --sla: ${opts.sla}. Pick from ${SLA_STATES.join(" | ")}.`);
+        }
+        args.slaState = s;
+    }
+    if (opts.limit !== undefined) {
+        const n = Number(opts.limit);
+        if (!Number.isInteger(n) || n < 1)
+            throw new Error("--limit takes a positive whole number (max 200).");
+        args.limit = n;
+    }
+    for (const k of ["label", "author", "assignee"])
+        if (opts[k])
+            args[k] = opts[k];
+    const res = (await mcpCall(conn(), "list_issues", args));
+    if (opts.json) {
+        console.log(JSON.stringify(res, null, 2));
+        return;
+    }
+    const rows = Array.isArray(res?.issues) ? res.issues : [];
+    console.log(issueListView(rows));
+    // The default filter hides done + canceled, so a short list is not necessarily a small
+    // project. Say which set was counted rather than letting the number imply the whole one.
+    if (rows.length) {
+        console.log("");
+        console.log(`${rows.length} issue${rows.length === 1 ? "" : "s"}${opts.status ? "" : " (active work; done and canceled are hidden, pass --status to include them)"}.`);
+    }
+}
+// --- checkpoint / check-claim ----------------------------------------------
+/**
+ * `retasc checkpoint [issue] --note … --claim-token …`
+ *
+ * The lease half of the gap. `workflow.md` tells a worker to checkpoint at any long-silence
+ * boundary, and until now that instruction could only be followed by an agent: a human at a
+ * terminal could take a lease and give it back, but not leave the note the next holder
+ * resumes from. It renews the lease too, which is the other reason to run it.
+ */
+export async function checkpointAction(opts) {
+    if (!opts.note?.trim()) {
+        throw new Error("A checkpoint needs a note: `retasc checkpoint --note \"what's done / what's next\"`.");
+    }
+    // Fenced by the server on claim_token (only the holder may write the note), and the CLI
+    // stores no tokens, so refusing here with the reason beats sending a call that comes back
+    // as a fence error with no context. Same contract as `retasc release`.
+    if (!opts.claimToken) {
+        throw new Error("Checkpointing needs the issue's claim token: `retasc checkpoint --claim-token <token>`.\n" +
+            "  The token is printed when you claim, and is in the `--json` output of `retasc claim`.\n" +
+            "  It proves you are the session holding the lease, which is what stops one agent\n" +
+            "  overwriting another's handoff note.");
+    }
+    const c = conn();
+    const identifier = await targetIssue(c, opts.issueArg);
+    const res = (await mcpCall(c, "checkpoint", {
+        identifier,
+        note: opts.note,
+        claimToken: opts.claimToken,
+    }));
+    console.log(`✓ Checkpointed ${identifier}.`);
+    if (typeof res?.claimExpiresAt === "number") {
+        const mins = Math.round((res.claimExpiresAt - Date.now()) / 60000);
+        console.log(`  Lease renewed, ${mins}m left. The note survives a release or a reclaim.`);
+    }
+}
+/**
+ * `retasc check-claim [issue]`
+ *
+ * Read-only. Exits non-zero when this session does not hold the lease, so it can gate the
+ * thing its own tool description tells you to gate: `retasc check-claim && git commit …`.
+ */
+export async function checkClaimAction(opts) {
+    const c = conn();
+    const identifier = await targetIssue(c, opts.issueArg);
+    const res = (await mcpCall(c, "check_claim", { identifier }));
+    console.log(opts.json ? JSON.stringify(res, null, 2) : claimStatusView(res));
+    if (!res?.youHold)
+        process.exitCode = 1;
+}

package/dist/commands/tidy.js

@@ -2,6 +2,8 @@ import { spawnSync } from "node:child_process";
 import { dirname, resolve, sep } from "node:path";
 import { resolveMcpConn, readMcpJson, mcpCall, isValidIssueId } from "../lib/claim.js";
 import { issueIdFromBranch, classifyBranch, parseWorktreePorcelain, } from "../lib/tidy.js";
+import { confirm, isInteractive } from "../lib/prompt.js";
+import { doneReadback } from "../lib/format.js";
 // `retasc tidy` / `retasc done` (RTSC-93). The CLI already creates the worktree +
 // branch on claim (commands/claim.ts); this closes the loop — it tears them down
 // when the issue is done, reading status read-only from the control plane and
@@ -37,6 +39,14 @@ function setup() {
     const currentBranch = gitOut(["rev-parse", "--abbrev-ref", "HEAD"]);
     return { conn, mainCheckout, currentBranch };
 }
+/** Short ref names under a refspec (`origin/` stripped when asked). */
+function refList(mainCheckout, refspec, strip) {
+    return (gitOut(["for-each-ref", "--format=%(refname:short)", refspec], mainCheckout) ?? "")
+        .split("\n")
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((s) => (strip ? s.replace(strip, "") : s));
+}
 /** Build the reconciled branch table: every issue-shaped branch (local ∪ remote)
  *  joined with its issue status (read-only) and merged-into-main state. */
 async function scan(ctx, only) {
@@ -48,13 +58,8 @@ async function scan(ctx, only) {
     for (const w of worktrees)
         if (w.branch)
             wtByBranch.set(w.branch, w.path);
-    const refList = (refspec, strip) => (gitOut(["for-each-ref", "--format=%(refname:short)", refspec], mainCheckout) ?? "")
-        .split("\n")
-        .map((s) => s.trim())
-        .filter(Boolean)
-        .map((s) => (strip ? s.replace(strip, "") : s));
-    const locals = refList("refs/heads/");
-    const remotes = refList("refs/remotes/origin/", "origin/").filter((b) => b !== "HEAD");
+    const locals = refList(mainCheckout, "refs/heads/");
+    const remotes = refList(mainCheckout, "refs/remotes/origin/", "origin/").filter((b) => b !== "HEAD");
     const localSet = new Set(locals);
     const remoteSet = new Set(remotes);
     let branches = [...new Set([...locals, ...remotes])]
@@ -223,35 +228,98 @@ export async function tidyAction(opts) {
     if (failed)
         process.exitCode = 1; // let scripts/CI see a partial failure
 }
+/**
+ * Is every branch for this issue already on origin/main? null when it has no branch here.
+ *
+ * Pessimistic on purpose: if ANY branch for the issue is unmerged, this says unmerged. The
+ * readback exists to stop a close over open work, so the cautious answer is the true one.
+ */
+function issueBranchMerged(ctx, issueId) {
+    const locals = refList(ctx.mainCheckout, "refs/heads/");
+    const remotes = refList(ctx.mainCheckout, "refs/remotes/origin/", "origin/").filter((b) => b !== "HEAD");
+    const remoteSet = new Set(remotes);
+    const branches = [...new Set([...locals, ...remotes])].filter((b) => issueIdFromBranch(b) === issueId);
+    if (branches.length === 0)
+        return null;
+    return branches.every((b) => git(["merge-base", "--is-ancestor", remoteSet.has(b) ? `origin/${b}` : b, BASE], ctx.mainCheckout)
+        .status === 0);
+}
 /**
  * `retasc done` — the symmetric close to `retasc claim`: mark the current issue
  * (from the `rtsc-NN/` branch, or --id) done, then tear down its worktree+branch.
  * Run it after the PR merges; an unmerged branch is kept (reported as an orphan)
  * unless you pass --force. Run from the main checkout for full teardown — from
  * inside the worktree it can't remove the tree you're standing in.
+ *
+ * RTSC-709 — it reads the issue back and asks before closing it. This command writes a
+ * terminal status from a single word, and it shipped with nothing in front of that write:
+ * a stray `retasc done` closed RTSC-706 while its PR was open and unreviewed, printed a
+ * tick, and went on to offer branch deletion. `tidy` already asks before it deletes a
+ * branch; closing an issue is the less reversible of the two.
+ *
+ * The prompt is skipped when stdin is not a TTY, so scripts and CI keep working exactly as
+ * before — the accident this guards against is a human typing a word, and a pipeline that
+ * hangs on a question nobody can answer is a worse failure than the one being fixed.
  */
 export async function doneAction(opts) {
-    const conn = resolveMcpConn({ mcpJson: readMcpJson() });
-    if (!conn.key) {
-        note("✗ No Retasc MCP key found. Run `retasc mcp install`, or set RETASC_MCP_KEY.");
-        process.exit(1);
-    }
-    const currentBranch = gitOut(["rev-parse", "--abbrev-ref", "HEAD"]);
+    // setup() resolves the MCP key AND the main checkout. Both are needed either way, and
+    // failing on a missing repo BEFORE the write beats closing the issue and then finding
+    // the teardown can't run.
+    const ctx = setup();
     // Normalize an explicit --id to the canonical uppercase form so `done --id rtsc-93`
     // matches the uppercased branch ids (and is sent canonically to save_issue).
-    const issueId = opts.id ? opts.id.toUpperCase() : currentBranch ? issueIdFromBranch(currentBranch) : null;
+    const issueId = opts.id
+        ? opts.id.toUpperCase()
+        : ctx.currentBranch
+            ? issueIdFromBranch(ctx.currentBranch)
+            : null;
     if (!issueId || !isValidIssueId(issueId)) {
         note("✗ Not on a rtsc-NN/ branch — pass --id <RTSC-NN>.");
         process.exit(1);
     }
+    // Refresh before judging merged-state: a stale origin/main reports merged work as
+    // unmerged, which is the warning that teaches people to ignore the warning.
+    git(["fetch", "origin", "--prune"], ctx.mainCheckout);
+    let issue = null;
     try {
-        await mcpCall(conn, "save_issue", { identifier: issueId, status: "done" });
+        issue = await mcpCall(ctx.conn, "get_issue", { identifier: issueId });
     }
     catch (e) {
-        note(`✗ Couldn't mark ${issueId} done: ${String(e?.message ?? e).split("\n")[0]}`);
-        process.exit(1);
+        // A failed read must not become a silent close. Say so, and let the confirmation
+        // below carry the decision with what little is known.
+        note(`⚠ Couldn't read ${issueId}: ${String(e?.message ?? e).split("\n")[0]}`);
+    }
+    note(doneReadback({ ...(issue ?? {}), id: issueId }, issueBranchMerged(ctx, issueId)));
+    if (opts.dryRun) {
+        note("");
+        note(`· Dry run: ${issueId} was NOT closed. Below is what the teardown would do.`);
+        note("");
+        await tidyAction({ force: opts.force, only: issueId });
+        return;
+    }
+    // Already done: go straight to the teardown. Re-sending the write would cost a metered
+    // write and bump updatedAt to say something changed when nothing did.
+    if (issue?.status === "done") {
+        note("");
+        note(`· ${issueId} is already done; tidying its branch.`);
+    }
+    else {
+        if (isInteractive() && !opts.yes) {
+            note("");
+            if (!(await confirm(`Close ${issueId} and tear down its branch?`))) {
+                note("· Nothing closed.");
+                return;
+            }
+        }
+        try {
+            await mcpCall(ctx.conn, "save_issue", { identifier: issueId, status: "done" });
+        }
+        catch (e) {
+            note(`✗ Couldn't mark ${issueId} done: ${String(e?.message ?? e).split("\n")[0]}`);
+            process.exit(1);
+        }
+        note(`✓ ${issueId} → done`);
     }
-    note(`✓ ${issueId} → done`);
     note("  tidying its branch…");
     await tidyAction({ prune: true, force: opts.force, only: issueId });
 }

package/dist/index.js

@@ -17,6 +17,7 @@ import { billingAction } from "./commands/billing.js";
 import { isNetworkError, readLocalBinding, resolveBinding } from "./lib/binding.js";
 import { whoamiView, orgCreatedView, projectCreatedView, keyListView, inviteListView, } from "./lib/format.js";
 import { tidyAction, doneAction } from "./commands/tidy.js";
+import { issueShowAction, issueListAction, checkpointAction, checkClaimAction, } from "./commands/issue.js";
 import { runProxy } from "./proxy.js";
 import { deviceLogin } from "./auth.js";
 import { api, formatError } from "./api.js";
@@ -620,7 +621,51 @@ program
     .description("Mark the current issue (rtsc-NN/ branch, or --id) done and tear down its worktree+branch.")
     .option("--id <RTSC-NN>", "The issue to close (default: derived from the current branch)")
     .option("--force", "Tear down even if the branch isn't merged into main yet")
+    // RTSC-709: a read before the write. `done` is one word that closes an issue, and it
+    // closed one whose PR was still open. --dry-run shows the readback and the teardown plan
+    // without touching anything; -y is for the human who already knows (scripts never prompt).
+    .option("--dry-run", "Show what would be closed and torn down, then stop")
+    .option("-y, --yes", "Skip the confirmation prompt")
     .action((opts) => doneAction(opts).catch(fail));
+// --- reading the queue from a terminal (RTSC-709) ---------------------------
+//
+// `tidy` and `done` both reason about issue status, and until these existed a human could
+// not see the status they were being asked to act on without opening the Dash.
+const issue = program.command("issue").description("Read issues from the terminal.");
+issue
+    .command("show [issue]")
+    .description("Show one issue in full (defaults to the current rtsc-NN/ branch's issue).")
+    .option("--json", "Emit the raw payload instead of the view.")
+    .allowExcessArguments(false)
+    .action((issueArg, opts) => issueShowAction({ issueArg, ...opts }).catch(fail));
+issue
+    .command("list")
+    .description("List issues in this folder's project. Defaults to active work.")
+    .option("--status <statuses>", "todo | doing | blocked | review | done | canceled (comma-separated)")
+    .option("--priority <0-4>", "Filter by priority (0 = none, 1 = urgent)")
+    .option("--label <name>", "Filter by label")
+    .option("--author <name|me>", "Filter by who created it")
+    .option("--assignee <name|me|none>", "Filter by the responsible human")
+    .option("--sla <state>", "ok | warning | breaching | breached")
+    .option("--limit <n>", "How many to return (default 50, max 200)")
+    .option("--json", "Emit the raw payload instead of the table.")
+    .action((opts) => issueListAction(opts).catch(fail));
+// --- the lease, from a terminal (RTSC-709) ----------------------------------
+program
+    .command("checkpoint [issue]")
+    .description("Record a handoff note on your claimed issue (and renew its lease).")
+    .option("--note <text>", "What's done, what's next, and the gotchas")
+    // Not a requiredOption, unlike `release`: commander's "required option not specified"
+    // can't say WHERE the token comes from, and the action's own error does.
+    .option("--claim-token <token>", "The claim token printed when you claimed it (the server fences on it)")
+    .allowExcessArguments(false)
+    .action((issueArg, opts) => checkpointAction({ issueArg, ...opts }).catch(fail));
+program
+    .command("check-claim [issue]")
+    .description("Does THIS session still hold the issue, and is anything renewing the lease? Exits non-zero if not.")
+    .option("--json", "Emit the raw payload instead of the view.")
+    .allowExcessArguments(false)
+    .action((issueArg, opts) => checkClaimAction({ issueArg, ...opts }).catch(fail));
 // --- config ----------------------------------------------------------------
 program
     .command("config")

package/dist/lib/claim.js

@@ -162,3 +162,20 @@ export async function mcpCall(conn, name, args = {}, fetchImpl = fetch) {
     }
     return toolResult(resp);
 }
+export async function resolveIssueRef(conn, raw, cache = {}, fetchImpl = fetch) {
+    const bare = /^\d+$/.test(raw.trim());
+    if (bare && !cache.resolved) {
+        cache.prefix = (await workspacePrefix(conn, fetchImpl)) ?? cache.fallback?.();
+        cache.resolved = true;
+    }
+    const norm = normalizeIssueId(raw, cache.prefix);
+    if (norm)
+        return { id: norm };
+    if (bare && !cache.prefix) {
+        return {
+            error: `"${raw}" is a bare number and the project prefix couldn't be resolved from this workspace.\n` +
+                `  Use the full id (e.g. RTSC-${raw.trim()}).`,
+        };
+    }
+    return { error: `"${raw}" doesn't look like an issue id (expected RTSC-NN or a bare number).` };
+}

package/dist/lib/format.js

@@ -163,3 +163,159 @@ export function inviteListView(rows) {
         i.status === "pending" ? day(i.expiresAt) : "—",
     ]), "No invites yet. Create one with `retasc members invite --org-id <id>`.");
 }
+/**
+ * Who a member is, in one phrase.
+ *
+ * An agent's `principal` is kept because it answers the question the name raises: three
+ * rows reading "Em de Vries's claude-code" are three sessions of one person, and without
+ * the principal a reader cannot tell an agent's name from a human's.
+ */
+export function memberRef(m, fallback = "none") {
+    if (!m || !m.name)
+        return fallback;
+    const name = clean(m.name);
+    return m.principal && m.principal !== m.name ? `${name} (for ${clean(m.principal)})` : name;
+}
+/**
+ * `clean()`, line by line, so newlines survive.
+ *
+ * `clean()` maps every control character to a space, and a newline is one, which is right
+ * for a name in a table and wrong for the two fields that are prose. A body run through it
+ * whole comes back as a single unreadable paragraph (caught the first time `issue show` was
+ * pointed at a real issue), and the body is the reason the command exists.
+ */
+function block(s) {
+    return String(s)
+        .split(/\r?\n/)
+        .map(clean)
+        .join("\n");
+}
+/**
+ * One issue, as a person reads it: the header line first, then the fields that decide
+ * whether to act on it, then the body.
+ *
+ * The body is printed in full rather than truncated. This command exists so `tidy` and
+ * `done` can be judged without the Dash, and a body cut off at N lines sends the reader
+ * straight back to the Dash for the rest.
+ */
+export function issueView(i, now = Date.now()) {
+    const rows = [
+        // Status first: it is the field `done` and `tidy` both turn on.
+        ["Status", clean(i.status ?? "—") + (i.work === false ? " (container, not claimable)" : "")],
+        ["Priority", clean(i.priorityLabel ?? (i.priority != null ? String(i.priority) : "—"))],
+        ["Assignee", memberRef(i.assignee)],
+        ["Author", memberRef(i.createdBy, "—")],
+    ];
+    if (i.labels?.length)
+        rows.push(["Labels", clean(i.labels.join(", "))]);
+    // Said only when true. "Blocked  no" on every issue is a line every reader learns to skip,
+    // and then misses on the one issue where it says yes.
+    if (i.blocked) {
+        const by = (i.blockedByOpen ?? []).map((b) => `${clean(b.id)} (${clean(b.status)})`).join(", ");
+        rows.push(["Blocked by", by || "yes"]);
+    }
+    if (i.dueAt != null)
+        rows.push(["Deadline", `${day(i.dueAt)}${i.slaState ? ` (${clean(i.slaState)})` : ""}`]);
+    rows.push(["Created", ago(i.createdAt, now)], ["Updated", ago(i.updatedAt, now)]);
+    if (i.reclaimCount)
+        rows.push(["Reclaimed", `${i.reclaimCount}×`]);
+    if (i.sourceUrl)
+        rows.push(["Source", clean(i.sourceUrl)]);
+    if (i.cancelReason)
+        rows.push(["Canceled", clean(i.cancelReason)]);
+    // The checkpoint is the handoff note, so it is shown whole, under its own label.
+    if (i.checkpoint?.note) {
+        const by = i.checkpoint.by ? ` by ${clean(i.checkpoint.by)}` : "";
+        rows.push(["Checkpoint", `${ago(i.checkpoint.at, now)}${by}\n${block(i.checkpoint.note)}`]);
+    }
+    const rel = i.relations ?? {};
+    for (const [label, ids] of [
+        ["Blocks", rel.blocks],
+        ["Blocked by", i.blocked ? undefined : rel.blockedBy],
+        ["Related", rel.related],
+        ["Duplicate of", rel.duplicateOf],
+    ]) {
+        if (ids?.length)
+            rows.push([label, clean(ids.join(", "))]);
+    }
+    const head = `${clean(i.id ?? "—")}  ${clean(i.title ?? "")}`.trimEnd();
+    const body = (i.body ?? "").trim();
+    return [head, "", labelled(rows), ...(body ? ["", block(body)] : [])].join("\n");
+}
+/**
+ * The compact list. Titles are not truncated: `list_issues` is already capped by `--limit`,
+ * and a title cut mid-sentence is the version a reader has to re-run the command to finish.
+ */
+export function issueListView(rows, now = Date.now()) {
+    return table(["ID", "STATUS", "PRIORITY", "ASSIGNEE", "UPDATED", "TITLE"], rows.map((r) => [
+        clean(r.id ?? "—"),
+        clean(r.status ?? "—"),
+        clean(r.priorityLabel ?? "—"),
+        // list_issues sends the assignee as a plain name; get_issue sends an object. Take both
+        // so one row shape can never render as "[object Object]".
+        typeof r.assignee === "string" ? clean(r.assignee) : memberRef(r.assignee, "—"),
+        ago(r.updatedAt, now),
+        // The SLA state rides on the title so a breaching issue cannot be skimmed past, and
+        // "ok" is omitted, which is every issue without a deadline.
+        `${r.slaState && r.slaState !== "ok" ? `[${clean(r.slaState)}] ` : ""}${clean(r.title ?? "")}`,
+    ]), "No issues match. Try `retasc issue list --status todo` or widen the filters.");
+}
+/**
+ * `check_claim`, rendered.
+ *
+ * `lastRenewedAt` is the whole point (RTSC-646): the CLI is where a human runs this twice
+ * across a long stretch to prove something is renewing the lease. So it is printed as a
+ * clock time AND as an elapsed one, because "17:42" is what you compare between two runs
+ * and "8m ago" is what tells you it moved.
+ */
+export function claimStatusView(c, now = Date.now()) {
+    const rows = [
+        ["Issue", clean(c.issue ?? "—")],
+        ["Holder", c.youHold ? "you (this session)" : clean(c.status ?? "—")],
+    ];
+    if (!c.youHold && c.heldBy) {
+        const h = c.heldBy;
+        const who = [h.holder && clean(h.holder), h.principal && `for ${clean(h.principal)}`, h.session && `session ${clean(h.session)}`]
+            .filter(Boolean)
+            .join(" · ");
+        if (who)
+            rows.push(["Held by", who]);
+    }
+    if (c.expiresAt != null) {
+        const left = Math.round((c.expiresAt - now) / 60000);
+        rows.push(["Expires", `${time(c.expiresAt)} (${left > 0 ? `in ${left}m` : "expired"})`]);
+    }
+    if (c.lastRenewedAt != null)
+        rows.push(["Last renewed", `${time(c.lastRenewedAt)} (${ago(c.lastRenewedAt, now)})`]);
+    const tail = c.status === "other_session"
+        ? // RTSC-658: the holder named above is often this human's own previous session, and the
+            // remedy is a re-claim, not waiting out the lease.
+            "\n\nA restart or /resume looks like a different session. If that holder was you,\nre-claim it with the same token: retasc claim " +
+                clean(c.issue ?? "<RTSC-NN>")
+        : c.lastRenewedAt != null && c.youHold
+            ? "\n\nRun this again later: a Last renewed that moved proves something is renewing you,\none frozen at claim time means nothing is."
+            : "";
+    return labelled(rows) + tail;
+}
+/** Wall-clock, local, for a lease you are comparing between two runs. */
+function time(ms) {
+    return new Date(ms).toTimeString().slice(0, 5);
+}
+/**
+ * The readback `retasc done` prints before it closes anything (RTSC-709).
+ *
+ * `done` is one word that writes a terminal status, and it shipped with no read path in
+ * front of it: it closed RTSC-706 while that PR was open and unreviewed, printed a tick,
+ * and moved on to offering branch deletion. This is the sentence that would have caught it.
+ */
+export function doneReadback(i, merged) {
+    const rows = [
+        ["Issue", `${clean(i.id ?? "—")}  ${clean(i.title ?? "")}`.trimEnd()],
+        ["Status", `${clean(i.status ?? "—")} → done`],
+    ];
+    if (i.assignee)
+        rows.push(["Assignee", memberRef(i.assignee)]);
+    if (merged !== null)
+        rows.push(["Branch", merged ? "merged into origin/main" : "NOT merged into origin/main"]);
+    return labelled(rows);
+}

package/package.json

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