@pleri/olam-cli 0.1.68 → 0.1.69

package/dist/__tests__/audit-publish-deps-contract.test.d.ts

@@ -0,0 +1,26 @@
+/**
+ * audit-publish-deps-contract.test.ts — contractual regression for the fix
+ * that prevents the May-2026 release-pipeline wedge.
+ *
+ * Bug history: PR #375 added `_require('json-source-map')` to
+ * src/commands/config.ts but rewrite-publish-package-json.mjs's hand-curated
+ * PUBLISH_DEPS list never picked it up. Versions 0.1.66 / 0.1.67 / 0.1.68
+ * published to npm without json-source-map declared. host-cp Dockerfile's
+ * `npm install -g @pleri/olam-cli@latest && olam --version` crashed with
+ * `Cannot find module 'json-source-map'`. Three consecutive release runs
+ * failed; pipeline wedged because the host-cp build sat upstream of the
+ * commit-and-publish-npm step that would have shipped the fix.
+ *
+ * Pin the contract:
+ *   1. PUBLISH_DEPS must contain json-source-map.
+ *   2. EXTERNAL must contain json-source-map (esbuild can't bundle dynamic
+ *      _require()'d modules; without external, the require survives in the
+ *      bundle and crashes if not also installed at runtime).
+ *   3. The audit-publish-deps.mjs script exists and is wired into prepublishOnly
+ *      so this drift class fails fast rather than wedging the pipeline.
+ *   4. The host-cp Dockerfile installs from a local tarball (cli.tgz), not
+ *      from npm @latest — eliminates the wedge class permanently.
+ *   5. The release.yml workflow stages cli.tgz before the host-cp build.
+ */
+export {};
+//# sourceMappingURL=audit-publish-deps-contract.test.d.ts.map

package/dist/__tests__/audit-publish-deps-contract.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-publish-deps-contract.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/audit-publish-deps-contract.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG"}

package/dist/__tests__/audit-publish-deps-contract.test.js

