@koalaauto/agentchannel 3.10.0 → 3.11.0

package/README.md

@@ -42,6 +42,10 @@ installed or changed.
   --interactive-first` for the current directory; `--notify` only on a machine
   with a desktop), and starts it. Through npx the service runs the same pinned
   npx spec as the MCP entry, so nothing is installed globally.
+- When the agent tool's sandbox does not work on this machine (on Linux: bubblewrap and
+  socat missing, or Ubuntu's AppArmor rule), it shows the commands that fix it and runs
+  them only after you say yes in a terminal (they use sudo). Without a terminal it only
+  prints them. The background helper takes no tasks until the sandbox works.
 - `--dry-run` prints the plan; the invite is not used and nothing is written.
 - `--yes` skips the question.
 

package/dist/src/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { execFileSync } from 'node:child_process';
+import { execFileSync, execSync, spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
 import { chmodSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { basename, delimiter, dirname, isAbsolute, join, relative, resolve } from 'node:path';
@@ -415,7 +415,7 @@ async function dispatch(p, io) {
                 : `joined ${inv.hub} as agent ${me.name}${me.owner_name ? ` (owner ${me.owner_name})` : ''}; key stored in the ${where === 'keychain' ? 'OS keychain' : 'agent-key file (0600)'}.`);
             const { runSetup, doneLine } = await import('./onboard.js');
             const { defaultExec } = await import('./doctor.js');
-            const r = await runSetup({ env, out: io.out, err: io.err, exec: io.exec ?? defaultExec, ask: io.ask, cwd: io.cwd ?? process.cwd() }, { yes: !!v.yes, service: !!v.service, runtime: typeof me.runtime === 'string' ? me.runtime : undefined, zh });
+            const r = await runSetup({ env, out: io.out, err: io.err, exec: io.exec ?? defaultExec, ask: io.ask, cwd: io.cwd ?? process.cwd(), ...(io.ask ? { runTty: (line) => runInTerminal(line, env) } : {}) }, { yes: !!v.yes, service: !!v.service, runtime: typeof me.runtime === 'string' ? me.runtime : undefined, zh });
             out(r.failed.length ? (zh ? `部分步骤失败（${r.failed.join(', ')}）：运行 ach doctor 查看怎么修。` : `Some steps failed (${r.failed.join(', ')}): run ach doctor to see how to fix them.`) : r.tools.length ? doneLine(r.tools, zh) : zh ? '密钥已保存，但还没有接入任何工具（见上面）。' : 'The key is stored, but no tool is connected yet (see above).');
             return r.failed.length ? 1 : 0;
         }
@@ -1485,6 +1485,14 @@ function linkOf(env, t) {
 function splitList(v) {
     return v.split(',').map((x) => x.trim()).filter(Boolean);
 }
+/** A shell line with this terminal's stdin/stdout/stderr (sudo asks for its password there); its exit code. */
+function runInTerminal(line, env) {
+    return new Promise((res) => {
+        const c = spawn('/bin/sh', ['-c', line], { env, stdio: 'inherit' });
+        c.on('error', () => res(127));
+        c.on('exit', (code) => res(code ?? 1));
+    });
+}
 function shq(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }
@@ -1576,6 +1584,10 @@ async function runCommand(p, io) {
             return shim ? { ...env, PATH: `${shim}${delimiter}${env.PATH ?? ''}` } : env;
         })(),
         log: io.err,
+        sandboxCheck: async () => {
+            const { probeSandbox } = await import('./sandboxcheck.js');
+            return probeSandbox(runtime === 'codex' ? 'codex' : 'claude', { env });
+        },
     });
     io.err(`ach run: agent ${me.name}, runtime ${runtime}, perm min(${me.perm_level}, ${perm}), dir ${dir}` +
         (Object.keys(repos).length ? `, repos ${Object.entries(repos).map(([k, x]) => `${k}=${x}`).join(' ')}` : '') +
@@ -1666,8 +1678,8 @@ async function installService(p, io, o) {
     const { isBundledBin, npmSpec, whichAll } = await import('./invite.js');
     const env = io.env;
     const platform = (env.ACH_SERVICE_PLATFORM || process.platform);
-    if (platform !== 'darwin' && platform !== 'linux')
-        throw new UsageError(`run --install-service: unsupported platform ${platform} (macOS launchd or Linux systemd only)`);
+    if (platform !== 'darwin' && platform !== 'linux' && platform !== 'win32')
+        throw new UsageError(`run --install-service: unsupported platform ${platform} (macOS, Linux and Windows only)`);
     const v = p.values;
     const args = ['--dir', o.dir];
     for (const [name, path] of Object.entries(o.repos))
@@ -1704,14 +1716,17 @@ async function installService(p, io, o) {
         args,
         env: svcEnv,
         logFile: join(o.home, 'logs', 'runner.log'),
-    }, env.ACH_SERVICE_DIR || undefined);
+    }, env.ACH_SERVICE_DIR || undefined, env);
     writeServiceFile(f);
     const load = !env.ACH_SERVICE_DIR;
     let failed = '';
     if (load) {
         for (const c of f.start) {
             try {
-                execFileSync('/bin/sh', ['-c', c], { env, stdio: ['ignore', 'ignore', 'pipe'] });
+                if (platform === 'win32')
+                    execSync(c, { env, stdio: ['ignore', 'ignore', 'pipe'] }); // cmd.exe
+                else
+                    execFileSync('/bin/sh', ['-c', c], { env, stdio: ['ignore', 'ignore', 'pipe'] });
             }
             catch (e) {
                 failed = `${c}: ${String(e?.stderr ?? e?.message ?? e).trim().split('\n')[0]}`;

package/dist/src/client.d.ts

@@ -379,6 +379,20 @@ export declare class Client {
     /** The total size of a work prompt (Memory trial metrics). */
     promptSize(taskId: string, run_id: string, chars: number, parts?: Record<string, number>): Promise<any>;
     usage(taskId: string, run_id: string, cost_usd: number, estimated: boolean): Promise<any>;
+    /**
+     * design §27: what keeps this agent's runner from taking tasks on its machine (null: nothing). The hub shows it as
+     * "needs setup" with the fix.
+     */
+    reportSetup(sandbox: {
+        tool: string;
+        problem: string;
+        detail?: string;
+        fix?: {
+            en: string;
+            zh: string;
+            commands: string[];
+        };
+    } | null): Promise<any>;
     /** 409 when the run lost the task. Carries a fresh `run_token` when the old one is near expiry (C5). */
     heartbeat(taskId: string, run_id: string): Promise<{
         ok: boolean;

package/dist/src/client.js

@@ -297,6 +297,13 @@ export class Client {
     async usage(taskId, run_id, cost_usd, estimated) {
         return this.ach('POST', `/tasks/${enc(taskId)}/usage`, { run_id, cost_usd, estimated });
     }
+    /**
+     * design §27: what keeps this agent's runner from taking tasks on its machine (null: nothing). The hub shows it as
+     * "needs setup" with the fix.
+     */
+    async reportSetup(sandbox) {
+        return this.ach('PUT', '/me/setup', { sandbox });
+    }
     /** 409 when the run lost the task. Carries a fresh `run_token` when the old one is near expiry (C5). */
     async heartbeat(taskId, run_id) {
         return this.ach('POST', `/tasks/${enc(taskId)}/heartbeat`, { run_id });

package/dist/src/doctor.d.ts

@@ -49,6 +49,10 @@ export declare function runDoctor(o: {
     fetch?: FetchLike;
     exec?: ExecLike;
     self?: string;
+    /** the sandbox probe (tests) */
+    sandbox?: (tool: 'claude' | 'codex', o: {
+        env: NodeJS.ProcessEnv;
+    }) => Promise<import('./sandboxcheck.js').SandboxStatus>;
 }): Promise<DoctorCheck[]>;
 /**
  * Command, args and AGENTCHANNEL_HOME of an MCP entry from `claude mcp get`

package/dist/src/doctor.js

@@ -247,6 +247,7 @@ export async function runDoctor(o) {
             const { serviceFile, serviceLabel } = await import('./service.js');
             const platform = (env.ACH_SERVICE_PLATFORM || process.platform);
             if (platform === 'darwin' || platform === 'linux') {
+                // (Windows: the Startup script has no status command; doctor says nothing rather than guess)
                 const f = serviceFile({ platform, agentName, command: [], args: [], env: {}, logFile: '' }, env.ACH_SERVICE_DIR || undefined);
                 if (!existsSync(f.path))
                     add('background', 'info', 'no background runner on this machine (optional: ach run --dir <repo> --install-service --interactive-first)');
@@ -299,6 +300,17 @@ export async function runDoctor(o) {
         if (codexPath)
             await mcpCheck('codex', codexPath);
     }
+    // design §27: the agent tool's sandbox, probed for real (every run that answers a question or an @mention is sandboxed)
+    const { probeSandbox } = await import('./sandboxcheck.js');
+    const tools = runtime === 'codex' ? ['codex'] : runtime === 'claude' ? ['claude'] : [...(claude ? ['claude'] : []), ...(codexPath || bundled ? ['codex'] : [])];
+    for (const t of tools) {
+        const st = await (o.sandbox ?? probeSandbox)(t, { env });
+        const name = `${t} sandbox`;
+        if (st.ok)
+            add(name, st.unverified ? 'info' : 'ok', st.unverified ? `not checked: ${st.detail ?? 'unknown'}` : 'starts, and stops writes outside the task directory');
+        else
+            add(name, runtime ? 'fail' : 'warn', `${st.fix?.en ?? st.detail ?? st.problem}${runtime ? ' The background runner takes no tasks until this is fixed.' : ''}`, 'machine', st.fix?.commands.length ? st.fix.commands.join('\n            ') : st.fix?.en);
+    }
     return out;
     /**
      * The `ach` MCP entry as the runtime itself reports it (`<runtime> mcp get

