@superjackfruitlabs/salaam 0.0.3 → 0.0.4

package/src/command-network.ts

@@ -0,0 +1,215 @@
+import { createServer, connect, type Server, type Socket } 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 interface CommandNetworkSummary {
+  broker: 'available' | 'unavailable';
+  connections: { target: string; allowed: number; refused: number; reason?: string }[];
+  truncated?: boolean;
+}
+
+export class BrokerRelay {
+  private counts = new Map<string, { allowed: number; refused: number; reason?: string }>();
+  private truncated = false;
+  private unavailable = false;
+  private sockets = new Set<Socket>();
+  private constructor(
+    private readonly server: Server,
+    private readonly broker: string,
+    readonly port: number | null,
+    readonly path: string | null,
+    readonly dir: string | null,
+  ) {}
+
+  /** `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: string, mode: 'tcp' | 'unix'): Promise<BrokerRelay> {
+    let relay!: BrokerRelay;
+    const server = createServer((client) => relay.handle(client));
+    if (mode === 'tcp') {
+      await new Promise<void>((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => resolve());
+      });
+      relay = new BrokerRelay(
+        server,
+        broker,
+        (server.address() as { port: number }).port,
+        null,
+        null,
+      );
+    } else {
+      const dir = mkdtempSync(join(tmpdir(), 'salaam-net-'));
+      chmodSync(dir, 0o755);
+      const path = join(dir, 'relay.sock');
+      await new Promise<void>((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(): Socket {
+    return this.path ? connect(this.path) : connect(this.port!, '127.0.0.1');
+  }
+
+  private record(target: string, allowed: boolean, reason?: string) {
+    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);
+    }
+  }
+
+  private handle(client: Socket) {
+    this.sockets.add(client);
+    client.on('close', () => this.sockets.delete(client));
+    client.on('error', () => {});
+    let head = Buffer.alloc(0);
+    const onHead = (chunk: Buffer) => {
+      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: Buffer) => {
+          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(): CommandNetworkSummary {
+    return {
+      broker: this.unavailable ? 'unavailable' : 'available',
+      connections: [...this.counts].map(([target, c]) => ({ target, ...c })),
+      ...(this.truncated ? { truncated: true } : {}),
+    };
+  }
+
+  async close(): Promise<void> {
+    for (const s of this.sockets) s.destroy();
+    await new Promise<void>((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();

package/src/command-sandbox.ts

@@ -0,0 +1,273 @@
+import { COMMAND_NETWORK_PORT, inSandboxRelaySource } from './command-network.js';
+import { existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { isAbsolute } from 'node:path';
+import { ServiceError } from './protocol.js';
+
+/**
+ * Item 10: the sandbox a local command runs in. `workspace-write` (the default) and `read-only` run
+ * the command under the host's OS sandbox, with the system read-only, a private tmp, the workspace
+ * writable or read-only, and no network unless declared:
+ * - Linux: bubblewrap, with an empty root and user, PID, IPC, UTS and network namespaces unshared,
+ *   dying with its parent;
+ * - macOS: Seatbelt (`sandbox-exec`), with a deny-by-default profile.
+ * `full-access` runs the command as is and must be chosen explicitly by the operator. A host with
+ * no usable sandbox refuses local commands (operator ruling 2026-10-30, option A) unless the host
+ * config sets `unsandboxed_commands: "allow"`; then it runs them unsandboxed and says so:
+ * "unsandboxed" in host plan and in every approval, and kind `none` in the approved arguments and
+ * the execution result.
+ */
+export const SANDBOX_LEVELS = ['read-only', 'workspace-write', 'full-access'] as const;
+export type SandboxLevel = (typeof SANDBOX_LEVELS)[number];
+export interface Bwrap {
+  path: string;
+  version: string;
+}
+export interface Seatbelt {
+  path: string;
+}
+export type SandboxKind = 'bwrap' | 'seatbelt' | 'none';
+
+/** The pinned bubblewrap: its absolute path and the version it reports, or null when unusable. */
+export function findBwrap(candidates = ['/usr/bin/bwrap', '/bin/bwrap']): Bwrap | null {
+  for (const path of candidates) {
+    if (!existsSync(path)) continue;
+    try {
+      const version = execFileSync(path, ['--version'], { encoding: 'utf8', timeout: 5000 }).trim();
+      // Usable means it can actually make the namespaces we ask for, not just that it exists.
+      execFileSync(
+        path,
+        ['--unshare-user', '--unshare-net', '--ro-bind', '/', '/', '--', '/bin/true'],
+        {
+          timeout: 5000,
+          stdio: 'ignore',
+        },
+      );
+      return { path, version };
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+export function sandboxArgv(
+  level: SandboxLevel,
+  root: string,
+  argv: string[],
+  bwrap: Bwrap | null,
+  options: {
+    network: boolean;
+    /** Broker network: the host relay's private directory and the node that runs the in-sandbox
+     * relay. The network stays unshared; only the relay socket and node are bound in. */
+    broker?: { dir: string; node: string };
+  },
+): string[] {
+  if (level === 'full-access') return argv;
+  if (!bwrap)
+    throw new ServiceError(
+      'sandbox_unavailable',
+      'This host has no usable bubblewrap, so it cannot run a sandboxed command; an operator can choose full access explicitly',
+    );
+  if (!isAbsolute(root) || root.includes('\0'))
+    throw new ServiceError('invalid_field', 'A sandboxed command needs an absolute workspace path');
+  // Optional system directories, bound read-only only where the host has them.
+  const optional = ['/lib', '/lib64', '/lib32', '/bin', '/sbin', '/etc/alternatives'].flatMap(
+    (dir) => ['--ro-bind-try', dir, dir],
+  );
+  return [
+    bwrap.path,
+    '--unshare-user',
+    '--unshare-pid',
+    '--unshare-ipc',
+    '--unshare-uts',
+    ...(options.network ? [] : ['--unshare-net']),
+    '--die-with-parent',
+    '--new-session',
+    '--tmpfs',
+    '/',
+    // The system read-only; /usr and /etc/ssl always asked for, the rest only where present.
+    '--ro-bind',
+    '/usr',
+    '/usr',
+    '--ro-bind',
+    '/etc/ssl',
+    '/etc/ssl',
+    ...optional,
+    '--proc',
+    '/proc',
+    '--dev',
+    '/dev',
+    '--tmpfs',
+    '/tmp',
+    level === 'read-only' ? '--ro-bind' : '--bind',
+    root,
+    root,
+    // Broker network: only the host relay's socket directory and the node that bridges to it.
+    ...(options.broker
+      ? [
+          '--bind',
+          options.broker.dir,
+          '/run/salaam-net',
+          '--ro-bind',
+          options.broker.node,
+          '/run/salaam-node',
+        ]
+      : []),
+    // The empty root itself is read-only too: only the workspace (and the private /tmp) is writable.
+    '--remount-ro',
+    '/',
+    '--chdir',
+    root,
+    '--',
+    ...(options.broker
+      ? [
+          '/run/salaam-node',
+          '-e',
+          inSandboxRelaySource,
+          '/run/salaam-net/relay.sock',
+          String(COMMAND_NETWORK_PORT),
+        ]
+      : []),
+    ...argv,
+  ];
+}
+
+function brokerPort(port: number): number {
+  if (!Number.isInteger(port) || port < 1 || port > 65535)
+    throw new ServiceError('invalid_field', 'A broker relay port is 1–65535');
+  return port;
+}
+
+/** The pinned Seatbelt launcher, or null when this host cannot apply a deny-by-default profile. */
+export function findSeatbelt(path = '/usr/bin/sandbox-exec'): Seatbelt | null {
+  if (!existsSync(path)) return null;
+  try {
+    // Usable means it applies a deny-by-default profile and the command still runs.
+    execFileSync(
+      path,
+      [
+        '-p',
+        '(version 1)(deny default)(allow process-exec process-fork)(allow file-read*)(allow sysctl-read)',
+        '/usr/bin/true',
+      ],
+      { timeout: 5000, stdio: 'ignore' },
+    );
+    return { path };
+  } catch {
+    return null;
+  }
+}
+
+/** A path Seatbelt can quote: absolute, with no quote, backslash or control character. */
+function sbplPath(path: string, what: string): string {
+  if (!isAbsolute(path) || /["\\\x00-\x1f\x7f]/.test(path))
+    throw new ServiceError('invalid_field', `A sandboxed command needs a plain absolute ${what}`);
+  return `"${path}"`;
+}
+
+/**
+ * The deny-by-default Seatbelt profile for a level. Reads: the system, developer tools and
+ * package prefixes, the workspace and the private tmp (file metadata anywhere, so paths resolve).
+ * Writes: the workspace (workspace-write only), the private tmp and the standard devices. No
+ * network unless declared, no mach services, no home directory.
+ */
+export function seatbeltProfile(
+  level: 'read-only' | 'workspace-write',
+  root: string,
+  tmp: string,
+  /** brokerPort: the host relay's loopback port, the only place a broker-network command may connect. */
+  options: { network: boolean; brokerPort?: number },
+): string {
+  const w = sbplPath(root, 'workspace path'),
+    t = sbplPath(tmp, 'tmp path');
+  const system = [
+    '/usr',
+    '/bin',
+    '/sbin',
+    '/System',
+    '/Library/Apple',
+    '/Library/Developer/CommandLineTools',
+    '/Applications/Xcode.app',
+    '/opt/homebrew',
+    '/usr/local',
+    '/private/etc',
+    '/private/var/db/dyld',
+    '/private/var/db/timezone',
+    '/dev',
+  ]
+    .map((p) => `(subpath "${p}")`)
+    .join(' ');
+  const devices = ['/dev/null', '/dev/zero', '/dev/stdout', '/dev/stderr', '/dev/tty']
+    .map((p) => `(literal "${p}")`)
+    .join(' ');
+  return [
+    '(version 1)',
+    '(deny default)',
+    '(allow process-exec process-fork)',
+    '(allow signal (target same-sandbox))',
+    '(allow sysctl-read)',
+    '(allow file-read-metadata)',
+    `(allow file-read* (literal "/") ${system} (subpath ${w}) (subpath ${t}))`,
+    level === 'workspace-write'
+      ? `(allow file-write* (subpath ${w}) (subpath ${t}) ${devices} (regex #"^/dev/fd/"))`
+      : `(allow file-write* (subpath ${t}) ${devices} (regex #"^/dev/fd/"))`,
+    `(allow file-ioctl ${devices} (regex #"^/dev/fd/"))`,
+    ...(options.network ? ['(allow network*)'] : []),
+    ...(options.brokerPort !== undefined && !options.network
+      ? [`(allow network-outbound (remote tcp "localhost:${brokerPort(options.brokerPort)}"))`]
+      : []),
+  ].join('\n');
+}
+
+export function seatbeltArgv(
+  level: SandboxLevel,
+  root: string,
+  tmp: string,
+  argv: string[],
+  seatbelt: Seatbelt | null,
+  options: { network: boolean; brokerPort?: number },
+): string[] {
+  if (level === 'full-access') return argv;
+  if (!seatbelt)
+    throw new ServiceError(
+      'sandbox_unavailable',
+      'This host has no usable Seatbelt, so it cannot run a sandboxed command; an operator can choose full access explicitly',
+    );
+  return [
+    seatbelt.path,
+    '-p',
+    seatbeltProfile(level, root, tmp, options),
+    '/usr/bin/env',
+    `TMPDIR=${tmp}/`,
+    ...argv,
+  ];
+}
+
+/** The sandbox this host gives local commands: bubblewrap on Linux and Seatbelt on macOS when
+ * usable, otherwise none. */
+export function chooseLocalSandbox(
+  level: SandboxLevel,
+  platform: NodeJS.Platform = process.platform,
+  find: () => Bwrap | null = findBwrap,
+  findSb: () => Seatbelt | null = findSeatbelt,
+): { kind: SandboxKind; level: SandboxLevel; bwrap: Bwrap | null; seatbelt: Seatbelt | null } {
+  const none = { kind: 'none' as const, level, bwrap: null, seatbelt: null };
+  if (level === 'full-access') return none;
+  if (platform === 'linux') {
+    const bwrap = find();
+    return bwrap ? { ...none, kind: 'bwrap', bwrap } : none;
+  }
+  if (platform === 'darwin') {
+    const seatbelt = findSb();
+    return seatbelt ? { ...none, kind: 'seatbelt', seatbelt } : none;
+  }
+  return none;
+}
+/** How host plan and approvals name a sandbox kind. */
+export function sandboxLabel(kind: SandboxKind): string {
+  return kind === 'bwrap' ? 'bubblewrap' : kind === 'seatbelt' ? 'seatbelt' : 'unsandboxed';
+}
+/** The refusal for a local command on a host with no usable sandbox and no operator opt-in. */
+export const UNSANDBOXED_REFUSAL =
+  'Local commands are refused: this host has no usable command sandbox (bubblewrap on Linux, Seatbelt on macOS). Install or repair bubblewrap, or have the operator set unsandboxed_commands: "allow" in the host config to run them unsandboxed.';

package/src/execution-evidence.ts

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import type { Store } from './store.js';
 import type { Artifacts } from './artifacts.js';
 import type { AgentPodWorkAdmission } from './agentpod-work-protocol.js';
@@ -244,6 +245,32 @@ export function executionEvidence(
     SELECT id,session_id,digest,bytes FROM artifacts
     WHERE session_id IN (SELECT id FROM tree) ORDER BY id LIMIT 257`),
   );
+  // A verified completion names each deliverable's artifact with the sha256 of its bytes.
+  // Only an artifact whose bytes match that digest counts as produced; dispositions are
+  // computed for this session's own artifacts alone, so another session's id names nothing.
+  const deliverables = new Set<string>();
+  const completed = store.db
+    .prepare("SELECT artifact_id FROM task_completions WHERE task_id=? AND state='succeeded'")
+    .get(taskId);
+  if (completed?.artifact_id) {
+    let record: { deliverables?: unknown } = {};
+    try {
+      record = JSON.parse(artifacts.read(String(completed.artifact_id)));
+    } catch {
+      record = {};
+    }
+    for (const d of Array.isArray(record.deliverables) ? record.deliverables : []) {
+      const id = (d as { artifact_id?: unknown }).artifact_id,
+        sha = (d as { sha256?: unknown }).sha256;
+      if (typeof id !== 'string' || typeof sha !== 'string') continue;
+      try {
+        if (createHash('sha256').update(artifacts.read(id)).digest('hex') === sha)
+          deliverables.add(id);
+      } catch {
+        /* a missing or corrupt artifact is not a deliverable */
+      }
+    }
+  }
   const artifactEvidence = artifactRows.map((row): Row & { disposition: string } => {
     // Check actual immutable bytes, not just a database's claimed fingerprint.
     const content = artifacts.read(String(row.id));
@@ -273,7 +300,10 @@ export function executionEvidence(
         ? 'integrated'
         : children.some((child) => child.artifact_id === row.id)
           ? 'proposed'
-          : appliedPatch || completion || checks.some((check) => check.artifact_id === row.id)
+          : appliedPatch ||
+              completion ||
+              deliverables.has(String(row.id)) ||
+              checks.some((check) => check.artifact_id === row.id)
             ? 'produced'
             : 'observed';
     return { ...row, disposition };

package/src/host-bind.ts

@@ -0,0 +1,156 @@
+import {
+  chmodSync,
+  closeSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  writeFileSync,
+  existsSync,
+} from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { isAbsolute, join, resolve } from 'node:path';
+import { planHost } from './host.js';
+import { canonical, digest } from './protocol.js';
+import {
+  stationHash,
+  stationRuntimeFingerprint,
+  stationWorkspaceIdentity,
+} from './station-config.js';
+
+export interface BindInput {
+  organization_id: string;
+  node_id: string;
+  station_key: string;
+  workspace: string;
+  tools_user: string;
+  files: string;
+  runtime_root: string;
+  runtime_image_digest: string;
+  operator_group?: string;
+  dir?: string;
+  state?: string;
+  provider?: string;
+  model?: string;
+  mcp_config?: string;
+  /** Item 9: the operator's persona file (root-owned, outside the workspace). */
+  persona?: string;
+  /** AgentPod-managed MCP profile: HTTP mcpServers the node assigns to admitted sessions. */
+  managed_mcp_config?: string;
+  /** Defaults to /usr/bin/systemd-run and /usr/bin/systemctl. */
+  systemd_run?: string;
+  systemctl?: string;
+  /** Tests only: where the default per-station directories live. */
+  roots?: { config: string; state: string };
+}
+
+const userName = /^[a-z_][a-z0-9_-]{0,31}$/;
+function pin(path: string) {
+  const real = realpathSync(path);
+  return { path: real, sha256: stationHash(readFileSync(real)) };
+}
+/** Write a private file only when its content changes; report whether it did. */
+function put(path: string, value: unknown): boolean {
+  const text = JSON.stringify(value, null, 2) + '\n';
+  if (existsSync(path) && readFileSync(path, 'utf8') === text) return false;
+  const tmp = path + '.tmp',
+    fd = openSync(tmp, 'w', 0o600);
+  try {
+    writeFileSync(fd, text);
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(tmp, path);
+  return true;
+}
+
+/** Bind one AgentPod station to a launcher-profile strict work host. Root on Linux.
+ * Every output is derived from the inputs; nothing is edited by hand. */
+export async function bindHost(input: BindInput) {
+  if (process.platform !== 'linux' || process.getuid?.() !== 0)
+    throw Error('host bind runs as root on Linux');
+  const workspace = input.workspace;
+  if (!isAbsolute(workspace) || realpathSync(workspace) !== workspace)
+    throw Error('Use the canonical absolute workspace path');
+  const key = 'salaam:' + createHash('sha256').update(workspace).digest('hex').slice(0, 16);
+  if (input.station_key !== key)
+    throw Error('Station key does not name this workspace (expected ' + key + ')');
+  if (!userName.test(input.tools_user)) throw Error('tools user must be a user name');
+  try {
+    execFileSync('/usr/bin/getent', ['passwd', input.tools_user], { stdio: 'ignore' });
+  } catch {
+    throw Error('tools user does not exist');
+  }
+  if (input.tools_user === 'root') throw Error('tools user must not be root');
+  const id = key.slice('salaam:'.length),
+    roots = input.roots ?? { config: '/etc/salaam/stations', state: '/var/lib/salaam/stations' },
+    dir = resolve(input.dir ?? join(roots.config, id)),
+    state = resolve(input.state ?? join(roots.state, id, 'state'));
+  mkdirSync(dir, { recursive: true, mode: 0o755 });
+  // Ancestors of state stay traversable so the operator group can reach operator.sock;
+  // state itself is the daemon's (0700, or 0710 for the operator group once served).
+  mkdirSync(join(state, '..'), { recursive: true, mode: 0o755 });
+  chmodSync(join(state, '..'), 0o755);
+  const pinsPath = join(dir, 'agentpod-pins.json'),
+    stationPath = join(dir, 'station-config.json'),
+    configPath = join(dir, 'host-config.json'),
+    manifestPath = join(dir, 'host.json');
+  let changed = put(pinsPath, {
+    version: 1,
+    organization_id: input.organization_id,
+    node_id: input.node_id,
+    station_key: key,
+    workspace,
+  });
+  const runtime = realpathSync(input.runtime_root);
+  changed =
+    put(stationPath, {
+      version: 1,
+      kind: 'linux-systemd-station-v1',
+      workspace,
+      workspace_identity: stationWorkspaceIdentity(workspace),
+      files: pin(input.files),
+      systemd_run: pin(input.systemd_run ?? '/usr/bin/systemd-run'),
+      systemctl: pin(input.systemctl ?? '/usr/bin/systemctl'),
+      runtime_root: runtime,
+      runtime_fingerprint: stationRuntimeFingerprint(runtime),
+      runtime_image_digest: input.runtime_image_digest,
+      tools_user: input.tools_user,
+    }) || changed;
+  const config = {
+    mode: 'agentpod',
+    state,
+    agentpod_config: pinsPath,
+    station_config: stationPath,
+    strict_work_version: 1,
+    ...(input.operator_group ? { operator_group: input.operator_group } : {}),
+    ...(input.provider ? { provider: input.provider } : {}),
+    ...(input.model ? { model: input.model } : {}),
+    ...(input.mcp_config ? { operator_mcp_config: realpathSync(input.mcp_config) } : {}),
+    ...(input.persona ? { persona_config: realpathSync(input.persona) } : {}),
+    ...(input.managed_mcp_config ? { mcp_config: realpathSync(input.managed_mcp_config) } : {}),
+  };
+  changed = put(configPath, config) || changed;
+  const manifest = await planHost(config);
+  const before = existsSync(manifestPath)
+    ? canonical(JSON.parse(readFileSync(manifestPath, 'utf8')))
+    : null;
+  if (before !== canonical(manifest)) {
+    put(manifestPath, manifest);
+    changed = true;
+  }
+  return {
+    version: 1,
+    station_key: key,
+    dir,
+    state,
+    manifest: manifestPath,
+    manifest_digest: digest(manifest),
+    unit: 'salaam-host@' + id + '.service',
+    changed,
+  };
+}