@rol1n/multi-harness 0.1.0 → 0.1.1

package/README.md

@@ -14,10 +14,10 @@ Also included in `@rol1n/pi-kit`. Enable one copy of the extension.
 
 ## Use
 
-Load `extensions/multi-harness` through the aggregate package, or run from this repository:
+Load `multi-harness` through the aggregate package, or run from this repository:
 
 ```sh
-pi --no-extensions -e ./extensions/multi-harness/index.ts
+pi --no-extensions -e ./multi-harness/index.ts
 ```
 
 Example tool calls:
@@ -60,4 +60,4 @@ Session entries record only worker artifact locations. On session restore/reload
 - Windows requires PowerShell 7 (`pwsh`) for external CLI invocation. Encoded PowerShell commands preserve Unicode, multiline tasks, JSON, and quoted paths. CLI hooks and `harness-done.cmd`/`.ps1` wrappers use the same native Windows Node installation. A mux must be available for visible TUIs; otherwise process fallback applies.
 - Existing worktrees, reports, and sessions created by the removed `worktree-studio` extension are left untouched. Its old `the_road_not_taken` tool and two-route manifests are not imported into this runtime. Synchronize platform resources/reload before using the new tool; old running workers should be finished before upgrading.
 
-Validation scripts are kept outside the repository. Check extension loading from this repository with `pi --no-extensions -e ./extensions/multi-harness/index.ts --list-models '<filter>'`.
+Validation scripts are kept outside the repository. Check extension loading from this repository with `pi --no-extensions -e ./multi-harness/index.ts --list-models '<filter>'`.

package/{extensions/multi-harness/index.ts → index.ts}

