@bridge_gpt/mcp-server 0.2.16 → 0.2.19

package/build/executor/job-types.js

@@ -0,0 +1,60 @@
+/**
+ * Shared executor job-type policy (BAPI-542, TDD §9).
+ *
+ * Single source of truth for which claimed job types the executor spawns and
+ * which of those are RECOVERY jobs. Recovery jobs (`remediate`/`ci_fix`/`rebase`)
+ * resume the ticket's existing branch/PR through the `/implement-ticket <KEY>
+ * --auto` correction loop rather than cutting a fresh branch off base. Dispatch
+ * (`job-runner.ts` `runClaimedJob`), prompt synthesis (`worker-command.ts`
+ * `resolveExecutorPrompt`), and worktree reuse (`job-runner.ts` `prepareSpawn` →
+ * `worktree.ts` `ensureExecutorWorktree`) all read from here so the recovery /
+ * spawn classification cannot drift between them.
+ *
+ * ARCHITECTURE BOUNDARY (TDD §12): this module is executor-local. It imports
+ * NOTHING from the v1 conductor runtime, ledger, event, taxonomy, supervisor, or
+ * server-side reconciler graph — only bare string sets and predicates.
+ */
+/**
+ * Recovery job types: enqueued by the server-side reconciler when a gate is
+ * ACTIONABLE (review changes requested → `remediate`, CI failed → `ci_fix`,
+ * merge conflict → `rebase`). They re-enter the correction loop on the ticket's
+ * EXISTING branch/PR, so the executor reuses that branch instead of cutting a
+ * fresh one off base.
+ */
+export const RECOVERY_JOB_TYPES = new Set([
+    "remediate",
+    "ci_fix",
+    "rebase",
+]);
+/**
+ * Real headless-spawn job types (worktree + worker LLM): the first-pass
+ * `implement`, the `resume` continuation (own pre-spawn protocol), the
+ * `spec_review` verdict job, and the three recovery jobs. `merge` (deterministic,
+ * no worktree/worker) and `smoke` (no-op acceptance) are intentionally EXCLUDED —
+ * they have dedicated dispatch branches BEFORE the generic spawn path.
+ */
+export const SPAWN_JOB_TYPES = new Set([
+    "implement",
+    "resume",
+    "spec_review",
+    "remediate",
+    "ci_fix",
+    "rebase",
+]);
+/** True only for the exact lowercase recovery job types. */
+export function isRecoveryJobType(jobType) {
+    return RECOVERY_JOB_TYPES.has(jobType);
+}
+/** True only for the exact lowercase spawn job types. */
+export function isSpawnJobType(jobType) {
+    return SPAWN_JOB_TYPES.has(jobType);
+}
+/**
+ * Implementation-style spawn jobs (BAPI-551): every spawn job type expected to
+ * end with a pushed origin branch or an opened PR — `implement`, `resume`, and
+ * the recovery jobs. Excludes `spec_review`, the one spawn type that is a
+ * verdict job (it produces `.conductor/result.json` instead of a branch/PR).
+ */
+export function isImplementationStyleJobType(jobType) {
+    return isSpawnJobType(jobType) && jobType !== "spec_review";
+}

package/build/executor/merge-job.js

