@oscharko-dev/keiko 0.1.0-beta.0

package/dist/tools/browser/types.d.ts

@@ -0,0 +1,48 @@
+export interface NormalizedNavigateUrl {
+    readonly url: string;
+    readonly host: string;
+    readonly originOnly: string;
+    readonly port: number;
+}
+export interface BrowserViewportPx {
+    readonly width: number;
+    readonly height: number;
+}
+export type BrowserSessionStatus = "open" | "closed";
+export interface BrowserSessionMeta {
+    readonly sessionId: string;
+    readonly cdpPort: number;
+    readonly targetId: string;
+    readonly status: BrowserSessionStatus;
+    readonly createdAt: number;
+}
+export interface BrowserNavigateResult {
+    readonly originOnly: string;
+    readonly httpStatus: number | null;
+}
+export interface BrowserScreenshotPreview {
+    readonly seq: number;
+    readonly viewportPx: BrowserViewportPx;
+    readonly dataBase64: string;
+    readonly persisted: false;
+}
+export interface BrowserScreenshotPersisted {
+    readonly seq: number;
+    readonly viewportPx: BrowserViewportPx;
+    readonly persisted: true;
+    readonly path: string;
+    readonly sha256: string;
+    readonly bytes: number;
+}
+export type BrowserScreenshotResult = BrowserScreenshotPreview | BrowserScreenshotPersisted;
+export interface BrowserContentResult {
+    readonly seq: number;
+    readonly byteLength: number;
+    readonly redactedHtml: string;
+}
+export interface CdpReachability {
+    readonly reachable: boolean;
+    readonly userAgent: string | null;
+    readonly browserVersion: string | null;
+    readonly webSocketDebuggerUrl: string | null;
+}

package/dist/tools/browser/types.js

@@ -0,0 +1,2 @@
+// Data shapes for the browser tool (ADR-0017). Pure types: no runtime imports.
+export {};

package/dist/tools/browser/validators.d.ts

@@ -0,0 +1,5 @@
+import type { NormalizedNavigateUrl } from "./types.js";
+export declare function normalizeCdpPort(value: unknown): number;
+export declare function normalizeNavigateUrl(raw: unknown): NormalizedNavigateUrl;
+export declare function isLoopbackHost(host: string): boolean;
+export declare function isLoopbackUrl(raw: string): boolean;

package/dist/tools/browser/validators.js

