@rol1n/multi-harness 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# Multi Harness
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A 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 `multi-harness` through the aggregate package, or run from this repository:
+
+```sh
+pi --no-extensions -e ./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 ./multi-harness/index.ts --list-models '<filter>'`.

package/adapters.mjs

@@ -0,0 +1,72 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export const HARNESSES = Object.freeze(["pi", "codex", "claude", "opencode"]);
+const extensionDir = dirname(fileURLToPath(import.meta.url));
+export const quotePs = (value) => `'${value.replaceAll("'", "''")}'`;
+const quoteSh = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+
+/** Avoid cmd/npm shim argument re-parsing and preserve Unicode and JSON on Windows. */
+export function commandSpec(argv, platform = process.platform) {
+  if (platform !== "win32") return { command: argv[0], args: argv.slice(1) };
+  const script = `$OutputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false); & ${argv.map(quotePs).join(" ")}; if ($null -eq $LASTEXITCODE) { exit 1 }; exit $LASTEXITCODE`;
+  return { command: "pwsh", args: ["-NoProfile", "-EncodedCommand", Buffer.from(script, "utf16le").toString("base64")] };
+}
+
+/** Add a dependency-free local plugin for native OpenCode only; never rewrite user config. */
+export function buildEnv(config, inherited = process.env) {
+  if (config.harness !== "opencode" || !config.interactive) return inherited;
+  let content;
+  try { content = inherited.OPENCODE_CONFIG_CONTENT ? JSON.parse(inherited.OPENCODE_CONFIG_CONTENT) : {}; }
+  catch { throw new Error("OPENCODE_CONFIG_CONTENT must be valid JSON to append the multi-harness plugin."); }
+  if (!content || typeof content !== "object" || Array.isArray(content) || (content.plugin !== undefined && !Array.isArray(content.plugin))) {
+    throw new Error("OpenCode config must be an object with an optional plugin array.");
+  }
+  const plugin = pathToFileURL(join(extensionDir, "opencode-plugin.mjs")).href;
+  return { ...inherited, PI_MULTI_HARNESS_CWD: config.cwd,
+    OPENCODE_CONFIG_CONTENT: JSON.stringify({ ...content, plugin: [...(content.plugin ?? []).filter((item) => item !== plugin), plugin] }) };
+}
+
+export function buildArgs(config) {
+  const { harness, cwd, prompt, sessionFile, model, trusted, artifactDir, interactive, resume, sessionId } = config;
+  const modelArgs = model ? ["--model", model] : [];
+  switch (harness) {
+    case "pi":
+      return ["pi", ...(interactive ? ["--tui-mode", "regular", "-e", join(extensionDir, "worker-bridge.ts")] : ["--print"]),
+        trusted ? "--approve" : "--no-approve", "--session", sessionFile, ...modelArgs, prompt];
+    case "codex": {
+      const base = ["codex", "--sandbox", "danger-full-access", "-a", "never"];
+      if (interactive) {
+        const hook = JSON.stringify([process.execPath, join(extensionDir, "turn-hook.mjs"), artifactDir, "codex"]);
+        return [...base, "--cd", cwd, ...modelArgs, "-c", `notify=${hook}`, prompt];
+      }
+      return [...base, "exec", ...(resume ? ["resume", sessionId] : ["--cd", cwd]), "--skip-git-repo-check", "--json", ...modelArgs, "-"];
+    }
+    case "claude": {
+      const base = ["claude", "--permission-mode", "bypassPermissions", ...modelArgs];
+      if (interactive) {
+        const hook = (kind) => {
+          const args = [process.execPath, join(extensionDir, "turn-hook.mjs"), artifactDir, kind];
+          // Claude command hooks use a shell, not necessarily the interactive pane's shell.
+          if (process.platform === "win32") {
+            const script = `& ${args.map(quotePs).join(" ")}; exit $LASTEXITCODE`;
+            return `pwsh -NoProfile -EncodedCommand ${Buffer.from(script, "utf16le").toString("base64")}`;
+          }
+          return args.map(quoteSh).join(" ");
+        };
+        const settings = { hooks: {
+          UserPromptSubmit: [{ hooks: [{ type: "command", command: hook("claude-start"), timeout: 10 }] }],
+          Stop: [{ hooks: [{ type: "command", command: hook("claude"), timeout: 10 }] }],
+        } };
+        return [...base, "--session-id", sessionId, "--settings", JSON.stringify(settings), prompt];
+      }
+      return [...base, "-p", "--verbose", "--output-format", "stream-json", "--max-budget-usd", "0.50",
+        ...(resume ? ["--resume", sessionId] : ["--session-id", sessionId])];
+    }
+    case "opencode":
+      return interactive
+        ? ["opencode", cwd, "--auto", ...modelArgs, "--prompt", prompt]
+        : ["opencode", "run", "--dir", cwd, "--format", "json", "--auto", ...modelArgs, ...(resume ? ["--session", sessionId] : [])];
+    default: throw new Error(`Unsupported harness: ${harness}`);
+  }
+}

package/harness-done.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { join } from "node:path";
+import { readJson, writeJson } from "./ipc.mjs";
+
+const directory = process.env.PI_MULTI_HARNESS_DIR;
+if (!directory) throw new Error("harness-done must run inside a multi_harness worker.");
+const request = readJson(join(directory, "request.json"));
+if (!request) throw new Error("No task is assigned to this worker.");
+writeJson(join(directory, "proposal.json"), {
+  id: request.id,
+  summary: process.argv.slice(2).join(" ").trim() || "Task finished; inspect the artifacts for verification.",
+  at: Date.now(),
+});
+console.log("Summary recorded. The coordinator will be notified when this turn settles; keep the TUI open.");

package/index.ts