@@ -0,0 +1,155 @@
+/**
+ * Deterministic `merge` job body (BAPI-535, TDD §5, §9).
+ *
+ * `merge` is a DETERMINISTIC executor action, distinct from every spawn-a-worker
+ * job type: NO worktree is ensured and NO `claude` worker is spawned. It runs
+ * `gh pr merge <pr_number> --<method> --match-head-commit <expected_head_sha>`
+ * under the machine's LOCAL `gh` auth by reusing {@link makeLocalMergeExecutor}
+ * (the App token is `contents: read` and cannot merge — the run-7
+ * `provider_unauthorized` failure). `--match-head-commit` rejects head drift at
+ * GitHub, so no action-key idempotency protocol is needed. On success the merge
+ * outcome (accepted / merge commit) is posted at `/complete`; gate advancement is
+ * left entirely to the merge OBSERVER (T4/T5) — this module never advances a gate.
+ */
+import { makeLocalMergeExecutor, resolveLocalMergeMethod, } from "../conductor/local-merge.js";
+import { resolveConductorBridgeApiAccess, } from "../conductor/bridge-api-client.js";
+import { secretFreeErrorMessage } from "./job-errors.js";
+function positiveIntOrNull(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : null;
+}
+function asString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+/**
+ * Extract and validate merge fields. Prefers the claimed-job `expected_head_sha`
+ * over any payload copy, validates `pr_number` as a positive integer, and fails
+ * (before any subprocess) when the PR number or expected head SHA is absent.
+ */
+export function readMergeJobPayloadFields(job) {
+    const payload = job.payload && typeof job.payload === "object" ? job.payload : {};
+    const prNumber = positiveIntOrNull(payload.pr_number);
+    if (prNumber === null) {
+        return { ok: false, error: "merge job requires a positive integer pr_number" };
+    }
+    const expectedHeadSha = asString(job.expected_head_sha) ?? asString(payload.expected_head_sha);
+    if (!expectedHeadSha) {
+        return { ok: false, error: "merge job requires an expected_head_sha (top-level or payload)" };
+    }
+    const method = resolveLocalMergeMethod(payload.method);
+    const requiredChecks = Array.isArray(payload.required_checks)
+        ? payload.required_checks.filter((c) => typeof c === "string")
+        : [];
+    const actionKey = asString(payload.action_key) ?? `merge:pr-${prNumber}:${expectedHeadSha}`;
+    return {
+        ok: true,
+        fields: { prNumber, expectedHeadSha, method, requiredChecks, actionKey },
+    };
+}
+/** Construct the {@link ConductorMergeRequest} for the local merge executor. */
+export function buildConductorMergeRequestForExecutorJob(fields, repoName) {
+    return {
+        repo_name: repoName,
+        pr_number: fields.prNumber,
+        expected_head_sha: fields.expectedHeadSha,
+        gate: { name: "merge", required_checks: fields.requiredChecks },
+        action_key: fields.actionKey,
+    };
+}
+/**
+ * Resolve {@link ConductorBridgeApiAccess} for the merge via the SHARED conductor
+ * resolver (repo name + credential store + base URL). The API key never reaches
+ * `gh` argv/env/logs — it is used only for the executor's own read-only CI
+ * re-poll. Returns a structured failure rather than throwing.
+ */
+export async function buildConductorMergeAccessForExecutorJob(deps) {
+    const result = await resolveConductorBridgeApiAccess(deps);
+    if (result.ok)
+        return { ok: true, access: result.access };
+    return { ok: false, error: result.error };
+}
+/** Pull the best-effort merge commit SHA from a succeeded merge response. */
+function extractMergeCommitSha(response) {
+    for (const ev of response.ledger_events) {
+        if (ev.type === "merge.succeeded") {
+            const sha = ev.details?.merge_commit_sha;
+            if (typeof sha === "string" && sha.length > 0)
+                return sha;
+        }
+    }
+    return undefined;
+}
+/**
+ * Map a succeeded local-merge response into the backend `merge` result schema
+ * (`MinimalJobResult`, `extra="allow"`): the provider action was accepted, plus
+ * the best-effort merge commit SHA. NO gate-advancement or observer-only fields.
+ */
+export function buildMergeJobResult(response, fields) {
+    const mergeCommitSha = extractMergeCommitSha(response);
+    const result = {
+        accepted: true,
+        pr_number: fields.prNumber,
+        merge_method: fields.method,
+        summary: `merged PR #${fields.prNumber} via ${fields.method}`,
+    };
+    if (mergeCommitSha) {
+        result.commit_sha = mergeCommitSha;
+        result.head_sha = mergeCommitSha;
+    }
+    return result;
+}
+/** Convert a non-succeeded local-merge response into a bounded executor failure. */
+export function buildMergeJobFailure(response) {
+    const reason = asString(response.reason ?? undefined) ?? response.status;
+    return {
+        error_kind: "MergeFailed",
+        error_message: secretFreeErrorMessage(new Error(`local merge ${response.status}: ${reason}`)),
+        classification: "crashed",
+    };
+}
+/**
+ * Run the deterministic merge. NEVER ensures/recreates a worktree and NEVER
+ * spawns a worker. Returns a completion result on a succeeded merge, else a
+ * bounded, secret-free executor failure.
+ */
+export async function runExecutorMergeJob(job, seams) {
+    const resolution = readMergeJobPayloadFields(job);
+    if (!resolution.ok) {
+        return {
+            ok: false,
+            failure: {
+                error_kind: "ContractError.MergePayload",
+                error_message: resolution.error,
+                classification: "crashed",
+            },
+        };
+    }
+    const fields = resolution.fields;
+    const request = buildConductorMergeRequestForExecutorJob(fields, seams.access.repoName);
+    const make = seams.makeExecutor ?? makeLocalMergeExecutor;
+    const executor = make({ method: fields.method }, seams.localMergeDeps);
+    let response;
+    try {
+        response = await executor(seams.access, request);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            failure: {
+                error_kind: "MergeFailed",
+                error_message: secretFreeErrorMessage(err),
+                classification: "crashed",
+            },
+        };
+    }
+    if (response.status === "succeeded") {
+        return { ok: true, result: buildMergeJobResult(response, fields) };
+    }
+    return { ok: false, failure: buildMergeJobFailure(response) };
+}
+/** Build the default local-merge deps for production wiring (no real I/O here). */
+export function buildDefaultMergeLocalDeps(deps) {
+    // Local `gh` auth lives in the ambient environment; makeLocalMergeExecutor
+    // overlays it and pins the no-noise/non-interactive flags. The App token is
+    // never placed here.
+    return { env: deps.env };
+}

