okstra 0.174.0 → 0.176.0

package/src/commands/pr/pr.mjs

@@ -1,261 +0,0 @@
-import { promises as fs } from "node:fs";
-import { execFileSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { dirname, join, resolve } from "node:path";
-import { createInterface } from "node:readline/promises";
-import { stdin as input, stdout as output } from "node:process";
-import { resolveOkstraHome } from "../../lib/paths.mjs";
-
-const NAME_RE = /^[A-Za-z0-9._-]+$/;
-const DEFAULT_TEMPLATE_PATH = join(
-  dirname(fileURLToPath(import.meta.url)),
-  "default.md",
-);
-
-const USAGE = `okstra pr — PR body templates and PR generation
-
-Usage:
-  okstra pr template list [--json]
-  okstra pr template show <name|default> [--json]
-  okstra pr template add --name <name> (--content <text> | --file <path>) [--yes]
-  okstra pr template path
-  okstra pr branches [--json]
-  okstra pr gen --base <ref> [--template <name|default>] [--json]
-`;
-
-export function isValidTemplateName(name) {
-  return (
-    typeof name === "string" &&
-    NAME_RE.test(name) &&
-    name !== "." &&
-    name !== ".."
-  );
-}
-
-export function templateDir(home) {
-  return join(home, "template", "pr");
-}
-
-export async function listTemplates(home) {
-  let entries;
-  try {
-    entries = await fs.readdir(templateDir(home));
-  } catch (err) {
-    if (err.code === "ENOENT") return [];
-    throw err;
-  }
-  return entries
-    .filter((f) => f.endsWith(".md"))
-    .map((f) => f.slice(0, -3))
-    .sort();
-}
-
-async function readBundledDefault() {
-  return fs.readFile(DEFAULT_TEMPLATE_PATH, "utf8");
-}
-
-export async function readTemplate(home, name) {
-  if (!name || name === "default") return readBundledDefault();
-  if (!isValidTemplateName(name)) throw new Error(`invalid template name: ${name}`);
-  try {
-    return await fs.readFile(join(templateDir(home), `${name}.md`), "utf8");
-  } catch (err) {
-    if (err.code === "ENOENT") return readBundledDefault();
-    throw err;
-  }
-}
-
-export async function addTemplate(home, name, content, opts = {}) {
-  if (!isValidTemplateName(name)) throw new Error(`invalid template name: ${name}`);
-  const dir = templateDir(home);
-  await fs.mkdir(dir, { recursive: true });
-  const target = join(dir, `${name}.md`);
-  if (!opts.force) {
-    try {
-      await fs.access(target);
-      throw new Error(`template exists: ${name} (use --yes to overwrite)`);
-    } catch (err) {
-      if (err.code !== "ENOENT") throw err;
-    }
-  }
-  await fs.writeFile(target, content, "utf8");
-  return target;
-}
-
-function takeValue(args, i, flag) {
-  const v = args[i + 1];
-  if (!v || v.startsWith("--")) throw new Error(`${flag} requires a value`);
-  return v;
-}
-
-async function readAddContent(opts) {
-  if (opts.content !== null) return opts.content;
-  if (opts.file !== null) return fs.readFile(resolve(opts.file), "utf8");
-  throw new Error("template add requires --content or --file");
-}
-
-async function confirm(question) {
-  const rl = createInterface({ input, output });
-  try {
-    const answer = (await rl.question(`${question} [y/N] `)).trim().toLowerCase();
-    return answer === "y" || answer === "yes";
-  } finally {
-    rl.close();
-  }
-}
-
-async function cmdTemplate(args, home) {
-  const sub = args[0];
-  const rest = args.slice(1);
-  const json = rest.includes("--json");
-  if (sub === "list") {
-    const names = await listTemplates(home);
-    if (json) output.write(JSON.stringify({ templates: names }) + "\n");
-    else output.write(names.length ? names.join("\n") + "\n" : "(no templates)\n");
-    return 0;
-  }
-  if (sub === "show") {
-    const name = rest.find((a) => !a.startsWith("--"));
-    if (!name) throw new Error("template show requires a name");
-    const body = await readTemplate(home, name);
-    output.write(json ? JSON.stringify({ name, body }) + "\n" : body);
-    return 0;
-  }
-  if (sub === "path") {
-    output.write(templateDir(home) + "\n");
-    return 0;
-  }
-  if (sub === "add") {
-    const opts = { name: null, content: null, file: null, yes: false };
-    for (let i = 0; i < rest.length; i++) {
-      const flag = rest[i];
-      if (flag === "--name") opts.name = takeValue(rest, i++, flag);
-      else if (flag === "--content") opts.content = takeValue(rest, i++, flag);
-      else if (flag === "--file") opts.file = takeValue(rest, i++, flag);
-      else if (flag === "--yes") opts.yes = true;
-      else throw new Error(`unknown flag ${flag}`);
-    }
-    if (!opts.name) throw new Error("template add requires --name");
-    const content = await readAddContent(opts);
-    const dir = templateDir(home);
-    const target = join(dir, `${opts.name}.md`);
-    let force = opts.yes;
-    if (!force && isValidTemplateName(opts.name)) {
-      let exists = false;
-      try {
-        await fs.access(target);
-        exists = true;
-      } catch (err) {
-        if (err.code !== "ENOENT") throw err;
-      }
-      if (exists) {
-        if (!process.stdin.isTTY) {
-          throw new Error(`template exists: ${opts.name} (use --yes to overwrite)`);
-        }
-        force = await confirm(`Overwrite existing template ${opts.name}?`);
-        if (!force) { output.write("aborted\n"); return 1; }
-      }
-    }
-    const saved = await addTemplate(home, opts.name, content, { force: true });
-    output.write(`saved: ${saved}\n`);
-    return 0;
-  }
-  throw new Error(`unknown template subcommand: ${sub ?? "(none)"}`);
-}
-
-function tryGit(cwd, args) {
-  try {
-    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
-  } catch {
-    return null;
-  }
-}
-
-export function recommendBranches(cwd) {
-  const currentBranch = tryGit(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
-  if (currentBranch === null) return { currentBranch: null, recommended: [] };
-  const ordered = [];
-  const remoteDefault = tryGit(cwd, ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]);
-  if (remoteDefault) {
-    const bare = remoteDefault.replace(/^origin\//, "");
-    if (tryGit(cwd, ["rev-parse", "--verify", "--quiet", `${bare}^{commit}`]) !== null) ordered.push(bare);
-    else if (tryGit(cwd, ["rev-parse", "--verify", "--quiet", `${remoteDefault}^{commit}`]) !== null) ordered.push(remoteDefault);
-  }
-  for (const b of ["main", "master", "develop"]) {
-    const local = tryGit(cwd, ["show-ref", "--verify", "--quiet", `refs/heads/${b}`]);
-    if (local !== null) ordered.push(b);
-  }
-  const recent = tryGit(cwd, [
-    "for-each-ref", "--sort=-committerdate", "--format=%(refname:short)", "refs/heads",
-  ]);
-  if (recent) ordered.push(...recent.split("\n").filter(Boolean));
-  const recommended = [];
-  for (const b of ordered) {
-    if (b && b !== currentBranch && !recommended.includes(b)) recommended.push(b);
-  }
-  return { currentBranch, recommended };
-}
-
-function cmdBranches(args, cwd) {
-  const json = args.includes("--json");
-  const r = recommendBranches(cwd);
-  if (json) output.write(JSON.stringify(r) + "\n");
-  else output.write((r.recommended.join("\n") || "(no branches)") + "\n");
-  return 0;
-}
-
-export async function buildGenBundle({ cwd, home, base, templateName }) {
-  if (!base) throw new Error("gen requires --base");
-  const verified = tryGit(cwd, ["rev-parse", "--verify", "--quiet", `${base}^{commit}`]);
-  if (verified === null) throw new Error(`base ref not found: ${base}`);
-  const currentBranch = tryGit(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
-  const logRaw = tryGit(cwd, [
-    "log", "--reverse", "--format=%h%x09%s", `${base}..HEAD`,
-  ]) || "";
-  const commits = logRaw
-    .split("\n")
-    .filter(Boolean)
-    .map((line) => {
-      const tab = line.indexOf("\t");
-      return { hash: line.slice(0, tab), subject: line.slice(tab + 1) };
-    });
-  const diffStat = tryGit(cwd, ["diff", "--stat", `${base}...HEAD`]) || "";
-  const template = await readTemplate(home, templateName);
-  const resolvedName = templateName && templateName !== "default"
-    ? templateName
-    : "default";
-  return { base, currentBranch, templateName: resolvedName, template, commits, diffStat };
-}
-
-async function cmdGen(args, cwd, home) {
-  const opts = { base: null, template: "default" };
-  for (let i = 0; i < args.length; i++) {
-    const flag = args[i];
-    if (flag === "--base") opts.base = takeValue(args, i++, flag);
-    else if (flag === "--template") opts.template = takeValue(args, i++, flag);
-    else if (flag === "--json") continue;
-    else throw new Error(`unknown flag ${flag}`);
-  }
-  const bundle = await buildGenBundle({ cwd, home, base: opts.base, templateName: opts.template });
-  output.write(JSON.stringify(bundle) + "\n");
-  return 0;
-}
-
-export async function run(args) {
-  if (args.length === 0 || args.includes("--help")) {
-    output.write(USAGE);
-    return 0;
-  }
-  const home = resolveOkstraHome();
-  const sub = args[0];
-  const rest = args.slice(1);
-  try {
-    if (sub === "template") return await cmdTemplate(rest, home);
-    if (sub === "branches") return cmdBranches(rest, process.cwd());
-    if (sub === "gen") return await cmdGen(rest, process.cwd(), home);
-    throw new Error(`unknown pr subcommand: ${sub}`);
-  } catch (err) {
-    process.stderr.write(`error: ${err.message}\n`);
-    return 1;
-  }
-}

package/src/lib/host-registry-client.mjs

@@ -1,176 +0,0 @@
-import { homedir } from "node:os";
-
-import { runPythonModule } from "./python-helper.mjs";
-
-export const RUNTIME_AUTO = "auto";
-
-const HOST_REQUEST_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
-const PLAIN_TEXT_INPUT = "plain_text_input";
-
-export class HostRegistryClientError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "HostRegistryClientError";
-  }
-}
-
-async function callHosts(runPython, args) {
-  const result = await runPython({
-    module: "okstra_ctl.entrypoints.hosts",
-    args,
-    stdio: "capture",
-  });
-  if (result.code !== 0) {
-    const detail = String(result.stderr || "").trim() || `Python exited ${result.code}`;
-    throw new HostRegistryClientError(detail);
-  }
-  const stdout = String(result.stdout || "").trim();
-  if (!stdout) throw new HostRegistryClientError("host registry returned empty stdout");
-  try {
-    return JSON.parse(stdout);
-  } catch (error) {
-    throw new HostRegistryClientError(`host registry returned invalid JSON: ${error.message}`);
-  }
-}
-
-function resolutionContext(env = {}, capabilities = {}) {
-  return {
-    env: { OKSTRA_RUNTIME_HOST: String(env?.OKSTRA_RUNTIME_HOST ?? "") },
-    capabilities: {
-      claudeSkillHandoff: capabilities?.claudeSkillHandoff === true,
-      tmuxAvailable: capabilities?.tmuxAvailable === true,
-    },
-  };
-}
-
-export function createHostRegistryClient({ runPython = runPythonModule } = {}) {
-  return {
-    async catalog() {
-      return await callHosts(runPython, ["catalog", "--json"]);
-    },
-    async resolveHostRuntime({ requestedRuntime, command, env, capabilities }) {
-      return await callHosts(runPython, [
-        "resolve",
-        "--requested", requestedRuntime,
-        "--command", command,
-        "--context-json", JSON.stringify(resolutionContext(env, capabilities)),
-      ]);
-    },
-    async probeHost({
-      hostRuntime,
-      entryMode,
-      projectRoot,
-      homeDir,
-      availableFunctions = [],
-    }) {
-      const args = [
-        "probe",
-        "--host", hostRuntime,
-        "--entry-mode", entryMode,
-        "--project-root", projectRoot,
-        "--home-dir", homeDir,
-      ];
-      for (const availableFunction of availableFunctions) {
-        args.push("--available-function", availableFunction);
-      }
-      return await callHosts(runPython, args);
-    },
-  };
-}
-
-const hostRegistryClient = createHostRegistryClient();
-
-export function normalizeHostRequest(value) {
-  const runtime = String(value ?? "").trim() || RUNTIME_AUTO;
-  if (!HOST_REQUEST_PATTERN.test(runtime)) {
-    throw new Error(
-      `invalid runtime '${runtime}' (expected auto, all, or a lowercase host ID)`,
-    );
-  }
-  return runtime;
-}
-
-function failedResolution(requestedRuntime, error) {
-  return {
-    ok: false,
-    requestedRuntime,
-    resolvedRuntime: null,
-    launchMode: null,
-    installTargets: [],
-    host: "unknown",
-    confidence: "low",
-    reason: error.message,
-    fallbackFrom: null,
-    warnings: [],
-  };
-}
-
-function catalogResolution(catalog) {
-  const hosts = Array.isArray(catalog?.hosts) ? catalog.hosts : [];
-  const catalogHostIds = hosts.map((host) => host.id);
-  const installTargets = Array.from(new Set(
-    hosts.flatMap((host) => host.install_targets ?? host.installTargets ?? []),
-  )).sort();
-  return {
-    ok: true,
-    requestedRuntime: "all",
-    resolvedRuntime: "all",
-    launchMode: "catalog",
-    installTargets,
-    catalogHostIds,
-    host: "explicit",
-    confidence: "high",
-    reason: "All registered host runtimes requested.",
-    fallbackFrom: null,
-    warnings: [],
-  };
-}
-
-export async function loadHostCatalog() {
-  return await hostRegistryClient.catalog();
-}
-
-export async function resolveHostRuntime(options) {
-  return await hostRegistryClient.resolveHostRuntime(options);
-}
-
-export async function probeHost(options) {
-  return await hostRegistryClient.probeHost(options);
-}
-
-export async function resolveRuntime({
-  requestedRuntime = RUNTIME_AUTO,
-  command = "run",
-  env = {},
-  capabilities = {},
-} = {}) {
-  const request = normalizeHostRequest(requestedRuntime);
-  try {
-    if (request === "all") return catalogResolution(await loadHostCatalog());
-    return await resolveHostRuntime({
-      requestedRuntime: request,
-      command,
-      env,
-      capabilities,
-    });
-  } catch (error) {
-    if (!(error instanceof HostRegistryClientError)) throw error;
-    return failedResolution(request, error);
-  }
-}
-
-export async function checkRuntimeReadiness({
-  runtime,
-  projectRoot,
-  homeDir = homedir(),
-  hostRegistryClient = { probeHost },
-}) {
-  if (!runtime) return { runtime: "auto", status: "ready", checks: [] };
-  return await hostRegistryClient.probeHost({
-    hostRuntime: runtime,
-    entryMode: "current-session",
-    projectRoot,
-    homeDir,
-    availableFunctions: [PLAIN_TEXT_INPUT],
-  });
-}

package/src/lib/paths.mjs

@@ -1,86 +0,0 @@
-import { homedir, tmpdir } from "node:os";
-import { join } from "node:path";
-import { existsSync } from "node:fs";
-import { getPackageRoot, getPackageVersion } from "./version.mjs";
-
-function isStaleTmpHome(p) {
-  // tests/conftest.py creates the isolated home as `<tmp_path>/.okstra-isolated`
-  // under the system temp dir. Only a deleted one (env leaked, dir gone) heals;
-  // a soon-to-be-created `.okstra` temp home or a custom home is left untouched.
-  if (!p.endsWith("/.okstra-isolated")) return false;
-  const roots = [tmpdir(), "/tmp", "/private/tmp", "/var/folders", "/private/var/folders"];
-  return roots.some(
-    (r) => r && (p === r || p.startsWith(r.replace(/\/+$/, "") + "/")),
-  );
-}
-
-// Resolve OKSTRA_HOME, healing a leaked value: when it points at a missing
-// system-temp path (e.g. a deleted pytest-isolated home), warn and fall back
-// to ~/.okstra instead of operating on the dead directory.
-export function resolveOkstraHome() {
-  const raw = process.env.OKSTRA_HOME?.trim();
-  if (!raw) return join(homedir(), ".okstra");
-  if (!existsSync(raw) && isStaleTmpHome(raw)) {
-    process.stderr.write(
-      `⚠ OKSTRA_HOME=${raw} points to a missing temp dir (leaked test value); falling back to ~/.okstra\n`,
-    );
-    return join(homedir(), ".okstra");
-  }
-  return raw;
-}
-
-export async function resolvePaths() {
-  const home = resolveOkstraHome();
-  const pkgRoot = getPackageRoot();
-  const devLink = await readSimpleFile(join(home, "dev-link"));
-  const runtimeRoot = devLink || join(pkgRoot, "runtime");
-  return {
-    agents: join(runtimeRoot, "agents"),
-    workspace: runtimeRoot,
-    pythonpath: join(home, "lib", "python"),
-    bin: join(home, "bin"),
-    home,
-    package: await getPackageVersion(),
-    version: await readSimpleFile(join(home, "version")),
-    "dev-link": devLink || "",
-  };
-}
-
-function workspacePythonpath(paths) {
-  const candidates = [
-    join(paths.workspace, "python"),
-    join(paths.workspace, "scripts"),
-  ];
-  return candidates.find((candidate) => existsSync(candidate)) || "";
-}
-
-// Compose the PYTHONPATH spawned python3 subprocesses should see.
-//
-// Precedence (first wins):
-//   1. process.env.PYTHONPATH (user override — e.g. in-repo `PYTHONPATH=scripts`
-//      for dev work without re-running `okstra install`).
-//   2. The package/dev-link workspace runtime selected by `okstra paths`.
-//   3. The installed user-runtime path (~/.okstra/lib/python).
-//
-// This is a colon-joined string suitable for direct assignment into the child
-// process env. Empty segments are dropped so a missing env var does not produce
-// a leading ':' (which Python treats as 'current directory').
-export function buildPythonpath(paths) {
-  const fragments = [
-    process.env.PYTHONPATH,
-    workspacePythonpath(paths),
-    paths.pythonpath,
-  ].filter(
-    (s) => typeof s === "string" && s.length > 0,
-  );
-  return fragments.join(":");
-}
-
-async function readSimpleFile(path) {
-  try {
-    const { readFile } = await import("node:fs/promises");
-    return (await readFile(path, "utf8")).trim();
-  } catch {
-    return "";
-  }
-}

package/src/lib/proc.mjs

@@ -1,31 +0,0 @@
-// Shared filesystem / subprocess helpers used by the Node command modules.
-// Extracted to one place so a fix lands once instead of in each command file.
-import { spawn } from "node:child_process";
-import { promises as fs } from "node:fs";
-
-export async function fileExists(p) {
-  try {
-    await fs.access(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-// Run `cmd args`, capturing stdout/stderr. `env` holds *additional* vars that
-// are merged over the inherited process.env. Never rejects — failures resolve
-// with { code: -1, stderr: <message> }.
-export function runProcess(cmd, args, env = {}) {
-  return new Promise((resolve) => {
-    const child = spawn(cmd, args, {
-      stdio: ["ignore", "pipe", "pipe"],
-      env: { ...process.env, ...env },
-    });
-    let stdout = "";
-    let stderr = "";
-    child.stdout.on("data", (b) => (stdout += b.toString()));
-    child.stderr.on("data", (b) => (stderr += b.toString()));
-    child.on("error", (err) => resolve({ code: -1, stdout, stderr: err.message }));
-    child.on("close", (code) => resolve({ code, stdout, stderr }));
-  });
-}

package/src/lib/python-helper.mjs

@@ -1,142 +0,0 @@
-import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
-import { join, resolve as resolvePath } from "node:path";
-import { fileURLToPath } from "node:url";
-import { buildPythonpath, resolvePaths } from "./paths.mjs";
-
-export function resolveInstalledScript(paths, scriptName) {
-  // Prefer the installed copy under ~/.okstra/bin (what production users run);
-  // fall back to the in-repo source when invoked from a checkout that has not
-  // been installed (dev / CI).
-  const installed = join(paths.bin, scriptName);
-  if (existsSync(installed)) return installed;
-  const repoRoot = fileURLToPath(new URL("../..", import.meta.url));
-  const dev = resolvePath(repoRoot, "scripts", scriptName);
-  return existsSync(dev) ? dev : null;
-}
-
-export function resolveInstalledValidator(paths, validatorName) {
-  // `okstra install` lands the validators tree at ~/.okstra/lib/validators;
-  // a checkout that has not been installed still has the in-repo source.
-  const installed = join(paths.home, "lib", "validators", validatorName);
-  if (existsSync(installed)) return installed;
-  const repoRoot = fileURLToPath(new URL("../..", import.meta.url));
-  const dev = resolvePath(repoRoot, "validators", validatorName);
-  return existsSync(dev) ? dev : null;
-}
-
-async function spawnPythonEntry(entry, args, paths) {
-  return await new Promise((resolve) => {
-    const child = spawn("python3", [entry, ...args], {
-      stdio: "inherit",
-      env: { ...process.env, PYTHONPATH: buildPythonpath(paths) },
-    });
-    child.on("error", (err) => {
-      process.stderr.write(`error: failed to spawn python3: ${err.message}\n`);
-      resolve(1);
-    });
-    child.on("close", (code) => resolve(typeof code === "number" ? code : 1));
-  });
-}
-
-// Thin spawn shim shared by every `okstra <cmd>` subcommand that fronts a
-// `scripts/okstra-*.py` entry point. Centralizing it keeps PYTHONPATH wiring
-// and installed/dev resolution in one place so skills call `okstra <cmd>`
-// instead of emitting `python3 "$HOME/..."` (which breaks `Bash(okstra:*)`
-// permission matching and prompts on every call).
-export async function runInstalledScript({ scriptName, args, usage, emptyArgsCode = 2 }) {
-  if (args.length === 0) {
-    process.stdout.write(usage);
-    return emptyArgsCode;
-  }
-  // Only a bare `--help` / `-h` prints the wrapper usage. A `--help` that
-  // follows a subcommand (e.g. `error-log append-observed --help`) must reach
-  // the python helper so its own per-subcommand help shows through.
-  if (args.length === 1 && (args[0] === "--help" || args[0] === "-h")) {
-    process.stdout.write(usage);
-    return 0;
-  }
-  const paths = await resolvePaths();
-  const entry = resolveInstalledScript(paths, scriptName);
-  if (!entry) {
-    process.stderr.write(
-      `error: ${scriptName} not found — run 'okstra install' (or 'okstra ensure-installed') first\n`,
-    );
-    return 1;
-  }
-  return await spawnPythonEntry(entry, args, paths);
-}
-
-export async function runInstalledValidator({ validatorName, args }) {
-  const paths = await resolvePaths();
-  const entry = resolveInstalledValidator(paths, validatorName);
-  if (!entry) {
-    process.stderr.write(
-      `error: ${validatorName} not found — run 'okstra install' (or 'okstra ensure-installed') first\n`,
-    );
-    return 1;
-  }
-  return await spawnPythonEntry(entry, args, paths);
-}
-
-export async function runPythonSnippet({ script, args = [], extraEnv = {} }) {
-  const paths = await resolvePaths();
-  return new Promise((resolve) => {
-    const child = spawn("python3", ["-c", script, ...args], {
-      stdio: ["ignore", "pipe", "pipe"],
-      env: { ...process.env, PYTHONPATH: buildPythonpath(paths), ...extraEnv },
-    });
-    // Collect chunks and join once: repeated `s += chunk` is O(n^2) for the
-    // large rendered prompts some capture-mode callers stream through here.
-    const outChunks = [];
-    const errChunks = [];
-    child.stdout.on("data", (b) => outChunks.push(b));
-    child.stderr.on("data", (b) => errChunks.push(b));
-    child.on("error", (err) =>
-      resolve({ code: -1, stdout: Buffer.concat(outChunks).toString(), stderr: err.message }),
-    );
-    child.on("close", (code) =>
-      resolve({
-        code,
-        stdout: Buffer.concat(outChunks).toString(),
-        stderr: Buffer.concat(errChunks).toString(),
-      }),
-    );
-  });
-}
-
-export async function runPythonModule({ module, args = [], extraEnv = {}, stdio = "inherit-stdout" }) {
-  const paths = await resolvePaths();
-  return new Promise((resolve) => {
-    const child = spawn("python3", ["-m", module, ...args], {
-      stdio: stdio === "capture" ? ["ignore", "pipe", "pipe"] : ["ignore", "inherit", "inherit"],
-      env: { ...process.env, PYTHONPATH: buildPythonpath(paths), ...extraEnv },
-    });
-    // Collect chunks and join once: repeated `s += chunk` is O(n^2) for the
-    // large rendered prompts some capture-mode callers stream through here.
-    const outChunks = [];
-    const errChunks = [];
-    if (stdio === "capture") {
-      child.stdout.on("data", (b) => outChunks.push(b));
-      child.stderr.on("data", (b) => errChunks.push(b));
-    }
-    child.on("error", (err) =>
-      resolve({ code: -1, stdout: Buffer.concat(outChunks).toString(), stderr: err.message }),
-    );
-    // A signal-killed child reports code === null; normalize to a non-zero exit
-    // here so every consumer inherits correct failure semantics from one place.
-    child.on("close", (code) =>
-      resolve({
-        code: typeof code === "number" ? code : 1,
-        stdout: Buffer.concat(outChunks).toString(),
-        stderr: Buffer.concat(errChunks).toString(),
-      }),
-    );
-  });
-}
-
-export function emitJsonError({ stage, reason, extra = {} }) {
-  process.stdout.write(
-    JSON.stringify({ ok: false, stage, reason, ...extra }, null, 2) + "\n",
-  );
-}