@pleri/olam-cli 0.1.147 → 0.1.150

package/host-cp/src/plan-chat-service.mjs

@@ -22,18 +22,21 @@
 // Configuration is environment-driven so a single binary works in laptop
 // (the K3 container-spike), in a devbox container, and on a host-cp Mac:
 //
-//   OLAM_PLAN_CHAT_PORT          (default 3112)
+//   OLAM_PLAN_CHAT_PORT          (default 3200; moved off 3112 — see
+//                                 olam-chunks-subscriber-long-poll Phase A.
+//                                 agentmemory iii/node claim 3111-3113.)
 //   OLAM_PLAN_CHAT_DATABASE_URL  (default postgres://postgres:spike@localhost:54321/chunks)
 //   OLAM_PLAN_CHAT_ELECTRIC_URL  (default http://localhost:30001)
 //   OLAM_PLAN_CHAT_SECRET_PATH   (default ~/.olam/plan-chat-secret)
 
 import http from 'node:http';
+import { performance } from 'node:perf_hooks';
 import { Readable } from 'node:stream';
 import { URL } from 'node:url';
 import pg from 'pg';
 import { ensureSecret, timingSafeEqual, SECRET_PATH } from './plan-chat-secret.mjs';
 
-const DEFAULT_PORT = 3112;
+const DEFAULT_PORT = 3200;
 const DEFAULT_DB_URL = 'postgres://postgres:spike@localhost:54321/chunks';
 const DEFAULT_ELECTRIC_URL = 'http://localhost:30001';
 
