lmnr-cli 0.1.12 → 0.1.14

package/README.md

@@ -128,11 +128,20 @@ lmnr-cli dataset create my-dataset data.jsonl -o out.jsonl
 Record findings on a trace and review/name agent debug sessions.
 
 ```bash
-lmnr-cli trace append-note <trace-id> "note text"        # Append a markdown note to a trace
-lmnr-cli debug session set-name <session-id> "title"     # Rename a debug session
-lmnr-cli debug session summary <session-id>              # Every trace in a session + its note
+lmnr-cli debug session new                               # Mint a fresh debug session
+lmnr-cli debug session open                              # Open the session in the browser
+lmnr-cli trace append-note "note text"                   # Markdown note on the latest debug trace
+lmnr-cli debug session set-name "title"                  # Rename the current debug session
+lmnr-cli debug session summary                           # Every trace in the session + its note
 ```
 
+These commands default to the session/trace recorded in
+`.lmnr/debug-session.json` (written by `debug session new` and `LMNR_DEBUG=1`
+runs; the nearest one walking up from the current directory, so subdirectories
+of a project work too); target another one with an explicit id flag
+(e.g. `lmnr-cli debug session summary --session-id <session-id>`,
+`lmnr-cli trace append-note "note" --trace-id <trace-id>`).
+
 `trace append-note` accumulates (each call appends a paragraph). See the Laminar
 debugger docs: https://laminar.sh/docs/platform/debugger
 

package/dist/index.cjs

@@ -41,18 +41,24 @@ let fs_promises = require("fs/promises");
 fs_promises = __toESM(fs_promises);
 let cli_table3 = require("cli-table3");
 cli_table3 = __toESM(cli_table3);
+let node_crypto = require("node:crypto");
 let open = require("open");
 open = __toESM(open);
+let node_fs = require("node:fs");
 let picocolors = require("picocolors");
 let node_readline_promises = require("node:readline/promises");
 let node_child_process = require("node:child_process");
 let node_util = require("node:util");
 let giget = require("giget");
 //#region ../types/dist/index.mjs
+/** Directory the debug-session file lives in, relative to the working dir. */
+const DEBUG_SESSION_DIR = ".lmnr";
+/** Filename of the debug-session file inside {@link DEBUG_SESSION_DIR}. */
+const DEBUG_SESSION_FILE = "debug-session.json";
 const errorMessage = (error) => error instanceof Error ? error.message : String(error);
 //#endregion
 //#region package.json
-var version$1 = "0.1.12";
+var version$1 = "0.1.14";
 //#endregion
 //#region ../../node_modules/.pnpm/dotenv@17.4.2/node_modules/dotenv/lib/main.js
 var require_main = /* @__PURE__ */ __commonJSMin(((exports, module) => {
@@ -323,6 +329,12 @@ var require_main = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	module.exports = DotenvModule;
 }));
 //#endregion
+//#region ../../node_modules/.pnpm/uuid@14.0.0/node_modules/uuid/dist-node/rng.js
+const rnds8 = new Uint8Array(16);
+function rng() {
+	return crypto.getRandomValues(rnds8);
+}
+//#endregion
 //#region ../../node_modules/.pnpm/uuid@14.0.0/node_modules/uuid/dist-node/stringify.js
 const byteToHex = [];
 for (let i = 0; i < 256; ++i) byteToHex.push((i + 256).toString(16).slice(1));
@@ -330,12 +342,6 @@ function unsafeStringify(arr, offset = 0) {
 	return (byteToHex[arr[offset + 0]] + byteToHex[arr[offset + 1]] + byteToHex[arr[offset + 2]] + byteToHex[arr[offset + 3]] + "-" + byteToHex[arr[offset + 4]] + byteToHex[arr[offset + 5]] + "-" + byteToHex[arr[offset + 6]] + byteToHex[arr[offset + 7]] + "-" + byteToHex[arr[offset + 8]] + byteToHex[arr[offset + 9]] + "-" + byteToHex[arr[offset + 10]] + byteToHex[arr[offset + 11]] + byteToHex[arr[offset + 12]] + byteToHex[arr[offset + 13]] + byteToHex[arr[offset + 14]] + byteToHex[arr[offset + 15]]).toLowerCase();
 }
 //#endregion
