@wardby/cli 0.6.0 → 0.7.0

package/dist/native-worker/protocol.js

@@ -11,7 +11,11 @@
  * child process's stdio, and (phase 3) over HTTP.
  */
 import { z } from "zod";
+import { causeCodeOf, GATEWAY_CAUSE_CODES } from "../core/error-code.js";
 import { LLM_EFFORT_LEVELS } from "../providers/llm/types.js";
+import { overlapsSecretValue } from "../sandbox/host-functions.js";
+// The allow-list and its checked helper live in core/error-code.ts (shared with the runner); re-exported here.
+export { causeCodeOf, GATEWAY_CAUSE_CODES };
 export const NATIVE_WORKER_PROTOCOL_VERSION = 1;
 /** Above the sandbox's 12 MiB bridge-result cap, plus envelope. */
 export const MAX_MESSAGE_BYTES = 16 * 1024 * 1024;
@@ -25,12 +29,54 @@ export class ProtocolError extends Error {
 }
 export class GatewayError extends Error {
     code;
-    constructor(code, message) {
+    causeCode;
+    constructor(code, message, 
+    /**
+     * For `internal` only: the code the underlying error's message led with (causeCodeOf), so the
+     * run can name the cause without the rest of that message.
+     */
+    causeCode) {
         super(message);
         this.code = code;
+        this.causeCode = causeCode;
         this.name = "GatewayError";
     }
 }
+/** What the worker is told about an unexpected gateway failure: never the error's own text. */
+export const GATEWAY_INTERNAL_MESSAGE = "The gateway could not serve this call.";
+/**
+ * `err` as the worker may see it, on every transport (HTTP, stdio, loopback). An unexpected error
+ * becomes `internal` with the generic message; a GatewayError keeps its code and message. A cause
+ * code is carried only when it is declared (GATEWAY_CAUSE_CODES) and checked: not when it equals, contains, or is contained in a secret
+ * value the run can read (`secretValues`, read only when there is a code to check), and not at
+ * all when there is nothing to check it against or reading the values fails.
+ */
+export async function workerGatewayError(err, secretValues) {
+    const leading = err instanceof GatewayError ? err.causeCode : causeCodeOf(err);
+    // Declared codes only; the exact-value check below is a second guard.
+    const candidate = leading && GATEWAY_CAUSE_CODES.has(leading) ? leading : undefined;
+    let causeCode;
+    if (candidate && secretValues) {
+        const values = await secretValues().catch(() => undefined);
+        if (values && !overlapsSecretValue(candidate, values))
+            causeCode = candidate;
+    }
+    if (err instanceof GatewayError)
+        return new GatewayError(err.code, err.message, causeCode);
+    return new GatewayError("internal", causeCode ? `The gateway could not serve this call (${causeCode}).` : GATEWAY_INTERNAL_MESSAGE, causeCode);
+}
+/**
+ * `err` as a transport carries it to the worker: a GatewayError (already checked by the gateway
+ * that threw it) as is, with a declared cause code only; anything else `internal` with the generic message and no cause code, since
+ * a transport has no secret values to check one against.
+ */
+export function toGatewayError(err) {
+    if (err instanceof GatewayError) {
+        const causeCode = err.causeCode && GATEWAY_CAUSE_CODES.has(err.causeCode) ? err.causeCode : undefined;
+        return new GatewayError(err.code, err.message, causeCode);
+    }
+    return new GatewayError("internal", GATEWAY_INTERNAL_MESSAGE);
+}
 const runId = z.string().min(1).max(64);
 const callId = z.string().min(1).max(128);
 const LlmMessageSchema = z

package/dist/native-worker/sandbox-executor.d.ts

@@ -7,8 +7,10 @@
  *   worker, and returns. Whichever gateway replica serves the worker's
  *   `finish` makes the terminal write; this executor only watches for a
  *   worker that exits without one, and for its deadline.
- * - stop: ends the session (every further gateway call is refused), kills the
- *   worker, records the run cancelled, and stops its open delegations.
+ * - stop: records the run cancelled, ends the session (every further gateway
+ *   call is refused, so the worker exits at its next one), gives the worker a
+ *   short grace to exit, then kills and removes it (a warm pool worker is
+ *   discarded, never reused), and stops its open delegations.
  * - recover: answers the reconciler from the worker's container state, and
  *   never launches one.
  * - launch: the janitor removes workers whose runs have ended.
@@ -43,8 +45,15 @@ export interface NativeSandboxExecutorOptions {
     gatewayUrl: string;
     /** NATIVE_SANDBOX_MAX_CONCURRENT: a start past this many active sessions fails with native_sandbox_capacity. */
     maxConcurrent?: number;
+    /** How long a stopped run's worker gets to exit on its own before it is killed (default NATIVE_SANDBOX_STOP_GRACE_MS). */
+    stopGraceMs?: number;
+    /** How often a launching run's heartbeat is refreshed (default a third of HEARTBEAT_TIMEOUT_MS). */
+    heartbeatIntervalMs?: number;
     now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
 }
+/** A stopped sandbox run's worker exits at its next (refused) gateway call; past this it is killed. */
+export declare const NATIVE_SANDBOX_STOP_GRACE_MS = 5000;
 export declare const NATIVE_SANDBOX_WORKER_EXITED = "native_sandbox_worker_exited";
 export declare const NATIVE_SANDBOX_DEADLINE = "native_sandbox_deadline_exceeded";
 export declare class NativeSandboxExecutor implements Executor {
@@ -56,11 +65,17 @@ export declare class NativeSandboxExecutor implements Executor {
     private now;
     private finishContext;
     start(runId: string): Promise<void>;
+    /** Refreshes a still-live run's heartbeat while `work` runs. */
+    private whileHeartbeating;
+    /** The run is still live and its session open: a worker launched now would have work to do. */
+    private stillWanted;
     /** Watches one worker in this process: its exit, and its deadline. */
     private watch;
     private onWorkerExit;
     private endSession;
     stop(runId: string, reason?: string): Promise<void>;
+    /** Waits up to stopGraceMs for the run's worker to exit or be gone; false when it still runs. Never throws. */
+    private awaitWorkerExit;
     recover(handle: PersistedExecutionHandle): Promise<ExecutionRecoveryResult>;
     /** Startup janitor: removes worker containers whose runs have ended or passed their deadline. Starts the warm pool. */
     launch(): Promise<void>;

package/dist/native-worker/sandbox-executor.js

@@ -7,8 +7,10 @@
  *   worker, and returns. Whichever gateway replica serves the worker's
  *   `finish` makes the terminal write; this executor only watches for a
  *   worker that exits without one, and for its deadline.
- * - stop: ends the session (every further gateway call is refused), kills the
- *   worker, records the run cancelled, and stops its open delegations.
+ * - stop: records the run cancelled, ends the session (every further gateway
+ *   call is refused, so the worker exits at its next one), gives the worker a
+ *   short grace to exit, then kills and removes it (a warm pool worker is
+ *   discarded, never reused), and stops its open delegations.
  * - recover: answers the reconciler from the worker's container state, and
  *   never launches one.
  * - launch: the janitor removes workers whose runs have ended.
@@ -16,11 +18,14 @@
 import { logger } from "../core/logger.js";
 import { failNativeRun, nativeRunIntegrations, RunCancelledError, NATIVE_SANDBOX_BACKEND, } from "../core/runner.js";
 import { nativeRunLabel } from "./docker-isolation.js";
+import { HEARTBEAT_TIMEOUT_MS } from "../core/timing.js";
 import { startSandboxRun } from "./launch.js";
 import { NATIVE_SANDBOX_CAPACITY } from "./kubernetes-launcher.js";
 import { PrismaGatewayLedger } from "./ledger.js";
 const executorLog = logger.child({ module: "native-sandbox-executor" });
 const isUniqueViolation = (err) => typeof err === "object" && err !== null && err.code === "P2002";
+/** A stopped sandbox run's worker exits at its next (refused) gateway call; past this it is killed. */
+export const NATIVE_SANDBOX_STOP_GRACE_MS = 5_000;
 export const NATIVE_SANDBOX_WORKER_EXITED = "native_sandbox_worker_exited";
 export const NATIVE_SANDBOX_DEADLINE = "native_sandbox_deadline_exceeded";
 export class NativeSandboxExecutor {
@@ -56,7 +61,17 @@ export class NativeSandboxExecutor {
         let outcome;
         try {
             const url = launcher.resolveGatewayUrl ? await launcher.resolveGatewayUrl() : gatewayUrl;
-            outcome = await startSandboxRun({ runId, providers, db, gatewayUrl: url, launcher });
+            // A cold launch (a low-power gateway wake, a sandbox node scale-up) can outlast the reconciler's
+            // heartbeat timeout, and the worker has no pod to find yet: beat for it until it exists. The
+            // launch's own timeouts bound this (wake, pod ready, isolation proof), each failing the run.
+            outcome = await this.whileHeartbeating(runId, () => startSandboxRun({
+                runId,
+                providers,
+                db,
+                gatewayUrl: url,
+                launcher,
+                stillWanted: () => this.stillWanted(runId),
+            }));
         }
         catch (err) {
             // A concurrent start won the race for the run's one session: attach to its worker.
@@ -78,6 +93,42 @@ export class NativeSandboxExecutor {
         });
         this.watch(runId, outcome.handle, session.deadlineAt);
     }
+    /** Refreshes a still-live run's heartbeat while `work` runs. */
+    async whileHeartbeating(runId, work) {
+        const beat = () => this.options.db.run
+            .updateMany({
+            where: { id: runId, status: { in: ["pending", "running"] } },
+            data: { heartbeatAt: new Date(this.now()) },
+        })
+            .catch((err) => executorLog.warn({ err, runId }, "could not refresh a launching run's heartbeat"));
+        // At most one beat in flight: a tick while one is pending is skipped. Overlapping beats could
+        // commit out of order, and only the last one sent would be awaited below.
+        let inFlight;
+        const timer = setInterval(() => {
+            inFlight ??= beat().finally(() => {
+                inFlight = undefined;
+            });
+        }, this.options.heartbeatIntervalMs ?? Math.floor(HEARTBEAT_TIMEOUT_MS / 3));
+        // Never hold the process open for a heartbeat: shutdown should not wait on one.
+        timer.unref?.();
+        try {
+            return await work();
+        }
+        finally {
+            clearInterval(timer);
+            // The beat in flight, if any, lands before the launch returns, never after the worker's own beats.
+            await inFlight;
+        }
+    }
+    /** The run is still live and its session open: a worker launched now would have work to do. */
+    async stillWanted(runId) {
+        const { db } = this.options;
+        const [run, session] = await Promise.all([
+            db.run.findUnique({ where: { id: runId }, select: { status: true } }),
+            db.nativeGatewaySession.findUnique({ where: { runId }, select: { status: true } }),
+        ]);
+        return !!run && (run.status === "pending" || run.status === "running") && session?.status === "active";
+    }
     /** Watches one worker in this process: its exit, and its deadline. */
     watch(runId, handle, deadlineAt) {
         if (this.watching.has(runId))
@@ -129,8 +180,14 @@ export class NativeSandboxExecutor {
         // worker exit, and its exit watcher must then find the run already ended (and leave it
         // cancelled) rather than record the exit as a failure.
         await failNativeRun(this.finishContext(runId), new RunCancelledError(reason ?? "The run was cancelled."));
+        // The stop reaches the worker through the gateway: with its run cancelled and its session ended,
+        // its next call (a model turn, a tool, its result) is refused and it exits on its own. It gets a
+        // bounded grace for that, then is killed either way.
         const sessionId = await this.endSession(runId, "cancelled");
-        await this.options.launcher.kill(runId).catch(() => { });
+        if (!(await this.awaitWorkerExit(runId))) {
+            executorLog.info({ runId }, "a stopped sandbox run's worker did not exit within its grace; killing it");
+            await this.options.launcher.kill(runId).catch(() => { });
+        }
         if (sessionId) {
             // Its delegations' children belong to the server's executor; a child left running would
             // spend on behalf of a parent that no longer waits for it.
@@ -140,8 +197,25 @@ export class NativeSandboxExecutor {
                 });
             }
         }
+        // Removed, never returned to a warm pool: a claimed pool worker is discarded with its row.
         await this.options.launcher.remove(runId).catch(() => { });
     }
+    /** Waits up to stopGraceMs for the run's worker to exit or be gone; false when it still runs. Never throws. */
+    async awaitWorkerExit(runId) {
+        const graceMs = this.options.stopGraceMs ?? NATIVE_SANDBOX_STOP_GRACE_MS;
+        const sleep = this.options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        const until = this.now() + graceMs;
+        for (;;) {
+            const state = await this.options.launcher.inspect(runId).catch(() => undefined);
+            // An unreadable state counts as still running: the kill below is the safe default.
+            if (state && state.state !== "running")
+                return true;
+            const left = until - this.now();
+            if (left <= 0)
+                return false;
+            await sleep(Math.min(250, left));
+        }
+    }
     async recover(handle) {
         if (handle.backend !== NATIVE_SANDBOX_BACKEND) {
             return { state: "lost", reason: `NativeSandboxExecutor cannot recover backend "${handle.backend}".` };

package/dist/native-worker/stderr-redaction.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The sandbox worker's stderr is not a redacted channel by itself: a failed worker's stderr tail
+ * reaches the server's log (docker-launcher.ts, kubernetes-launcher.ts; the launcher masks it
+ * again, as the worker is untrusted), and a tool's host calls hand the worker secret
+ * values (`secrets.get`). The worker knows those exact values (raw and JSON-escaped), so it masks
+ * them in everything it writes to stderr — its own failure line and the shared logger's lines —
+ * with the shared redactor's spans (secretSpans: the union of every occurrence, overlapping ones
+ * included, minimum length included). One set per worker process.
+ *
+ * process.stderr writes are buffered (StderrRedactionBuffer), because a value may arrive split
+ * across writes. A string is matched as text, whatever encoding it was written with (its trailing
+ * high surrogate is held for the next write, so a split surrogate pair still matches); a hex or
+ * base64 string and any ArrayBufferView go through one UTF-8 byte decoder; any other chunk type is
+ * refused, never written raw. Emitted text is written as UTF-8. On each write the buffer:
+ * 1. holds back `hold`: the longest suffix of the buffer that is a proper prefix of a remembered
+ *    value, since those characters could still become a value;
+ * 2. picks a cut `c` <= length − hold: after the last "\n" there, or, once the text after that
+ *    exceeds MAX_PENDING_STDERR_CHARS, at length − hold; otherwise it emits nothing yet;
+ * 3. masks spans over the whole buffer, with its first `maskedLead` characters forced into a span;
+ * 4. when `c` falls inside a span [s, e), emits [s, c) as the marker and carries `maskedLead` =
+ *    e − c, so the rest of that span is masked when it is emitted later;
+ * 5. emits the masked text before `c` and keeps the rest.
+ * Masking is safe at any cut, so no cut is ever searched for. On exit, SIGTERM/SIGINT and the
+ * worker's fail path the remainder is emitted with its spans, `maskedLead` and the held suffix all
+ * masked: fail closed, a possible value start is emitted as `[REDACTED]`, never raw.
+ *
+ * Why no value character is emitted: an occurrence that begins before `c` either ends within the
+ * buffer (it is a span, masked here, and its part past `c` is carried as `maskedLead`) or runs
+ * past the buffer's end, in which case the text from its start to the end is a proper prefix of
+ * the value, so `hold` >= length − start and `c` <= its start, a contradiction. By induction over
+ * writes, every character emitted that belongs to an occurrence is inside a masked span.
+ *
+ * The shared logger does not write through process.stderr: pino serializes each log call to one
+ * whole line (ending in "\n") and hands that line to its `streamWrite` hook before writing it to
+ * fd 2 itself, so the line filter below (the shared redactor) sees whole lines.
+ */
+/** Records a secret value this process received, and its JSON-escaped form (as a log line holds it). */
+export declare function rememberSecretValue(value: string): void;
+/** `text` without any secret value this process received. */
+export declare function redactReceivedSecrets(text: string): string;
+/**
+ * Text after the last "\n" longer than this (64 KiB) is emitted without waiting for its "\n", so an
+ * unterminated stream cannot grow the buffer without bound: it stays within this plus the longest
+ * remembered value plus one write.
+ */
+export declare const MAX_PENDING_STDERR_CHARS: number;
+/**
+ * The stderr buffer as a value: text in (`write`), masked text out, never a remembered value's
+ * character unmasked (see the module comment). `values` is read on every call, so a value
+ * remembered later applies to what is still buffered.
+ */
+export declare class StderrRedactionBuffer {
+    private readonly values;
+    private readonly bound;
+    private pending;
+    private maskedLead;
+    private atLineStart;
+    constructor(values: () => readonly string[], bound?: number);
+    /** Characters still buffered. */
+    get pendingLength(): number;
+    /** Adds `text` and returns what may be emitted now (possibly ""). */
+    write(text: string): string;
+    /**
+     * Everything still buffered, masked, fail closed (the held suffix too), ending with "\n" if output
+     * is mid-line. `maskTail` masks one more character at the end: a write's trailing lone high
+     * surrogate that never got its low half.
+     */
+    flush(maskTail?: boolean): string;
+    private redactable;
+    /** Spans over the whole buffer, the carried `maskedLead` and any `extra` forced in. */
+    private spans;
+    private emitted;
+}
+/** Emits the buffered remainder, masked fail closed and ended with "\n". Safe to call any number of times. */
+export declare function flushStderrRedaction(): void;
+/** Routes process.stderr writes through the buffer, and the shared logger's lines through redactReceivedSecrets. */
+export declare function installStderrRedaction(): void;

package/dist/native-worker/stderr-redaction.js

@@ -0,0 +1,237 @@
+/**
+ * The sandbox worker's stderr is not a redacted channel by itself: a failed worker's stderr tail
+ * reaches the server's log (docker-launcher.ts, kubernetes-launcher.ts; the launcher masks it
+ * again, as the worker is untrusted), and a tool's host calls hand the worker secret
+ * values (`secrets.get`). The worker knows those exact values (raw and JSON-escaped), so it masks
+ * them in everything it writes to stderr — its own failure line and the shared logger's lines —
+ * with the shared redactor's spans (secretSpans: the union of every occurrence, overlapping ones
+ * included, minimum length included). One set per worker process.
+ *
+ * process.stderr writes are buffered (StderrRedactionBuffer), because a value may arrive split
+ * across writes. A string is matched as text, whatever encoding it was written with (its trailing
+ * high surrogate is held for the next write, so a split surrogate pair still matches); a hex or
+ * base64 string and any ArrayBufferView go through one UTF-8 byte decoder; any other chunk type is
+ * refused, never written raw. Emitted text is written as UTF-8. On each write the buffer:
+ * 1. holds back `hold`: the longest suffix of the buffer that is a proper prefix of a remembered
+ *    value, since those characters could still become a value;
+ * 2. picks a cut `c` <= length − hold: after the last "\n" there, or, once the text after that
+ *    exceeds MAX_PENDING_STDERR_CHARS, at length − hold; otherwise it emits nothing yet;
+ * 3. masks spans over the whole buffer, with its first `maskedLead` characters forced into a span;
+ * 4. when `c` falls inside a span [s, e), emits [s, c) as the marker and carries `maskedLead` =
+ *    e − c, so the rest of that span is masked when it is emitted later;
+ * 5. emits the masked text before `c` and keeps the rest.
+ * Masking is safe at any cut, so no cut is ever searched for. On exit, SIGTERM/SIGINT and the
+ * worker's fail path the remainder is emitted with its spans, `maskedLead` and the held suffix all
+ * masked: fail closed, a possible value start is emitted as `[REDACTED]`, never raw.
+ *
+ * Why no value character is emitted: an occurrence that begins before `c` either ends within the
+ * buffer (it is a span, masked here, and its part past `c` is carried as `maskedLead`) or runs
+ * past the buffer's end, in which case the text from its start to the end is a proper prefix of
+ * the value, so `hold` >= length − start and `c` <= its start, a contradiction. By induction over
+ * writes, every character emitted that belongs to an occurrence is inside a masked span.
+ *
+ * The shared logger does not write through process.stderr: pino serializes each log call to one
+ * whole line (ending in "\n") and hands that line to its `streamWrite` hook before writing it to
+ * fd 2 itself, so the line filter below (the shared redactor) sees whole lines.
+ */
+import { StringDecoder } from "node:string_decoder";
+import { setLogLineFilter } from "../core/logger.js";
+import { maskSpans, mergeSpans, MIN_REDACTABLE_SECRET_LENGTH, redactExactSecretValues, secretSpans, withEscapedForms, } from "../core/secret-spans.js";
+const received = new Set();
+/** Records a secret value this process received, and its JSON-escaped form (as a log line holds it). */
+export function rememberSecretValue(value) {
+    for (const form of withEscapedForms([value]))
+        received.add(form);
+}
+/** `text` without any secret value this process received. */
+export function redactReceivedSecrets(text) {
+    return received.size === 0 ? text : redactExactSecretValues(text, received);
+}
+/**
+ * Text after the last "\n" longer than this (64 KiB) is emitted without waiting for its "\n", so an
+ * unterminated stream cannot grow the buffer without bound: it stays within this plus the longest
+ * remembered value plus one write.
+ */
+export const MAX_PENDING_STDERR_CHARS = 64 * 1024;
+/** The longest suffix of `text` that is a proper prefix of one of `values`. */
+function heldLength(text, values) {
+    let hold = 0;
+    for (const value of values) {
+        for (let k = Math.min(value.length - 1, text.length); k > hold; k -= 1) {
+            if (text.charCodeAt(text.length - k) === value.charCodeAt(0) && text.endsWith(value.slice(0, k))) {
+                hold = k;
+                break;
+            }
+        }
+    }
+    return hold;
+}
+/**
+ * The stderr buffer as a value: text in (`write`), masked text out, never a remembered value's
+ * character unmasked (see the module comment). `values` is read on every call, so a value
+ * remembered later applies to what is still buffered.
+ */
+export class StderrRedactionBuffer {
+    values;
+    bound;
+    pending = "";
+    maskedLead = 0;
+    atLineStart = true;
+    constructor(values, bound = MAX_PENDING_STDERR_CHARS) {
+        this.values = values;
+        this.bound = bound;
+    }
+    /** Characters still buffered. */
+    get pendingLength() {
+        return this.pending.length;
+    }
+    /** Adds `text` and returns what may be emitted now (possibly ""). */
+    write(text) {
+        this.pending += text;
+        const values = this.redactable();
+        const hold = heldLength(this.pending, values);
+        const limit = this.pending.length - hold;
+        // (lastIndexOf treats a negative start as 0, so an empty window is checked first.)
+        let cut = limit > 0 ? this.pending.lastIndexOf("\n", limit - 1) + 1 : 0;
+        if (this.pending.length - cut > this.bound)
+            cut = limit;
+        if (cut <= 0)
+            return "";
+        const spans = this.spans(values, []);
+        const inside = spans.find(([start, end]) => start < cut && cut < end);
+        this.maskedLead = inside ? inside[1] - cut : 0;
+        const ready = maskSpans(this.pending.slice(0, cut), spans.filter(([start]) => start < cut).map(([start, end]) => [start, Math.min(end, cut)]));
+        this.pending = this.pending.slice(cut);
+        return this.emitted(ready);
+    }
+    /**
+     * Everything still buffered, masked, fail closed (the held suffix too), ending with "\n" if output
+     * is mid-line. `maskTail` masks one more character at the end: a write's trailing lone high
+     * surrogate that never got its low half.
+     */
+    flush(maskTail = false) {
+        if (maskTail)
+            this.pending += "\uFFFD";
+        const values = this.redactable();
+        const text = this.pending;
+        const hold = heldLength(text, values);
+        const extra = [];
+        if (hold > 0)
+            extra.push([text.length - hold, text.length]);
+        if (maskTail)
+            extra.push([text.length - 1, text.length]);
+        const out = maskSpans(text, this.spans(values, extra));
+        this.pending = "";
+        this.maskedLead = 0;
+        const ready = this.emitted(out);
+        if (this.atLineStart)
+            return ready;
+        this.atLineStart = true;
+        return `${ready}\n`;
+    }
+    redactable() {
+        return this.values().filter((value) => value.length >= MIN_REDACTABLE_SECRET_LENGTH);
+    }
+    /** Spans over the whole buffer, the carried `maskedLead` and any `extra` forced in. */
+    spans(values, extra) {
+        const forced = this.maskedLead > 0 ? [[0, this.maskedLead], ...extra] : extra;
+        return mergeSpans([...secretSpans(this.pending, values), ...forced]);
+    }
+    emitted(text) {
+        if (text)
+            this.atLineStart = text.endsWith("\n");
+        return text;
+    }
+}
+const buffer = new StderrRedactionBuffer(() => [...received]);
+let installed = false;
+let rawWrite;
+const bytes = new StringDecoder("utf8");
+/**
+ * A string write's trailing high surrogate, held for the next write: encoded alone it would become
+ * U+FFFD, and a value whose non-BMP character is split between two writes would never match.
+ */
+let heldHighSurrogate = "";
+const isHighSurrogate = (code) => code >= 0xd800 && code <= 0xdbff;
+/** String encodings that name bytes rather than text: such a string is decoded to its bytes first. */
+const BYTE_STRING_ENCODINGS = new Set(["hex", "base64", "base64url"]);
+/**
+ * `chunk` as text for the buffer. A string is matched as the JavaScript string itself, whatever
+ * text encoding it was written with (utf16le, latin1, ...): re-encoding it and decoding the bytes as
+ * UTF-8 would turn an ASCII value into one with NULs that never matches. Its trailing high surrogate
+ * is held for the next write. A hex or base64 string, and any ArrayBufferView, goes through the one
+ * byte decoder. Any other chunk type throws (after emitting a held surrogate masked).
+ */
+function decodeChunk(chunk, encoding) {
+    if (typeof chunk === "string" && !BYTE_STRING_ENCODINGS.has(encoding?.toLowerCase() ?? "")) {
+        // An incomplete multi-byte character from an earlier byte write ends here (as U+FFFD), in order.
+        let text = bytes.end() + heldHighSurrogate + chunk;
+        heldHighSurrogate = "";
+        if (text.length > 0 && isHighSurrogate(text.charCodeAt(text.length - 1))) {
+            heldHighSurrogate = text.slice(-1);
+            text = text.slice(0, -1);
+        }
+        return text;
+    }
+    if (typeof chunk !== "string" && !ArrayBuffer.isView(chunk)) {
+        // Never handed to the raw write: its content is unknown. A held surrogate goes out masked
+        // first (fail closed, with everything buffered before it). The message names no content.
+        if (heldHighSurrogate) {
+            heldHighSurrogate = "";
+            const out = buffer.flush(true);
+            if (out)
+                rawWrite?.(out);
+        }
+        throw new TypeError("process.stderr.write takes a string or bytes (an ArrayBufferView).");
+    }
+    // Bytes end a held surrogate's chance of a low half: it is decoded alone (as U+FFFD).
+    const lone = heldHighSurrogate ? bytes.write(Buffer.from(heldHighSurrogate, "utf8")) : "";
+    heldHighSurrogate = "";
+    if (typeof chunk === "string")
+        return lone + bytes.write(Buffer.from(chunk, encoding));
+    return lone + bytes.write(Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength));
+}
+/** Emits the buffered remainder, masked fail closed and ended with "\n". Safe to call any number of times. */
+export function flushStderrRedaction() {
+    if (!rawWrite)
+        return;
+    const lone = heldHighSurrogate !== "";
+    heldHighSurrogate = "";
+    const tail = bytes.end();
+    const ready = (tail ? buffer.write(tail) : "") + buffer.flush(lone);
+    if (ready)
+        rawWrite(ready);
+}
+/** Routes process.stderr writes through the buffer, and the shared logger's lines through redactReceivedSecrets. */
+export function installStderrRedaction() {
+    if (installed)
+        return;
+    installed = true;
+    setLogLineFilter(redactReceivedSecrets);
+    const write = process.stderr.write.bind(process.stderr);
+    rawWrite = (chunk) => write(chunk);
+    process.stderr.write = (chunk, ...rest) => {
+        const encoding = typeof rest[0] === "string" ? rest[0] : undefined;
+        const callback = rest.find((arg) => typeof arg === "function");
+        // Every write goes through the one decoder, so a string after an incomplete multi-byte
+        // character from an earlier byte write keeps its place.
+        const text = decodeChunk(chunk, encoding);
+        const ready = buffer.write(text);
+        if (ready)
+            return write(ready, callback);
+        // Held for its line's end: the write is accepted, so its callback runs as if written.
+        if (callback)
+            process.nextTick(callback, null);
+        return true;
+    };
+    process.on("exit", flushStderrRedaction);
+    // A signal's default action would drop the buffered tail: flush it, then exit as the signal would.
+    process.once("SIGTERM", () => {
+        flushStderrRedaction();
+        process.exit(143);
+    });
+    process.once("SIGINT", () => {
+        flushStderrRedaction();
+        process.exit(130);
+    });
+}

package/dist/native-worker/stdio.d.ts

@@ -6,7 +6,7 @@
  * worker's diagnostics only.
  *
  * Frames, worker → control:  { id, request }
- * Frames, control → worker:  { id, ok: true, result } | { id, ok: false, error: { code, message } }
+ * Frames, control → worker:  { id, ok: true, result } | { id, ok: false, error: { code, message, causeCode? } }
  *                            | { id, event }  (llm.stream events)  | { id, end: true }
  */
 import type { Readable, Writable } from "node:stream";

package/dist/native-worker/stdio.js

@@ -6,11 +6,11 @@
  * worker's diagnostics only.
  *
  * Frames, worker → control:  { id, request }
- * Frames, control → worker:  { id, ok: true, result } | { id, ok: false, error: { code, message } }
+ * Frames, control → worker:  { id, ok: true, result } | { id, ok: false, error: { code, message, causeCode? } }
  *                            | { id, event }  (llm.stream events)  | { id, end: true }
  */
 import { spawn } from "node:child_process";
-import { GatewayError, MAX_MESSAGE_BYTES, ProtocolError, } from "./protocol.js";
+import { GatewayError, MAX_MESSAGE_BYTES, ProtocolError, toGatewayError, } from "./protocol.js";
 /** Splits a byte stream into lines, refusing any line over the cap. */
 export function readLines(stream, onLine, onError) {
     let buffer = "";
@@ -36,9 +36,10 @@ function writeLine(stream, frame) {
         throw new ProtocolError("message_too_large");
     stream.write(`${line}\n`);
 }
+/** An error as the worker sees it: exactly what the HTTP path carries (protocol.ts toGatewayError). */
 const errorFrame = (err) => {
-    const gatewayError = err instanceof GatewayError ? err : new GatewayError("internal", err instanceof Error ? err.message : String(err));
-    return { code: gatewayError.code, message: gatewayError.message };
+    const { code, message, causeCode } = toGatewayError(err);
+    return { code, message, ...(causeCode ? { causeCode } : {}) };
 };
 /** The worker's side: requests out on `output`, answers in on `input`. */
 export function createStdioTransport(input, output) {
@@ -62,7 +63,7 @@ export function createStdioTransport(input, output) {
         if (!entry)
             return;
         const error = frame.error
-            ? new GatewayError(frame.error.code, frame.error.message)
+            ? new GatewayError(frame.error.code, frame.error.message, typeof frame.error.causeCode === "string" ? frame.error.causeCode : undefined)
             : undefined;
         if (entry.kind === "call") {
             pending.delete(frame.id);

package/dist/native-worker/warm-pool.d.ts

@@ -11,7 +11,7 @@
  * size (only ever unclaimed ones), and replenishes the deficit. Claims work from any process.
  */
 import type { NativeWorkerState } from "./docker-launcher.js";
-import type { WorkerHandle } from "./launch.js";
+import type { WorkerHandle, WorkerLaunchOptions } from "./launch.js";
 import type { WorkerInput } from "./protocol.js";
 import type { ManagedWorkerLauncher } from "./sandbox-executor.js";
 import type { PrismaWarmPoolLedger } from "./warm-pool-ledger.js";
@@ -73,7 +73,7 @@ export declare class PooledWorkerLauncher implements ManagedWorkerLauncher {
     private get cold();
     private now;
     private sleep;
-    launch(input: WorkerInput): Promise<WorkerHandle>;
+    launch(input: WorkerInput, launchOptions?: WorkerLaunchOptions): Promise<WorkerHandle>;
     private confirmGone;
     /** Removes a pool worker and its row. */
     private discard;

package/dist/native-worker/warm-pool.js

@@ -52,7 +52,7 @@ export class PooledWorkerLauncher {
     sleep(ms) {
         return (this.options.sleep ?? ((t) => new Promise((resolve) => setTimeout(resolve, t))))(ms);
     }
-    async launch(input) {
+    async launch(input, launchOptions) {
         const runId = input.runId;
         const claimed = this.options.size > 0
             ? await this.options.ledger
@@ -66,7 +66,7 @@ export class PooledWorkerLauncher {
             if (this.options.size > 0)
                 poolLog.info({ runId, event: "miss" }, "no idle warm worker; launching cold");
             this.nudge();
-            return this.cold.launch(input);
+            return this.cold.launch(input, launchOptions);
         }
         const token = claimed.id;
         this.nudge();
@@ -74,7 +74,7 @@ export class PooledWorkerLauncher {
         if (!intact) {
             poolLog.warn({ runId, worker: claimed.name, event: "fallback" }, "claimed warm worker failed re-attest");
             await this.discard(token);
-            return this.cold.launch(input);
+            return this.cold.launch(input, launchOptions);
         }
         try {
             await this.cold.deliver(token, input);
@@ -88,7 +88,7 @@ export class PooledWorkerLauncher {
                 throw new Error(`${NATIVE_SANDBOX_WARM_DELIVERY_FAILED}: the run's input could not be delivered to its warm worker, which could not be confirmed stopped.`, { cause: err });
             }
             await this.options.ledger.remove(token);
-            return this.cold.launch(input);
+            return this.cold.launch(input, launchOptions);
         }
         if (this.networkReadyAtLaunch === false)
             await this.options.onDelivered?.(runId);