@@ -0,0 +1,97 @@
+// ADR-0017 D2 — pure URL validation. NO filesystem, NO network. The localhost→127.0.0.1 rewrite
+// happens here so that downstream code never hands `localhost` to the OS resolver, eliminating the
+// /etc/hosts attack surface even if a downstream caller forgets the rule.
+import { BrowserToolError } from "./errors.js";
+const MIN_PORT = 1024;
+const MAX_PORT = 65535;
+const ALLOWED_SCHEMES = new Set(["http:", "https:"]);
+// Strict literal-host policy: IPv4-mapped IPv6 forms like `::ffff:127.0.0.1` are
+// REJECTED on purpose. ADR-0017 D2 normalises only `localhost`/`127.0.0.1`/`::1`.
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "::1"]);
+export function normalizeCdpPort(value) {
+    if (typeof value !== "number") {
+        throw new BrowserToolError("BAD_PORT", "CDP port must be a number.");
+    }
+    if (!Number.isInteger(value)) {
+        throw new BrowserToolError("BAD_PORT", "CDP port must be an integer.");
+    }
+    if (value < MIN_PORT || value > MAX_PORT) {
+        throw new BrowserToolError("BAD_PORT", `CDP port must be in the range ${String(MIN_PORT)}-${String(MAX_PORT)}.`);
+    }
+    return value;
+}
+// Parses the URL with the WHATWG parser, rejects non-http(s) schemes, rewrites `localhost` to its
+// literal IP before any further use, then enforces literal-IP loopback + bounded-port. Returns the
+// canonical {url, originOnly, host, port} struct the CDP layer consumes.
+export function normalizeNavigateUrl(raw) {
+    if (typeof raw !== "string" || raw.length === 0) {
+        throw new BrowserToolError("BAD_URL", "Navigate URL must be a non-empty string.");
+    }
+    const parsed = parseUrlOrThrow(raw);
+    if (!ALLOWED_SCHEMES.has(parsed.protocol)) {
+        throw new BrowserToolError("SCHEME_NOT_ALLOWED", "Navigate URL must use the http or https scheme.");
+    }
+    const rewritten = rewriteLocalhost(parsed);
+    const host = bareHost(rewritten);
+    if (!LOOPBACK_HOSTS.has(host)) {
+        throw new BrowserToolError("ORIGIN_NOT_ALLOWED", "Navigate URL host must be a loopback literal (127.0.0.1 or ::1).");
+    }
+    if (rewritten.port === "") {
+        throw new BrowserToolError("BAD_PORT", "Navigate URL must include an explicit port.");
+    }
+    const port = normalizeCdpPort(Number.parseInt(rewritten.port, 10));
+    return {
+        url: rewritten.toString(),
+        host,
+        originOnly: rewritten.origin,
+        port,
+    };
+}
+function parseUrlOrThrow(raw) {
+    try {
+        return new URL(raw);
+    }
+    catch {
+        throw new BrowserToolError("BAD_URL", "Navigate URL is not a valid URL.");
+    }
+}
+// `URL.hostname` returns `localhost` unchanged; we rewrite to 127.0.0.1 and rebuild the URL so the
+// canonical .url field handed to CDP never contains `localhost`.
+function rewriteLocalhost(parsed) {
+    if (parsed.hostname !== "localhost")
+        return parsed;
+    const clone = new URL(parsed.toString());
+    clone.hostname = "127.0.0.1";
+    return clone;
+}
+// URL.hostname returns `[::1]` for IPv6 input; strip brackets so the LOOPBACK_HOSTS set comparison
+// is performed against the bare literal `::1`.
+function bareHost(parsed) {
+    const h = parsed.hostname;
+    if (h.startsWith("[") && h.endsWith("]"))
+        return h.slice(1, -1);
+    return h;
+}
+// Narrow host-string check: takes a bare hostname (no scheme, no port, no brackets stripped)
+// and returns true if it is a loopback literal. Used by session.ts to validate the host
+// component of webSocketDebuggerUrl returned by /json/version (ADR-0017 D2 H1).
+export function isLoopbackHost(host) {
+    return LOOPBACK_HOSTS.has(host);
+}
+// Re-check after a navigation completes (ADR-0017 D2 layer 2). The CDP `frameNavigated` event
+// reports the effective URL; if it drifted to a non-loopback origin (server-side redirect), the
+// session manager must stop loading and refuse subsequent capture. Pure: takes the post-navigate
+// URL string and returns the typed result.
+export function isLoopbackUrl(raw) {
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    if (!ALLOWED_SCHEMES.has(parsed.protocol))
+        return false;
+    const host = bareHost(parsed);
+    return LOOPBACK_HOSTS.has(host);
+}

package/dist/tools/errors.d.ts

