excaliagent 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Popovski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# excaliagent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A spatial scratchboard for your Claude Code sessions, on an Excalidraw canvas.
+
+![The board: session cards triaged into lanes](https://raw.githubusercontent.com/martinkozle/excaliagent/main/docs/images/board.png)
+
+Every session is a card. You drag cards wherever they make sense to you (parked,
+blocked on a colleague, come back to, done) and draw anything around them. The
+app keeps each card's **color and label** in sync with the session and never
+moves, resizes, or edits anything else.
+
+```
+Fix flaky checkout test           ← title (handwritten, larger)
+demo-app · fix/flaky              ← repo · branch
+needs user: input needed · 2m     ← status · what it waits for · last activity
+cache warm 41m                    ← prompt-cache warmth
+herdr: demo-app › oauth           ← herdr workspace › tab
+PR #12                            ← last PR link
+```
+
+| Color | Meaning |
+|---|---|
+| red | needs you (input, permission, trust, blocked) |
+| yellow | busy |
+| green | idle, prompt cache still warm: review it before it goes cold |
+| grey | idle, cache cold |
+| dashed, pale | dormant (not running) |
+
+![Right-click on a card: the excaliagent section next to the Excalidraw menu](https://raw.githubusercontent.com/martinkozle/excaliagent/main/docs/images/card-menu.png)
+
+## Run
+
+```sh
+npx excaliagent
+```
+
+It starts a server on `127.0.0.1` and opens the board in your browser.
+
+- **Live sessions** appear in the *inbox* by themselves. A new board comes with
+  lanes next to it (To Do, In Progress, Review, Blocked, Parked, Done, and two
+  blank ones to name yourself); they are plain shapes you can rename, move or
+  delete. On an older board, add them from the main menu: *Add starter lanes*.
+- **Dormant sessions** are added from the **Sessions** panel (top right).
+- **Double-click a card** to jump to it: a live session focuses its
+  [herdr](https://herdr.dev) pane and raises the terminal window (Hyprland,
+  Sway). A dormant session is resumed with `claude --resume` in a new herdr
+  tab, in the workspace for that repo. Without herdr, the resume command is
+  copied instead.
+- **Right-click a card** for an excaliagent section on top of the Excalidraw
+  menu: focus or resume, copy the resume command (with or without `cd`), open
+  the PR.
+- A **PR link** (GitHub, Bitbucket, GitLab) shows on the card; the card's link
+  icon opens it.
+- The board is saved to `$XDG_STATE_HOME/excaliagent/scene.json`
+  (default `~/.local/state/excaliagent/`).
+
+Options: `--port`, `--no-open`, `--state-dir`, `--claude-dir`, `--no-herdr`, `--no-raise`.
+See `npx excaliagent --help`.
+
+## Privacy and security
+
+- Reads `~/.claude/sessions/*.json` and the transcript files under
+  `~/.claude/projects/` (only metadata lines: title, branch, timestamps, token
+  usage, PR links; never message content). Installs no hooks, writes nothing
+  outside its state directory.
+- Listens on loopback only. A random token is put into the URL it opens and
+  exchanged for an HttpOnly cookie; every request needs it. Requests with a
+  foreign `Host` (DNS rebinding) or cross-origin writes are refused.
+- Its only actions: focus a herdr pane, raise the terminal window, and start
+  `claude --resume <id>` in a new herdr pane. It never types into a running
+  session.
+- The only outside request: Chinese, Japanese or Korean text on the board loads
+  Excalidraw's CJK font from esm.sh (it is not bundled, to keep the package
+  small). Everything else, including all other fonts, is served locally.
+
+## Platforms
+
+Linux and macOS. Raising the terminal window after a jump works on Hyprland,
+Sway and macOS. Windows is not supported yet
+([#1](https://github.com/martinkozle/excaliagent/issues/1), contributions welcome).
+
+## herdr (optional)
+
+If [herdr](https://herdr.dev) is running, cards are linked to panes by matching
+the session's process id to the pane's foreground process. No herdr
+integration or plugin is needed. Tested with herdr 0.9.0 and its protocol 22.
+
+## Development
+
+The repo ships a Nix flake with Node 24 and Chromium for the browser tests:
+
+```sh
+direnv allow        # or: nix develop
+npm install
+npm test            # unit tests (vitest)
+npm run test:e2e    # browser tests (playwright) against a mock Claude home
+npm run demo        # the board with a seeded, synthetic set of sessions
+npm run dev         # server + Vite hot reload against your real ~/.claude
+```
+
+Tests never read your real `~/.claude` or talk to your running herdr:
+`test/mock-claude.ts` seeds a throwaway Claude home with dummy processes, and the
+herdr tests start an isolated `herdr server` with its own temp home and socket.
+A privacy test fails if any fixture contains this machine's home path or user
+name.
+
+Docs: [product](docs/product.md), [design](docs/design.md), [roadmap](docs/roadmap.md). Agents start at [AGENTS.md](AGENTS.md).

package/bin/excaliagent.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/server/cli.js";

package/dist/server/args.js

@@ -0,0 +1,52 @@
+import { parseArgs } from "node:util";
+export const USAGE = `Usage: excaliagent [options]
+
+A spatial Excalidraw board for your Claude Code sessions.
+
+Options:
+  --port <n>          Port on 127.0.0.1 (default: random free port)
+  --no-open           Do not open the browser, just print the URL
+  --state-dir <dir>   Where scene.json lives (default: $XDG_STATE_HOME/excaliagent)
+  --claude-dir <dir>  Claude Code home (default: ~/.claude)
+  --no-herdr          Do not link sessions to herdr panes
+  --no-raise          Focus the herdr pane but do not raise its terminal window
+                      (raising supports Hyprland, Sway and macOS)
+  --dev               Serve the frontend through Vite with hot reload
+  -h, --help          Show this help
+  -v, --version       Show the version
+`;
+export function parseCliArgs(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        strict: true,
+        allowNegative: true,
+        options: {
+            port: { type: "string" },
+            open: { type: "boolean", default: true },
+            dev: { type: "boolean", default: false },
+            herdr: { type: "boolean", default: true },
+            raise: { type: "boolean", default: true },
+            "state-dir": { type: "string" },
+            "claude-dir": { type: "string" },
+            help: { type: "boolean", short: "h", default: false },
+            version: { type: "boolean", short: "v", default: false },
+        },
+    });
+    let port = 0;
+    if (values.port !== undefined) {
+        port = Number(values.port);
+        if (!Number.isInteger(port) || port < 0 || port > 65535)
+            throw new Error(`invalid --port: ${values.port}`);
+    }
+    return {
+        port,
+        open: values.open,
+        dev: values.dev,
+        herdr: values.herdr,
+        raise: values.raise,
+        stateDir: values["state-dir"],
+        claudeDir: values["claude-dir"],
+        help: values.help,
+        version: values.version,
+    };
+}

package/dist/server/cli.js

@@ -0,0 +1,100 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseCliArgs, USAGE } from "./args.js";
+import { createHub } from "./hub.js";
+import { createAppServer } from "./http.js";
+import { createDesktop } from "./desktop/desktop.js";
+import { createHerdrLink, createNoPaneLink } from "./panes/herdr.js";
+import { createSceneStore, defaultStateDir } from "./scene-store.js";
+import { createClaudeSource } from "./sources/claude.js";
+const here = dirname(fileURLToPath(import.meta.url));
+// src/server or dist/server → package root
+const root = join(here, "..", "..");
+function openBrowser(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        const child = spawn(cmd, args, { detached: true, stdio: "ignore" });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // printing the URL is enough
+    }
+}
+async function main(args) {
+    const token = randomBytes(24).toString("base64url");
+    const source = createClaudeSource({ claudeDir: args.claudeDir });
+    const desktop = args.herdr && args.raise ? createDesktop({ env: process.env }) : undefined;
+    const panes = args.herdr ? createHerdrLink({ desktop }) : createNoPaneLink();
+    const hub = createHub({ source, panes });
+    await hub.start();
+    const scenes = createSceneStore(args.stateDir ?? defaultStateDir());
+    let middleware;
+    let closeVite = async () => { };
+    const server = createAppServer({
+        hub,
+        scenes,
+        token,
+        webRoot: join(root, "dist", "web"),
+        get middleware() {
+            return middleware;
+        },
+    });
+    if (args.dev) {
+        const { createServer } = await import("vite");
+        const vite = await createServer({
+            configFile: join(root, "vite.config.ts"),
+            server: { middlewareMode: true, hmr: { server: server.server } },
+            appType: "spa",
+        });
+        middleware = vite.middlewares;
+        closeVite = () => vite.close();
+    }
+    await server.listen(args.port);
+    const url = `http://127.0.0.1:${server.port}/?token=${token}`;
+    console.log(`excaliagent ${args.dev ? "(dev) " : ""}listening on http://127.0.0.1:${server.port}`);
+    console.log(`scene: ${scenes.path}`);
+    console.log(`herdr: ${panes.available() ? "connected" : args.herdr ? "not running (will retry)" : "disabled"}`);
+    if (args.herdr)
+        console.log(`raise window on focus: ${!desktop ? "off (--no-raise)" : desktop.kind === "none" ? "unsupported here" : desktop.kind}`);
+    console.log(`open: ${url}`);
+    if (args.open)
+        openBrowser(url);
+    let stopping = false;
+    const stop = async () => {
+        if (stopping)
+            process.exit(1);
+        stopping = true;
+        hub.stop();
+        panes.close();
+        await closeVite();
+        await server.close();
+        process.exit(0);
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+}
+let args;
+try {
+    args = parseCliArgs(process.argv.slice(2));
+}
+catch (err) {
+    console.error(`excaliagent: ${err.message}\n\n${USAGE}`);
+    process.exit(2);
+}
+if (args.help) {
+    console.log(USAGE);
+}
+else if (args.version) {
+    console.log(JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version);
+}
+else {
+    main(args).catch((err) => {
+        console.error("excaliagent:", err);
+        process.exit(1);
+    });
+}

package/dist/server/desktop/desktop.js

@@ -0,0 +1,150 @@
+/**
+ * Raise the desktop window that hosts a process (e.g. the terminal running a
+ * herdr client), so focusing a pane also brings its terminal to the front.
+ *
+ * Walks each candidate pid's ancestors through a ProcessTable and acts on the
+ * first ancestor that is a window / app:
+ * - Linux + Hyprland: `hyprctl clients -j` → `hyprctl dispatch focuswindow address:<addr>`
+ * - Linux + Sway: `swaymsg -t get_tree` → `swaymsg [pid=N] focus`
+ * - macOS: first ancestor whose executable lives in an `.app` bundle →
+ *   `open -a <bundle>` (activates the app; no Accessibility permission).
+ *   Unverified on real hardware.
+ * - anything else: no-op.
+ * Never throws; raise() resolves false when nothing was raised.
+ */
+import { defaultExec, defaultLog, describeExecFailure, logOnce } from "./exec.js";
+import { createProcessTable } from "./process-table.js";
+export { defaultExec };
+/** pid, then its parents up to (excluding) init/launchd. */
+async function ancestry(table, pid) {
+    const chain = [];
+    const seen = new Set();
+    let cur = pid;
+    while (cur !== undefined && cur > 1 && !seen.has(cur) && chain.length < 64) {
+        seen.add(cur);
+        chain.push(cur);
+        cur = await table.parent(cur);
+    }
+    return chain;
+}
+function windowManager(listWindows, focus) {
+    return {
+        async prepare() {
+            const windows = await listWindows();
+            return async (pid) => windows.get(pid);
+        },
+        focus,
+    };
+}
+function hyprland(exec, timeout) {
+    return windowManager(async () => {
+        const { stdout } = await exec("hyprctl", ["clients", "-j"], { timeout });
+        const out = new Map();
+        for (const c of JSON.parse(stdout)) {
+            if (typeof c.pid === "number" && typeof c.address === "string" && !out.has(c.pid))
+                out.set(c.pid, c.address);
+        }
+        return out;
+    }, async (address) => {
+        await exec("hyprctl", ["dispatch", "focuswindow", `address:${address}`], { timeout });
+    });
+}
+function sway(exec, timeout) {
+    return windowManager(async () => {
+        const { stdout } = await exec("swaymsg", ["-t", "get_tree"], { timeout });
+        const out = new Map();
+        const walk = (n) => {
+            if (typeof n.pid === "number")
+                out.set(n.pid, String(n.pid));
+            for (const c of [...(n.nodes ?? []), ...(n.floating_nodes ?? [])])
+                walk(c);
+        };
+        walk(JSON.parse(stdout));
+        return out;
+    }, async (pid) => {
+        await exec("swaymsg", [`[pid=${pid}]`, "focus"], { timeout });
+    });
+}
+/** Outermost `.app` bundle containing an executable path, e.g. /Applications/kitty.app. */
+export function appBundleOf(exe) {
+    const m = /^(\/.*?\.app)\//.exec(exe);
+    return m?.[1];
+}
+function macos(exec, timeout, table, log) {
+    const once = logOnce(log);
+    return {
+        async prepare() {
+            return async (pid) => {
+                const exe = await table.exe(pid);
+                return exe ? appBundleOf(exe) : undefined;
+            };
+        },
+        async focus(bundle) {
+            const args = ["-a", bundle];
+            try {
+                await exec("open", args, { timeout });
+            }
+            catch (e) {
+                once(`open:${bundle}`, `raise: ${describeExecFailure("open", args, e)}`);
+                throw e;
+            }
+        },
+        async notFound(chains) {
+            const shown = await Promise.all(chains.map(async (chain) => (await Promise.all(chain.map(async (p) => `${p} ${(await table.exe(p)) ?? "?"}`))).join(" <- ")));
+            once("no-app", `raise: no .app bundle among the ancestors of herdr client(s): ${shown.join("; ")}`);
+        },
+        noPids() {
+            once("no-pids", "raise: no herdr client process found (is herdr running in a terminal on this Mac?)");
+        },
+    };
+}
+export function createDesktop(opts = {}) {
+    const { platform = process.platform, env = process.env, exec = defaultExec, timeoutMs = 2000 } = opts;
+    const table = opts.table ?? createProcessTable({ platform, procRoot: opts.procRoot, exec, timeoutMs, log: opts.log });
+    const log = opts.log ?? defaultLog;
+    const kind = platform === "darwin"
+        ? "macos"
+        : platform === "linux" && env.HYPRLAND_INSTANCE_SIGNATURE
+            ? "hyprland"
+            : platform === "linux" && env.SWAYSOCK
+                ? "sway"
+                : "none";
+    const raiser = kind === "macos"
+        ? macos(exec, timeoutMs, table, log)
+        : kind === "hyprland"
+            ? hyprland(exec, timeoutMs)
+            : kind === "sway"
+                ? sway(exec, timeoutMs)
+                : undefined;
+    return {
+        kind,
+        async raise(pids) {
+            if (!raiser)
+                return false;
+            if (pids.length === 0) {
+                raiser.noPids?.();
+                return false;
+            }
+            try {
+                const targetOf = await raiser.prepare();
+                const chains = [];
+                for (const pid of pids) {
+                    const chain = await ancestry(table, pid);
+                    chains.push(chain);
+                    for (const p of chain) {
+                        const target = await targetOf(p);
+                        if (target !== undefined) {
+                            await raiser.focus(target);
+                            return true;
+                        }
+                    }
+                }
+                await raiser.notFound?.(chains);
+            }
+            catch {
+                // no compositor, timeout, bad output: just don't raise
+            }
+            return false;
+        },
+    };
+}

package/dist/server/desktop/exec.js

@@ -0,0 +1,27 @@
+import { execFile } from "node:child_process";
+export const defaultExec = (file, args, opts) => new Promise((resolve, reject) => {
+    execFile(file, args, { timeout: opts.timeout, maxBuffer: 16 << 20, encoding: "utf8" }, (err, stdout, stderr) => {
+        if (err)
+            reject(Object.assign(err, { stderr }));
+        else
+            resolve({ stdout });
+    });
+});
+/** "`cmd args` failed: <stderr, else message>" for logs. */
+export function describeExecFailure(file, args, err) {
+    const e = err;
+    const stderr = typeof e?.stderr === "string" ? e.stderr.trim() : "";
+    const detail = stderr || (typeof e?.message === "string" ? e.message : String(err));
+    return `\`${[file, ...args].join(" ")}\` failed: ${detail}`;
+}
+export const defaultLog = (m) => console.warn(`excaliagent: ${m}`);
+/** Wraps a logger so each key is reported at most once. */
+export function logOnce(log) {
+    const seen = new Set();
+    return (key, message) => {
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        log(message);
+    };
+}

package/dist/server/desktop/process-table.js

@@ -0,0 +1,167 @@
+/**
+ * Minimal process information, portable across Linux and macOS.
+ *
+ * - linux: /proc (stat, comm, cmdline, environ, exe). No subprocesses.
+ * - darwin: `ps -axww -o pid=,ppid=,comm=` (comm is the full executable path
+ *   on macOS), `ps -ww -o command= -p N` for argv and `ps -E -ww -o command= -p N`
+ *   for the environment (own-user processes only; -E = "display the environment"). argv/env are split on
+ *   whitespace, so arguments or values containing spaces are approximate.
+ *   Unverified on real hardware; CI runs the parsers against fixtures.
+ * - anything else: an empty table.
+ * Every method fails soft (empty / undefined).
+ */
+import { readdir, readFile, readlink } from "node:fs/promises";
+import { join } from "node:path";
+import { defaultExec, defaultLog, describeExecFailure, logOnce } from "./exec.js";
+const read = (p) => readFile(p, "utf8").catch(() => undefined);
+function parseStat(stat) {
+    const open = stat.indexOf("(");
+    const close = stat.lastIndexOf(")");
+    if (open < 0 || close < open)
+        return undefined;
+    const ppid = Number(stat.slice(close + 1).trim().split(/\s+/)[1]);
+    return Number.isInteger(ppid) ? { comm: stat.slice(open + 1, close), ppid } : undefined;
+}
+function linuxTable(procRoot) {
+    const stat = async (pid) => {
+        const s = await read(join(procRoot, String(pid), "stat"));
+        return s === undefined ? undefined : parseStat(s);
+    };
+    return {
+        async list() {
+            let entries;
+            try {
+                entries = await readdir(procRoot);
+            }
+            catch {
+                return [];
+            }
+            const out = await Promise.all(entries
+                .filter((e) => /^\d+$/.test(e))
+                .map(async (e) => {
+                const s = await stat(Number(e));
+                return s ? { pid: Number(e), ppid: s.ppid, comm: s.comm } : undefined;
+            }));
+            return out.filter((p) => p !== undefined);
+        },
+        async parent(pid) {
+            const ppid = (await stat(pid))?.ppid;
+            return ppid !== undefined && ppid > 0 ? ppid : undefined;
+        },
+        async argv(pid) {
+            return (await read(join(procRoot, String(pid), "cmdline")))?.split("\0").filter(Boolean);
+        },
+        async env(pid) {
+            const environ = await read(join(procRoot, String(pid), "environ"));
+            if (environ === undefined)
+                return undefined;
+            const env = {};
+            for (const kv of environ.split("\0")) {
+                const i = kv.indexOf("=");
+                if (i > 0)
+                    env[kv.slice(0, i)] = kv.slice(i + 1);
+            }
+            return env;
+        },
+        async exe(pid) {
+            return readlink(join(procRoot, String(pid), "exe")).catch(() => undefined);
+        },
+    };
+}
+/** Lines of `ps -o pid=,ppid=,comm=`; comm runs to end of line (may contain spaces). */
+export function parsePsList(out) {
+    const list = [];
+    for (const line of out.split("\n")) {
+        const m = /^\s*(\d+)\s+(\d+)\s(.*)$/.exec(line);
+        if (m)
+            list.push({ pid: Number(m[1]), ppid: Number(m[2]), comm: m[3].trim() });
+    }
+    return list;
+}
+/**
+ * Environment from `ps -E -ww -o command=`: the command line followed by
+ * KEY=VALUE pairs. The known argv prefix is skipped; a token that is not
+ * KEY=VALUE continues the previous value (values with spaces).
+ */
+export function parsePsEnv(out, argv = []) {
+    let rest = out.trim();
+    const cmd = argv.join(" ");
+    if (cmd && rest.startsWith(cmd))
+        rest = rest.slice(cmd.length);
+    else if (argv.length > 0)
+        return {};
+    const env = {};
+    let last;
+    for (const tok of rest.split(/\s+/).filter(Boolean)) {
+        const m = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/.exec(tok);
+        if (m) {
+            last = m[1];
+            env[last] = m[2];
+        }
+        else if (last !== undefined) {
+            env[last] += " " + tok;
+        }
+    }
+    return env;
+}
+function darwinTable(exec, timeout, cacheMs, log) {
+    const once = logOnce(log);
+    const ps = async (args, key) => {
+        try {
+            return (await exec("ps", args, { timeout })).stdout;
+        }
+        catch (e) {
+            once(key, `process table: ${describeExecFailure("ps", args, e)}`);
+            return undefined;
+        }
+    };
+    let cached;
+    const list = () => {
+        if (!cached || Date.now() - cached.at > cacheMs) {
+            const listing = ps(["-axww", "-o", "pid=,ppid=,comm="], "list").then((out) => (out === undefined ? [] : parsePsList(out)));
+            cached = { at: Date.now(), list: listing };
+        }
+        return cached.list;
+    };
+    // A process that exited meanwhile also makes ps fail: not worth a log line each.
+    const argv = async (pid) => {
+        const out = await ps(["-ww", "-o", "command=", "-p", String(pid)], "argv");
+        const parts = out?.trim().split(/\s+/).filter(Boolean) ?? [];
+        return parts.length > 0 ? parts : undefined;
+    };
+    return {
+        list,
+        async parent(pid) {
+            const ppid = (await list()).find((p) => p.pid === pid)?.ppid;
+            return ppid !== undefined && ppid > 0 ? ppid : undefined;
+        },
+        argv,
+        async env(pid) {
+            const args = await argv(pid);
+            if (!args)
+                return undefined;
+            const out = await ps(["-E", "-ww", "-o", "command=", "-p", String(pid)], "env");
+            return out === undefined ? undefined : parsePsEnv(out, args);
+        },
+        async exe(pid) {
+            const comm = (await list()).find((p) => p.pid === pid)?.comm;
+            return comm?.startsWith("/") ? comm : undefined;
+        },
+    };
+}
+const emptyTable = {
+    list: async () => [],
+    parent: async () => undefined,
+    argv: async () => undefined,
+    env: async () => undefined,
+    exe: async () => undefined,
+};
+export function createProcessTable(opts = {}) {
+    const { platform = process.platform, procRoot = "/proc", exec = defaultExec, timeoutMs = 2000, cacheMs = 1000 } = opts;
+    const log = opts.log ?? defaultLog;
+    if (platform === "linux")
+        return linuxTable(procRoot);
+    if (platform === "darwin")
+        return darwinTable(exec, timeoutMs, cacheMs, log);
+    return emptyTable;
+}