@retasc/cli 1.39.4 → 1.41.0

package/CHANGELOG.md

@@ -6,6 +6,32 @@ release commits and the issues they reference.
 
 Dates are the npm publish date. Each entry names the RTSC issue behind it.
 
+## 1.41.0 (2026-09-04)
+
+- **RTSC-825** — every workspace now carries the name of the folder it is bound to. The
+  server never receives a path, so the name can only come from the machine that has one:
+  `retasc bind` sends it when the key is minted, and the watchdog proxy re-sends it at
+  every session start, so a folder bound before this existed is named the next time an
+  agent runs there. Only the folder's own name travels, never the path above it, and it
+  is the folder the BINDING names — a session opened in a subdirectory still reports the
+  bound folder rather than renaming the row to whatever directory it started in. The
+  Dash shows it as `workspace` on the Agents page and on the Connect page, and shows
+  nothing at all where a workspace has not reported one; a key retired before this
+  shipped can never report one, so it stays blank.
+
+## 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

package/dist/commands/bind.js

@@ -521,6 +521,9 @@ export async function completeWorkspaceSetup(args) {
             // The server cleans the name and falls back to the project's own when the
             // leaf is empty.
             keyName: basename(cwd),
+            // RTSC-825 — and as the WORKSPACE, which is the field the Dash reads. `keyName`
+            // stays for the legacy label; nothing reads it as a folder any more.
+            workspace: 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).
@@ -646,7 +649,7 @@ export async function setupFromToken(token, opts, deps = {}) {
     const cwd = process.cwd();
     const guard = deps.guard ?? rebindGuard;
     const redeem = deps.redeem ??
-        ((t, label) => api.redeemSetupToken({ token: t, label }));
+        ((t, label, workspace) => api.redeemSetupToken({ token: t, label, workspace }));
     // BEFORE the redeem. `rebindGuard` prints its own explanation and, with no TTY,
     // refuses with exit 1 unless `--yes` — which is exactly the required behaviour, so it
     // is reused rather than restated. No org/project passed: its idempotent-converge
@@ -664,7 +667,12 @@ export async function setupFromToken(token, opts, deps = {}) {
     // RTSC-532 — the LEAF name, never the full path. It names the key in the Dash, so it
     // has to be recognisable ("client-a → ENG") without publishing where on her disk it
     // sits. `basename` of the cwd is exactly that.
-    const redeemed = await redeem(token.trim(), basename(cwd));
+    //
+    // RTSC-825 — sent TWICE, on purpose: once as the legacy `label` and once as the
+    // `workspace`. They happen to be the same string here and nowhere is that a rule —
+    // the label is a human field a future caller may set to anything, so the folder
+    // travels in its own argument rather than being read back out of it.
+    const redeemed = await redeem(token.trim(), basename(cwd), basename(cwd));
     const workspaceId = existing?.workspaceId ?? newWorkspaceId();
     (deps.bind ?? setBinding)(workspaceId, {
         orgId: redeemed.orgId,

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/index.js

@@ -1,10 +1,12 @@
 #!/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";
 import { loadConfig, patchConfig, saveConfig, configPath, isLoggedIn } from "./config.js";
 import { installMcp, noteRuntimeIsALabel, normalizeScope } from "./commands/mcp.js";
-import { runSetup } from "./commands/setup.js";
+import { runSetup, printSetup } from "./commands/setup.js";
 import { installGate, resolveGatePrefix } from "./commands/gate.js";
 import { claimAction, releaseAction } from "./commands/claim.js";
 import { bindAction, completeWorkspaceSetup, rebindGuard, setupFromToken } from "./commands/bind.js";
@@ -574,7 +576,7 @@ program
     .option("--no-install", "Don't install `retasc` on this machine; wire the pinned npx launcher instead")
     .allowExcessArguments(false)
     .action((opts) => {
-    runSetup({ install: opts.install });
+    printSetup(runSetup({ install: opts.install, quiet: true }));
 });
 const mcp = program.command("mcp").description("Wire the Retasc MCP server into your agent.");
 mcp
@@ -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/keystore.js

@@ -202,6 +202,7 @@ export function resolveConn(opts) {
     // came from the keystore, so it travels only to the keystore's url. That is what
     // lets `auto` be written into a GLOBAL harness config: the entry is identical on
     // every machine and in every folder, and carries nothing worth stealing.
+    let boundPath = "";
     if (!key) {
         const wsId = env.RETASC_WORKSPACE || entry?.env?.RETASC_WORKSPACE;
         const b = wsId === AUTO_WORKSPACE
@@ -217,7 +218,8 @@ export function resolveConn(opts) {
             // url" is stated here outright rather than left resting on that invariant, so
             // restoring an unpaired url above cannot quietly resurrect the RTSC-800 redirect.
             url = b.url;
+            boundPath = b.boundPath ?? "";
         }
     }
-    return { key, url: url || opts.defaultUrl || "" };
+    return { key, url: url || opts.defaultUrl || "", boundPath };
 }

package/dist/lib/session.js

@@ -5,9 +5,17 @@
 // sessions collapse into one server-side identity and the per-session claim fence
 // (RTSC-49/50) is silently inert.
 import { toolResult } from "./toolresult.js";
-// Out-of-band ids are negative so they never collide with the harness's (the
-// same convention as the proxy's heartbeat ids; announceBinding uses -1001).
-const MINT_RPC_ID = -1000;
+// Out-of-band ids are negative so they never collide with the harness's (the same
+// convention as the proxy's heartbeat ids). One id per out-of-band call, named rather
+// than counted: the offsets these replaced had drifted into a collision, with
+// `announceBinding` and `record_session` both sending -1001.
+export const RPC_ID = {
+    mint: -1000,
+    announce: -1001,
+    recordSession: -1002,
+    nameWorkspace: -1003,
+};
+const MINT_RPC_ID = RPC_ID.mint;
 // The mint runs BEFORE the proxy serves `initialize`, so a hung server must not
 // stall startup past the harness's MCP timeout — that would turn "degraded
 // identity" into "no Retasc tools at all", the exact failure fail-soft exists
@@ -91,3 +99,82 @@ export function appendFallbackNotice(toolName, resp, degraded) {
         result.content.push({ type: "text", text: MINT_FALLBACK_NOTICE });
     }
 }
+/**
+ * One out-of-band `tools/call` (RTSC-825). The proxy makes several of these around a
+ * session's start — mint the session key, announce the binding, record the transcript,
+ * name the folder — and they had been written out longhand each time, so a change to
+ * the transport (the auth header, the timeout, how a failure is surfaced) had to be
+ * made in three places and would have been made in one.
+ *
+ * Every caller here is best-effort: the session must serve MCP traffic whatever the
+ * server says, so this NEVER throws. `expect` is the field the tool returns on success;
+ * its presence is what separates a real result from an error envelope carrying prose.
+ */
+async function callTool(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: opts.id,
+                method: "tools/call",
+                params: { name: opts.name, arguments: opts.args },
+            }),
+            signal: AbortSignal.timeout(MINT_TIMEOUT_MS),
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            warn(`${opts.name} failed (HTTP ${res.status})`);
+            // 5xx is the server having a bad minute; anything else is it saying no.
+            return res.status >= 500 ? "unreachable" : "refused";
+        }
+        const r = toolResult(text ? JSON.parse(text) : null, warn);
+        if (r && typeof r === "object" && opts.expect in r)
+            return "ok";
+        // A 200 carrying an error result: an unknown tool on an older deployment, a
+        // revoked key, the wrong kind of key. All of them are answers, not outages.
+        return "refused";
+    }
+    catch (e) {
+        warn(`${opts.name} failed: ${String(e?.message ?? e)}`);
+        return "unreachable";
+    }
+}
+/**
+ * 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 out = await callTool({
+        ...opts,
+        id: RPC_ID.recordSession,
+        name: "record_session",
+        args: { transcriptId: opts.transcriptId, ...(opts.harness ? { harness: opts.harness } : {}) },
+        expect: "transcriptId",
+    });
+    return out === "ok";
+}
+/**
+ * Tell Retasc which folder a workspace key is bound to (RTSC-825). Best effort and
+ * quiet, like `recordSession`: the worst case is the Dash omitting the workspace, which
+ * is what it did before this existed. "named" once the server holds this folder
+ * (already-correct counts).
+ */
+export async function nameWorkspace(opts) {
+    const out = await callTool({
+        ...opts,
+        id: RPC_ID.nameWorkspace,
+        name: "name_workspace",
+        args: { workspace: opts.workspace },
+        expect: "workspace",
+    });
+    return out === "ok" ? "named" : out;
+}

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