@@ -6,7 +6,7 @@ import { delimiter, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { createSurface, closeSurface, getMuxBackend, renderSubagentCommand, sendLongCommand, sendCommand, readScreenAsync, shellEscape, psEscape, zellijPaneId, type WorkerBackend } from "../subagent/mux.ts";
+import { createSurface, closeSurface, getMuxBackend, renderSubagentCommand, sendLongCommand, sendCommand, readScreenAsync, shellEscape, psEscape, zellijPaneId, type WorkerBackend } from "@rol1n/subagent/mux";
 import { HARNESSES, commandSpec } from "./adapters.mjs";
 import { readJson, writeJson } from "./ipc.mjs";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rol1n/multi-harness",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "multi-harness extension from pi-kit",
   "keywords": [
@@ -8,8 +8,8 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com/RolinShmily/pi-kit.git",
-    "directory": "extensions/multi-harness"
+    "url": "git+https://github.com/RolinShmily/pi-kit.git",
+    "directory": "multi-harness"
   },
   "homepage": "https://github.com/RolinShmily/pi-kit#readme",
   "bugs": {
@@ -21,11 +21,9 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "extensions/multi-harness",
-    "extensions/subagent/mux.ts",
-    "extensions/multi-harness/README.md"
-  ],
+  "dependencies": {
+    "@rol1n/subagent": "^0.1.1"
+  },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-agent-core": "*",
@@ -35,7 +33,7 @@
   },
   "pi": {
     "extensions": [
-      "./extensions/multi-harness/index.ts"
+      "./index.ts"
     ],
     "skills": [],
     "prompts": [],

package/extensions/multi-harness/README.md

@@ -1,63 +0,0 @@
-# Multi Harness
-
-A small delegation runtime with one tool, `multi_harness`. `pi`, `codex`, `claude`, and `opencode` are equal CLI peers. The original `subagent` extension remains a separate, lean Pi-only tool.
-
-The runtime accepts **one named worker and an existing cwd**. Those decisions belong to the caller. An independently installed `worktree-studio` skill can coordinate isolated implementations and their acceptance review.
-
-## Install
-
-```sh
-pi install npm:@rol1n/multi-harness
-```
-
-Also included in `@rol1n/pi-kit`. Enable one copy of the extension.
-
-## Use
-
-Load `extensions/multi-harness` through the aggregate package, or run from this repository:
-
-```sh
-pi --no-extensions -e ./extensions/multi-harness/index.ts
-```
-
-Example tool calls:
-
-```json
-{"action":"spawn","name":"reviewer","harness":"claude","cwd":"/existing/project","task":"Review error handling without changing files. Report concrete findings with file paths."}
-{"action":"spawn","name":"implementer","harness":"pi","cwd":"/existing/other-directory","task":"Implement the approved fix and run the specified checks.","model":"provider/model"}
-{"action":"spawn","name":"opencode-reviewer","harness":"opencode","cwd":"/existing/project","task":"Review the changes and report evidence without editing files."}
-{"action":"send","target":"reviewer","task":"Review the revised implementation in the same session."}
-{"action":"status"}
-{"action":"stop","target":"implementer"}
-{"action":"close","target":"reviewer"}
-```
-
-- `spawn` is the default action; `name`, `harness`, and `task` are required. `cwd` defaults to the parent directory and must already exist. Names are reserved for the session, including after closing.
-- `model` is optional and passed to the selected CLI. Pi defaults to the parent model; external CLIs use their installed defaults. Only the selected executable is checked on demand.
-- `spawn` and `send` return after dispatch. **Turn completion is pushed to the real parent Pi session via `pi.sendMessage`**, not by a background wrapper writing a log. Do not poll terminals or run waiting shell loops.
-- With tmux/Zellij, each worker runs its **native interactive TUI**. Turn settlement leaves the application open and idle. `send` continues that same application; `close` exits idle TUIs. `stop` terminates active work and its runtime, preserving files.
-- Without a supported mux, workers use silent child processes. `send` starts another invocation that resumes the same persisted CLI session. Set `PI_MULTI_HARNESS_BACKEND=process` to force this fallback. This is not a live TUI in headless mode.
-- Pi follow-ups use a file inbox and native `pi.sendUserMessage`. OpenCode uses a local server plugin, its native SDK inbox, and the same visible TUI session (no key injection). Codex uses its reported thread ID with `codex queue`; when no ID is available, mux input uses bracketed paste. Claude uses idle-only bracketed paste. Avoid simultaneous human typing and coordinator dispatch; startup trust/permission dialogs may require manual attention. Zellij input transport still requires validation with your installed Zellij/terminal build.
-
-## Notifications and state
-
-Artifacts live in `~/.pi/agent/multi-harness/<worker-id>/`: task prompts, CLI session data/IDs, console/event logs in process mode, completion records, and short TUI screen captures. Working files remain in the caller's `cwd`. No automatic Git report is generated.
-
-`harness-done "summary"` is injected into the worker PATH; `studio-done` is a compatibility alias. It records a proposed summary, **not an early completion event**. Native Codex/Claude hooks, OpenCode's root-session idle events, Pi's `agent_settled`, or the headless process exit publish the authoritative completion. This avoids racing a still-running CLI or notifying twice. Every dispatch has a task ID; stale and duplicate completions are ignored.
-
-The parent subscribes to directory `fs.watch` events, with no periodic terminal capture or completion polling. Screen capture happens once per completed turn. Watcher failures are surfaced rather than silently claiming delivery. A worker's final text is a claim: independently review its files and test results.
-
-Default turn timeout: 15 minutes (`maxMinutes`: 1–120). Headless workers are stopped on timeout. A native TUI stays open and cannot receive a new dispatch until it settles or is stopped. Timeouts do not cap tokens or spending; missing usage/pricing is not zero cost.
-
-Session entries record only worker artifact locations. On session restore/reload, the extension reattaches notification watchers for saved workers. A `controller.lock` prevents another session from controlling the same worker concurrently. After an unclean crash, verify the recorded owner PID is no longer running before manually removing that lock. Normal shutdown releases watchers/locks and stops active tasks; idle TUIs remain open and can be recovered by resuming the parent session.
-
-## Permissions and platform boundaries
-
-- This tool dispatches directly; user confirmation for expensive or risky workflows belongs to the caller/skill. It is not a sandbox.
-- Per the configured workflow, Codex runs with `--sandbox danger-full-access -a never`, and Claude with `--permission-mode bypassPermissions`. Workers have the invoking user's filesystem/network privileges. Headless Claude has a $0.50 CLI API budget; interactive mode does not impose that limit. Use only in trusted environments.
-- OpenCode uses `--auto`: automatically approve requests not explicitly denied by its configuration. Existing deny rules remain effective. Native mode injects the dependency-free local `opencode-plugin.mjs` through a merged `OPENCODE_CONFIG_CONTENT`; it never edits project/global config files or installs packages. Existing content must be valid JSON. Headless mode uses `opencode run --format json` and resumes by the exact reported `--session` ID. The adapter targets the OpenCode 1.x CLI/plugin API (source-checked against v1.19.3); 2.x API compatibility is not assumed. Install and authenticate the CLI yourself. DeepSeek Harness (`dsh`) is not integrated.
-- Pi's project-resource trust flags apply only to loading project resources, not filesystem access. A different cwd does not inherit the parent's project trust automatically.
-- Windows requires PowerShell 7 (`pwsh`) for external CLI invocation. Encoded PowerShell commands preserve Unicode, multiline tasks, JSON, and quoted paths. CLI hooks and `harness-done.cmd`/`.ps1` wrappers use the same native Windows Node installation. A mux must be available for visible TUIs; otherwise process fallback applies.
-- Existing worktrees, reports, and sessions created by the removed `worktree-studio` extension are left untouched. Its old `the_road_not_taken` tool and two-route manifests are not imported into this runtime. Synchronize platform resources/reload before using the new tool; old running workers should be finished before upgrading.
-
-Validation scripts are kept outside the repository. Check extension loading from this repository with `pi --no-extensions -e ./extensions/multi-harness/index.ts --list-models '<filter>'`.

package/extensions/subagent/mux.ts

@@ -1,621 +0,0 @@
-/**
- * subagent/mux.ts — Cross-platform Terminal Multiplexer Layer (tmux & Zellij)
- *
- * Provides:
- * - Surface creation (split pane, tab, or grid layout with scaling for multiple workers)
- * - Cross-platform command rendering (POSIX bash & Windows native PowerShell)
- * - Long command dispatch via wrapper scripts (.sh / .ps1 with UTF-8 BOM)
- * - Screen capture, surface termination, and exit polling
- */
-
-import { type ChildProcess, execFile, execFileSync, spawn, spawnSync } from "node:child_process";
-import { promisify } from "node:util";
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, watch, writeFileSync, type FSWatcher } from "node:fs";
-import { tmpdir } from "node:os";
-import { basename, dirname, join } from "node:path";
-
-const execFileAsync = promisify(execFile);
-
-export type MuxBackend = "tmux" | "zellij";
-export type WorkerBackend = "tmux" | "zellij" | "process";
-
-// ── Availability & Detection ──
-
-const commandAvailability = new Map<string, boolean>();
-
-function hasCommand(command: string): boolean {
-  if (commandAvailability.has(command)) {
-    return commandAvailability.get(command)!;
-  }
-
-  let available = false;
-  try {
-    if (process.platform === "win32") {
-      execFileSync("where.exe", [command], { stdio: "ignore" });
-    } else {
-      execFileSync("sh", ["-c", `command -v ${command}`], { stdio: "ignore" });
-    }
-    available = true;
-  } catch {
-    available = false;
-  }
-
-  commandAvailability.set(command, available);
-  return available;
-}
-
-export function isTmuxAvailable(): boolean {
-  return !!process.env.TMUX && hasCommand("tmux");
-}
-
-export function isZellijAvailable(): boolean {
-  return !!(process.env.ZELLIJ || process.env.ZELLIJ_SESSION_NAME) && hasCommand("zellij");
-}
-
-export function getMuxBackend(): MuxBackend | null {
-  const pref = (process.env.PI_SUBAGENT_MUX ?? "").trim().toLowerCase();
-  if (pref === "tmux") return isTmuxAvailable() ? "tmux" : null;
-  if (pref === "zellij") return isZellijAvailable() ? "zellij" : null;
-  if (isTmuxAvailable()) return "tmux";
-  if (isZellijAvailable()) return "zellij";
-  return null;
-}
-
-export function getWorkerBackend(): WorkerBackend {
-  const pref = (process.env.PI_SUBAGENT_BACKEND ?? process.env.PI_SUBAGENT_MUX ?? "").trim().toLowerCase();
-  if (pref === "process" || pref === "headless" || pref === "daemon") return "process";
-  if (pref === "tmux" && isTmuxAvailable()) return "tmux";
-  if (pref === "zellij" && isZellijAvailable()) return "zellij";
-  if (isTmuxAvailable()) return "tmux";
-  if (isZellijAvailable()) return "zellij";
-  return "process";
-}
-
-export function getPowerShellCommand(): string {
-  if (hasCommand("pwsh")) return "pwsh";
-  return "powershell";
-}
-
-export function isProcessSurface(surface: string): boolean {
-  return surface.startsWith("process:");
-}
-
-export function isMuxAvailable(): boolean {
-  return getMuxBackend() !== null;
-}
-
-export function muxSetupHint(): string {
-  if (process.platform === "win32") {
-    return "Start pi inside Zellij (`zellij --session pi`, then run `pi`).";
-  }
-  return "Start pi inside tmux (`tmux new -A -s pi 'pi'`) or Zellij (`zellij --session pi`, then run `pi`).";
-}
-
-export function requireMuxBackend(): MuxBackend {
-  const backend = getMuxBackend();
-  if (!backend) {
-    throw new Error(`No supported terminal multiplexer found. ${muxSetupHint()}`);
-  }
-  return backend;
-}
-
-// ── Shell Escaping & Command Rendering ──
-
-export function shellEscape(s: string): string {
-  return "'" + s.replace(/'/g, "'\\''") + "'";
-}
-
-export function psEscape(s: string): string {
-  return "'" + s.replace(/'/g, "''") + "'";
-}
-
-const PS_SAFE_TOKEN = /^[A-Za-z0-9_.:/\\+\-]+$/;
-function psToken(s: string): string {
-  return s !== "" && PS_SAFE_TOKEN.test(s) ? s : psEscape(s);
-}
-
-export interface SubagentCommandSpec {
-  cwd: string | null;
-  env: Array<[string, string]>;
-  args: string[];
-}
-
-export function renderSubagentCommand(spec: SubagentCommandSpec, options?: { persistent?: boolean }): {
-  script: string;
-  scriptExt: ".sh" | ".ps1";
-} {
-  const renderArgs = (escape: (s: string) => string): string =>
-    spec.args.map(escape).join(" ");
-
-  if (process.platform === "win32") {
-    const lines: string[] = [
-      `$OutputEncoding = [System.Text.Encoding]::UTF8`,
-      `[Console]::OutputEncoding = [System.Text.Encoding]::UTF8`,
-    ];
-    if (spec.cwd) {
-      lines.push(
-        `try { Set-Location -LiteralPath ${psEscape(spec.cwd)} -ErrorAction Stop } catch { Write-Output '__SUBAGENT_DONE_1__'; exit 1 }`,
-      );
-    }
-    for (const [key, value] of spec.env) {
-      lines.push(`$env:${key} = ${psEscape(value)}`);
-    }
-    lines.push(`& ${renderArgs(psToken)}`);
-    lines.push(
-      `if ($null -eq $LASTEXITCODE) { Write-Output '__SUBAGENT_DONE_127__' } else { Write-Output "__SUBAGENT_DONE_\${LASTEXITCODE}__" }`,
-    );
-    return { script: lines.join("\r\n"), scriptExt: ".ps1" };
-  }
-
-  const envPrefix = spec.env.map(([key, value]) => `${key}=${shellEscape(value)}`).join(" ");
-  const cdPrefix = spec.cwd ? `cd ${shellEscape(spec.cwd)} && ` : "";
-  const script = options?.persistent
-    ? `${cdPrefix}exec ${envPrefix ? `env ${envPrefix} ` : ""}${renderArgs(shellEscape)}`
-    : `${cdPrefix}${envPrefix ? envPrefix + " " : ""}${renderArgs(shellEscape)}; echo '__SUBAGENT_DONE_'$?'__'`;
-  return { script, scriptExt: ".sh" };
-}
-
-// ── Long Command Execution via Scripts ──
-
-export function sendLongCommand(
-  surface: string,
-  command: string,
-  options?: { scriptPath?: string; scriptPreamble?: string },
-): string {
-  const isWin = process.platform === "win32";
-  const ext = isWin ? ".ps1" : ".sh";
-  const scriptPath =
-    options?.scriptPath ??
-    join(
-      tmpdir(),
-      "pi-subagent-scripts",
-      `worker-${Date.now()}-${Math.random().toString(16).slice(2, 8)}${ext}`,
-    );
-  mkdirSync(dirname(scriptPath), { recursive: true });
-
-  const isSh = scriptPath.endsWith(".sh");
-  const parts: string[] = [];
-  if (isSh) parts.push("#!/usr/bin/env bash");
-  if (options?.scriptPreamble) parts.push(options.scriptPreamble.trimEnd());
-  parts.push(command);
-
-  let content = parts.join(isSh ? "\n" : "\r\n") + "\n";
-  if (isSh) {
-    content = content.replace(/\r\n/g, "\n");
-  } else if (isWin) {
-    // Add UTF-8 BOM so PowerShell 5.1/7 parses non-ASCII reliably
-    content = "\uFEFF" + content;
-  }
-  writeFileSync(scriptPath, content, { mode: 0o755 });
-
-  if (isSh) {
-    if (isWin) {
-      sendCommand(surface, `bash "${scriptPath.replace(/\\/g, "/")}"`);
-    } else {
-      sendCommand(surface, `bash ${shellEscape(scriptPath)}`);
-    }
-  } else {
-    const ps = getPowerShellCommand();
-    sendCommand(
-      surface,
-      `${ps} -NoProfile -ExecutionPolicy Bypass -Command "& ${psEscape(scriptPath)}; exit $LASTEXITCODE"`,
-    );
-  }
-
-  return scriptPath;
-}
-
-export function sendCommand(surface: string, command: string): void {
-  const backend = requireMuxBackend();
-  if (backend === "tmux") {
-    execFileSync("tmux", ["send-keys", "-t", surface, "-l", command], { encoding: "utf8" });
-    execFileSync("tmux", ["send-keys", "-t", surface, "Enter"], { encoding: "utf8" });
-    return;
-  }
-
-  // Zellij: write characters and press return (code 13)
-  const paneId = zellijPaneId(surface);
-  execFileSync("zellij", ["action", "write-chars", "--pane-id", paneId, command], {
-    encoding: "utf8",
-  });
-  execFileSync("zellij", ["action", "write", "--pane-id", paneId, "13"], { encoding: "utf8" });
-}
-
-// ── Zellij Plumbing ──
-
-export function zellijPaneId(surface: string): string {
-  return surface.startsWith("pane:") ? surface.slice("pane:".length) : surface;
-}
-
-function parseZellijPaneSurface(rawId: string): string {
-  const idMatch = rawId.match(/(\d+)/);
-  if (!idMatch) {
-    throw new Error(`Unexpected zellij pane id: ${rawId || "(empty)"}`);
-  }
-  return `pane:${idMatch[1]}`;
-}
-
-function createZellijSurface(name: string): string {
-  // Check available terminal dimensions
-  try {
-    const stdout = execFileSync("zellij", ["action", "list-clients"], { encoding: "utf8" });
-    // Attempt standard right split with no focus
-    const args = [
-      "action",
-      "new-pane",
-      "--direction",
-      "right",
-      "--near-current-pane",
-      "--no-focus",
-      "--name",
-      name,
-      "--cwd",
-      process.cwd(),
-    ];
-    const rawId = execFileSync("zellij", args, { encoding: "utf8" }).trim();
-    return parseZellijPaneSurface(rawId);
-  } catch {
-    // Fallback: stacked pane
-    const args = [
-      "action",
-      "new-pane",
-      "--stacked",
-      "--near-current-pane",
-      "--no-focus",
-      "--name",
-      name,
-      "--cwd",
-      process.cwd(),
-    ];
-    const rawId = execFileSync("zellij", args, { encoding: "utf8" }).trim();
-    return parseZellijPaneSurface(rawId);
-  }
-}
-
-// ── tmux Layout & Balancing ──
-
-let rebalanceTimer: ReturnType<typeof setTimeout> | null = null;
-
-function rebalanceTmuxLayout(targetPane?: string): void {
-  const target = process.env.TMUX_PANE ?? targetPane;
-  if (!target) return;
-  if (rebalanceTimer) clearTimeout(rebalanceTimer);
-
-  rebalanceTimer = setTimeout(() => {
-    rebalanceTimer = null;
-    try {
-      // Check total panes in the current window
-      const countOut = execFileSync(
-        "tmux",
-        ["list-panes", "-t", target, "-F", "#{pane_id}"],
-        { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
-      ).trim();
-      const paneCount = countOut.split("\n").filter(Boolean).length;
-
-      // <= 3 panes: even-horizontal; > 3 panes: tiled grid so each pane has space
-      const layout = paneCount <= 3 ? "even-horizontal" : "tiled";
-      execFileSync("tmux", ["select-layout", "-t", target, layout], { encoding: "utf8", stdio: "ignore" });
-    } catch {
-      // Best effort layout balancing
-    }
-  }, 100);
-}
-
-function createTmuxSurface(name: string): string {
-  const parentPane = process.env.TMUX_PANE;
-
-  // Query window width to see if we can safely split horizontally
-  let paneCount = 1;
-  let windowWidth = 120;
-  if (parentPane) {
-    try {
-      const info = execFileSync(
-        "tmux",
-        ["display-message", "-p", "-t", parentPane, "#{window_width}:#{window_panes}"],
-        { encoding: "utf8" },
-      ).trim().split(":");
-      windowWidth = parseInt(info[0], 10) || 120;
-      paneCount = parseInt(info[1], 10) || 1;
-    } catch {}
-  }
-
-  // If already overcrowded (> 5 panes or width per pane would be < 35 cols),
-  // create a new window in the background to avoid crushing the terminal
-  if (paneCount >= 6 || windowWidth / (paneCount + 1) < 35) {
-    const out = execFileSync(
-      "tmux",
-      ["new-window", "-d", "-n", `sub-${name}`, "-c", process.cwd(), "-P", "-F", "#{pane_id}"],
-      { encoding: "utf8" },
-    ).trim();
-    if (out.startsWith("%")) return out;
-  }
-
-  // Otherwise, split horizontally to the right of the parent pane
-  const splitArgs = ["split-window", "-d", "-h", "-c", process.cwd(), "-P", "-F", "#{pane_id}"];
-  if (parentPane) {
-    splitArgs.push("-t", parentPane);
-  }
-
-  const newPane = execFileSync("tmux", splitArgs, { encoding: "utf8" }).trim();
-  if (!newPane.startsWith("%")) {
-    throw new Error(`Unexpected tmux split-window output: ${newPane}`);
-  }
-
-  rebalanceTmuxLayout(newPane);
-  return newPane;
-}
-
-// ── Surface Management (Unified) ──
-
-export function createSurface(name: string, backend?: WorkerBackend): string {
-  const effective = backend ?? getWorkerBackend();
-  if (effective === "process") {
-    return `process:${name}-${Date.now().toString(36)}`;
-  }
-  if (effective === "zellij") {
-    return createZellijSurface(name);
-  }
-  return createTmuxSurface(name);
-}
-
-export function spawnProcessWorker(spec: {
-  cwd?: string | null;
-  env: Array<[string, string]>;
-  args: string[];
-  logPath: string;
-  useProcessEntrypoint?: boolean;
-}): ChildProcess {
-  const logFd = openSync(spec.logPath, "a");
-  const envObj = {
-    ...process.env,
-    ...Object.fromEntries(spec.env),
-  };
-
-  const rawCommand = spec.args[0] || "pi";
-  const userArgs = spec.args.slice(1);
-
-  // On Windows, if process.argv[1] is valid, run Node directly with the script
-  // to avoid cmd.exe / shell:true quoting pitfalls and ENOENT on pi.cmd.
-  const cliScript = process.argv[1];
-  let command = rawCommand;
-  let args = userArgs;
-
-  if (spec.useProcessEntrypoint !== false && cliScript && existsSync(cliScript) && (rawCommand === "pi" || rawCommand === process.execPath)) {
-    command = process.execPath;
-    args = [cliScript, ...userArgs];
-  }
-
-  const child = spawn(command, args, {
-    cwd: spec.cwd ?? process.cwd(),
-    env: envObj,
-    stdio: ["ignore", logFd, logFd],
-    shell: process.platform === "win32" && command === "pi",
-    detached: false,
-  });
-
-  child.on("close", () => {
-    try {
-      closeSync(logFd);
-    } catch {}
-  });
-
-  return child;
-}
-
-export function closeSurface(surface: string, childProcess?: ChildProcess): void {
-  if (isProcessSurface(surface)) {
-    if (childProcess && childProcess.exitCode === null && !childProcess.killed) {
-      if (process.platform === "win32" && childProcess.pid) {
-        try {
-          execFileSync("taskkill", ["/pid", String(childProcess.pid), "/T", "/F"], { stdio: "ignore" });
-        } catch {
-          try {
-            childProcess.kill();
-          } catch {}
-        }
-      } else {
-        try {
-          childProcess.kill("SIGTERM");
-          setTimeout(() => {
-            if (childProcess.exitCode === null && !childProcess.killed) {
-              try {
-                childProcess.kill("SIGKILL");
-              } catch {}
-            }
-          }, 1000).unref();
-        } catch {}
-      }
-    }
-    return;
-  }
-
-  const backend = getMuxBackend();
-  if (backend === "zellij") {
-    try {
-      execFileSync("zellij", ["action", "close-pane", "--pane-id", zellijPaneId(surface)], {
-        encoding: "utf8",
-        stdio: "ignore",
-      });
-    } catch {}
-    return;
-  }
-
-  if (backend === "tmux") {
-    try {
-      execFileSync("tmux", ["kill-pane", "-t", surface], { encoding: "utf8", stdio: "ignore" });
-    } catch {}
-    rebalanceTmuxLayout();
-  }
-}
-
-export async function readScreenAsync(surface: string, lines = 50): Promise<string> {
-  const backend = requireMuxBackend();
-  if (backend === "zellij") {
-    try {
-      const paneId = zellijPaneId(surface);
-      const { stdout } = await execFileAsync(
-        "zellij",
-        ["action", "dump-screen", "--pane-id", paneId, "--full"],
-        { encoding: "utf8" },
-      );
-      const split = stdout.split("\n");
-      return split.slice(-lines).join("\n");
-    } catch {
-      return "";
-    }
-  }
-
-  try {
-    const { stdout } = await execFileAsync(
-      "tmux",
-      ["capture-pane", "-p", "-t", surface, "-S", `-${Math.max(1, lines)}`],
-      { encoding: "utf8" },
-    );
-    return stdout;
-  } catch {
-    return "";
-  }
-}
-
-// ── Exit Polling ──
-
-export interface PollResult {
-  reason: "done" | "sentinel" | "error";
-  exitCode: number;
-  errorMessage?: string;
-}
-
-export async function pollForExit(
-  surface: string,
-  signal: AbortSignal,
-  options: {
-    interval: number;
-    sessionFile?: string;
-    childProcess?: ChildProcess;
-    onTick?: (elapsed: number) => void;
-  },
-): Promise<PollResult> {
-  const start = Date.now();
-
-  for (;;) {
-    if (signal.aborted) {
-      throw new Error("Aborted while waiting for subagent worker to finish");
-    }
-
-    // 1. Check for .exit sidecar file (written by bridge on completion/error)
-    if (options.sessionFile) {
-      try {
-        const exitFile = `${options.sessionFile}.exit`;
-        if (existsSync(exitFile)) {
-          const raw = readFileSync(exitFile, "utf-8");
-          rmSync(exitFile, { force: true });
-          const data = JSON.parse(raw);
-          if (data?.type === "error") {
-            return {
-              reason: "error",
-              exitCode: 1,
-              errorMessage: data.errorMessage || "Worker ended with error",
-            };
-          }
-          return { reason: "done", exitCode: 0 };
-        }
-      } catch {}
-    }
-
-    // 2. If running as a headless child process, check process exit
-    if (options.childProcess && options.childProcess.exitCode !== null) {
-      const code = options.childProcess.exitCode;
-      await new Promise((r) => setTimeout(r, 100));
-      if (options.sessionFile) {
-        try {
-          const exitFile = `${options.sessionFile}.exit`;
-          if (existsSync(exitFile)) {
-            const raw = readFileSync(exitFile, "utf-8");
-            rmSync(exitFile, { force: true });
-            const data = JSON.parse(raw);
-            return {
-              reason: data?.type === "error" ? "error" : "done",
-              exitCode: data?.type === "error" ? 1 : 0,
-              errorMessage: data?.errorMessage,
-            };
-          }
-        } catch {}
-      }
-      return {
-        reason: code === 0 ? "done" : "error",
-        exitCode: code,
-        errorMessage: code !== 0 ? `Process exited with code ${code}` : undefined,
-      };
-    }
-
-    // 3. Fallback for mux mode: check screen for sentinel output __SUBAGENT_DONE_<code >__
-    if (!isProcessSurface(surface)) {
-      try {
-        const screen = await readScreenAsync(surface, 5);
-        const match = screen.match(/__SUBAGENT_DONE_(\d+)__/);
-        if (match) {
-          const code = parseInt(match[1], 10);
-          return { reason: "sentinel", exitCode: code };
-        }
-      } catch {
-        // Surface may be destroyed
-        if (options.sessionFile) {
-          try {
-            const exitFile = `${options.sessionFile}.exit`;
-            if (existsSync(exitFile)) {
-              const raw = readFileSync(exitFile, "utf-8");
-              rmSync(exitFile, { force: true });
-              const data = JSON.parse(raw);
-              return {
-                reason: data?.type === "error" ? "error" : "done",
-                exitCode: data?.type === "error" ? 1 : 0,
-                errorMessage: data?.errorMessage,
-              };
-            }
-          } catch {}
-        }
-      }
-    }
-
-    const elapsed = Math.floor((Date.now() - start) / 1000);
-    options.onTick?.(elapsed);
-
-    await new Promise<void>((resolve, reject) => {
-      if (signal.aborted) return reject(new Error("Aborted"));
-      let watcher: FSWatcher | undefined;
-      let settled = false;
-      const done = () => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        signal.removeEventListener("abort", onAbort);
-        if (watcher) {
-          try { watcher.close(); } catch {}
-          watcher = undefined;
-        }
-        resolve();
-      };
-      const onAbort = () => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        if (watcher) {
-          try { watcher.close(); } catch {}
-          watcher = undefined;
-        }
-        reject(new Error("Aborted"));
-      };
-      signal.addEventListener("abort", onAbort, { once: true });
-      const timer = setTimeout(done, options.interval);
-      if (options.sessionFile) {
-        try {
-          const dir = dirname(options.sessionFile);
-          const target = basename(`${options.sessionFile}.exit`);
-          watcher = watch(dir, (_event, filename) => {
-            if (filename === target || existsSync(`${options.sessionFile}.exit`)) done();
-          });
-        } catch {}
-      }
-    });
-  }
-}