glm-coding-router 0.2.0 → 0.4.0

package/dist/cli.js

@@ -13,6 +13,8 @@ import { projectInitCommand } from "./commands/project-init.js";
 import { projectRemoveCommand } from "./commands/project-remove.js";
 import { skillInstallCommand, skillRemoveCommand } from "./commands/skill.js";
 import { uninstallCommand } from "./commands/uninstall.js";
+import { delegateCommand } from "./commands/delegate.js";
+import { benchmarkCommand } from "./commands/benchmark.js";
 const program = new Command();
 program
     .name("glm-router")
@@ -87,6 +89,20 @@ skill
     .command("remove")
     .description("remove the glm-delegation skill")
     .action(() => execute(() => Promise.resolve(skillRemoveCommand(globalOptions()))));
+program
+    .command("delegate <name> [prompt...]")
+    .description("run a GLM worker in an isolated git worktree (branch glm/delegate/<name>)")
+    .option("--profile <name>", "profile overlay (defaults to a profile named <name> if defined)")
+    .option("--remove", "remove the worktree after a successful run (branch is always kept)")
+    .action((name, prompt, commandOptions) => execute(() => delegateCommand(name, prompt, { ...globalOptions(), ...commandOptions })));
+program
+    .command("benchmark")
+    .description("measure the Claude+GLM stack on built-in coding tasks (makes real GLM calls)")
+    .option("--task <id>", "run only this task (repeatable)", (value, previous) => previous.concat([value]), [])
+    .option("--stack <name>", "orchestration stack (default claude; codex not yet supported)")
+    .option("--max-turns <n>", "worker --max-turns override", (value) => Number(value))
+    .option("--repeat <n>", "run each task N times", (value) => Number(value))
+    .action((commandOptions) => execute(() => benchmarkCommand({ ...globalOptions(), ...commandOptions })));
 program
     .command("uninstall")
     .description("guided removal (keeps ZAI_API_KEY by default)")

package/dist/commands/benchmark.js

