@pleri/olam-cli 0.1.169 → 0.1.173

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

@@ -68,7 +68,7 @@ const SCOPE_ID_RE = /^[A-Za-z0-9_.-]+$/;
 // /v1/shape. Only these tables have server-side where-rewrite support; any
 // other table=... param gets a 400. Guards against a client enumerating
 // tables the service doesn't own.
-const ALLOWED_SHAPE_TABLES = new Set(['chunks', 'message_usage']);
+const ALLOWED_SHAPE_TABLES = new Set(['chunks', 'message_usage', 'planning_artifacts']);
 
 // B6 (plan-chat-context-window-display Phase B): context-window caps per
 // model. Mirrors CONTEXT_CAPS from @olam/intelligence/src/llm-router/providers/claude.ts.
@@ -399,6 +399,44 @@ export function createHandler({
           }
         }
       }
+      // H2 (plan-chat-spa-canonical-surface Phase G) — extract commit_plan /
+      // propose_plan tool_use chunks into the planning_artifacts mutable
+      // table. The chunk's content carries JSON-stringified {name, input}
+      // per the substrate contract; we parse it once + write a single row.
+      // Failure to extract is logged + swallowed — the chunk itself is
+      // already persisted; artifact row absence is recoverable via
+      // re-extraction from chunks in a follow-up batch job.
+      if (body.chunk_type === 'tool_use') {
+        try {
+          const parsed = JSON.parse(body.chunk);
+          const toolName = typeof parsed?.name === 'string' ? parsed.name : '';
+          const artifactType = (toolName === 'commit_plan' || toolName === 'propose_plan')
+            ? 'commit_plan'
+            : toolName === 'component_scaffold'
+              ? 'component_scaffold'
+              : toolName === 'design_jam'
+                ? 'design_jam'
+                : null;
+          if (artifactType && parsed.input && typeof parsed.input === 'object') {
+            const input = parsed.input;
+            const title = typeof input.title === 'string' && input.title.length > 0
+              ? input.title.slice(0, 200)
+              : `Untitled ${artifactType}`;
+            const artifactId = `${body.message_id}:${body.seq}`;
+            await pool.query(
+              `INSERT INTO planning_artifacts
+                 (id, world_id, session_id, type, title, body)
+               VALUES ($1, $2, $3, $4, $5, $6)
+               ON CONFLICT (id) DO NOTHING`,
+              [artifactId, body.world_id, body.session_id, artifactType, title, input],
+            );
+          }
+        } catch (artifactErr) {
+          console.warn(
+            `[plan-chat-service] planning_artifacts extraction failed for message=${body.message_id} seq=${body.seq}: ${artifactErr?.message ?? artifactErr}`,
+          );
+        }
+      }
     } catch (err) {
       if (err && typeof err === 'object' && 'code' in err && err.code === '23505') {
         return send(res, 409, { error: 'duplicate', message: '(message_id, seq) already exists' });
@@ -634,6 +672,26 @@ export function createHandler({
         createWorld,
         destroyWorld,
       });
+      // H7 (Phase G) — back-fill crystallized_world_id to all planning_artifacts
+      // rows for this session. The status pill state machine (Phase E E4) reads
+      // this field; the editor view + diagrams viewer use it for the
+      // "View world →" CTA. Failure here is logged + swallowed — the
+      // crystallize itself already succeeded; back-fill is a best-effort
+      // sync that an operator can re-run via a CLI helper.
+      if (result.worldId) {
+        try {
+          await pool.query(
+            `UPDATE planning_artifacts
+               SET crystallized_world_id = $1, status = 'crystallized'
+               WHERE session_id = $2 AND status = 'open'`,
+            [result.worldId, body.session_id],
+          );
+        } catch (backfillErr) {
+          console.warn(
+            `[plan-chat-service] crystallize back-fill failed for session=${body.session_id}: ${backfillErr?.message ?? backfillErr}`,
+          );
+        }
+      }
       return send(res, 200, {
         ok: true,
         created_world_id: result.worldId,
@@ -649,6 +707,68 @@ export function createHandler({
     }
   }
 
+  // H4 (Phase G) — GET + PATCH /v1/artifacts/:id endpoint pair backing
+  // the SPA's editor-view round-trip. GET returns the artifact row;
+  // PATCH updates body (the JSON payload) + bumps updated_at via trigger.
+  // SCOPE_ID_RE on :id; bearer auth identical to the chunks endpoints.
+  async function handleGetArtifact(req, res, id) {
+    if (!checkAuth(req)) return unauthorized(res);
+    if (!SCOPE_ID_RE.test(id)) return badRequest(res, 'invalid artifact id');
+    try {
+      const result = await pool.query(
+        `SELECT id, world_id, session_id, type, title, body, status,
+                linear_issue_url, crystallized_world_id,
+                created_at, updated_at
+           FROM planning_artifacts WHERE id = $1`,
+        [id],
+      );
+      const row = result.rows[0];
+      if (!row) return send(res, 404, { error: 'not-found' });
+      return send(res, 200, row);
+    } catch (err) {
+      return send(res, 500, { error: 'query-failed', message: String(err?.message ?? err) });
+    }
+  }
+
+  async function handlePatchArtifact(req, res, id) {
+    if (!checkAuth(req)) return unauthorized(res);
+    if (!SCOPE_ID_RE.test(id)) return badRequest(res, 'invalid artifact id');
+    let body;
+    try {
+      body = await readJson(req);
+    } catch {
+      return badRequest(res, 'malformed JSON body');
+    }
+    const sets = [];
+    const values = [id];
+    if (body.body !== undefined) {
+      values.push(body.body);
+      sets.push(`body = $${values.length}::jsonb`);
+    }
+    if (typeof body.title === 'string') {
+      values.push(body.title.slice(0, 200));
+      sets.push(`title = $${values.length}`);
+    }
+    if (typeof body.status === 'string' && ['open', 'crystallized', 'failed', 'archived'].includes(body.status)) {
+      values.push(body.status);
+      sets.push(`status = $${values.length}`);
+    }
+    if (sets.length === 0) {
+      return badRequest(res, 'no patchable fields supplied (body | title | status)');
+    }
+    try {
+      const result = await pool.query(
+        `UPDATE planning_artifacts SET ${sets.join(', ')} WHERE id = $1 RETURNING *`,
+        values,
+      );
+      const row = result.rows[0];
+      if (!row) return send(res, 404, { error: 'not-found' });
+      return send(res, 200, row);
+    } catch (err) {
+      return send(res, 500, { error: 'update-failed', message: String(err?.message ?? err) });
+    }
+  }
+
   return async function handler(req, res) {
     const url = new URL(req.url ?? '/', `http://${req.headers.host}`);
     if (req.method === 'GET' && url.pathname === '/livez') return send(res, 200, { ok: true });
@@ -656,6 +776,14 @@ export function createHandler({
     if (req.method === 'GET' && url.pathname === '/v1/shape') return handleGetShape(req, res, url);
     if (req.method === 'GET' && url.pathname === '/v1/planning-sessions') return handleGetPlanningSessions(req, res, url);
     if (req.method === 'POST' && url.pathname === '/v1/crystallize') return handlePostCrystallize(req, res);
+    // H4 — /v1/artifacts/:id pair
+    const artifactMatch = /^\/v1\/artifacts\/([^/]+)$/.exec(url.pathname);
+    if (artifactMatch) {
+      const id = decodeURIComponent(artifactMatch[1]);
+      if (req.method === 'GET') return handleGetArtifact(req, res, id);
+      if (req.method === 'PATCH') return handlePatchArtifact(req, res, id);
+      return send(res, 405, { error: 'method-not-allowed' });
+    }
     return send(res, 404, { error: 'not-found' });
   };
 }

package/host-cp/src/pr-nanny.mjs

@@ -13,10 +13,17 @@
  *   2. wall-clock since first dispatch >= MAX_WALL_CLOCK_MIN (default 60)
  *   3. same-root-cause loop detected (last 2 dispatch summaries identical)
  *   4. operator manual pause
+ *
+ * Tier escalation (PR #N tier-escalation):
+ *   On each retry, the nanny advances to the next tier in `escalationTiers`
+ *   (stored per-world in nanny_current_tier) instead of repeating the same
+ *   model. When the chain is exhausted, emits `dispatch.tier-exhausted` on
+ *   the host-stream and falls back to existing operator escalation.
  */
 
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
+import { pickNextTier } from './dispatch/tier-escalator.mjs';
 
 const execFileAsync = promisify(execFile);
 
@@ -68,8 +75,9 @@ function parsePrUrl(prUrl) {
  * @param {{
  *   prStateStore: ReturnType<import('./world-pr-state.mjs').createWorldPrStateStore>,
  *   getGhToken: () => Promise<string|null>,
- *   dispatchToWorld: (worldId: string, prompt: string) => Promise<void>,
+ *   dispatchToWorld: (worldId: string, prompt: string, opts?: { tier?: string }) => Promise<void>,
  *   consultCodex: (ctx: string) => Promise<string>,
+ *   broadcastTierEvent?: (eventType: string, payload: unknown) => void,
  *   pollIntervalMs?: number,
  *   maxDispatches?: number,
  *   maxWallClockMin?: number,
@@ -80,6 +88,7 @@ export function createPrNanny({
   getGhToken,
   dispatchToWorld,
   consultCodex,
+  broadcastTierEvent = () => {},
   pollIntervalMs = 60_000,
   maxDispatches = parseInt(process.env.OLAM_PR_NANNY_MAX_DISPATCHES ?? '5', 10),
   maxWallClockMin = parseInt(process.env.OLAM_PR_NANNY_MAX_WALL_CLOCK_MIN ?? '60', 10),
@@ -198,17 +207,60 @@ export function createPrNanny({
       return;
     }
 
+    // ── Tier escalation (PR #938) ───────────────────────────────────────────
+    //
+    // `nanny_escalation_tiers` is set by the olam_dispatch caller via the
+    // escalationTiers schema field and persisted here by server.mjs when the
+    // world is registered for nanny tracking. Defaults to ['sonnet'] when
+    // absent (no escalation, no cost surprise).
+    //
+    // `nanny_current_tier` tracks the model tier used by the LAST dispatch for
+    // this PR. On first dispatch (dispatchCount === 0) it is undefined, and we
+    // use escalationTiers[0] as the starting tier. On retries we advance the
+    // chain via pickNextTier. This is the pr-state store (option c from the
+    // design doc) — it persists across polls and matches the nanny_* field
+    // pattern already established by nanny_dispatch_count et al.
+    const escalationTiers = entry.nanny_escalation_tiers ?? ['sonnet'];
+    const currentTier = entry.nanny_current_tier ?? escalationTiers[0] ?? 'sonnet';
+    let tierForThisDispatch = currentTier;
+
+    if (dispatchCount > 0) {
+      // This is a retry — try to escalate the tier.
+      const nextTier = pickNextTier(currentTier, escalationTiers);
+      if (nextTier !== null) {
+        tierForThisDispatch = nextTier;
+        broadcastTierEvent('dispatch.escalated', {
+          worldId,
+          fromTier: currentTier,
+          toTier: nextTier,
+          reason: 'retry-after-failure',
+        });
+        console.log(`[pr-nanny] tier escalated for ${worldId}: ${currentTier} → ${nextTier}`);
+      } else {
+        // Chain exhausted — emit tier-exhausted and fall back to operator escalation.
+        broadcastTierEvent('dispatch.tier-exhausted', {
+          worldId,
+          exhaustedTier: currentTier,
+          escalationTiers,
+        });
+        console.log(`[pr-nanny] tier chain exhausted for ${worldId} (last tier: ${currentTier}) — escalating to operator`);
+        prStateStore.set(worldId, { nanny_escalated: true, nanny_escalate_reason: 'tier_exhausted' });
+        return;
+      }
+    }
+
     // Dispatch fix
     try {
-      await dispatchToWorld(worldId, prompt);
+      await dispatchToWorld(worldId, prompt, { tier: tierForThisDispatch });
       const now = new Date().toISOString();
       prStateStore.set(worldId, {
         nanny_dispatch_count: dispatchCount + 1,
         nanny_first_dispatch_at: entry.nanny_first_dispatch_at ?? now,
         nanny_last_dispatch_at: now,
         nanny_last_dispatch_prompt: prompt,
+        nanny_current_tier: tierForThisDispatch,
       });
-      console.log(`[pr-nanny] dispatched fix to ${worldId} (dispatch ${dispatchCount + 1}/${maxDispatches})`);
+      console.log(`[pr-nanny] dispatched fix to ${worldId} (dispatch ${dispatchCount + 1}/${maxDispatches}, tier: ${tierForThisDispatch})`);
     } catch (err) {
       console.error(`[pr-nanny] dispatch failed for ${worldId}: ${err.message}`);
     }

package/host-cp/src/server.mjs

@@ -34,7 +34,19 @@ import { computeProgress } from './world-progress.mjs';
 import { createPrCache } from './pr-cache.mjs';
 import { fetchContainerSecret } from './container-secret-fetcher.mjs';
 import { subscribeDockerEvents } from './docker-events.mjs';
+import {
+  recordWorldLifecycle,
+  emptyEvidence,
+  WorldLifecyclePhase,
+  WorldStartupFailureKind,
+} from '../lifecycle/index.mjs';
 import { createHostStream, newStreamId } from './host-stream.mjs';
+import {
+  createNdjsonSpanSink,
+  attachBetaResponseEvents,
+} from '../observability/ndjson-span-sink.mjs';
+import { betaResponseEmitter } from '@olam/auth-client';
+import { attemptRecovery, findScenarioForKind } from '../recovery/index.mjs';
 import { detectHaltChunk } from './halt-detect.mjs';
 import { spawnUpgraderContainer } from './upgrade-spawner.mjs';
 import { parseProxyPath, perWorldBase, proxyToWorld } from './proxy.mjs';
@@ -74,6 +86,8 @@ import {
   handleServerBridges,
 } from './routes/process-port.mjs';
 import { instrumentHandler, renderMetrics } from './metrics.mjs';
+import { handleDispatchFromEmail } from './lib/email-dispatch.mjs';
+import { emitTierSuggestion } from '../dispatch/auto-tier-scheduler.mjs';
 
 // ── Deployment-mode detection ─────────────────────────────────────
 //
@@ -142,6 +156,20 @@ const OLAM_REPO_HOST_PATH = process.env.OLAM_REPO_HOST_PATH ?? '';
 const OLAM_GH_CONFIG_HOST_PATH = process.env.OLAM_GH_CONFIG_HOST_PATH ?? '';
 const OLAM_UPGRADER_IMAGE = process.env.OLAM_UPGRADER_IMAGE ?? 'ghcr.io/pleri/olam-host-cp:latest';
 const WORKSPACES_DIR = process.env.OLAM_WORKSPACES_DIR ?? '/data/workspaces';
+// Email-trigger surface (PR feat/email-as-world-trigger). The signing
+// secret is the operator-shared key with the CF Email Worker — see
+// docs/architecture/email-as-trigger.md. The allowlist is enforced
+// defense-in-depth: the worker rejects at SMTP-time so bounces reach
+// senders; we re-check at HTTP-time so a misrouted direct POST cannot
+// bypass it. Both empty → endpoint stays mis-configured and returns
+// 500/403 (fail-closed).
+const OLAM_EMAIL_SIGNING_SECRET = process.env.OLAM_EMAIL_SIGNING_SECRET ?? '';
+const OLAM_EMAIL_ALLOWED_SENDERS = process.env.OLAM_EMAIL_ALLOWED_SENDERS ?? '';
+const OLAM_EMAIL_ATTACHMENTS_ROOT =
+  process.env.OLAM_EMAIL_ATTACHMENTS_ROOT ??
+  (HOST_CP_MODE === 'container'
+    ? '/data/email-attachments'
+    : path.join(os.homedir(), '.olam', 'email-attachments'));
 const WORLD_NAMES_PATH =
   process.env.OLAM_WORLD_NAMES_PATH ??
   (HOST_CP_MODE === 'container'
@@ -458,6 +486,29 @@ const sseGate = new SseGate({ maxConcurrent: SSE_CAP });
 // poll-every-2s `useListeningServers` loop.
 const hostStream = createHostStream({ log: (m) => console.log(`[host-stream] ${m}`) });
 
+// Zero-config NDJSON span sink. Subscribes to host-stream `event: span`
+// broadcasts and appends to ~/.olam/logs/host.trace.ndjson (override via
+// OLAM_TRACE_LOG_PATH). Fail-open: a sink-bootstrap error logs a warning
+// and proceeds without tracing rather than blocking host-cp boot.
+const ndjsonSpanSink = await createNdjsonSpanSink({ hostStream }).catch((err) => {
+  console.warn(`[trace] NDJSON span sink unavailable: ${err?.message ?? err}`);
+  return null;
+});
+
+// Wire @olam/auth-client `beta-response` events (Anthropic SDK 0.96+ beta
+// flags — thinking-token-count, cache-diagnostics, future passthrough) into
+// the NDJSON trace as `withCredential.beta-response` spans. Opt-in via the
+// caller's `withCredential('claude', fn, { betas: [...] })` options; when
+// no caller opts in, the emitter never fires and this subscription is a
+// no-op. See docs/decisions/047-anthropic-sdk-beta-flags.md.
+if (ndjsonSpanSink) {
+  try {
+    attachBetaResponseEvents({ sink: ndjsonSpanSink, emitter: betaResponseEmitter });
+  } catch (err) {
+    console.warn(`[trace] beta-response wire unavailable: ${err?.message ?? err}`);
+  }
+}
+
 // A4: coalesce docker-event bursts into a single servers.snapshot. World
 // boot fires `create` + `start` + healthcheck transitions in <100ms; we
 // don't want a broadcast storm. Window matches plan-source.md P3 target.
@@ -485,6 +536,93 @@ const stopEvents = subscribeDockerEvents({
     // this callback is by construction an olam world.
     scheduleServersSnapshot();
   },
+  // Killshot #2 — emit typed world.lifecycle events alongside the cache
+  // invalidate. Docker actions map onto phases as follows:
+  //   start | restart → Spawning   (container boot kicked off)
+  //   stop            → Finished   (clean operator-initiated stop)
+  //   die  | kill     → Failed     (involuntary exit; carries exit code +
+  //                                 classifier-derived failureKind)
+  // The lifecycle module's classifier runs against a synthetic evidence
+  // bundle so the trace records *why* the bucket was chosen. TrustRequired,
+  // ReadyForPrompt, and Running emissions are not observable from
+  // host-cp's docker-events surface — those transitions happen inside
+  // container-cp and are wired in a follow-up (see ADR 033 § Open
+  // questions for the planned container-cp → host-cp emission seam).
+  onWorldLifecycleEvent: ({ worldId, action, exitCode }) => {
+    const now = Date.now();
+    if (action === 'start' || action === 'restart') {
+      recordWorldLifecycle(hostStream, {
+        worldId,
+        phase: WorldLifecyclePhase.Spawning,
+        at: now,
+      });
+      return;
+    }
+    if (action === 'stop') {
+      recordWorldLifecycle(hostStream, {
+        worldId,
+        phase: WorldLifecyclePhase.Finished,
+        at: now,
+      });
+      return;
+    }
+    if (action === 'die' || action === 'kill') {
+      const ev = emptyEvidence(worldId, now);
+      ev.lastPhase = WorldLifecyclePhase.Running;
+      ev.lastPhaseAt = now;
+      if (exitCode !== undefined) ev.processExitCode = exitCode;
+      // For involuntary exit with a code we know the bucket up front;
+      // skip the classifier inference and pass it through explicitly so
+      // the trace records the exact docker-derived signal.
+      const failureKind =
+        exitCode !== undefined ? WorldStartupFailureKind.ProviderProcessGone : undefined;
+      const lifecycleEvent = recordWorldLifecycle(hostStream, {
+        worldId,
+        phase: WorldLifecyclePhase.Failed,
+        at: now,
+        evidence: ev,
+        failureKind,
+      });
+
+
+      // Killshot #3 — bounded auto-recovery. Attempt once per
+      // (worldId, failureKind) pair; the engine enforces idempotency.
+      // Emit recovery.* events on the host-stream so the NDJSON trace
+      // sink captures the full attempt trail.
+      const resolvedKind = lifecycleEvent.failureKind ?? null;
+      const scenario = findScenarioForKind(resolvedKind);
+      if (scenario !== undefined) {
+        hostStream.broadcast('recovery.attempt-started', {
+          worldId,
+          scenario: scenario?.name ?? 'unmatched',
+          recipe: scenario?.recipe ?? null,
+        });
+        attemptRecovery(worldId, ev, resolvedKind)
+          .then((entry) => {
+            if (entry.outcome === 'escalated') {
+              hostStream.broadcast('recovery.escalated', {
+                worldId,
+                ledgerEntry: entry,
+              });
+            } else if (entry.outcome === 'success') {
+              hostStream.broadcast('recovery.attempt-succeeded', {
+                worldId,
+                ledgerEntry: entry,
+              });
+            } else {
+              hostStream.broadcast('recovery.attempt-failed', {
+                worldId,
+                ledgerEntry: entry,
+              });
+            }
+          })
+          .catch((err) => {
+            // Recovery engine always resolves — this path is a safety net.
+            console.error(`[recovery] unexpected engine rejection for ${worldId}: ${err?.message}`);
+          });
+      }
+    }
+  },
 });
 
 // Initial servers.snapshot so subscribers connecting before any docker
@@ -803,6 +941,58 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
     if (handled) return;
   }
 
+  // /api/telemetry/planning-sessions — B9: aggregate planning_sessions by
+  // session_source for the canonical-surface bet's adoption signal. Per
+  // plan-chat-spa-canonical-surface plan § Operator workflow seam falsification
+  // trigger: if plan-chat-spa weekly-active sessions < 60% of control-plane/app
+  // by 2026-Q3, freeze plan-chat-spa feature work. This endpoint is the
+  // data source for that measurement.
+  //
+  // Query param: ?since=YYYY-MM-DD (required; rejects with 400 otherwise).
+  // Response: { plan_chat_spa: N, control_plane_app: M, unknown: K, ratio: pct }
+  // where ratio = plan_chat_spa / (plan_chat_spa + control_plane_app) * 100,
+  // null if denominator is 0.
+  if (url.pathname === '/api/telemetry/planning-sessions' && req.method === 'GET') {
+    const since = url.searchParams.get('since');
+    if (!since || !/^\d{4}-\d{2}-\d{2}$/.test(since)) {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      return res.end(JSON.stringify({
+        error: 'bad_request',
+        message: 'Missing or malformed `since` query param. Expected YYYY-MM-DD.',
+      }));
+    }
+    // B9 ships the endpoint CONTRACT + the session_source schema column.
+    // The query implementation goes through plan-chat-service.mjs (which
+    // owns the pg pool); this host-cp handler currently emits a 503 with
+    // a structured "not_implemented" marker so callers can verify the
+    // endpoint shape + auth + query-param parsing without the data path.
+    //
+    // Phase G of this epic adds the plan-chat-service handler that this
+    // endpoint will proxy to. Until then operators can run the SQL
+    // directly:
+    //   SELECT COALESCE(session_source, 'unknown'), COUNT(*)
+    //   FROM planning_sessions
+    //   WHERE created_at >= $since
+    //   GROUP BY 1;
+    //
+    // Notify-C: ship contract + schema; defer data path to Phase G.
+    res.writeHead(503, { 'Content-Type': 'application/json' });
+    return res.end(JSON.stringify({
+      error: 'not_implemented',
+      message: 'B9 ships the endpoint contract + session_source schema column. ' +
+        'Aggregation handler scaffolded in plan-chat-service.mjs lands in Phase G.',
+      since,
+      contractShape: {
+        plan_chat_spa: 0,
+        control_plane_app: 0,
+        unknown: 0,
+        ratio: null,
+        since: '<YYYY-MM-DD>',
+        asOf: '<ISO 8601>',
+      },
+    }));
+  }
+
   // /api/version/status: returns the current version snapshot (baked SHA
   // vs operator's local HEAD). No auth required beyond the existing gate
   // (already applied above). Phase 1 only — detection, no auto-upgrade.
@@ -2070,6 +2260,76 @@ const server = http.createServer(instrumentHandler('host-cp', async (req, res) =
   //     B5's CLI uses).
   // When unset, returns 503 with a clear setup hint instead of failing
   // silently — operators wire when they're ready for cloud-mode dogfood.
+  // POST /v1/dispatch-from-email — see docs/architecture/email-as-trigger.md.
+  //
+  // The CF Email Worker (packages/email-worker-cloudflare) HMAC-signs the
+  // canonical payload (Decision 022) and POSTs it here. The host re-validates
+  // the signature, re-checks the sender allowlist (defense in depth), persists
+  // attachments under OLAM_EMAIL_ATTACHMENTS_ROOT/<worldId>/<timestampMs>/,
+  // and either routes the dispatch to a known world or persists a
+  // spawn-pending request for the MCP/CLI layer to drain.
+  //
+  // The body cap here is 30 MiB — 25 MiB attachment ceiling + 5 MiB margin
+  // for the JSON envelope. Larger payloads are rejected at 413.
+  if (url.pathname === '/v1/dispatch-from-email' && req.method === 'POST') {
+    const chunks = [];
+    let size = 0;
+    const MAX_BODY = 30 * 1024 * 1024;
+    let aborted = false;
+    req.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > MAX_BODY) {
+        aborted = true;
+        jsonReply(res, 413, { error: 'body_too_large', maxBytes: MAX_BODY });
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', async () => {
+      if (aborted) return;
+      let dispatch;
+      try {
+        dispatch = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+      } catch (err) {
+        return jsonReply(res, 400, { error: 'invalid_json', message: err.message });
+      }
+      try {
+        // Auto-tier-scheduler v1 (ADR 042): emit an informational
+        // `dispatch.tier-suggestion` event BEFORE handing off to the
+        // dispatch handler. Pure-informational — never changes which
+        // provider actually runs. The dispatch payload's optional
+        // `tierSpec` ({ kind?, expectedDurationMs?, explicitTier? })
+        // carries the shape; absent it, the heuristic falls through to
+        // its default (`cloudflare-sandbox`).
+        if (dispatch && typeof dispatch.worldId === 'string') {
+          try {
+            emitTierSuggestion({
+              worldId: dispatch.worldId,
+              dispatchSpec: dispatch.tierSpec ?? {},
+              currentTier: null,
+              hostStream,
+            });
+          } catch { /* never let a hint surface break dispatch */ }
+        }
+        const result = await handleDispatchFromEmail({
+          dispatch,
+          worlds: WORLDS,
+          secret: OLAM_EMAIL_SIGNING_SECRET,
+          attachmentsRoot: OLAM_EMAIL_ATTACHMENTS_ROOT,
+          allowlist: OLAM_EMAIL_ALLOWED_SENDERS,
+        });
+        return jsonReply(res, result.status, result.body);
+      } catch (err) {
+        return jsonReply(res, 500, {
+          error: 'dispatch_failed',
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+    });
+    return;
+  }
+
   if (url.pathname === '/api/cloud-dispatch' && req.method === 'POST') {
     const cloudUrl = process.env.OLAM_CLOUD_URL;
     const showcasePw = process.env.OLAM_SHOWCASE_PASSWORD;
@@ -3078,6 +3338,7 @@ for (const sig of ['SIGTERM', 'SIGINT']) {
     stopListeningSnapshotLoop();
     if (serversSnapshotTimer) { clearTimeout(serversSnapshotTimer); serversSnapshotTimer = null; }
     hostStream.close();
+    if (ndjsonSpanSink) ndjsonSpanSink.close().catch(() => {});
     clearInterval(versionPollTimer);
     cache.clear();
     server.close(() => process.exit(0));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pleri/olam-cli",
-  "version": "0.1.169",
+  "version": "0.1.173",
   "type": "module",
   "bin": {
     "olam": "./bin/olam.cjs"