@jaggerxtrm/pi-extensions 0.7.22 → 0.7.24

package/README.md

@@ -48,3 +48,4 @@ Notable bundled extensions include:
 
 - `xtrm-ui` — XTRM Pi chrome, native tool summaries, selectable external tool chrome (`/xtrm-ui chrome background|box`).
 - `sp-terminal-overlay` — `/sp-feed` streaming overlay, `/sp-ps` snapshot overlay, and `/xtrm-terminal` shell overlay for specialist monitoring.
+- `serena-pool` — shared Serena MCP daemon per repo root; sets `SERENA_MCP_PORT` for `pi-serena-tools`, reuses daemons across sessions, and safely cleans up owned orphan process groups.

package/extensions/README.md

@@ -15,3 +15,21 @@ Commands:
 - `/xtrm-terminal <command>` — opens an arbitrary shell command in an overlay.
 
 Keys: `Esc`/`q` close, `r` restart, arrows/page keys scroll.
+
+## serena-pool
+
+Shared Serena daemon pool for Pi sessions.
+
+Behavior:
+
+- Resolves the current git repo root on `session_start`.
+- Maps each repo root to a deterministic local port.
+- Reuses an existing Serena MCP daemon when the port is already listening.
+- Spawns Serena via `uvx` when no daemon is listening and exports `SERENA_MCP_PORT` for `pi-serena-tools`.
+- Persists ownership state under `/tmp/serena-pool` and reaps only owned orphan process groups from dead recorded daemons.
+
+Debugging:
+
+```bash
+DEBUG=serena-pool pi
+```

package/extensions/serena-pool/index.ts

@@ -1,23 +1,56 @@
 /**
- * serena-pool — shared Serena daemon per repo root
+ * serena-pool — shared Serena daemon per repo root with ownership-based cleanup
  *
- * Sets SERENA_MCP_PORT to a deterministic port derived from the git root before
- * pi-serena-tools session_start fires. If no Serena server is already listening
- * on that port, spawns one (detached, persists after session ends).
+ * On session_start:
+ *   1. Resolve repo root from cwd → deterministic port via hash.
+ *   2. If a Serena is already listening on that port → reuse it, set SERENA_MCP_PORT.
+ *   3. Otherwise acquire a per-port file lock and:
+ *        - Read the recorded state (pid, pgid, startTime, instanceId) from /tmp.
+ *        - If the previously-recorded Serena process is dead → kill its process
+ *          group (SIGTERM then SIGKILL) to reap orphaned LSP children.
+ *        - Spawn a fresh Serena (detached → new process group, pgid == pid).
+ *        - Persist new state to /tmp.
+ *        - Wait until the port answers, then release the lock.
  *
- * pi-serena-tools reads SERENA_MCP_PORT lazily in resolveSerenaPort(), finds the
- * server already running, skips its own spawn, and stopServer() is a no-op since
- * it never held serverProcess. No patches to pi-serena-tools needed.
+ * pi-serena-tools reads SERENA_MCP_PORT lazily and reuses the daemon; its
+ * own stopServer() is a no-op because it never held the child handle.
+ *
+ * Orphan cleanup is by process-group ownership only — never by path matching.
+ * We only signal processes whose pgid matches the recorded pgid AND whose
+ * controlling Serena is verifiably dead (pid+startTime check). Process-group
+ * kills are bounded to ours, so editor LSPs / tests / hooks are never touched.
  */
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { spawn } from "node:child_process";
+import { spawn, execFileSync } from "node:child_process";
 import { connect } from "node:net";
-import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, openSync, writeSync, closeSync, readFileSync, unlinkSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
 
 const POOL_PORT_MIN = 40000;
-const POOL_PORT_RANGE = 5000; // 40000–44999
+const POOL_PORT_RANGE = 5000; // ports 40000–44999
 const STARTUP_TIMEOUT_MS = 15_000;
 const POLL_INTERVAL_MS = 300;