@@ -0,0 +1,252 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import prompts from "prompts";
+import { version } from "../core/version.js";
+import { WORKER_TOOLS } from "../bin/glm-worker.js";
+import { loadConfig } from "../core/config.js";
+import { locateClaude } from "../core/claude.js";
+import { createGlmEnv } from "../core/env.js";
+import { Errors } from "../core/errors.js";
+import { configDir } from "../core/paths.js";
+import { spawnAgentCapture } from "../core/process.js";
+import { resolveZaiApiKey } from "../core/zai-key.js";
+import { BENCHMARK_TASKS, benchmarkTaskById } from "../templates/benchmark-tasks.js";
+import { emitJson } from "./context.js";
+const KNOWN_STACKS = ["claude", "codex"];
+/**
+ * glm-router benchmark (spec §54 v0.4, specs/benchmark.md): run built-in
+ * coding tasks through the Claude+GLM worker path and report §54 metrics.
+ * Failed tasks are measurements, not CLI errors — exits 0 once the suite ran.
+ */
+export async function benchmarkCommand(options, deps = {}) {
+    const stack = options.stack ?? "claude";
+    if (stack === "codex") {
+        throw Errors.invalidArgs("The codex stack is not supported yet: headless Codex orchestration cannot be driven reliably today.", ["v0.4 ships the harness + claude stack; codex slots in later without redesign."]);
+    }
+    if (!KNOWN_STACKS.includes(stack)) {
+        throw Errors.invalidArgs(`Unknown stack "${stack}".`, [`Known stacks: ${KNOWN_STACKS.join(", ")}`]);
+    }
+    const ids = options.task && options.task.length > 0 ? options.task : BENCHMARK_TASKS.map((t) => t.id);
+    const unknown = ids.filter((id) => !benchmarkTaskById(id));
+    if (unknown.length > 0) {
+        throw Errors.invalidArgs(`Unknown task id(s): ${unknown.join(", ")}.`, [`Available tasks: ${BENCHMARK_TASKS.map((t) => t.id).join(", ")}`]);
+    }
+    const tasks = ids.map((id) => benchmarkTaskById(id));
+    const repeat = options.repeat ?? 1;
+    const maxTurns = options.maxTurns;
+    if (!Number.isInteger(repeat) || repeat < 1) {
+        throw Errors.invalidArgs(`--repeat expects a positive integer, got "${repeat}".`);
+    }
+    if (maxTurns !== undefined && (!Number.isInteger(maxTurns) || maxTurns < 1)) {
+        throw Errors.invalidArgs(`--max-turns expects a positive integer, got "${maxTurns}".`);
+    }
+    if (options.dryRun) {
+        if (options.json) {
+            emitJson({ stack, tasks: ids, repeat, maxTurns: maxTurns ?? "(config default)", dryRun: true });
+        }
+        else {
+            const lines = [
+                `would run stack   ${stack}`,
+                `would run tasks   ${ids.join(", ")}`,
+                `would repeat      ${repeat}x`,
+                `would use maxTurns ${maxTurns ?? "(config default)"}`,
+            ];
+            process.stdout.write(lines.join("\n") + "\n");
+        }
+        return 0;
+    }
+    const interactive = deps.interactive ?? process.stdin.isTTY === true;
+    if (!options.yes) {
+        if (!interactive) {
+            throw Errors.invalidArgs(`benchmark makes real GLM API calls; confirm with --yes when running non-interactively.`, [`  glm-router benchmark --yes`]);
+        }
+        const confirm = deps.confirm ?? defaultConfirm;
+        const ok = await confirm();
+        if (!ok) {
+            process.stdout.write("Cancelled.\n");
+            return 1;
+        }
+    }
+    const home = deps.home ?? os.homedir();
+    const env = deps.env ?? process.env;
+    const config = loadConfig(home);
+    const resolved = resolveZaiApiKey({ env, readUserEnv: deps.readUserEnv });
+    if (!resolved) {
+        throw Errors.zaiKeyMissing();
+    }
+    const claudePath = locateClaude(config, env);
+    const turns = maxTurns ?? config.worker.maxTurns;
+    const now = deps.now ?? Date.now;
+    const mkdtemp = deps.mkdtemp ?? (() => fs.mkdtempSync(path.join(os.tmpdir(), "glm-benchmark-")));
+    const spawn = deps.spawn ?? spawnAgentCapture;
+    const startedAt = new Date(now()).toISOString();
+    const metrics = [];
+    for (const task of tasks) {
+        for (let run = 1; run <= repeat; run++) {
+            metrics.push(await runTask(task, run, { turns, claudePath, config, key: resolved.key, env, now, mkdtemp, spawn }));
+        }
+    }
+    const report = {
+        version,
+        stack,
+        startedAt,
+        finishedAt: new Date(now()).toISOString(),
+        maxTurns: turns,
+        repeat,
+        tasks: metrics,
+    };
+    const savedPath = saveReport(report, home);
+    if (!options.quiet && !options.json) {
+        process.stdout.write(`report saved to ${savedPath}\n`);
+    }
+    if (options.json) {
+        emitJson({ ...report, savedPath });
+    }
+    else {
+        renderTable(metrics, options);
+    }
+    return 0;
+}
+async function runTask(task, run, ctx) {
+    const dir = ctx.mkdtemp();
+    try {
+        for (const [relative, content] of Object.entries(task.files)) {
+            const file = path.join(dir, relative);
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(file, content, "utf8");
+        }
+        const args = [
+            "-p",
+            task.prompt,
+            "--max-turns",
+            String(ctx.turns),
+            "--permission-mode",
+            "acceptEdits",
+            "--tools",
+            WORKER_TOOLS,
+            "--output-format",
+            "json",
+        ];
+        const childEnv = createGlmEnv(ctx.config, ctx.key, ctx.env);
+        const started = ctx.now();
+        let captured;
+        try {
+            captured = await ctx.spawn(ctx.claudePath, { args, cwd: dir, env: childEnv, interactive: false });
+        }
+        catch (error) {
+            throw Errors.childAgentFailed(error instanceof Error ? error.message : String(error));
+        }
+        const durationMs = ctx.now() - started;
+        const parsed = parseClaudeResult(captured.stdout);
+        const validation = await runValidation(task.validate, dir);
+        const selfCompleted = captured.code === 0 && parsed?.isError !== true && !isErrorSubtype(parsed?.subtype);
+        const success = selfCompleted && validation.pass;
+        return {
+            task: task.id,
+            run,
+            durationMs,
+            childDurationMs: parsed?.durationMs ?? null,
+            workerExit: captured.code,
+            glmCalls: parsed?.numTurns ?? null,
+            inputTokens: parsed?.usage?.input_tokens ?? null,
+            outputTokens: parsed?.usage?.output_tokens ?? null,
+            subtype: parsed?.subtype ?? null,
+            testsPass: validation.pass,
+            testsOutput: validation.output,
+            success,
+            interventionNeeded: !selfCompleted,
+            resultParsed: parsed !== null,
+        };
+    }
+    finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}
+/** Parse the child's `--output-format json` result document (last JSON line wins). */
+export function parseClaudeResult(stdout) {
+    const lines = stdout.split(/\r?\n/).filter((line) => line.trim().length > 0);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        try {
+            const parsed = JSON.parse(lines[i]);
+            if (typeof parsed === "object" && parsed !== null) {
+                return {
+                    subtype: typeof parsed.subtype === "string" ? parsed.subtype : undefined,
+                    isError: typeof parsed.is_error === "boolean" ? parsed.is_error : undefined,
+                    numTurns: typeof parsed.num_turns === "number" ? parsed.num_turns : undefined,
+                    durationMs: typeof parsed.duration_ms === "number" ? parsed.duration_ms : undefined,
+                    usage: typeof parsed.usage === "object" && parsed.usage !== null
+                        ? {
+                            input_tokens: numberOrUndefined(parsed.usage.input_tokens),
+                            output_tokens: numberOrUndefined(parsed.usage.output_tokens),
+                        }
+                        : undefined,
+                };
+            }
+        }
+        catch {
+            // Not JSON — keep walking backwards.
+        }
+    }
+    return null;
+}
+function numberOrUndefined(value) {
+    return typeof value === "number" ? value : undefined;
+}
+function isErrorSubtype(subtype) {
+    return subtype !== undefined && subtype.startsWith("error");
+}
+async function runValidation(argv, cwd) {
+    const [bin, ...rest] = argv;
+    return new Promise((resolve) => {
+        execFile(bin, rest, { cwd, windowsHide: true, encoding: "utf8", timeout: 30_000 }, (error, stdout, stderr) => {
+            const output = `${stdout}${stderr}`.trim();
+            resolve({ pass: !error, output: output.length > 0 ? output.slice(-400) : "(no output)" });
+        });
+    });
+}
+function saveReport(report, home) {
+    const dir = path.join(configDir(home), "benchmarks");
+    fs.mkdirSync(dir, { recursive: true });
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const file = path.join(dir, `benchmark-${stamp}.json`);
+    const tmp = `${file}.tmp-${process.pid}`;
+    fs.writeFileSync(tmp, JSON.stringify(report, null, 2) + "\n", "utf8");
+    fs.renameSync(tmp, file);
+    return file;
+}
+function renderTable(metrics, options) {
+    if (options.quiet)
+        return;
+    const header = ["task", "run", "duration", "GLM calls", "retries", "tokens i/o", "tests", "success", "intervention"];
+    const rows = metrics.map((m) => [
+        m.task,
+        String(m.run),
+        formatMs(m.durationMs),
+        m.glmCalls === null ? "-" : String(m.glmCalls),
+        "-", // retry count: not exposed by Claude Code (specs/benchmark.md)
+        m.inputTokens === null || m.outputTokens === null ? "-" : `${m.inputTokens}/${m.outputTokens}`,
+        m.testsPass ? "PASS" : "FAIL",
+        m.success ? "yes" : "no",
+        m.interventionNeeded ? "needed" : "none",
+    ]);
+    const widths = header.map((_, column) => Math.max(header[column].length, ...rows.map((row) => row[column].length)));
+    const line = (cells) => cells.map((cell, column) => cell.padEnd(widths[column])).join("  ");
+    process.stdout.write([line(header), ...rows.map(line)].join("\n") + "\n");
+    for (const m of metrics.filter((m) => !m.testsPass)) {
+        process.stdout.write(`\n${m.task} (run ${m.run}) validation output:\n${m.testsOutput}\n`);
+    }
+}
+function formatMs(ms) {
+    return ms >= 10_000 ? `${(ms / 1000).toFixed(1)}s` : `${Math.round(ms / 100) / 10}s`;
+}
+async function defaultConfirm() {
+    const response = await prompts({
+        type: "confirm",
+        name: "ok",
+        message: "Benchmark will make real GLM API calls. Continue?",
+        initial: false,
+    });
+    return response.ok === true;
+}