package/build/executor/observation.js

@@ -0,0 +1,123 @@
+/**
+ * Collect load-bearing git telemetry from a worktree. Individual git failures
+ * degrade the telemetry (fields omitted) rather than throwing — a degraded
+ * signal must never surface as a worker correctness failure.
+ */
+export async function collectGitTelemetry(deps, worktreePath, baseBranch) {
+    const telemetry = {};
+    try {
+        const revList = await deps.runCommand("git", [
+            "-C",
+            worktreePath,
+            "rev-list",
+            "--count",
+            `origin/${baseBranch}..HEAD`,
+        ]);
+        if (revList.exitCode === 0) {
+            const count = Number.parseInt(revList.stdout.trim(), 10);
+            if (Number.isFinite(count))
+                telemetry.local_commit_count = count;
+        }
+    }
+    catch {
+        /* degraded: omit local_commit_count */
+    }
+    try {
+        const revParse = await deps.runCommand("git", ["-C", worktreePath, "rev-parse", "HEAD"]);
+        if (revParse.exitCode === 0) {
+            const sha = revParse.stdout.trim();
+            if (sha.length > 0)
+                telemetry.last_commit_sha = sha;
+        }
+    }
+    catch {
+        /* degraded: omit last_commit_sha */
+    }
+    try {
+        const status = await deps.runCommand("git", [
+            "-C",
+            worktreePath,
+            "status",
+            "--porcelain",
+        ]);
+        if (status.exitCode === 0) {
+            const dirty = status.stdout.trim().length > 0;
+            telemetry.dirty = dirty;
+            if (dirty) {
+                telemetry.last_activity_at = new Date(deps.now()).toISOString();
+            }
+        }
+    }
+    catch {
+        /* degraded: omit dirty/last_activity_at */
+    }
+    return telemetry;
+}
+/**
+ * Tolerantly parse one Claude stream-json line for an advisory `phase_hint`.
+ * Catches ALL parse/schema errors and never throws; returns `{}` when nothing
+ * usable is found.
+ */
+export function parseClaudeStreamJsonLine(line) {
+    try {
+        const trimmed = typeof line === "string" ? line.trim() : "";
+        if (trimmed.length === 0)
+            return {};
+        const parsed = JSON.parse(trimmed);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        const obj = parsed;
+        // Advisory only: prefer an explicit phase/subtype, else the stream event type.
+        const hint = pickString(obj.phase) ??
+            pickString(obj.subtype) ??
+            pickString(obj.type);
+        return hint ? { phase_hint: hint } : {};
+    }
+    catch {
+        return {};
+    }
+}
+function pickString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/**
+ * Create the observation state. When `advisoryParserEnabled` is false, stdout is
+ * still timestamped (`last_stdout_at`) but never parsed — proving the advisory
+ * parser is not load-bearing.
+ */
+export function createObservationState(deps, options) {
+    let git = {};
+    const advisory = {};
+    let exitCode;
+    return {
+        recordStdout(chunk) {
+            advisory.last_stdout_at = new Date(deps.now()).toISOString();
+            if (!options.advisoryParserEnabled)
+                return;
+            for (const line of chunk.split("\n")) {
+                const hint = parseClaudeStreamJsonLine(line);
+                if (hint.phase_hint)
+                    advisory.phase_hint = hint.phase_hint;
+            }
+        },
+        setGitTelemetry(telemetry) {
+            git = telemetry;
+        },
+        setExitCode(code) {
+            exitCode = code;
+        },
+        git() {
+            return git;
+        },
+        snapshot() {
+            const residue = { ...git };
+            if (advisory.phase_hint)
+                residue.phase_hint = advisory.phase_hint;
+            if (advisory.last_stdout_at)
+                residue.last_stdout_at = advisory.last_stdout_at;
+            if (exitCode !== undefined)
+                residue.exit_code = exitCode;
+            return residue;
+        },
+    };
+}