@@ -176,13 +179,36 @@ function validateChunkInput(body) {
 /**
  * Build the HTTP request handler. Pure factory — easy to test against a
  * stubbed pool. Production callers pass a real pg.Pool.
+ *
+ * Phase A A2 (olam-spa-electric-subscription-staleness): when `shapeDebug`
+ * is true OR `OLAM_PLAN_CHAT_SHAPE_DEBUG=1` is set in the environment,
+ * `handleGetShape` emits two structured log lines per long-poll cycle —
+ * one BEFORE the upstream fetch (with the rewritten `where` predicate +
+ * forwarded params) and one AFTER (with upstream status + electric-*
+ * response headers). Log lines go to `shapeDebugLog` (default
+ * `console.error`); tests inject a spy. Flag defaults OFF — production
+ * shapes incur a single boolean check per cycle and zero log I/O.
  */
-export function createHandler({ pool, bearer, electricUrl }) {
+export function createHandler({
+  pool,
+  bearer,
+  electricUrl,
+  shapeDebug,
+  shapeDebugLog,
+}) {
   if (!pool) throw new Error('createHandler: { pool } required');
   if (typeof bearer !== 'string' || bearer.length === 0) {
     throw new Error('createHandler: { bearer } required');
   }
   const electricBase = electricUrl ?? DEFAULT_ELECTRIC_URL;
+  const shapeDebugEnabled =
+    typeof shapeDebug === 'boolean'
+      ? shapeDebug
+      : process.env.OLAM_PLAN_CHAT_SHAPE_DEBUG === '1';
+  const shapeLog =
+    typeof shapeDebugLog === 'function'
+      ? shapeDebugLog
+      : (msg, details) => console.error(msg, details);
 
   function checkAuth(req) {
     const header = req.headers.authorization;
@@ -280,29 +306,76 @@ export function createHandler({ pool, bearer, electricUrl }) {
       `session_id='${sessionId}' AND world_id='${worldId}'`,
     );
 
+    // Phase A A2 — log BEFORE upstream fetch. Includes the rewritten
+    // `where` predicate so an operator can correlate client-supplied
+    // offset/handle with the server-derived scope. Cheap when off: one
+    // boolean check.
+    if (shapeDebugEnabled) {
+      shapeLog('[plan-chat-service:shape] → upstream', {
+        upstream: upstream.pathname + upstream.search,
+        offset: url.searchParams.get('offset'),
+        handle: url.searchParams.get('handle'),
+        live: url.searchParams.get('live'),
+        where: upstream.searchParams.get('where'),
+      });
+    }
+
     let upstreamRes;
+    const upstreamStartedAt = shapeDebugEnabled ? performance.now() : 0;
     try {
       upstreamRes = await fetch(upstream, {
         method: 'GET',
         headers: { accept: 'application/json' },
       });
     } catch (err) {
+      if (shapeDebugEnabled) {
+        shapeLog('[plan-chat-service:shape] ✖ upstream-error', {
+          upstream: upstream.pathname + upstream.search,
+          err: String(err?.message ?? err),
+        });
+      }
       return send(res, 502, {
         error: 'shape-upstream-unreachable',
         message: String(err?.message ?? err),
       });
     }
 
-    // Forward upstream electric-* headers BEFORE the stream starts. Once
-    // res.writeHead fires, headers are locked.
-    for (const header of [
-      'electric-handle',
-      'electric-offset',
-      'electric-up-to-date',
-      'electric-schema',
-    ]) {
-      const value = upstreamRes.headers.get(header);
-      if (value) res.setHeader(header, value);
+    // Phase A A2 — log AFTER upstream returns headers but BEFORE
+    // `res.writeHead` fires (Seam: must not touch the body stream;
+    // logging post-pipe risks hanging the response on a sync exception
+    // in the logger). Captures the electric-* response headers to
+    // disambiguate offset-cursor staleness from handle eviction.
+    if (shapeDebugEnabled) {
+      const elapsedMs = Math.round(performance.now() - upstreamStartedAt);
+      shapeLog(
+        `[plan-chat-service:shape] ← upstream ${upstreamRes.status} ${elapsedMs}ms`,
+        {
+          resHandle: upstreamRes.headers.get('electric-handle'),
+          resOffset: upstreamRes.headers.get('electric-offset'),
+          resUpToDate: upstreamRes.headers.get('electric-up-to-date'),
+          resSchema: upstreamRes.headers.get('electric-schema'),
+        },
+      );
+    }
+
+    // Forward every upstream `electric-*` header BEFORE the stream starts.
+    // Once `res.writeHead` fires, headers are locked.
+    //
+    // Phase B B4 (olam-spa-electric-subscription-staleness) — prefix-match
+    // the entire `electric-*` namespace upstream owns instead of a static
+    // four-header whitelist. ElectricSQL 1.6.3 added `electric-cursor` to
+    // the live-mode response contract; the old whitelist dropped it; the
+    // SPA's TanStack Electric collection raised `MissingHeadersError` and
+    // stopped processing the long-poll stream. Mirror-all-electric closes
+    // the class — any future header upstream adds inside this namespace
+    // flows through with zero proxy changes. See plan
+    // `~/.claude/plans/olam-spa-electric-subscription-staleness.md` § Phase B
+    // and Phase A A3 evidence at
+    // `docs/screenshots/olam-spa-electric-subscription-staleness/a3-evidence-2026-05-18/`.
+    for (const [header, value] of upstreamRes.headers) {
+      if (header.toLowerCase().startsWith('electric-')) {
+        res.setHeader(header, value);
+      }
     }
     const upstreamContentType = upstreamRes.headers.get('content-type');
     if (upstreamContentType) res.setHeader('content-type', upstreamContentType);
@@ -360,11 +433,22 @@ export async function startService(opts = {}) {
     opts.databaseUrl ?? process.env.OLAM_PLAN_CHAT_DATABASE_URL ?? DEFAULT_DB_URL;
   const electricUrl =
     opts.electricUrl ?? process.env.OLAM_PLAN_CHAT_ELECTRIC_URL ?? DEFAULT_ELECTRIC_URL;
+  // Layered defense: SECRET_PATH (imported above) is itself env-aware at
+  // module load. Reading OLAM_PLAN_CHAT_SECRET_PATH here too lets explicit
+  // opts.secretPath callers and env-changes-since-import still win. Do not
+  // collapse either layer — direct callers in server.mjs (readPlanChatSecret
+  // with no arg) rely on the module-const path being env-aware.
   const secretPath = opts.secretPath ?? process.env.OLAM_PLAN_CHAT_SECRET_PATH ?? SECRET_PATH;
   const bearer = opts.bearer ?? ensureSecret(secretPath);
 
   const pool = opts.pool ?? new pg.Pool({ connectionString: databaseUrl, max: 8 });
-  const handler = createHandler({ pool, bearer, electricUrl });
+  const handler = createHandler({
+    pool,
+    bearer,
+    electricUrl,
+    shapeDebug: opts.shapeDebug,
+    shapeDebugLog: opts.shapeDebugLog,
+  });
   const server = http.createServer((req, res) => {
     handler(req, res).catch((err) => {
       try {
@@ -374,7 +458,24 @@ export async function startService(opts = {}) {
   });
 
   await new Promise((resolve, reject) => {
-    server.once('error', reject);
+    server.once('error', (err) => {
+      if (err && err.code === 'EADDRINUSE') {
+        // A3 — port-collision diagnostic. Prevents silent half-start when the
+        // target port is held by another process. agentmemory's `iii` has
+        // historically claimed 3111-3113 (motivated the 3112 → 3200 move in
+        // olam-chunks-subscriber-long-poll Phase A); flag it so the next
+        // collision is debuggable in one log line, not three rounds of grep.
+        // eslint-disable-next-line no-console
+        console.error(`[plan-chat-service] EADDRINUSE on :${port} — port already in use.`);
+        // eslint-disable-next-line no-console
+        console.error(`[plan-chat-service]   Check:  lsof -i:${port}`);
+        // eslint-disable-next-line no-console
+        console.error(`[plan-chat-service]   Note:   agentmemory's iii claims 3111-3113 (motivated 3112 → 3200 move).`);
+        // eslint-disable-next-line no-console
+        console.error(`[plan-chat-service]   Override: OLAM_PLAN_CHAT_PORT=<free-port>`);
+      }
+      reject(err);
+    });
     server.listen(port, () => resolve(undefined));
   });
 

package/host-cp/src/server.mjs

@@ -95,14 +95,26 @@ const WORLD_HOST = HOST_CP_MODE === 'container' ? 'host.docker.internal' : '127.
 const HOST_CP_ENGINE = resolveHostCpEngine();
 
 const PORT = parseInt(process.env.OLAM_HOST_CP_PORT ?? '19000', 10);
-// In container mode the host-cp talks to the docker daemon via the
-// socket-proxy sidecar (the proxy enforces the read-only API allow-list).
-// In bare-node mode there's no socket-proxy on the host; we shell out to
-// `docker exec` directly via child_process. The sentinel `docker-cli`
-// triggers that path in fetchContainerSecret. (B5 below; closes the
-// secret_fetch_failed bare-node bug class — see ~/.claude/plans/bare-node-mode-safeguards.md.)
+// D1 (Phase 2 Phase D) — substrate-conditional docker socket transport.
+//
+// Compose substrate (HOST_CP_ENGINE === 'docker', container mode):
+//   tcp://docker-socket-proxy:2375 — the compose sidecar enforces the
+//   read-only API allow-list. Zero behavior change from pre-D1.
+//
+// Kubernetes substrate (HOST_CP_ENGINE === 'kubernetes'):
+//   unix:///var/run/docker.sock — direct hostPath bind-mount per Decision #3
+//   (architecture a2). The init container (socket-perm) chmods the socket
+//   to 666 before the main container starts (Decision #15).
+//
+// Bare-node mode (HOST_CP_MODE !== 'container'):
+//   'docker-cli' — sentinel that triggers docker-exec path in
+//   fetchContainerSecret (bare-node safeguard, unchanged).
 const DOCKER_HOST = process.env.DOCKER_HOST
-  ?? (HOST_CP_MODE === 'container' ? 'tcp://docker-socket-proxy:2375' : 'docker-cli');
+  ?? (HOST_CP_MODE !== 'container'
+    ? 'docker-cli'
+    : HOST_CP_ENGINE === 'kubernetes'
+      ? 'unix:///var/run/docker.sock'
+      : 'tcp://docker-socket-proxy:2375');
 const TTL_SEC = parseInt(process.env.OLAM_SECRET_CACHE_TTL_SEC ?? '300', 10);
 const HOST_FOR_WORLD = process.env.OLAM_HOST_FOR_WORLD ?? WORLD_HOST;
 const TOKEN_PATH = process.env.OLAM_HOST_CP_TOKEN_PATH ?? '/data/host-cp.token';
@@ -1921,7 +1933,7 @@ const server = http.createServer(async (req, res) => {
     // the host-cp service name. Default: host.docker.internal for the
     // operator-local demo flow.
     const hostCpUrlForContainer =
-      process.env.OLAM_AGENT_RUNTIME_HOST_CP_URL ?? 'http://host.docker.internal:3112';
+      process.env.OLAM_AGENT_RUNTIME_HOST_CP_URL ?? 'http://host.docker.internal:3200';
     try {
       const result = await triggerAgentRuntime({
         worldId: body.worldId,
@@ -1940,7 +1952,7 @@ const server = http.createServer(async (req, res) => {
   }
 
   // /api/plan-chat/* — passthrough proxy to plan-chat-service.
-  // The sidecar runs on PLAN_CHAT_SERVICE_URL (default http://127.0.0.1:3112).
+  // The sidecar runs on PLAN_CHAT_SERVICE_URL (default http://127.0.0.1:3200).
   // Strips the /api/plan-chat prefix; forwards method, headers, body, and
   // query verbatim. Streams the response (Electric SQL long-poll friendly).
   // Auth: client supplies Bearer; we don't add or strip it.
@@ -1950,8 +1962,8 @@ const server = http.createServer(async (req, res) => {
       // Default depends on where host-cp runs. In-container = host.docker.internal;
       // bare-node = 127.0.0.1. DOCKER_HOST=tcp://* implies container mode.
       ((process.env.DOCKER_HOST ?? '').startsWith('tcp://')
-        ? 'http://host.docker.internal:3112'
-        : 'http://127.0.0.1:3112');
+        ? 'http://host.docker.internal:3200'
+        : 'http://127.0.0.1:3200');
     const subPath = url.pathname === '/api/plan-chat'
       ? '/'
       : url.pathname.slice('/api/plan-chat'.length);

package/host-cp/src/upgrade-spawner.mjs

@@ -145,13 +145,18 @@ export async function spawnUpgraderContainer({
   }
 
   // Bare-node (operator's host docker CLI on PATH) is documented but
-  // out of scope for the trigger feature — single deployment shape
-  // (compose stack) is supported in Phase 1.
+  // out of scope for the trigger feature — container + unix-socket paths
+  // are supported (compose stack and k8s hostPath socket mount).
   if (dockerHost === 'docker-cli') {
-    // The literal `docker-socket-proxy` below is diagnostic text naming
-    // the deployment shape that IS supported, not a hostname.
+    // The literals below (`unix:///var/run/docker.sock` and `tcp://docker-socket-proxy:2375`)
+    // are diagnostic text naming the deployment shapes that ARE supported,
+    // not hostnames being used as transport — error-message-only.
     throw new Error(
-      'upgrade-trigger requires the docker-socket-proxy deployment shape; bare-node not yet supported', // bare-node-allow: diagnostic-text
+      'upgrade-trigger requires a docker socket (unix:///var/run/docker.sock via k8s hostPath mount, ' + // bare-node-allow: diagnostic-text
+      'or tcp://docker-socket-proxy:2375 via compose); bare-node not yet supported. ' + // bare-node-allow: diagnostic-text
+      'For k8s: ensure the cluster was created with ' +
+      '--volume /var/run/docker.sock:/var/run/docker.sock@server:* ' +
+      'and olam doctor reports probeDockerSocketBindMount [PASS].',
     );
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pleri/olam-cli",
-  "version": "0.1.147",
+  "version": "0.1.150",
   "type": "module",
   "bin": {
     "olam": "./bin/olam.cjs"
@@ -32,7 +32,8 @@
     "test:ci": "vitest run --reporter=basic --passWithNoTests",
     "test:docker": "vitest run --config vitest.config.docker.ts",
     "audit:publish-deps": "node scripts/audit-publish-deps.mjs",
-    "audit:cli-bundle-k8s": "node scripts/audit-cli-bundle-k8s.mjs"
+    "audit:cli-bundle-k8s": "node scripts/audit-cli-bundle-k8s.mjs",
+    "audit:cli-package-contents": "node scripts/audit-cli-package-contents.mjs"
   },
   "dependencies": {
     "better-sqlite3": "^12.0.0",
@@ -43,6 +44,7 @@
     "picocolors": "^1.1.0",
     "ssh2": "^1.16.0",
     "yaml": "^2.7.0",
+    "@inquirer/prompts": "^7.0.0",
     "zod-to-json-schema": "^3.24.0",
     "playwright-core": "~1.59.0",
     "@napi-rs/keyring": "^1.1.6",