excaliagent 0.3.0 → 0.4.0

package/dist/server/http.js

@@ -4,6 +4,7 @@ import { extname, join, normalize, sep } from "node:path";
 import { timingSafeEqual } from "node:crypto";
 import { SESSION_ID } from "./hub.js";
 import { validFile } from "./scene-store.js";
+import { StatusError } from "./characters.js";
 /** Cookies ignore the port, so the name carries it: two boards never clobber each other. */
 export const cookieName = (port) => `excaliagent_token_${port}`;
 /** The token is stable per state dir (token.ts), so the cookie may outlive a restart. */
@@ -53,15 +54,21 @@ function text(res, status, body) {
     res.writeHead(status, { "content-type": "text/plain; charset=utf-8" });
     res.end(body);
 }
-async function readJson(req) {
+/** Body limits of the character and pack routes: an image upload, everything else. */
+export const IMAGE_BODY_LIMIT = 1536 * 1024;
+export const SMALL_BODY_LIMIT = 64 * 1024;
+async function readJson(req, limit = MAX_BODY) {
     if (!(req.headers["content-type"] ?? "").startsWith("application/json")) {
         throw new HttpError(415, "expected application/json");
     }
+    // Refuse a declared oversize body before reading any of it.
+    if (Number(req.headers["content-length"] ?? 0) > limit)
+        throw new HttpError(413, "body too large");
     const chunks = [];
     let size = 0;
     for await (const chunk of req) {
         size += chunk.length;
-        if (size > MAX_BODY)
+        if (size > limit)
             throw new HttpError(413, "body too large");
         chunks.push(chunk);
     }
@@ -122,9 +129,77 @@ export function createAppServer(opts) {
             unsubscribe();
         });
     }
