@koalaauto/agentchannel 0.0.0-stage → 3.0.0

package/dist/src/doctor.js

@@ -0,0 +1,375 @@
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { Client } from './client.js';
+import { achHome, loadAgentKey, loadConfig } from './config.js';
+import { hubTransportOk, identifyAch, isOurs, npmSpec, thisCliPath, userBin, whichAll } from './invite.js';
+import { openKeyStore } from './keystore.js';
+import { PKG_NAME, VERSION } from './version.js';
+/** Ask-the-admin fix: a fresh join line carries a new key and whatever the hub needs to let you in. */
+export const NEW_LINE_FIX = 'ask your admin to run `ach admin invite <your agent>` again and paste the new line';
+/** Allowed clock difference with the hub before warning (login links and tokens are time-bound). */
+export const CLOCK_SKEW_WARN_MS = 5 * 60_000;
+function causeCode(e) {
+    return String(e?.cause?.code ?? e?.code ?? '');
+}
+/** GET /api/health without following redirects, and classify what came back. */
+export async function probeHub(hub, headers, fetchFn) {
+    let res;
+    try {
+        res = await fetchFn(`${hub}/api/health`, { method: 'GET', headers, redirect: 'manual' });
+    }
+    catch (e) {
+        const code = causeCode(e);
+        const message = String(e?.cause?.message ?? e?.message ?? e);
+        if (/ENOTFOUND|EAI_AGAIN|EAI_NONAME/.test(code))
+            return { kind: 'dns', message };
+        if (/ECONNREFUSED|ECONNRESET|EHOSTUNREACH|ENETUNREACH/.test(code))
+            return { kind: 'refused', message };
+        if (/TIMEOUT|ETIMEDOUT|ABORT/i.test(code) || /timeout/i.test(message))
+            return { kind: 'timeout', message };
+        if (/CERT|SSL|TLS|SELF_SIGNED/i.test(code + message))
+            return { kind: 'tls', message };
+        return { kind: 'network', message };
+    }
+    const loc = res.headers.get('location') ?? '';
+    if (res.status >= 300 && res.status < 400 && /cloudflareaccess\.com|\/cdn-cgi\/access\//i.test(loc))
+        return { kind: 'gate', status: res.status, where: loc };
+    if ((res.status === 401 || res.status === 403) && (res.headers.get('cf-ray') || /cloudflare/i.test(res.headers.get('server') ?? '')) && !/application\/json/.test(res.headers.get('content-type') ?? '')) {
+        return { kind: 'gate', status: res.status, where: 'the hub address' };
+    }
+    if (res.status >= 300 && res.status < 400)
+        return { kind: 'gate', status: res.status, where: loc || 'a sign-in page' };
+    if (!res.ok)
+        return { kind: 'http', status: res.status };
+    return { kind: 'ok', status: res.status, date: res.headers.get('date') ?? undefined };
+}
+function probeText(p, host) {
+    switch (p.kind) {
+        case 'dns': return { detail: `cannot find ${host} (${p.message})`, fix: 'check the hub address in the line from your admin, and that you are on the right network or VPN' };
+        case 'refused': return { detail: `${host} refused the connection (${p.message})`, fix: 'the hub may be down: ask your admin whether it is running' };
+        case 'timeout': return { detail: `${host} did not answer in time`, fix: 'check your network or VPN; if others can reach it, ask your admin' };
+        case 'tls': return { detail: `the secure connection to ${host} failed (${p.message})`, fix: 'check the date and time on this machine; otherwise ask your admin to check the hub certificate' };
+        case 'http': return { detail: `${host} answered HTTP ${p.status}`, fix: 'ask your admin to check the hub' };
+        default: return { detail: p.message ?? String(p.kind), fix: 'check your network, then run ach doctor again' };
+    }
+}
+/** Runs a status command with a timeout; never throws. */
+export const defaultExec = (file, args, env) => new Promise((res) => {
+    execFile(file, args, { env, timeout: 15_000, encoding: 'utf8', maxBuffer: 1 << 20 }, (err, stdout, stderr) => {
+        res({ code: err ? (typeof err.code === 'number' ? err.code : 1) : 0, stdout: String(stdout ?? ''), stderr: String(stderr ?? '') });
+    });
+});
+/** The Codex CLI the runner's SDK uses when `codex` is not on PATH. */
+function bundledCodex() {
+    try {
+        const req = createRequire(import.meta.url);
+        const f = join(dirname(req.resolve('@openai/codex/package.json')), 'bin', 'codex.js');
+        return existsSync(f) ? f : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function firstLine(s) {
+    return (s.split('\n').find((l) => l.trim()) ?? '').trim().slice(0, 160);
+}
+/**
+ * `ach doctor`: a read-only setup check. Never prints the key
+ * or the CF secret, and never reads Claude/Codex credential files: login state
+ * comes from `claude auth status` and `codex login status`.
+ */
+export async function runDoctor(o) {
+    const env = o.env;
+    const exec = o.exec ?? defaultExec;
+    const out = [];
+    const add = (name, status, detail, section, fix) => out.push({ name, status, detail, ...(section && section !== 'machine' ? { section } : {}), ...(fix && status !== 'ok' && status !== 'info' ? { fix } : {}) });
+    add('version', 'info', `ach ${VERSION} (${o.self ?? thisCliPath()})`);
+    // Home
+    const home = achHome(env);
+    add('home', existsSync(home) ? 'ok' : 'warn', `${home}${env.AGENTCHANNEL_HOME ? ' (AGENTCHANNEL_HOME)' : ''}${existsSync(home) ? '' : ' does not exist yet: run the `ach join ...` line'}`);
+    // Config and key
+    const cfg = loadConfig(env);
+    add('hub', cfg.hub ? 'ok' : 'fail', cfg.hub ? `${cfg.hub}${env.ACH_HUB ? ' (ACH_HUB)' : ''}` : 'no hub configured', 'hub', `paste the join line from your admin (npx -y ${npmSpec()} join ach2....)`);
+    let key;
+    let keyErr = '';
+    try {
+        key = env.ACH_KEY || loadAgentKey(env);
+    }
+    catch (e) {
+        keyErr = String(e?.message ?? e);
+    }
+    const where = env.ACH_KEY ? 'ACH_KEY' : openKeyStore(home, env).kind === 'keychain' ? 'OS keychain' : 'agent-key file';
+    add('agent key', key ? 'ok' : 'fail', key ? `present (${where}; not shown)` : `missing${keyErr ? ` (${keyErr})` : ''}`, 'key', key ? undefined : 'paste the join line from your admin again');
+    // Hub: reachable over HTTPS; front door (if any); the key works; clock
+    let runtime;
+    let agentName;
+    if (cfg.hub) {
+        const fetchFn = o.fetch ?? ((u, i) => fetch(u, i));
+        let host = cfg.hub;
+        try {
+            const u = new URL(cfg.hub);
+            host = u.host;
+            if (!hubTransportOk(cfg.hub)) {
+                add('hub https', 'warn', `${cfg.hub} is plain http:// to ${u.host} (not this machine): your key and every task travel unencrypted`, 'hub', 'ask your admin for the https:// address of the hub, then paste the new join line');
+            }
+            else if (u.protocol !== 'https:')
+                add('hub https', 'info', `${cfg.hub} is plain http:// to a local address (${u.host})`, 'hub');
+        }
+        catch {
+            add('hub', 'fail', `${cfg.hub} is not a valid address`, 'hub', 'paste the join line from your admin again');
+        }
+        const hasPass = !!(cfg.cfId && cfg.cfSecret);
+        const pass = hasPass ? { 'CF-Access-Client-Id': cfg.cfId, 'CF-Access-Client-Secret': cfg.cfSecret } : {};
+        const bare = await probeHub(cfg.hub, { accept: 'application/json' }, fetchFn);
+        const withPass = hasPass && bare.kind === 'gate' ? await probeHub(cfg.hub, { accept: 'application/json', ...pass }, fetchFn) : bare;
+        let reachable = false;
+        let date;
+        if (bare.kind === 'gate') {
+            add('hub reachable', 'ok', `${host} answers (behind a front door)`, 'hub');
+            const passSrc = env.ACH_CF_ID && env.ACH_CF_SECRET ? 'from ACH_CF_ID/ACH_CF_SECRET' : 'stored by join; not shown';
+            if (withPass.kind === 'ok') {
+                reachable = true;
+                date = withPass.date;
+                add('front door', 'ok', `the hub's front door lets this machine in (${passSrc})`, 'front door');
+            }
+            else if (!hasPass) {
+                add('front door', 'fail', `the hub's front door (sign-in page at ${shortWhere(bare.where)}) blocks this machine: no pass for it is stored`, 'front door', NEW_LINE_FIX);
+            }
+            else {
+                add('front door', 'fail', `the hub's front door refused this machine's pass (HTTP ${withPass.status ?? '?'}): it expired or was revoked`, 'front door', NEW_LINE_FIX);
+            }
+        }
+        else if (bare.kind === 'ok') {
+            reachable = true;
+            date = bare.date;
+            add('hub reachable', 'ok', `${cfg.hub}/api/health`, 'hub');
+            if (hasPass)
+                add('front door', 'info', 'a front-door pass is stored, but the hub does not ask for one', 'front door');
+        }
+        else {
+            const t = probeText(bare, host);
+            add('hub reachable', 'fail', t.detail, 'hub', t.fix);
+        }
+        if (date) {
+            const skew = Date.parse(date) - Date.now();
+            if (Number.isFinite(skew) && Math.abs(skew) > CLOCK_SKEW_WARN_MS) {
+                add('clock', 'warn', `this machine's clock is ${Math.round(Math.abs(skew) / 60_000)} min ${skew > 0 ? 'behind' : 'ahead of'} the hub`, 'hub', 'turn on automatic date and time (login links and tokens are time-limited)');
+            }
+            else if (Number.isFinite(skew))
+                add('clock', 'ok', 'in sync with the hub', 'hub');
+        }
+        if (key && reachable) {
+            const c = new Client({ hub: cfg.hub, token: key, cfId: cfg.cfId, cfSecret: cfg.cfSecret, fetch: o.fetch });
+            try {
+                const me = await c.me();
+                runtime = typeof me.runtime === 'string' ? me.runtime : undefined;
+                agentName = me.name;
+                add('hub login', 'ok', `agent ${me.name}${me.owner_name ? ` (owner ${me.owner_name})` : ''}, runtime ${me.runtime ?? '?'}`, 'key');
+            }
+            catch (e) {
+                const st = e?.status;
+                const why = st === 401 ? (e?.code === 'owner_deactivated' ? "the agent's owner is deactivated" : 'the key was replaced or the agent was turned off') : `${st ?? ''} ${e?.message ?? e}`.trim();
+                add('hub login', 'fail', `the hub refused the key: ${why}`, 'key', NEW_LINE_FIX);
+            }
+        }
+    }
+    // Which `ach` runs
+    const self = o.self ?? thisCliPath();
+    const achs = whichAll('ach', env).map((p) => identifyAch(p, self));
+    if (!achs.length) {
+        add('ach on PATH', 'warn', 'no `ach` command on PATH', 'machine', `npm install -g ${npmSpec()} (needed only to type \`ach\` yourself or for the background helper: the join line with --service does it)`);
+    }
+    else {
+        const desc = (a) => `${a.path}${a.real && a.real !== a.path ? ` -> ${a.real}` : ''} (${a.ours ? 'this CLI' : `${a.name ?? 'unknown'} ${a.version ?? ''}`.trim()})`;
+        const first = achs[0];
+        if (isOurs(first))
+            add('ach on PATH', 'ok', desc(first));
+        else {
+            add('ach on PATH', 'fail', `${desc(first)} is another program called \`ach\` and comes first on PATH, so \`ach ...\` runs it. MCP entries made by \`ach join\` use this CLI's absolute path meanwhile.`, 'machine', `remove it or put this CLI first on PATH (or use npx -y ${npmSpec()} …); see below`);
+            add('fix', 'info', shadowFix(first, achs.find((a) => isOurs(a)), self));
+        }
+        for (const a of achs.slice(1))
+            add('ach (shadowed)', isOurs(a) ? 'info' : 'warn', desc(a));
+    }
+    if (/[\\/]_npx[\\/]/.test(self)) {
+        add('install', 'warn', 'this `ach` runs from the npx cache, which npm may clear', 'machine', `npm install -g ${npmSpec()}`);
+    }
+    // Background runner (ach run --install-service): is a unit file there?
+    if (agentName) {
+        try {
+            const { serviceFile } = await import('./service.js');
+            const platform = (env.ACH_SERVICE_PLATFORM || process.platform);
+            if (platform === 'darwin' || platform === 'linux') {
+                const f = serviceFile({ platform, agentName, node: '', cli: '', args: [], env: {}, logFile: '' }, env.ACH_SERVICE_DIR || undefined);
+                add('background', 'info', existsSync(f.path) ? `tasks are picked up in the background (${f.path})` : 'no background runner on this machine (optional: ach run --dir <repo> --install-service --interactive-first)');
+            }
+        }
+        catch {
+            /* informational only */
+        }
+    }
+    // Claude / Codex login (their own status commands; credential files are never read)
+    const claude = userBin('claude', env);
+    if (!claude)
+        add('claude', 'info', 'not on PATH (needed only for the claude runtime or Claude Code)');
+    else {
+        const r = await exec(claude, ['auth', 'status'], env);
+        let detail = firstLine(r.stdout || r.stderr);
+        let ok = r.code === 0;
+        try {
+            const j = JSON.parse(r.stdout);
+            ok = ok && j.loggedIn === true;
+            detail = j.loggedIn ? `logged in (${j.authMethod ?? 'unknown method'})` : 'not logged in: run `claude auth login`';
+        }
+        catch {
+            /* text output */
+        }
+        // round 2: only the agent's own runtime login matters; the other is informational
+        add('claude login', ok ? 'ok' : runtime && runtime !== 'claude' ? 'info' : 'warn', detail || `exit ${r.code}`);
+        await mcpCheck('claude', claude);
+    }
+    // a codex that npx put on PATH (this package's SDK dependency) is not the user's Codex
+    const codexPath = userBin('codex', env);
+    const bundled = codexPath ? undefined : bundledCodex();
+    if (!codexPath && !bundled)
+        add('codex', 'info', 'not found (needed only for the codex runtime)');
+    else {
+        const r = codexPath ? await exec(codexPath, ['login', 'status'], env) : await exec(process.execPath, [bundled, 'login', 'status'], env);
+        const detail = firstLine(r.stdout || r.stderr) || `exit ${r.code}`;
+        add('codex login', r.code === 0 ? 'ok' : runtime && runtime !== 'codex' ? 'info' : 'warn', `${detail}${codexPath ? '' : ' (bundled codex)'}`);
+        if (codexPath)
+            await mcpCheck('codex', codexPath);
+    }
+    return out;
+    /**
+     * The `ach` MCP entry as the runtime itself reports it (`<runtime> mcp get
+     * ach`): what command it runs and whether that is this CLI. Never assumed from
+     * what join did.
+     */
+    async function mcpCheck(name, bin) {
+        const mine = !runtime || runtime === name;
+        const r = await exec(bin, ['mcp', 'get', 'ach'], env);
+        const fix = `run the join line again on this machine: it adds it to ${name === 'claude' ? 'Claude Code' : 'Codex'}`;
+        if (r.code !== 0) {
+            add(`${name} mcp`, mine ? 'warn' : 'info', `no \`ach\` MCP entry (\`${name} mcp get ach\` exit ${r.code})`, 'machine', fix);
+        }
+        else {
+            const e = parseMcpEntry(r.stdout, 'ach');
+            if (!e.command)
+                add(`${name} mcp`, 'warn', `an \`ach\` entry exists but \`${name} mcp get ach\` did not show its command: ${firstLine(r.stdout) || '(no output)'}`, 'machine', fix);
+            else {
+                const v = entryVersion(e, env, o.self ?? thisCliPath());
+                const shown = `runs \`${[e.command, ...e.args].join(' ')}\`${e.home ? ` with AGENTCHANNEL_HOME=${e.home}` : ''}`;
+                if (!v.ok)
+                    add(`${name} mcp`, 'warn', `\`ach\` entry ${shown}: ${v.why}`, 'machine', fix);
+                else if (e.home && !e.home.includes('*') && e.home !== achHome(env))
+                    add(`${name} mcp`, 'warn', `\`ach\` entry ${shown}, but this machine's AgentChannel home is ${achHome(env)}`, 'machine', fix);
+                else
+                    add(`${name} mcp`, 'ok', `\`ach\` entry ${shown} (${v.why})`);
+            }
+        }
+    }
+}
+/**
+ * Command, args and AGENTCHANNEL_HOME of an MCP entry from `claude mcp get`
+ * ("Command: npx" / "Args: -y @koalaauto/agentchannel@3 mcp" / "AGENTCHANNEL_HOME=...")
+ * or `codex mcp get` ("command: npx" / "args: ..." / "env: AGENTCHANNEL_HOME=..."),
+ * or a `name: command args` line (mcp list style).
+ */
+export function parseMcpEntry(text, name) {
+    const cmd = /^\s*command:\s*(.+?)\s*$/im.exec(text)?.[1];
+    const args = /^\s*args:\s*(.*?)\s*$/im.exec(text)?.[1];
+    const home = /AGENTCHANNEL_HOME=([^\s,}]+)/.exec(text)?.[1];
+    if (cmd)
+        return { command: cmd, args: args && args !== '-' && args !== '[]' ? args.replace(/^\[|\]$/g, '').split(/[\s,]+/).map((x) => x.replace(/^"|"$/g, '')).filter(Boolean) : [], home };
+    const line = new RegExp(`^\\s*${name}:\\s+(\\S.*?)(?:\\s+-\\s+[✓✗!].*)?$`, 'm').exec(text)?.[1];
+    if (!line)
+        return { args: [], home };
+    const parts = line.split(/\s+/);
+    return { command: parts[0], args: parts.slice(1), home };
+}
+/** Whether an MCP entry starts this CLI's package, and why (or why not). */
+function entryVersion(e, env, self) {
+    const all = [e.command, ...e.args];
+    if (all.at(-1) !== 'mcp')
+        return { ok: false, why: 'it does not end with `mcp`' };
+    if (/(^|[\\/])npx$/.test(e.command)) {
+        const spec = all.find((a) => a === PKG_NAME || a.startsWith(`${PKG_NAME}@`));
+        return spec ? { ok: true, why: `through npx (${spec})` } : { ok: false, why: `npx does not start ${PKG_NAME}` };
+    }
+    // node <path>/cli.js mcp, or an ach executable
+    const target = /(^|[\\/])node(\.exe)?$/.test(e.command) ? e.args[0] : e.command;
+    if (!target)
+        return { ok: false, why: 'no CLI path' };
+    const path = target.includes('/') || target.includes('\\') ? target : whichAll(target, env)[0];
+    if (!path)
+        return { ok: false, why: `\`${target}\` is not on PATH` };
+    if (!existsSync(path))
+        return { ok: false, why: `${path} does not exist` };
+    const i = identifyAch(path, self);
+    return isOurs(i) ? { ok: true, why: i.ours ? 'this CLI' : `${PKG_NAME} ${i.version}` } : { ok: false, why: `${path} is ${i.name ?? 'not AgentChannel'} ${i.version ?? ''}`.trim() + `, not ${PKG_NAME}` };
+}
+/** The package directory of a CLI path (…/<pkg>/dist/src/cli.js -> …/<pkg>). */
+function packageDirOf(cli) {
+    let d = dirname(cli);
+    for (let i = 0; i < 6; i++, d = dirname(d)) {
+        if (existsSync(join(d, 'package.json')))
+            return d;
+        if (dirname(d) === d)
+            break;
+    }
+    return dirname(dirname(dirname(cli)));
+}
+function shellQuote(s) {
+    return /^[A-Za-z0-9_./:=@+-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * The commands that make this CLI the `ach` on PATH when another program
+ * called `ach` comes first: remove that link, or put this CLI's directory
+ * first (or install this CLI when it is not on PATH at all).
+ */
+export function shadowFix(other, ours, self) {
+    const lines = ['to make this CLI the `ach` on PATH, run:'];
+    lines.push(`  # ${other.path}${other.real && other.real !== other.path ? ` -> ${other.real}` : ''} is another \`ach\`: remove it, or put this CLI first:`);
+    lines.push(ours
+        ? `  export PATH=${shellQuote(dirname(ours.path))}:"$PATH"        # add this line to ~/.zshrc or ~/.bashrc`
+        : `  npm install -g ${shellQuote(packageDirOf(self))}        # installs this CLI as \`ach\``);
+    lines.push('  hash -r');
+    lines.push('  ach doctor        # should now show this CLI first');
+    return lines.join('\n');
+}
+function shortWhere(u) {
+    try {
+        return new URL(u).host;
+    }
+    catch {
+        return u;
+    }
+}
+const SECTIONS = [
+    { id: 'hub', title: 'Hub (reachable over HTTPS)' },
+    { id: 'front door', title: 'Front door' },
+    { id: 'key', title: 'Key' },
+    { id: 'machine', title: 'This machine' },
+];
+/** Grouped report: hub, front door (only when there is one), key, this machine; each problem with a one-line fix. */
+export function formatDoctor(checks) {
+    const mark = { ok: '[ok]  ', warn: '[warn]', fail: '[FAIL]', info: '[info]' };
+    const out = [];
+    for (const s of SECTIONS) {
+        const list = checks.filter((c) => (c.section ?? 'machine') === s.id);
+        if (!list.length)
+            continue;
+        if (out.length)
+            out.push('');
+        out.push(s.title);
+        for (const c of list) {
+            out.push(`${mark[c.status]} ${c.name}: ${c.detail}`);
+            if (c.fix)
+                out.push(`       fix: ${c.fix}`);
+        }
+    }
+    return out.join('\n');
+}

package/dist/src/env.d.ts

@@ -0,0 +1,31 @@
+/** Env vars that make a spawned Claude Code think it is nested inside another session. */
+export declare const STRIPPED_ENV: readonly ["CLAUDECODE", "CLAUDE_CODE_SESSION_ID", "CLAUDE_CODE_ENTRYPOINT", "CLAUDE_CODE_SSE_PORT", "CLAUDE_CODE_EXECPATH"];
+/**
+ * The only parent env vars a spawned agent inherits (S4). Everything else
+ * (cloud credentials, tokens, the runner's own ACH_KEY, Claude Code messaging
+ * sockets) is dropped unless the runner names it with `--pass-env NAME`.
+ */
+export declare const ENV_ALLOWLIST: readonly ["PATH", "HOME", "LANG", "TERM", "SHELL", "USER", "TMPDIR"];
+/**
+ * Never passed, even with --pass-env: runner credentials and the Claude Code
+ * nesting / messaging / socket / host-auth vars of the parent session.
+ */
+export declare function neverPass(name: string): boolean;
+export interface AgentEnvInput {
+    hub: string;
+    runToken: string;
+    taskId: string;
+    agentName: string;
+    /** §16 mention runs: the thread (root post id) the agent replies in. */
+    threadId?: string;
+    /** Work runs: the handoff version the worker was shown; `ach complete` sends it so the hub can refuse an outdated finish. */
+    handoffVersion?: number;
+    /** §19: base URL for links in agent output (ACH_PUBLIC_URL). */
+    publicUrl?: string;
+    cfId?: string;
+    cfSecret?: string;
+    /** Extra parent env var names to pass through (`ach run --pass-env NAME`). */
+    passEnv?: string[];
+}
+/** Env for a spawned agent: allowlisted parent vars + --pass-env names + task-scoped ACH vars. */
+export declare function buildAgentEnv(base: NodeJS.ProcessEnv | Record<string, string | undefined>, a: AgentEnvInput): Record<string, string>;

package/dist/src/env.js

@@ -0,0 +1,52 @@
+/** Env vars that make a spawned Claude Code think it is nested inside another session. */
+export const STRIPPED_ENV = [
+    'CLAUDECODE',
+    'CLAUDE_CODE_SESSION_ID',
+    'CLAUDE_CODE_ENTRYPOINT',
+    'CLAUDE_CODE_SSE_PORT',
+    'CLAUDE_CODE_EXECPATH',
+];
+/**
+ * The only parent env vars a spawned agent inherits (S4). Everything else
+ * (cloud credentials, tokens, the runner's own ACH_KEY, Claude Code messaging
+ * sockets) is dropped unless the runner names it with `--pass-env NAME`.
+ */
+export const ENV_ALLOWLIST = ['PATH', 'HOME', 'LANG', 'TERM', 'SHELL', 'USER', 'TMPDIR'];
+/**
+ * Never passed, even with --pass-env: runner credentials and the Claude Code
+ * nesting / messaging / socket / host-auth vars of the parent session.
+ */
+export function neverPass(name) {
+    if (STRIPPED_ENV.includes(name))
+        return true;
+    if (/^ACH_/.test(name))
+        return true; // the ACH_* run vars are set explicitly
+    if (name === 'AGENTCHANNEL_HOME')
+        return true;
+    return /^CLAUDE_CODE_.*(SESSION|ENTRYPOINT|EXECPATH|SSE|PORT|SOCK|IPC|MESSAG|HOST|OAUTH|TOKEN|AUTH|BRIDGE|REMOTE)/.test(name);
+}
+/** Env for a spawned agent: allowlisted parent vars + --pass-env names + task-scoped ACH vars. */
+export function buildAgentEnv(base, a) {
+    const env = {};
+    for (const k of [...ENV_ALLOWLIST, ...(a.passEnv ?? [])]) {
+        const v = base[k];
+        if (v === undefined || neverPass(k))
+            continue;
+        env[k] = v;
+    }
+    env.ACH_HUB = a.hub;
+    env.ACH_RUN_TOKEN = a.runToken;
+    env.ACH_TASK_ID = a.taskId;
+    env.ACH_AGENT = a.agentName;
+    if (a.threadId)
+        env.ACH_THREAD_ID = a.threadId;
+    if (a.handoffVersion)
+        env.ACH_HANDOFF_VERSION = String(a.handoffVersion);
+    if (a.publicUrl)
+        env.ACH_PUBLIC_URL = a.publicUrl;
+    if (a.cfId)
+        env.ACH_CF_ID = a.cfId;
+    if (a.cfSecret)
+        env.ACH_CF_SECRET = a.cfSecret;
+    return env;
+}