chamba 0.3.1 → 0.4.0

package/templates/webterm/config.js

@@ -0,0 +1,269 @@
+// config.js - Single place for the knobs the server reads at startup.
+// Values fall back to sane defaults so `node server.js` just works inside the container.
+// Nothing here is claude-specific: the relayed agent is whichever one `webterm <agent>` was given.
+
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { existsSync, statSync } from "node:fs";
+import { basename, join, relative, resolve, sep } from "node:path";
+
+// The server always binds this container port. chamba publishes it to a host port
+// (127.0.0.1:HOST:3899); the host side may differ per workspace, this side never does.
+export const PORT = Number(process.env.WEBTERM_PORT) || 3899;
+
+// The agents this server will run. One server relays all of them - the agent is per session - so this is the
+// list a session may be started with, and the same list the `webterm` launcher accepts. Nothing else may be
+// spawned: the browser names an agent, and a name that is not in here is refused rather than run.
+export const AGENTS = ["claude", "opencode", "codex"];
+
+export function isKnownAgent(name) {
+    return typeof name === "string" && AGENTS.includes(name);
+}
+
+// The agent a session gets when the browser does not name one, which is the one-click "+ New session". The
+// `webterm` launcher sets it from the agent the user named, so the fallback only applies to a bare
+// `node server.js`. It moves at runtime (POST /agent), so the server holds its own copy of this.
+export const DEFAULT_AGENT = isKnownAgent(process.env.WEBTERM_AGENT) ? process.env.WEBTERM_AGENT : AGENTS[0];
+
+// Extra arguments for the default agent, and only for it: they come from the same launcher run that named it,
+// so they mean nothing to any other agent the browser might start.
+export const AGENT_ARGS = (process.env.WEBTERM_AGENT_ARGS || "").split(/\s+/).filter(Boolean);
+
+// Resume marker: a host-written file whose content is the full command that resumes the most
+// recent conversation. The first session to consume it (rename-then-read, atomic) spawns that
+// command instead of the default agent; later sessions start fresh. Empty means resume is disabled,
+// so a standalone `node server.js` behaves exactly as before.
+export const RESUME_MARKER = process.env.WEBTERM_RESUME_MARKER || "";
+
+// One-line file naming the agent new sessions get, written once the port is bound and again whenever the
+// default moves. The `webterm` launcher reads it so a second run can say what is live instead of just
+// "already running": probing the port proves something is listening, never what it runs. Empty disables it.
+// Its directory is bind-mounted from the host workspace cache, so the choice also survives this container:
+// chamba reads the same file when it starts the interface at the next container start.
+export const STATE_FILE = process.env.WEBTERM_STATE_FILE || "/home/devuser/.chamba-webterm/agent";
+
+// The mounted workspace, and the only tree a session may be started in. Every directory the interface
+// deals with is this one or something under it.
+export const WORKSPACE_ROOT = "/workspace";
+
+// This user's home in the container. Every agent store the pane reads, and the pane's own directory, hang
+// off it. Guarded because a detached `docker exec` need not carry HOME.
+export const HOME = process.env.HOME || "/home/devuser";
+
+// --- The web pane ------------------------------------------------------------------------------------------------------------------------
+//
+// Pages published by the agents, one directory per conversation. Bind-mounted from the host workspace cache,
+// which is what makes a page outlive the container and a resumed conversation find its own history.
+
+export const PANE_DIR = process.env.WEBTERM_PANE_DIR || `${HOME}/.webpane`;
+
+// Caps, enforced by the server rather than by the helper: a page is refused above the first, and a publish
+// is refused once the whole directory has reached the second. Nothing is ever deleted to make room - a page
+// the user has not read yet is not the server's to throw away - so reaching the cap is a message, not a
+// cleanup. A page is a document, so a couple of megabytes is already generous; the total is the backstop.
+export const MAX_PAGE_BYTES = Number(process.env.WEBTERM_MAX_PAGE_BYTES) || 2 * 1024 * 1024;
+export const MAX_PANE_BYTES = Number(process.env.WEBTERM_MAX_PANE_BYTES) || 128 * 1024 * 1024;
+
+// And a cap on how many files, not only how many bytes. Answers are small, so the byte cap alone would let a
+// page that submits to itself put hundreds of thousands of them in the directory - and every write walks the
+// whole tree to add the bytes up, so that walk is what would slow down. A personal pane holds tens of pages.
+export const MAX_PANE_FILES = Number(process.env.WEBTERM_MAX_PANE_FILES) || 5_000;
+
+// How often the pane directories are looked at again. This is what notices a file written by hand rather
+// than through the helper, and it is also when a session that has no conversation id yet asks for one.
+// Deliberately a poll and not a watch: the directory is a bind mount, and inotify does not cross one on
+// every host.
+export const PANE_SCAN_MS = Number(process.env.WEBTERM_PANE_SCAN_MS) || 1_500;
+
+// --- The status strip --------------------------------------------------------------------------------------------------------------------
+
+// How often a session's snapshot file is looked at again for the strip above the composer. A poll for the
+// same reason the pane's is: the file is written into a bind mount by a shell script, and there is nothing to
+// subscribe to. Claude Code rewrites it on every prompt render, so this is really "how quickly the strip
+// catches up", and a frame goes out only when something in it actually changed.
+export const STATUS_SCAN_MS = Number(process.env.WEBTERM_STATUS_SCAN_MS) || 2_000;
+
+// What a feedback submission may be. The body cap is what the endpoint accepts at all; the rest bound what
+// is written, so a page with a runaway form produces a file an agent can still read.
+export const MAX_FEEDBACK_BYTES = 64 * 1024;
+export const MAX_FEEDBACK_FIELDS = 40;
+export const MAX_FEEDBACK_FIELD_LENGTH = 4_000;
+export const MAX_FEEDBACK_TEXT_LENGTH = 8_000;
+
+// Shortest gap between two submissions on the same page. A form is submitted by a person, so anything faster
+// is a stuck button or a script; refusing it keeps one page from filling the directory with files.
+export const FEEDBACK_MIN_INTERVAL_MS = Number(process.env.WEBTERM_FEEDBACK_MIN_INTERVAL_MS) || 1_000;
+
+// How many answers one page may file at all. A person submits a form once, or a few times after changing
+// their mind. Past that it is a script in the page submitting to itself, and each submission also types a
+// line into the agent's terminal - so this, not the byte cap, is what bounds how often a page can drive an
+// agent. The gap above only slows that down; this stops it.
+export const MAX_FEEDBACK_PER_PAGE = Number(process.env.WEBTERM_MAX_FEEDBACK_PER_PAGE) || 20;
+
+// Where each agent writes down which conversation it is having. All of them are chamba mounts, so they hold
+// what earlier containers wrote too - which is exactly what makes a resumed conversation findable, and why
+// the reads that use them check the process and the directory rather than trusting recency alone.
+export const AGENT_STORES = {
+    claudeSnapshots: process.env.WEBTERM_CLAUDE_SNAPSHOT_DIR || `${HOME}/.claude/context-usage`,
+    claudeProjects: process.env.WEBTERM_CLAUDE_PROJECTS_DIR || `${HOME}/.claude/projects`,
+    codexSessions: process.env.WEBTERM_CODEX_SESSIONS_DIR || `${HOME}/.codex/sessions`,
+    opencodeSessions: process.env.WEBTERM_OPENCODE_SESSIONS_DIR || `${HOME}/.local/share/opencode/storage/session`,
+};
+
+/** A container path as it reads to an agent: its own home written as `~`, so a nudge names a path it can use. */
+export function homeLabel(absolute) {
+    return absolute.startsWith(`${HOME}/`) ? `~${absolute.slice(HOME.length)}` : absolute;
+}
+
+// Where sessions start unless the browser asks for somewhere else. The host sets it to the directory
+// `npx chamba` ran in, so a browser session opens where the terminal session would; a hand-run
+// `webterm <agent>` passes its own $PWD. Read raw here and checked by the server, which is what turns a
+// value from outside the workspace into a log line rather than a silent oddity.
+export const WEBTERM_CWD_RAW = process.env.WEBTERM_CWD || "";
+
+/**
+ * The absolute directory a raw value names, or null when it names nothing usable. Empty means the
+ * workspace root, a relative value is read against it, and an absolute one has to already be inside it.
+ * `root` is a parameter so this can be unit-tested against a temp dir.
+ *
+ * This is a scoping rule, not a security boundary: the container is the boundary, and an agent can cd
+ * wherever it likes once it is running. What it buys is a picker that cannot quietly start a session
+ * outside the workspace, or in a path that does not exist.
+ */
+export function resolveWorkspacePath(raw, root = WORKSPACE_ROOT) {
+    const wanted = typeof raw === "string" ? raw.trim() : "";
+    // resolve() takes both shapes: an absolute value is kept, a relative one is read against the root.
+    const full = wanted === "" ? root : resolve(root, wanted);
+    if (full !== root && !full.startsWith(root + sep)) return null;
+    try {
+        if (!statSync(full).isDirectory()) return null;
+    } catch {
+        return null; // Gone, or not readable.
+    }
+    return full;
+}
+
+/**
+ * How a directory travels to the browser: relative to the workspace root, with "" for the root itself.
+ * The one place that decides it, so the wire never carries an absolute container path and the client
+ * never has to know where the workspace is mounted.
+ */
+export function workspaceLabel(absolute, root = WORKSPACE_ROOT) {
+    return relative(root, absolute);
+}
+
+// The directory list the picker offers. A workspace can hold tens of thousands of directories, so the
+// walk is bounded on every axis: how deep it goes, how many it returns, and what it never descends into.
+// Depth 3 covers where work actually happens (apps/*/src, packages/*/lib) without listing a whole tree.
+export const DIR_SCAN_DEPTH = 3;
+export const DIR_SCAN_MAX = 400;
+export const DIR_SCAN_SKIP = new Set(["node_modules"]);
+
+// The workspace this container belongs to, shown in the session bar. Several workspaces can have their
+// own interface open at once, each on its own port, so the page says which one you are looking at.
+// Empty just leaves it out.
+export const WORKSPACE = process.env.WEBTERM_WORKSPACE || "";
+
+// A short note appended to claude's system prompt only when it is launched through the web interface,
+// so it knows it is reached in a browser rather than a terminal. The whole webterm/ dir is baked into
+// the image, so this resolves next to the server. WEBTERM_CONTEXT_FILE overrides it (used by tests).
+export const CONTEXT_FILE = process.env.WEBTERM_CONTEXT_FILE || join(import.meta.dirname, "context", "claude.md");
+
+// Build the argv a session's agent is spawned with. claude, and only claude, is told it is reached
+// through the web interface: its CLI takes a per-launch system-prompt file, so the browser-awareness
+// note rides on the spawn without touching the shared managed CLAUDE.md the terminal also reads. Every
+// other agent (opencode, codex, a bare shell) is spawned verbatim - which is decided per session, since
+// a bar can hold several agents at once. The flag is appended last, so it survives a --resume too. Lives
+// here beside CONTEXT_FILE so it imports with no server side effects, which is what lets it be
+// unit-tested without starting the server.
+export function agentSpawnArgv(cmd, args) {
+    if (basename(cmd) === "claude" && CONTEXT_FILE && existsSync(CONTEXT_FILE)) {
+        return [...args, "--append-system-prompt-file", CONTEXT_FILE];
+    }
+    return args;
+}
+
+// Where pasted/uploaded images land. Fixed to a container tmp dir on purpose:
+// it is never the host, and the weekly cleanup check only ever touches paths under here.
+export const UPLOAD_DIR = "/tmp/uploads";
+
+// Reject uploads larger than this (bytes). Images only; big files are almost always a mistake.
+export const MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
+
+// Age after which a file in UPLOAD_DIR is removed, and how often the cleanup check runs.
+// Weekly cadence, age-based - deliberately not a minute-level timer.
+export const UPLOAD_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+export const CHECK_INTERVAL_MS = 7 * 24 * 60 * 60 * 1000;
+
+// The key that the URL carries (`/?k=<key>`) and the relay demands. A fresh one is minted every time
+// this server starts, so a key never outlives the process that issued it and nothing has to store it:
+// whoever prints the URL reads it back from KEY_FILE. WEBTERM_KEY pins it (tests, hand-run debugging).
+// There is deliberately no unauthenticated mode - without the gate the relay would drive an agent for
+// any process that can reach the port, which loopback publishing alone does not prevent.
+export const KEY = process.env.WEBTERM_KEY || randomBytes(16).toString("hex");
+
+// Where the live key is published for the things that print the URL: the `webterm` launcher and the
+// container greeting read it, and so does chamba on the host (docker exec cat) before probing /status.
+// Written the moment the port is bound, so a server that never got the port leaves no key behind.
+export const KEY_FILE = process.env.WEBTERM_KEY_FILE || "/tmp/webterm.key";
+
+// Whether a presented key is the live one. Compared in constant time so a caller cannot learn the key
+// one character at a time from how long the answer takes. Lives here, beside KEY and with no server
+// side effects, which is what lets it be unit-tested without starting the server.
+export function isAuthorized(candidate) {
+    if (typeof candidate !== "string") return false;
+    // Byte lengths, not string lengths: timingSafeEqual throws on a length mismatch, and a multi-byte
+    // character makes those two differ.
+    const presented = Buffer.from(candidate);
+    const live = Buffer.from(KEY);
+    if (presented.length !== live.length) return false;
+    return timingSafeEqual(presented, live);
+}
+
+// WebSocket Origin gate, checked alongside the key: a page from a non-loopback origin cannot open the
+// relay even if it somehow holds a key. We allow any localhost / 127.0.0.1 origin regardless of port,
+// because the published host port can differ from the container port (e.g. 3900:3899) so the browser's
+// Origin varies per workspace. The publish is loopback-only, so "any local port" is the right
+// granularity: it still rejects remote origins like http://evil.com.
+export function isAllowedOrigin(origin) {
+    if (!origin) return false;
+    try {
+        const { hostname } = new URL(origin);
+        return hostname === "localhost" || hostname === "127.0.0.1";
+    } catch {
+        return false;
+    }
+}
+
+// Bracketed-paste framing. Wrapping the composed message in these markers makes the
+// TUI treat a multi-line message (text + image paths) as one paste, then Enter submits it once.
+export const PASTE_START = "\x1b[200~";
+export const PASTE_END = "\x1b[201~";
+export const SUBMIT = "\r";
+
+// Delay between delivering the paste and sending the submit Enter. When a message contains an
+// image path, claude ingests the file asynchronously; an immediate Enter can land mid-ingest and
+// be dropped (leaving the text un-submitted until a second Enter). A short gap lets the paste settle.
+export const SUBMIT_DELAY_MS = Number(process.env.WEBTERM_SUBMIT_DELAY_MS) || 150;
+
+// Stopping the container from the browser. The announce delay is how long the "going down" frame gets to
+// reach every window before PID 1 is signalled - the container can die the instant it is, and a window
+// that never heard would blame the network. The timeout is how long to wait before deciding the signal
+// was ignored (a container started with a keep-alive that traps nothing), so the page can say so.
+export const STOP_ANNOUNCE_MS = 150;
+export const STOP_TIMEOUT_MS = 3_000;
+
+// Cap on the replayed session buffer (bytes), per session. A session's PTY outlives every socket, so
+// on attach we replay up to this much recent output and the window lands back in the live conversation.
+// Older output beyond the cap is dropped from the replay (the agent's own history is unaffected).
+export const MAX_OUTPUT_BUFFER = 1_000_000;
+
+// How many sessions (live agent processes) may exist at once. Sessions are never closed for the user,
+// so this is the backstop on memory: each live agent holds a few hundred MB in the container. Reaching
+// it refuses the new session and says why, rather than quietly recycling a conversation.
+export const MAX_SESSIONS = Number(process.env.WEBTERM_MAX_SESSIONS) || 8;
+
+// WebSocket keepalive interval. A socket that stops answering pings is terminated, which releases the
+// session it was driving. Without this a laptop that slept would hold its session "attached" until TCP
+// gave up: the host would see a watcher that is not there, and the window that comes back would be
+// told its own session is busy.
+export const CLIENT_PING_INTERVAL_MS = Number(process.env.WEBTERM_PING_INTERVAL_MS) || 20_000;

