@superjackfruitlabs/salaam 0.0.3 → 0.0.4

package/dist/src/board-reads.js

@@ -0,0 +1,106 @@
+import { randomUUID } from 'node:crypto';
+import { ServiceError } from './protocol.js';
+const ITEM = /^itm_[0-9a-f]{16}$/;
+/** The most a hub answer may carry back to the agent. */
+export const BOARD_READ_MAX_BYTES = 256 * 1024;
+const bad = (message) => new ServiceError('invalid_board_read', message, 400);
+/** Closed arguments per action; anything else is refused. */
+export function boardReadArgs(input) {
+    const { action, ...rest } = input;
+    const keys = Object.keys(rest).filter((k) => rest[k] !== undefined);
+    if (action === 'card' || action === 'attempts') {
+        if (keys.length)
+            throw bad(`${action} takes no arguments: it is always this run's own card`);
+        return { action, args: {} };
+    }
+    if (action === 'library_search') {
+        const q = rest.query;
+        if (keys.join() !== 'query' || typeof q !== 'string' || !q.trim() || q.length > 500)
+            throw bad('library_search takes one query of 1 to 500 characters');
+        return { action, args: { query: q.trim() } };
+    }
+    if (action === 'library_get') {
+        const id = rest.item_id;
+        if (keys.join() !== 'item_id' || typeof id !== 'string' || !ITEM.test(id))
+            throw bad('library_get takes one item_id (itm_ and 16 hex characters)');
+        return { action, args: { item_id: id } };
+    }
+    throw bad('Board reads are card, attempts, library_search or library_get');
+}
+export class BoardReads {
+    store;
+    constructor(store) {
+        this.store = store;
+        store.db.exec(`CREATE TABLE IF NOT EXISTS board_reads(
+      id TEXT PRIMARY KEY, session_id TEXT NOT NULL, tool_call_id TEXT NOT NULL, action TEXT NOT NULL,
+      args TEXT NOT NULL, state TEXT NOT NULL, ok INTEGER, text TEXT, error TEXT,
+      created_at TEXT NOT NULL, answered_at TEXT, UNIQUE(session_id, tool_call_id))`);
+    }
+    view(row) {
+        return {
+            id: String(row.id),
+            action: String(row.action),
+            args: JSON.parse(String(row.args)),
+            state: String(row.state),
+            ...(row.state === 'answered'
+                ? {
+                    ok: row.ok === 1,
+                    ...(row.text !== null ? { text: String(row.text) } : {}),
+                    ...(row.error !== null ? { error: String(row.error) } : {}),
+                }
+                : {}),
+        };
+    }
+    /** Record a read for this session, once per tool call. */
+    request(session, toolCallId, input) {
+        const { action, args } = boardReadArgs(input);
+        const existing = this.store.db
+            .prepare('SELECT * FROM board_reads WHERE session_id=? AND tool_call_id=?')
+            .get(session, toolCallId);
+        if (existing)
+            return this.view(existing);
+        const id = randomUUID();
+        this.store.db
+            .prepare("INSERT INTO board_reads(id,session_id,tool_call_id,action,args,state,created_at) VALUES (?,?,?,?,?,'pending',?)")
+            .run(id, session, toolCallId, action, JSON.stringify(args), new Date().toISOString());
+        return this.get(session, id);
+    }
+    get(session, id) {
+        const row = this.store.db
+            .prepare('SELECT * FROM board_reads WHERE id=? AND session_id=?')
+            .get(id, session);
+        if (!row)
+            throw new ServiceError('board_read_not_found', 'No such board read', 404);
+        return this.view(row);
+    }
+    /** What the hub should serve for this session, oldest first. */
+    pending(session) {
+        return this.store.db
+            .prepare("SELECT * FROM board_reads WHERE session_id=? AND state='pending' ORDER BY rowid LIMIT 8")
+            .all(session)
+            .map((r) => {
+            const v = this.view(r);
+            return { id: v.id, action: v.action, args: v.args };
+        });
+    }
+    /** The hub's answer: once, for a read of this session, bounded. */
+    answer(session, value) {
+        const a = (value ?? {});
+        const keys = Object.keys(a).sort().join();
+        const ok = a.ok === true;
+        if (typeof a.read_id !== 'string' ||
+            (ok
+                ? keys !== 'ok,read_id,text' || typeof a.text !== 'string'
+                : keys !== 'error,ok,read_id' || a.ok !== false || typeof a.error !== 'string'))
+            throw bad('Closed board read answer required');
+        const body = ok ? a.text : a.error;
+        if (Buffer.byteLength(body) > (ok ? BOARD_READ_MAX_BYTES : 2048))
+            throw bad('Board read answer too large');
+        const done = this.store.db
+            .prepare("UPDATE board_reads SET state='answered',ok=?,text=?,error=?,answered_at=? WHERE id=? AND session_id=? AND state='pending'")
+            .run(ok ? 1 : 0, ok ? body : null, ok ? null : body, new Date().toISOString(), a.read_id, session);
+        if (done.changes !== 1)
+            throw new ServiceError('board_read_settled', 'That board read is not pending for this run', 409);
+        return this.get(session, a.read_id);
+    }
+}