@@ -0,0 +1,59 @@
+import type { PatchConflict, PatchRejection } from "./types.js";
+export declare const TOOL_CODES: {
+    readonly ARGUMENT: "TOOL_ARGUMENT";
+    readonly UNKNOWN: "TOOL_UNKNOWN";
+    readonly COMMAND_DENIED: "TOOL_COMMAND_DENIED";
+    readonly COMMAND_TIMEOUT: "TOOL_COMMAND_TIMEOUT";
+    readonly COMMAND_CANCELLED: "TOOL_COMMAND_CANCELLED";
+    readonly OUTPUT_LIMIT: "TOOL_OUTPUT_LIMIT";
+    readonly PATCH_INVALID: "TOOL_PATCH_INVALID";
+    readonly PATCH_APPLY_DISABLED: "TOOL_PATCH_APPLY_DISABLED";
+    readonly PATCH_APPLY_FAILED: "TOOL_PATCH_APPLY_FAILED";
+};
+export type ToolCode = (typeof TOOL_CODES)[keyof typeof TOOL_CODES];
+export declare abstract class ToolError extends Error {
+    abstract readonly code: ToolCode;
+    constructor(message: string, secrets?: readonly string[]);
+}
+export declare class ToolArgumentError extends ToolError {
+    readonly code: "TOOL_ARGUMENT";
+    readonly toolName: string;
+    constructor(message: string, toolName: string, secrets?: readonly string[]);
+}
+export declare class UnknownToolError extends ToolError {
+    readonly code: "TOOL_UNKNOWN";
+    readonly toolName: string;
+    constructor(message: string, toolName: string, secrets?: readonly string[]);
+}
+export declare class CommandDeniedError extends ToolError {
+    readonly code: "TOOL_COMMAND_DENIED";
+    readonly executable: string;
+    constructor(message: string, executable: string, secrets?: readonly string[]);
+}
+export declare class CommandTimeoutError extends ToolError {
+    readonly code: "TOOL_COMMAND_TIMEOUT";
+    readonly timeoutMs: number;
+    constructor(message: string, timeoutMs: number, secrets?: readonly string[]);
+}
+export declare class CommandCancelledError extends ToolError {
+    readonly code: "TOOL_COMMAND_CANCELLED";
+}
+export declare class OutputLimitError extends ToolError {
+    readonly code: "TOOL_OUTPUT_LIMIT";
+    readonly limitBytes: number;
+    constructor(message: string, limitBytes: number, secrets?: readonly string[]);
+}
+export declare class PatchValidationError extends ToolError {
+    readonly code: "TOOL_PATCH_INVALID";
+    readonly reasons: readonly PatchRejection[];
+    readonly conflicts: readonly PatchConflict[];
+    constructor(message: string, reasons: readonly PatchRejection[], conflicts: readonly PatchConflict[], secrets?: readonly string[]);
+}
+export declare class PatchApplyDisabledError extends ToolError {
+    readonly code: "TOOL_PATCH_APPLY_DISABLED";
+}
+export declare class PatchApplyError extends ToolError {
+    readonly code: "TOOL_PATCH_APPLY_FAILED";
+    readonly path: string;
+    constructor(message: string, path: string, secrets?: readonly string[]);
+}

package/dist/tools/errors.js

@@ -0,0 +1,94 @@
+// Tool error taxonomy, mirroring gateway/harness/workspace (ADR-0003/0004/0005/0006).
+// Errors carry a stable `code` discriminant; callers switch on `code`, never parse `message`.
+// Every message is redacted at construction so errors are always safe to log or surface.
+import { redact } from "../gateway/redaction.js";
+export const TOOL_CODES = {
+    ARGUMENT: "TOOL_ARGUMENT",
+    UNKNOWN: "TOOL_UNKNOWN",
+    COMMAND_DENIED: "TOOL_COMMAND_DENIED",
+    COMMAND_TIMEOUT: "TOOL_COMMAND_TIMEOUT",
+    COMMAND_CANCELLED: "TOOL_COMMAND_CANCELLED",
+    OUTPUT_LIMIT: "TOOL_OUTPUT_LIMIT",
+    PATCH_INVALID: "TOOL_PATCH_INVALID",
+    PATCH_APPLY_DISABLED: "TOOL_PATCH_APPLY_DISABLED",
+    PATCH_APPLY_FAILED: "TOOL_PATCH_APPLY_FAILED",
+};
+export class ToolError extends Error {
+    constructor(message, secrets = []) {
+        super(redact(message, secrets));
+        this.name = new.target.name;
+    }
+}
+// Malformed tool arguments (a required field missing or of the wrong type).
+export class ToolArgumentError extends ToolError {
+    code = TOOL_CODES.ARGUMENT;
+    toolName;
+    constructor(message, toolName, secrets = []) {
+        super(message, secrets);
+        this.toolName = toolName;
+    }
+}
+// No such tool in the host's dispatch map.
+export class UnknownToolError extends ToolError {
+    code = TOOL_CODES.UNKNOWN;
+    toolName;
+    constructor(message, toolName, secrets = []) {
+        super(message, secrets);
+        this.toolName = toolName;
+    }
+}
+// Executable or subcommand not on the allowlist (deny-by-default). Raised BEFORE any spawn.
+export class CommandDeniedError extends ToolError {
+    code = TOOL_CODES.COMMAND_DENIED;
+    executable;
+    constructor(message, executable, secrets = []) {
+        super(message, secrets);
+        this.executable = executable;
+    }
+}
+// The command exceeded its wall-time budget and was terminated.
+export class CommandTimeoutError extends ToolError {
+    code = TOOL_CODES.COMMAND_TIMEOUT;
+    timeoutMs;
+    constructor(message, timeoutMs, secrets = []) {
+        super(message, secrets);
+        this.timeoutMs = timeoutMs;
+    }
+}
+// Abort-driven cancellation of a command or a patch apply.
+export class CommandCancelledError extends ToolError {
+    code = TOOL_CODES.COMMAND_CANCELLED;
+}
+// A hard output-limit breach (used where truncate-and-flag is not acceptable, e.g. patch input).
+export class OutputLimitError extends ToolError {
+    code = TOOL_CODES.OUTPUT_LIMIT;
+    limitBytes;
+    constructor(message, limitBytes, secrets = []) {
+        super(message, secrets);
+        this.limitBytes = limitBytes;
+    }
+}
+// Patch validation failed; carries the structured rejection reasons. Nothing was written.
+export class PatchValidationError extends ToolError {
+    code = TOOL_CODES.PATCH_INVALID;
+    reasons;
+    conflicts;
+    constructor(message, reasons, conflicts, secrets = []) {
+        super(message, secrets);
+        this.reasons = reasons;
+        this.conflicts = conflicts;
+    }
+}
+// Fail-closed: apply requested while applyEnabled is false. Nothing was written.
+export class PatchApplyDisabledError extends ToolError {
+    code = TOOL_CODES.PATCH_APPLY_DISABLED;
+}
+// A write (or rollback) failed during the apply phase at the filesystem boundary.
+export class PatchApplyError extends ToolError {
+    code = TOOL_CODES.PATCH_APPLY_FAILED;
+    path;
+    constructor(message, path, secrets = []) {
+        super(message, secrets);
+        this.path = path;
+    }
+}