@@ -0,0 +1,375 @@
+import { spawn, execFileSync, type ChildProcess } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { closeSync, mkdirSync, openSync, statSync, unlinkSync, utimesSync, watch, writeFileSync, type FSWatcher } from "node:fs";
+import { homedir } from "node:os";
+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 "@rol1n/subagent/mux";
+import { HARNESSES, commandSpec } from "./adapters.mjs";
+import { readJson, writeJson } from "./ipc.mjs";
+
+const extensionDir = dirname(fileURLToPath(import.meta.url));
+const RUNNER = join(extensionDir, "process-runner.mjs");
+type Harness = "pi" | "codex" | "claude" | "opencode";
+type Status = "running" | "idle" | "timed_out" | "stopped" | "closed" | "exited" | "failed";
+interface Worker {
+  id: string; name: string; harness: Harness; cwd: string; model?: string; trusted: boolean;
+  artifactDir: string; sessionFile: string; sessionId: string; backend: WorkerBackend;
+  surface?: string; panePid?: string; status: Status; taskId?: string; summary?: string;
+  watcher?: FSWatcher; timer?: ReturnType<typeof setTimeout>; child?: ChildProcess;
+}
+const Params = Type.Object({
+  action: Type.Optional(Type.Union([Type.Literal("spawn"), Type.Literal("send"), Type.Literal("status"), Type.Literal("stop"), Type.Literal("close")], { description: "Defaults to spawn. Send continues an idle worker; stop terminates active work; close exits an idle TUI. All artifacts remain." })),
+  name: Type.Optional(Type.String({ description: "Unique worker name for spawn (letters, digits, hyphen, underscore)." })),
+  target: Type.Optional(Type.String({ description: "Existing worker name for send/stop/close; optional for status (lists all)." })),
+  harness: Type.Optional(Type.Union([Type.Literal("pi"), Type.Literal("codex"), Type.Literal("claude"), Type.Literal("opencode")], { description: "Required for spawn. Equal CLI peers, not execution modes." })),
+  cwd: Type.Optional(Type.String({ description: "Existing working directory for spawn; defaults to the parent cwd. No directory or Git worktree is created." })),
+  task: Type.Optional(Type.String({ description: "Task for spawn/send; include scope, deliverables, and verification criteria." })),
+  model: Type.Optional(Type.String({ description: "Optional model accepted by the selected CLI. Pi defaults to the parent model; other CLIs use their own defaults." })),
+  maxMinutes: Type.Optional(Type.Number({ minimum: 1, maximum: 120, description: "Turn timeout in minutes (default 15), not a spending limit. Native TUIs remain open on timeout until stopped or settled." })),
+});
+const errorText = (cause: unknown) => cause instanceof Error ? cause.message : String(cause);
+const busy = (worker: Worker) => worker.status === "running" || worker.status === "timed_out";
+
+function record(worker: Worker) {
+  const { watcher, timer, child, ...data } = worker;
+  return data;
+}
+function save(worker: Worker) { writeJson(join(worker.artifactDir, "worker.json"), record(worker)); }
+function backend(): WorkerBackend {
+  const preference = process.env.PI_MULTI_HARNESS_BACKEND;
+  if (preference && preference !== "process") throw new Error("PI_MULTI_HARNESS_BACKEND only accepts process.");
+  return preference === "process" ? "process" : getMuxBackend() ?? "process";
+}
+function inspectPane(worker: Worker) {
+  const runner = readJson(join(worker.artifactDir, "process.json"));
+  if (!runner?.pid) throw new Error(`No live runner identity for ${worker.name}.`);
+  process.kill(runner.pid, 0); // Fail before pasting if the runner has exited.
+  if (worker.backend !== "tmux" || !worker.surface) return;
+  const state = execFileSync("tmux", ["display-message", "-p", "-t", worker.surface, "#{pane_pid}:#{pane_dead}"], { encoding: "utf8", timeout: 2000 });
+  const [pid, dead] = state.trim().split(":");
+  if (pid !== worker.panePid || dead === "1") throw new Error(`The pane for ${worker.name} has exited or been replaced. Refusing to send input.`);
+}
+function setupBin(directory: string) {
+  const bin = join(directory, "bin");
+  mkdirSync(bin, { recursive: true, mode: 0o700 });
+  const done = join(extensionDir, "harness-done.mjs");
+  for (const name of ["harness-done", "studio-done"]) {
+    writeFileSync(join(bin, name), `#!/usr/bin/env sh\nexec ${shellEscape(process.execPath.replace(/\\/g, "/"))} ${shellEscape(done.replace(/\\/g, "/"))} "$@"\n`, { mode: 0o700 });
+    writeFileSync(join(bin, `${name}.ps1`), `\uFEFF& ${psEscape(process.execPath)} ${psEscape(done)} @args\r\nexit $LASTEXITCODE\r\n`);
+    writeFileSync(join(bin, `${name}.cmd`), `@"${process.execPath}" "${done}" %*\r\n`);
+  }
+  return bin;
+}
+function deliverInbox(worker: Worker, text: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let finished = false;
+    const watcher = watch(worker.artifactDir, inspect);
+    const timer = setTimeout(() => finish(Object.assign(new Error("Worker has not acknowledged delivery. The task may still be accepted; it remains tracked as running. Wait for completion or stop it before retrying."), { deliveryUncertain: true })), 5000);
+    function finish(error?: Error) {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      watcher.close();
+      error ? reject(error) : resolve();
+    }
+    function inspect() {
+      try {
+        const ack = readJson(join(worker.artifactDir, "ack.json"));
+        if (ack?.id === worker.taskId) finish(ack.status === "ok" ? undefined : new Error(ack.error ?? "Worker rejected the task."));
+      } catch (cause) { finish(Object.assign(new Error(errorText(cause)), { deliveryUncertain: true })); }
+    }
+    watcher.on("error", (cause) => finish(Object.assign(cause, { deliveryUncertain: true })));
+    try {
+      const file = join(worker.artifactDir, "inbox.json");
+      writeJson(file, { id: worker.taskId, task: text });
+      // Some Bun directory watchers coalesce an atomic rename under its temporary filename.
+      // A final-file change event is an explicit wakeup, not a polling/re-send loop.
+      const now = new Date();
+      try { utimesSync(file, now, now); }
+      catch (cause) { if ((cause as NodeJS.ErrnoException).code !== "ENOENT") throw cause; } // Already consumed is fine.
+      inspect();
+    } catch (cause) { finish(Object.assign(new Error(errorText(cause)), { deliveryUncertain: true })); }
+  });
+}
+
+function prompt(task: string, id: string) {
+  return `[Harness task ${id}]\n${task}\n\nCoordinator protocol: keep the native TUI open after completing this task. Finish with a concise summary of artifacts, verification actually performed, and blockers. Optionally run harness-done "summary" (studio-done is an alias) to record your summary. The turn-settlement hook sends completion to the parent automatically; do not exit the application. Do not launch nested multi_harness workers.`;
+}
+function terminate(worker: Worker) {
+  if (worker.timer) clearTimeout(worker.timer);
+  worker.timer = undefined;
+  if (worker.backend === "process" && worker.child?.pid && worker.child.exitCode === null && worker.child.signalCode === null) {
+    if (process.platform === "win32") execFileSync("taskkill", ["/pid", String(worker.child.pid), "/T", "/F"], { stdio: "ignore" });
+    else {
+      try { process.kill(-worker.child.pid, "SIGTERM"); }
+      catch (cause) { if ((cause as NodeJS.ErrnoException).code !== "ESRCH") throw cause; }
+      const pid = worker.child.pid;
+      setTimeout(() => {
+        try { process.kill(-pid, "SIGKILL"); }
+        catch (cause) { if ((cause as NodeJS.ErrnoException).code !== "ESRCH") console.error(`Cannot terminate worker group ${pid}: ${errorText(cause)}`); }
+      }, 1000).unref();
+    }
+  } else if (worker.surface) {
+    closeSurface(worker.surface);
+    worker.surface = undefined;
+  }
+}
+
+export default function multiHarness(pi: ExtensionAPI) {
+  if (process.env.PI_MULTI_HARNESS_WORKER === "1") return;
+  const workers = new Map<string, Worker>();
+  const captures = new Set<Promise<void>>();
+  const controls = new Set<string>();
+  function release(worker: Worker) {
+    if (!controls.delete(worker.id)) return;
+    unlinkSync(join(worker.artifactDir, "controller.lock"));
+  }
+  let shuttingDown = false;
+  function notify(worker: Worker, status: string, summary: string) {
+    if (shuttingDown) return;
+    pi.sendMessage({ customType: "multi_harness_result", content: `[Harness "${worker.name}" (${worker.harness}) ${status}]\n${summary.slice(-8000)}\nArtifacts: ${worker.artifactDir}`, display: true, details: { ...record(worker), event: status } }, { triggerTurn: true, deliverAs: "steer" });
+  }
+  function sync(worker: Worker) {
+    const completion = readJson(join(worker.artifactDir, "completion.json"));
+    const processReady = worker.backend !== "process" || !worker.child || worker.child.exitCode !== null || worker.child.signalCode !== null;
+    if (processReady && busy(worker) && worker.taskId && completion?.id === worker.taskId) {
+      if (worker.timer) clearTimeout(worker.timer);
+      worker.timer = undefined;
+      worker.summary = completion.summary;
+      worker.status = worker.backend === "process" ? (completion.status === "completed" ? "idle" : "failed") : "idle";
+      save(worker);
+      notify(worker, completion.status, [completion.summary, completion.error].filter(Boolean).join("\n"));
+      if (worker.surface) {
+        const capture = readScreenAsync(worker.surface, 100).then((screen) => {
+          if (screen.trim()) writeFileSync(join(worker.artifactDir, `${completion.id}.screen.log`), screen, "utf8");
+        }).catch((cause) => console.error(`Could not capture ${worker.name}: ${errorText(cause)}`)).finally(() => captures.delete(capture));
+        captures.add(capture);
+      }
+    }
+    const ack = readJson(join(worker.artifactDir, "ack.json"));
+    if (busy(worker) && ack?.id === worker.taskId && ack?.status === "error") {
+      if (worker.timer) clearTimeout(worker.timer);
+      worker.timer = undefined;
+      worker.status = "idle";
+      save(worker);
+      notify(worker, "failed", `Worker rejected the task: ${ack.error}`);
+    }
+    const state = readJson(join(worker.artifactDir, "state.json"));
+    if (worker.backend !== "process" && state?.status === "exited" && !["closed", "stopped", "exited"].includes(worker.status)) {
+      worker.status = "exited";
+      if (worker.timer) clearTimeout(worker.timer);
+      worker.timer = undefined;
+      if (worker.surface) closeSurface(worker.surface);
+      worker.surface = undefined;
+      worker.watcher?.close(); worker.watcher = undefined;
+      release(worker);
+      save(worker);
+      notify(worker, "exited", "The native TUI exited. Its pane was closed; artifacts were preserved.");
+    }
+  }
+  function attach(worker: Worker) {
+    if (worker.watcher) return;
+    if (!controls.has(worker.id)) {
+      try {
+        const fd = openSync(join(worker.artifactDir, "controller.lock"), "wx", 0o600);
+        try { writeFileSync(fd, JSON.stringify({ pid: process.pid })); } finally { closeSync(fd); }
+        controls.add(worker.id);
+      } catch (cause) {
+        throw new Error(`Cannot take control of ${worker.name}: ${errorText(cause)}. A second session may own it. After a crash, verify the owner process is gone before manually removing controller.lock.`);
+      }
+    }
+    worker.watcher = watch(worker.artifactDir, (_event, name) => {
+      if (!["completion.json", "state.json", "ack.json"].includes(name?.toString() ?? "")) return;
+      try { sync(worker); }
+      catch (cause) { notify(worker, "IPC error", errorText(cause)); }
+    });
+    worker.watcher.on("error", (cause) => notify(worker, "watcher error", `Automatic completion delivery unavailable: ${cause.message}`));
+    sync(worker); // Subscribe before checking to avoid a fast-completion race.
+  }
+  function arm(worker: Worker, task: string, minutes: number) {
+    worker.taskId = randomUUID();
+    worker.status = "running";
+    writeJson(join(worker.artifactDir, "request.json"), { id: worker.taskId, task, at: Date.now() });
+    writeFileSync(join(worker.artifactDir, `${worker.taskId}.prompt.md`), prompt(task, worker.taskId), { mode: 0o600 });
+    worker.timer = setTimeout(() => {
+      if (!busy(worker)) return;
+      worker.status = "timed_out";
+      if (worker.backend === "process") { terminate(worker); worker.status = "stopped"; }
+      save(worker);
+      notify(worker, "timed_out", worker.backend === "process" ? "Process stopped after the time limit." : "No settlement received before the deadline. TUI remains open; inspect it or stop the worker. This is not a token/cost limit.");
+    }, minutes * 60_000);
+    save(worker);
+    return prompt(task, worker.taskId);
+  }
+  function launch(worker: Worker, text: string, resume = false) {
+    const metadata = readJson(join(worker.artifactDir, "metadata.json"));
+    if (resume && ["codex", "opencode"].includes(worker.harness) && !metadata?.sessionId) throw new Error(`${worker.harness} did not report a session ID; cannot resume a headless conversation.`);
+    const configFile = join(worker.artifactDir, "runner.json");
+    writeJson(configFile, { harness: worker.harness, cwd: worker.cwd, prompt: text, sessionFile: worker.sessionFile,
+      model: worker.model, trusted: worker.trusted, artifactDir: worker.artifactDir, interactive: worker.backend !== "process", resume,
+      sessionId: metadata?.sessionId ?? worker.sessionId });
+    const bin = setupBin(worker.artifactDir);
+    const env: Array<[string, string]> = [["PI_MULTI_HARNESS_WORKER", "1"], ["PI_SUBAGENT_ACTIVE", "1"], ["PI_MULTI_HARNESS_DIR", worker.artifactDir], ["PATH", `${bin}${delimiter}${process.env.PATH ?? ""}`]];
+    if (process.env.PI_CODING_AGENT_DIR) env.push(["PI_CODING_AGENT_DIR", process.env.PI_CODING_AGENT_DIR]);
+    if (worker.backend !== "process") {
+      worker.surface = createSurface(worker.name, worker.backend);
+      if (worker.backend === "tmux") worker.panePid = execFileSync("tmux", ["display-message", "-p", "-t", worker.surface, "#{pane_pid}"], { encoding: "utf8" }).trim();
+      const rendered = renderSubagentCommand({ cwd: worker.cwd, env, args: [process.execPath, RUNNER, configFile] });
+      if (process.platform === "win32") {
+        writeFileSync(join(worker.artifactDir, "launch.ps1"), `\uFEFF${rendered.script}`, "utf8");
+        sendCommand(worker.surface, `pwsh -NoProfile -EncodedCommand ${Buffer.from(rendered.script, "utf16le").toString("base64")}`);
+      } else sendLongCommand(worker.surface, rendered.script, { scriptPath: join(worker.artifactDir, `launch${rendered.scriptExt}`) });
+    } else {
+      const fd = openSync(join(worker.artifactDir, "console.log"), "a");
+      try {
+        const child = spawn(process.execPath, [RUNNER, configFile], { cwd: worker.cwd, env: { ...process.env, ...Object.fromEntries(env) }, detached: process.platform !== "win32", stdio: ["ignore", fd, fd], windowsHide: true });
+        worker.child = child;
+        child.once("error", (cause) => { if (!busy(worker)) return; terminate(worker); worker.status = "failed"; save(worker); notify(worker, "failed", cause.message); });
+        child.once("close", (code) => {
+          if (worker.child !== child) return;
+          try {
+            sync(worker);
+            if (busy(worker)) { if (worker.timer) clearTimeout(worker.timer); worker.status = "failed"; save(worker); notify(worker, "failed", `Runner exited (${code}) without completion. Inspect console.log.`); }
+          } catch (cause) { notify(worker, "IPC error", `Cannot collect exited runner: ${errorText(cause)}`); }
+        });
+      } finally { closeSync(fd); }
+    }
+    save(worker);
+  }
+  async function dispatch(worker: Worker, text: string) {
+    if (worker.backend === "process") {
+      if (worker.child && worker.child.exitCode === null) throw new Error("Previous process is still flushing its output; retry after it exits.");
+      launch(worker, text, true);
+      return;
+    }
+    inspectPane(worker);
+    const state = readJson(join(worker.artifactDir, "state.json"));
+    if (state?.status !== "idle") throw new Error("Native TUI is not idle; finish its current turn or permission dialog first.");
+    if (worker.harness === "pi" || worker.harness === "opencode") {
+      await deliverInbox(worker, text);
+      return;
+    }
+    if (worker.harness === "codex") {
+      const metadata = readJson(join(worker.artifactDir, "metadata.json"));
+      if (metadata?.sessionId) {
+        const spec = commandSpec(["codex", "queue", "--thread", metadata.sessionId, "--message", text]);
+        execFileSync(spec.command, spec.args, { cwd: worker.cwd, encoding: "utf8", timeout: 10000, windowsHide: true });
+        return;
+      }
+    }
+    // Idle-only bracketed paste preserves multiline tasks without interpreting them as keystrokes.
+    if (worker.backend === "tmux") {
+      const buffer = `harness-${worker.taskId}`;
+      const taskFile = join(worker.artifactDir, `${worker.taskId}.prompt.md`);
+      execFileSync("tmux", ["load-buffer", "-b", buffer, taskFile], { stdio: "ignore", timeout: 2000 });
+      execFileSync("tmux", ["paste-buffer", "-p", "-d", "-b", buffer, "-t", worker.surface!], { stdio: "ignore", timeout: 2000 });
+      execFileSync("tmux", ["send-keys", "-t", worker.surface!, "Enter"], { stdio: "ignore", timeout: 2000 });
+    } else {
+      execFileSync("zellij", ["action", "write-chars", "--pane-id", zellijPaneId(worker.surface!), `\x1b[200~${text}\x1b[201~`], { stdio: "ignore", timeout: 2000 });
+      execFileSync("zellij", ["action", "write", "--pane-id", zellijPaneId(worker.surface!), "13"], { stdio: "ignore", timeout: 2000 });
+    }
+  }
+  pi.registerTool({
+    name: "multi_harness", label: "Multi Harness",
+    description: "Delegate work to a named pi, codex, claude, or opencode CLI peer in any existing cwd. Spawn/send return immediately; turn completion is pushed to this parent session. Native mux TUIs stay open for follow-ups; no mux uses a silent process with session resume. No Git, worktree, comparison mode, model picker, or confirmation dialog is built in. External CLIs use their own billing; permission defaults are documented in the extension README. When the worktree-studio skill is installed, use it for isolated alternative implementations.",
+    promptSnippet: "Spawn named CLI peers with multi_harness, then wait for automatic completion messages; do not poll terminals or status loops.",
+    promptGuidelines: ["Specify scope, existing cwd, and verification criteria. Prevent overlapping file edits yourself. Worker conclusions are unverified; review artifacts before integrating. Use stop for active work and close for idle TUIs."],
+    parameters: Params,
+    async execute(_id, params, signal, _update, ctx) {
+      const action = params.action ?? "spawn";
+      const reply = (text: string, details: unknown = {}) => ({ content: [{ type: "text" as const, text }], details });
+      if (action === "status") {
+        const selected = params.target ? [workers.get(params.target)].filter(Boolean) as Worker[] : [...workers.values()];
+        return reply(selected.length ? selected.map((w) => `${w.name} (${w.harness}): ${w.status}; cwd=${w.cwd}; ${w.surface ?? "process"}; artifacts=${w.artifactDir}`).join("\n") : "No matching workers in this session.", { workers: selected.map(record) });
+      }
+      if ((action === "spawn" || action === "send") && params.task && /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(params.task)) throw new Error("Tasks may contain multiline text, but not terminal control characters.");
+      if (action === "spawn") {
+        if (!params.name || !/^[\w-]{1,64}$/.test(params.name)) throw new Error("Spawn requires a name of 1–64 letters, digits, hyphens or underscores.");
+        if (workers.has(params.name)) throw new Error(`Worker ${params.name} already exists. Use send or choose a new name.`);
+        if (!params.harness || !HARNESSES.includes(params.harness) || !params.task?.trim()) throw new Error("Spawn requires harness (pi/codex/claude/opencode) and task.");
+        const cwd = resolve(ctx.cwd, params.cwd ?? ".");
+        if (!statSync(cwd).isDirectory()) throw new Error(`Not a directory: ${cwd}`);
+        const check = commandSpec([params.harness, "--version"]);
+        execFileSync(check.command, check.args, { cwd, encoding: "utf8", timeout: 10000, windowsHide: true });
+        if (signal?.aborted) throw new Error("Spawn cancelled before launch.");
+        const id = randomUUID();
+        const artifactDir = join(homedir(), ".pi", "agent", "multi-harness", id);
+        mkdirSync(artifactDir, { recursive: true, mode: 0o700 });
+        const worker: Worker = { id, name: params.name, harness: params.harness, cwd, model: params.model ?? (params.harness === "pi" && ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined), trusted: cwd === resolve(ctx.cwd) && ctx.isProjectTrusted(), artifactDir, sessionFile: join(artifactDir, "session.jsonl"), sessionId: randomUUID(), backend: backend(), status: "running" };
+        workers.set(worker.name, worker); // Reserve the name before any asynchronous operation.
+        try { attach(worker); const text = arm(worker, params.task, params.maxMinutes ?? 15); launch(worker, text); }
+        catch (cause) { terminate(worker); worker.watcher?.close(); release(worker); worker.status = "failed"; save(worker); throw cause; }
+        pi.appendEntry("multi_harness_worker", { artifactDir });
+        return reply(`Started ${worker.name} (${worker.harness}, ${worker.backend}). Completion will be pushed automatically; do not poll. Artifacts: ${artifactDir}`, record(worker));
+      }
+      const worker = params.target ? workers.get(params.target) : undefined;
+      if (!worker) throw new Error("Specify target: an existing worker name.");
+      if (action === "send") {
+        if (worker.status !== "idle" || !params.task?.trim()) throw new Error("Send requires an idle worker and non-empty task. Stop active work first.");
+        if (signal?.aborted) throw new Error("Send cancelled before dispatch.");
+        const oldId = worker.taskId;
+        const previousRequest = readJson(join(worker.artifactDir, "request.json"));
+        try {
+          const text = arm(worker, params.task, params.maxMinutes ?? 15);
+          await dispatch(worker, text);
+        } catch (cause) {
+          if ((cause as { deliveryUncertain?: boolean }).deliveryUncertain) { save(worker); throw cause; }
+          if (worker.timer) clearTimeout(worker.timer);
+          worker.status = "idle"; worker.taskId = oldId;
+          if (previousRequest) writeJson(join(worker.artifactDir, "request.json"), previousRequest);
+          save(worker);
+          throw cause;
+        }
+        return reply(`Sent a new task to ${worker.name}. Completion will be pushed automatically.`, record(worker));
+      }
+      const nativeBusy = worker.backend !== "process" && readJson(join(worker.artifactDir, "state.json"))?.status === "running";
+      if (action === "close" && (busy(worker) || nativeBusy)) throw new Error("Worker has active work. Use stop before close.");
+      if (action === "stop" && !busy(worker) && !nativeBusy) return reply(`${worker.name} has no active work; use close to exit its idle TUI.`, record(worker));
+      if (action === "close") {
+        await Promise.all(captures);
+        if (shuttingDown || busy(worker) || (worker.backend !== "process" && readJson(join(worker.artifactDir, "state.json"))?.status === "running")) throw new Error("Worker state changed while closing; inspect status and stop active work first.");
+      }
+      terminate(worker);
+      worker.status = action === "stop" ? "stopped" : "closed";
+      worker.watcher?.close(); worker.watcher = undefined;
+      release(worker);
+      save(worker);
+      return reply(`${action === "stop" ? "Stopped" : "Closed"} ${worker.name}. Working files, sessions, and artifacts are preserved.`, record(worker));
+    },
+  });
+  pi.on("session_start", (_event, ctx) => {
+    shuttingDown = false;
+    for (const worker of workers.values()) {
+      if (busy(worker)) { terminate(worker); worker.status = "stopped"; save(worker); }
+      worker.watcher?.close();
+      release(worker);
+    }
+    workers.clear();
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type !== "custom" || entry.customType !== "multi_harness_worker") continue;
+      const saved = readJson(join((entry.data as { artifactDir: string }).artifactDir, "worker.json"));
+      if (!saved || workers.has(saved.name)) continue;
+      const worker = saved as Worker;
+      workers.set(worker.name, worker);
+      if (!["closed", "stopped", "exited", "failed"].includes(worker.status)) {
+        try { attach(worker); }
+        catch (cause) {
+          workers.delete(worker.name);
+          if (ctx.hasUI) ctx.ui.notify(errorText(cause), "warning");
+          else console.error(errorText(cause));
+        }
+      }
+    }
+  });
+  pi.on("session_shutdown", () => {
+    shuttingDown = true;
+    for (const worker of workers.values()) {
+      if (busy(worker)) { terminate(worker); worker.status = "stopped"; save(worker); }
+      worker.watcher?.close(); worker.watcher = undefined;
+      release(worker);
+    }
+  });
+}