@@ -8,12 +8,13 @@
 import { createInterface } from "node:readline";
 import { hostname } from "node:os";
 import { spawn, spawnSync } from "node:child_process";
-import { dirname, resolve } from "node:path";
+import { basename, dirname, resolve } from "node:path";
 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, nameWorkspace, RPC_ID } 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
@@ -180,7 +251,7 @@ async function announceBinding() {
     try {
         const resp = await postRemote({
             jsonrpc: "2.0",
-            id: -1001,
+            id: RPC_ID.announce,
             method: "tools/call",
             params: { name: "whoami", arguments: {} },
         });
@@ -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,21 @@ export async function runProxy() {
     // attributed to this session. stdin buffers in the OS pipe meanwhile.
     await adoptSessionKey();
     await announceBinding();
+    // RTSC-825 — the folder this session runs in IS its workspace, and this process is
+    // the only thing that knows it. Sent on the WORKSPACE key (not the session child just
+    // adopted), so a folder bound before the CLI reported one, or renamed since, corrects
+    // itself the next time an agent starts. A no-op server-side when it already matches.
+    //
+    // The BOUND folder, not the cwd. The `auto` marker resolves this key by walking up
+    // from wherever the harness was started, so a session opened in `retasc/dash` runs on
+    // `retasc`'s key — naming it `dash` would be wrong, and the next session from the root
+    // would rename it back, flapping the row on every start. Empty for a key that came
+    // from the environment rather than the keystore: that one names no folder.
+    const BOUND_FOLDER = resolved.boundPath ? basename(resolved.boundPath) : "";
+    if (KEY && BOUND_FOLDER) {
+        nameWorkspace({ url: MCP_URL, key: KEY, workspace: BOUND_FOLDER, warn: log }).catch((e) => log(`name_workspace: ${String(e?.message ?? e)}`));
+    }
+    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.4",
+  "version": "1.41.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": {