@retasc/cli 1.39.3 → 1.40.0

package/CHANGELOG.md

@@ -6,6 +6,43 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.40.0 (2026-09-04)
+
+- **RTSC-820** — every session now tells Retasc which conversation it is. `retasc setup`
+  wires a Claude Code `SessionStart` hook (`retasc hook session-start`) into
+  `~/.claude/settings.json`, idempotently and beside whatever hooks you already have; the
+  hook leaves the session's id in the keystore dir, and the watchdog proxy picks it up and
+  records it on its session key through a new `record_session` tool. Grok needs no hook:
+  the proxy reads `GROK_SESSION_ID` at startup. The Dash's Agents page then ends each
+  session's panel with the line that reopens it on the machine that ran it,
+  `claude --resume <uuid>`. Only the NAME of the transcript is stored, never its
+  contents and never a path. A session started before `setup` re-ran shows
+  "none recorded" and names the missing hook.
+
+## 1.39.4 (2026-09-03)
+
+- **RTSC-810** — `retasc unbind` revokes the key it says it revokes. It had two faults in
+  one lookup, and each on its own was enough to leave the credential live: it destructured
+  `{ keys }` off `listKeys`, which returns a bare array, and it derived the folder's key
+  prefix with a 12-character slice while the server stores 14. An exact compare between a
+  12-character string and a 14-character one is never true, so every run since `unbind`
+  shipped (RTSC-721) printed "not found server-side (already revoked, or the org is
+  gone)" and moved on. The length now mirrors the server's own `displayPrefixOf`, and the
+  test reads that file, so the two cannot drift apart again. A session child key can no
+  longer be the one revoked either: those are minted in memory by the proxy and never
+  reach the keystore, so a match on one would mean revoking a key this folder does not own.
+- **RTSC-810** — `retasc bind --org-id X --project-id Y` learns the project's prefix. The
+  provisioning form skipped every branch that looks a project up, so nothing knew the
+  prefix: the key went out nameless, the keystore entry was written without `prefix` or
+  `orgName`, and the receipt card printed an empty one. It now resolves the project the
+  same way the interactive pickers do.
+- **RTSC-810** — a key is named after the folder it was bound in, not after the project.
+  The Keys list is the folder map (`client-a` → `ENG`), which is what tells you which
+  machine a credential belongs to; `ENG key` on every row told nobody anything. Naming is
+  the server's job now, so no door can store a nameless key: the Dash mint form with the
+  name left blank and `retasc key mint` without `--name` both fall back to the project's
+  own name rather than leaving the Dash to print "Unnamed key".
+
 ## 1.39.3 (2026-09-02)
 
 - **RTSC-801** — (security) `save_attachment_file` no longer reads a workspace's own secrets,

package/dist/commands/bind.js

@@ -455,6 +455,20 @@ export async function completeWorkspaceSetup(args) {
             throw new Error("no project selected — pass --project-id <id>, or --project <name> --prefix <PFX>.");
         }
     }
+    // RTSC-810 — a `--project-id` skipped every branch above, so nothing here knew the
+    // project's prefix: the key went out nameless (`keyName` was built from `prefix`), the
+    // keystore entry was written without `prefix`/`orgName`, and the receipt card printed
+    // an empty one. The provisioning form is documented and supported, so it fills the
+    // gap the way the pickers do: one list call. Best-effort on the match — a scoped
+    // member may hold an id the list does not show, and that folder still has to bind.
+    if (projectId && !prefix) {
+        const { projects } = (await api.listProjects({ orgId }));
+        const hit = (projects ?? []).find((p) => p.id === projectId);
+        if (hit) {
+            prefix = hit.prefix;
+            emptyProject = projectIsEmpty(hit);
+        }
+    }
     // --- make `retasc` durable BEFORE anything is committed (RTSC-493) ---------
     // The marker names a command something else spawns on every agent start, so it has to
     // name one proved to run on this machine. Resolved (and announced) here so the install
@@ -501,7 +515,12 @@ export async function completeWorkspaceSetup(args) {
             projectId: projectId,
             agentName: opts.agent,
             runtime: opts.runtime ?? "claude-code",
-            keyName: prefix ? `${prefix} key` : undefined,
+            // RTSC-810 — named after the FOLDER, the leaf only, exactly as the setup-token
+            // door has done since RTSC-532: the Keys list is the folder map (`client-a →
+            // ENG`), and the old prefix-plus-"key" name told nobody which folder held it.
+            // The server cleans the name and falls back to the project's own when the
+            // leaf is empty.
+            keyName: basename(cwd),
         }));
     // The key is named in the receipt card below, not here — one mention, in the place
     // that says where it went (RTSC-673).