package/ipc.mjs

@@ -0,0 +1,37 @@
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+export function readJson(path) {
+  try { return JSON.parse(readFileSync(path, "utf8")); }
+  catch (error) {
+    if (error.code === "ENOENT") return undefined;
+    throw new Error(`Cannot read IPC file ${path}: ${error.message}`, { cause: error });
+  }
+}
+
+export function writeJson(path, value) {
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  writeFileSync(temporary, JSON.stringify(value, null, 2), { encoding: "utf8", mode: 0o600 });
+  renameSync(temporary, path);
+}
+
+export function taskId(prompt) {
+  return typeof prompt === "string" ? prompt.match(/\[Harness task ([\w-]+)\]/)?.[1] : undefined;
+}
+
+/** Record a settled turn, not a model's early claim that it has finished. */
+export function complete(directory, result) {
+  const request = readJson(join(directory, "request.json"));
+  if (!request || !result.id || request.id !== result.id) return;
+  const previous = readJson(join(directory, "completion.json"));
+  if (previous?.id === result.id) return;
+  const proposal = readJson(join(directory, "proposal.json"));
+  const value = {
+    ...result,
+    summary: result.summary || (proposal?.id === result.id ? proposal.summary : undefined) || "No final text captured; inspect the session or log.",
+    at: Date.now(),
+  };
+  writeJson(join(directory, "state.json"), { status: "idle", id: result.id, at: value.at });
+  writeJson(join(directory, "completion.json"), value);
+}

