excaliagent 0.1.0 → 0.3.0

package/README.md

@@ -2,13 +2,15 @@
 
 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)
+Fix flaky checkout test       ✳   ← title (handwritten, larger), harness logo
 demo-app · fix/flaky              ← repo · branch
 needs user: input needed · 2m     ← status · what it waits for · last activity
 cache warm 41m                    ← prompt-cache warmth
@@ -19,24 +21,34 @@ PR #12                            ← last PR link
 | Color | Meaning |
 |---|---|
 | red | needs you (input, permission, trust, blocked) |
-| blue | busy |
+| 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* rectangle by themselves.
+It starts a server on `127.0.0.1:7357` (a random free port if that one is
+busy; choose with `--port`), prints the URL with its access token, and opens it
+in your browser. After that first visit, `http://127.0.0.1:7357/` works as a
+bookmark. Running it again while a board is up just opens that board.
+
+- **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 move, resize,
+  rename (double-click) or delete. **+ Lane** (top right) adds one more at the
+  right end. On an older
+  board, add the whole set 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
+  Sway, macOS). 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
@@ -45,7 +57,11 @@ It starts a server on `127.0.0.1` and opens the board in your browser.
 - 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/`).
+  (default `~/.local/state/excaliagent/`), pasted images under `files/` next
+  to it.
+- **Start over**: main menu → *Reset the canvas* (undoable) lays out a fresh
+  board with the live sessions. Or try a clean board without touching yours:
+  `npx excaliagent --state-dir /tmp/excaliagent-fresh`.
 
 Options: `--port`, `--no-open`, `--state-dir`, `--claude-dir`, `--no-herdr`, `--no-raise`.
 See `npx excaliagent --help`.
@@ -56,12 +72,25 @@ See `npx excaliagent --help`.
   `~/.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
+- Listens on loopback only. A random token (created once, kept in the state
+  directory, readable only by you) is put into the URL it opens and exchanged
+  for an HttpOnly cookie; every request needs it, so other users on the same
+  machine stay out. 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.
+- Images you paste onto the board are stored next to the scene, in the
+  state directory.
+- 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)
 
@@ -89,3 +118,5 @@ 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).
+
+MIT licensed. The harness logos on cards (from [simple-icons](https://simpleicons.org), CC0) are trademarks of their owners and only identify which agent a card belongs to.

package/dist/server/args.js

@@ -1,15 +1,19 @@
 import { parseArgs } from "node:util";
+/** Used when --port is not given; a busy default falls back to a random port. */
+export const DEFAULT_PORT = 7357;
 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)
+  --port <n>          Port on 127.0.0.1 (default: 7357, or a random free port
+                      if that is busy; 0 = always random)
   --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
@@ -31,7 +35,7 @@ export function parseCliArgs(argv) {
             version: { type: "boolean", short: "v", default: false },
         },
     });