package/dist/tools/exec.d.ts

@@ -0,0 +1,42 @@
+import type { ChildProcess } from "node:child_process";
+import { type WorkspaceFs } from "../workspace/fs.js";
+import type { WorkspaceInfo } from "../workspace/types.js";
+import type { CommandResult, CommandRule, SandboxPolicy } from "./types.js";
+export interface SpawnOptions {
+    readonly cwd: string;
+    readonly env: Record<string, string>;
+    readonly shell: false;
+    readonly detached: boolean;
+}
+export type SpawnFn = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+export interface ExecutableResolverDeps {
+    readonly workspace: WorkspaceInfo;
+    readonly processEnv: NodeJS.ProcessEnv;
+    readonly fs?: WorkspaceFs | undefined;
+}
+export type ExecutableResolver = (command: string, deps: ExecutableResolverDeps) => string;
+export declare const nodeSpawnFn: SpawnFn;
+export interface HomeProvider {
+    readonly make: () => string;
+    readonly cleanup: (dir: string) => void;
+}
+export declare const nodeHomeProvider: HomeProvider;
+export interface RunCommandDeps {
+    readonly workspace: WorkspaceInfo;
+    readonly policy: SandboxPolicy;
+    readonly commandRules: readonly CommandRule[];
+    readonly spawn: SpawnFn;
+    readonly resolveExecutable?: ExecutableResolver | undefined;
+    readonly processEnv: NodeJS.ProcessEnv;
+    readonly now: () => number;
+    readonly fs?: WorkspaceFs | undefined;
+    readonly home?: HomeProvider | undefined;
+}
+export interface RunCommandInput {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly cwd: string | undefined;
+    readonly timeoutMs: number | undefined;
+    readonly signal: AbortSignal;
+}
+export declare function runCommand(input: RunCommandInput, deps: RunCommandDeps): Promise<CommandResult>;

package/dist/tools/exec.js