package/dist/commands/setup.js

@@ -14,6 +14,7 @@
 // nothing (the reason `resolveLauncher` exists, RTSC-493), so a postinstall would never
 // run for them; and writing into somebody's global agent configs from a package install
 // is a thing to do in front of a human, not behind one.
+import { wireClaudeHook, hookLauncher } from "../lib/sessionHook.js";
 import { AUTO_WORKSPACE } from "../lib/keystore.js";
 import { HARNESSES, detectHarnesses, tildePath } from "../lib/harness.js";
 import { resolveLauncher, launcherNote } from "../lib/launcher.js";
@@ -58,6 +59,13 @@ export function runSetup(opts) {
             result.failed.push({ label: h.label, reason: outcome.reason });
         }
     }
+    // RTSC-820 — Claude Code hands its session id to hooks, not to MCP servers, so the
+    // marker alone can never learn which conversation a session is. Same launcher as the
+    // marker, so both resolve or neither does.
+    if (presentIds.has("claude-code")) {
+        const hooked = wireClaudeHook(hookLauncher(resolved.launcher, VERSION));
+        result.hook = hooked.ok ? { where: tildePath(hooked.path), outcome: hooked.outcome } : { reason: hooked.reason };
+    }
     if (!opts.quiet)
         printSetup(result);
     return result;
@@ -82,6 +90,12 @@ export function printSetup(r) {
         }))));
     for (const f of r.failed)
         console.log(`  ! ${f.label}: ${f.reason}`);