package/opencode-plugin.mjs

@@ -0,0 +1,99 @@
+import { existsSync, realpathSync, renameSync, unlinkSync, watch } from "node:fs";
+import { join } from "node:path";
+import { complete, readJson, taskId, writeJson } from "./ipc.mjs";
+
+const text = (parts) => (parts ?? []).filter((part) => part.type === "text").map((part) => part.text).join("\n");
+const describe = (error) => error?.data?.message ?? error?.message ?? error?.name ?? String(error);
+
+/** OpenCode 1.x server plugin: native SDK input and idle events, no terminal key injection. */
+export default async function multiHarnessOpenCode({ client, directory }) {
+  const artifactDir = process.env.PI_MULTI_HARNESS_DIR;
+  if (process.env.PI_MULTI_HARNESS_WORKER !== "1" || !artifactDir) return {};
+  const assignedCwd = process.env.PI_MULTI_HARNESS_CWD;
+  if (assignedCwd && realpathSync(directory) !== realpathSync(assignedCwd)) return {};
+  let sessionId = readJson(join(artifactDir, "metadata.json"))?.sessionId;
+  let active;
+  let settling = false;
+  let receiving = false;
+  let disposed = false;
+  let model;
+  let agent;
+  const inbox = join(artifactDir, "inbox.json");
+  const state = (status, id) => writeJson(join(artifactDir, "state.json"), { status, id, at: Date.now() });
+
+  async function receive() {
+    if (disposed || receiving) return;
+    receiving = true;
+    let payload;
+    try {
+      const processing = `${inbox}.processing`;
+      renameSync(inbox, processing);
+      try { payload = readJson(processing); } finally { unlinkSync(processing); }
+      const request = readJson(join(artifactDir, "request.json"));
+      if (!sessionId || !payload?.id || payload.id !== request?.id || typeof payload.task !== "string" || taskId(payload.task) !== payload.id) {
+        throw new Error("OpenCode inbox requires a known session and the current task ID.");
+      }
+      const current = readJson(join(artifactDir, "state.json"));
+      if (current?.status !== "idle") throw new Error("OpenCode is not idle; do not dispatch during another turn or permission dialog.");
+      state("running", payload.id);
+      // The injected SDK is bound to this backend/directory, so the visible TUI observes this same session.
+      const result = await client.session.promptAsync({ path: { id: sessionId }, body: { parts: [{ type: "text", text: payload.task }], ...(model ? { model } : {}), ...(agent ? { agent } : {}) } });
+      if (result.error) throw new Error(`OpenCode rejected the prompt: ${describe(result.error)}`);
+      writeJson(join(artifactDir, "ack.json"), { id: payload.id, status: "ok" });
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        if (!active) state("idle");
+        writeJson(join(artifactDir, "ack.json"), { id: payload?.id ?? readJson(join(artifactDir, "request.json"))?.id, status: "error", error: describe(error) });
+      }
+    } finally { receiving = false; }
+  }
+
+  async function settled() {
+    if (settling || disposed) return;
+    if (!active) { state("idle"); return; }
+    settling = true;
+    const turn = active;
+    try {
+      const result = await client.session.messages({ path: { id: sessionId } });
+      if (result.error || !Array.isArray(result.data)) throw new Error(`Cannot read OpenCode messages: ${result.error ? describe(result.error) : "invalid SDK response"}`);
+      const messages = result.data;
+      const start = messages.findIndex((message) => message.info?.id === turn.messageId);
+      if (start === -1) throw new Error("Assigned user message was not found; refusing to report another turn's answer.");
+      // Compaction may add synthetic user continuations; use the last root-session answer after our message.
+      const last = messages.slice(start + 1).filter((message) => message.info?.role === "assistant" && (!message.info.sessionID || message.info.sessionID === sessionId)).at(-1);
+      const error = last?.info.error ?? (last?.info.finish === "stop" ? undefined : turn.error) ?? (!last ? new Error("No assistant response for the assigned task.") : undefined);
+      complete(artifactDir, { id: turn.id, sessionId, status: error ? "failed" : "completed", summary: text(last?.parts), ...(error ? { error: describe(error) } : {}) });
+    } catch (error) {
+      complete(artifactDir, { id: turn.id, sessionId, status: "failed", error: describe(error) });
+    } finally {
+      if (active === turn) active = undefined;
+      settling = false;
+    }
+  }
+
+  const watcher = watch(artifactDir, (_event, name) => { if (name?.toString() === "inbox.json" || existsSync(inbox)) void receive(); });
+  watcher.unref();
+  watcher.on("error", (error) => writeJson(join(artifactDir, "ack.json"), { id: readJson(join(artifactDir, "request.json"))?.id, status: "error", error: `OpenCode inbox watcher failed: ${error.message}` }));
+  void receive();
+  return {
+    "chat.message": async (input, output) => {
+      const id = taskId(text(output.parts));
+      const request = readJson(join(artifactDir, "request.json"));
+      if (sessionId && input.sessionID !== sessionId) return; // Ignore subagents and unrelated sessions.
+      if (id && id === request?.id) {
+        sessionId = input.sessionID;
+        active = { id, messageId: output.message.id ?? input.messageID };
+        writeJson(join(artifactDir, "metadata.json"), { harness: "opencode", sessionId });
+      } else if (!sessionId) return;
+      model = input.model;
+      agent = input.agent;
+      state("running", id);
+    },
+    event: async ({ event }) => {
+      if (!sessionId || event.properties?.sessionID !== sessionId) return;
+      if (event.type === "session.error" && active) active.error = event.properties.error;
+      if (event.type === "session.idle" || (event.type === "session.status" && event.properties.status?.type === "idle")) await settled();
+    },
+    dispose: async () => { disposed = true; watcher.close(); },
+  };
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@rol1n/multi-harness",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "description": "multi-harness extension from pi-kit",
+  "keywords": [
+    "pi-package"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RolinShmily/pi-kit.git",
+    "directory": "multi-harness"
+  },
+  "homepage": "https://github.com/RolinShmily/pi-kit#readme",
+  "bugs": {
+    "url": "https://github.com/RolinShmily/pi-kit/issues"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@rol1n/subagent": "^0.1.1"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [],
+    "prompts": [],
+    "themes": []
+  }
+}

