@koalaauto/agentchannel 3.10.0 → 3.12.0

package/dist/src/runner/runner.js

@@ -1,5 +1,5 @@
 import { randomBytes } from 'node:crypto';
-import { appendFileSync, copyFileSync, existsSync, lstatSync, mkdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { appendFileSync, copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { gitCommonDir } from '../adapters/index.js';
@@ -10,6 +10,10 @@ import { buildAgentEnv } from '../env.js';
 import { effectivePerm } from '../perm.js';
 import { ANSWER_SCHEMA, buildAnswerPrompt, buildMentionPrompt, buildResumePrompt, buildTaskPrompt, postUrl, refOf, taskUrl } from '../prompts.js';
 import { RunnerState } from './state.js';
+import { looksLikeLoginError, summarizeRuntimeError } from '../envcheck.js';
+import { redact } from '../redact.js';
+import { TraceRecorder } from '../trace.js';
+import { looksLikeSandboxError } from '../sandboxcheck.js';
 export function jobKey(j) {
     if (j.kind === 'mention')
         return `mention:${j.item.mention.id}`;
@@ -207,9 +211,17 @@ export class Runner {
     /** B7: set when the hub answered 401 (key rotated, agent or owner deactivated): the runner stops. */
     fatal;
     wake;
+    /** design §27: the last sandbox probe, when it ran, and what the hub was last told (a JSON key). */
+    sandbox;
+    sandboxReported;
+    sandboxRecheck = false;
+    /** Execution traces the hub has not taken yet (kept on disk too), and the last trace of each task (a commit joins it). */
+    traceQueue = new Map();
+    lastTrace = new Map();
     constructor(opts) {
         this.o = { max: 2, perm: 'workdir', intervalMs: 3000, heartbeatMs: 30_000, idleMs: 60 * 60_000, ...opts };
         this.state = new RunnerState(opts.home);
+        this.loadPendingTraces();
     }
     log(s) {
         (this.o.log ?? ((x) => console.error(x)))(`[ach run] ${s}`);
@@ -283,8 +295,11 @@ export class Runner {
         }
         await this.checkActive();
         await this.prune();
+        await this.flushTraces();
         if (this.paused)
             return; // heartbeats of parked runs went out in checkActive; nothing new is taken (it waits in the hub's inbox)
+        if (await this.sandboxBlocked())
+            return; // design §27: same, until the sandbox works
         if (!this.me || inbox.tasks_to_me.length)
             this.me = await this.o.client.me();
         const me = this.me;
@@ -332,6 +347,50 @@ export class Runner {
         }
         this.pump();
     }
+    /** design §27: probe the sandbox when due, tell the hub when the answer changes; true = take nothing new. */
+    async sandboxBlocked() {
+        const check = this.o.sandboxCheck;
+        if (!check)
+            return false;
+        const prev = this.sandbox;
+        const due = !prev || this.sandboxRecheck || (!prev.st.ok && Date.now() - prev.at >= (this.o.sandboxRecheckMs ?? 5 * 60_000)) || (prev.st.ok && Date.now() - prev.at >= (this.o.okRecheckMs ?? 6 * 3600_000));
+        if (due) {
+            this.sandboxRecheck = false;
+            let st;
+            try {
+                st = await check();
+            }
+            catch (e) {
+                st = { tool: 'claude', ok: false, problem: 'failed', detail: String(e?.message ?? e) };
+            }
+            this.sandbox = { st, at: Date.now() };
+            if (!prev || prev.st.ok !== st.ok || prev.st.problem !== st.problem) {
+                if (st.ok)
+                    this.log(`sandbox: ${st.unverified ? `not checked (${st.detail})` : 'works'}${prev ? '; taking tasks again' : ''}`);
+                else
+                    this.log(`sandbox: ${st.fix?.en ?? st.detail ?? st.problem} Taking no tasks until it works.${st.fix?.commands.length ? `\n  fix:\n${st.fix.commands.map((c) => `    ${c}`).join('\n')}` : ''}`);
+            }
+        }
+        const st = this.sandbox.st;
+        const report = st.ok ? null : { tool: st.tool, problem: st.problem ?? 'failed', ...(st.detail ? { detail: st.detail } : {}), ...(st.fix ? { fix: st.fix } : {}) };
+        const key = JSON.stringify(report);
+        if (key !== this.sandboxReported && this.o.client.reportSetup) {
+            try {
+                await this.o.client.reportSetup(report);
+                this.sandboxReported = key;
+            }
+            catch (e) {
+                if (is401(e))
+                    this.authFailed('setup');
+                // an older hub without /me/setup: the log above is all there is
+                else if (e instanceof HubError && e.status === 404)
+                    this.sandboxReported = key;
+                else
+                    this.log(`setup report: ${e?.message ?? e}`);
+            }
+        }
+        return !st.ok;
+    }
     async notifyBudget(t, me) {
         if (this.state.runs.budgetNotified[t.id])
             return;
@@ -717,8 +776,19 @@ export class Runner {
             return;
         try {
             const sha = await this.o.workspace.commit(rec.taskId, `ach: ${task.title ?? rec.taskId} (task ${rec.taskId})`.slice(0, 200));
-            if (sha)
+            if (sha) {
                 this.taskLog(rec.taskId, `runner committed ${sha}`);
+                // the commit joins the run's trace, so the panel can name what the run produced
+                const id = this.lastTrace.get(rec.taskId);
+                const q = id ? this.traceQueue.get(id) : undefined;
+                if (id && q) {
+                    q.body.commit = sha;
+                    this.persistTrace(id);
+                }
+                else if (id && this.o.client.putTrace)
+                    await this.o.client.putTrace(rec.taskId, id, { commit: sha }).catch((e) => this.taskLog(rec.taskId, `trace commit: ${e?.message ?? e}`));
+                await this.flushTraces();
+            }
         }
         catch (e) {
             this.taskLog(rec.taskId, `commit failed: ${e?.message ?? e}`);
@@ -778,7 +848,22 @@ export class Runner {
             return;
         }
         if (!result.ok) {
-            await client.fail(taskId, `runtime error: ${result.error ?? 'unknown'}`, rec.runId).catch((e) => this.log(`fail ${taskId}: ${e?.message ?? e}`));
+            const err = result.error ?? 'unknown';
+            // The machine, not the task: when the run died of a login or sandbox problem and the check now confirms it, the task goes
+            // back to the queue (the runner takes nothing more until the check passes, and the owner has been told) instead of failing.
+            if (this.o.sandboxCheck && (looksLikeSandboxError(err) || looksLikeLoginError(err))) {
+                this.sandboxRecheck = true;
+                if ((await this.sandboxBlocked()) && client.release) {
+                    const why = this.sandbox?.st.fix?.en ?? this.sandbox?.st.detail ?? summarizeRuntimeError(err);
+                    const done = await client.release(taskId, why, rec.runId).then(() => true, (e) => { this.log(`release ${taskId}: ${e?.message ?? e}`); return false; });
+                    if (done) {
+                        this.taskLog(taskId, `released: ${why}`);
+                        this.state.drop(taskId);
+                        return;
+                    }
+                }
+            }
+            await client.fail(taskId, `runtime error: ${summarizeRuntimeError(err)}`, rec.runId).catch((e) => this.log(`fail ${taskId}: ${e?.message ?? e}`));
             this.state.drop(taskId);
             return;
         }
@@ -1032,22 +1117,33 @@ export class Runner {
         // adapter events, unless a tool call is still in flight.
         let lastEvent = Date.now();
         const inflight = new Set();
-        const hb = mode === 'work'
-            ? setInterval(() => {
-                this.heartbeat(rec).catch((e) => {
-                    this.log(`heartbeat ${taskId}: ${e?.message ?? e}`);
-                    // C3: 409 = this run no longer owns the task; stop working on it.
-                    // Except when the task is completed / failed: that is the agent's own
-                    // `ach complete` / `ach fail`; let the turn end so its usage is recorded.
-                    const st = e instanceof HubError ? String(e.body?.status ?? '') : '';
-                    if (is409(e) && !entry.reason && st !== 'completed' && st !== 'failed') {
-                        entry.reason = 'lost';
-                        this.taskLog(taskId, 'heartbeat 409: run lost the task; aborting');
-                        entry.controller.abort();
-                    }
-                });
-            }, this.o.heartbeatMs)
-            : undefined;
+        // the execution trace of this run: what it thought, ran and printed, masked before it leaves this machine
+        const startedAt = new Date();
+        const recorder = new TraceRecorder([rec.runToken, ...(this.o.secrets ?? []), this.o.cfSecret ?? ''].filter(Boolean));
+        let hb;
+        hb =
+            mode === 'work'
+                ? setInterval(() => {
+                    this.heartbeat(rec).catch((e) => {
+                        this.log(`heartbeat ${taskId}: ${e?.message ?? e}`);
+                        // C3: 409 = this run no longer owns the task; stop working on it.
+                        // Except when the task is completed / failed: that is the agent's own
+                        // `ach complete` / `ach fail`; let the turn end so its usage is recorded.
+                        const st = e instanceof HubError ? String(e.body?.status ?? '') : '';
+                        if (is409(e) && !entry.reason && st !== 'completed' && st !== 'failed') {
+                            entry.reason = 'lost';
+                            this.taskLog(taskId, 'heartbeat 409: run lost the task; aborting');
+                            entry.controller.abort();
+                        }
+                        // the task is finished (the agent's own complete / fail) but the run goes on: say so in the trace and stop beating for it
+                        if (is409(e) && (st === 'completed' || st === 'failed' || st === 'awaiting_acceptance')) {
+                            recorder.mark(`task_${st}`);
+                            if (hb)
+                                clearInterval(hb);
+                        }
+                    });
+                }, this.o.heartbeatMs)
+                : undefined;
         const idle = setInterval(() => {
             if (!inflight.size && Date.now() - lastEvent > this.o.idleMs && !entry.reason) {
                 entry.reason = 'idle';
@@ -1083,7 +1179,9 @@ export class Runner {
                     if (e.type === 'session' && e.data && mode !== 'mention') {
                         this.state.setSession(taskId, mode, { id: String(e.data), cwd: rec.workdir });
                     }
-                    this.taskLog(taskId, `${e.type} ${typeof e.data === 'string' ? e.data.slice(0, 500) : JSON.stringify(e.data)?.slice(0, 500)}`);
+                    recorder.event(e);
+                    // the log keeps its one line per event; what a tool printed is in the trace, not here
+                    this.taskLog(taskId, `${e.type} ${typeof e.data === 'string' ? e.data.slice(0, 500) : JSON.stringify(e.data, (k, v) => (k === 'output' ? undefined : v))?.slice(0, 500)}`);
                 },
             });
         }
@@ -1102,8 +1200,104 @@ export class Runner {
         if (!this.fatal)
             await usage(Number(result.costUsd ?? 0), !!result.estimated).catch((e) => this.log(`usage ${taskId}: ${e?.message ?? e}`));
         this.taskLog(taskId, `${mode} run end ok=${result.ok} cost=${result.costUsd ?? 0} err=${result.error ?? ''}`);
+        if (mode !== 'mention')
+            await this.uploadTrace(taskId, rec.runId, mode, startedAt, result, recorder, !this.fatal);
         return result;
     }
+    // ---- the execution trace -------------------------------------------------------------------------------------------------
+    traceDir() {
+        return join(this.o.home, 'traces');
+    }
+    /** Traces an earlier process could not upload are tried again. */
+    loadPendingTraces() {
+        try {
+            for (const f of readdirSync(this.traceDir())) {
+                if (!f.endsWith('.json'))
+                    continue;
+                const j = JSON.parse(readFileSync(join(this.traceDir(), f), 'utf8'));
+                if (j?.taskId && j?.traceId && j?.body)
+                    this.traceQueue.set(j.traceId, { taskId: j.taskId, body: j.body });
+            }
+        }
+        catch {
+            /* none */
+        }
+    }
+    /** Build and send the trace of the run that just ended. Never throws; a failed upload is kept and retried. */
+    async uploadTrace(taskId, runId, mode, startedAt, result, recorder, send) {
+        if (!this.o.client.putTrace)
+            return;
+        try {
+            const { steps, omitted } = recorder.finish();
+            if (!steps.length && result.ok)
+                return; // nothing happened worth auditing
+            const traceId = `tr_${randomBytes(9).toString('base64url')}`;
+            const body = {
+                run_id: runId, mode, started: startedAt.toISOString(), ended: new Date().toISOString(), ok: !!result.ok,
+                ...(result.error ? { error: redact(summarizeRuntimeError(result.error), [...(this.o.secrets ?? [])]).slice(0, 600) } : {}),
+                steps, omitted,
+            };
+            this.lastTrace.set(taskId, traceId);
+            this.traceQueue.set(traceId, { taskId, body });
+            this.persistTrace(traceId);
+            if (send)
+                await this.flushTraces();
+        }
+        catch (e) {
+            this.taskLog(taskId, `trace: ${e?.message ?? e}`);
+        }
+    }
+    persistTrace(traceId) {
+        const q = this.traceQueue.get(traceId);
+        if (!q)
+            return;
+        try {
+            mkdirSync(this.traceDir(), { recursive: true, mode: 0o700 });
+            writeFileSync(join(this.traceDir(), `${traceId}.json`), JSON.stringify({ traceId, ...q }), { mode: 0o600 });
+        }
+        catch {
+            /* kept in memory */
+        }
+    }
+    /** Send what is waiting (a few at a time). A trace never holds up a task: failures are logged and tried again on the next poll. */
+    async flushTraces() {
+        const put = this.o.client.putTrace;
+        if (!put || !this.traceQueue.size)
+            return;
+        let n = 0;
+        for (const [id, q] of [...this.traceQueue]) {
+            if (n++ >= 5)
+                break;
+            try {
+                await put.call(this.o.client, q.taskId, id, q.body);
+                this.traceQueue.delete(id);
+                try {
+                    unlinkSync(join(this.traceDir(), `${id}.json`));
+                }
+                catch {
+                    /* already gone */
+                }
+            }
+            catch (e) {
+                const code = e instanceof HubError ? e.status : 0;
+                if (is401(e))
+                    return this.authFailed('trace');
+                // an older hub (404), a task that is gone or not ours (403/404/409): not worth keeping
+                if (code === 404 || code === 403 || code === 409 || code === 400) {
+                    this.traceQueue.delete(id);
+                    try {
+                        unlinkSync(join(this.traceDir(), `${id}.json`));
+                    }
+                    catch {
+                        /* */
+                    }
+                    this.taskLog(q.taskId, `trace not taken (${code}): ${e?.message ?? e}`);
+                }
+                else
+                    this.taskLog(q.taskId, `trace upload failed, will retry: ${e?.message ?? e}`);
+            }
+        }
+    }
     /** Polls until stop() or a 401 (B7: resolves 'unauthorized' after aborting every job). */
     async start() {
         this.recover();

package/dist/src/sandboxcheck.d.ts

@@ -0,0 +1,97 @@
+/**
+ * design §27: does the agent tool's sandbox work on this machine?
+ *
+ * Probe, do not guess: run the mechanism the tool uses (bubblewrap on Linux for Claude Code, Seatbelt on macOS, `codex
+ * sandbox` for Codex) on a throwaway directory, once with a command that must succeed (write inside it) and once with one
+ * that must be refused (write in the home directory). Passing means the sandbox starts and enforces. No model call.
+ *
+ * When it fails, `sandboxFix` maps what it can see about the machine (package manager, AppArmor, WSL) to the commands
+ * that fix it. Nothing here runs them: setup asks first, doctor and the runner print them.
+ */
+export type SandboxTool = 'claude' | 'codex';
+export type SandboxProblem = 
+/** a package the sandbox needs is not installed (`missing` names them) */
+'missing'
+/** Ubuntu's AppArmor rule stops unprivileged user namespaces (kernel.apparmor_restrict_unprivileged_userns=1) */
+ | 'userns-blocked'
+/** the kernel has user namespaces turned off */
+ | 'userns-off'
+/** the sandbox ran the command but let it write outside its directory */
+ | 'not-enforced'
+/** Claude Code has no sandbox on native Windows */
+ | 'windows-native'
+/** an OS neither tool sandboxes */
+ | 'unsupported'
+/** the tool is not logged in on this machine (envcheck.ts): not the sandbox, but the same "takes no tasks" state */
+ | 'not-logged-in'
+/** anything else: `detail` has the first line of the error */
+ | 'failed';
+export interface SandboxFix {
+    /** One sentence: what is wrong and what the commands do. */
+    en: string;
+    zh: string;
+    /** Shell lines to run, in order (sudo included). Empty: there is nothing safe to run; the sentence says what to do. */
+    commands: string[];
+}
+export interface SandboxStatus {
+    tool: SandboxTool;
+    ok: boolean;
+    /** ok, but the probe could not run (an older Codex without `codex sandbox`): not blocking, doctor warns. */
+    unverified?: boolean;
+    problem?: SandboxProblem;
+    missing?: string[];
+    detail?: string;
+    fix?: SandboxFix;
+}
+export type PkgManager = 'apt' | 'dnf' | 'pacman' | 'zypper' | 'apk';
+/** What the fix depends on, read from the machine (tests pass their own). */
+export interface Host {
+    platform: NodeJS.Platform;
+    wsl: boolean;
+    /** /etc/os-release ID and ID_LIKE */
+    distro?: string[];
+    pkg?: PkgManager;
+    /** kernel.apparmor_restrict_unprivileged_userns ('1' = on) */
+    appArmorUserns?: string;
+    /** an AppArmor profile that lets /usr/bin/bwrap create user namespaces is installed */
+    bwrapProfile: boolean;
+    /** absolute paths, when found on PATH */
+    bwrap?: string;
+    socat?: string;
+}
+export type RunResult = {
+    code: number;
+    stdout: string;
+    stderr: string;
+};
+export type Run = (file: string, args: string[], opts: {
+    env: NodeJS.ProcessEnv;
+    cwd?: string;
+}) => Promise<RunResult>;
+export declare const defaultRun: Run;
+export declare function onPath(name: string, env: NodeJS.ProcessEnv): string | undefined;
+export declare function pkgFor(distro: string[] | undefined): PkgManager | undefined;
+/** Read the machine (Linux files; elsewhere only the platform matters). */
+export declare function detectHost(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): Host;
+/** The Codex CLI the runner's SDK uses (the @openai/codex package next to this CLI), else `codex` on PATH. */
+export declare function codexCommand(env?: NodeJS.ProcessEnv): string[] | undefined;
+/** What a failed sandbox start said, as a problem. */
+export declare function classify(stderr: string, host: Host): SandboxProblem;
+export interface ProbeOptions {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    host?: Host;
+    run?: Run;
+    /** where the forbidden write goes (default: the home directory) */
+    home?: string;
+    /** the Codex CLI (default: codexCommand()) */
+    codex?: string[];
+}
+/** Probe `tool`'s sandbox on this machine. Never throws. */
+export declare function probeSandbox(tool: SandboxTool, o?: ProbeOptions): Promise<SandboxStatus>;
+/** Lets the system bubblewrap (only that path) create user namespaces under Ubuntu's AppArmor rule; never machine-wide. */
+export declare const BWRAP_APPARMOR: string;
+/** The fix for a failed probe on this host. */
+export declare function sandboxFix(st: SandboxStatus, host: Host): SandboxFix;
+/** Does a run's error look like the sandbox failing (the runner then probes again)? */
+export declare function looksLikeSandboxError(s: string): boolean;

package/dist/src/sandboxcheck.js

@@ -0,0 +1,236 @@
+import { execFile } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir, tmpdir } from 'node:os';
+import { delimiter, dirname, join } from 'node:path';
+export const defaultRun = (file, args, opts) => new Promise((res) => {
+    execFile(file, args, { env: opts.env, cwd: opts.cwd, timeout: 20_000, encoding: 'utf8', maxBuffer: 1 << 20 }, (err, stdout, stderr) => {
+        const code = err ? (typeof err.code === 'number' ? err.code : err.code === 'ENOENT' ? 127 : 1) : 0;
+        res({ code, stdout: String(stdout ?? ''), stderr: String(stderr ?? '') || (err?.code === 'ENOENT' ? `${file}: not found` : '') });
+    });
+});
+export function onPath(name, env) {
+    for (const d of (env.PATH ?? '').split(delimiter)) {
+        if (!d)
+            continue;
+        const f = join(d, name);
+        if (existsSync(f))
+            return f;
+    }
+    return undefined;
+}
+function read(f) {
+    try {
+        return readFileSync(f, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+const PKG_BY_DISTRO = [
+    [/^(debian|ubuntu|linuxmint|pop|elementary|raspbian|kali)$/, 'apt'],
+    [/^(fedora|rhel|centos|rocky|almalinux|amzn|ol)$/, 'dnf'],
+    [/^(arch|manjaro|endeavouros)$/, 'pacman'],
+    [/^(opensuse.*|suse|sles)$/, 'zypper'],
+    [/^alpine$/, 'apk'],
+];
+export function pkgFor(distro) {
+    for (const id of distro ?? [])
+        for (const [re, pm] of PKG_BY_DISTRO)
+            if (re.test(id))
+                return pm;
+    return undefined;
+}
+/** Read the machine (Linux files; elsewhere only the platform matters). */
+export function detectHost(env = process.env, platform = process.platform) {
+    const h = { platform, wsl: false, bwrapProfile: false };
+    if (platform !== 'linux')
+        return h;
+    const osr = read('/etc/os-release') ?? '';
+    const field = (k) => (osr.match(new RegExp(`^${k}=("?)([^"\\n]*)\\1`, 'm'))?.[2] ?? '').toLowerCase();
+    h.distro = [field('ID'), ...field('ID_LIKE').split(/\s+/)].filter(Boolean);
+    h.pkg = pkgFor(h.distro);
+    h.wsl = /microsoft/i.test(read('/proc/version') ?? '') || !!env.WSL_DISTRO_NAME;
+    h.appArmorUserns = read('/proc/sys/kernel/apparmor_restrict_unprivileged_userns')?.trim();
+    h.bwrapProfile = existsSync('/etc/apparmor.d/bwrap') || existsSync('/etc/apparmor.d/bwrap-userns-restrict');
+    h.bwrap = onPath('bwrap', env);
+    h.socat = onPath('socat', env);
+    return h;
+}
+/** The Codex CLI the runner's SDK uses (the @openai/codex package next to this CLI), else `codex` on PATH. */
+export function codexCommand(env = process.env) {
+    try {
+        const req = createRequire(import.meta.url);
+        const f = join(dirname(req.resolve('@openai/codex/package.json')), 'bin', 'codex.js');
+        if (existsSync(f))
+            return [process.execPath, f];
+    }
+    catch {
+        /* not installed next to us */
+    }
+    const p = onPath(process.platform === 'win32' ? 'codex.cmd' : 'codex', env);
+    return p ? [p] : undefined;
+}
+/** What a failed sandbox start said, as a problem. */
+export function classify(stderr, host) {
+    if (/No permissions to create new namespace|max_user_namespaces|user namespaces? (are|is) (disabled|not (enabled|supported))/i.test(stderr))
+        return 'userns-off';
+    // bwrap's own namespace setup failing: under Ubuntu's AppArmor rule that is the rule; elsewhere namespaces are off
+    if (/setting up uid map|RTM_NEWADDR|loopback: Failed|creating new namespace|unshare/i.test(stderr))
+        return host.appArmorUserns === '1' ? 'userns-blocked' : 'userns-off';
+    // a bare "not permitted" from bwrap is the AppArmor rule only when that rule is on; else it is something else
+    if (host.appArmorUserns === '1' && /^bwrap: .*(Operation not permitted|Permission denied)/im.test(stderr))
+        return 'userns-blocked';
+    return 'failed';
+}
+function firstLine(s) {
+    return (s.split('\n').map((l) => l.trim()).find(Boolean) ?? '').slice(0, 200);
+}
+/** The two writes: inside the sandbox's directory (must work) and in the home directory (must be refused). */
+function probeScript() {
+    return 'touch "$1/ok" || exit 3; if touch "$2" 2>/dev/null; then exit 4; fi; exit 0';
+}
+/** Probe `tool`'s sandbox on this machine. Never throws. */
+export async function probeSandbox(tool, o = {}) {
+    const env = o.env ?? process.env;
+    // the CLI's own tests (scripts/test-sandbox.mjs) run on machines whose sandbox is not what they test
+    if ((env.ACH_SANDBOX_CHECK ?? process.env.ACH_SANDBOX_CHECK) === 'off' && !o.run)
+        return { tool, ok: true, unverified: true, detail: 'skipped (ACH_SANDBOX_CHECK=off)' };
+    const platform = o.platform ?? process.platform;
+    const host = o.host ?? detectHost(env, platform);
+    const run = o.run ?? defaultRun;
+    const st = await probe(tool, { env, platform, host, run, home: o.home ?? homedir(), codex: o.codex });
+    if (!st.ok)
+        st.fix = sandboxFix(st, host);
+    return st;
+}
+async function probe(tool, o) {
+    const { platform, host, run, env } = o;
+    if (platform === 'win32') {
+        if (tool === 'claude')
+            return { tool, ok: false, problem: 'windows-native' };
+    }
+    else if (platform !== 'linux' && platform !== 'darwin') {
+        return { tool, ok: false, problem: 'unsupported', detail: platform };
+    }
+    if (platform === 'linux' && tool === 'claude') {
+        const missing = [...(host.bwrap ? [] : ['bubblewrap']), ...(host.socat ? [] : ['socat'])];
+        if (missing.length)
+            return { tool, ok: false, problem: 'missing', missing };
+    }
+    let dir;
+    try {
+        dir = mkdtempSync(join(tmpdir(), 'ach-sandbox-probe-'));
+    }
+    catch (e) {
+        return { tool, ok: false, problem: 'failed', detail: `cannot make a temporary directory: ${e?.message ?? e}` };
+    }
+    const outside = join(o.home, `.ach-sandbox-probe-${randomBytes(4).toString('hex')}`);
+    const sh = ['/bin/sh', '-c', probeScript(), 'probe', dir, outside];
+    try {
+        let r;
+        if (tool === 'claude' && platform === 'linux') {
+            // what Claude Code's sandbox does: a new session, no network, the filesystem read-only except the work directory
+            r = await run(host.bwrap, ['--new-session', '--die-with-parent', '--unshare-net', '--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc', '--bind', dir, dir, '--', ...sh], { env });
+        }
+        else if (tool === 'claude') {
+            const q = (p) => JSON.stringify(p);
+            const profile = `(version 1)(allow default)(deny file-write* (subpath ${q(o.home)}))(allow file-write* (subpath ${q(dir)}))`;
+            r = await run('/usr/bin/sandbox-exec', ['-p', profile, ...sh], { env });
+        }
+        else {
+            const codex = o.codex ?? codexCommand(env);
+            if (!codex)
+                return { tool, ok: true, unverified: true, detail: 'Codex was not found' };
+            const cmd = platform === 'win32' ? ['cmd', '/c', `type nul > "${join(dir, 'ok')}" && (type nul > "${outside}" && exit 4 || exit 0)`] : sh;
+            // the work directory is the cwd (`-C` would also need a named permission profile)
+            r = await run(codex[0], [...codex.slice(1), 'sandbox', '-c', 'sandbox_mode="workspace-write"', '--', ...cmd], { env, cwd: dir });
+            if (r.code !== 0 && /unrecognized subcommand|unexpected argument|Usage: codex \[OPTIONS\]/i.test(r.stderr)) {
+                return { tool, ok: true, unverified: true, detail: 'this Codex has no `codex sandbox` command' };
+            }
+        }
+        if (existsSync(outside) || r.code === 4)
+            return { tool, ok: false, problem: 'not-enforced', detail: `a sandboxed command could write ${outside}` };
+        if (r.code === 0 && existsSync(join(dir, 'ok')))
+            return { tool, ok: true };
+        const err = `${r.stderr}\n${r.stdout}`;
+        if (r.code === 127 && platform === 'linux' && tool === 'claude')
+            return { tool, ok: false, problem: 'missing', missing: ['bubblewrap'] };
+        return { tool, ok: false, problem: classify(err, host), detail: firstLine(err) || `exit ${r.code}` };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+        rmSync(outside, { force: true });
+    }
+}
+const INSTALL = {
+    apt: (p) => `sudo apt-get install -y ${p.join(' ')}`,
+    dnf: (p) => `sudo dnf install -y ${p.join(' ')}`,
+    pacman: (p) => `sudo pacman -S --needed --noconfirm ${p.join(' ')}`,
+    zypper: (p) => `sudo zypper install -y ${p.join(' ')}`,
+    apk: (p) => `sudo apk add ${p.join(' ')}`,
+};
+/** Lets the system bubblewrap (only that path) create user namespaces under Ubuntu's AppArmor rule; never machine-wide. */
+export const BWRAP_APPARMOR = `printf '%s\\n' 'abi <abi/4.0>,' 'include <tunables/global>' 'profile bwrap /usr/bin/bwrap flags=(unconfined) {' '  userns,' '  include if exists <local/bwrap>' '}' ` +
+    `| sudo tee /etc/apparmor.d/bwrap >/dev/null && sudo apparmor_parser -r /etc/apparmor.d/bwrap`;
+/** The fix for a failed probe on this host. */
+export function sandboxFix(st, host) {
+    const name = st.tool === 'claude' ? 'Claude Code' : 'Codex';
+    switch (st.problem) {
+        case 'not-logged-in': {
+            const cmd = st.tool === 'claude' ? 'claude auth login' : 'codex login';
+            return { en: `${name} is not logged in on this machine: run \`${cmd}\` as the user that runs this agent.`, zh: `${name} 在这台机器上没有登录：以运行这个智能体的用户身份执行 \`${cmd}\`。`, commands: [cmd] };
+        }
+        case 'windows-native':
+            return {
+                en: 'Claude Code has no sandbox on native Windows: run this agent inside WSL2 (wsl --install, then join again there).',
+                zh: 'Claude Code 在原生 Windows 上没有沙箱：请在 WSL2 里运行这个智能体（wsl --install，然后在 WSL 里重新 join）。',
+                commands: [],
+            };
+        case 'unsupported':
+            return { en: `${name} has no sandbox on ${st.detail ?? 'this system'}.`, zh: `${name} 在 ${st.detail ?? '这个系统'} 上没有沙箱。`, commands: [] };
+        case 'userns-off':
+            return {
+                en: 'This kernel does not allow user namespaces, which the sandbox needs. Ask whoever runs this machine to allow them (user.max_user_namespaces).',
+                zh: '这台机器的内核不允许用户命名空间，沙箱需要它。请让管理这台机器的人开启（user.max_user_namespaces）。',
+                commands: [],
+            };
+        case 'not-enforced':
+            return { en: `${name}'s sandbox started but did not stop a write outside its directory: do not run this agent here.`, zh: `${name} 的沙箱能启动，但没有拦住目录外的写入：不要在这台机器上运行这个智能体。`, commands: [] };
+        case 'missing':
+        case 'userns-blocked': {
+            if (host.platform !== 'linux')
+                break;
+            const pkgs = st.tool === 'claude' ? ['bubblewrap', 'socat'] : ['bubblewrap'];
+            // the profile only covers /usr/bin/bwrap: a bwrap from elsewhere (a user install) means installing the system one
+            const need = pkgs.filter((p) => (p === 'socat' ? !host.socat : !host.bwrap || host.bwrap !== '/usr/bin/bwrap' || st.missing?.includes(p)));
+            const appArmor = host.appArmorUserns === '1' && (st.problem === 'userns-blocked' || !host.bwrapProfile);
+            const commands = [];
+            if (need.length) {
+                if (!host.pkg) {
+                    return {
+                        en: `Install ${need.join(' and ')} with this system's package manager${appArmor ? ', then allow /usr/bin/bwrap in AppArmor (see the Claude Code sandbox docs)' : ''}.`,
+                        zh: `请用系统的包管理器安装 ${need.join(' 和 ')}${appArmor ? '，再在 AppArmor 里放行 /usr/bin/bwrap（见 Claude Code 沙箱文档）' : ''}。`,
+                        commands: [],
+                    };
+                }
+                commands.push(INSTALL[host.pkg](need));
+            }
+            if (appArmor)
+                commands.push(BWRAP_APPARMOR);
+            const what = [need.length ? `install ${need.join(' and ')}` : '', appArmor ? 'let /usr/bin/bwrap create user namespaces under AppArmor (this program only)' : ''].filter(Boolean);
+            const zhWhat = [need.length ? `安装 ${need.join(' 和 ')}` : '', appArmor ? '在 AppArmor 里只放行 /usr/bin/bwrap 创建用户命名空间' : ''].filter(Boolean);
+            return {
+                en: `${name}'s sandbox cannot start on this machine${st.missing?.length ? ` (${st.missing.join(', ')} missing)` : ''}. Fix: ${what.join(', then ')}.`,
+                zh: `${name} 的沙箱在这台机器上起不来${st.missing?.length ? `（缺 ${st.missing.join('、')}）` : ''}。修复：${zhWhat.join('，然后')}。`,
+                commands,
+            };
+        }
+    }
+    return { en: `${name}'s sandbox cannot start on this machine: ${st.detail ?? 'unknown error'}.`, zh: `${name} 的沙箱在这台机器上起不来：${st.detail ?? '未知错误'}。`, commands: [] };
+}
+/** Does a run's error look like the sandbox failing (the runner then probes again)? */
+export function looksLikeSandboxError(s) {
+    return /sandbox|bwrap|bubblewrap|socat|seatbelt|user namespace|uid map|RTM_NEWADDR/i.test(s);
+}