@retasc/cli 1.39.4 → 1.40.0

package/CHANGELOG.md

@@ -6,6 +6,19 @@ 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

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,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.4",
+  "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": {