package/templates/webterm/context/claude.md

@@ -0,0 +1,14 @@
+# You are running in the chamba web interface
+
+You are being reached through the chamba web interface: a browser front-end to this container, not a plain terminal.
+A person is talking to you from a web page - one session tab in their browser - while your process runs inside the container exactly as it would in the terminal.
+
+Everything else is unchanged: the same workspace, the same tools, the same container isolation.
+Two things are yours here that a terminal does not have.
+
+**The web pane.** Beside this terminal is a pane of pages, and `webpane <file.html> --title "..."` puts one there.
+Use it for anything longer or more structured than a terminal reply carries well, and to ask anything with more options or structure than your question tooling holds - a page can carry a form, and the answers come back to you as a file plus a line in this terminal.
+The `web-pane` skill is how to write one well; read it before your first page.
+
+**The status strip.** Above the composer the user can already see this session's model, the context it is holding, and what is left of the quota, so there is no need to report any of it unasked.
+Run `context-usage` when you want the same numbers yourself.

package/templates/webterm/conversation.js

@@ -0,0 +1,248 @@
+// conversation.js - Which conversation a session is having, according to the agent itself.
+//
+// The web pane files a session's pages under the agent's own conversation id, and that is the whole reason
+// this file exists. A key the server invented would be lost the moment a conversation came back by another
+// route: an auto-resume after a container restart, a `claude --resume <id>` typed by hand, a codex session
+// picked from its own list. The conversation id is the one name that survives all of them, so a resumed
+// conversation walks back into its own pages without the server having witnessed anything.
+//
+// Every agent already writes that id down somewhere the container can read - chamba mounts those directories
+// so the history outlives the container. Nothing here asks an agent anything; it reads what is on disk and
+// matches it to the session by the two facts the server holds: the process tree and the directory.
+//
+// A miss is normal and cheap. An agent that has not written its first record yet has no id to find, so the
+// answer is null, the pane keeps its provisional directory, and the next sweep asks again.
+
+import { closeSync, openSync, readdirSync, readFileSync, readSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { snapshotFor } from "./snapshot.js";
+
+// How much of a transcript is read looking for the directory it runs in. Every agent records that within its
+// first few lines; reading further would mean paging in megabytes of conversation for one field.
+const HEAD_BYTES = 64 * 1024;
+
+// How many candidate files one lookup will consider, newest first. A long-lived workspace accumulates
+// hundreds of conversations, and the one being looked for is always among the freshest.
+const MAX_CANDIDATES = 40;
+
+// The largest a snapshot or a session record can be and still be read whole. The files these stores write
+// are a few hundred bytes; the cap is only there so an unrelated file that happens to be in the directory
+// cannot be pulled into memory.
+const MAX_JSON_BYTES = 1024 * 1024;
+
+// How deep the walk goes under a store's root. Codex files sessions under a date tree
+// (sessions/2026/08/23/), opencode under a project directory; nothing goes deeper than that.
+const MAX_STORE_DEPTH = 5;
+
+/** Files under `dir` matching `pattern`, newest first, capped. Depth-limited; unreadable dirs contribute nothing. */
+function filesNewestFirst(dir, pattern, depth = MAX_STORE_DEPTH) {
+    const found = [];
+    const queue = [{ dir, depth }];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        let entries;
+        try {
+            entries = readdirSync(current.dir, { withFileTypes: true });
+        } catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const full = join(current.dir, entry.name);
+            // Symlinks are skipped rather than followed: these stores are the agents' own, and a link in one
+            // of them would only ever lead somewhere this lookup has no business reading.
+            if (entry.isDirectory() && current.depth > 0) {
+                queue.push({ dir: full, depth: current.depth - 1 });
+            } else if (entry.isFile() && pattern.test(entry.name)) {
+                try {
+                    found.push({ path: full, mtime: statSync(full).mtimeMs });
+                } catch {
+                    // Vanished between the listing and the stat.
+                }
+            }
+        }
+    }
+    return found
+        .sort((a, b) => b.mtime - a.mtime)
+        .slice(0, MAX_CANDIDATES)
+        .map((entry) => entry.path);
+}
+
+/**
+ * The head of a file as text, or "" when it cannot be read.
+ *
+ * Bounded at the read, not after it: a live transcript is tens of megabytes and there may be forty of them
+ * to look at, on a timer, until an id is found. Reading them whole would stall every session in the
+ * container for the sake of a field in the first few lines.
+ */
+function readHead(path) {
+    let fd = null;
+    try {
+        fd = openSync(path, "r");
+        const buffer = Buffer.alloc(HEAD_BYTES);
+        const read = readSync(fd, buffer, 0, HEAD_BYTES, 0);
+        return buffer.subarray(0, read).toString("utf8");
+    } catch {
+        return "";
+    } finally {
+        if (fd !== null) closeSync(fd);
+    }
+}
+
+/**
+ * A whole JSON file as an object, or null. Whole, because a record cut in half parses as nothing - so the
+ * size is checked first instead, and anything that is not the small record these stores write is not one.
+ */
+function readJson(path) {
+    try {
+        if (statSync(path).size > MAX_JSON_BYTES) return null;
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : null;
+    } catch {
+        return null;
+    }
+}
+
+/** When a file last changed, or 0 when it is gone. */
+function mtimeOf(path) {
+    try {
+        return statSync(path).mtimeMs;
+    } catch {
+        return 0;
+    }
+}
+
+/**
+ * The directory a JSONL transcript says it runs in, read from its first records: the first `cwd` (or
+ * `directory`) string any of them carries. Returns null when none of them says - transcripts written before
+ * the agent recorded it, and the one case where the directory cannot be used to tell conversations apart.
+ */
+function recordedCwd(path) {
+    for (const line of readHead(path).split("\n")) {
+        if (!line.includes('"cwd"') && !line.includes('"directory"')) continue;
+        let record;
+        try {
+            record = JSON.parse(line);
+        } catch {
+            continue; // A line cut in half by the read window, or one that is not JSON at all.
+        }
+        const found = firstPathField(record);
+        if (found !== null) return found;
+    }
+    return null;
+}
+
+// The first `cwd`/`directory` string in a record, looked for one level into the record's own objects too:
+// codex wraps its fields in a payload, and which wrapper is in fashion is not something to hard-code.
+function firstPathField(record) {
+    if (!record || typeof record !== "object") return null;
+    for (const key of ["cwd", "directory"]) {
+        if (typeof record[key] === "string" && record[key] !== "") return record[key];
+    }
+    for (const value of Object.values(record)) {
+        if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+        for (const key of ["cwd", "directory"]) {
+            if (typeof value[key] === "string" && value[key] !== "") return value[key];
+        }
+    }
+    return null;
+}
+
+/**
+ * True when a conversation file may belong to this session: it changed since the session started, and it
+ * either records this session's directory or records none at all.
+ *
+ * The time check is what keeps a session from adopting a conversation it never had - yesterday's transcript
+ * in the same directory is not this session's, however recently it was the newest. A resumed conversation
+ * passes it: resuming writes to the transcript, which is what makes it recent again.
+ */
+function couldBelong(path, cwd, since) {
+    if (mtimeOf(path) < since) return false;
+    const recorded = recordedCwd(path);
+    return recorded === null || recorded === cwd;
+}
+
+// --- Claude ------------------------------------------------------------------------------------------------------------------------------
+
+const CLAUDE_TRANSCRIPT = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.jsonl$/;
+
+/**
+ * Claude's conversation id for a session, by two routes.
+ *
+ * The first is the status line's own snapshot: it names the conversation and the claude process that wrote
+ * it, so a snapshot that belongs to this session (snapshot.js decides that, and the status strip asks the
+ * same question the same way) names this session's conversation, whatever else is running. That is an
+ * identity rather than a guess.
+ *
+ * The second is for the minutes before the status line has rendered: the newest transcript that recorded
+ * this session's directory. Weaker (two sessions in one directory could both point at it) but bounded by the
+ * session's own start time, and replaced by the first route as soon as a snapshot appears.
+ */
+export function claudeConversationId(session, stores) {
+    const id = snapshotFor(session, stores.claudeSnapshots)?.session_id;
+    if (typeof id === "string" && id !== "") return id;
+    for (const path of filesNewestFirst(stores.claudeProjects, CLAUDE_TRANSCRIPT)) {
+        if (couldBelong(path, session.cwd, session.since)) return basename(path).slice(0, -".jsonl".length);
+    }
+    return null;
+}
+
+// --- Codex -------------------------------------------------------------------------------------------------------------------------------
+
+// rollout-<timestamp>-<uuid>.jsonl - the uuid is the conversation id codex resumes by.
+const CODEX_ROLLOUT = /^rollout-.*-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/;
+
+/** Codex's conversation id for a session: the newest rollout file that could be this session's. */
+export function codexConversationId(session, stores) {
+    for (const path of filesNewestFirst(stores.codexSessions, CODEX_ROLLOUT)) {
+        if (!couldBelong(path, session.cwd, session.since)) continue;
+        const match = CODEX_ROLLOUT.exec(basename(path));
+        if (match) return match[1];
+    }
+    return null;
+}
+
+// --- OpenCode ----------------------------------------------------------------------------------------------------------------------------
+
+/**
+ * OpenCode's conversation id for a session: the newest session record in its local store that could be this
+ * session's. The id comes from the record when it carries one and from the filename otherwise, which is the
+ * same value - opencode names the file after the session.
+ */
+export function opencodeConversationId(session, stores) {
+    for (const path of filesNewestFirst(stores.opencodeSessions, /\.json$/)) {
+        if (mtimeOf(path) < session.since) continue;
+        const record = readJson(path);
+        const recorded = firstPathField(record);
+        if (recorded !== null && recorded !== session.cwd) continue;
+        const id = typeof record?.id === "string" && record.id !== "" ? record.id : basename(path, ".json");
+        if (id !== "") return id;
+    }
+    return null;
+}
+
+// --- The one entry point -----------------------------------------------------------------------------------------------------------------
+
+const BY_AGENT = {
+    claude: claudeConversationId,
+    codex: codexConversationId,
+    opencode: opencodeConversationId,
+};
+
+/**
+ * The conversation id for a session, or null when there is nothing to find yet.
+ *
+ * `session` is `{ agent, cwd, pid, since }`: the agent decides which store is read, the directory and the
+ * start time bound what may match, and the pid is the session's PTY leader - the root of the process tree
+ * the agent runs in. An agent nobody wrote a reader for (a plain shell, something new) has no id, which is a
+ * supported answer rather than an error: those sessions keep a provisional key for their whole life.
+ */
+export function conversationId(session, stores) {
+    const lookup = BY_AGENT[session.agent];
+    if (!lookup) return null;
+    try {
+        return lookup(session, stores);
+    } catch {
+        // A store that changed shape under us must never take the session down with it.
+        return null;
+    }
+}