package/dist/src/children.js

@@ -169,6 +169,89 @@ export class ChildWork {
             this.start(child);
         return child;
     }
+    /**
+     * The task critic (item 8): a reviewer child over an immutable snapshot of the verified
+     * deliverables. No parent attempt is active at completion, so it is linked to the task's last
+     * step attempt and charged to its own bounded budget, never to an attempt's reservation. The
+     * grant must be the built-in reviewer; the child can read the snapshot and report findings only.
+     */
+    spawnCritic(parent, parentAttempt, step, prompt, budget, grant, snapshot) {
+        if (!Number.isSafeInteger(budget) || budget < 1 || budget > 8)
+            throw new ServiceError('invalid_budget', 'Critic request budget must be 1–8');
+        if (grant.profile.id !== 'salaam/reviewer' || grant.owner_session !== parent)
+            throw new ServiceError('authority_denied', 'The critic must be the built-in reviewer');
+        if (!Object.keys(snapshot).length)
+            throw new ServiceError('invalid_child', 'A critic needs a snapshot of the verified deliverables');
+        if (!prompt.trim() || prompt.length > 32768)
+            throw new ServiceError('invalid_child', 'Invalid critic prompt');
+        const authority = [...grant.profile.tools].sort();
+        const input = digest({
+            prompt,
+            budget,
+            critic: grant.profile_digest,
+            snapshot: digest(snapshot),
+        });
+        const prepare = () => {
+            const old = this.store.db
+                .prepare('SELECT * FROM child_tasks WHERE parent_session=? AND step_key=?')
+                .get(parent, step);
+            if (old) {
+                if (old.input_digest !== input)
+                    throw new ServiceError('spawn_conflict', 'Critic step already binds a different review');
+                return { child: old, fresh: false };
+            }
+            if (this.paused)
+                throw new ServiceError('stopping', 'Child dispatch is stopping');
+            this.store.execution.assert(parent);
+            if (this.activeCount() >= 8)
+                throw new ServiceError('child_limit', 'Daemon worker admission limit reached');
+            const effectivePrompt = `${grant.profile.prompt}\n\nGoal:\n${prompt}`;
+            const id = randomUUID(), session = randomUUID(), submission = randomUUID(), childAttempt = randomUUID();
+            this.store.db
+                .prepare('INSERT INTO sessions(id,cwd,pi_session_id) VALUES (?,?,?)')
+                .run(session, this.store.session(parent).cwd, session);
+            this.store.db
+                .prepare('INSERT INTO submissions(id,session_id,text,attempt_id) VALUES (?,?,?,?)')
+                .run(submission, session, effectivePrompt, childAttempt);
+            this.store.db
+                .prepare("INSERT INTO attempts(id,session_id,submission_id,state) VALUES (?,?,?,'accepted')")
+                .run(childAttempt, session, submission);
+            this.store.db
+                .prepare("INSERT INTO child_tasks(id,parent_session,parent_attempt,step_key,input_digest,child_session,child_attempt,authority,budget,state) VALUES (?,?,?,?,?,?,?,?,?,'accepted')")
+                .run(id, parent, parentAttempt, step, input, session, childAttempt, JSON.stringify(authority), budget);
+            this.store.taskChildReserve?.(parent, childAttempt, budget);
+            this.store.usage.budget(childAttempt, budget);
+            const artifact = this.artifacts.prepare(session, effectivePrompt);
+            artifact.commit();
+            // The reviewed snapshot is the verified bytes; its base is empty, so its diff is all of it.
+            const current = this.artifacts.prepare(session, JSON.stringify(snapshot)), base = this.artifacts.prepare(session, JSON.stringify({}));
+            current.commit();
+            base.commit();
+            this.store.workerBoundary.freeze(this.owned(session), artifact.id, false, grant, {
+                artifact_id: current.id,
+                base_artifact: base.id,
+                digest: digest(snapshot),
+            });
+            this.store.event(session, 'session.created', { parent_session: parent, child_id: id });
+            this.store.event(session, 'submission.accepted', {
+                attempt_id: childAttempt,
+                submission_id: submission,
+            });
+            this.store.event(parent, 'child.spawned', {
+                child_id: id,
+                child_session: session,
+                step_key: step,
+                budget,
+                authority,
+                critic: true,
+            });
+            return { child: this.inspect(parent, id), fresh: true };
+        };
+        const { child, fresh } = this.store.transaction(prepare);
+        if (fresh)
+            this.start(child);
+        return child;
+    }
     activeCount(parent) {
         return Number(this.store.db
             .prepare(`SELECT count(*) AS n FROM child_tasks c WHERE (? IS NULL OR c.parent_session=?) AND (c.state='accepted' OR EXISTS(SELECT 1 FROM workers w WHERE w.session_id=c.child_session AND w.state!='exited') OR EXISTS(SELECT 1 FROM external_runs e WHERE e.child_id=c.id AND e.stopped=0))`)

package/dist/src/cli-help.js

@@ -103,6 +103,10 @@ salaam host inspect --manifest host-manifest.json
 salaam host unit --manifest host-manifest.json --platform systemd|launchd
 salaam host run --manifest host-manifest.json
 salaam host start --manifest host-manifest.json
+salaam host unit-start --unit salaam-host@STATION.service --state DIR
+salaam host bind --organization ORG --node NODE --station-key KEY --workspace DIR \
+  --tools-user USER --files HELPER --runtime-root DIR --runtime-image-digest sha256:… \
+  [--operator-group GROUP] [--provider P --model M] [--mcp-config FILE] [--persona FILE] [--managed-mcp-config FILE] [--dir DIR] [--state DIR]
 
 Config requires absolute state, coding_root and coding_socket paths; optional
 provider, model, max_output_tokens and workspace_id. Planning probes the existing
@@ -116,7 +120,18 @@ For a bound AgentPod host, use mode="agentpod", state and agentpod_config instea
 of coding_root/coding_socket. This profile enables no station tools. The private
 manifest pins Node, CLI, source/build, Pi, provider and authority pins. Invoke the
 canonical Node executable explicitly. host start waits for matching live health
-and safely coalesces concurrent callers; it never installs or upgrades packages.`,
+and safely coalesces concurrent callers; it never installs or upgrades packages.
+
+Launcher profile (Linux): root plans a strict work host with operator_group set.
+A root-owned unit runs host run from that root-held manifest. The daemon lets that
+one group traverse its state and use operator.sock. An unprivileged member then
+runs host unit-start, which asks systemd to start the named salaam-host@ unit and
+prints the receipt the running daemon reports. It cannot choose what root runs.
+
+host bind (root, Linux) writes everything a launcher-profile station needs into
+--dir (default /etc/salaam/stations/<key>): agentpod-pins.json, station-config.json
+(with tools_user), host-config.json, and host.json from host plan. It is
+idempotent: the same inputs leave the files and the manifest digest unchanged.`,
     schedules: `salaam schedules create TASK_ID --name NAME --revision N --max-steps N [--schedule FILE] [--compact]
 salaam schedules list [--offset N]
 salaam schedules inspect JOB_ID
@@ -208,10 +223,18 @@ Status prints metadata only. Existing Anthropic keys remain compatible.`,
                      [--coding-root PRIVATE_DIR] [--coding-socket DOCKER_SOCKET]
                      [--harness-config OWNER_ONLY_FILE] [--a2a-config OWNER_ONLY_FILE]
                      [--a2a-listen-config OWNER_ONLY_FILE]
-                     [--agentpod-config OWNER_ONLY_FILE]
+                     [--agentpod-config OWNER_ONLY_FILE] [--mcp-config FILE]
+                     [--tools-user USER]
 salaam service status
 salaam service stop
 
+--tools-user USER (or SALAAM_TOOLS_USER) runs local agent commands and edits as
+USER through sudo -n -u USER on Linux. Without it, tools share the provider
+credential's OS user and start prints a warning.
+
+Without --agentpod-config, start binds to ~/.config/salaam/agentpod-pins.json
+($XDG_CONFIG_HOME/salaam) when that file exists.
+
 The default provider is offline. Anthropic defaults to claude-sonnet-5-5.
 Other providers require --model; use salaam providers list and salaam models list PROVIDER.
 Start with --foreground for process-supervisor use; otherwise the service detaches.
@@ -287,6 +310,7 @@ Commands:
   auth          Configure provider credentials or OAuth
   service       Start, inspect or stop the session service
   session       Create, inspect, submit, resume or cancel work
+  mcp           Declare operator MCP servers (add, list, rm)
   attach        Open an interactive terminal on a session
   acp           Connect an editor over ACP v1 stdio
   approvals     Inspect, approve or deny managed operations
@@ -357,6 +381,7 @@ const valueOptions = new Set([
     '--a2a-config',
     '--agentpod-config',
     '--a2a-listen-config',
+    '--tools-user',
     '--assignment',
     '--peer',
     '--peer-client',

package/dist/src/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { SANDBOX_LEVELS } from './command-sandbox.js';
 import { acp } from './acp.js';
 import { homedir } from 'node:os';
 import { join, resolve, dirname } from 'node:path';
@@ -6,9 +7,12 @@ import { spawn } from 'node:child_process';
 import { randomUUID, randomBytes } from 'node:crypto';
 import { digest, object } from './protocol.js';
 import { fileURLToPath } from 'node:url';
-import { mkdirSync, openSync, closeSync, readFileSync, realpathSync, writeFileSync, fsyncSync, } from 'node:fs';
+import { mkdirSync, openSync, closeSync, readFileSync, realpathSync, writeFileSync, fsyncSync, existsSync, } from 'node:fs';
 import { VERSION } from './config.js';
 import { cliHelp, hasHelpFlag } from './cli-help.js';
+import { mcpCli, MCP_HELP } from './operator-mcp-cli.js';
+import { operatorMcpPath, readOperatorMcpFile } from './operator-mcp.js';
+import { defaultAgentPodConfig } from './agentpod-default-config.js';
 import { SalaamService } from './service.js';
 import { call } from './transport.js';
 import { attach, acquireControl, Outbox } from './attach.js';
@@ -29,6 +33,17 @@ async function main() {
         console.log('salaam ' + VERSION);
         return;
     }
+    if (args[0] === 'mcp') {
+        // Parsed before global help: a declared command's own flags follow "--".
+        const rest = args.slice(1);
+        const dash = rest.indexOf('--');
+        const flags = dash < 0 ? rest : rest.slice(0, dash);
+        if (!rest.length || flags.includes('--help') || flags.includes('-h'))
+            console.log(MCP_HELP);
+        else
+            console.log(mcpCli(rest));
+        return;
+    }
     if ((!args.length && !(process.stdin.isTTY && process.stdout.isTTY)) ||
         args[0] === 'help' ||
         hasHelpFlag(args)) {
@@ -388,7 +403,7 @@ async function main() {
         return;
     }
     if (group === 'host') {
-        const { planHost, readHost, hostUnit, runHost } = await import('./host.js');
+        const { planHost, readHost, hostUnit, runHost, hostReceipt, hostToolsUser, hostApprovalTtlMs, hostAllowsUnsandboxed, hostCommandNetwork, } = await import('./host.js');
         if (verb?.startsWith('config-')) {
             const file = option('--manifest');
             if (!file)
@@ -413,6 +428,42 @@ async function main() {
             console.log(JSON.stringify(await planHost(JSON.parse(readFileSync(resolve(file), 'utf8'))), null, 2));
             return;
         }
+        if (verb === 'bind') {
+            const { bindHost } = await import('./host-bind.js');
+            const required = (name) => {
+                const v = option(name);
+                if (!v)
+                    throw new Error('Supply ' + name);
+                return v;
+            };
+            console.log(JSON.stringify(await bindHost({
+                organization_id: required('--organization'),
+                node_id: required('--node'),
+                station_key: required('--station-key'),
+                workspace: required('--workspace'),
+                tools_user: required('--tools-user'),
+                files: required('--files'),
+                runtime_root: required('--runtime-root'),
+                runtime_image_digest: required('--runtime-image-digest'),
+                operator_group: option('--operator-group'),
+                dir: option('--dir'),
+                state: explicitState ? state : undefined,
+                provider: option('--provider'),
+                model: option('--model'),
+                mcp_config: option('--mcp-config'),
+                persona: option('--persona'),
+                managed_mcp_config: option('--managed-mcp-config'),
+            })));
+            return;
+        }
+        if (verb === 'unit-start') {
+            const { startHostUnit } = await import('./host-start.js');
+            const unit = option('--unit');
+            if (!unit || !explicitState)
+                throw new Error('Supply --unit UNIT and --state DIR');
+            console.log(JSON.stringify(await startHostUnit(unit, state)));
+            return;
+        }
         const file = option('--manifest');
         if (!file)
             throw new Error('Supply --manifest FILE');
@@ -462,9 +513,21 @@ async function main() {
                             : {}),
                         ...(m.schema === 5 || m.schema === 6 ? { stationConfig: m.station_execution } : {}),
                         ...(m.schema === 6 ? { agentpodWorkProgression: true } : {}),
+                        ...(m.schema === 6 && m.operator_access
+                            ? { operatorAccess: m.operator_access }
+                            : {}),
+                        ...(m.schema === 6 && m.operator_mcp
+                            ? { operatorMcpConfig: m.operator_mcp.config }
+                            : {}),
+                        ...(m.schema === 6 && m.persona ? { personaConfig: m.persona } : {}),
                     }),
                 hostManifestDigest: digest(m),
+                hostReceipt: hostReceipt(m),
+                toolsUser: hostToolsUser(m),
                 providerRoute: m.provider,
+                approvalTtlMs: hostApprovalTtlMs(m),
+                ...(hostAllowsUnsandboxed(m) ? { unsandboxedCommands: 'allow' } : {}),
+                ...(hostCommandNetwork(m) ? { commandNetwork: hostCommandNetwork(m) } : {}),
             });
             if (process.connected)
                 process.once('disconnect', () => void service.close());
@@ -1245,17 +1308,25 @@ async function main() {
         }
         const effectSocket = option('--effect-socket');
         const opaque = args.includes('--effect-opaque');
-        const codingRoot = option('--coding-root'), codingSocket = option('--coding-socket'), harnessConfig = option('--harness-config'), a2aConfig = option('--a2a-config'), agentpodConfig = option('--agentpod-config'), a2aListenConfig = option('--a2a-listen-config');
+        const codingRoot = option('--coding-root'), codingSocket = option('--coding-socket'), harnessConfig = option('--harness-config'), a2aConfig = option('--a2a-config'), agentpodConfig = option('--agentpod-config') ?? defaultAgentPodConfig(process.env, existsSync), a2aListenConfig = option('--a2a-listen-config'), mcpConfig = resolve(option('--mcp-config') ?? operatorMcpPath(process.env)), toolsUser = option('--tools-user') ?? (process.env.SALAAM_TOOLS_USER || undefined), localSandbox = option('--local-sandbox') ?? (process.env.SALAAM_LOCAL_SANDBOX || undefined), unsandboxedCommands = option('--unsandboxed-commands') ?? (process.env.SALAAM_UNSANDBOXED_COMMANDS || undefined);
+        if (localSandbox !== undefined && !SANDBOX_LEVELS.includes(localSandbox))
+            throw Error('--local-sandbox is read-only, workspace-write or full-access');
+        if (unsandboxedCommands !== undefined && unsandboxedCommands !== 'allow')
+            throw Error('--unsandboxed-commands is allow or absent');
         if (foreground) {
             const service = await SalaamService.open({
                 stateDir: state,
                 providerRoute: route,
                 agentpodConfig: agentpodConfig ? resolve(agentpodConfig) : undefined,
+                operatorMcpConfig: mcpConfig,
                 codingRoot: codingRoot ? resolve(codingRoot) : undefined,
                 codingSocket: codingSocket ? resolve(codingSocket) : undefined,
                 harnessConfig: harnessConfig ? resolve(harnessConfig) : undefined,
                 a2aConfig: a2aConfig ? resolve(a2aConfig) : undefined,
                 a2aListenConfig: a2aListenConfig ? resolve(a2aListenConfig) : undefined,
+                toolsUser,
+                ...(localSandbox ? { localSandbox: localSandbox } : {}),
+                ...(unsandboxedCommands ? { unsandboxedCommands: 'allow' } : {}),
                 effectConnector: effectSocket
                     ? new SocketEffectConnector(resolve(effectSocket), { opaque })
                     : undefined,
@@ -1263,6 +1334,9 @@ async function main() {
             const warning = service.supervisor.providerCapabilities().warning;
             if (warning)
                 console.error(warning);
+            // Only a live provider has a credential to share; the offline proof route stays quiet.
+            if (service.toolIdentity.warning && route.provider !== 'salaam-proof')
+                console.error('warning: ' + service.toolIdentity.warning);
             process.stdout.write(JSON.stringify({ socket, service: 'started' }) + '\n');
             for (const signal of ['SIGINT', 'SIGTERM'])
                 process.once(signal, () => {
@@ -1290,6 +1364,11 @@ async function main() {
             if ((health.coding_root ?? null) !== (codingRoot ? resolve(codingRoot) : null) ||
                 (health.coding_socket ?? null) !== (codingSocket ? resolve(codingSocket) : null))
                 throw new Error('Service is already running with another coding configuration; stop it first');
+            if ((health.operator_mcp?.config ?? null) !== mcpConfig)
+                throw new Error('Service is already running with another MCP config; stop it first');
+            if (health.operator_mcp &&
+                health.operator_mcp.digest !== digest(readOperatorMcpFile(mcpConfig)))
+                console.error('Declared MCP servers changed since the service started; run salaam service stop, then start, to apply them');
             console.log('Salaam service already running');
             return;
         }
@@ -1315,6 +1394,11 @@ async function main() {
             ...(a2aConfig ? ['--a2a-config', resolve(a2aConfig)] : []),
             ...(agentpodConfig ? ['--agentpod-config', resolve(agentpodConfig)] : []),
             ...(a2aListenConfig ? ['--a2a-listen-config', resolve(a2aListenConfig)] : []),
+            '--mcp-config',
+            mcpConfig,
+            ...(toolsUser ? ['--tools-user', toolsUser] : []),
+            ...(localSandbox ? ['--local-sandbox', localSandbox] : []),
+            ...(unsandboxedCommands ? ['--unsandboxed-commands', 'allow'] : []),
         ], { detached: true, stdio: ['ignore', fd, fd] });
         closeSync(fd);
         child.unref();

package/dist/src/command-network.js

@@ -0,0 +1,200 @@
+import { createServer, connect } from 'node:net';
+import { chmodSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Network for local commands through the broker allowlist (operator rulings 2026-10-30). A command
+ * has no network of its own; its only route out is stk's `local-commands` socket, where every
+ * connection is the `local-commands` identity and only `servers.local-commands.egress.hosts`
+ * decides. Salaam puts a relay of its own in between, outside the sandbox, so what a command
+ * reached is counted where the command cannot touch it.
+ *
+ * Linux: the relay listens on a unix socket in a private directory bound into the bubblewrap
+ * sandbox; inside, `inSandboxRelaySource` bridges 127.0.0.1:COMMAND_NETWORK_PORT to it and then
+ * starts the command. macOS: the relay listens on 127.0.0.1:<ephemeral>, the only address the
+ * Seatbelt profile lets the command connect to.
+ */
+export const COMMAND_NETWORK_PORT = 3128;
+export const DEFAULT_COMMAND_NETWORK_SOCKET = '/run/stk/local-commands.sock';
+const MAX_TARGETS = 32;
+const MAX_REASON = 300;
+export class BrokerRelay {
+    server;
+    broker;
+    port;
+    path;
+    dir;
+    counts = new Map();
+    truncated = false;
+    unavailable = false;
+    sockets = new Set();
+    constructor(server, broker, port, path, dir) {
+        this.server = server;
+        this.broker = broker;
+        this.port = port;
+        this.path = path;
+        this.dir = dir;
+    }
+    /** `tcp`: 127.0.0.1:<ephemeral> (macOS). `unix`: a socket in a new private directory (Linux),
+     * readable by the command's user so a tools-user command can reach it. */
+    static async start(broker, mode) {
+        let relay;
+        const server = createServer((client) => relay.handle(client));
+        if (mode === 'tcp') {
+            await new Promise((resolve, reject) => {
+                server.once('error', reject);
+                server.listen(0, '127.0.0.1', () => resolve());
+            });
+            relay = new BrokerRelay(server, broker, server.address().port, null, null);
+        }
+        else {
+            const dir = mkdtempSync(join(tmpdir(), 'salaam-net-'));
+            chmodSync(dir, 0o755);
+            const path = join(dir, 'relay.sock');
+            await new Promise((resolve, reject) => {
+                server.once('error', reject);
+                server.listen(path, () => resolve());
+            });
+            chmodSync(path, 0o666);
+            relay = new BrokerRelay(server, broker, null, path, dir);
+        }
+        return relay;
+    }
+    /** A client connection to this relay, for tests. */
+    connect() {
+        return this.path ? connect(this.path) : connect(this.port, '127.0.0.1');
+    }
+    record(target, allowed, reason) {
+        let entry = this.counts.get(target);
+        if (!entry) {
+            if (this.counts.size >= MAX_TARGETS) {
+                this.truncated = true;
+                return;
+            }
+            entry = { allowed: 0, refused: 0 };
+            this.counts.set(target, entry);
+        }
+        if (allowed)
+            entry.allowed++;
+        else {
+            entry.refused++;
+            if (reason && !entry.reason)
+                entry.reason = reason.slice(0, MAX_REASON);
+        }
+    }
+    handle(client) {
+        this.sockets.add(client);
+        client.on('close', () => this.sockets.delete(client));
+        client.on('error', () => { });
+        let head = Buffer.alloc(0);
+        const onHead = (chunk) => {
+            head = Buffer.concat([head, chunk]);
+            const end = head.indexOf('\r\n');
+            if (end < 0) {
+                if (head.length > 8192)
+                    client.destroy();
+                return;
+            }
+            client.off('data', onHead);
+            client.pause();
+            const line = head.subarray(0, end).toString('latin1');
+            const connectLine = /^CONNECT (\S+) HTTP\/1\.[01]$/.exec(line);
+            const absolute = /^[A-Z]+ http:\/\/([^/\s]+)/.exec(line);
+            const target = connectLine
+                ? connectLine[1].toLowerCase()
+                : absolute
+                    ? (absolute[1].includes(':') ? absolute[1] : absolute[1] + ':80').toLowerCase()
+                    : 'invalid-request';
+            const up = connect(this.broker);
+            this.sockets.add(up);
+            up.on('close', () => this.sockets.delete(up));
+            up.once('error', () => {
+                this.unavailable = true;
+                this.record(target, false, 'the broker socket is unavailable');
+                const body = 'salaam: the command network broker is unavailable\n';
+                client.end(`HTTP/1.1 502 Bad Gateway\r\nContent-Length: ${body.length}\r\nConnection: close\r\n\r\n${body}`);
+            });
+            up.once('connect', () => {
+                let reply = Buffer.alloc(0), decided = false;
+                const onReply = (chunk) => {
+                    client.write(chunk);
+                    if (decided)
+                        return;
+                    reply = Buffer.concat([reply, chunk]);
+                    const status = /^HTTP\/1\.[01] (\d{3})/.exec(reply.toString('latin1'));
+                    if (!status) {
+                        if (reply.length > 8192)
+                            decided = true;
+                        return;
+                    }
+                    const code = Number(status[1]);
+                    if (code >= 200 && code < 300) {
+                        decided = true;
+                        this.record(target, true);
+                        return;
+                    }
+                    // A refusal: wait for the body so the reason names the fix, as stk writes it.
+                    const text = reply.toString('utf8');
+                    const bodyAt = text.indexOf('\r\n\r\n');
+                    if (bodyAt >= 0 && text.length > bodyAt + 4) {
+                        decided = true;
+                        this.record(target, false, text
+                            .slice(bodyAt + 4)
+                            .trim()
+                            .split('\n')[0]);
+                    }
+                };
+                up.on('data', onReply);
+                up.on('end', () => {
+                    if (!decided) {
+                        decided = true;
+                        const status = /^HTTP\/1\.[01] (\d{3})[^\r\n]*/.exec(reply.toString('latin1'));
+                        const code = status ? Number(status[1]) : 0;
+                        this.record(target, code >= 200 && code < 300, status ? status[0] : 'no reply');
+                    }
+                    client.end();
+                });
+                up.write(head);
+                client.on('data', (d) => up.write(d));
+                client.on('end', () => up.end());
+                client.resume();
+            });
+        };
+        client.on('data', onHead);
+    }
+    summary() {
+        return {
+            broker: this.unavailable ? 'unavailable' : 'available',
+            connections: [...this.counts].map(([target, c]) => ({ target, ...c })),
+            ...(this.truncated ? { truncated: true } : {}),
+        };
+    }
+    async close() {
+        for (const s of this.sockets)
+            s.destroy();
+        await new Promise((resolve) => this.server.close(() => resolve()));
+        if (this.dir)
+            rmSync(this.dir, { recursive: true, force: true });
+    }
+}
+/**
+ * Runs inside the bubblewrap sandbox as `node -e <this> <unix socket> <port> <command...>`: listens
+ * on 127.0.0.1:<port> in the sandbox's own network namespace, pipes each connection to the bound
+ * relay socket, then starts the command with its stdio and exits with its status. It decides
+ * nothing; the host-side relay and stk do.
+ */
+export const inSandboxRelaySource = `
+const net = require('node:net'), { spawn } = require('node:child_process');
+const [sock, port, cmd, ...args] = process.argv.slice(1);
+const server = net.createServer((c) => {
+  const u = net.connect(sock);
+  c.on('error', () => u.destroy()); u.on('error', () => c.destroy());
+  c.pipe(u).pipe(c);
+});
+server.listen(Number(port), '127.0.0.1', () => {
+  const child = spawn(cmd, args, { stdio: 'inherit' });
+  child.on('exit', (code, signal) => process.exit(code ?? (signal ? 128 : 1)));
+  child.on('error', () => process.exit(127));
+});
+server.on('error', () => process.exit(126));
+`.trim();