@@ -0,0 +1,86 @@
+/**
+ * audit-publish-deps-contract.test.ts — contractual regression for the fix
+ * that prevents the May-2026 release-pipeline wedge.
+ *
+ * Bug history: PR #375 added `_require('json-source-map')` to
+ * src/commands/config.ts but rewrite-publish-package-json.mjs's hand-curated
+ * PUBLISH_DEPS list never picked it up. Versions 0.1.66 / 0.1.67 / 0.1.68
+ * published to npm without json-source-map declared. host-cp Dockerfile's
+ * `npm install -g @pleri/olam-cli@latest && olam --version` crashed with
+ * `Cannot find module 'json-source-map'`. Three consecutive release runs
+ * failed; pipeline wedged because the host-cp build sat upstream of the
+ * commit-and-publish-npm step that would have shipped the fix.
+ *
+ * Pin the contract:
+ *   1. PUBLISH_DEPS must contain json-source-map.
+ *   2. EXTERNAL must contain json-source-map (esbuild can't bundle dynamic
+ *      _require()'d modules; without external, the require survives in the
+ *      bundle and crashes if not also installed at runtime).
+ *   3. The audit-publish-deps.mjs script exists and is wired into prepublishOnly
+ *      so this drift class fails fast rather than wedging the pipeline.
+ *   4. The host-cp Dockerfile installs from a local tarball (cli.tgz), not
+ *      from npm @latest — eliminates the wedge class permanently.
+ *   5. The release.yml workflow stages cli.tgz before the host-cp build.
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const CLI_ROOT = join(__dirname, '..', '..');
+const REPO_ROOT = join(CLI_ROOT, '..', '..');
+describe('release pipeline wedge — invariants', () => {
+    it('PUBLISH_DEPS contains json-source-map', () => {
+        const src = readFileSync(join(CLI_ROOT, 'scripts', 'rewrite-publish-package-json.mjs'), 'utf8');
+        expect(src).toMatch(/['"]json-source-map['"]\s*:\s*['"]\^?0\.6\./);
+    });
+    it('bundle-cli.mjs marks json-source-map external (dynamic _require)', () => {
+        const src = readFileSync(join(CLI_ROOT, 'scripts', 'bundle-cli.mjs'), 'utf8');
+        // Must appear inside the EXTERNAL array literal.
+        const externalBlock = src.slice(src.indexOf('const EXTERNAL = ['));
+        expect(externalBlock).toMatch(/['"]json-source-map['"]/);
+    });
+    it('audit-publish-deps.mjs exists and is wired into prepublishOnly', () => {
+        const auditScript = readFileSync(join(CLI_ROOT, 'scripts', 'audit-publish-deps.mjs'), 'utf8');
+        expect(auditScript).toMatch(/PUBLISH_DEPS/);
+        expect(auditScript).toMatch(/EXTERNAL/);
+        const pkg = JSON.parse(readFileSync(join(CLI_ROOT, 'package.json'), 'utf8'));
+        // prepublishOnly must run audit:publish-deps before rewrite-publish-package-json.
+        expect(pkg.scripts.prepublishOnly).toMatch(/audit:publish-deps/);
+        // The script itself must exist as an npm script too.
+        expect(pkg.scripts['audit:publish-deps']).toBeDefined();
+    });
+    it('host-cp Dockerfile installs from local cli.tgz, not npm @latest', () => {
+        const dockerfile = readFileSync(join(REPO_ROOT, 'packages', 'host-cp', 'Dockerfile'), 'utf8');
+        // Must NOT pull from npm @latest — that's the wedge.
+        // Match only ACTUAL run-shape lines (npm install at line start or after
+        // backslash-continuation), not the comment block that documents the
+        // historical bug.
+        const runLines = dockerfile
+            .split('\n')
+            .filter((l) => !l.trim().startsWith('#'))
+            .join('\n');
+        expect(runLines).not.toMatch(/npm install -g @pleri\/olam-cli@latest/);
+        // Must install from the staged tarball.
+        expect(dockerfile).toMatch(/COPY cli\.tgz/);
+        expect(dockerfile).toMatch(/npm install -g \/tmp\/olam-cli\.tgz/);
+    });
+    it('release.yml stages cli.tgz before host-cp docker build', () => {
+        const workflow = readFileSync(join(REPO_ROOT, '.github', 'workflows', 'release.yml'), 'utf8');
+        expect(workflow).toMatch(/scripts\/ci\/stage-host-cp-cli\.sh/);
+        // Order matters: stage-host-cp-cli.sh must appear BEFORE the
+        // docker/build-push-action@v6 invocation in publish-host-cp.
+        const publishHostCpBlock = workflow.slice(workflow.indexOf('publish-host-cp:'));
+        const stageIdx = publishHostCpBlock.indexOf('stage-host-cp-cli.sh');
+        const buildIdx = publishHostCpBlock.indexOf('docker/build-push-action');
+        expect(stageIdx).toBeGreaterThan(0);
+        expect(buildIdx).toBeGreaterThan(stageIdx);
+    });
+    it('ci.yml audit job runs audit:publish-deps', () => {
+        const ci = readFileSync(join(REPO_ROOT, '.github', 'workflows', 'ci.yml'), 'utf8');
+        expect(ci).toMatch(/audit:publish-deps/);
+    });
+});
+//# sourceMappingURL=audit-publish-deps-contract.test.js.map

package/dist/__tests__/audit-publish-deps-contract.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-publish-deps-contract.test.js","sourceRoot":"","sources":["../../src/__tests__/audit-publish-deps-contract.test.ts"],"names":[],"mappings":"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"}

package/dist/image-digests.json

@@ -1,9 +1,9 @@
 {
-  "auth": "sha256:1e6d3574077ba70ba908b5ae343e9ff669937468ff1f48e3e9a449ac38578cc6",
-  "devbox": "sha256:6de8b15bc7e4b07b84ea10b011e939bd874c0ac5c2fb0c4c53db668c6c53b2b8",
-  "host-cp": "sha256:0a533a638300bda05a45440c62a673300c6d122be74eb83e9b21a0ea4432f174",
-  "mcp-auth": "sha256:cccf9fc022a3b58080007761ff10e4820080d26491e7b6e758e3e766c9eac896",
+  "auth": "sha256:ab26e55f6b6835720596edcc6e969740298ee6b4f42b0a2070886527d3b8d83b",
+  "devbox": "sha256:f1b6e9b92c89bc9d76d83a718f0345e7a9a8484fb8157d2007409c413ae80b35",
+  "host-cp": "sha256:60b01e6c33251ab52be32bcfd5cd798dda7f9be5078e6a1cc104737471ed73c6",
+  "mcp-auth": "sha256:c8dcaf921b5da00474a3c9585dac9b8a095bd2da60836cbc8637995d62b83f9c",
   "$schema_version": 1,
-  "$published_version": "0.1.68",
+  "$published_version": "0.1.69",
   "$registry": "ghcr.io/pleri"
 }

package/host-cp/src/listening-server-poller.mjs

@@ -0,0 +1,141 @@
+/**
+ * listening-server-poller.mjs
+ * Discovers listening TCP ports inside a world's devbox container.
+ * Dual-mode: Docker HTTP API (container) vs docker exec CLI (bare-node).
+ * Cache TTL: 10s per world.
+ */
+import { spawnSync } from 'node:child_process';
+
+const DOCKER_HOST = process.env.DOCKER_HOST ?? 'docker-cli';
+// Skip well-known infra ports — these are always running and not user servers
+const INFRA_PORTS = new Set([8080, 7681]);
+
+// Per-world cache: worldId → { ts, servers, error? }
+const cache = new Map();
+const CACHE_TTL_MS = 10_000;
+
+function worldContainerName(worldId) {
+  return `olam-${worldId}-devbox`;
+}
+
+/**
+ * Parse `ss -tlnp` output into server rows.
+ * Output format:
+ *   Netid  State   Recv-Q  Send-Q  Local Address:Port  Peer Address:Port  Process
+ *   tcp    LISTEN  0       128     0.0.0.0:5173        0.0.0.0:*           users:(("vite",pid=42,fd=8))
+ *
+ * @param {string} stdout
+ * @returns {Array<{port: number, pid: string, cmd: string}>}
+ */
+export function parseSsOutput(stdout) {
+  const lines = stdout.trim().split('\n').slice(1); // skip header
+  const results = [];
+  for (const line of lines) {
+    const parts = line.trim().split(/\s+/);
+    if (parts.length < 5) continue;
+    // parts[3] = Local Address:Port  (e.g. "0.0.0.0:5173" or "*:5173" or ":::5173")
+    const localAddr = parts[3];
+    const colonIdx = localAddr.lastIndexOf(':');
+    if (colonIdx === -1) continue;
+    const portStr = localAddr.slice(colonIdx + 1);
+    const port = parseInt(portStr, 10);
+    if (!Number.isFinite(port) || port <= 0) continue;
+    if (INFRA_PORTS.has(port)) continue;
+
+    // Extract pid and cmd from process column: users:(("vite",pid=42,fd=8))
+    let pid = '';
+    let cmd = '';
+    const processCol = parts.slice(4).join(' ');
+    const pidMatch = /pid=(\d+)/.exec(processCol);
+    if (pidMatch) pid = pidMatch[1];
+    const cmdMatch = /"([^"]+)"/.exec(processCol);
+    if (cmdMatch) cmd = cmdMatch[1];
+
+    results.push({ port, pid, cmd });
+  }
+  return results;
+}
+
+/**
+ * Fetch listening servers for a world. Returns cached result if <10s old.
+ * @param {string} worldId
+ * @returns {Promise<{ts: number, servers: Array<{port: number, pid: string, cmd: string}>, error?: string}>}
+ */
+export async function getListeningServers(worldId) {
+  const cached = cache.get(worldId);
+  if (cached && Date.now() - cached.ts < CACHE_TTL_MS) return cached;
+
+  const containerName = worldContainerName(worldId);
+  try {
+    let stdout;
+    if (DOCKER_HOST === 'docker-cli') {
+      const result = spawnSync(
+        'docker', ['exec', containerName, 'ss', '-tlnp'],
+        { encoding: 'utf-8', timeout: 3000 },
+      );
+      if (result.status !== 0 || result.error) {
+        const entry = { ts: Date.now(), servers: [], error: 'container not running' };
+        cache.set(worldId, entry);
+        return entry;
+      }
+      stdout = result.stdout ?? '';
+    } else {
+      const apiBase = DOCKER_HOST.replace(/^tcp:\/\//, 'http://');
+      const execCreate = await fetch(
+        `${apiBase}/containers/${encodeURIComponent(containerName)}/exec`,
+        {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            AttachStdout: true,
+            AttachStderr: false,
+            Cmd: ['ss', '-tlnp'],
+          }),
+          signal: AbortSignal.timeout(3000),
+        },
+      );
+      if (!execCreate.ok) {
+        const entry = { ts: Date.now(), servers: [], error: 'container not running' };
+        cache.set(worldId, entry);
+        return entry;
+      }
+      const { Id: execId } = await execCreate.json();
+      const execStart = await fetch(`${apiBase}/exec/${execId}/start`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ Detach: false, Tty: false }),
+        signal: AbortSignal.timeout(3000),
+      });
+      // Docker exec start streams multiplexed output (8-byte header per frame)
+      const buf = await execStart.arrayBuffer();
+      stdout = demuxDockerStream(Buffer.from(buf));
+    }
+    const servers = parseSsOutput(stdout);
+    const entry = { ts: Date.now(), servers };
+    cache.set(worldId, entry);
+    return entry;
+  } catch {
+    const entry = { ts: Date.now(), servers: [], error: 'container not running' };
+    cache.set(worldId, entry);
+    return entry;
+  }
+}
+
+/**
+ * Strip Docker stream multiplexing headers (8 bytes per frame: [stream, 0, 0, 0, size32be]).
+ * @param {Buffer} buf
+ * @returns {string}
+ */
+function demuxDockerStream(buf) {
+  let output = '';
+  let offset = 0;
+  while (offset + 8 <= buf.length) {
+    const size = buf.readUInt32BE(offset + 4);
+    const payload = buf.slice(offset + 8, offset + 8 + size);
+    output += payload.toString('utf-8');
+    offset += 8 + size;
+  }
+  return output;
+}
+
+export { parseSsOutput as _parseSsOutputForTests };

