akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/integrations/agent/spawn.js

@@ -18,35 +18,9 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { parseEmbeddedJsonResponse } from "../../core/parse.js";
-import { spawn as runtimeSpawn } from "../../runtime.js";
+import { runManagedSubprocess, } from "../../core/subprocess.js";
 import { getCommandBuilder } from "./builders.js";
 import { DEFAULT_AGENT_TIMEOUT_MS } from "./config.js";
-/**
- * Kill the process group of `proc` with `signal`, falling back to
- * `proc.kill(signal)` when `proc.pid` is unavailable (e.g. test fakes).
- *
- * Passing a negative PID to `process.kill` targets the entire process
- * group, so opencode's child processes (the .opencode binary, etc.) are
- * reaped alongside the node wrapper. The fallback keeps test fakes working
- * without modification.
- */
-function killGroup(proc, signal) {
-    if (typeof proc.pid === "number") {
-        try {
-            process.kill(-proc.pid, signal);
-            return;
-        }
-        catch {
-            // Process may have already exited; fall through to direct kill.
-        }
-    }
-    try {
-        proc.kill(signal);
-    }
-    catch {
-        /* ignore */
-    }
-}
 const DEFAULT_TIMEOUT_MS = DEFAULT_AGENT_TIMEOUT_MS;
 /**
  * Supplement `existingPath` with well-known user binary directories when
@@ -102,14 +76,6 @@ function pathCandidatesForCurrentPlatform(home) {
         "/usr/local/bin",
     ];
 }
-function resolveSpawnFn(options) {
-    if (options.spawn)
-        return options.spawn;
-    // Default to the runtime-boundary spawn, which delegates to the native
-    // subprocess API on each runtime. Tests inject `options.spawn` to avoid
-    // poking real binaries.
-    return runtimeSpawn;
-}
 /**
  * Build the child env. Starts empty and copies through:
  *   • Every name in `profile.envPassthrough`.
@@ -143,21 +109,19 @@ function buildChildEnv(profile, options) {
     }
     return env;
 }
-async function readStream(stream, opts) {
-    if (!stream)
-        return "";
-    const readPromise = new Response(stream).text().catch(() => "");
-    if (!opts?.timeoutMs)
-        return readPromise;
-    // Race the stream read against a timeout so a process that is killed via
-    // SIGTERM/SIGKILL but whose pipe endpoints stay open (e.g. background
-    // threads still holding the fd) cannot block the caller indefinitely.
-    // On timeout we return whatever we received so far (empty string here since
-    // `readPromise` is all-or-nothing with `Response.text()`).
-    const timeoutPromise = new Promise((resolve) => {
-        setTimeout(() => resolve(""), opts.timeoutMs);
-    });
-    return Promise.race([readPromise, timeoutPromise]);
+function streamFailureMessage(profileName, stdout, stderr) {
+    const failures = [];
+    if (stdout.error)
+        failures.push(`stdout read failed: ${stdout.error instanceof Error ? stdout.error.message : String(stdout.error)}`);
+    if (stderr.error)
+        failures.push(`stderr read failed: ${stderr.error instanceof Error ? stderr.error.message : String(stderr.error)}`);
+    if (stdout.timedOut)
+        failures.push("stdout drain timed out");
+    if (stderr.timedOut)
+        failures.push("stderr drain timed out");
+    if (failures.length === 0)
+        return undefined;
+    return `agent CLI "${profileName}" output capture failed: ${failures.join("; ")}`;
 }
 /**
  * Spawn the agent CLI described by `profile` with `prompt` (forwarded as
@@ -179,26 +143,37 @@ async function readStream(stream, opts) {
  */
 export async function runAgent(profile, prompt, options = {}) {
     const stdioMode = options.stdio ?? profile.stdio;
-    // null = explicitly disabled (no kill timer). undefined = inherit from profile/default.
-    const timeoutMs = options.timeoutMs !== undefined ? options.timeoutMs : (profile.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    // null = explicitly disabled (no kill timer). undefined = runtime default.
+    const timeoutMs = options.timeoutMs !== undefined ? options.timeoutMs : DEFAULT_TIMEOUT_MS;
     const parseOutput = options.parseOutput ?? profile.parseOutput;
     const setTimeoutImpl = options.setTimeoutFn ?? setTimeout;
     const clearTimeoutImpl = options.clearTimeoutFn ?? clearTimeout;
+    // Observability seam — ids/status only, best-effort (see RunAgentOptions.onEvent).
+    const emitSpawnEvent = (type, data) => {
+        if (!options.onEvent)
+            return;
+        try {
+            options.onEvent({ type, data });
+        }
+        catch {
+            // Observability must never break the dispatch.
+        }
+    };
     // Build argv via the platform-specific builder when dispatch params are
-    // provided; fall back to the legacy positional-prompt form otherwise.
+    // provided; otherwise use the direct positional-prompt form.
     let builtArgv;
     let builtEnv;
     if (options.dispatch !== undefined) {
-        const builder = getCommandBuilder(profile.commandBuilder ?? profile.name, options.builderRegistry);
+        const builder = getCommandBuilder(profile.platform ?? profile.name, options.builderRegistry);
         const built = builder.build(profile, options.dispatch);
         builtArgv = built.argv;
         builtEnv = built.env;
     }
     else {
-        const legacyArgs = [...profile.args, ...(options.args ?? [])];
+        const positionalArgs = [...profile.args, ...(options.args ?? [])];
         if (prompt !== undefined)
-            legacyArgs.push(prompt);
-        builtArgv = [profile.bin, ...legacyArgs];
+            positionalArgs.push(prompt);
+        builtArgv = [profile.bin, ...positionalArgs];
     }
     // Extra args (e.g. forwarded CLI positionals) are appended after the builder output.
     const finalArgv = [...builtArgv, ...(options.dispatch ? (options.args ?? []) : [])];
@@ -217,141 +192,43 @@ export async function runAgent(profile, prompt, options = {}) {
             error: `agent CLI "${profile.name}" not started: caller signal already aborted`,
         };
     }
-    let proc;
-    try {
-        const spawnFn = resolveSpawnFn(options);
-        proc = spawnFn(finalArgv, {
-            stdin: stdioMode === "captured" ? (options.stdin !== undefined ? "pipe" : "ignore") : "inherit",
-            stdout: stdioMode === "captured" ? "pipe" : "inherit",
-            stderr: stdioMode === "captured" ? "pipe" : "inherit",
-            env,
-            // options.cwd wins; dispatch.cwd is the request-level fallback (it was
-            // declared on AgentDispatchRequest but consumed by nothing — P0.5 fix).
-            ...((options.cwd ?? options.dispatch?.cwd) ? { cwd: options.cwd ?? options.dispatch?.cwd } : {}),
-            // Spawn in its own process group so killGroup(-pid, signal) reaches all
-            // descendants (e.g. the .opencode binary that opencode's node wrapper forks).
-            // Only applied in captured mode — interactive mode inherits the parent
-            // terminal's process group intentionally.
-            ...(stdioMode === "captured" ? { detached: true } : {}),
-        });
-    }
-    catch (err) {
-        const durationMs = Date.now() - start;
-        return {
-            ok: false,
-            exitCode: null,
-            stdout: "",
-            stderr: "",
-            durationMs,
-            reason: "spawn_failed",
-            error: err instanceof Error ? err.message : String(err),
-        };
-    }
-    // Hard timeout. We prefer SIGTERM, then SIGKILL if SIGTERM is ignored,
-    // but the subprocess only exposes a single .kill() — one signal is enough
-    // for the structured-failure contract.
+    // Spawn/timeout/abort/capture are owned by the managed-subprocess primitive
+    // (src/core/subprocess.ts): process-GROUP spawn (detached in captured mode),
+    // the SIGTERM→SIGKILL kill ladder on timeout/abort, bounded output capture,
+    // and the optional stdin payload. runAgent keeps its agent-specific surface —
+    // the onEvent observability seam, the failure taxonomy, and JSON parsing.
     //
-    // BUG-M3: only flag `timedOut` when the child has not already exited. A
-    // timer firing in the same microtask as `proc.exited` resolving could
-    // otherwise label a clean exit as a timeout.
-    //
-    // When timeoutMs is null the kill timer is skipped entirely — the task runs
-    // until the process exits naturally. Intended for long-running local-model
-    // tasks where wall-clock time is unpredictable.
-    let timedOut = false;
-    let timer;
-    if (timeoutMs !== null) {
-        timer = setTimeoutImpl(() => {
-            if (!proc || proc.exitCode !== null)
-                return;
-            timedOut = true;
-            killGroup(proc, "SIGTERM");
-            // Follow up with SIGKILL after 5 s in case the process ignores SIGTERM.
-            setTimeoutImpl(() => {
-                if (!proc || proc.exitCode !== null)
-                    return;
-                killGroup(proc, "SIGKILL");
-            }, 5000);
-        }, timeoutMs);
-    }
-    // Cooperative cancel: same SIGTERM→SIGKILL discipline as the timeout, but
-    // flagged separately so the result carries `reason: "aborted"`.
-    let aborted = false;
-    const abortSignal = options.signal;
-    const onAbort = () => {
-        if (!proc || proc.exitCode !== null)
-            return;
-        aborted = true;
-        killGroup(proc, "SIGTERM");
-        const sigkillTimer = setTimeoutImpl(() => {
-            if (!proc || proc.exitCode !== null)
-                return;
-            killGroup(proc, "SIGKILL");
-        }, 5000);
-        if (typeof sigkillTimer !== "number")
-            sigkillTimer.unref?.();
-    };
-    if (abortSignal) {
-        // A signal that aborted between the pre-spawn check and here is handled
-        // by calling the listener directly.
-        if (abortSignal.aborted)
-            onAbort();
-        else
-            abortSignal.addEventListener("abort", onAbort, { once: true });
-    }
-    // Stream-drain timeout: the overall wall-clock budget plus a 2 s grace
-    // period. When a process is killed via SIGTERM/SIGKILL (from our timeout
-    // handler or from outside) some runtimes keep the pipe write-end open in
-    // background threads, which would cause `Response.text()` to block forever.
-    // Capping stream draining ensures the caller never hangs past the wall
-    // budget regardless of subprocess pipe behaviour.
-    // When there is no kill timer, allow up to 30 s for streams to drain.
-    const streamDrainTimeoutMs = timeoutMs !== null ? timeoutMs + 2_000 : 30_000;
-    const stdoutPromise = stdioMode === "captured"
-        ? readStream(proc.stdout ?? null, { timeoutMs: streamDrainTimeoutMs })
-        : Promise.resolve("");
-    const stderrPromise = stdioMode === "captured"
-        ? readStream(proc.stderr ?? null, { timeoutMs: streamDrainTimeoutMs })
-        : Promise.resolve("");
-    // Optional stdin payload (captured mode only).
-    //
-    // BUG-H1: race the stdin write/close against `proc.exited` and the
-    // timeout timer. If the child never drains stdin, an unraced
-    // `await writer.write()` would block forever and prevent `runAgent`
-    // from ever returning.
-    if (options.stdin !== undefined && stdioMode === "captured" && proc.stdin) {
-        const stdinPayload = options.stdin;
-        const stdinStream = proc.stdin;
-        const stdinDone = (async () => {
-            try {
-                const writer = stdinStream.getWriter();
-                const bytes = new TextEncoder().encode(stdinPayload);
-                await writer.write(bytes);
-                await writer.close();
-            }
-            catch {
-                // Best-effort: ignore stdin write failures, the child will get EOF.
-            }
-        })();
-        // Resolve as soon as either the write completes or the child exits.
-        // We don't await the result — only that one of the two has settled —
-        // so a stuck writer cannot keep us pinned past the timeout.
-        await Promise.race([stdinDone, proc.exited.catch(() => undefined)]);
-    }
-    let exitCode = null;
-    try {
-        exitCode = await proc.exited;
-    }
-    catch (err) {
-        if (timer !== undefined)
-            clearTimeoutImpl(timer);
-        abortSignal?.removeEventListener("abort", onAbort);
-        // BUG-H2: drain stream readers before the early return so they don't
-        // surface as unhandled rejections after the function resolves.
-        // The streams already carry a built-in drain timeout so this allSettled
-        // will not block indefinitely.
-        await Promise.allSettled([stdoutPromise, stderrPromise]);
-        const durationMs = Date.now() - start;
+    // `onSpawn` fires spawn_start once the child is live (never for a pre-spawn
+    // abort or a synchronous spawn failure), and captures the proc so spawn_exit
+    // can carry the same pid.
+    let spawnedProc;
+    const result = await runManagedSubprocess(finalArgv, {
+        capture: stdioMode === "captured",
+        env,
+        ...(options.cwd ? { cwd: options.cwd } : {}),
+        ...(options.stdin !== undefined ? { stdin: options.stdin } : {}),
+        timeoutMs,
+        ...(options.signal ? { signal: options.signal } : {}),
+        ...(options.spawn ? { spawnFn: options.spawn } : {}),
+        setTimeoutFn: setTimeoutImpl,
+        clearTimeoutFn: clearTimeoutImpl,
+        onSpawn: (proc) => {
+            spawnedProc = proc;
+            emitSpawnEvent("spawn_start", {
+                profile: profile.name,
+                ...(typeof proc.pid === "number" ? { pid: proc.pid } : {}),
+            });
+        },
+    });
+    const pidField = spawnedProc && typeof spawnedProc.pid === "number" ? { pid: spawnedProc.pid } : {};
+    const durationMs = Date.now() - start;
+    // Spawn/exit failure. A synchronous spawn throw never reached a live child
+    // (no spawn_start fired, so no spawn_exit either); a rejected proc.exited did
+    // (spawn_start already fired, so it emits a spawn_exit with status spawn_failed).
+    if (result.spawnError) {
+        if (spawnedProc) {
+            emitSpawnEvent("spawn_exit", { profile: profile.name, ...pidField, exitCode: null, status: "spawn_failed" });
+        }
         return {
             ok: false,
             exitCode: null,
@@ -359,13 +236,16 @@ export async function runAgent(profile, prompt, options = {}) {
             stderr: "",
             durationMs,
             reason: "spawn_failed",
-            error: err instanceof Error ? err.message : String(err),
+            error: result.spawnError.message,
         };
     }
-    clearTimeoutImpl(timer);
-    abortSignal?.removeEventListener("abort", onAbort);
-    const [stdout, stderr] = await Promise.all([stdoutPromise, stderrPromise]);
-    const durationMs = Date.now() - start;
+    const { exitCode, timedOut, aborted, stdout, stderr } = result;
+    emitSpawnEvent("spawn_exit", {
+        profile: profile.name,
+        ...pidField,
+        exitCode,
+        status: aborted ? "aborted" : timedOut ? "timeout" : exitCode !== 0 ? "non_zero_exit" : "ok",
+    });
     if (aborted) {
         return {
             ok: false,
@@ -388,6 +268,18 @@ export async function runAgent(profile, prompt, options = {}) {
             error: `agent CLI "${profile.name}" timed out after ${timeoutMs ?? 0}ms`,
         };
     }
+    const captureFailure = streamFailureMessage(profile.name, result.stdoutRead, result.stderrRead);
+    if (captureFailure) {
+        return {
+            ok: false,
+            exitCode,
+            stdout,
+            stderr,
+            durationMs,
+            reason: "spawn_failed",
+            error: captureFailure,
+        };
+    }
     if (exitCode !== 0) {
         return {
             ok: false,

package/dist/integrations/harnesses/aider/agent-builder.js

@@ -0,0 +1,114 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Aider CLI agent command builder (P2, plan §"The adapter contract" step 2 /
+ * §"Capability matrix").
+ *
+ * Translates a platform-agnostic {@link AgentDispatchRequest} into the exact
+ * headless argv the `aider` CLI expects. Per the capability matrix the
+ * headless invocation is:
+ *
+ *   aider -m "<p>" --yes-always
+ *
+ * with `--model <m>` for model selection, NO structured-output mode (Aider is
+ * the "none" tier — prompt-injected schema + embedded-JSON extraction), and
+ * NO session flag (resume is chat-history files, not an id).
+ *
+ * Platform-specific mapping decisions (all localized here, per the adapter
+ * contract):
+ *
+ * - **prompt** — `--message` is Aider's one-shot non-interactive mode (the
+ *   matrix's `-m`; the long form is used for self-documenting argv). Unlike
+ *   claude/codex/pi there is NO positional prompt and NO `--` end-of-options
+ *   separator to hide behind: the prompt is a *flag value*. The glued
+ *   `--message=<payload>` form is therefore used so a payload that begins
+ *   with `-`/`--` binds to the flag lexically and can never be parsed as a
+ *   separate option by Aider's argument parser.
+ * - **--yes-always** — always emitted: auto-confirms every interactive
+ *   prompt (create file? run command? …), which is what makes a captured,
+ *   unattended run possible. This is the matrix's documented headless shape.
+ * - **--no-pretty** — always emitted: disables colored/pretty terminal
+ *   rendering so captured stdout is clean text for `./result-extractor.ts`
+ *   (the same "dispatch is the captured path" reasoning as the Claude
+ *   builder's unconditional `--print` and Codex's unconditional `--json`).
+ * - **systemPrompt** — Aider has no system-prompt flag (its nearest concept
+ *   is conventions files via `--read`, which take a path, not text). Folded
+ *   into the message payload — system text first, blank line, then the task —
+ *   mirroring the codex builder's treatment.
+ * - **schema** — the matrix places Aider in the "via prompt+validate" tier
+ *   with *no* structured output mode at all (plan §"Structured-output
+ *   normalization", tier "none"): there is no schema flag and no JSON output
+ *   flag, so the JSON Schema is injected into the message payload using the
+ *   exact directive wording of the engine's prompt assembly
+ *   (`step-work.ts` `buildUnitPrompt`) and the pi builder, so all
+ *   dispatch paths speak one dialect. Downstream, embedded-JSON extraction +
+ *   the engine's shared retry-until-valid loop supply the validation Aider
+ *   lacks. No temp schema file is written — that is Codex's native-schema
+ *   mechanism (`--output-schema`), which Aider does not have.
+ * - **tools** — deliberately unconsumed. Aider has no per-tool allowlist
+ *   flag; tool-ish behaviour is governed by its own switches (`--yes-always`,
+ *   git integration, shell-command confirmation). A restrictive policy is
+ *   therefore dropped rather than approximated — never silently widened.
+ * - **resume/session** — NOT expressible: Aider persists context in
+ *   chat-history files (`.aider.chat.history.md`), not session ids, so there
+ *   is no flag-shaped resume to describe and the extractor
+ *   never yields a `sessionId`. akm's `workflow_run_units` remains the
+ *   durable source of truth; resume works even against a harness with no
+ *   session model (plan §"Session, MCP, and identity across harnesses" —
+ *   Aider is the plan's named example).
+ * - **effort** — stays unconsumed (reserved; the shared request contract's
+ *   "no builder consumes it yet" note stays true).
+ *
+ * Registered: `aiderBuilder` is `AiderHarness.agentBuilder` (`./index.ts`),
+ * one of the ten harnesses `HARNESS_REGISTRY` constructs
+ * (`harnesses/index.ts`); `agent/builders.ts` derives `BUILTIN_BUILDERS` from
+ * that registry, so this builder is reachable under the `"aider"` platform
+ * name without any further wiring. The registry entry also declares
+ * `structuredOutput: "none"` alongside it (`./index.ts`).
+ */
+import { assertNotFlag, resolveDispatchModel, } from "../../agent/builder-shared.js";
+/** Canonical harness/platform id used for model-alias resolution. */
+export const AIDER_PLATFORM = "aider";
+/**
+ * Assemble the `--message` payload: optional system text, the task prompt,
+ * and — when a schema is requested — the same schema directive the workflow
+ * engine's prompt assembly uses (Aider has no native structured output, so
+ * the prompt is the only channel; plan §"Structured-output normalization",
+ * tier "none").
+ */
+function buildMessagePayload(req) {
+    const sections = [];
+    if (req.systemPrompt)
+        sections.push(req.systemPrompt);
+    sections.push(req.prompt);
+    if (req.schema) {
+        sections.push(`Respond with ONLY a JSON value matching this JSON Schema (no prose, no code fences):\n${JSON.stringify(req.schema)}`);
+    }
+    return sections.join("\n\n");
+}
+/**
+ * Aider builder.
+ * Command shape:
+ *   aider [--model <m>] --yes-always --no-pretty --message=<[system\n\n]prompt[\n\nschema directive]>
+ */
+export const aiderBuilder = {
+    platform: AIDER_PLATFORM,
+    build(profile, req) {
+        assertNotFlag(req.systemPrompt, "systemPrompt");
+        assertNotFlag(req.model, "model");
+        const args = [...profile.args];
+        if (req.model) {
+            const resolved = resolveDispatchModel(req, profile, AIDER_PLATFORM);
+            args.push("--model", resolved);
+        }
+        // Headless essentials (matrix shape): auto-confirm everything, and keep
+        // captured stdout free of pretty/ANSI rendering for the extractor.
+        args.push("--yes-always");
+        args.push("--no-pretty");
+        // Glued form: the payload is a flag VALUE (no positional prompt exists),
+        // so `=` binding keeps a dash-leading payload from parsing as an option.
+        args.push(`--message=${buildMessagePayload(req)}`);
+        return { argv: [profile.bin, ...args] };
+    },
+};

package/dist/integrations/harnesses/aider/index.js

@@ -0,0 +1,48 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Aider CLI harness (P2 integration, plan §"The adapter contract").
+ *
+ * Per-harness barrel gathering the Aider integration surfaces:
+ *   - agent command builder → ./agent-builder.ts    (aiderBuilder)
+ *   - result extractor      → ./result-extractor.ts (aiderResultExtractor)
+ *
+ * It also defines {@link AiderHarness}, the {@link AkmHarness} descriptor that
+ * `HARNESS_REGISTRY` registers. Dispatch-only: no native session-log reader or
+ * config importer yet.
+ */
+import { caps } from "../shared.js";
+import { BaseHarness } from "../types.js";
+import { aiderBuilder } from "./agent-builder.js";
+import { aiderResultExtractor } from "./result-extractor.js";
+export { AIDER_PLATFORM, aiderBuilder } from "./agent-builder.js";
+export { aiderResultExtractor } from "./result-extractor.js";
+/**
+ * Aider.
+ *
+ * Canonical id is `'aider'`; no alias or distinct runtime identity.
+ */
+export class AiderHarness extends BaseHarness {
+    id = "aider";
+    displayName = "Aider";
+    aliases = [];
+    agentBuilder = aiderBuilder;
+    resultExtractor = aiderResultExtractor;
+    // ── Workflow-engine descriptor (plan §"Capability matrix", P2) ────────────
+    // akm spawns the `aider` CLI locally per unit ⇒ local-runner.
+    pattern = "local-runner";
+    // No structured-output mode at all (the matrix's "none — parse output"):
+    // akm injects the schema into the prompt and extracts embedded JSON.
+    structuredOutput = "none";
+    // No flag-shaped resume: Aider persists context in chat-history files
+    // (`.aider.chat.history.md`), not session ids — the plan's named example of
+    // a harness with no session model. akm's `workflow_run_units` remains the
+    // durable resume source of truth.
+    // No `identityEnv`: the matrix lists Aider's identity markers as uncertain,
+    // and Aider stamps no session var onto child processes.
+    capabilities = caps({
+        agentDispatch: true,
+        detection: true,
+    });
+}

package/dist/integrations/harnesses/aider/result-extractor.js

@@ -0,0 +1,53 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * ANSI escape sequences (CSI color/cursor codes). Defensive only: the builder
+ * always passes `--no-pretty`, but a user profile may override that.
+ * Constructed from a char code so no literal control character appears in
+ * source (lint-friendly, same bytes).
+ */
+const ANSI_ESCAPE_RE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;?]*[ -/]*[@-~]`, "g");
+/**
+ * Aider's own announcement lines — banner, model/repo configuration echo,
+ * chat-history notices, edit/commit/usage reports. All patterns are anchored
+ * at line start and match documented phrasings only; anything else is treated
+ * as reply content.
+ */
+const NOISE_LINE_PATTERNS = [
+    /^aider v\d/, // version banner
+    /^(Main model|Weak model|Editor model|Model):\s/, // model announcements
+    /^Git repo:\s/, // repo detection
+    /^Repo-map:\s/, // repo-map status
+    /^Added .+ to the chat\.?$/, // file add notices
+    /^Restored previous conversation history\.?$/, // chat-history reload notice
+    /^Use \/help\b/, // onboarding hint line
+    /^Tokens: .+/, // usage/cost footer
+    /^Cost: .+/, // standalone cost footer
+    /^Applied edit to .+/, // edit application notices
+    /^Commit [0-9a-f]{6,}\b/, // auto-commit notices
+    /^You can use \/undo\b/, // undo hint after auto-commit
+    /^[─━-]{4,}$/, // ── / ━━ / ---- separator rules
+];
+function isNoiseLine(line) {
+    return NOISE_LINE_PATTERNS.some((pattern) => pattern.test(line));
+}
+/**
+ * Normalize a raw aider run result into `{ text, sessionId? }`.
+ * See the module doc for the stdout shape handled.
+ */
+export const aiderResultExtractor = (result) => {
+    const raw = result.stdout.replace(ANSI_ESCAPE_RE, "").trim();
+    const kept = raw
+        .split("\n")
+        .filter((line) => !isNoiseLine(line.trim()))
+        .join("\n")
+        .trim();
+    // Never return empty text when stdout had content: an all-noise filter
+    // outcome means the patterns over-matched for this capture, so fall back to
+    // the full trimmed stdout (downstream parsing still gets material).
+    const text = kept.length > 0 ? kept : raw;
+    // No session model (chat-history files, not ids): only a spawn-layer id
+    // passes through; output never supplies one.
+    return result.sessionId === undefined ? { text } : { text, sessionId: result.sessionId };
+};