package/build/executor/permissions.js

@@ -0,0 +1,79 @@
+/**
+ * Executor deny-layer provisioning (BAPI-534, TDD §7 permission model, R8).
+ *
+ * Provisions a small, stable deny set into each worktree's
+ * `.claude/settings.local.json` via the shared malformed-safe merge machinery.
+ * A denied call returns an error to the model (which adapts) — no stall. The
+ * deny layer FAILS OPEN: if it drifts or is missing, safety margin shrinks but
+ * liveness never does. (Refusing to claim on `enforced:false` is a SEPARATE,
+ * fatal preflight concern — see `preflight.ts`.)
+ *
+ * The Wave-1 probe on the target machine reports enforcement layer `settings-deny`
+ * (claude 2.1.201), so plain `permissions.deny` is provisioned; the PreToolUse
+ * fallback is available for CLIs where settings-deny is not enforced.
+ */
+import { mergeClaudeSettingsWithCommandHook, provisionClaudeSettingsForWorktree, DEFAULT_PRE_TOOL_USE_MATCHER, } from "../claude-settings.js";
+/**
+ * The stable executor deny rules. Grammar mirrors the deny-enforcement probe's
+ * `Bash(<cmd>:<args-glob>)` / `Read(<path-glob>)` form. Covers: reads under
+ * ~/.ssh, ~/.aws, and keychain paths; force-push to the base branch; and
+ * destructive `rm -rf` outside the worktree.
+ */
+export function executorDenyRules(inputs) {
+    return [
+        "Read(~/.ssh/**)",
+        "Read(~/.aws/**)",
+        "Read(~/Library/Keychains/**)",
+        "Read(/etc/shadow)",
+        `Bash(git push:*--force*${inputs.baseBranch}*)`,
+        "Bash(git push:*--force*)",
+        "Bash(rm:*-rf /*)",
+        "Bash(rm:*-rf ~*)",
+    ];
+}
+function asObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+/**
+ * Merge the executor deny set into a settings object under `permissions.deny`,
+ * preserving all existing settings and appending only rules not already present
+ * (idempotent).
+ */
+export function mergeExecutorDenySettings(existing, inputs) {
+    const permissions = { ...asObject(existing.permissions) };
+    const existingDeny = Array.isArray(permissions.deny) ? permissions.deny : [];
+    const merged = [...existingDeny];
+    for (const rule of executorDenyRules(inputs)) {
+        if (!merged.includes(rule))
+            merged.push(rule);
+    }
+    permissions.deny = merged;
+    return { ...existing, permissions };
+}
+/**
+ * Provision the executor deny layer into `<worktree>/.claude/settings.local.json`.
+ * Fails open: a malformed existing file is preserved (not clobbered) and I/O
+ * errors return a warning — the caller still spawns the worker.
+ */
+export async function provisionExecutorDenyLayer(worktreePath, options, deps) {
+    const inputs = {
+        baseBranch: options.baseBranch,
+        worktreePath,
+        homedir: deps.homedir(),
+    };
+    const result = await provisionClaudeSettingsForWorktree(worktreePath, (existing) => {
+        let merged = mergeExecutorDenySettings(existing, inputs);
+        if (options.preToolUseFallbackCommand) {
+            merged = mergeClaudeSettingsWithCommandHook(merged, options.preToolUseFallbackCommand, [], { enablePreToolUse: true, preToolUseMatcher: DEFAULT_PRE_TOOL_USE_MATCHER });
+        }
+        return merged;
+    }, deps);
+    if (result.ok)
+        return { ok: true };
+    return {
+        ok: false,
+        warning: `deny-layer provisioning did not complete (${result.reason}); continuing fail-open`,
+    };
+}

package/build/executor/preflight.js