package/process-runner.mjs

@@ -0,0 +1,115 @@
+import { spawn } from "node:child_process";
+import { appendFileSync } from "node:fs";
+import { join } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+import { buildArgs, buildEnv, commandSpec } from "./adapters.mjs";
+import { complete, readJson, writeJson } from "./ipc.mjs";
+
+const config = readJson(process.argv[2]);
+if (!config) throw new Error("Missing multi-harness runner configuration.");
+const { artifactDir, interactive, harness } = config;
+const request = readJson(join(artifactDir, "request.json"));
+writeJson(join(artifactDir, "process.json"), { pid: process.pid, at: Date.now() });
+let child;
+try {
+  const spec = commandSpec(buildArgs(config));
+  child = spawn(spec.command, spec.args, {
+    cwd: config.cwd, env: buildEnv(config), windowsHide: !interactive,
+    stdio: interactive ? "inherit" : ["pipe", "pipe", "pipe"],
+  });
+} catch (error) {
+  complete(artifactDir, { id: request.id, status: "failed", error: `Cannot launch ${harness}: ${error.message}` });
+  writeJson(join(artifactDir, "state.json"), { status: "exited", code: 1, at: Date.now() });
+  throw error;
+}
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(signal, () => child.kill(signal === "SIGHUP" && process.platform === "win32" ? "SIGTERM" : signal));
+}
+let summary = "";
+let failure;
+let stderr = "";
+let pending = "";
+const decoder = new StringDecoder("utf8");
+let metadata = readJson(join(artifactDir, "metadata.json")) ?? {};
+const seenSteps = new Set();
+const openCodeText = new Map();
+let openCodeMessageId;
+let openCodeSessionSeen = false;
+if (harness === "opencode") { delete metadata.usage; delete metadata.costUSD; }
+function textBlocks(content) {
+  return Array.isArray(content) ? content.filter((part) => part.type === "text").map((part) => part.text).join("\n") : "";
+}
+function onLine(line) {
+  if (harness === "pi") { summary = `${summary}${line}\n`.slice(-16000); return; }
+  let event;
+  try { event = JSON.parse(line); }
+  catch (error) {
+    if (error instanceof SyntaxError) return; // CLI diagnostics are preserved in console.log.
+    throw error;
+  }
+  if (harness === "codex") {
+    if (event.type === "thread.started") metadata.sessionId = event.thread_id ?? event["thread-id"];
+    if (event.item?.type === "agent_message") summary = event.item.text ?? summary;
+    if (event.type === "turn.completed") metadata.usage = event.usage;
+    if (["turn.failed", "error"].includes(event.type)) failure = event.message ?? event.error?.message ?? "Codex turn failed";
+  } else if (harness === "opencode") {
+    if (typeof event.sessionID === "string" && event.sessionID) {
+      openCodeSessionSeen = true;
+      if (config.resume && event.sessionID !== config.sessionId) failure = "OpenCode resumed a different session; refusing to treat it as the requested conversation.";
+      else metadata.sessionId = event.sessionID;
+    }
+    if (event.type === "text" && typeof event.part?.text === "string") {
+      if (event.part.messageID !== openCodeMessageId) { openCodeText.clear(); openCodeMessageId = event.part.messageID; }
+      openCodeText.set(event.part.id ?? "last", event.part.text);
+      summary = [...openCodeText.values()].join("\n");
+    }
+    if (event.type === "error") failure = event.error?.data?.message ?? event.error?.message ?? event.error?.name ?? "OpenCode turn failed";
+    if (event.type === "step_finish" && event.part && (!event.part.id || !seenSteps.has(event.part.id))) {
+      if (event.part.id) seenSteps.add(event.part.id);
+      if (event.part.tokens) {
+        metadata.usage ??= {};
+        for (const [key, value] of Object.entries({ input: event.part.tokens.input, output: event.part.tokens.output, reasoning: event.part.tokens.reasoning, cacheRead: event.part.tokens.cache?.read, cacheWrite: event.part.tokens.cache?.write })) {
+          if (typeof value === "number") metadata.usage[key] = (metadata.usage[key] ?? 0) + value;
+        }
+      }
+      if (typeof event.part.cost === "number") metadata.costUSD = (metadata.costUSD ?? 0) + event.part.cost;
+    }
+  } else {
+    if (event.type === "assistant") summary = textBlocks(event.message?.content) || summary;
+    if (event.session_id) metadata.sessionId = event.session_id;
+    if (event.type === "result") {
+      summary = event.result ?? summary;
+      metadata = { ...metadata, usage: event.usage, costUSD: event.total_cost_usd, model: Object.keys(event.modelUsage ?? {}).join(", ") };
+      if (event.is_error) failure = summary || "Claude turn failed";
+    }
+  }
+}
+if (!interactive) {
+  child.stdout.on("data", (chunk) => {
+    appendFileSync(join(artifactDir, "events.log"), chunk);
+    process.stdout.write(chunk);
+    pending += decoder.write(chunk);
+    let end;
+    while ((end = pending.indexOf("\n")) !== -1) { onLine(pending.slice(0, end)); pending = pending.slice(end + 1); }
+  });
+  child.stderr.on("data", (chunk) => { stderr = `${stderr}${chunk.toString("utf8")}`.slice(-4000); process.stderr.write(chunk); });
+  child.stdin.on("error", (cause) => { failure = `Prompt delivery failed: ${cause.message}`; });
+  // Pi receives its prompt as a CLI argument; the other CLIs receive exact UTF-8 stdin.
+  child.stdin.end(harness === "pi" ? undefined : config.prompt);
+}
+child.once("error", (cause) => { failure = `Cannot start ${harness}: ${cause.message}`; });
+child.once("close", (code, signal) => {
+  if (!interactive) {
+    pending += decoder.end();
+    if (pending) onLine(pending);
+    if (harness === "opencode" && !openCodeSessionSeen) failure ??= "OpenCode exited without a JSON session ID; inspect events.log for CLI compatibility errors.";
+    writeJson(join(artifactDir, "metadata.json"), metadata);
+    complete(artifactDir, { id: request.id, status: code === 0 && !failure ? "completed" : "failed", summary: summary.trim(), error: failure ?? (code !== 0 ? stderr || `Process exit ${code ?? signal}` : undefined), sessionId: metadata.sessionId });
+  } else {
+    const current = readJson(join(artifactDir, "request.json"));
+    const previous = readJson(join(artifactDir, "completion.json"));
+    if (current && previous?.id !== current.id) complete(artifactDir, { id: current.id, status: "failed", error: failure ?? `TUI exited before settlement (${code ?? signal}).` });
+  }
+  writeJson(join(artifactDir, "state.json"), { status: "exited", code, signal, at: Date.now() });
+  process.exitCode = code ?? 1;
+});