package/host-cp/src/port-bridge-manager.mjs

@@ -0,0 +1,290 @@
+/**
+ * port-bridge-manager.mjs
+ * Manages socat sidecar containers that bridge host port → world devbox port.
+ * Dual-mode: Docker HTTP API (container) vs docker CLI (bare-node).
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const DOCKER_HOST = process.env.DOCKER_HOST ?? 'docker-cli';
+const SOCAT_IMAGE = 'alpine/socat';
+const HOST_PORT_MIN = 25000;
+const HOST_PORT_MAX = 25999;
+const INFRA_PORTS = new Set([8080, 7681]);
+
+let BRIDGES_PATH =
+  process.env.OLAM_PORT_BRIDGES_PATH ??
+  path.join(os.homedir(), '.olam', 'port-bridges.json');
+let HOST_IP = '127.0.0.1';
+
+// key: `${worldId}:${containerPort}` → { worldId, containerPort, hostPort, containerId, containerName }
+const registry = new Map();
+
+export function configure({ bridgesPath, hostIp }) {
+  if (bridgesPath && bridgesPath !== BRIDGES_PATH) {
+    BRIDGES_PATH = bridgesPath;
+    loadState();
+  }
+  if (hostIp) HOST_IP = hostIp;
+}
+
+function bridgeKey(worldId, containerPort) {
+  return `${worldId}:${containerPort}`;
+}
+
+function bridgeContainerName(worldId, containerPort) {
+  return `olam-${worldId}-bridge-${containerPort}`;
+}
+
+function loadState() {
+  try {
+    if (!fs.existsSync(BRIDGES_PATH)) return;
+    const raw = fs.readFileSync(BRIDGES_PATH, 'utf-8');
+    const data = JSON.parse(raw);
+    if (!data || typeof data !== 'object') return;
+    for (const [key, entry] of Object.entries(data)) {
+      registry.set(key, entry);
+    }
+  } catch (err) {
+    console.error(`port-bridge-manager: loadState failed: ${err.message}`);
+  }
+}
+
+function saveState() {
+  try {
+    const dir = path.dirname(BRIDGES_PATH);
+    fs.mkdirSync(dir, { recursive: true });
+    const data = {};
+    for (const [key, entry] of registry) {
+      data[key] = entry;
+    }
+    const tmp = `${BRIDGES_PATH}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf-8');
+    fs.renameSync(tmp, BRIDGES_PATH);
+  } catch (err) {
+    console.error(`port-bridge-manager: saveState failed: ${err.message}`);
+  }
+}
+
+function allocateHostPort() {
+  const used = new Set(Array.from(registry.values()).map((e) => e.hostPort));
+  for (let p = HOST_PORT_MIN; p <= HOST_PORT_MAX; p++) {
+    if (!used.has(p)) return p;
+  }
+  return null;
+}
+
+async function dockerApiBase() {
+  return DOCKER_HOST === 'docker-cli'
+    ? null // bare-node: no socket proxy HTTP API
+    : DOCKER_HOST.replace(/^tcp:\/\//, 'http://');
+}
+
+/**
+ * Create and start a socat bridge container. Returns containerId.
+ * @param {string} worldId
+ * @param {number} containerPort
+ * @param {number} hostPort
+ * @returns {Promise<string>} containerId
+ */
+async function createBridgeContainer(worldId, containerPort, hostPort) {
+  const name = bridgeContainerName(worldId, containerPort);
+  const networkName = `olam-${worldId}`;
+  const devboxName = `olam-${worldId}-devbox`;
+  const socatCmd = `TCP-LISTEN:${containerPort},fork,reuseaddr TCP:${devboxName}:${containerPort}`;
+
+  const apiBase = await dockerApiBase();
+
+  if (!apiBase) {
+    // bare-node: use docker CLI
+    const args = [
+      'run', '-d',
+      '--name', name,
+      '--network', networkName,
+      '-p', `${HOST_IP}:${hostPort}:${containerPort}`,
+      '--label', `olam.world.id=${worldId}`,
+      '--label', 'olam.role=server-bridge',
+      '--restart', 'unless-stopped',
+      SOCAT_IMAGE,
+      'TCP-LISTEN:' + containerPort + ',fork,reuseaddr',
+      'TCP:' + devboxName + ':' + containerPort,
+    ];
+    const result = spawnSync('docker', args, { encoding: 'utf-8', timeout: 10000 });
+    if (result.status !== 0) {
+      throw new Error(result.stderr?.trim() || 'docker run failed');
+    }
+    return result.stdout.trim(); // container ID
+  }
+
+  // container mode: Docker HTTP API
+  const createBody = {
+    Image: SOCAT_IMAGE,
+    Cmd: socatCmd.split(' '),
+    Labels: {
+      'olam.world.id': worldId,
+      'olam.role': 'server-bridge',
+    },
+    HostConfig: {
+      NetworkMode: networkName,
+      PortBindings: {
+        [`${containerPort}/tcp`]: [{ HostIp: HOST_IP, HostPort: String(hostPort) }],
+      },
+      RestartPolicy: { Name: 'unless-stopped' },
+    },
+  };
+
+  const createResp = await fetch(
+    `${apiBase}/containers/create?name=${encodeURIComponent(name)}`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(createBody),
+      signal: AbortSignal.timeout(10000),
+    },
+  );
+
+  if (!createResp.ok) {
+    const body = await createResp.text().catch(() => '');
+    // If container already exists (409), try to get its ID
+    if (createResp.status === 409) {
+      const inspectResp = await fetch(
+        `${apiBase}/containers/${encodeURIComponent(name)}/json`,
+        { signal: AbortSignal.timeout(3000) },
+      );
+      if (inspectResp.ok) {
+        const info = await inspectResp.json();
+        return info.Id;
+      }
+    }
+    throw new Error(`container create failed: ${createResp.status} ${body}`);
+  }
+
+  const { Id: containerId } = await createResp.json();
+
+  const startResp = await fetch(`${apiBase}/containers/${encodeURIComponent(containerId)}/start`, {
+    method: 'POST',
+    signal: AbortSignal.timeout(5000),
+  });
+  if (!startResp.ok && startResp.status !== 304) {
+    throw new Error(`container start failed: ${startResp.status}`);
+  }
+
+  return containerId;
+}
+
+async function removeBridgeContainer(containerName, containerId) {
+  const id = containerId || containerName;
+  const apiBase = await dockerApiBase();
+
+  if (!apiBase) {
+    spawnSync('docker', ['rm', '-f', id], { encoding: 'utf-8', timeout: 5000 });
+    return;
+  }
+
+  // Force remove (stop + delete in one call)
+  await fetch(`${apiBase}/containers/${encodeURIComponent(id)}?force=true`, {
+    method: 'DELETE',
+    signal: AbortSignal.timeout(5000),
+  }).catch(() => { /* best-effort */ });
+}
+
+/**
+ * Expose a world's container port via a socat bridge.
+ * Idempotent: returns existing bridge if already active.
+ *
+ * @param {string} worldId
+ * @param {number} containerPort
+ * @returns {Promise<{hostPort: number, containerPort: number, url: string, containerId: string}>}
+ */
+export async function exposePort(worldId, containerPort) {
+  if (INFRA_PORTS.has(containerPort)) {
+    throw new Error(`port ${containerPort} is reserved for infrastructure`);
+  }
+
+  const key = bridgeKey(worldId, containerPort);
+  const existing = registry.get(key);
+  if (existing) {
+    return {
+      hostPort: existing.hostPort,
+      containerPort: existing.containerPort,
+      url: `http://${HOST_IP}:${existing.hostPort}`,
+      containerId: existing.containerId,
+    };
+  }
+
+  const hostPort = allocateHostPort();
+  if (hostPort === null) {
+    throw new Error('no host ports available in range 25000–25999');
+  }
+
+  const containerName = bridgeContainerName(worldId, containerPort);
+  const containerId = await createBridgeContainer(worldId, containerPort, hostPort);
+
+  const entry = { worldId, containerPort, hostPort, containerId, containerName };
+  registry.set(key, entry);
+  saveState();
+
+  return {
+    hostPort,
+    containerPort,
+    url: `http://${HOST_IP}:${hostPort}`,
+    containerId,
+  };
+}
+
+/**
+ * Remove a port bridge for a world.
+ * No-op if bridge doesn't exist.
+ *
+ * @param {string} worldId
+ * @param {number} containerPort
+ */
+export async function removePort(worldId, containerPort) {
+  const key = bridgeKey(worldId, containerPort);
+  const entry = registry.get(key);
+  if (!entry) return;
+
+  registry.delete(key);
+  saveState();
+
+  await removeBridgeContainer(entry.containerName, entry.containerId);
+}
+
+/**
+ * Remove all bridges for a world. Called on world destroy.
+ * @param {string} worldId
+ */
+export async function killWorld(worldId) {
+  const toDelete = [];
+  for (const [key, entry] of registry) {
+    if (entry.worldId === worldId) toDelete.push({ key, entry });
+  }
+  for (const { key, entry } of toDelete) {
+    registry.delete(key);
+    await removeBridgeContainer(entry.containerName, entry.containerId).catch(() => {});
+  }
+  if (toDelete.length > 0) saveState();
+}
+
+/**
+ * List active bridges for a world.
+ * @param {string} worldId
+ * @returns {Array<{containerPort: number, hostPort: number, url: string}>}
+ */
+export function getWorldBridges(worldId) {
+  const result = [];
+  for (const entry of registry.values()) {
+    if (entry.worldId === worldId) {
+      result.push({
+        containerPort: entry.containerPort,
+        hostPort: entry.hostPort,
+        url: `http://${HOST_IP}:${entry.hostPort}`,
+      });
+    }
+  }
+  return result;
+}
+
+loadState();