-    let port = 0;
+    let port;
     if (values.port !== undefined) {
         port = Number(values.port);
         if (!Number.isInteger(port) || port < 0 || port > 65535)

package/dist/server/cli.js

@@ -1,15 +1,16 @@
 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 { DEFAULT_PORT, 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";
+import { loadOrCreateToken } from "./token.js";
+import { clearRunning, findRunning, recordRunning } from "./instance.js";
 const here = dirname(fileURLToPath(import.meta.url));
 // src/server or dist/server → package root
 const root = join(here, "..", "..");
@@ -26,14 +27,24 @@ function openBrowser(url) {
     }
 }
 async function main(args) {
-    const token = randomBytes(24).toString("base64url");
+    const stateDir = args.stateDir ?? defaultStateDir();
+    const token = await loadOrCreateToken(stateDir);
+    // One board per state dir: a second server would overwrite the first one's saves.
+    const running = await findRunning(stateDir, token);
+    if (running !== undefined) {
+        const url = `http://127.0.0.1:${running}/?token=${token}`;
+        console.log(`excaliagent is already running for ${stateDir}`);
+        console.log(`open: ${url}`);
+        if (args.open)
+            openBrowser(url);
+        return;
+    }
     const source = createClaudeSource({ claudeDir: args.claudeDir });
-    const panes = args.herdr
-        ? createHerdrLink({ desktop: args.raise ? createDesktop({ env: process.env }) : undefined })
-        : createNoPaneLink();
+    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());
+    const scenes = createSceneStore(stateDir);
     let middleware;
     let closeVite = async () => { };
     const server = createAppServer({
@@ -55,12 +66,27 @@ async function main(args) {
         middleware = vite.middlewares;
         closeVite = () => vite.close();
     }
-    await server.listen(args.port);
+    if (args.port !== undefined)
+        await server.listen(args.port);
+    else {
+        try {
+            await server.listen(DEFAULT_PORT);
+        }
+        catch (err) {
+            if (err.code !== "EADDRINUSE")
+                throw err;
+            console.log(`port ${DEFAULT_PORT} is busy (another excaliagent?); using a random port`);
+            await server.listen(0);
+        }
+    }
     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}`);
+    await recordRunning(stateDir, server.port);
     if (args.open)
         openBrowser(url);
     let stopping = false;
@@ -72,6 +98,7 @@ async function main(args) {
         panes.close();
         await closeVite();
         await server.close();
+        await clearRunning(stateDir).catch(() => { });
         process.exit(0);
     };
     process.on("SIGINT", stop);

package/dist/server/desktop/desktop.js

@@ -2,102 +2,144 @@
  * 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 via /proc/<pid>/stat and focuses the
- * first ancestor that owns a window. Supported: Hyprland (hyprctl) and Sway
- * (swaymsg). Anything else is a no-op. Never throws.
+ * 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 { execFile } from "node:child_process";
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
-export const defaultExec = (file, args, opts) => new Promise((resolve, reject) => {
-    execFile(file, args, { timeout: opts.timeout, maxBuffer: 16 << 20, encoding: "utf8" }, (err, stdout) => {
-        if (err)
-            reject(err);
-        else
-            resolve({ stdout });
-    });
-});
-/** ppid from /proc/<pid>/stat; comm (field 2) may contain spaces and parens. */
-export async function parentPid(procRoot, pid) {
-    try {
-        const stat = await readFile(join(procRoot, String(pid), "stat"), "utf8");
-        const rest = stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/);
-        const ppid = Number(rest[1]);
-        return Number.isInteger(ppid) && ppid > 0 ? ppid : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-/** pid, then its parents up to (excluding) init. */
-async function ancestry(procRoot, pid) {
+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 parentPid(procRoot, cur);
+        cur = await table.parent(cur);
     }
     return chain;
 }
-function hyprland(exec, timeout) {
+function windowManager(listWindows, focus) {
     return {
-        async windows() {
-            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 focus(address) {
-            await exec("hyprctl", ["dispatch", "focuswindow", `address:${address}`], { timeout });
+        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 windows() {
-            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);
+        async prepare() {
+            return async (pid) => {
+                const exe = await table.exe(pid);
+                return exe ? appBundleOf(exe) : undefined;
             };
-            walk(JSON.parse(stdout));
-            return out;
         },
-        async focus(pid) {
-            await exec("swaymsg", [`[pid=${pid}]`, "focus"], { timeout });
+        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 { env = process.env, exec = defaultExec, procRoot = "/proc", timeoutMs = 2000 } = opts;
-    const wm = env.HYPRLAND_INSTANCE_SIGNATURE
-        ? hyprland(exec, timeoutMs)
-        : env.SWAYSOCK
-            ? sway(exec, timeoutMs)
-            : undefined;
+    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 (!wm || pids.length === 0)
+            if (!raiser)
                 return false;
+            if (pids.length === 0) {
+                raiser.noPids?.();
+                return false;
+            }
             try {
-                const windows = await wm.windows();
+                const targetOf = await raiser.prepare();
+                const chains = [];
                 for (const pid of pids) {
-                    for (const p of await ancestry(procRoot, pid)) {
-                        const target = windows.get(p);
+                    const chain = await ancestry(table, pid);
+                    chains.push(chain);
+                    for (const p of chain) {
+                        const target = await targetOf(p);
                         if (target !== undefined) {
-                            await wm.focus(target);
+                            await raiser.focus(target);
                             return true;
                         }
                     }
                 }
+                await raiser.notFound?.(chains);
             }
             catch {
                 // no compositor, timeout, bad output: just don't raise

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;
+}