package/turn-hook.mjs

@@ -0,0 +1,29 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { complete, readJson, taskId, writeJson } from "./ipc.mjs";
+
+const [directory, harness, raw] = process.argv.slice(2);
+if (!directory || !["codex", "claude", "claude-start"].includes(harness)) throw new Error("Invalid multi-harness hook arguments.");
+const event = JSON.parse(harness === "codex" ? raw : readFileSync(0, "utf8"));
+const request = readJson(join(directory, "request.json"));
+if (!request) process.exit(0);
+if (harness === "claude-start") {
+  if (event.hook_event_name !== "UserPromptSubmit") process.exit(0);
+  writeJson(join(directory, "state.json"), { status: "running", id: taskId(event.prompt), at: Date.now() });
+  process.exit(0);
+}
+if (harness === "codex" && event.type !== "agent-turn-complete") process.exit(0);
+if (harness === "claude" && event.hook_event_name !== "Stop") process.exit(0);
+const sessionId = event["thread-id"] ?? event.thread_id ?? event.session_id;
+const inputs = event["input-messages"] ?? event.input_messages;
+const state = readJson(join(directory, "state.json"));
+const id = harness === "codex"
+  ? (Array.isArray(inputs) ? inputs.map(taskId).filter(Boolean).at(-1) : request.id)
+  : state?.id;
+if (sessionId) writeJson(join(directory, "metadata.json"), { sessionId, harness });
+if (id !== request.id) {
+  // Manual turns must return to idle too, without completing a coordinator dispatch.
+  writeJson(join(directory, "state.json"), { status: "idle", at: Date.now() });
+  process.exit(0);
+}
+complete(directory, { id, status: "completed", sessionId, summary: event["last-assistant-message"] ?? event.last_assistant_message });