package/host-cp/src/server.mjs

@@ -55,13 +55,17 @@ import { composeWorldsSources } from './compose-worlds-sources.mjs';
 import { createWorldPrStateStore } from './world-pr-state.mjs';
 import { PlanOrchestrator } from './plan-orchestrator.mjs';
 import { createPrMergePoller } from './pr-merge-poller.mjs';
-import { createPrNanny, defaultConsultCodex, defaultDispatchToWorld } from './pr-nanny.mjs';
 import { parse as parseYaml } from 'yaml';
 import { startWorldsDbReconciler } from './worlds-db-source.mjs';
 import { authSecretHint } from './auth-secret-hint.mjs';
 import * as tunnelManager from './world-tunnel-manager.mjs';
-import { getProcessSnapshot, subscribeToProcesses } from './process-poller.mjs';
+import * as bridgeManager from './port-bridge-manager.mjs';
 import { buildVersionSnapshot } from './version-status.mjs';
+import {
+  handleListProcesses,
+  handleListServers,
+  handleServerBridges,
+} from './routes/process-port.mjs';
 
 // ── Deployment-mode detection ─────────────────────────────────────
 //
@@ -325,6 +329,7 @@ const prPoller = createPrMergePoller({
   getGhToken: resolveGhToken,
   destroyWorld: async (worldId) => {
     tunnelManager.killWorld(worldId);
+    await bridgeManager.killWorld(worldId);
     const apiBase = DOCKER_HOST.replace(/^tcp:\/\//, 'http://');
     const containerName = `olam-${worldId}-devbox`;
     try {
@@ -347,17 +352,6 @@ const prPoller = createPrMergePoller({
 });
 prPoller.start();
 
-// ── PR Nanny — watch all open PRs and dispatch fixes ──────────────────────
-
-const prNanny = createPrNanny({
-  prStateStore,
-  getGhToken: resolveGhToken,
-  dispatchToWorld: defaultDispatchToWorld,
-  consultCodex: defaultConsultCodex,
-  pollIntervalMs: parseInt(process.env.OLAM_PR_NANNY_POLL_INTERVAL_MS ?? '60000', 10),
-});
-prNanny.start();
-
 // ── Worlds-DB reconcile loop ────────────────────────────────────
 //
 // When host-cp runs bare-node, the CLI's auto-register may not have fired
@@ -630,11 +624,6 @@ const server = http.createServer(async (req, res) => {
       pr_number: pr.pr_number ?? null,
       pr_url: pr.pr_url ?? null,
       pr_state: prState,
-      nanny_dispatch_count: pr.nanny_dispatch_count ?? 0,
-      nanny_paused: pr.nanny_paused ?? false,
-      nanny_escalated: pr.nanny_escalated ?? false,
-      nanny_loop_halted: pr.nanny_loop_halted ?? false,
-      nanny_external_blocker: pr.nanny_external_blocker ?? false,
     });
   }
 
@@ -755,8 +744,9 @@ const server = http.createServer(async (req, res) => {
   const adminDelete = /^\/api\/admin\/registry\/([^/?#]+)$/.exec(url.pathname);
   if (adminDelete && req.method === 'DELETE') {
     const id = decodeURIComponent(adminDelete[1]);
-    // Kill tunnels before removing from registry so no cloudflared procs orphan.
+    // Kill tunnels and port bridges before removing from registry.
     tunnelManager.killWorld(id);
+    void bridgeManager.killWorld(id);
     if (id in WORLDS) {
       const next = { ...WORLDS };
       delete next[id];
@@ -1338,62 +1328,13 @@ const server = http.createServer(async (req, res) => {
     return;
   }
 
-  // ── PR Nanny operator overrides ──────────────────────────────────────────
-  //
-  // POST /api/admin/nanny/:worldId/pause    — pause nanny for this world
-  // POST /api/admin/nanny/:worldId/resume   — resume nanny for this world
-  // POST /api/admin/nanny/:worldId/escalate — mark escalated, stop dispatching
-  // GET  /api/admin/nanny                  — dump nanny state for all worlds
-  //
-  // Calling-world identity: X-Olam-World-Id header validated against registry.
-
-  const nannyAction = /^\/api\/admin\/nanny\/([^/?#]+)\/(pause|resume|escalate)$/.exec(url.pathname);
-  if (nannyAction && req.method === 'POST') {
-    if (!auth.isAuthorized(req)) { return res.writeHead(401).end(); }
-    const worldId = decodeURIComponent(nannyAction[1]);
-    const action = nannyAction[2];
-    // Validate calling-world identity when header present
-    const callerWorldId = req.headers['x-olam-world-id'];
-    if (callerWorldId && !(callerWorldId in WORLDS)) {
-      return jsonReply(res, 403, { error: 'caller_world_not_registered' });
-    }
-    const existing = prStateStore.get(worldId);
-    if (!existing) return jsonReply(res, 404, { error: 'world_not_found' });
-    if (action === 'pause') {
-      prStateStore.set(worldId, { nanny_paused: true, nanny_pause_reason: 'operator' });
-    } else if (action === 'resume') {
-      prStateStore.set(worldId, { nanny_paused: false, nanny_loop_halted: false, nanny_escalated: false });
-    } else if (action === 'escalate') {
-      prStateStore.set(worldId, { nanny_escalated: true, nanny_escalate_reason: 'operator' });
-    }
-    return jsonReply(res, 200, prStateStore.get(worldId));
-  }
-
-  if (url.pathname === '/api/admin/nanny' && req.method === 'GET') {
-    if (!auth.isAuthorized(req)) { return res.writeHead(401).end(); }
-    const all = prStateStore.getAll();
-    const nannyStates = Object.fromEntries(
-      Object.entries(all).map(([id, e]) => [id, {
-        nanny_dispatch_count: e.nanny_dispatch_count ?? 0,
-        nanny_paused: e.nanny_paused ?? false,
-        nanny_escalated: e.nanny_escalated ?? false,
-        nanny_loop_halted: e.nanny_loop_halted ?? false,
-        nanny_external_blocker: e.nanny_external_blocker ?? false,
-        nanny_first_dispatch_at: e.nanny_first_dispatch_at ?? null,
-        nanny_last_dispatch_at: e.nanny_last_dispatch_at ?? null,
-        pr_url: e.pr_url ?? null,
-        pr_state: e.pr_state ?? null,
-      }]),
-    );
-    return jsonReply(res, 200, nannyStates);
-  }
-
   // DELETE /api/worlds/:worldId — immediate destroy
   const worldDestroyMatch = /^\/api\/worlds\/([^/?#]+)$/.exec(url.pathname);
   if (worldDestroyMatch && req.method === 'DELETE') {
     if (!auth.isAuthorized(req)) { return res.writeHead(401).end(); }
     const worldId = decodeURIComponent(worldDestroyMatch[1]);
     tunnelManager.killWorld(worldId);
+    await bridgeManager.killWorld(worldId);
     const apiBase = DOCKER_HOST.replace(/^tcp:\/\//, 'http://');
     const containerName = `olam-${worldId}-devbox`;
     try {
@@ -1607,22 +1548,40 @@ const server = http.createServer(async (req, res) => {
     return jsonReply(res, 200, { ok: true });
   }
 
-  // GET /api/worlds/:id/processes — JSON snapshot of in-container processes.
-  // GET /api/worlds/:id/processes/stream — SSE fanout (5s cadence, per-world).
-  // Inserted after auth middleware and the /api/worlds/:id/services route.
+  // GET /api/worlds/:id/processes
+  // GET /api/worlds/:id/processes/stream — SSE fanout (5s cadence, per-world)
+  // Handler: routes/process-port.mjs → handleListProcesses
   const processesMatch = /^\/api\/worlds\/([^/?#]+)\/processes(\/stream)?\/?$/.exec(url.pathname);
   if (processesMatch && req.method === 'GET') {
     const worldId = decodeURIComponent(processesMatch[1]);
     if (!(worldId in WORLDS)) {
       return jsonReply(res, 404, { error: 'unknown_world', worldId, message: 'world not in registry' });
     }
-    const isStream = processesMatch[2] === '/stream';
-    if (isStream) {
-      subscribeToProcesses(worldId, res);
-      return;
+    return handleListProcesses(req, res, worldId, processesMatch[2] === '/stream');
+  }
+
+  // GET  /api/worlds/:id/servers                   → handleListServers
+  // GET  /api/worlds/:id/server-bridges            → handleServerBridges
+  // POST /api/worlds/:id/server-bridges            → handleServerBridges
+  // DEL  /api/worlds/:id/server-bridges/:port      → handleServerBridges
+  // Handler: routes/process-port.mjs
+  const serversMatch = /^\/api\/worlds\/([^/?#]+)\/servers$/.exec(url.pathname);
+  if (serversMatch && req.method === 'GET') {
+    const worldId = decodeURIComponent(serversMatch[1]);
+    if (!(worldId in WORLDS)) {
+      return jsonReply(res, 404, { error: 'unknown_world', worldId });
+    }
+    return handleListServers(req, res, worldId);
+  }
+
+  const bridgesMatch = /^\/api\/worlds\/([^/?#]+)\/server-bridges(\/(\d+))?\/?$/.exec(url.pathname);
+  if (bridgesMatch) {
+    const worldId = decodeURIComponent(bridgesMatch[1]);
+    const portSegment = bridgesMatch[3] ? parseInt(bridgesMatch[3], 10) : null;
+    if (!(worldId in WORLDS)) {
+      return jsonReply(res, 404, { error: 'unknown_world', worldId });
     }
-    const snapshot = await getProcessSnapshot(worldId);
-    return jsonReply(res, 200, snapshot);
+    return handleServerBridges(req, res, worldId, portSegment);
   }
 
   // GET /api/prs — list recent GitHub PRs for the Cmd+K palette.
@@ -1634,27 +1593,22 @@ const server = http.createServer(async (req, res) => {
       return jsonReply(res, 200, prListCacheEntry.data);
     }
     try {
-      // `gh pr list` infers the target repo from `cwd`'s git origin.
-      // host-cp's process cwd is `/app` (the install dir) — NOT a git
-      // working tree — so without an explicit cwd, gh exits with
-      // `fatal: not a git repository`. Run the command from the
-      // bind-mounted operator repo (`/operator-repo` per compose.yaml).
-      //
-      // Use `||` (not `??`) so empty-string OLAM_REPO_PATH falls back
-      // too. compose.yaml passes through `${OLAM_REPO_PATH:-}` which
-      // injects an empty string into the container env when the operator
-      // hasn't set the var; nullish-coalescing would treat that empty as
-      // present and pass `cwd: ""` (defaults to process.cwd() = /app, no
-      // .git). The original /api/prs cwd fix landed without catching
-      // this — both bug shapes had to be exercised before the gap
-      // surfaced.
-      const operatorRepoPath = process.env.OLAM_REPO_PATH || '/operator-repo';
+      // cwd is REQUIRED — without it gh inherits host-cp's process cwd
+      // (`/app`, the install dir, NOT a git working tree) and exits with
+      // `fatal: not a git repository`. The dashboard's PR filter +
+      // Cmd+K palette then quietly stay empty. Pin to the bind-mounted
+      // operator repo (env-overridable). PR #367 originally added this;
+      // PR #382 accidentally regressed it; api-prs-cwd.test.mjs locks
+      // the contract.
       const { stdout } = await execFileAsync('gh', [
         'pr', 'list',
         '--state', 'all',
         '--limit', '50',
         '--json', 'number,title,state,headRefName',
-      ], { timeout: 10_000, cwd: operatorRepoPath });
+      ], {
+        timeout: 10_000,
+        cwd: process.env.OLAM_REPO_PATH || '/operator-repo',
+      });
       const data = JSON.parse(stdout.trim() || '[]');
       prListCacheEntry = { data, fetchedAt: Date.now() };
       return jsonReply(res, 200, data);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pleri/olam-cli",
-  "version": "0.1.68",
+  "version": "0.1.69",
   "type": "module",
   "bin": {
     "olam": "./bin/olam.cjs"
@@ -28,12 +28,14 @@
     "build": "tsc",
     "dev": "tsx src/index.ts",
     "test": "vitest run --passWithNoTests",
-    "test:ci": "vitest run --reporter=basic --passWithNoTests"
+    "test:ci": "vitest run --reporter=basic --passWithNoTests",
+    "audit:publish-deps": "node scripts/audit-publish-deps.mjs"
   },
   "dependencies": {
     "better-sqlite3": "^12.0.0",
     "commander": "^13.0.0",
     "dockerode": "^4.0.0",
+    "json-source-map": "^0.6.1",
     "ora": "^8.0.0",
     "picocolors": "^1.1.0",
     "ssh2": "^1.16.0",