@@ -0,0 +1,144 @@
+/**
+ * Executor preflight + capability manifest construction (BAPI-534, TDD §11, R8).
+ *
+ * Before claiming, verify local tooling (wt/git/claude), credentials, disk, and
+ * — the binding post-Wave-2 contract — deny-layer enforcement. REFUSE TO CLAIM
+ * on any fatal finding. The capability manifest (exactly the 8 T2-accepted keys)
+ * is built from these inspections. Local `gh` auth is captured in the internal
+ * report (for T5's fatal-before-merge preflight) but is NOT added to the T2
+ * claim manifest, which does not accept it in this slice.
+ *
+ * The deny-enforcement probe is injected (`seams.runDenyPreflight`) so unit tests
+ * never spawn a real headless `claude`; the default is the real
+ * `runDenyEnforcementPreflight` from the conductor deny-enforcement module (an
+ * allowed reuse surface — it does not pull the v1 event/ledger graph).
+ */
+import { runDenyEnforcementPreflight } from "../conductor/deny-enforcement-preflight.js";
+import { resolveAllExecutorApiAccess } from "./credentials.js";
+const VERSION_DETAIL_MAX = 200;
+function normalizeVersion(stdout, stderr) {
+    return (stdout || stderr || "").trim().slice(0, VERSION_DETAIL_MAX);
+}
+/**
+ * Collect the executor preflight report. Populates the manifest fields and
+ * accumulates fatal findings — the runner refuses to claim when any exist.
+ */
+export async function collectExecutorPreflight(options, deps, seams = {}) {
+    const fatalFindings = [];
+    const warnings = [];
+    // --- Tooling probes ---------------------------------------------------
+    let wtVersion = "";
+    try {
+        const wt = await deps.runCommand(options.worktrunkBinary, ["--version"]);
+        if (wt.exitCode === 0) {
+            wtVersion = normalizeVersion(wt.stdout, wt.stderr);
+        }
+        else {
+            fatalFindings.push(`Worktrunk binary '${options.worktrunkBinary}' is not available`);
+        }
+    }
+    catch {
+        fatalFindings.push(`Worktrunk binary '${options.worktrunkBinary}' could not be probed`);
+    }
+    try {
+        const git = await deps.runCommand("git", ["--version"]);
+        if (git.exitCode !== 0)
+            fatalFindings.push("git is not available on PATH");
+    }
+    catch {
+        fatalFindings.push("git could not be probed");
+    }
+    let agentVersion = "";
+    try {
+        const claude = await deps.runCommand("claude", ["--version"]);
+        if (claude.exitCode === 0) {
+            agentVersion = normalizeVersion(claude.stdout, claude.stderr);
+        }
+        else {
+            fatalFindings.push("claude (headless agent) is not available on PATH");
+        }
+    }
+    catch {
+        fatalFindings.push("claude could not be probed");
+    }
+    // --- Credentials for every configured repo ----------------------------
+    const access = await resolveAllExecutorApiAccess(options.repos, deps);
+    for (const a of access) {
+        if (!a.ok)
+            fatalFindings.push(`credential resolution failed for repo '${a.repoName}'`);
+    }
+    // --- Disk space (fatal when it cannot be verified) --------------------
+    let diskFreeGb = null;
+    if (!deps.statfs) {
+        fatalFindings.push("disk space could not be verified (statfs unavailable)");
+    }
+    else {
+        try {
+            const fs = await deps.statfs(deps.homedir());
+            diskFreeGb = (fs.bavail * fs.bsize) / 1024 ** 3;
+        }
+        catch {
+            fatalFindings.push("disk space could not be verified (statfs failed)");
+        }
+    }
+    // --- Local gh merge capability (internal-only manifest residue) --------
+    let ghAuthed = false;
+    try {
+        const ghVersion = await deps.runCommand("gh", ["--version"]);
+        if (ghVersion.exitCode === 0) {
+            const ghAuth = await deps.runCommand("gh", ["auth", "status"]);
+            ghAuthed = ghAuth.exitCode === 0;
+        }
+    }
+    catch {
+        ghAuthed = false;
+    }
+    if (!ghAuthed) {
+        warnings.push("local `gh` is unavailable/unauthenticated; local merges would be degraded");
+    }
+    // --- Deny-layer enforcement (binding fatal contract) ------------------
+    let denyEnforced = false;
+    try {
+        const denyProbe = seams.runDenyPreflight ?? runDenyEnforcementPreflight;
+        const deny = await denyProbe();
+        denyEnforced = deny.enforced === true;
+        if (!deny.enforced) {
+            fatalFindings.push(`deny-layer enforcement not verified (enforced=false, layer=${deny.layer}); refusing to claim`);
+        }
+        else if (deny.layer === "none") {
+            // Defensive: an enforced=true with layer "none" is contradictory — treat
+            // as unverifiable, hence fatal.
+            fatalFindings.push("deny-layer enforcement layer is 'none'; cannot verify — refusing to claim");
+        }
+    }
+    catch {
+        fatalFindings.push("deny-layer enforcement probe failed; refusing to claim");
+    }
+    return {
+        ok: fatalFindings.length === 0,
+        fatalFindings,
+        warnings,
+        agentVersion,
+        wtVersion,
+        diskFreeGb,
+        ghAuthed,
+        denyEnforced,
+    };
+}
+/**
+ * Build the HTTP claim manifest — EXACTLY the eight T2-accepted keys. `free_slots`
+ * is supplied by the runner (dynamic). The internal-only `gh` auth capability is
+ * intentionally NOT included (not accepted by the T2 request schema in this slice).
+ */
+export function buildClaimManifest(report, options, freeSlots) {
+    return {
+        repo_name: options.repoName,
+        executor_id: options.executorId,
+        repos: options.repos,
+        agent_version: report.agentVersion,
+        wt_version: report.wtVersion,
+        max_concurrent: options.maxConcurrent,
+        free_slots: freeSlots,
+        disk_free_gb: report.diskFreeGb ?? 0,
+    };
+}