+const LOCK_TIMEOUT_MS = 10_000;
+const ORPHAN_TERM_GRACE_MS = 2_000;
+
+export const STATE_DIR = join(tmpdir(), "serena-pool");
+
+const DEBUG_ENABLED = (process.env.DEBUG ?? "").split(/[\s,]+/).includes("serena-pool");
+function debug(msg: string, ...args: unknown[]): void {
+  if (DEBUG_ENABLED) console.error(`[serena-pool] ${msg}`, ...args);
+}
+
+type PoolState = {
+  pid: number;
+  pgid: number;
+  startTime: string | null;
+  instanceId: string;
+  projectRoot: string;
+  port: number;
+  spawnedAt: number;
+};
 
 function hashToPort(s: string): number {
   let h = 5381;
@@ -28,18 +61,175 @@ function hashToPort(s: string): number {
   return POOL_PORT_MIN + (h % POOL_PORT_RANGE);
 }
 
+function ensureStateDir(): void {
+  if (!existsSync(STATE_DIR)) mkdirSync(STATE_DIR, { recursive: true, mode: 0o700 });
+}
+
+function stateFilePath(port: number): string {
+  return join(STATE_DIR, `pool-${port}.json`);
+}
+
+function lockFilePath(port: number): string {
+  return join(STATE_DIR, `pool-${port}.lock`);
+}
+
 function getRepoRoot(cwd: string): string {
+  let root = cwd;
   try {
-    return execSync("git rev-parse --show-toplevel", {
+    const out = execFileSync("git", ["rev-parse", "--show-toplevel"], {
       cwd,
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"],
     }).trim();
+    if (out) root = out;
+  } catch {
+    /* not a git repo — use cwd */
+  }
+  try {
+    return realpathSync(root);
+  } catch {
+    return root;
+  }
+}
+
+function isPidAlive(pid: number): boolean {
+  if (!pid || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err: unknown) {
+    const code = (err as NodeJS.ErrnoException)?.code;
+    if (code === "EPERM") return true; // exists, just not signalable by us
+    return false;
+  }
+}
+
+/** Linux: /proc/<pid>/stat field 22 (starttime). macOS/other: `ps -o lstart=`. */
+function getProcessStartTime(pid: number): string | null {
+  if (!pid || pid <= 0) return null;
+  try {
+    if (process.platform === "linux") {
+      const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+      // pid (comm) state ... — comm may contain spaces/parens; split after last ')'
+      const lastParen = stat.lastIndexOf(")");
+      if (lastParen < 0) return null;
+      const fields = stat.slice(lastParen + 2).split(" ");
+      // After (comm), fields[0]=state, fields[19]=starttime (clock ticks since boot)
+      return fields[19] ?? null;
+    }
+    const out = execFileSync("ps", ["-p", String(pid), "-o", "lstart="], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    return out || null;
   } catch {
-    return cwd;
+    return null;
   }
 }
 
+/** Verify that `pid` is alive AND its start time still matches `recorded`. */
+function isSameProcess(pid: number, recordedStartTime: string | null): boolean {
+  if (!isPidAlive(pid)) return false;
+  if (recordedStartTime == null) return true; // we never captured one — trust pid only
+  const current = getProcessStartTime(pid);
+  return current != null && current === recordedStartTime;
+}
+
+/** Enumerate all processes whose pgid matches the given value (excluding us). */
+function findProcessesByPgid(pgid: number): Array<{ pid: number; comm: string }> {
+  if (!pgid || pgid <= 0) return [];
+  try {
+    const out = execFileSync("ps", ["-e", "-o", "pid=,pgid=,comm="], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      maxBuffer: 4 * 1024 * 1024,
+    });
+    const result: Array<{ pid: number; comm: string }> = [];
+    for (const line of out.split("\n")) {
+      const m = line.trim().match(/^(\d+)\s+(\d+)\s+(.+)$/);
+      if (!m) continue;
+      const pid = Number(m[1]);
+      const procPgid = Number(m[2]);
+      if (procPgid === pgid && pid !== process.pid) {
+        result.push({ pid, comm: m[3].trim() });
+      }
+    }
+    return result;
+  } catch {
+    return [];
+  }
+}
+
+function tryKill(pid: number, signal: NodeJS.Signals): void {
+  try {
+    process.kill(pid, signal);
+  } catch {
+    /* already gone */
+  }
+}
+
+function readState(port: number): PoolState | null {
+  try {
+    const raw = readFileSync(stateFilePath(port), "utf8");
+    const parsed = JSON.parse(raw) as PoolState;
+    if (typeof parsed.pid === "number" && typeof parsed.pgid === "number") return parsed;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function writeState(state: PoolState): void {
+  ensureStateDir();
+  const path = stateFilePath(state.port);
+  const fd = openSync(path, "w", 0o600);
+  try {
+    writeSync(fd, JSON.stringify(state, null, 2));
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function removeState(port: number): void {
+  try {
+    unlinkSync(stateFilePath(port));
+  } catch {
+    /* ignore */
+  }
+}
+
+type Lock = { release: () => void };
+
+async function acquireLock(port: number, timeoutMs: number): Promise<Lock> {
+  ensureStateDir();
+  const path = lockFilePath(port);
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const fd = openSync(path, "wx", 0o600);
+      writeSync(fd, String(process.pid));
+      closeSync(fd);
+      return {
+        release: () => {
+          try { unlinkSync(path); } catch { /* ignore */ }
+        },
+      };
+    } catch (err: unknown) {
+      const code = (err as NodeJS.ErrnoException)?.code;
+      if (code !== "EEXIST") throw err;
+      // Held by someone — check if that someone is still alive
+      let heldByPid = 0;
+      try { heldByPid = parseInt(readFileSync(path, "utf8").trim(), 10) || 0; } catch { /* ignore */ }
+      if (heldByPid > 0 && !isPidAlive(heldByPid)) {
+        try { unlinkSync(path); } catch { /* race ok */ }
+        continue;
+      }
+      await new Promise((r) => setTimeout(r, 100));
+    }
+  }
+  throw new Error(`serena-pool: could not acquire lock ${path} within ${timeoutMs}ms`);
+}
+
 function isPortListening(port: number): Promise<boolean> {
   return new Promise((resolve) => {
     const socket = connect({ host: "127.0.0.1", port }, () => {
@@ -54,8 +244,8 @@ function isPortListening(port: number): Promise<boolean> {
   });
 }
 
-async function waitForPort(port: number): Promise<boolean> {
-  const deadline = Date.now() + STARTUP_TIMEOUT_MS;
+async function waitForPort(port: number, timeoutMs: number): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
     if (await isPortListening(port)) return true;
     await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
@@ -63,10 +253,25 @@ async function waitForPort(port: number): Promise<boolean> {
   return false;
 }
 
-async function ensureSerenaRunning(projectRoot: string, port: number): Promise<void> {
-  if (await isPortListening(port)) return;
+/**
+ * Reap orphaned LSP children left by a dead Serena daemon.
+ * Safety: we only signal processes whose pgid matches the recorded one AND
+ * whose controlling Serena (pid+startTime) is verifiably dead. The kernel
+ * guarantees nothing else can be in that process group unless it was a
+ * descendant of our spawned Serena.
+ */
+async function reapOrphansIfDaemonDead(state: PoolState): Promise<void> {
+  if (isSameProcess(state.pid, state.startTime)) return; // daemon still alive — abort
+  const candidates = findProcessesByPgid(state.pgid);
+  if (candidates.length === 0) return;
+  for (const c of candidates) tryKill(c.pid, "SIGTERM");
+  await new Promise((r) => setTimeout(r, ORPHAN_TERM_GRACE_MS));
+  const stragglers = findProcessesByPgid(state.pgid);
+  for (const s of stragglers) tryKill(s.pid, "SIGKILL");
+}
 
-  const proc = spawn(
+async function spawnSerena(projectRoot: string, port: number, instanceId: string): Promise<number> {
+  const child = spawn(
     "uvx",
     [
       "--from", "git+https://github.com/oraios/serena",
@@ -78,33 +283,121 @@ async function ensureSerenaRunning(projectRoot: string, port: number): Promise<v
     ],
     {
       cwd: projectRoot,
-      env: { ...process.env },
+      env: {
+        ...process.env,
+        SERENA_POOL_INSTANCE_ID: instanceId,
+        SERENA_POOL_ROOT: projectRoot,
+        SERENA_POOL_PORT: String(port),
+      },
       stdio: "ignore",
       detached: true,
     },
   );
-  proc.unref();
+  child.unref();
+  if (!child.pid) throw new Error("serena-pool: spawn returned no pid");
+  return child.pid;
+}
+
+export async function ensureSerenaForRoot(projectRoot: string): Promise<number | null> {
+  const port = hashToPort(projectRoot);
+  debug(`ensureSerenaForRoot root=${projectRoot} port=${port}`);
+
+  // Fast path: someone already serving on this port. Trust it.
+  if (await isPortListening(port)) {
+    debug(`fast path: port ${port} already listening`);
+    return port;
+  }
+
+  debug(`acquiring lock for port ${port}`);
+  const lock = await acquireLock(port, LOCK_TIMEOUT_MS);
+  try {
+    // Re-check under the lock — another concurrent spawner may have won.
+    if (await isPortListening(port)) {
+      debug(`raced: port ${port} now listening under lock`);
+      return port;
+    }
+
+    // Reap orphans from a previously-recorded dead daemon, if any.
+    const prior = readState(port);
+    if (prior) {
+      debug(`prior state found pid=${prior.pid} pgid=${prior.pgid}`);
+      const alive = isSameProcess(prior.pid, prior.startTime);
+      if (alive) {
+        debug(`prior daemon still alive — skipping reap (port may be transient down)`);
+      } else {
+        const candidates = findProcessesByPgid(prior.pgid);
+        debug(`prior daemon dead; reaping ${candidates.length} orphan(s) in pgid=${prior.pgid}`);
+        await reapOrphansIfDaemonDead(prior);
+      }
+      removeState(port);
+    } else {
+      debug(`no prior state`);
+    }
+
+    // Spawn fresh Serena. Detached → new process group, pgid == pid.
+    const instanceId = randomUUID();
+    const pid = await spawnSerena(projectRoot, port, instanceId);
+    const startTime = getProcessStartTime(pid);
+    debug(`spawned Serena pid=${pid} pgid=${pid} startTime=${startTime}`);
+    writeState({
+      pid,
+      pgid: pid, // detached process is a new group leader
+      startTime,
+      instanceId,
+      projectRoot,
+      port,
+      spawnedAt: Date.now(),
+    });
 
-  const ready = await waitForPort(port);
-  if (!ready) {
-    console.warn(`[serena-pool] Serena did not start on port ${port} within ${STARTUP_TIMEOUT_MS}ms`);
+    const ready = await waitForPort(port, STARTUP_TIMEOUT_MS);
+    if (!ready) {
+      console.warn(`[serena-pool] Serena did not become healthy on port ${port} within ${STARTUP_TIMEOUT_MS}ms (pid=${pid})`);
+      return null;
+    }
+    debug(`ready on port ${port}`);
+    return port;
+  } finally {
+    lock.release();
+    debug(`released lock for port ${port}`);
   }
 }
 
+// Internals exported for testing.
+export const __internals = {
+  hashToPort,
+  isPortListening,
+  isPidAlive,
+  isSameProcess,
+  getProcessStartTime,
+  findProcessesByPgid,
+  getRepoRoot,
+  readState,
+  writeState,
+  removeState,
+  stateFilePath,
+  lockFilePath,
+};
+export type { PoolState };
+
 export default function registerSerenaPool(pi: ExtensionAPI) {
   pi.on("session_start", async (_event: unknown, ctx: any) => {
     const cwd: string = ctx?.cwd ?? process.cwd();
-    const projectRoot = getRepoRoot(cwd);
-    const port = hashToPort(projectRoot);
+    let projectRoot: string;
+    try {
+      projectRoot = getRepoRoot(cwd);
+    } catch (err) {
+      console.warn("[serena-pool] failed to resolve repo root:", err);
+      return;
+    }
 
     try {
-      await ensureSerenaRunning(projectRoot, port);
-      process.env.SERENA_MCP_PORT = String(port);
+      const port = await ensureSerenaForRoot(projectRoot);
+      if (port != null) process.env.SERENA_MCP_PORT = String(port);
     } catch (err) {
-      console.warn("[serena-pool] Error ensuring Serena running:", err);
+      console.warn("[serena-pool] failed to ensure Serena running:", err);
     }
   });
 
-  // session_shutdown intentionally absent — server persists as daemon across sessions.
-  // Kill manually with: kill $(lsof -ti:PORT) or pkill -f "serena start-mcp-server"
+  // No session_shutdown handler — Serena persists as a daemon across sessions.
+  // Next session_start that finds the port dead will reap orphans via PGID.
 }

package/extensions/serena-pool/test/e2e.ts

@@ -0,0 +1,229 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * E2E driver for serena-pool. Exercises the state machine without Pi.
+ *
+ * Usage:
+ *   DEBUG=serena-pool npx tsx extensions/serena-pool/test/e2e.ts
+ *   DEBUG=serena-pool bun extensions/serena-pool/test/e2e.ts
+ *
+ * Requires: `uvx` on PATH (the real Serena spawn path is exercised).
+ *
+ * Five scenarios:
+ *   1. cold start         — clean slate → spawn, port listens, state written
+ *   2. warm reuse         — second call → same pid, same state
+ *   3. dead recovery      — kill Serena → next call spawns fresh
+ *   4. synthetic orphans  — fake state pointing at a detached `sleep` group
+ *                           with dead leader → cleanup kills group members
+ *   5. concurrent spawn   — 5 parallel calls → exactly one Serena alive
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, existsSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+
+import {
+  ensureSerenaForRoot,
+  STATE_DIR,
+  __internals as I,
+  type PoolState,
+} from "../index.ts";
+
+let testsPassed = 0;
+let testsFailed = 0;
+
+function assert(cond: unknown, msg: string): void {
+  if (cond) {
+    console.log(`  ✓ ${msg}`);
+    testsPassed++;
+  } else {
+    console.log(`  ✗ ${msg}`);
+    testsFailed++;
+  }
+}
+
+function header(name: string): void {
+  console.log(`\n── ${name} ──`);
+}
+
+function cleanState(): void {
+  if (!existsSync(STATE_DIR)) return;
+  for (const f of readdirSync(STATE_DIR)) {
+    try { rmSync(join(STATE_DIR, f), { force: true }); } catch { /* ignore */ }
+  }
+}
+
+function killSerenaForPort(port: number): void {
+  const state = I.readState(port);
+  if (!state) return;
+  try { process.kill(-state.pgid, "SIGKILL"); } catch { /* ignore */ }
+  try { process.kill(state.pid, "SIGKILL"); } catch { /* ignore */ }
+  I.removeState(port);
+}
+
+function preflight(): boolean {
+  const uvx = spawnSync("which", ["uvx"], { encoding: "utf8" });
+  if (uvx.status !== 0 || !uvx.stdout.trim()) {
+    console.error("✗ uvx not on PATH — install uv first: https://docs.astral.sh/uv/");
+    return false;
+  }
+  console.log(`✓ uvx: ${uvx.stdout.trim()}`);
+  return true;
+}
+
+async function withTestRoot(fn: (root: string, port: number) => Promise<void>): Promise<void> {
+  const root = mkdtempSync(join(tmpdir(), "serena-pool-test-"));
+  const port = I.hashToPort(root);
+  try {
+    cleanState();
+    await fn(root, port);
+  } finally {
+    killSerenaForPort(port);
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+async function test1_coldStart(): Promise<void> {
+  header("1. cold start");
+  await withTestRoot(async (root, expectedPort) => {
+    const port = await ensureSerenaForRoot(root);
+    assert(port === expectedPort, `port returned (${port}) === hashToPort(root) (${expectedPort})`);
+    assert(port != null && (await I.isPortListening(port)), "port is listening");
+    const state = I.readState(port!);
+    assert(state != null, "state file written");
+    assert(state != null && I.isPidAlive(state.pid), "recorded Serena pid is alive");
+    assert(state != null && state.pgid === state.pid, "pgid == pid (detached)");
+  });
+}
+
+async function test2_warmReuse(): Promise<void> {
+  header("2. warm reuse");
+  await withTestRoot(async (root) => {
+    const port1 = await ensureSerenaForRoot(root);
+    const state1 = I.readState(port1!)!;
+
+    const port2 = await ensureSerenaForRoot(root);
+    const state2 = I.readState(port2!)!;
+
+    assert(port1 === port2, "same port across calls");
+    assert(state1.pid === state2.pid, `same pid (no respawn) — pid=${state1.pid}`);
+  });
+}
+
+async function test3_deadDaemonRecovery(): Promise<void> {
+  header("3. dead-daemon recovery");
+  await withTestRoot(async (root) => {
+    const port = await ensureSerenaForRoot(root);
+    const before = I.readState(port!)!;
+    assert(I.isPidAlive(before.pid), `Serena up (pid=${before.pid})`);
+
+    // Kill the whole process group ungracefully
+    try { process.kill(-before.pgid, "SIGKILL"); } catch { /* ignore */ }
+    try { process.kill(before.pid, "SIGKILL"); } catch { /* ignore */ }
+    await sleep(800);
+    assert(!I.isPidAlive(before.pid), "Serena killed");
+    assert(!(await I.isPortListening(port!)), "port no longer listening");
+
+    const port2 = await ensureSerenaForRoot(root);
+    const after = I.readState(port2!)!;
+    assert(after.pid !== before.pid, `fresh spawn — new pid=${after.pid}`);
+    assert(I.isPidAlive(after.pid), "fresh Serena alive");
+    assert(await I.isPortListening(port2!), "port listening again");
+  });
+}
+
+async function test4_syntheticOrphanCleanup(): Promise<void> {
+  header("4. synthetic orphan cleanup");
+  await withTestRoot(async (root, port) => {
+    // Spawn `bash -c "sleep 9999 & sleep 9999 & wait"` detached so bash is a new
+    // group leader (pgid == bash pid). The two sleeps inherit that pgid.
+    const fake = spawn(
+      "bash",
+      ["-c", "sleep 9999 & sleep 9999 & wait"],
+      { detached: true, stdio: "ignore" },
+    );
+    fake.unref();
+    if (!fake.pid) throw new Error("could not spawn fake daemon");
+    const fakePid = fake.pid;
+    const fakePgid = fakePid;
+    await sleep(300);
+
+    const orphansBefore = I.findProcessesByPgid(fakePgid);
+    assert(orphansBefore.length >= 2, `2+ children in fake pgid before — found ${orphansBefore.length}`);
+
+    // Inject fake state matching this group, then kill the parent bash so
+    // children become orphans (reparented to PID 1, pgid retained).
+    const fakeStart = I.getProcessStartTime(fakePid);
+    const state: PoolState = {
+      pid: fakePid, pgid: fakePgid, startTime: fakeStart,
+      instanceId: "synthetic-test", projectRoot: root, port,
+      spawnedAt: Date.now(),
+    };
+    I.writeState(state);
+    process.kill(fakePid, "SIGKILL");
+    await sleep(500);
+    assert(!I.isPidAlive(fakePid), "fake daemon killed");
+    const stillOrphaned = I.findProcessesByPgid(fakePgid);
+    assert(stillOrphaned.length >= 2, `children survived parent death — orphans=${stillOrphaned.length}`);
+
+    // Trigger cleanup via the real code path (spawns a real Serena afterwards).
+    await ensureSerenaForRoot(root);
+    await sleep(500); // allow SIGTERM/SIGKILL fan-out to land
+
+    const orphansAfter = I.findProcessesByPgid(fakePgid);
+    assert(orphansAfter.length === 0, `orphans reaped — remaining=${orphansAfter.length}`);
+  });
+}
+
+async function test5_concurrentSpawn(): Promise<void> {
+  header("5. concurrent spawn");
+  await withTestRoot(async (root) => {
+    const results = await Promise.all(
+      Array.from({ length: 5 }, () => ensureSerenaForRoot(root)),
+    );
+    const unique = new Set(results);
+    assert(unique.size === 1, `all 5 calls returned the same port — got ${unique.size} unique`);
+
+    // Count actual Serena processes for this port.
+    const port = results[0]!;
+    const state = I.readState(port)!;
+    assert(I.isPidAlive(state.pid), "one Serena alive");
+
+    // Count actual TCP listeners on the port — uvx spawns a python child, so a
+    // command-line pattern match would over-count. Only one process binds LISTEN.
+    const ssOut = spawnSync("ss", ["-tlnpH"], { encoding: "utf8" }).stdout;
+    const listeners = ssOut.split("\n").filter((l) => l.includes(`:${port} `)).length;
+    assert(listeners === 1, `exactly one TCP listener on port ${port} — found ${listeners}`);
+  });
+}
+
+async function main(): Promise<void> {
+  console.log("serena-pool e2e driver\n");
+  if (!preflight()) process.exit(2);
+
+  const tests = [
+    test1_coldStart,
+    test2_warmReuse,
+    test3_deadDaemonRecovery,
+    test4_syntheticOrphanCleanup,
+    test5_concurrentSpawn,
+  ];
+
+  for (const t of tests) {
+    try {
+      await t();
+    } catch (err) {
+      console.error(`  ✗ test threw: ${err instanceof Error ? err.message : err}`);
+      testsFailed++;
+    }
+  }
+
+  console.log(`\n────────────────────────────────`);
+  console.log(`passed: ${testsPassed}   failed: ${testsFailed}`);
+  process.exit(testsFailed > 0 ? 1 : 0);
+}
+
+main().catch((err) => {
+  console.error("fatal:", err);
+  process.exit(2);
+});

package/extensions/xtrm-ui/format.ts

@@ -258,6 +258,8 @@ export function formatLineLabel(count: number, noun: string): string {
   return `${count} ${noun}${count === 1 ? "" : "s"}`;
 }
 
+export const TOOL_ROW_MARKER = "›";
+
 const TOOL_SUMMARY_SUBJECT_MAX = 34;
 const TOOL_SUMMARY_META_MAX = 34;
 
@@ -275,7 +277,7 @@ export function renderToolSummary(
     : "muted";
   const compactSubject = subject ? shortenCommand(subject, TOOL_SUMMARY_SUBJECT_MAX) : undefined;
   const compactMeta = meta ? shortenCommand(meta, TOOL_SUMMARY_META_MAX) : undefined;
-  let text = `${theme.fg(color, "•")} ${theme.fg("toolTitle", theme.bold(label))}`;
+  let text = `${theme.fg(color, TOOL_ROW_MARKER)} ${theme.fg("toolTitle", theme.bold(label))}`;
   if (compactSubject) text += ` ${theme.fg("accent", compactSubject)}`;
   if (compactMeta) text += theme.fg("muted", ` · ${compactMeta}`);
   return text;

package/extensions/xtrm-ui/index.ts

@@ -47,6 +47,7 @@ import {
   previewLines,
   renderRichDiffPreview,
   renderToolSummary,
+  TOOL_ROW_MARKER,
   shortenCommand,
   shortenPath,
 } from "./format";
@@ -252,7 +253,7 @@ type PatchableToolExecutionComponent = {
 type ExternalToolFrameKind = "serena" | "gitnexus" | "structured" | "process" | "external";
 
 const PATCHED_EXTERNAL_TOOL_FRAME = "__xtrmUiExternalToolFrame";
-const EXTERNAL_TOOL_FRAME_PATCH_VERSION = 11;
+const EXTERNAL_TOOL_FRAME_PATCH_VERSION = 12;
 const ANSI_PATTERN = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
 
 function stripAnsi(text: string): string {
@@ -291,21 +292,21 @@ function getToolArgs(component: PatchableToolExecutionComponent): Record<string,
 function summarizeExternalToolPending(toolName: string | undefined, input: Record<string, unknown>): string {
   const name = toolName ?? "tool";
   if (name === "structured_return") {
-    return `• structured_return ${shortenCommand(String(input.command ?? "running"), 38)}`;
+    return `${TOOL_ROW_MARKER} structured_return ${shortenCommand(String(input.command ?? "running"), 38)}`;
   }
   if (name === "process") {
-    return `• process ${String(input.action ?? "running")}`;
+    return `${TOOL_ROW_MARKER} process ${String(input.action ?? "running")}`;
   }
   if (name.startsWith("gitnexus_")) {
     const subject = summarizeSerenaSubject(name, input) ?? summarizeToolSubject(name, input);
-    return `• ${normalizeToolLabel(name)}${subject ? ` ${subject}` : ""}`;
+    return `${TOOL_ROW_MARKER} ${normalizeToolLabel(name)}${subject ? ` ${subject}` : ""}`;
   }
   if (SERENA_COMPACT_TOOLS.has(name)) {
     const subject = summarizeSerenaSubject(name, input);
-    return `• serena ${name}${subject ? ` ${subject}` : ""}`;
+    return `${TOOL_ROW_MARKER} serena ${name}${subject ? ` ${subject}` : ""}`;
   }
   const subject = summarizeToolSubject(name, input) ?? summarizeSerenaSubject(name, input);
-  return `• ${normalizeToolLabel(name)}${subject ? ` ${subject}` : ""}`;
+  return `${TOOL_ROW_MARKER} ${normalizeToolLabel(name)}${subject ? ` ${subject}` : ""}`;
 }
 
 function extractResultTextLines(component: PatchableToolExecutionComponent): string[] | undefined {
@@ -339,7 +340,7 @@ function externalToolBadgeColor(kind: ExternalToolFrameKind, text: string): stri
 }
 
 function highlightExternalToolBadge(kind: ExternalToolFrameKind, line: string): string {
-  const match = line.match(/^(•\s+)(\S+)/u);
+  const match = line.match(/^([•›]\s+)(\S+)/u);
   if (!match?.[1] || !match[2]) return line;
   return match[1] + externalToolBadgeColor(kind, match[2]) + line.slice(match[1].length + match[2].length);
 }
@@ -1140,28 +1141,28 @@ function summarizeSerenaToolResult(
     case "jet_brains_find_symbol":
     case "jet_brains_find_referencing_symbols": {
       const count = countJsonItems(payload) ?? (text.match(/"name_path"\s*:/g)?.length ?? 0);
-      return `• serena ${toolName} ${subject ?? "symbol"}${meta(formatLineLabel(count, "result"), duration)}`;
+      return `${TOOL_ROW_MARKER} serena ${toolName} ${subject ?? "symbol"}${meta(formatLineLabel(count, "result"), duration)}`;
     }
     case "get_symbols_overview":
     case "jet_brains_get_symbols_overview":
     case "jet_brains_type_hierarchy": {
       const count = Math.max(countOverviewSymbols(payload), text.match(/"name_path"\s*:/g)?.length ?? 0);
-      return `• serena ${toolName} ${subject ?? "file"}${meta(formatLineLabel(count, "symbol"), duration)}`;
+      return `${TOOL_ROW_MARKER} serena ${toolName} ${subject ?? "file"}${meta(formatLineLabel(count, "symbol"), duration)}`;
     }
     case "search_for_pattern": {
       const count = countSearchMatches(payload) ?? (text.match(/^\s*>\s*\d+:/gm)?.length ?? 0);
-      return `• serena search ${subject ?? "pattern"}${meta(formatLineLabel(count, "match"), duration)}`;
+      return `${TOOL_ROW_MARKER} serena search ${subject ?? "pattern"}${meta(formatLineLabel(count, "match"), duration)}`;
     }
     case "read_file": {
-      return `• serena read ${subject ?? "file"}${meta(formatLineLabel(countLines(text), "line"), duration)}`;
+      return `${TOOL_ROW_MARKER} serena read ${subject ?? "file"}${meta(formatLineLabel(countLines(text), "line"), duration)}`;
     }
     case "list_dir": {
       const count = countJsonItems(payload) ?? countLines(text);
-      return `• serena list_dir ${subject ?? "."}${meta(formatLineLabel(count, "entry"), duration)}`;
+      return `${TOOL_ROW_MARKER} serena list_dir ${subject ?? "."}${meta(formatLineLabel(count, "entry"), duration)}`;
     }
     case "find_file": {
       const count = countJsonItems(payload) ?? countLines(text);
-      return `• serena find_file ${String(input.file_mask ?? "")}${meta(formatLineLabel(count, "match"), duration)}`;
+      return `${TOOL_ROW_MARKER} serena find_file ${String(input.file_mask ?? "")}${meta(formatLineLabel(count, "match"), duration)}`;
     }
     case "replace_symbol_body":
     case "insert_after_symbol":
@@ -1182,14 +1183,14 @@ function summarizeSerenaToolResult(
     case "restart_language_server":
     case "onboarding":
     case "serena_mcp_reset":
-      return `• serena ${toolName}${subject ? ` ${subject}` : ""}${meta(duration)}`;
+      return `${TOOL_ROW_MARKER} serena ${toolName}${subject ? ` ${subject}` : ""}${meta(duration)}`;
     case "execute_shell_command": {
       const count = countLines(text);
-      return `• serena shell ${subject ?? "command"}${meta(formatLineLabel(count, "line"), duration)}`;
+      return `${TOOL_ROW_MARKER} serena shell ${subject ?? "command"}${meta(formatLineLabel(count, "line"), duration)}`;
     }
     default: {
       const count = countJsonItems(payload) ?? countLines(text);
-      return `• serena ${toolName}${subject ? ` ${subject}` : ""}${meta(formatLineLabel(count, "item"), duration)}`;
+      return `${TOOL_ROW_MARKER} serena ${toolName}${subject ? ` ${subject}` : ""}${meta(formatLineLabel(count, "item"), duration)}`;
     }
   }
 }
@@ -1257,7 +1258,7 @@ function summarizeGenericToolResult(
   const label = formatLineLabel(count, "line");
   const joined = joinMeta([label, duration]);
   const normalized = normalizeToolLabel(toolName);
-  return `• ${normalized}${subject ? ` ${subject}` : ""}${joined ? ` · ${joined}` : ""}`;
+  return `${TOOL_ROW_MARKER} ${normalized}${subject ? ` ${subject}` : ""}${joined ? ` · ${joined}` : ""}`;
 }
 
 function summarizeStructuredReturnToolResult(
@@ -1275,7 +1276,7 @@ function summarizeStructuredReturnToolResult(
   const exitCode = typeof record?.exitCode === "number" ? `exit ${record.exitCode}` : undefined;
   const duration = formatDuration(durationMs);
   const meta = joinMeta([summary ? shortenCommand(summary, 72) : undefined, parser, exitCode, duration]);
-  return `• structured_return ${command}${meta ? ` · ${meta}` : ""}`;
+  return `${TOOL_ROW_MARKER} structured_return ${command}${meta ? ` · ${meta}` : ""}`;
 }
 
 function summarizeProcessToolResult(
@@ -1297,7 +1298,7 @@ function summarizeProcessToolResult(
     const name = String(proc?.name ?? input.name ?? "process");
     const id = proc?.id ? String(proc.id) : undefined;
     const pid = proc?.pid != null ? `pid ${String(proc.pid)}` : undefined;
-    return `• process start "${name}"${meta(id, pid)}`;
+    return `${TOOL_ROW_MARKER} process start "${name}"${meta(id, pid)}`;
   }
 
   if (action === "list") {
@@ -1306,25 +1307,25 @@ function summarizeProcessToolResult(
       const proc = asRecord(item);
       return proc?.status === "running" || proc?.status === "terminating";
     }).length;
-    return `• process list${meta(`${processes.length} ${processes.length === 1 ? "process" : "processes"}`, `${running} running`)}`;
+    return `${TOOL_ROW_MARKER} process list${meta(`${processes.length} ${processes.length === 1 ? "process" : "processes"}`, `${running} running`)}`;
   }
 
   if (action === "output") {
     const output = asRecord(record?.output);
     const stdout = Array.isArray(output?.stdout) ? output.stdout.length : undefined;
     const stderr = Array.isArray(output?.stderr) ? output.stderr.length : undefined;
-    return `• process output ${String(input.id ?? "process")}${meta(
+    return `${TOOL_ROW_MARKER} process output ${String(input.id ?? "process")}${meta(
       stdout != null ? `${stdout} stdout` : undefined,
       stderr != null ? `${stderr} stderr` : undefined,
     )}`;
   }
 
   if (action === "logs") {
-    return `• process logs ${String(input.id ?? "process")}${meta("log paths")}`;
+    return `${TOOL_ROW_MARKER} process logs ${String(input.id ?? "process")}${meta("log paths")}`;
   }
 
   const message = typeof record?.message === "string" ? record.message : text.split("\n")[0];
-  return `• process ${action}${message ? ` · ${shortenCommand(message, 38)}` : ""}${duration ? ` · ${duration}` : ""}`;
+  return `${TOOL_ROW_MARKER} process ${action}${message ? ` · ${shortenCommand(message, 38)}` : ""}${duration ? ` · ${duration}` : ""}`;
 }
 
 function summarizeExternalToolResult(
@@ -1452,13 +1453,13 @@ function registerXtrmUiTools(pi: ExtensionAPI, getPrefs: () => XtrmUiPrefs): voi
       const meta = getXtrmMeta<BashToolDetails, Record<string, unknown>>(details);
       const command = shortenCommand(String(meta?.args.command ?? ""), 38);
       if (isPartial) {
-        return toolRowText(theme, `${theme.fg("accent", "•")} ${theme.fg("toolTitle", "Running ")}${theme.fg("accent", command)}${theme.fg("toolTitle", " in bash")}`);
+        return toolRowText(theme, `${theme.fg("accent", TOOL_ROW_MARKER)} ${theme.fg("toolTitle", "Running ")}${theme.fg("accent", command)}${theme.fg("toolTitle", " in bash")}`);
       }
       const output = getTextContent(result as any);
       const outputLines = cleanOutputLines(output);
       const exitMatch = output.match(/exit code:\s*(-?\d+)/i);
       const exitCode = exitMatch ? Number.parseInt(exitMatch[1] ?? "0", 10) : 0;
-      const bullet = exitCode === 0 ? theme.fg("success", "•") : theme.fg("error", "•");
+      const bullet = exitCode === 0 ? theme.fg("success", TOOL_ROW_MARKER) : theme.fg("error", TOOL_ROW_MARKER);
       const summary = joinMeta([formatLineLabel(outputLines.length, "line"), formatDuration(meta?.durationMs), details.truncation?.truncated ? "truncated" : undefined]);
       let text = `${bullet} ${theme.fg("toolTitle", "Ran ")}${theme.fg("accent", command)}`;
       if (summary) text += theme.fg("dim", ` · ${summary}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaggerxtrm/pi-extensions",
-  "version": "0.7.22",
+  "version": "0.7.24",
   "description": "Unified Pi extension entrypoint for xtrm-managed extensions",
   "type": "module",
   "publishConfig": {