+    if (r.hook) {
+        if ("reason" in r.hook)
+            console.log(`  ! Claude Code session hook: ${r.hook.reason}`);
+        else if (r.hook.outcome !== "unchanged")
+            console.log(`  ${r.hook.outcome === "added" ? "+" : "~"} Claude Code session hook in ${r.hook.where}, so the Dash can name each session's transcript.`);
+    }
     if (r.absent.length)
         console.log(`  Not on this machine: ${r.absent.join(", ")}.`);
     console.log("\nThese entries carry no key and name no project, so they are correct in every folder.\n" +

package/dist/commands/unbind.js

@@ -27,6 +27,35 @@ import { removeProjectMarker, tryClaudeCliRemove } from "./mcp.js";
  *   • **The session is left alone.** Signing out is `logout`'s job; conflating the two
  *     turns "detach this folder" into "log me out everywhere", which nobody asked.
  */
+/**
+ * The prefix the SERVER stored for a raw key — `displayPrefixOf` in `convex/lib/keys.ts`,
+ * mirrored here because the CLI cannot import backend code.
+ *
+ * RTSC-810: this length is the join `unbind` revokes on, and it was wrong. The local side
+ * sliced 12 while the server stores 14, so the exact compare was never true once, and
+ * `unbind` reported "not found server-side" on every run while leaving the key LIVE —
+ * the same outcome as the `{ keys }` destructure below, from the other half of the same
+ * lookup. A change to the server's slice has to change this one; `unbindRevoke810.test.mjs`
+ * reads `convex/lib/keys.ts` and fails if the two ever disagree again.
+ */
+export const DISPLAY_PREFIX_LEN = 14;
+export function displayPrefixOf(key) {
+    return key.slice(0, DISPLAY_PREFIX_LEN);
+}
+/**
+ * This folder's live key among the org's, by display prefix — the join `unbind` revokes
+ * on. Takes the ARRAY `listKeys` returns; anything else is "nothing to revoke", never a
+ * throw, because the caller's fallback is to name the Dash rather than to fail.
+ *
+ * WORKSPACE keys only: a session child (`parentKeyId` set) is minted in memory by the
+ * proxy and never reaches the keystore, so one matching here would mean revoking a key
+ * this folder does not own.
+ */
+export function liveKeyFor(keys, prefix) {
+    if (!Array.isArray(keys) || !prefix)
+        return undefined;
+    return keys.find((k) => k?.displayPrefix === prefix && !k.revokedAt && !k.parentKeyId && typeof k.id === "string");
+}
 export async function unbindAction(opts) {
     const cwd = process.cwd();
     const existing = readLocalBinding(cwd);
@@ -35,7 +64,7 @@ export async function unbindAction(opts) {
         return;
     }
     const entry = existing.workspaceId ? getBinding(existing.workspaceId) : undefined;
-    const keyPrefix = (entry?.key ?? existing.key ?? "").slice(0, 12);
+    const keyPrefix = displayPrefixOf(entry?.key ?? existing.key ?? "");
     console.log(`This will disconnect ${cwd} from Retasc:`);
     if (entry?.orgName || entry?.prefix) {
         console.log(`  bound to: ${entry.orgName ?? entry.orgId} / ${entry.prefix ?? entry.projectId}`);
@@ -58,14 +87,18 @@ export async function unbindAction(opts) {
         return;
     }
     // Revoke FIRST, while the keystore still holds what identifies the key. displayPrefix
-    // is how the server names keys (the raw value is never stored there), so the first 12
-    // chars of ours is the join.
+    // is how the server names keys (the raw value is never stored there), so the first
+    // DISPLAY_PREFIX_LEN chars of ours is the join — the server's own slice, not a shorter
+    // guess at it (RTSC-810).
     if (entry?.orgId && keyPrefix && isLoggedIn()) {
         try {
-            const { keys } = (await api.listKeys({ orgId: entry.orgId }));
-            const mine = (keys ?? []).find((k) => k.displayPrefix === keyPrefix && !k.revokedAt);
+            // RTSC-810 — `listKeys` returns a bare ARRAY (as `retasc key list` has always
+            // read it). This destructured `{ keys }` off it, got `undefined`, and so every
+            // unbind since RTSC-721 printed "not found server-side" and left the key LIVE —
+            // the exact half of hand-editing the command exists to stop.
+            const mine = liveKeyFor(await api.listKeys({ orgId: entry.orgId }), keyPrefix);
             if (mine) {
-                await api.revokeKey({ keyId: mine.id ?? mine._id });
+                await api.revokeKey({ keyId: mine.id });
                 console.log(`✓ Revoked key ${keyPrefix}… server-side.`);
             }
             else {

package/dist/index.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { findBindingByPath } from "./lib/keystore.js";
+import { parseClaudeHookInput, writeHookRecord } from "./lib/sessionHook.js";
 import { Command } from "commander";
 import { VERSION } from "./version.js";
 import { selfCommand, versionStamp } from "./lib/launcher.js";
@@ -593,6 +595,35 @@ mcp
     .command("proxy", { hidden: true })
     .description("Run the liveness watchdog proxy (spawned by your harness; wired by mcp install).")
     .action(() => runProxy());
+// RTSC-820 — what a harness's SessionStart hook runs. Reads the harness's JSON on stdin
+// and leaves the session id where the proxy will find it. Exits 0 no matter what: a
+// hook that fails must never fail the session it was told about.
+const hook = program.command("hook").description("Harness hook handlers (wired by `retasc setup`).");
+hook
+    .command("session-start")
+    .description("Claude Code SessionStart hook: record this session's transcript id for the proxy.")
+    .action(async () => {
+    try {
+        // The hook is wired machine-wide, so it fires in every folder Claude Code opens.
+        // Only a folder bound to Retasc has a proxy to hand the id to; anywhere else a
+        // record would be a note about a project Retasc was never told about.
+        if (process.stdin.isTTY)
+            return;
+        const chunks = [];
+        for await (const c of process.stdin)
+            chunks.push(c);
+        const parsed = parseClaudeHookInput(Buffer.concat(chunks).toString("utf8"));
+        if (parsed && findBindingByPath(parsed.cwd)) {
+            writeHookRecord({ harness: "claude-code", sessionId: parsed.sessionId, cwd: parsed.cwd, at: Date.now() });
+        }
+    }
+    catch {
+        /* never fail the harness's session start */
+    }
+    finally {
+        process.exitCode = 0;
+    }
+});
 // Top-level alias so harness config can spawn `retasc mcp-proxy`.
 program
     .command("mcp-proxy", { hidden: true })

package/dist/lib/session.js

@@ -91,3 +91,43 @@ export function appendFallbackNotice(toolName, resp, degraded) {
         result.content.push({ type: "text", text: MINT_FALLBACK_NOTICE });
     }
 }
+/**
+ * Record the harness's transcript id on THIS session's key (RTSC-820). Best effort and
+ * quiet: the worst case is the Dash saying "none recorded", which is what it said
+ * before this existed. Returns true once the server has it (already-recorded counts).
+ */
+export async function recordSession(opts) {
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const warn = opts.warn ?? ((msg) => process.stderr.write(`[retasc] ${msg}\n`));
+    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 - 1,
+                method: "tools/call",
+                params: {
+                    name: "record_session",
+                    arguments: { transcriptId: opts.transcriptId, ...(opts.harness ? { harness: opts.harness } : {}) },
+                },
+            }),
+            signal: AbortSignal.timeout(MINT_TIMEOUT_MS),
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            warn(`record_session failed (HTTP ${res.status})`);
+            return false;
+        }
+        const r = toolResult(text ? JSON.parse(text) : null, warn);
+        return !!(r && typeof r === "object" && "transcriptId" in r);
+    }
+    catch (e) {
+        warn(`record_session failed: ${String(e?.message ?? e)}`);
+        return false;
+    }
+}

package/dist/lib/sessionHook.js

@@ -0,0 +1,233 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+/** Where the records live. `RETASC_DIR` relocates it, like the keystore (tests, sandboxes). */
+export function sessionsDir() {
+    return join(process.env.RETASC_DIR || join(homedir(), ".retasc"), "sessions");
+}
+/** The folder as the kernel names it: the hook's `cwd` and the proxy's `process.cwd()`
+ *  may spell a symlinked path differently, and both must land on one file. */
+export function canonPath(p) {
+    const r = resolve(p);
+    try {
+        return realpathSync(r);
+    }
+    catch {
+        return r;
+    }
+}
+/** One file per folder: a stable, filename-safe key for the cwd. */
+export function hookFilePath(cwd, dir = sessionsDir()) {
+    const h = createHash("sha256").update(canonPath(cwd)).digest("hex").slice(0, 16);
+    return join(dir, `${h}.json`);
+}
+/** Records nobody consumed in a day are nobody's session any more: dropped on the next
+ *  write, so the dir never becomes an index of every folder ever opened. Best effort. */
+const RECORD_TTL_MS = 24 * 60 * 60 * 1000;
+function sweepOldRecords(dir, now) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const n of names) {
+        if (!n.endsWith(".json"))
+            continue;
+        try {
+            const path = join(dir, n);
+            if (now - statSync(path).mtimeMs > RECORD_TTL_MS)
+                unlinkSync(path);
+        }
+        catch {
+            /* someone else's problem */
+        }
+    }
+}
+/**
+ * What a hook writes. Never throws past its caller: a hook that fails must not fail the
+ * harness's session start, and the worst case is the Dash saying "none recorded".
+ */
+export function writeHookRecord(rec, dir = sessionsDir()) {
+    const path = hookFilePath(rec.cwd, dir);
+    // 0o700 all the way up: the hook is wired machine-wide and can be the first thing to
+    // create ~/.retasc, and the keystore's own mkdir is a no-op on a directory that
+    // already exists (keystore.ts). The two must agree on user-only.
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, JSON.stringify(rec), { mode: 0o600 });
+    sweepOldRecords(dirname(path), rec.at);
+    return path;
+}
+/**
+ * The record for THIS folder, if a hook left one recently enough to be this session's.
+ * `maxAgeMs` is measured from `now`; the proxy passes its own start time so a record
+ * written a little before the proxy came up still counts. `notAfter` is the other edge:
+ * a record written well AFTER the proxy started belongs to the next session in this
+ * folder, and a long-lived proxy that never found its own must not adopt it.
+ */
+export function readHookRecord(cwd, opts = {}) {
+    const path = hookFilePath(cwd, opts.dir ?? sessionsDir());
+    if (!existsSync(path))
+        return null;
+    let rec;
+    try {
+        rec = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!rec || typeof rec !== "object")
+        return null;
+    // Same shape the server accepts: a filename stem, never something a shell or a CLI
+    // would read as a flag (first character alphanumeric).
+    if (typeof rec.sessionId !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/.test(rec.sessionId))
+        return null;
+    if (typeof rec.harness !== "string" || !rec.harness)
+        return null;
+    if (typeof rec.cwd !== "string" || canonPath(rec.cwd) !== canonPath(cwd))
+        return null;
+    const now = opts.now ?? Date.now();
+    const maxAge = opts.maxAgeMs ?? 10 * 60 * 1000;
+    if (typeof rec.at !== "number" || rec.at > now + 60_000 || now - rec.at > maxAge)
+        return null;
+    if (opts.notAfter !== undefined && rec.at > opts.notAfter)
+        return null;
+    return rec;
+}
+/** Consume a record once it has been reported, so no later session can adopt it. */
+export function clearHookRecord(cwd, dir = sessionsDir()) {
+    try {
+        unlinkSync(hookFilePath(cwd, dir));
+    }
+    catch {
+        /* already gone */
+    }
+}
+/**
+ * Parse what Claude Code hands a SessionStart hook on stdin. Verified against the hooks
+ * reference (2026-09-04): `session_id`, `transcript_path`, `cwd`, `hook_event_name`,
+ * `source`. Only the id and the cwd are kept; the path is derivable and would bake in a
+ * username (RTSC-791).
+ */
+export function parseClaudeHookInput(stdin) {
+    let j;
+    try {
+        j = JSON.parse(stdin);
+    }
+    catch {
+        return null;
+    }
+    const sessionId = typeof j?.session_id === "string" ? j.session_id.trim() : "";
+    const cwd = typeof j?.cwd === "string" && j.cwd ? j.cwd : process.cwd();
+    if (!sessionId)
+        return null;
+    return { sessionId, cwd };
+}
+// --- wiring the Claude Code hook ---------------------------------------------------
+export const HOOK_MARKER = "hook session-start";
+/** A shell word: bare when it is plainly one, single-quoted otherwise. Claude Code runs
+ *  hook commands through a shell, and an absolute launcher path can carry a space
+ *  (`/Users/John Doe/...`); unquoted, the hook would fail on every session start and
+ *  nothing would name the cause. */
+export function shellWord(part) {
+    return /^[A-Za-z0-9_.\/@:=+%,-]+$/.test(part) ? part : `'${part.replace(/'/g, `'\\''`)}'`;
+}
+/** The command the hook runs: the same launcher the MCP marker names, so an `npx`
+ *  install and a global one both resolve. The marker verb stays bare, so idempotence
+ *  can find the entry by it. */
+export function claudeHookCommand(launcher) {
+    return [...[launcher.command, ...launcher.args].map(shellWord), HOOK_MARKER].join(" ");
+}
+/**
+ * Merge our SessionStart hook into a Claude Code `settings.json` text, and say what
+ * happened. Idempotent: an entry already carrying our marker is updated in place if
+ * its command changed (a moved launcher), left alone if not, never duplicated. Every
+ * other hook, and every other setting, survives untouched. Returns null when the file
+ * is not JSON we can read, rather than replacing something we cannot parse.
+ */
+export function mergeClaudeHook(text, command) {
+    let settings = {};
+    if (text && text.trim()) {
+        try {
+            settings = JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+        if (!settings || typeof settings !== "object" || Array.isArray(settings))
+            return null;
+    }
+    const hooks = (settings.hooks && typeof settings.hooks === "object" ? settings.hooks : {});
+    const list = Array.isArray(hooks.SessionStart) ? hooks.SessionStart : [];
+    let outcome = "unchanged";
+    let found = false;
+    for (const entry of list) {
+        // Someone else's entries may be any shape; only walk the ones shaped like hooks.
+        if (!entry || typeof entry !== "object" || !Array.isArray(entry.hooks))
+            continue;
+        for (const h of entry.hooks) {
+            if (h && typeof h === "object" && h.type === "command" && typeof h.command === "string" && h.command.includes(HOOK_MARKER)) {
+                found = true;
+                if (h.command !== command) {
+                    h.command = command;
+                    outcome = "updated";
+                }
+            }
+        }
+    }
+    if (!found) {
+        // `startup|resume` only: a compaction or a /clear re-fires SessionStart with the
+        // same id and would re-arm the record for a session already served. `timeout` in
+        // seconds: a hook that hangs (a cold npx offline) must never hold a session start.
+        list.push({ matcher: "startup|resume", hooks: [{ type: "command", command, timeout: 10 }] });
+        outcome = "added";
+    }
+    hooks.SessionStart = list;
+    settings.hooks = hooks;
+    return { text: JSON.stringify(settings, null, 2) + "\n", outcome };
+}
+/**
+ * The launcher the hook may name. The MCP marker's launcher is whatever `retasc` is on
+ * PATH, at whatever version; a 1.39 binary has no `hook` verb and would print "unknown
+ * command" on every session start, everywhere. So the hook gets that launcher only if it
+ * actually answers the verb, and the pinned npx form of THIS version otherwise.
+ */
+export function hookLauncher(launcher, version, probe = (cmd, args) => {
+    try {
+        const r = spawnSync(cmd, args, { encoding: "utf8", timeout: 20_000, shell: process.platform === "win32" });
+        return !r.error && r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}) {
+    if (launcher.command === "npx")
+        return launcher; // pinned to a version that has it
+    if (probe(launcher.command, [...launcher.args, ...HOOK_MARKER.split(" "), "--help"]))
+        return launcher;
+    return { command: "npx", args: ["-y", `@retasc/cli@${version}`] };
+}
+/** `~/.claude/settings.json`, under the same home override the harness registry honours. */
+export function claudeSettingsPath(home = process.env.RETASC_HOME || homedir()) {
+    return join(home, ".claude", "settings.json");
+}
+/**
+ * Wire the hook on this machine. Returns what it did, or why it could not. The file
+ * is user-owned config Claude Code reads at start (unlike `~/.claude.json`, which a
+ * running Claude Code rewrites and which is only ever edited through `claude mcp`).
+ */
+export function wireClaudeHook(launcher, home) {
+    const path = claudeSettingsPath(home);
+    const before = existsSync(path) ? readFileSync(path, "utf8") : null;
+    const merged = mergeClaudeHook(before, claudeHookCommand(launcher));
+    if (!merged)
+        return { ok: false, reason: `${path} is not JSON I can read; add the hook by hand` };
+    if (merged.outcome !== "unchanged") {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, merged.text);
+    }
+    return { ok: true, path, outcome: merged.outcome };
+}

package/dist/proxy.js

@@ -13,7 +13,8 @@ import { fileURLToPath } from "node:url";
 import { applyObservation, heartbeatRequest, isClaimLost, isUnauthorized, shouldReapOnClose, untrackedLeaseWarning, } from "./lib/watchdog.js";
 import { AUTO_WORKSPACE, resolveConn } from "./lib/keystore.js";
 import { toolResult as parseTool } from "./lib/toolresult.js";
-import { mintSessionKey, appendFallbackNotice } from "./lib/session.js";
+import { mintSessionKey, appendFallbackNotice, recordSession } from "./lib/session.js";
+import { readHookRecord, clearHookRecord } from "./lib/sessionHook.js";
 import { attachRoot, isLocalAttachCall, mergeAttachTool, readAttachFile, resolveAttachPath, uploadFailureMessage, uploadUrlWith, } from "./lib/attachFile.js";
 import { MAX_FETCH_BYTES, downloadFailureMessage, existingDownload, isLocalFetchCall, mergeFetchTool, resolveDownloadTarget, writeDownloadedFile, } from "./lib/fetchFile.js";
 // RTSC-92/98: resolve the workspace key via the SHARED resolver, so the proxy and
@@ -47,6 +48,24 @@ let authWarned = false;
 // 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;
+// RTSC-820 — the harness's transcript id, once we learn it, and whether the server has
+// it. Grok exports GROK_SESSION_ID to MCP servers, so that one is known at startup.
+// Claude Code hands its id to a SessionStart HOOK, which drops a record in the keystore
+// dir (lib/sessionHook.ts); hook and proxy start in either order, so the record is
+// looked for after the mint and then on each forwarded call until found, bounded.
+const PROXY_STARTED_AT = Date.now();
+const TRANSCRIPT_LOOKUPS_MAX = 40;
+let transcript = process.env.GROK_SESSION_ID ? { id: process.env.GROK_SESSION_ID, harness: "grok" } : null;
+let transcriptRecorded = false;
+let transcriptLookups = 0;
+let transcriptInFlight = null;
+// The name the client gave at `initialize` (RTSC-717), so a Codex session started in a
+// folder never adopts a claude-code hook's record.
+let clientName = null;
+// A hook record is this session's only if written within a minute BEFORE we started or
+// a few minutes after; and a session that has not found one in five minutes never will.
+const RECORD_NOT_AFTER_MS = 3 * 60_000;
+const RECORD_SEARCH_MS = 5 * 60_000;
 // 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;
@@ -171,6 +190,58 @@ async function adoptSessionKey() {
         sessionKeyFallback = true;
     }
 }
+/**
+ * RTSC-820 — tell the server which conversation this session is, once we know. Only on
+ * a real session key: the workspace key is the folder, not a conversation, and the
+ * server refuses it anyway. Looks for the Claude Code hook's record while nothing has
+ * been found, a bounded number of times, then stops asking: a session whose harness
+ * wired no hook simply never learns its id, and the Dash says so.
+ */
+async function reportTranscript() {
+    if (transcriptRecorded || sessionKeyFallback || activeKey === KEY)
+        return;
+    // Startup and the first forwarded call can both get here; one report at a time.
+    if (transcriptInFlight)
+        return transcriptInFlight;
+    transcriptInFlight = reportTranscriptOnce().finally(() => { transcriptInFlight = null; });
+    return transcriptInFlight;
+}
+async function reportTranscriptOnce() {
+    // One budget for looking AND for asking: a server that keeps refusing is not asked
+    // on every call for the rest of the session either.
+    if (transcriptLookups >= TRANSCRIPT_LOOKUPS_MAX)
+        return;
+    transcriptLookups += 1;
+    if (!transcript) {
+        const now = Date.now();
+        if (now - PROXY_STARTED_AT > RECORD_SEARCH_MS) {
+            transcriptLookups = TRANSCRIPT_LOOKUPS_MAX; // stop looking: any record now is the next session's
+            return;
+        }
+        // A record written within a minute before we started, or up to a few minutes after:
+        // the hook and the proxy are spawned together. Older belongs to an earlier session in
+        // this folder; newer belongs to a later one.
+        const rec = readHookRecord(process.cwd(), {
+            now,
+            maxAgeMs: now - PROXY_STARTED_AT + 60_000,
+            notAfter: PROXY_STARTED_AT + RECORD_NOT_AFTER_MS,
+        });
+        if (!rec)
+            return;
+        // A record names its harness; the client named itself at `initialize`. Different
+        // harness, not our record (a Codex pane opened in a folder a Claude hook wrote for).
+        if (rec.harness === "claude-code" && clientName && !/claude/i.test(clientName))
+            return;
+        transcript = { id: rec.sessionId, harness: rec.harness };
+    }
+    const ok = await recordSession({ url: MCP_URL, key: activeKey, transcriptId: transcript.id, harness: transcript.harness, warn: log });
+    if (ok) {
+        transcriptRecorded = true;
+        if (transcript.harness !== "grok")
+            clearHookRecord(process.cwd());
+        log(`session recorded as ${transcript.harness} transcript ${transcript.id}`);
+    }
+}
 /**
  * RTSC-91 (DESIGN §13, D2): announce the binding to the HUMAN on startup, so the
  * org/project this session will write into is visible in the harness's MCP logs
@@ -443,6 +514,11 @@ async function handleLine(line) {
         }) + "\n");
         return;
     }
+    if (msg.method === "initialize") {
+        const n = msg.params?.clientInfo?.name;
+        if (typeof n === "string" && n)
+            clientName = n;
+    }
     let resp;
     try {
         resp = await postRemote(msg);
@@ -475,6 +551,9 @@ async function handleLine(line) {
     // 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.
     let reapId;
+    if (msg.method === "tools/call" && !transcriptRecorded) {
+        reportTranscript().catch((e) => log(`record_session: ${String(e?.message ?? e)}`));
+    }
     if (msg.method === "tools/call" && resp) {
         const result = toolResult(resp, msg.params?.name);
         const obs = { toolName: msg.params?.name, args: msg.params?.arguments, result };
@@ -548,6 +627,7 @@ export async function runProxy() {
     // attributed to this session. stdin buffers in the OS pipe meanwhile.
     await adoptSessionKey();
     await announceBinding();
+    reportTranscript().catch((e) => log(`record_session: ${String(e?.message ?? e)}`));
     const timer = setInterval(() => void heartbeatAll(), HEARTBEAT_MS);
     timer.unref?.(); // the timer alone must not keep the process alive
     const rl = createInterface({ input: process.stdin });

package/package.json

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