package/build/executor/process.js

@@ -0,0 +1,81 @@
+/** Default retained stdout/stderr excerpt bound (bytes). */
+export const DEFAULT_EXCERPT_BYTES = 8_000;
+/** Default SIGTERM→SIGKILL grace period (ms). */
+export const DEFAULT_TERM_GRACE_MS = 10_000;
+function byteLength(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+function appendBounded(existing, chunk, limitBytes) {
+    if (byteLength(existing) >= limitBytes)
+        return existing;
+    const combined = existing + chunk;
+    if (byteLength(combined) <= limitBytes)
+        return combined;
+    return Buffer.from(combined, "utf8").subarray(0, limitBytes).toString("utf8");
+}
+async function pump(iterable, onChunk) {
+    if (!iterable)
+        return;
+    try {
+        for await (const chunk of iterable) {
+            onChunk(typeof chunk === "string" ? chunk : String(chunk));
+        }
+    }
+    catch {
+        /* stream errors degrade observability, never correctness */
+    }
+}
+/**
+ * Run an owned child process to completion, enforcing `timeoutSeconds` locally.
+ * On timeout: SIGTERM, then SIGKILL after the grace period if still alive;
+ * classification `timeout`. On normal exit: `clean_exit` (code 0) or `crashed`
+ * (non-zero). Retained stdout/stderr excerpts are bounded.
+ */
+export async function runProcessWithTimeout(proc, timeoutSeconds, deps, options = {}) {
+    const termGraceMs = options.termGraceMs ?? DEFAULT_TERM_GRACE_MS;
+    const limit = options.excerptLimitBytes ?? DEFAULT_EXCERPT_BYTES;
+    let stdoutExcerpt = "";
+    let stderrExcerpt = "";
+    const pumpStdout = pump(proc.stdout, (chunk) => {
+        options.onStdout?.(chunk);
+        stdoutExcerpt = appendBounded(stdoutExcerpt, chunk, limit);
+    });
+    const pumpStderr = pump(proc.stderr, (chunk) => {
+        stderrExcerpt = appendBounded(stderrExcerpt, chunk, limit);
+    });
+    let timedOut = false;
+    let graceTimer;
+    const timeoutTimer = deps.setTimer(() => {
+        timedOut = true;
+        proc.kill("SIGTERM");
+        graceTimer = deps.setTimer(() => {
+            // Still alive after the grace period — escalate.
+            proc.kill("SIGKILL");
+        }, termGraceMs);
+    }, timeoutSeconds * 1000);
+    const { exitCode, signal } = await proc.wait();
+    deps.clearTimer(timeoutTimer);
+    if (graceTimer !== undefined)
+        deps.clearTimer(graceTimer);
+    await pumpStdout;
+    await pumpStderr;
+    let classification;
+    if (timedOut) {
+        classification = "timeout";
+    }
+    else if (exitCode === 0) {
+        classification = "clean_exit";
+    }
+    else {
+        classification = "crashed";
+    }
+    return { classification, exitCode, signal, stdoutExcerpt, stderrExcerpt };
+}
+/**
+ * Immediately SIGKILL an owned process for a stale-claim or dead-man abandonment.
+ * Returns a `killed` classification carrying the abandonment reason.
+ */
+export function killOwnedProcess(proc, reason) {
+    proc.kill("SIGKILL");
+    return { classification: "killed", reason };
+}