@@ -0,0 +1,327 @@
+// Command execution — the spawn boundary. Deny-by-default allowlist is checked BEFORE any
+// spawn; the child runs with a clean name-allowlisted env, no shell, and a resolved-in-workspace
+// cwd. Timeout and abort both kill the process group (SIGTERM→SIGKILL after the grace period).
+// stdout/stderr are byte-capped and redacted before they leave this layer (ADR-0006 D3/D5).
+//
+// node:child_process is imported ONLY for the default SpawnFn adapter; all decision logic lives
+// in sandbox.ts (pure). Tests inject a fake SpawnFn for the allowlist/timeout/cancel paths and a
+// real `node`-spawn for the env-isolation / no-shell / real-cancellation integration cases.
+import { spawn as nodeSpawn } from "node:child_process";
+import { accessSync, constants, mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { delimiter, join, resolve as resolvePath } from "node:path";
+import { redact } from "../gateway/redaction.js";
+import { isDenied } from "../workspace/ignore.js";
+import { isWithinWorkspace, resolveWithinWorkspace } from "../workspace/paths.js";
+import { containedRealPathInfo } from "../workspace/realpath.js";
+import { nodeWorkspaceFs } from "../workspace/fs.js";
+import { PathDeniedError } from "../workspace/errors.js";
+import { CommandCancelledError, CommandDeniedError, CommandTimeoutError } from "./errors.js";
+import { buildSandboxEnv, collectSensitiveEnvValues, isCommandAllowed } from "./sandbox.js";
+export const nodeSpawnFn = (command, args, options) => nodeSpawn(command, [...args], options);
+export const nodeHomeProvider = {
+    make: () => mkdtempSync(join(tmpdir(), "keiko-home-")),
+    cleanup: (dir) => {
+        // Best-effort: a leftover temp dir is not worth failing or rejecting the command over.
+        rmSync(dir, { recursive: true, force: true });
+    },
+};
+const POSIX = process.platform !== "win32";
+// Kills the whole process group on POSIX (negative pid) so orphaned grandchildren die too;
+// on Windows, best-effort child.kill() (a tree-kill needs a dependency we cannot add).
+function killGroup(child, sig) {
+    const pid = child.pid;
+    if (pid === undefined) {
+        return;
+    }
+    try {
+        if (POSIX) {
+            process.kill(-pid, sig);
+        }
+        else {
+            child.kill(sig);
+        }
+    }
+    catch {
+        // The child already exited; nothing to signal. Swallowing here keeps termination idempotent.
+    }
+}
+const TRUNCATED_OUTPUT_MARKER = "[TRUNCATED OUTPUT REDACTED]";
+function hasPathSeparator(value) {
+    return value.includes("/") || value.includes("\\");
+}
+function hasNul(value) {
+    return value.includes("\u0000");
+}
+function realRoot(fs, root) {
+    try {
+        return fs.realPath(root);
+    }
+    catch {
+        return root;
+    }
+}
+function assertBareExecutable(command) {
+    if (command.length === 0 || hasNul(command) || hasPathSeparator(command)) {
+        throw new CommandDeniedError("executable must be a bare PATH-resolved name", command);
+    }
+}
+function pathEntries(processEnv) {
+    const pathValue = processEnv.PATH ?? "";
+    return pathValue.length === 0 ? [] : pathValue.split(delimiter).filter(Boolean);
+}
+function executableExtensions(processEnv) {
+    if (process.platform !== "win32") {
+        return [""];
+    }
+    return (processEnv.PATHEXT ?? ".EXE;.CMD;.BAT;.COM")
+        .split(";")
+        .filter((value) => value.length > 0);
+}
+function candidateExecutable(command, rawEntry, ext) {
+    const candidate = resolvePath(resolvePath(rawEntry), command + ext);
+    try {
+        accessSync(candidate, constants.X_OK);
+        return { path: candidate, real: realpathSync(candidate) };
+    }
+    catch {
+        return undefined;
+    }
+}
+function assertExecutableOutsideWorkspace(command, lexicalWorkspaceRoot, realWorkspaceRoot, candidate) {
+    if (isWithinWorkspace(lexicalWorkspaceRoot, candidate.path) ||
+        isWithinWorkspace(realWorkspaceRoot, candidate.real)) {
+        throw new CommandDeniedError(`executable resolves inside workspace: ${command}`, command);
+    }
+}
+function defaultResolveExecutable(command, deps) {
+    assertBareExecutable(command);
+    const fs = deps.fs ?? nodeWorkspaceFs;
+    const lexicalWorkspaceRoot = deps.workspace.root;
+    const realWorkspaceRoot = realRoot(fs, lexicalWorkspaceRoot);
+    for (const rawEntry of pathEntries(deps.processEnv)) {
+        for (const ext of executableExtensions(deps.processEnv)) {
+            const candidate = candidateExecutable(command, rawEntry, ext);
+            if (candidate === undefined) {
+                continue;
+            }
+            assertExecutableOutsideWorkspace(command, lexicalWorkspaceRoot, realWorkspaceRoot, candidate);
+            return candidate.real;
+        }
+    }
+    throw new CommandDeniedError(`executable not found on PATH: ${command}`, command);
+}
+function appendCapped(buffers, sink, chunk, max) {
+    if (buffers.truncated) {
+        return false;
+    }
+    const remaining = max - buffers.total;
+    if (chunk.length <= remaining) {
+        sink.push(chunk);
+        buffers.total += chunk.length;
+        return false;
+    }
+    if (remaining > 0) {
+        sink.push(chunk.subarray(0, remaining));
+        buffers.total = max;
+    }
+    buffers.truncated = true;
+    return true; // signals the caller to kill the child (flood protection)
+}
+// Resolves the validated cwd. Lexical containment first, then symlink containment via realpath
+// (S-H1): a cwd that is a symlink escaping the root or resolving into an always-denied path must
+// not become the spawn cwd. Both cases surface as workspace path errors, which the host maps to a
+// tool error — the command never spawns.
+function resolveCwd(deps, cwd) {
+    const lexical = resolveWithinWorkspace(deps.workspace.root, cwd ?? ".");
+    const fs = deps.fs ?? nodeWorkspaceFs;
+    const rel = lexical.slice(deps.workspace.root.length).replace(/^[/\\]/, "");
+    if (isDenied(rel === "" ? (cwd ?? ".") : rel)) {
+        throw new PathDeniedError("path matches an always-on deny pattern", cwd ?? ".");
+    }
+    const info = containedRealPathInfo(fs, deps.workspace.root, lexical);
+    if (isDenied(info.realRelative)) {
+        throw new PathDeniedError("path matches an always-on deny pattern", cwd ?? ".");
+    }
+    return lexical;
+}
+function buildResult(input, buffers, state, exitCode, termSignal, deps, startedAt) {
+    const secrets = collectSensitiveEnvValues(deps.processEnv, deps.policy.envAllowlist);
+    if (buffers.truncated) {
+        return {
+            command: input.command,
+            args: input.args,
+            exitCode,
+            signal: termSignal,
+            stdout: TRUNCATED_OUTPUT_MARKER,
+            stderr: TRUNCATED_OUTPUT_MARKER,
+            durationMs: deps.now() - startedAt,
+            timedOut: state.timedOut,
+            truncated: true,
+        };
+    }
+    return {
+        command: input.command,
+        args: input.args,
+        exitCode,
+        signal: termSignal,
+        stdout: redact(Buffer.concat(buffers.out).toString("utf8"), secrets),
+        stderr: redact(Buffer.concat(buffers.err).toString("utf8"), secrets),
+        durationMs: deps.now() - startedAt,
+        timedOut: state.timedOut,
+        truncated: buffers.truncated,
+    };
+}
+function cleanup(state, signal) {
+    if (state.timer !== undefined) {
+        clearTimeout(state.timer);
+    }
+    if (state.graceTimer !== undefined) {
+        clearTimeout(state.graceTimer);
+    }
+    if (state.onAbort !== undefined) {
+        signal.removeEventListener("abort", state.onAbort);
+    }
+    // Remove the ephemeral HOME exactly once, on whichever settle path fires first (C5).
+    if (!state.homeCleaned && state.home !== undefined && state.homeDir !== undefined) {
+        state.homeCleaned = true;
+        state.home.cleanup(state.homeDir);
+    }
+}
+// Escalates from SIGTERM to SIGKILL after the grace period so a child ignoring SIGTERM is still
+// guaranteed to terminate within terminationGraceMs of the trigger.
+function terminate(child, policy, state) {
+    killGroup(child, "SIGTERM");
+    state.graceTimer = setTimeout(() => {
+        killGroup(child, "SIGKILL");
+    }, policy.terminationGraceMs);
+    state.graceTimer.unref();
+}
+function wireStreams(child, buffers, policy, state) {
+    const onData = (sink) => (chunk) => {
+        if (appendCapped(buffers, sink, chunk, policy.maxOutputBytes)) {
+            terminate(child, policy, state); // output flood → kill
+        }
+    };
+    child.stdout?.on("data", onData(buffers.out));
+    child.stderr?.on("data", onData(buffers.err));
+}
+function settleOnClose(ctx, resolve, reject) {
+    ctx.child.on("close", (code, signalName) => {
+        if (ctx.state.settled) {
+            return;
+        }
+        ctx.state.settled = true;
+        cleanup(ctx.state, ctx.input.signal);
+        if (ctx.state.timedOut) {
+            reject(new CommandTimeoutError("command timed out", timeoutOf(ctx)));
+            return;
+        }
+        if (ctx.input.signal.aborted) {
+            reject(new CommandCancelledError("command cancelled"));
+            return;
+        }
+        resolve(buildResult(ctx.input, ctx.buffers, ctx.state, code, signalName, ctx.deps, ctx.startedAt));
+    });
+    ctx.child.on("error", (error) => {
+        if (ctx.state.settled) {
+            return;
+        }
+        ctx.state.settled = true;
+        cleanup(ctx.state, ctx.input.signal);
+        reject(error);
+    });
+}
+function timeoutOf(ctx) {
+    return ctx.input.timeoutMs ?? ctx.deps.policy.defaultTimeoutMs;
+}
+function armTimersAndAbort(ctx) {
+    const ms = timeoutOf(ctx);
+    ctx.state.timer = setTimeout(() => {
+        ctx.state.timedOut = true;
+        terminate(ctx.child, ctx.deps.policy, ctx.state);
+    }, ms);
+    ctx.state.timer.unref();
+    const onAbort = () => {
+        terminate(ctx.child, ctx.deps.policy, ctx.state);
+    };
+    ctx.state.onAbort = onAbort;
+    if (ctx.input.signal.aborted) {
+        onAbort();
+    }
+    else {
+        ctx.input.signal.addEventListener("abort", onAbort, { once: true });
+    }
+}
+function asError(error, fallback) {
+    return error instanceof Error ? error : new Error(fallback);
+}
+function validateRunCommandInput(input, deps) {
+    if (!Array.isArray(deps.policy.envAllowlist) || deps.policy.envAllowlist.length === 0) {
+        throw new CommandDeniedError("sandbox envAllowlist must be a non-empty array", input.command);
+    }
+    const decision = isCommandAllowed(deps.commandRules, input.command, input.args);
+    if (!decision.allowed) {
+        throw new CommandDeniedError(decision.reason ?? "command denied", input.command);
+    }
+}
+function resolveExecutable(input, deps) {
+    const resolver = deps.resolveExecutable ?? defaultResolveExecutable;
+    return resolver(input.command, {
+        workspace: deps.workspace,
+        processEnv: deps.processEnv,
+        fs: deps.fs,
+    });
+}
+function createRunState(home, homeDir) {
+    return {
+        settled: false,
+        timedOut: false,
+        timer: undefined,
+        graceTimer: undefined,
+        onAbort: undefined,
+        home,
+        homeDir,
+        homeCleaned: false,
+    };
+}
+function spawnChild(input, deps, executable, cwd, env, state) {
+    try {
+        return deps.spawn(executable, input.args, { cwd, env, shell: false, detached: POSIX });
+    }
+    catch (error) {
+        cleanup(state, input.signal);
+        throw asError(error, "spawn failed");
+    }
+}
+function runSpawnedChild(ctx) {
+    return new Promise((resolve, reject) => {
+        wireStreams(ctx.child, ctx.buffers, ctx.deps.policy, ctx.state);
+        settleOnClose(ctx, resolve, reject);
+        armTimersAndAbort(ctx);
+    });
+}
+// Runs an allowlisted command. Rejects with CommandDeniedError (before spawn) for a denied
+// command or a workspace-escaping cwd (PathEscapeError), CommandTimeoutError on timeout, and
+// CommandCancelledError on abort; otherwise resolves a redacted, byte-capped CommandResult. All
+// failure paths are Promise rejections — the function never throws synchronously.
+export function runCommand(input, deps) {
+    try {
+        validateRunCommandInput(input, deps);
+        const executable = resolveExecutable(input, deps);
+        const cwd = resolveCwd(deps, input.cwd);
+        const env = buildSandboxEnv(deps.processEnv, deps.policy.envAllowlist);
+        const home = deps.home ?? nodeHomeProvider;
+        const homeDir = home.make();
+        env.HOME = homeDir;
+        env.USERPROFILE = homeDir;
+        const state = createRunState(home, homeDir);
+        const child = spawnChild(input, deps, executable, cwd, env, state);
+        const buffers = { out: [], err: [], total: 0, truncated: false };
+        const ctx = { child, input, deps, buffers, state, startedAt: deps.now() };
+        return runSpawnedChild(ctx);
+    }
+    catch (error) {
+        return Promise.reject(asError(error, "command execution failed"));
+    }
+}