package/dist/src/onboard.d.ts

@@ -1,10 +1,14 @@
 import type { ExecLike } from './doctor.js';
+import { type SandboxStatus, type SandboxTool } from './sandboxcheck.js';
 /**
  * One-line onboarding: what `ach join` sets up after the key is stored.
  *
  *   1. connect: add the `ach` MCP server to the agent's own tool (Claude Code
  *      for a claude agent, Codex for a codex one; both found ones for "other")
- *   2. background helper, only with --service: `ach run --install-service`
+ *   2. sandbox (design §27): when the probe of the agent tool's sandbox fails, the
+ *      commands that fix it (sudo included), run only after Enter in a terminal;
+ *      with no terminal they are printed and nothing runs
+ *   3. background helper, only with --service: `ach run --install-service`
  *      (+ --notify on a machine with a desktop), which installs and starts it.
  *      Run through npx, the helper runs the same pinned npx spec as the MCP
  *      entry, never a path in the npx cache.
@@ -22,6 +26,10 @@ export interface SetupIo {
     /** Asks one question; undefined = not interactive. */
     ask?: (q: string) => Promise<string>;
     cwd: string;
+    /** Runs a shell line with this terminal (sudo can ask for a password); the exit code. Absent: sandbox fixes are only printed. */
+    runTty?: (line: string) => Promise<number>;
+    /** The sandbox probe (tests). */
+    sandbox?: (tool: SandboxTool) => Promise<SandboxStatus>;
 }
 export interface SetupOptions {
     yes: boolean;
@@ -40,7 +48,7 @@ export interface SetupOptions {
 }
 export type Argv = string[];
 export interface Step {
-    id: 'connect' | 'service';
+    id: 'connect' | 'sandbox' | 'service';
     question: string;
     /** Commands, printed as shell lines and run one by one. */
     commands: Argv[];
@@ -92,6 +100,7 @@ export declare function planSteps(d: Detected, o: {
     runtime?: string;
     service?: boolean;
     desktop?: boolean;
+    sandbox?: SandboxStatus[];
 }): Step[];
 export interface SetupResult {
     ran: string[];

package/dist/src/onboard.js

@@ -1,5 +1,6 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { probeSandbox } from './sandboxcheck.js';
 import { identifyAch, isOurs, MCP_SERVER_NAME, npxAch, thisCliPath, userBin, whichAll } from './invite.js';
 /** The closing line: which tool to open and what to say to it. */
 export function doneLine(tools, zh) {
@@ -105,7 +106,20 @@ export function planSteps(d, o) {
         connect.question = [zh ? `把 AgentChannel 接入 ${where}？会运行：` : `Add AgentChannel to ${where}? This runs:`, ...lines].join('\n') + '\n';
         steps.push(connect);
     }
-    // 2. background helper: only when asked for (--service)
+    // 2. sandbox: the fix for each tool whose sandbox probe failed (one command list; the same line twice runs once)
+    const broken = (o.sandbox ?? []).filter((st) => !st.ok && st.fix);
+    if (broken.length) {
+        const lines = [...new Set(broken.flatMap((st) => st.fix.commands))];
+        const why = broken.map((st) => `  ${zh ? st.fix.zh : st.fix.en}`);
+        steps.push({
+            id: 'sandbox',
+            question: lines.length
+                ? [...why, zh ? '现在修复？会运行（可能要输入你的系统密码）：' : 'Fix it now? This runs (it may ask for your password):', ...lines.map((l) => `  ${l}`)].join('\n') + '\n'
+                : why.join('\n') + '\n',
+            commands: lines.map((l) => ['/bin/sh', '-c', l]),
+        });
+    }
+    // 3. background helper: only when asked for (--service)
     if (o.service) {
         const notify = o.desktop !== false;
         const helper = ['run', '--install-service', ...(notify ? ['--notify'] : []), '--interactive-first', '--dir', o.cwd];
@@ -135,7 +149,10 @@ export async function runSetup(io, o) {
     const result = { ran: [], skipped: [], failed: [], tools: [] };
     const zh = !!o.zh;
     const desktop = hasDesktop(env);
-    const plan = planSteps(d, { home, achCmd: d.achCmd, cwd: io.cwd, zh, env, runtime: o.runtime, service: o.service, desktop });
+    // design §27: probe the sandbox of the tools this agent runs with (not in a dry run: it runs nothing)
+    const probe = io.sandbox ?? ((t) => probeSandbox(t, { env }));
+    const sandbox = o.dryRun ? [] : await Promise.all(toolsFor(o.runtime).map((t) => probe(t)));
+    const plan = planSteps(d, { home, achCmd: d.achCmd, cwd: io.cwd, zh, env, runtime: o.runtime, service: o.service, desktop, sandbox });
     if (o.dryRun) {
         printOnly(io, d, plan, { zh, join: o.join });
         return result;
@@ -173,10 +190,23 @@ export async function runSetup(io, o) {
         return failedBins.size === 0;
     };
     for (const s of plan) {
+        // nothing to run (no safe command for this machine), or no terminal to run sudo in: say what to do and go on
+        if (s.id === 'sandbox' && (!s.commands.length || !io.ask || !io.runTty)) {
+            io.err(s.question.trimEnd());
+            if (s.commands.length)
+                io.err(zh ? '  没有终端，所以没有运行。请在终端里运行上面的命令，然后运行 ach doctor 检查。' : '  No terminal, so nothing was run. Run the commands above in a terminal, then check with ach doctor.');
+            result.failed.push('sandbox');
+            continue;
+        }
         if (!(await ask(s))) {
             result.skipped.push(s.id);
             continue;
         }
+        if (s.id === 'sandbox') {
+            const ok = await fixSandbox(io, s, sandbox, probe, zh);
+            (ok ? result.ran : result.failed).push('sandbox');
+            continue;
+        }
         if (s.id === 'service') {
             const ok = await installService(io, s.commands[0]);
             (ok ? result.ran : result.failed).push('service');
@@ -198,6 +228,27 @@ export async function runSetup(io, o) {
     }
     return result;
 }
+/** Run the sandbox fix in this terminal, then probe again: true when every tool's sandbox works now. */
+async function fixSandbox(io, s, before, probe, zh) {
+    for (const c of s.commands) {
+        const code = await io.runTty(c[2]);
+        if (code !== 0) {
+            io.err(`  failed (exit ${code}): ${c[2]}`);
+            return false;
+        }
+    }
+    let ok = true;
+    for (const st of before.filter((x) => !x.ok)) {
+        const now = await probe(st.tool);
+        if (now.ok)
+            io.out(zh ? `  ${st.tool === 'claude' ? 'Claude Code' : 'Codex'} 的沙箱可以用了` : `  ${st.tool === 'claude' ? 'Claude Code' : 'Codex'}'s sandbox works now`);
+        else {
+            ok = false;
+            io.err(`  ${zh ? now.fix?.zh : now.fix?.en}`);
+        }
+    }
+    return ok;
+}
 /** `ach run --install-service --json`: it writes the unit and starts it (not under ACH_SERVICE_DIR: tests). */
 async function installService(io, argv) {
     const r = await io.exec(argv[0], [...argv.slice(1), '--json'], io.env);
@@ -226,6 +277,7 @@ function printOnly(io, d, plan, o) {
     }
     for (const s of plan)
         out.push(s.question.trimEnd());
+    out.push(zh ? '  检查这台机器能否运行智能体的沙箱；不能时给出修复命令，你同意后才运行' : "  check that the agent's sandbox works on this machine; if not, show the fix and run it only after you agree");
     out.push('', `${zh ? '随时检查配置：' : 'Check the setup any time with: '}${shellLine([...(d.npx ? d.achCmd : ['ach']), 'doctor'])}`);
     io.out(out.join('\n'));
 }

package/dist/src/runner/runner.d.ts

@@ -3,7 +3,8 @@ import { type Agent, type Client, type MentionItem, type Message } from '../clie
 import { type Perm } from '../perm.js';
 import { RunnerState } from './state.js';
 import type { Workspace } from './workspace.js';
-export type RunnerClient = Pick<Client, 'me' | 'inbox' | 'claim' | 'getTask' | 'postMessage' | 'complete' | 'fail' | 'usage' | 'heartbeat' | 'answerRun' | 'endRun'> & Partial<Pick<Client, 'download' | 'channelPosts' | 'mentionRun' | 'mentionEnd' | 'mentionUsage' | 'promptSize'>>;
+import { type SandboxStatus } from '../sandboxcheck.js';
+export type RunnerClient = Pick<Client, 'me' | 'inbox' | 'claim' | 'getTask' | 'postMessage' | 'complete' | 'fail' | 'usage' | 'heartbeat' | 'answerRun' | 'endRun'> & Partial<Pick<Client, 'download' | 'channelPosts' | 'mentionRun' | 'mentionEnd' | 'mentionUsage' | 'promptSize' | 'reportSetup'>>;
 export interface RunnerOptions {
     client: RunnerClient;
     adapter: RuntimeAdapter;
@@ -39,6 +40,12 @@ export interface RunnerOptions {
     agentHomesDir?: string;
     /** §16: how many recent channel posts work prompts carry (default 15; 0 = none). */
     channelContext?: number;
+    /**
+     * design §27: probes the agent tool's sandbox. While it fails the runner takes nothing new (tasks wait in the hub's
+     * inbox), reports why, and probes again every `sandboxRecheckMs`. Absent: no check (tests).
+     */
+    sandboxCheck?: () => Promise<SandboxStatus>;
+    sandboxRecheckMs?: number;
 }
 export type Job = {
     kind: 'work';
@@ -141,6 +148,13 @@ export declare class Runner {
     /** B7: set when the hub answered 401 (key rotated, agent or owner deactivated): the runner stops. */
     fatal?: 'unauthorized';
     private wake?;
+    /** design §27: the last sandbox probe, when it ran, and what the hub was last told (a JSON key). */
+    sandbox?: {
+        st: SandboxStatus;
+        at: number;
+    };
+    private sandboxReported?;
+    private sandboxRecheck;
     constructor(opts: RunnerOptions);
     private log;
     private taskLog;
@@ -155,6 +169,8 @@ export declare class Runner {
     authFailed(where: string): void;
     /** One poll cycle. */
     tick(): Promise<void>;
+    /** design §27: probe the sandbox when due, tell the hub when the answer changes; true = take nothing new. */
+    private sandboxBlocked;
     private notifyBudget;
     /**
      * Cancel running jobs whose task went terminal; forget parked runs of

package/dist/src/runner/runner.js

@@ -10,6 +10,7 @@ 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 { looksLikeSandboxError } from '../sandboxcheck.js';
 export function jobKey(j) {
     if (j.kind === 'mention')
         return `mention:${j.item.mention.id}`;
@@ -207,6 +208,10 @@ 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;
     constructor(opts) {
         this.o = { max: 2, perm: 'workdir', intervalMs: 3000, heartbeatMs: 30_000, idleMs: 60 * 60_000, ...opts };
         this.state = new RunnerState(opts.home);
@@ -285,6 +290,8 @@ export class Runner {
         await this.prune();
         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 +339,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));
+        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;
@@ -778,6 +829,8 @@ export class Runner {
             return;
         }
         if (!result.ok) {
+            if (looksLikeSandboxError(result.error ?? ''))
+                this.sandboxRecheck = true;
             await client.fail(taskId, `runtime error: ${result.error ?? 'unknown'}`, rec.runId).catch((e) => this.log(`fail ${taskId}: ${e?.message ?? e}`));
             this.state.drop(taskId);
             return;

package/dist/src/sandboxcheck.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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'
+/** 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 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,232 @@
+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` : '') });
+    });
+});
+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 '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);
+}

package/dist/src/service.d.ts

@@ -1,10 +1,11 @@
 /**
  * P4: `ach run --install-service` writes a macOS launchd agent or a Linux
  * systemd user unit that starts this runner at login and restarts it, then
- * loads it (startService).
+ * loads it (startService). design §27, Windows: a script in the user's Startup
+ * folder (no admin rights needed) that runs the runner hidden and restarts it.
  */
 export interface ServiceSpec {
-    platform: 'darwin' | 'linux';
+    platform: 'darwin' | 'linux' | 'win32';
     agentName: string;
     /** What starts the CLI: node + cli.js of an install, or `npx -y <spec>` when it runs from the npx cache. */
     command: string[];
@@ -23,6 +24,11 @@ export interface ServiceFile {
 export declare function serviceLabel(agentName: string): string;
 export declare function launchdPlist(s: ServiceSpec): string;
 export declare function systemdUnit(s: ServiceSpec): string;
-export declare function serviceFile(s: ServiceSpec, dir?: string): ServiceFile;
+/**
+ * Windows: a VBScript in the Startup folder. It runs the runner with no window, appends its output to the log, and
+ * starts it again 10 s after it exits, except after exit 78 (key rotated or agent deactivated: restarting cannot help).
+ */
+export declare function windowsScript(s: ServiceSpec): string;
+export declare function serviceFile(s: ServiceSpec, dir?: string, env?: NodeJS.ProcessEnv): ServiceFile;
 /** Write the unit file (mode 0644; it holds no secrets). */
 export declare function writeServiceFile(f: ServiceFile): void;

package/dist/src/service.js

@@ -72,7 +72,45 @@ RestartPreventExitStatus=78
 WantedBy=default.target
 `;
 }
-export function serviceFile(s, dir) {
+/** VBScript string literal. */
+function vbs(s) {
+    return `"${s.replace(/"/g, '""')}"`;
+}
+/** cmd.exe argument: quoted unless plain. */
+function cmdArg(s) {
+    return /^[A-Za-z0-9_.:\\/=@,+-]+$/.test(s) ? s : `"${s.replace(/"/g, '\\"')}"`;
+}
+/**
+ * Windows: a VBScript in the Startup folder. It runs the runner with no window, appends its output to the log, and
+ * starts it again 10 s after it exits, except after exit 78 (key rotated or agent deactivated: restarting cannot help).
+ */
+export function windowsScript(s) {
+    const line = `${[...s.command, 'run', ...s.args].map(cmdArg).join(' ')} >> ${cmdArg(s.logFile)} 2>&1`;
+    const env = Object.entries(s.env).map(([k, v]) => `env(${vbs(k)}) = ${vbs(v)}`).join('\n');
+    return `' AgentChannel runner (agent ${s.agentName}): starts at login, restarts after it exits (not after exit 78).
+Option Explicit
+Dim sh, env, code
+Set sh = CreateObject("WScript.Shell")
+Set env = sh.Environment("Process")
+${env}
+Do
+  code = sh.Run("cmd /c " & ${vbs(`"${line}"`)}, 0, True)
+  If code = 78 Then Exit Do
+  WScript.Sleep 10000
+Loop
+`;
+}
+export function serviceFile(s, dir, env = process.env) {
+    if (s.platform === 'win32') {
+        const name = `agentchannel-runner-${s.agentName.replace(/[^A-Za-z0-9-]/g, '-')}.vbs`;
+        const startup = join(env.APPDATA || join(homedir(), 'AppData', 'Roaming'), 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Startup');
+        const path = join(dir ?? startup, name);
+        // stop: the script's own wscript, then the runner it started (its command line holds the same --dir)
+        const kill = (like) => `Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -like '${like.replace(/'/g, "''")}' } | ForEach-Object { Invoke-CimMethod -InputObject $_ -MethodName Terminate | Out-Null }`;
+        const dirArg = s.args[s.args.indexOf('--dir') + 1] ?? '';
+        const stop = `powershell -NoProfile -Command "${kill(`*${name}*`)}; ${kill(`* run *--dir*${dirArg}*`)}"`;
+        return { path, content: windowsScript(s), start: [`${stop}`, `wscript "${path}"`], stop: [stop, `del "${path}"`] };
+    }
     if (s.platform === 'darwin') {
         const label = serviceLabel(s.agentName);
         const path = join(dir ?? join(homedir(), 'Library', 'LaunchAgents'), `${label}.plist`);

package/dist/src/version.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "3.10.0";
+export declare const VERSION = "3.11.0";
 /** The npm package (scripts/release.mjs keeps it and VERSION in step with package.json). */
 export declare const PKG_NAME = "@koalaauto/agentchannel";
 /**

package/dist/src/version.js

@@ -1,4 +1,4 @@
-export const VERSION = '3.10.0';
+export const VERSION = '3.11.0';
 /** The npm package (scripts/release.mjs keeps it and VERSION in step with package.json). */
 export const PKG_NAME = '@koalaauto/agentchannel';
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@koalaauto/agentchannel",
-  "version": "3.10.0",
+  "version": "3.11.0",
   "description": "Hand work between your team's agents (Claude Code, Codex) and follow it in one panel: the ach CLI, MCP server and runner for AgentChannel v2",
   "keywords": [
     "agentchannel",