package/worker-bridge.ts

@@ -0,0 +1,52 @@
+import { watch, renameSync, unlinkSync, type FSWatcher } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { complete, readJson, taskId, writeJson } from "./ipc.mjs";
+
+/** Native Pi inbox and settlement events; never shuts down an idle TUI. */
+export default function workerBridge(pi: ExtensionAPI) {
+  const directory = process.env.PI_MULTI_HARNESS_DIR;
+  if (process.env.PI_MULTI_HARNESS_WORKER !== "1" || !directory) return;
+  let watcher: FSWatcher | undefined;
+  let id: string | undefined;
+  let summary = "";
+  let error: string | undefined;
+  const inbox = join(directory, "inbox.json");
+
+  function receive() {
+    let payload: { id?: string; task?: string } | undefined;
+    const processing = `${inbox}.processing`;
+    try {
+      renameSync(inbox, processing);
+      payload = readJson(processing);
+      unlinkSync(processing);
+      if (!payload?.id || !payload.task) throw new Error("Inbox requires id and task.");
+      pi.sendUserMessage(payload.task, { deliverAs: "followUp", expandPromptTemplates: false });
+      writeJson(join(directory, "ack.json"), { id: payload.id, status: "ok" });
+    } catch (cause) {
+      if ((cause as NodeJS.ErrnoException).code === "ENOENT") return;
+      writeJson(join(directory, "ack.json"), { id: payload?.id, status: "error", error: String(cause) });
+    }
+  }
+  pi.on("session_start", () => {
+    watcher = watch(directory, (_event, name) => { if (name?.toString() === "inbox.json") receive(); });
+    watcher.on("error", (cause) => console.error(`Multi-harness inbox watcher failed: ${cause.message}`));
+    receive();
+  });
+  pi.on("before_agent_start", (event) => {
+    id = event.messageType === "user" ? taskId(event.prompt) : undefined;
+    summary = "";
+    error = undefined;
+    writeJson(join(directory, "state.json"), { status: "running", id, at: Date.now() });
+  });
+  pi.on("agent_end", (event) => {
+    const last = event.messages.filter((message) => message.role === "assistant").at(-1);
+    summary = last?.content?.filter((part) => part.type === "text").map((part) => part.text).join("\n") ?? "";
+    error = last?.stopReason === "error" ? last.errorMessage || "Model error" : undefined;
+  });
+  pi.on("agent_settled", (event) => {
+    if (id) complete(directory, { id, status: error || event.aborted ? "failed" : "completed", summary, error: error ?? (event.aborted ? "Turn aborted" : undefined) });
+    else writeJson(join(directory, "state.json"), { status: "idle", at: Date.now() });
+  });
+  pi.on("session_shutdown", () => { watcher?.close(); });
+}