-    async function api(req, res, pathname) {
+    /** GET /api/packs/<pack>/<file>: a custom pack's image, only if that pack lists it. */
+    async function packImage(res, rest, version) {
+        const parts = rest.split("/");
+        if (parts.length !== 2)
+            return json(res, 404, { error: "not found" });
+        let pack, file;
+        try {
+            [pack, file] = parts.map((p) => decodeURIComponent(p));
+        }
+        catch {
+            throw new HttpError(400, "bad path");
+        }
+        const img = await opts.characters.readImage(pack, file);
+        if (!img)
+            return json(res, 404, { error: "not found" });
+        res.writeHead(200, {
+            "content-type": img.mimeType,
+            // `?v=<content hash>` (from the pack listing) names these exact bytes.
+            "cache-control": version === img.hash ? "private, max-age=31536000, immutable" : "no-store",
+            "x-content-type-options": "nosniff",
+            // An SVG opened directly must not run scripts on our origin.
+            "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; sandbox",
+        });
+        res.end(img.bytes);
+    }
+    async function api(req, res, pathname, search) {
         const route = `${req.method} ${pathname}`;
+        if (req.method === "GET" && pathname.startsWith("/api/packs/"))
+            return packImage(res, pathname.slice("/api/packs/".length), search.get("v"));
+        const chars = opts.characters;
+        const body = async () => {
+            const b = await readJson(req, pathname === "/api/packs/image" ? IMAGE_BODY_LIMIT : SMALL_BODY_LIMIT);
+            if (!b || typeof b !== "object")
+                throw new HttpError(400, "expected a JSON object");
+            return b;
+        };
         switch (route) {
+            case "GET /api/characters":
+                return json(res, 200, await chars.load());
+            case "POST /api/characters/assign": {
+                const b = await body();
+                return json(res, 200, await chars.assign(b.pack, b.assign));
+            }
+            case "POST /api/characters/override": {
+                const b = await body();
+                return json(res, 200, await chars.override(b.sessionId, (b.character ?? null)));
+            }
+            case "POST /api/characters/active":
+                return json(res, 200, await chars.setActive((await body()).pack));
+            case "POST /api/packs": {
+                const b = await body();
+                return json(res, 200, await chars.createPack(b.name, (b.from ?? undefined)));
+            }
+            case "POST /api/packs/rename": {
+                const b = await body();
+                return json(res, 200, await chars.renamePack(b.pack, b.name));
+            }
+            case "POST /api/packs/delete":
+                return json(res, 200, await chars.deletePack((await body()).pack));
+            case "POST /api/packs/emoji": {
+                const b = await body();
+                return json(res, 200, await chars.addEmoji(b.pack, b.emoji));
+            }
+            case "POST /api/packs/image": {
+                const b = await body();
+                return json(res, 200, await chars.addImage(b.pack, b.name, b.dataURL));
+            }
+            case "POST /api/packs/remove": {
+                const b = await body();
+                return json(res, 200, await chars.removeCharacter(b.pack, b.id));
+            }
             case "GET /api/sessions":
                 return json(res, 200, opts.hub.sessions());
             case "GET /api/events":
@@ -167,6 +242,20 @@ export function createAppServer(opts) {
                 }
                 return json(res, 200, await opts.scenes.loadFiles(body.ids));
             }
+            case "POST /api/end": {
+                const body = (await readJson(req));
+                if (typeof body?.sessionId !== "string" || !SESSION_ID.test(body.sessionId)) {
+                    throw new HttpError(400, "sessionId must be a session id");
+                }
+                const result = await opts.hub.end(body.sessionId);
+                if (result === "ended") {
+                    res.writeHead(204).end();
+                    return;
+                }
+                if (result === "unsupported")
+                    return json(res, 501, { error: "unsupported" });
+                return json(res, 409, { error: "not running" });
+            }
             case "POST /api/focus": {
                 const body = (await readJson(req));
                 if (typeof body?.sessionId !== "string")
@@ -180,7 +269,7 @@ export function createAppServer(opts) {
             case "POST /api/resume": {
                 const body = (await readJson(req));
                 if (typeof body?.sessionId !== "string" || !SESSION_ID.test(body.sessionId)) {
-                    throw new HttpError(400, "sessionId must be a session UUID");
+                    throw new HttpError(400, "sessionId must be a session id");
                 }
                 const result = await opts.hub.resume(body.sessionId);
                 if (result === "resumed") {
@@ -220,14 +309,14 @@ export function createAppServer(opts) {
             return text(res, 401, "excaliagent: open the URL printed in the terminal (it carries the access token).");
         }
         if (url.pathname.startsWith("/api/"))
-            return api(req, res, url.pathname);
+            return api(req, res, url.pathname, url.searchParams);
         if (opts.middleware)
             return opts.middleware(req, res, () => text(res, 404, "not found"));
         return serveStatic(req, res, url.pathname);
     }
     const server = createServer((req, res) => {
         handle(req, res).catch((err) => {
-            const status = err instanceof HttpError ? err.status : 500;
+            const status = err instanceof HttpError || err instanceof StatusError ? err.status : 500;
             if (status === 500)
                 console.error("excaliagent:", err);
             if (!res.headersSent)

package/dist/server/hub.js

@@ -1,5 +1,10 @@
-/** Claude session ids are UUIDs; anything else is never put into a command. */
-export const SESSION_ID = /^[0-9a-f-]{36}$/i;
+/**
+ * The id formats of every supported harness (Claude and Codex: UUIDs;
+ * OpenCode: `ses_` + 26 alphanumerics).
+ * Anything else is refused before it reaches a source or the characters store;
+ * each source also checks its own exact format before an id goes into a command.
+ */
+export const SESSION_ID = /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|ses_[0-9a-zA-Z]{26})$/i;
 const LABEL_MAX = 40;
 function resumeLabel(s) {
     const title = s.title?.trim();
@@ -80,16 +85,25 @@ export function createHub({ source, panes }) {
                 return "unknown";
             if (s.live)
                 return "live";
+            if (!s.resumeCommand)
+                return "unknown";
             if (!panes.resume || !panes.available())
                 return "no-herdr";
             await panes.resume({
                 cwd: s.cwd,
                 ...(s.repoRoot !== undefined ? { repoRoot: s.repoRoot } : {}),
-                command: `claude --resume ${s.id}`,
+                command: s.resumeCommand,
                 label: resumeLabel(s),
             });
             return "resumed";
         },
+        async end(sessionId) {
+            if (!SESSION_ID.test(sessionId))
+                return "unknown";
+            if (!source.end)
+                return "unsupported";
+            return source.end(sessionId);
+        },
         async focus(sessionId) {
             const pane = current.find((s) => s.id === sessionId)?.pane;
             if (!pane)

package/dist/server/panes/herdr.js

@@ -50,15 +50,40 @@ export function defaultHerdrSocketPath() {
     return herdrSocketPath(process.env, homedir()) ?? join(homedir(), ".config", "herdr", "herdr.sock");
 }
 const workspaceOf = (paneId) => paneId.split(":")[0] ?? paneId;
-/** pid → pane for every foreground process of every pane; `panes` supplies ids and labels. */
-export function parsePaneMap(infos, panes = new Map()) {
+/**
+ * pid → pane for every foreground process of every pane; `panes` supplies ids
+ * and labels. With `procs` (the process table), every descendant of a pane's
+ * shell maps to that pane too: a session is not always in the foreground (a
+ * command it runs can take the terminal, or it is suspended). Foreground wins.
+ */
+export function parsePaneMap(infos, panes = new Map(), procs = []) {
     const map = new Map();
+    const byShell = new Map();
     for (const info of infos) {
         const pane = panes.get(info.pane_id) ?? { paneId: info.pane_id, workspaceId: workspaceOf(info.pane_id) };
         for (const p of info.foreground_processes ?? []) {
             if (typeof p.pid === "number")
                 map.set(p.pid, pane);
         }
+        if (typeof info.shell_pid === "number")
+            byShell.set(info.shell_pid, pane);
+    }
+    if (!byShell.size)
+        return map;
+    const children = new Map();
+    for (const p of procs)
+        children.set(p.ppid, [...(children.get(p.ppid) ?? []), p.pid]);
+    const seen = new Set(); // a pid is walked once, even if the table has a cycle
+    for (const [shell, pane] of byShell) {
+        const todo = [...(children.get(shell) ?? [])];
+        for (let pid = todo.pop(); pid !== undefined; pid = todo.pop()) {
+            if (seen.has(pid))
+                continue;
+            seen.add(pid);
+            if (!map.has(pid))
+                map.set(pid, pane);
+            todo.push(...(children.get(pid) ?? []));
+        }
     }
     return map;
 }
@@ -150,6 +175,7 @@ export function createHerdrLink(opts = {}) {
             panes.set(p.pane_id, pane);
         }
         const panesList = list;
+        const procs = table.list().catch(() => []);
         const infos = await Promise.all(panesList.map(async (p) => {
             try {
                 const res = (await client.request("pane.process_info", { pane_id: p.pane_id }));
@@ -161,7 +187,7 @@ export function createHerdrLink(opts = {}) {
         }));
         if (closed || !client.connected())
             return;
-        setMap(parsePaneMap(infos.filter((i) => !!i), panes));
+        setMap(parsePaneMap(infos.filter((i) => !!i), panes, await procs));
     }
     // Coalesce: at most one build running, plus one queued behind it.
     let running;

package/dist/server/sources/claude.js

@@ -5,10 +5,23 @@ import { watch as fsWatch } from "node:fs";
 import { readdir, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
+import { createProcessTable } from "../desktop/process-table.js";
 import { GitReader } from "./git.js";
 import { onceLogger } from "./log.js";
 import { defaultIsAlive, isLive, readRegistry } from "./registry.js";
 import { TranscriptScanner } from "./transcript.js";
+/** A Claude Code process: its executable, argv[0], or script (node cli.js) names claude. */
+export function looksLikeClaude(argv, exe) {
+    const names = [argv?.[0] && basename(argv[0]), exe && basename(exe)];
+    return names.some((n) => !!n && /claude/i.test(n)) || /claude/i.test(argv?.[1] ?? "");
+}
+function defaultIsClaudeProcess() {
+    const table = createProcessTable();
+    return async (pid) => looksLikeClaude(await table.argv(pid), await table.exe(pid));
+}
+/** Claude session ids are UUIDs; anything else is never put into a command. */
+export const CLAUDE_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const claudeResumeCommand = (id) => `claude --resume ${id}`;
 const LIVE_STATUSES = new Set([
     "busy", "idle", "waiting", "needs_user", "needs_trust", "blocked",
 ]);
@@ -26,6 +39,8 @@ export function liveSession(e, t, git) {
         live: true,
         pid: e.pid,
         prLinks: t?.prLinks ?? [],
+        resumeCommand: claudeResumeCommand(e.sessionId),
+        canEnd: true,
     };
     return withGit(withTranscriptExtras(s, t, e.name, e.waitingFor), git);
 }
@@ -42,6 +57,7 @@ export function dormantSession(f, t, fallbackCwd, git) {
         cacheExpiresAt: t.cacheExpiresAt,
         live: false,
         prLinks: t.prLinks,
+        resumeCommand: claudeResumeCommand(f.id),
     };
     // A parked session keeps the branch it was on; only the useless "HEAD" stamp
     // is replaced by the repo's current branch.
@@ -97,6 +113,8 @@ export function createClaudeSource(opts = {}) {
     const warn = onceLogger(opts.log ?? console.warn);
     const scanner = new TranscriptScanner({ warn });
     const git = new GitReader({ ttlMs: opts.gitTtlMs ?? 2000 });
+    const isClaudeProcess = opts.isClaudeProcess ?? defaultIsClaudeProcess();
+    const kill = opts.kill ?? ((pid, signal) => process.kill(pid, signal));
     const pathById = new Map();
     /** A cwd seen in any transcript of a project dir, for transcripts without one. */
     const cwdBySlug = new Map();
@@ -197,6 +215,8 @@ export function createClaudeSource(opts = {}) {
         return toDormant(files, maxDormant);
     }
     async function get(id) {
+        if (!CLAUDE_ID.test(id))
+            return undefined;
         const live = (await list()).find((s) => s.id === id);
         if (live)
             return live;
@@ -288,5 +308,20 @@ export function createClaudeSource(opts = {}) {
             watcher = undefined;
         };
     }
-    return { list, listDormant, get, watch };
+    /** SIGTERM, as when its terminal closes: Claude Code exits and keeps the transcript. */
+    async function end(id) {
+        if (!CLAUDE_ID.test(id))
+            return "not-live";
+        const e = (await liveEntries()).find((x) => x.sessionId === id);
+        if (!e || !(await isClaudeProcess(e.pid).catch(() => false)))
+            return "not-live";
+        try {
+            kill(e.pid, "SIGTERM");
+        }
+        catch {
+            return "not-live"; // exited in the meantime
+        }
+        return "ended";
+    }
+    return { list, listDormant, get, watch, end };
 }

package/dist/server/sources/codex-live.js

@@ -0,0 +1,279 @@
+// Which Codex threads are running, and in which process. Codex has no session
+// registry like Claude's; what it has (verified on 0.163.0, Linux):
+//
+// - `<codexHome>/thread-writer-locks/<thread id>.lock`: created and flock()ed
+//   by whoever has the thread loaded, unlocked and deleted when it is unloaded.
+//   Crashes leave the file but release the lock, so only a *held* lock counts:
+//   the holder is found in /proc/locks by inode and confirmed through
+//   /proc/<pid>/fd.
+// - The interactive TUI (`codex`, `codex resume <id>`) does not hold it: it
+//   talks to a shared app-server daemon (`codex app-server ... --managed-daemon`,
+//   one per Codex home) that loads the thread. The daemon keeps a thread loaded
+//   for `thread_unload_delay_secs` (default 30 min) after its last client left,
+//   so a held lock alone does not mean someone is looking at it.
+// - `codex exec` loads its thread in-process and holds the lock itself.
+//
+// So a thread held by a non-daemon codex process is live in that process. A
+// thread held by the daemon is live only when a TUI process claims it: by its
+// argv (`resume <id>`), else by working directory, among threads loaded after
+// that TUI started (a thread loaded earlier belongs to another, maybe closed,
+// TUI; a fresh TUI's own thread appears ~1.4 s after it): one with a rollout
+// if any, else its earliest new thread (with auto-review on, the daemon loads
+// a second, reviewer thread right after the conversation, which never gets a
+// rollout unless it reviews something).
+// Daemon threads no TUI claims are lingering, i.e. dormant. Only the first two
+// (in-process holder, `resume <id>`) are exact; a working-directory claim is a
+// guess, so such a session cannot be stopped from the board. Pure matching
+// lives in `assignLive`; the /proc reading around it is Linux-only and takes a
+// proc root, so tests read a synthetic tree.
+import { readdir, readFile, readlink, realpath, stat } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { createProcessTable } from "../desktop/process-table.js";
+import { CODEX_ID, uuidV7Ms } from "./codex-rollout.js";
+import { bootTime, startedAt } from "./proc.js";
+/** A Codex executable: argv[0] or exe named `codex`, or the npm shim (`node …/codex.js`). */
+export function looksLikeCodex(argv, exe) {
+    const names = [argv?.[0], exe].filter((n) => !!n).map((n) => basename(n));
+    if (names.some((n) => n === "codex" || n === "codex.exe"))
+        return true;
+    const script = argv?.[1] ? basename(argv[1]) : "";
+    return names.some((n) => /^node(\.exe)?$/.test(n)) && (script === "codex" || script === "codex.js");
+}
+// Options that take a value, so the next word is not the subcommand.
+const VALUE_FLAGS = new Set([
+    "-c", "--config", "-m", "--model", "-p", "--profile", "-s", "--sandbox", "-a", "--ask-for-approval",
+    "-C", "--cd", "-i", "--image", "--add-dir", "--enable", "--disable", "--local-provider", "--remote",
+    "--remote-auth-token-env",
+]);
+// Subcommands that are not an interactive session (the TUI is `codex [PROMPT]`, `resume`, `fork`).
+const NOT_TUI = new Set([
+    "agents", "exec", "e", "review", "login", "logout", "mcp", "plugin", "app-server", "remote-control",
+    "completion", "update", "doctor", "sandbox", "debug", "apply", "a", "queue", "archive", "delete",
+    "migrate-rollouts", "unarchive", "cloud", "exec-server", "features", "help", "mcp-server",
+]);
+/** The words after the program (and after the script, for the npm shim). */
+function args(argv) {
+    const shim = /^node(\.exe)?$/.test(basename(argv[0] ?? ""));
+    return argv.slice(shim ? 2 : 1);
+}
+/** First positional word: the subcommand, a prompt, or undefined. */
+export function codexSubcommand(argv) {
+    const a = args(argv);
+    for (let i = 0; i < a.length; i++) {
+        const w = a[i];
+        if (w === "--")
+            return a[i + 1];
+        if (w.startsWith("-")) {
+            if (VALUE_FLAGS.has(w))
+                i++;
+            continue;
+        }
+        return w;
+    }
+    return undefined;
+}
+export const isDaemon = (argv) => codexSubcommand(argv) === "app-server";
+/**
+ * An interactive Codex TUI process. Codex also runs its own binary as helpers
+ * (verified on 0.163.0: `codex-linux-sandbox ...` around every sandboxed
+ * command, once under bwrap, with the repo as cwd); those have another
+ * argv[0] (`codex-linux-sandbox`, `apply_patch`) or a `--codex-run-as-*`
+ * argv[1], and are not TUIs.
+ */
+export const isTui = (argv) => {
+    const shim = /^node(\.exe)?$/.test(basename(argv[0] ?? ""));
+    const name = basename((shim ? argv[1] : argv[0]) ?? "");
+    if (!(shim ? name === "codex" || name === "codex.js" : name === "codex" || name === "codex.exe"))
+        return false;
+    if (args(argv)[0]?.startsWith("--codex-run-as-"))
+        return false;
+    const sub = codexSubcommand(argv);
+    return sub === undefined || !NOT_TUI.has(sub);
+};
+/** `codex resume <id>` / `codex fork <id>`: the thread named on the command line. */
+export function argvThreadId(argv) {
+    const a = args(argv);
+    const sub = codexSubcommand(argv);
+    if (sub !== "resume")
+        return undefined; // a fork gets a new id
+    const rest = a.slice(a.indexOf(sub) + 1);
+    return rest.find((w) => CODEX_ID.test(w))?.toLowerCase();
+}
+/**
+ * Pure: which held threads are live, and where. `threadCwd` gives a thread's
+ * start cwd (from its rollout; undefined before the first message is written).
+ * `isUser` says whether a thread may be claimed by a TUI (not a sub-agent etc.).
+ * `threadActivity` gives the epoch ms of a thread's last rollout activity, and
+ * is undefined exactly when it has no rollout (default: when it has no cwd).
+ * Deterministic: the same locks and processes give the same answer in any order.
+ */
+export function assignLive(locks, procs, threadCwd, isUser = () => true, threadActivity = (id) => (threadCwd(id) === undefined ? undefined : 0)) {
+    const byPid = new Map(procs.map((p) => [p.pid, p]));
+    const out = [];
+    const daemonHeld = [];
+    for (const l of locks) {
+        const holder = byPid.get(l.pid);
+        if (!holder)
+            continue;
+        if (isDaemon(holder.argv))
+            daemonHeld.push(l);
+        else
+            out.push({ threadId: l.threadId, pid: l.pid, exact: true });
+    }
+    // TUIs; the npm shim and the native binary below it count once (the outer one).
+    const codexPids = new Set(procs.map((p) => p.pid));
+    const tuis = procs
+        .filter((p) => !isDaemon(p.argv) && isTui(p.argv) && !codexPids.has(p.ppid))
+        .filter((p) => !out.some((t) => t.pid === p.pid))
+        // Newest first: a later TUI is more likely on the newest thread of a directory,
+        // and what it leaves (its reviewer, say) is reserved before older TUIs choose.
+        .sort((a, b) => b.startedAt - a.startedAt || b.pid - a.pid);
+    const free = new Set(daemonHeld.filter((l) => isUser(l.threadId)).map((l) => l.threadId));
+    const loaded = new Map(daemonHeld.map((l) => [l.threadId, l.loadedAt]));
+    const created = (id) => uuidV7Ms(id) ?? loaded.get(id);
+    // Earliest created first; a tie goes to the smaller id, never to scan order.
+    const earlier = (a, b) => created(a) - created(b) || (a < b ? -1 : a > b ? 1 : 0);
+    /** Free threads `t` can have opened: from its directory (or no rollout yet), loaded after it started. */
+    const candidates = (t) => [...free]
+        .filter((id) => {
+        const cwd = threadCwd(id);
+        if (cwd !== undefined && cwd !== t.cwd)
+            return false;
+        const rollout = threadActivity(id) !== undefined;
+        // `codex resume` (its picker) only ever opens a thread with a rollout.
+        if (!rollout && codexSubcommand(t.argv) === "resume")
+            return false;
+        // Loaded after it started (else another TUI's, lingering), and, with no
+        // rollout yet (nobody can resume such a thread), created after it
+        // started. startedAt is never late (btime is whole seconds, rounded
+        // down), so its own thread always passes.
+        if (t.startedAt > 0 && (loaded.get(id) < t.startedAt || (!rollout && created(id) < t.startedAt)))
+            return false;
+        return true;
+    })
+        .sort(earlier);
+    // Threads loaded after a TUI started that it did not take (its reviewer, say):
+    // no other TUI may take them either, unless one is that TUI's own earliest.
+    const reserved = new Set();
+    const claimed = new Set();
+    for (const t of tuis) {
+        const id = argvThreadId(t.argv);
+        // A TUI that names its thread never guesses another one, even if that one is taken.
+        if (id)
+            claimed.add(t.pid);
+        if (id && free.has(id)) {
+            free.delete(id);
+            out.push({ threadId: id, pid: t.pid, exact: true, ...(t.cwd ? { cwd: t.cwd } : {}) });
+        }
+    }
+    for (const t of tuis)
+        if (claimed.has(t.pid) && t.cwd)
+            for (const id of candidates(t))
+                reserved.add(id);
+    for (const t of tuis) {
+        if (claimed.has(t.pid) || !t.cwd)
+            continue;
+        const mine = candidates(t);
+        const allowed = mine.filter((id, i) => i === 0 || !reserved.has(id));
+        for (const id of mine)
+            reserved.add(id);
+        // A thread with a rollout wins (the newest activity, then the newest load,
+        // then the larger id); else the earliest new thread: the conversation, not
+        // the auto-review thread the daemon loads just after it.
+        const withRollout = allowed.filter((id) => threadActivity(id) !== undefined);
+        const best = withRollout.length
+            ? withRollout.reduce((a, b) => {
+                const d = threadActivity(b) - threadActivity(a) || loaded.get(b) - loaded.get(a);
+                return d > 0 || (d === 0 && b > a) ? b : a;
+            })
+            : allowed[0];
+        if (best === undefined)
+            continue;
+        free.delete(best);
+        out.push({ threadId: best, pid: t.pid, cwd: t.cwd, exact: false });
+    }
+    return out;
+}
+/** `/proc/locks` → inode → pids holding (not waiting for) a lock on it. */
+export function parseProcLocks(text) {
+    const out = new Map();
+    for (const line of text.split("\n")) {
+        const f = line.trim().split(/\s+/);
+        if (f.length < 6 || f[1] === "->")
+            continue;
+        const pid = Number(f[4]);
+        const inode = Number(f[5].split(":")[2]);
+        if (!Number.isInteger(pid) || pid <= 0 || !Number.isInteger(inode))
+            continue;
+        out.set(inode, [...(out.get(inode) ?? []), pid]);
+    }
+    return out;
+}
+/**
+ * Reads the held thread locks under `lockDir`, their holders and, only when a
+ * daemon holds one, the Codex TUI processes that may be showing it. No lock
+ * file → nothing else is read. Undefined when /proc/locks is not readable (not
+ * Linux): liveness unknown.
+ */
+export async function scanCodexProcesses(lockDir, procRoot = "/proc") {
+    const locksText = await readFile(join(procRoot, "locks"), "utf8").catch(() => undefined);
+    if (locksText === undefined)
+        return undefined;
+    lockDir = await realpath(lockDir).catch(() => lockDir);
+    const files = (await readdir(lockDir).catch(() => [])).filter((f) => f.endsWith(".lock") && CODEX_ID.test(f.slice(0, -5)));
+    if (!files.length)
+        return { locks: [], procs: [] };
+    const table = createProcessTable({ platform: "linux", procRoot });
+    const btime = await bootTime(procRoot);
+    const procs = new Map();
+    const proc = async (pid, ppid) => {
+        const known = procs.get(pid);
+        if (known !== undefined)
+            return known ?? undefined;
+        const [argv, exe] = await Promise.all([table.argv(pid), table.exe(pid)]);
+        if (!argv || !looksLikeCodex(argv, exe)) {
+            procs.set(pid, null);
+            return undefined;
+        }
+        const [cwd, parent, started] = await Promise.all([
+            readlink(join(procRoot, String(pid), "cwd")).catch(() => undefined),
+            ppid ?? table.parent(pid),
+            startedAt(procRoot, pid, btime),
+        ]);
+        const p = { pid, ppid: parent ?? 0, argv, startedAt: started, ...(cwd ? { cwd } : {}) };
+        procs.set(pid, p);
+        return p;
+    };
+    const fds = async (pid) => {
+        const dir = join(procRoot, String(pid), "fd");
+        const names = await readdir(dir).catch(() => []);
+        return new Set((await Promise.all(names.map((n) => readlink(join(dir, n)).catch(() => "")))).filter(Boolean));
+    };
+    const holders = parseProcLocks(locksText);
+    const fdCache = new Map();
+    const locks = [];
+    for (const f of files) {
+        const path = join(lockDir, f);
+        const st = await stat(path).catch(() => undefined);
+        if (!st)
+            continue;
+        for (const pid of holders.get(st.ino) ?? []) {
+            if (!(await proc(pid)))
+                continue;
+            if (!fdCache.has(pid))
+                fdCache.set(pid, await fds(pid));
+            if (!fdCache.get(pid).has(path))
+                continue;
+            locks.push({ threadId: f.slice(0, -5).toLowerCase(), pid, loadedAt: st.birthtimeMs || st.ctimeMs });
+            break;
+        }
+    }
+    if (locks.some((l) => isDaemon(procs.get(l.pid).argv))) {
+        for (const p of await table.list()) {
+            // Cheap filter before reading argv: the native binary, or a node shim.
+            if (/codex|node|MainThread/i.test(p.comm))
+                await proc(p.pid, p.ppid);
+        }
+    }
+    return { locks, procs: [...procs.values()].filter((p) => p !== null) };
+}