package/dist/commands/delegate.js

@@ -0,0 +1,134 @@
+import os from "node:os";
+import { loadConfig } from "../core/config.js";
+import { locateClaude } from "../core/claude.js";
+import { createGlmEnv } from "../core/env.js";
+import { Errors } from "../core/errors.js";
+import { gitTopLevel } from "../core/git.js";
+import { logger, redact } from "../core/logging.js";
+import { spawnAgent } from "../core/process.js";
+import { applyProfile } from "../core/profile.js";
+import { readStdin, resolvePrompt } from "../core/prompt.js";
+import { resolveZaiApiKey } from "../core/zai-key.js";
+import { createDelegateWorktree, delegateBranch, delegateWorktreePath, removeDelegateWorktree, rollbackDelegateBranch, validateDelegateName, } from "../core/worktree.js";
+import { buildWorkerArgs } from "../bin/glm-worker.js";
+import { emitJson } from "./context.js";
+/** A profile literally named after the delegate applies unless --profile says otherwise. */
+function resolveProfileName(name, options, config) {
+    if (options.profile) {
+        return options.profile;
+    }
+    return config.profiles[name] ? name : undefined;
+}
+function banner(text, quiet) {
+    if (!quiet) {
+        process.stdout.write(`${text}\n`);
+    }
+}
+/**
+ * glm-router delegate (spec §54 v0.3, specs/delegate-worktrees.md): run a GLM
+ * worker in an isolated git worktree. Worktree + branch are kept after the run
+ * (no automatic git commits); --remove drops the worktree after success only.
+ */
+export async function delegateCommand(name, promptArgs, options, deps = {}) {
+    validateDelegateName(name);
+    const cwd = deps.cwd ?? process.cwd();
+    const env = deps.env ?? process.env;
+    const runGit = deps.runGit;
+    const repoRoot = await gitTopLevel(cwd, runGit);
+    if (!repoRoot) {
+        throw Errors.gitRepoRequired(cwd);
+    }
+    const home = deps.home ?? os.homedir();
+    const baseConfig = loadConfig(home);
+    const profileName = resolveProfileName(name, options, baseConfig);
+    const config = applyProfile(baseConfig, profileName);
+    const resolved = resolveZaiApiKey({ env, readUserEnv: deps.readUserEnv });
+    if (!resolved) {
+        throw Errors.zaiKeyMissing();
+    }
+    const claudePath = locateClaude(config, env);
+    const prompt = await resolvePrompt(promptArgs, deps.readStdinFn ?? readStdin, "glm-router delegate");
+    const branch = delegateBranch(name);
+    const worktreePath = delegateWorktreePath(repoRoot, name);
+    if (options.dryRun) {
+        if (options.json) {
+            emitJson({ name, profile: profileName ?? null, worktree: worktreePath, branch, dryRun: true });
+        }
+        else {
+            banner(`would create worktree ${worktreePath}`, options.quiet);
+            banner(`would create branch   ${branch} (from HEAD)`, options.quiet);
+            banner(`would run glm-worker in the worktree with the given prompt`, options.quiet);
+        }
+        return 0;
+    }
+    // Collision checks run inside createDelegateWorktree before anything is written.
+    const createdPath = await createDelegateWorktree(repoRoot, name, { runGit });
+    if (options.json) {
+        emitJson({ name, profile: profileName ?? null, worktree: createdPath, branch });
+    }
+    else {
+        banner(`[glm-router] delegate ${name}`, options.quiet);
+        banner(`[glm-router] worktree ${createdPath}`, options.quiet);
+        banner(`[glm-router] branch   ${branch}`, options.quiet);
+        if (profileName) {
+            banner(`[glm-router] profile  ${profileName}`, options.quiet);
+        }
+    }
+    const args = buildWorkerArgs(prompt, config);
+    const childEnv = createGlmEnv(config, resolved.key, env);
+    logger.debug(redact(`spawning ${claudePath} in ${createdPath}`, [resolved.key]));
+    const spawn = deps.spawn ?? ((binPath, spawnOptions) => spawnAgent(binPath, {
+        args: [...spawnOptions.args],
+        cwd: spawnOptions.cwd,
+        env: spawnOptions.env,
+        interactive: false,
+    }));
+    let exitCode;
+    try {
+        exitCode = await spawn(claudePath, { args, cwd: createdPath, env: childEnv, interactive: false });
+    }
+    catch (error) {
+        // Worker never started: roll back the pristine worktree and its branch so
+        // the same delegate name can simply be re-run.
+        const worktreeComplaint = await removeDelegateWorktree(repoRoot, createdPath, { runGit });
+        if (worktreeComplaint) {
+            logger.debug(`worktree kept after spawn failure: ${worktreeComplaint}`);
+        }
+        const branchComplaint = await rollbackDelegateBranch(repoRoot, branch, { runGit });
+        if (branchComplaint) {
+            logger.debug(`branch kept after spawn failure: ${branchComplaint}`);
+        }
+        throw error;
+    }
+    let removed = false;
+    if (options.remove && exitCode === 0) {
+        const complaint = await removeDelegateWorktree(repoRoot, createdPath, { runGit });
+        if (complaint) {
+            removed = false;
+            const message = `git refused to remove the worktree (it may contain uncommitted work):\n  ${complaint.trim().split("\n").join("\n  ")}`;
+            if (options.json) {
+                emitJson({ name, exitCode, worktree: createdPath, branch, removed: false, note: message });
+            }
+            else {
+                banner(`[glm-router] ${message}`, options.quiet);
+                banner(`[glm-router] worktree kept at ${createdPath}`, options.quiet);
+            }
+            return exitCode;
+        }
+        removed = true;
+    }
+    if (options.json) {
+        emitJson({ name, exitCode, worktree: createdPath, branch, removed });
+    }
+    else {
+        banner(`[glm-router] worker exited ${exitCode}`, options.quiet);
+        if (removed) {
+            banner(`[glm-router] worktree removed; branch ${branch} kept`, options.quiet);
+        }
+        else {
+            banner(`[glm-router] worktree kept at ${createdPath}`, options.quiet);
+            banner(`[glm-router] next: inspect it, then merge ${branch} (or discard with git worktree remove)`, options.quiet);
+        }
+    }
+    return exitCode;
+}