-//#region ../../node_modules/.pnpm/uuid@14.0.0/node_modules/uuid/dist-node/rng.js
-const rnds8 = new Uint8Array(16);
-function rng() {
-	return crypto.getRandomValues(rnds8);
-}
-//#endregion
 //#region ../../node_modules/.pnpm/uuid@14.0.0/node_modules/uuid/dist-node/v4.js
 function v4(options, buf, offset) {
 	if (!buf && !options && crypto.randomUUID) return crypto.randomUUID();
@@ -358,7 +364,7 @@ function _v4(options, buf, offset) {
 //#endregion
 //#region ../client/dist/index.mjs
 var import_main = require_main();
-var version = "0.8.29";
+var version = "0.8.32";
 function getLangVersion() {
 	if (typeof process !== "undefined" && process.versions && process.versions.node) return `node-${process.versions.node}`;
 	if (typeof navigator !== "undefined" && navigator.userAgent) return `browser-${navigator.userAgent}`;
@@ -1210,19 +1216,19 @@ function outputJsonError(error, exitCode = 1) {
 const DEFAULT_FRONTEND_URL$1 = "https://laminar.sh";
 const DEFAULT_BASE_URL$1 = "https://api.lmnr.ai";
 //#endregion
-//#region src/utils/project-link.ts
-const LINK_DIR = ".lmnr";
-const LINK_FILE = "project.json";
+//#region src/utils/local-project-file.ts
+const LOCAL_LMNR_DIR = ".lmnr";
+const LOCAL_LMNR_PROJECT_FILE = "project.json";
 /**
 * Find the nearest `.lmnr/project.json`, walking up from `startDir` to the
 * filesystem root (so commands work from subdirectories of a linked project).
 * Returns null if none is found.
 */
-async function readProjectLink(startDir = process.cwd()) {
+async function readLocalProjectFile(startDir = process.cwd()) {
 	let dir = startDir;
 	const root = (0, node_path.parse)(dir).root;
 	while (true) {
-		const candidate = (0, node_path.join)(dir, LINK_DIR, LINK_FILE);
+		const candidate = (0, node_path.join)(dir, LOCAL_LMNR_DIR, LOCAL_LMNR_PROJECT_FILE);
 		try {
 			const parsed = JSON.parse(await (0, node_fs_promises.readFile)(candidate, "utf8"));
 			if (parsed && typeof parsed.projectId === "string" && parsed.projectId.length > 0) return parsed;
@@ -1234,10 +1240,10 @@ async function readProjectLink(startDir = process.cwd()) {
 	return null;
 }
 /** Write `.lmnr/project.json` under `dir` (default cwd). Returns the file path. */
-async function writeProjectLink(link, dir = process.cwd()) {
-	const linkDir = (0, node_path.join)(dir, LINK_DIR);
+async function writeLocalProjectFile(link, dir = process.cwd()) {
+	const linkDir = (0, node_path.join)(dir, LOCAL_LMNR_DIR);
 	await (0, node_fs_promises.mkdir)(linkDir, { recursive: true });
-	const path = (0, node_path.join)(linkDir, LINK_FILE);
+	const path = (0, node_path.join)(linkDir, LOCAL_LMNR_PROJECT_FILE);
 	await (0, node_fs_promises.writeFile)(path, JSON.stringify(link, null, 2) + "\n", "utf8");
 	return path;
 }
@@ -1495,7 +1501,7 @@ async function resolveAuth(opts) {
 	const creds = await readCredentials();
 	if (!creds) throw new Error("Not authenticated. Run `lmnr-cli login`.");
 	let projectId = opts.projectId;
-	if (!projectId || projectId.length === 0) projectId = (await readProjectLink())?.projectId;
+	if (!projectId || projectId.length === 0) projectId = (await readLocalProjectFile())?.projectId;
 	if (!projectId || projectId.length === 0) throw new Error("No project for this directory. Run `lmnr-cli setup` here, or pass --project-id <id>.");
 	return {
 		bearer: (await refreshIfNeeded(creds)).accessToken,
@@ -1594,6 +1600,15 @@ function runWithEnvelope(work, opts, exitCodeFor) {
 	});
 }
 /**
+* Wrap a local-only command handler. No auth resolution / client build (the
+* command must not call the API), but the same positionals + options threading
+* and error envelope as the client wrappers, so handlers stay pure.
+*/
+const withLocalOpts = (action, exitCodeFor = defaultExitCode) => async (...cmdArgs) => {
+	const { positionals, opts } = splitCommanderArgs(cmdArgs);
+	await runWithEnvelope(() => action(...positionals, opts), opts, exitCodeFor);
+};
+/**
 * Wrap a project-scoped command handler. Resolves a user-token
 * {@link LaminarClient} (routes to `/v1/cli/*` with the resolved project),
 * threads the commander positionals + options through, and owns the error
@@ -1853,8 +1868,7 @@ function fitColumnWidths(contentWidths, terminalWidth) {
 	const totalContentWidth = contentWidths.reduce((sum, w) => sum + w, 0);
 	if (totalContentWidth + overhead <= terminalWidth) return;
 	const availableContent = terminalWidth - overhead;
-	const minColWidth = 5;
-	return contentWidths.map((w) => Math.max(minColWidth + PADDING_RIGHT, Math.floor(w / totalContentWidth * availableContent) + PADDING_RIGHT));
+	return contentWidths.map((w) => Math.max(7, Math.floor(w / totalContentWidth * availableContent) + PADDING_RIGHT));
 }
 function truncate(str, maxLen) {
 	if (maxLen < 1) return str;
@@ -2006,6 +2020,99 @@ const handleDatasetsCreate = async (client, name, paths, opts) => {
 	else logger$2.info(`Successfully created dataset '${name}' and saved ${result.length} datapoints to ${opts.outputFile}`);
 };
 //#endregion
+//#region src/utils/debug-session-file.ts
+const str = (v) => typeof v === "string" && v.length > 0 ? v : null;
+/**
+* Read `${dir ?? cwd}/.lmnr/debug-session.json`. Best-effort: returns null on a
+* missing / unreadable / malformed file, or one with no usable `session_id`.
+* Mirrors the SDK's reader (`@lmnr-ai/lmnr` `src/debug/debug-session-file.ts`)
+* over the shared `DebugSessionFile` contract from `@lmnr-ai/types`.
+*/
+const readDebugSessionFile = (dir = process.cwd()) => {
+	try {
+		const raw = (0, node_fs.readFileSync)((0, node_path.join)(dir, DEBUG_SESSION_DIR, DEBUG_SESSION_FILE), "utf-8");
+		const r = JSON.parse(raw);
+		const session_id = str(r.session_id);
+		if (!session_id) return null;
+		return {
+			session_id,
+			trace_id: str(r.trace_id),
+			replay_trace_id: str(r.replay_trace_id),
+			cache_until: str(r.cache_until),
+			debugger_url: str(r.debugger_url),
+			started_at: str(r.started_at) ?? (/* @__PURE__ */ new Date()).toISOString()
+		};
+	} catch {
+		return null;
+	}
+};
+/**
+* Find the nearest directory (walking up from `startDir` to the filesystem
+* root) whose `.lmnr/debug-session.json` holds a usable session record, so CLI
+* commands run from a subdirectory of a project act on the project's session.
+* Mirrors the SDK's `findDebugSessionDir`. Returns null when no ancestor
+* (including `startDir`) has one.
+*/
+const findDebugSessionDir = (startDir = process.cwd()) => {
+	let dir = (0, node_path.resolve)(startDir);
+	const root = (0, node_path.parse)(dir).root;
+	while (true) {
+		if (readDebugSessionFile(dir) !== null) return dir;
+		const parent = (0, node_path.dirname)(dir);
+		if (parent === dir || dir === root) return null;
+		dir = parent;
+	}
+};
+/**
+* The directory the debug-session file should be read from AND written to: the
+* nearest ancestor (incl. `startDir`) that already has one, else `startDir`
+* itself. Read and write MUST share this anchor — `debug session new` resets
+* the nearest existing file rather than shadowing it with a nested copy.
+*/
+const resolveDebugSessionDir = (startDir = process.cwd()) => findDebugSessionDir(startDir) ?? (0, node_path.resolve)(startDir);
+/**
+* Resolve the session id a debug command should act on: the explicit
+* `--session-id` value when given, else the `session_id` of the nearest
+* `.lmnr/debug-session.json` (walking up from `startDir`). Throws an
+* actionable error when neither exists; the command wrapper's error envelope
+* formats it.
+*/
+const resolveSessionId = (explicit, startDir) => {
+	if (explicit) return explicit;
+	const file = readDebugSessionFile(resolveDebugSessionDir(startDir));
+	if (file?.session_id) return file.session_id;
+	throw new Error("No session id given and no .lmnr/debug-session.json found in this directory. Pass --session-id <id> or run `lmnr-cli debug session new`.");
+};
+/**
+* Resolve the trace id a trace command should act on: the explicit `--trace-id`
+* value when given, else the `trace_id` of the nearest
+* `.lmnr/debug-session.json` (the root trace of the most recent debug run,
+* walking up from `startDir`). Throws an actionable error when neither exists;
+* the command wrapper's error envelope formats it.
+*/
+const resolveTraceId = (explicit, startDir) => {
+	if (explicit) return explicit;
+	const traceId = readDebugSessionFile(resolveDebugSessionDir(startDir))?.trace_id;
+	if (traceId) return traceId;
+	throw new Error("No trace id given and .lmnr/debug-session.json has no trace_id (no debug run has completed in this directory yet). Pass --trace-id <id> or run your program with LMNR_DEBUG=1 first.");
+};
+/**
+* Write `${dir ?? cwd}/.lmnr/debug-session.json` (mkdir -p first). Best-effort:
+* swallows IO errors. Shares the `DebugSessionFile` contract + filename consts
+* with the SDK (`@lmnr-ai/types`), so the SDK reads this same file at init to
+* join the session `debug session new` minted.
+*/
+const writeDebugSessionFile = (file, dir = process.cwd()) => {
+	try {
+		const directory = (0, node_path.join)(dir, DEBUG_SESSION_DIR);
+		(0, node_fs.mkdirSync)(directory, { recursive: true });
+		(0, node_fs.writeFileSync)((0, node_path.join)(directory, DEBUG_SESSION_FILE), JSON.stringify(file), "utf-8");
+		return true;
+	} catch {
+		return false;
+	}
+};
+//#endregion
 //#region src/utils/trace-note.ts
 const NOTE_METADATA_KEY = "rollout.note";
 /**
@@ -2045,11 +2152,15 @@ const logger$1 = initializeLogger();
 * Upsert the display name of a debug session. Update-only on the backend: a
 * session id unknown to the project 404s rather than creating a ghost session.
 *
+* The target session is the optional `--session-id` flag; when omitted the
+* session comes from `.lmnr/debug-session.json` (see `resolveSessionId`).
+*
 * Pure handler: the command wrapper (`withProjectClient`) resolves a user-token
 * {@link LaminarClient} (routes to `/v1/cli/*` with the resolved project) and
 * owns the error envelope.
 */
-const handleDebugSessionSetName = async (client, sessionId, name, opts) => {
+const handleDebugSessionSetName = async (client, name, opts) => {
+	const sessionId = resolveSessionId(opts.sessionId);
 	await client.rolloutSessions.setName({
 		sessionId,
 		name
@@ -2068,11 +2179,15 @@ const handleDebugSessionSetName = async (client, sessionId, name, opts) => {
 * groups it to the session (`rollout.session_id`), oldest first, with the
 * agent-authored note (`rollout.note`) attached to each.
 *
+* The target session is the optional `--session-id` flag; when omitted the
+* session comes from `.lmnr/debug-session.json` (see `resolveSessionId`).
+*
 * Pure handler: the command wrapper (`withProjectClient`) resolves a user-token
 * {@link LaminarClient} (routes to `/v1/cli/*` with the resolved project) and
 * owns the error envelope.
 */
-const handleDebugSessionSummary = async (client, sessionId, opts) => {
+const handleDebugSessionSummary = async (client, opts) => {
+	const sessionId = resolveSessionId(opts.sessionId);
 	const traces = (await client.sql.query("SELECT id, formatDateTime(end_time, '%Y-%m-%dT%H:%i:%S.%fZ') AS end_time, metadata FROM traces WHERE simpleJSONExtractString(metadata, 'rollout.session_id') = {session_id:String} ORDER BY start_time", { session_id: sessionId })).map((row) => ({
 		note: readNoteFromMetadata(row.metadata),
 		traceId: String(row.id ?? ""),
@@ -2092,6 +2207,104 @@ const handleDebugSessionSummary = async (client, sessionId, opts) => {
 	});
 	console.log(blocks.join("\n\n"));
 };
+/**
+* Build the frontend debugger-session URL. The frontend URL is its own env var
+* (LMNR_FRONTEND_URL) with a cloud default; self-host/local sets it explicitly.
+*/
+const buildDebuggerUrl = (projectId, sessionId) => {
+	return `${process.env.LMNR_FRONTEND_URL?.trim().replace(/\/+$/, "") || "https://laminar.sh"}/project/${projectId}/debugger-sessions/${sessionId}`;
+};
+/**
+* Open a debug session's debugger page in the browser.
+*
+* The target session is the optional `--session-id` flag; when omitted the
+* session comes from `.lmnr/debug-session.json` (see `resolveSessionId`).
+* The URL is the file's stored `debugger_url` when it belongs to the resolved
+* session, else it is rebuilt from the resolved project (`--project-id` or the
+* linked `.lmnr/project.json`) + LMNR_FRONTEND_URL.
+*
+* Local-only handler (registered via `withLocalOpts`, NOT `withProjectClient`):
+* everything needed lives on disk, so no auth resolution / API call — `open`
+* works offline and before login.
+*/
+const handleDebugSessionOpen = async (opts) => {
+	const sessionId = resolveSessionId(opts.sessionId);
+	const file = readDebugSessionFile(resolveDebugSessionDir());
+	let debuggerUrl = file?.session_id === sessionId ? file.debugger_url : null;
+	if (!debuggerUrl) {
+		const projectId = opts.projectId || (await readLocalProjectFile())?.projectId;
+		if (!projectId) throw new Error("Cannot build the debugger URL: no project is linked to this directory. Pass --project-id or run `lmnr-cli setup`.");
+		debuggerUrl = buildDebuggerUrl(projectId, sessionId);
+	}
+	if (opts.json) outputJson({
+		sessionId,
+		debuggerUrl
+	});
+	else console.log(debuggerUrl);
+	try {
+		await (0, open.default)(debuggerUrl);
+	} catch (e) {
+		logger$1.warn(`Could not open a browser (${errorMessage(e)}). URL: ${debuggerUrl}`);
+	}
+};
+/**
+* Mint a fresh debug session and reset `.lmnr/debug-session.json` to it.
+*
+* The next `LMNR_DEBUG=1 <run>` in this directory reads that file and rejoins the
+* minted session silently (no browser) — "new session" is owned by this command;
+* the SDK only mints when no file exists.
+*
+* Ordering matters: the local file is written FIRST (so the minted session is
+* usable for `LMNR_DEBUG=1` continuation even if the network is down / the
+* backend endpoint isn't deployed yet), THEN the session is best-effort
+* registered with the backend. A registration failure WARNS but does not fail
+* the command (exit 0) — the file is already written.
+*
+* Pure handler: the command wrapper (`withProjectClient`) resolves a user-token
+* {@link LaminarClient} (routes `register()` to `POST /v1/cli/rollouts/{id}` with
+* the resolved project) and owns the error envelope.
+*/
+const handleDebugSessionNew = async (client, opts) => {
+	const sessionId = (0, node_crypto.randomUUID)();
+	const sessionDir = resolveDebugSessionDir();
+	writeDebugSessionFile({
+		session_id: sessionId,
+		trace_id: null,
+		replay_trace_id: null,
+		cache_until: null,
+		debugger_url: null,
+		started_at: (/* @__PURE__ */ new Date()).toISOString()
+	}, sessionDir);
+	let projectId = null;
+	try {
+		projectId = await client.rolloutSessions.register({ sessionId });
+	} catch (e) {
+		logger$1.warn(`Could not register the debug session with the backend (the local .lmnr/debug-session.json is still usable): ${errorMessage(e)}`);
+	}
+	const debuggerUrl = projectId ? buildDebuggerUrl(projectId, sessionId) : null;
+	if (debuggerUrl) writeDebugSessionFile({
+		session_id: sessionId,
+		trace_id: null,
+		replay_trace_id: null,
+		cache_until: null,
+		debugger_url: debuggerUrl,
+		started_at: (/* @__PURE__ */ new Date()).toISOString()
+	}, sessionDir);
+	if (opts.json) {
+		outputJson({
+			sessionId,
+			projectId,
+			debuggerUrl
+		});
+		return;
+	}
+	if (debuggerUrl) logger$1.info(`New debug session: ${debuggerUrl}`);
+	else logger$1.info(`New debug session: ${sessionId}`);
+	console.log(sessionId);
+	if (opts.browser !== false && debuggerUrl) try {
+		await (0, open.default)(debuggerUrl);
+	} catch {}
+};
 //#endregion
 //#region src/utils/colors.ts
 function enabledFor(stream) {
@@ -2195,7 +2408,7 @@ function trimSlash$2(url) {
 */
 const handleProjectsList = async (client, opts) => {
 	const projects = await client.cli.listProjects();
-	const linked = (await readProjectLink())?.projectId;
+	const linked = (await readLocalProjectFile())?.projectId;
 	if (opts.json) {
 		outputJson(projects.map((p) => ({
 			...p,
@@ -2565,7 +2778,7 @@ async function handleSetup(options) {
 	const cwd = process.cwd();
 	const existingKey = await findEnvKey(cwd);
 	let creds = await safeReadCredentials();
-	let link = await readProjectLink();
+	let link = await readLocalProjectFile();
 	if (!creds) {
 		let login;
 		try {
@@ -2742,7 +2955,7 @@ async function resolveProjectViaCli(creds, userBaseUrl, issuer, isJson, options)
 		}
 		chosen = await promptProjectChoice(projects);
 	}
-	const linkPath = await writeProjectLink({
+	const linkPath = await writeLocalProjectFile({
 		projectId: chosen.id,
 		projectName: chosen.name,
 		workspaceId: chosen.workspaceId,
@@ -2772,7 +2985,7 @@ async function writeLink(issuer, userBaseUrl, projectId, isJson) {
 		}
 	} catch {}
 	try {
-		const linkPath = await writeProjectLink(link);
+		const linkPath = await writeLocalProjectFile(link);
 		if (!isJson) process.stderr.write(`${pc.green("✓")} Linked ${linkPath}\n`);
 	} catch (err) {
 		if (!isJson) process.stderr.write(`${pc.yellow("Warning")}: could not write .lmnr/project.json (${describeError(err)}). CLI commands will need --project-id ${projectId}.\n`);
@@ -2924,7 +3137,15 @@ Available tables:
 
   signal_events
     id (UUID), signal_id (UUID), trace_id (UUID), run_id (UUID),
-    name (String), payload (String), timestamp (DateTime64)
+    name (String), payload (String), timestamp (DateTime64),
+    severity (UInt8: 0=INFO|1=WARNING|2=CRITICAL), summary (String),
+    clusters (Array(UUID))
+
+  clusters
+    id (UUID), signal_id (UUID), name (String),
+    level (UInt8), parent_id (UUID), num_signal_events (UInt32),
+    num_children_clusters (UInt16),
+    created_at (DateTime64), updated_at (DateTime64)
 
   signal_runs
     signal_id (UUID), job_id (UUID), trigger_id (UUID), run_id (UUID),
@@ -2953,6 +3174,10 @@ const NOTE_SEPARATOR = "\n\n";
 * as `existing + "\n\n" + note`. The note may contain markdown /
 * span-reference links.
 *
+* The target trace is the optional `--trace-id` flag; when omitted the trace
+* comes from `.lmnr/debug-session.json`'s `trace_id` — the root trace of the
+* most recent debug run in this directory (see `resolveTraceId`).
+*
 * Pure handler: the command wrapper (`withProjectClient`) resolves a user-token
 * {@link LaminarClient} (routes to `/v1/cli/*` with the resolved project) and
 * owns the error envelope (`--json` → structured error + exit, else log + exit).
@@ -2967,8 +3192,8 @@ const NOTE_SEPARATOR = "\n\n";
 * the metadata patch endpoint that concatenates within the Postgres UPDATE,
 * which already serializes on the trace row lock).
 */
-const handleTraceAppendNote = async (client, traceId, note, opts) => {
-	const id = normalizeTraceId(traceId);
+const handleTraceAppendNote = async (client, note, opts) => {
+	const id = normalizeTraceId(resolveTraceId(opts.traceId));
 	const rows = await client.sql.query("SELECT metadata FROM traces WHERE id = {trace_id:UUID} LIMIT 1", { trace_id: id });
 	if (rows.length === 0) throw new Error(`Trace ${id} not found. If the run just finished, the trace may not be flushed yet. Retry in a few seconds.`);
 	const existing = readNoteFromMetadata(rows[0].metadata);
@@ -3017,23 +3242,35 @@ Examples:
 	program.command("setup").description("One-shot onboarding: login, select a project, write its key to .env, link .lmnr, and install the Laminar agent skill").option("--write-env", "Write LMNR_PROJECT_API_KEY to ./.env (default)", true).option("--no-write-env", "Do not write to ./.env").option("--project-id <id>", "Project to link when you can access more than one (disambiguates the project_ambiguous case in --json mode)").option("--json", "Emit a machine-readable JSON line on stdout").option("--no-browser", "Do not auto-open the device-flow URL").option("--frontend-url <url>", "Frontend URL (issuer). Defaults to LMNR_FRONTEND_URL or https://laminar.sh").option("--base-url <url>", "Base URL for the Laminar API. Defaults to LMNR_BASE_URL or https://api.lmnr.ai").action(async (options) => {
 		await handleSetup(options);
 	});
-	program.command("trace").description("Inspect and operate on traces").option("--project-id <id>", "Target project id. Defaults to the linked .lmnr/project.json. Run `lmnr-cli login` first.").option("--base-url <url>", "Base URL for the Laminar API. Defaults to https://api.lmnr.ai or LMNR_BASE_URL env variable").option("--port <port>", "Port for the Laminar API. Defaults to 443", (val) => parseInt(val, 10)).option("--json", "Output structured JSON to stdout").command("append-note").description("Append a free-text note to a trace (stored in trace metadata)").argument("<trace-id>", "Trace ID (UUID or 32-char OTel hex trace id)").argument("<note>", "Note text (may contain markdown)").action(withProjectClient(handleTraceAppendNote)).addHelpText("after", `
+	program.command("trace").description("Inspect and operate on traces").option("--project-id <id>", "Target project id. Defaults to the linked .lmnr/project.json. Run `lmnr-cli login` first.").option("--base-url <url>", "Base URL for the Laminar API. Defaults to https://api.lmnr.ai or LMNR_BASE_URL env variable").option("--port <port>", "Port for the Laminar API. Defaults to 443", (val) => parseInt(val, 10)).option("--json", "Output structured JSON to stdout").command("append-note").description("Append a free-text note to a trace (stored in trace metadata)").argument("<note>", "Note text (may contain markdown)").option("--trace-id <id>", "Trace ID (UUID or 32-char OTel hex trace id). Defaults to the trace_id of .lmnr/debug-session.json (the most recent debug run here)").action(withProjectClient(handleTraceAppendNote)).addHelpText("after", `
 Notes accumulate: each call appends a new paragraph to the trace's existing
 note rather than overwriting it.
 
+Without --trace-id, the note goes to the trace_id recorded in
+.lmnr/debug-session.json — the root trace of the most recent LMNR_DEBUG=1 run
+in this directory.
+
 Examples:
-  $ lmnr-cli trace append-note <trace-id> "Reproduced the timeout on the search tool."
+  $ lmnr-cli trace append-note "Reproduced the timeout on the search tool."
+  $ lmnr-cli trace append-note "Reproduced the timeout." --trace-id <trace-id>
 `);
 	const debugSessionCmd = program.command("debug").description("Operate on debug sessions").option("--project-id <id>", "Target project id. Defaults to the linked .lmnr/project.json. Run `lmnr-cli login` first.").option("--base-url <url>", "Base URL for the Laminar API. Defaults to https://api.lmnr.ai or LMNR_BASE_URL env variable").option("--port <port>", "Port for the Laminar API. Defaults to 443", (val) => parseInt(val, 10)).option("--json", "Output structured JSON to stdout").addHelpText("after", `
 Learn more about debugging features at https://laminar.sh/docs/platform/debugger
 `).command("session").description("Manage debug sessions").addHelpText("after", `
 Learn more about debugging features at https://laminar.sh/docs/platform/debugger
 `);
-	debugSessionCmd.command("set-name").description("Set the display name of a debug session").argument("<session-id>", "Debug session ID").argument("<name>", "Session display name").action(withProjectClient(handleDebugSessionSetName)).addHelpText("after", `
+	debugSessionCmd.command("set-name").description("Set the display name of a debug session").argument("<name>", "Session display name").option("--session-id <id>", "Debug session ID. Defaults to the session in .lmnr/debug-session.json").action(withProjectClient(handleDebugSessionSetName)).addHelpText("after", `
+Without --session-id, the name applies to the session recorded in
+.lmnr/debug-session.json (written by \`debug session new\` / LMNR_DEBUG=1 runs).
+
 Examples:
-  $ lmnr-cli debug session set-name <session-id> "Fix report length + search tool"
+  $ lmnr-cli debug session set-name "Fix report length + search tool"
+  $ lmnr-cli debug session set-name "Fix report length" --session-id <session-id>
 `);
-	debugSessionCmd.command("summary").description("Print every trace in a debug session with its note, oldest first").argument("<session-id>", "Debug session ID").action(withProjectClient(handleDebugSessionSummary)).addHelpText("after", `
+	debugSessionCmd.command("summary").description("Print every trace in a debug session with its note, oldest first").option("--session-id <id>", "Debug session ID. Defaults to the session in .lmnr/debug-session.json").action(withProjectClient(handleDebugSessionSummary)).addHelpText("after", `
+Without --session-id, summarizes the session recorded in
+.lmnr/debug-session.json (written by \`debug session new\` / LMNR_DEBUG=1 runs).
+
 Output is one block per trace (oldest first), the trace's note followed by a
 self-closing tag carrying the trace id and end time:
 
@@ -3043,8 +3280,31 @@ self-closing tag carrying the trace id and end time:
 With --json, prints an array of {"note", "traceId", "endTime"} objects.
 
 Examples:
-  $ lmnr-cli debug session summary <session-id>
-  $ lmnr-cli debug session summary <session-id> --json
+  $ lmnr-cli debug session summary
+  $ lmnr-cli debug session summary --session-id <session-id> --json
+`);
+	debugSessionCmd.command("open").description("Open a debug session's debugger page in the browser").option("--session-id <id>", "Debug session ID. Defaults to the session in .lmnr/debug-session.json").action(withLocalOpts(handleDebugSessionOpen)).addHelpText("after", `
+Without --session-id, opens the session recorded in .lmnr/debug-session.json
+(written by \`debug session new\` / LMNR_DEBUG=1 runs). The URL is also printed
+to stdout; in --json mode a {"sessionId","debuggerUrl"} object is printed
+instead. Local-only: no login or network needed.
+
+Examples:
+  $ lmnr-cli debug session open
+  $ lmnr-cli debug session open --session-id <session-id>
+`);
+	debugSessionCmd.command("new").description("Create a fresh debug session and reset .lmnr/debug-session.json").option("--no-browser", "Do not open the debugger session URL in a browser").action(withProjectClient(handleDebugSessionNew)).addHelpText("after", `
+Mints a new session id, writes it to .lmnr/debug-session.json (resetting any
+prior session), and registers it with the backend. The next \`LMNR_DEBUG=1 <run>\`
+in this directory rejoins this session silently (no browser).
+
+The bare session id is printed to stdout; in --json mode a
+{"sessionId","projectId","debuggerUrl"} object is printed instead.
+
+Examples:
+  $ lmnr-cli debug session new
+  $ lmnr-cli debug session new --json
+  $ lmnr-cli debug session new --no-browser
 `);
 	program.addHelpText("after", `
 Authentication:
@@ -3064,9 +3324,11 @@ Examples:
   lmnr-cli dataset pull output.jsonl -n my-dataset --json  # Pull data from a dataset
   lmnr-cli sql query "SELECT * FROM spans LIMIT 10" --json # Query spans
   lmnr-cli sql schema                                      # Show available tables
-  lmnr-cli trace append-note <trace-id> "note text"        # Append a note to a trace
-  lmnr-cli debug session set-name <session-id> "title"     # Rename a debug session
-  lmnr-cli debug session summary <session-id>              # Notes for each trace in a session
+  lmnr-cli trace append-note "note text"                   # Note on the latest debug trace
+  lmnr-cli debug session new                               # Mint a fresh debug session
+  lmnr-cli debug session open                              # Open the session in the browser
+  lmnr-cli debug session set-name "title"                  # Rename the current debug session
+  lmnr-cli debug session summary                           # Notes for each trace in the session
 
 For more information about the Laminar platfrom:
   Documentation: https://laminar.sh/docs