package/dist/core/errors.js

@@ -96,6 +96,36 @@ export const Errors = {
         ],
         exitCode: ExitCode.InvalidArgs,
     }),
+    invalidArgs: (detail, hint) => new GlmRouterError({
+        name: "INVALID_ARGS",
+        message: detail,
+        hint: hint && hint.length > 0 ? hint : undefined,
+        exitCode: ExitCode.InvalidArgs,
+    }),
+    gitNotFound: () => new GlmRouterError({
+        name: "GIT_NOT_FOUND",
+        message: "git was not found on PATH.",
+        hint: ["delegate needs git for worktree isolation.", "", "Install Git for Windows: https://git-scm.com/download/win"],
+        exitCode: ExitCode.ProjectRootNotFound,
+    }),
+    gitRepoRequired: (cwd) => new GlmRouterError({
+        name: "GIT_REPO_REQUIRED",
+        message: `Not inside a git repository (cwd: ${cwd}).`,
+        hint: ["delegate runs each worker in a git worktree and needs a repo root.", "", "Run it from inside the project's git repository, or create one:", "", "  git init"],
+        exitCode: ExitCode.ProjectRootNotFound,
+    }),
+    worktreeFailed: (operation, cause, hint) => new GlmRouterError({
+        name: "WORKTREE_FAILED",
+        message: `git ${operation} failed: ${cause.trim() || "unknown git error"}`,
+        hint: hint ?? ["Fix the state git describes above, then re-run the delegate command."],
+        exitCode: ExitCode.ManagedFileWriteFailed,
+    }),
+    invalidDelegateName: (name) => new GlmRouterError({
+        name: "INVALID_DELEGATE_NAME",
+        message: `"${name}" is not a valid delegate name.`,
+        hint: ["Use letters, digits, dots, dashes, underscores; start with a letter or digit.", "", "Examples: backend, auth-refresh, tests.v2"],
+        exitCode: ExitCode.InvalidArgs,
+    }),
     managedBlockCorrupt: (file, cause) => new GlmRouterError({
         name: "MANAGED_BLOCK_CORRUPT",
         message: `Managed block in ${file} is malformed: ${cause}`,

package/dist/core/git.js

@@ -0,0 +1,31 @@
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { Errors } from "./errors.js";
+function isENOENT(error) {
+    return error !== null && typeof error === "object" && error.code === "ENOENT";
+}
+/** Real git runner: resolves with the exit code instead of throwing on failure. */
+export const runGit = (args, cwd) => new Promise((resolve, reject) => {
+    execFile("git", args, { cwd, windowsHide: true, encoding: "utf8", maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => {
+        if (error && isENOENT(error)) {
+            reject(Errors.gitNotFound());
+            return;
+        }
+        const code = error && typeof error.code === "number"
+            ? error.code
+            : 0;
+        resolve({ code, stdout: stdout ?? "", stderr: stderr ?? "" });
+    });
+});
+/**
+ * Strict repo-root lookup for delegate (specs/delegate-worktrees.md):
+ * unlike findProjectRoot, undefined when cwd is not inside a git repo.
+ */
+export async function gitTopLevel(cwd, run = runGit) {
+    const result = await run(["rev-parse", "--show-toplevel"], cwd);
+    if (result.code !== 0) {
+        return undefined;
+    }
+    const root = result.stdout.trim();
+    return root.length > 0 ? path.resolve(root) : undefined;
+}

package/dist/core/process.js

@@ -10,51 +10,84 @@ import { Errors } from "./errors.js";
 export function spawnAgent(binPath, options) {
     const { args, cwd, env, interactive = true } = options;
     return new Promise((resolve, reject) => {
-        let child;
-        try {
-            child = spawn(binPath, args, {
-                cwd,
-                env,
-                stdio: interactive ? "inherit" : ["ignore", "inherit", "inherit"],
-                shell: false,
-                windowsHide: false,
-            });
-        }
-        catch (error) {
-            reject(Errors.childAgentFailed(errorMessage(error)));
-            return;
-        }
-        const signals = ["SIGINT", "SIGTERM"];
-        const handlers = new Map();
-        for (const signal of signals) {
-            const handler = () => {
-                if (child.killed)
-                    return;
-                try {
-                    child.kill(signal);
-                }
-                catch {
-                    // Child already gone; the exit event settles the promise.
-                }
-            };
-            handlers.set(signal, handler);
-            process.on(signal, handler);
-        }
-        const cleanup = () => {
-            for (const [signal, handler] of handlers) {
-                process.removeListener(signal, handler);
-            }
-        };
+        const child = spawn(binPath, args, {
+            cwd,
+            env,
+            stdio: interactive ? "inherit" : ["ignore", "inherit", "inherit"],
+            shell: false,
+            windowsHide: false,
+        });
+        const handlers = forwardSignals(child);
         child.on("error", (error) => {
-            cleanup();
+            removeSignals(handlers);
             reject(Errors.childAgentFailed(errorMessage(error)));
         });
         child.on("exit", (code) => {
-            cleanup();
+            removeSignals(handlers);
             resolve(code ?? 1);
         });
     });
 }
+/**
+ * Like spawnAgent but pipes stdout/stderr instead of inheriting them and
+ * resolves the captured output (specs/benchmark.md) — same no-shell rule and
+ * signal forwarding. Used by `benchmark` to parse the child's result JSON.
+ */
+export function spawnAgentCapture(binPath, options) {
+    const { args, cwd, env } = options;
+    return new Promise((resolve, reject) => {
+        const child = spawn(binPath, args, {
+            cwd,
+            env,
+            stdio: ["ignore", "pipe", "pipe"],
+            shell: false,
+            windowsHide: false,
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        const handlers = forwardSignals(child);
+        child.on("error", (error) => {
+            removeSignals(handlers);
+            reject(Errors.childAgentFailed(errorMessage(error)));
+        });
+        child.on("exit", (code) => {
+            removeSignals(handlers);
+            resolve({ code: code ?? 1, stdout, stderr });
+        });
+    });
+}
+/** Install SIGINT/SIGTERM forwarding; returns the handlers for cleanup. */
+function forwardSignals(child) {
+    const handlers = new Map();
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+        const handler = () => {
+            if (child.killed)
+                return;
+            try {
+                child.kill(signal);
+            }
+            catch {
+                // Child already gone; the exit event settles the promise.
+            }
+        };
+        handlers.set(signal, handler);
+        process.on(signal, handler);
+    }
+    return handlers;
+}
+function removeSignals(handlers) {
+    for (const [signal, handler] of handlers) {
+        process.removeListener(signal, handler);
+    }
+}
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }