@pleri/olam-cli 0.1.168 → 0.1.170

package/dist/spawn/home-override.d.ts

@@ -0,0 +1,82 @@
+/**
+ * --claude-home — per-world Claude Code instance isolation.
+ *
+ * Today, every world inherits the operator's single `~/.claude/` (host login,
+ * settings, hooks, MCP topology, 429 bucket). When the operator wants to run
+ * one world against their personal Anthropic account and another against
+ * their work account on the same host, they have no clean seam — both worlds
+ * share `~/.claude/.credentials.json` and the same 429 cooldown.
+ *
+ * Inspired by t3code (pingdotgg/t3code) — one server process hosts N Claude
+ * Code instances, each with its own `HOME` env var pointing at a separate
+ * `~/.claude.instance-N` directory. Zero containers, zero processes-per-
+ * account, just `env: { HOME: '...' }` on the spawn.
+ *
+ * This module exports two pure helpers used by `olam create --claude-home`:
+ *
+ *   - {@link resolveClaudeHome} — pick the directory to use as HOME for the
+ *     world's Claude Code config snapshot. Precedence:
+ *       1. Explicit `--claude-home <id-or-path>` flag.
+ *       2. Stored claudeHome from a prior `olam create` (re-runs of
+ *          `olam enter <worldId>` honour the original choice).
+ *       3. Operator's default `$HOME` (legacy behaviour — no behavioural
+ *          change for worlds created without the flag).
+ *
+ *   - {@link ensureClaudeHomeDir} — `mkdir -p` the target dir and write a
+ *     `.olam-claude-home` sentinel so first-use detection works.
+ *
+ * Composes with @olam/auth-client's vault: the vault still rotates
+ * credentials WITHIN a HOME; `--claude-home` isolates DIFFERENT HOMEs from
+ * each other.
+ *
+ * See `docs/decisions/045-claude-home-override.md` for the full rationale
+ * + operator workflow.
+ */
+/** Relative path under `$HOME` where bare-id homes are materialised. */
+export declare const CLAUDE_HOMES_BASE: string;
+/** First-use sentinel filename — written into a freshly-created home. */
+export declare const SENTINEL_FILENAME = ".olam-claude-home";
+/**
+ * Allowed shape of a bare `--claude-home <id>` argument.
+ *
+ * Same shape rule as world ids and skill prefixes: a leading lowercase-or-
+ * digit char, then 0–63 more of `[a-z0-9_-]`. Rejects `..`, spaces,
+ * absolute-path injections, uppercase. Absolute paths are handled
+ * separately (see {@link resolveClaudeHome}) — they don't go through this
+ * regex.
+ */
+export declare const HOME_ID_RE: RegExp;
+export interface ResolveClaudeHomeArgs {
+    /** `--claude-home <id-or-path>` flag value from CLI parse. Optional. */
+    readonly flag?: string;
+    /**
+     * Prior `claudeHome` stored on the world's metadata. When set and the
+     * caller didn't pass `flag`, this wins over the operator's `$HOME`.
+     */
+    readonly existingWorldConfig?: {
+        readonly claudeHome?: string;
+    };
+    /** Test hook — defaults to `os.homedir()`. */
+    readonly homeDir?: string;
+    /** Test hook — defaults to `process.env.HOME ?? os.homedir()`. */
+    readonly envHome?: string;
+}
+/**
+ * Resolve the absolute filesystem path to use as the world's Claude Code
+ * HOME. Pure function — no IO, no env reads beyond the injected hooks.
+ *
+ * @throws Error if `flag` (or `existingWorldConfig.claudeHome`) is a
+ *   relative path that doesn't match {@link HOME_ID_RE}.
+ */
+export declare function resolveClaudeHome(args: ResolveClaudeHomeArgs): string;
+/**
+ * Ensure the resolved Claude home directory exists and carries the
+ * `.olam-claude-home` sentinel. Idempotent — re-running on an existing
+ * home leaves the sentinel byte-identical (so `olam enter` re-runs don't
+ * mutate the home's mtime gratuitously).
+ *
+ * Does NOT seed credentials, settings, or MCP config — that's the
+ * operator's job (one-time `HOME=<resolved-path> claude login`).
+ */
+export declare function ensureClaudeHomeDir(targetPath: string): Promise<void>;
+//# sourceMappingURL=home-override.d.ts.map

package/dist/spawn/home-override.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"home-override.d.ts","sourceRoot":"","sources":["../../src/spawn/home-override.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAMH,wEAAwE;AACxE,eAAO,MAAM,iBAAiB,QAAqC,CAAC;AAEpE,yEAAyE;AACzE,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AAErD;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,QAA+B,CAAC;AAEvD,MAAM,WAAW,qBAAqB;IACpC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE;QAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAChE,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,qBAAqB,GAAG,MAAM,CAerE;AAiBD;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB3E"}

package/dist/spawn/home-override.js

@@ -0,0 +1,107 @@
+/**
+ * --claude-home — per-world Claude Code instance isolation.
+ *
+ * Today, every world inherits the operator's single `~/.claude/` (host login,
+ * settings, hooks, MCP topology, 429 bucket). When the operator wants to run
+ * one world against their personal Anthropic account and another against
+ * their work account on the same host, they have no clean seam — both worlds
+ * share `~/.claude/.credentials.json` and the same 429 cooldown.
+ *
+ * Inspired by t3code (pingdotgg/t3code) — one server process hosts N Claude
+ * Code instances, each with its own `HOME` env var pointing at a separate
+ * `~/.claude.instance-N` directory. Zero containers, zero processes-per-
+ * account, just `env: { HOME: '...' }` on the spawn.
+ *
+ * This module exports two pure helpers used by `olam create --claude-home`:
+ *
+ *   - {@link resolveClaudeHome} — pick the directory to use as HOME for the
+ *     world's Claude Code config snapshot. Precedence:
+ *       1. Explicit `--claude-home <id-or-path>` flag.
+ *       2. Stored claudeHome from a prior `olam create` (re-runs of
+ *          `olam enter <worldId>` honour the original choice).
+ *       3. Operator's default `$HOME` (legacy behaviour — no behavioural
+ *          change for worlds created without the flag).
+ *
+ *   - {@link ensureClaudeHomeDir} — `mkdir -p` the target dir and write a
+ *     `.olam-claude-home` sentinel so first-use detection works.
+ *
+ * Composes with @olam/auth-client's vault: the vault still rotates
+ * credentials WITHIN a HOME; `--claude-home` isolates DIFFERENT HOMEs from
+ * each other.
+ *
+ * See `docs/decisions/045-claude-home-override.md` for the full rationale
+ * + operator workflow.
+ */
+import { mkdir, writeFile, access } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+/** Relative path under `$HOME` where bare-id homes are materialised. */
+export const CLAUDE_HOMES_BASE = path.join('.olam', 'claude-homes');
+/** First-use sentinel filename — written into a freshly-created home. */
+export const SENTINEL_FILENAME = '.olam-claude-home';
+/**
+ * Allowed shape of a bare `--claude-home <id>` argument.
+ *
+ * Same shape rule as world ids and skill prefixes: a leading lowercase-or-
+ * digit char, then 0–63 more of `[a-z0-9_-]`. Rejects `..`, spaces,
+ * absolute-path injections, uppercase. Absolute paths are handled
+ * separately (see {@link resolveClaudeHome}) — they don't go through this
+ * regex.
+ */
+export const HOME_ID_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+/**
+ * Resolve the absolute filesystem path to use as the world's Claude Code
+ * HOME. Pure function — no IO, no env reads beyond the injected hooks.
+ *
+ * @throws Error if `flag` (or `existingWorldConfig.claudeHome`) is a
+ *   relative path that doesn't match {@link HOME_ID_RE}.
+ */
+export function resolveClaudeHome(args) {
+    const home = args.homeDir ?? homedir();
+    if (args.flag !== undefined && args.flag.length > 0) {
+        return resolveSpec(args.flag, home);
+    }
+    const stored = args.existingWorldConfig?.claudeHome;
+    if (stored !== undefined && stored.length > 0) {
+        return resolveSpec(stored, home);
+    }
+    // Default — legacy behaviour. Operator's $HOME, with same fallback as
+    // node's stdlib (HOME env → os.homedir()).
+    return args.envHome ?? home;
+}
+function resolveSpec(spec, home) {
+    if (path.isAbsolute(spec)) {
+        return spec;
+    }
+    if (!HOME_ID_RE.test(spec)) {
+        throw new Error(`--claude-home value "${spec}" must be either an absolute path ` +
+            `or a bare id matching ${HOME_ID_RE} (alphanumeric, underscore, dash; ` +
+            `starts with alphanumeric; max 64 chars). Rejected: relative paths, ` +
+            `parent refs, uppercase, whitespace.`);
+    }
+    return path.join(home, CLAUDE_HOMES_BASE, spec);
+}
+/**
+ * Ensure the resolved Claude home directory exists and carries the
+ * `.olam-claude-home` sentinel. Idempotent — re-running on an existing
+ * home leaves the sentinel byte-identical (so `olam enter` re-runs don't
+ * mutate the home's mtime gratuitously).
+ *
+ * Does NOT seed credentials, settings, or MCP config — that's the
+ * operator's job (one-time `HOME=<resolved-path> claude login`).
+ */
+export async function ensureClaudeHomeDir(targetPath) {
+    await mkdir(targetPath, { recursive: true });
+    const sentinelPath = path.join(targetPath, SENTINEL_FILENAME);
+    try {
+        await access(sentinelPath);
+        // Sentinel exists — leave it alone (idempotency).
+        return;
+    }
+    catch {
+        // Sentinel absent → write it.
+    }
+    await writeFile(sentinelPath, '# olam claude-home — managed by `olam create --claude-home`.\n' +
+        '# Do not delete. Re-create by running `olam create --claude-home <id>` again.\n', 'utf-8');
+}
+//# sourceMappingURL=home-override.js.map

package/dist/spawn/home-override.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"home-override.js","sourceRoot":"","sources":["../../src/spawn/home-override.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,wEAAwE;AACxE,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;AAEpE,yEAAyE;AACzE,MAAM,CAAC,MAAM,iBAAiB,GAAG,mBAAmB,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,4BAA4B,CAAC;AAgBvD;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAA2B;IAC3D,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,IAAI,OAAO,EAAE,CAAC;IAEvC,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpD,OAAO,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,mBAAmB,EAAE,UAAU,CAAC;IACpD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9C,OAAO,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC;IAED,sEAAsE;IACtE,2CAA2C;IAC3C,OAAO,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC;AAC9B,CAAC;AAED,SAAS,WAAW,CAAC,IAAY,EAAE,IAAY;IAC7C,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,wBAAwB,IAAI,oCAAoC;YAC9D,yBAAyB,UAAU,oCAAoC;YACvE,qEAAqE;YACrE,qCAAqC,CACxC,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,iBAAiB,EAAE,IAAI,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,UAAkB;IAC1D,MAAM,KAAK,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC;IAC9D,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,YAAY,CAAC,CAAC;QAC3B,kDAAkD;QAClD,OAAO;IACT,CAAC;IAAC,MAAM,CAAC;QACP,8BAA8B;IAChC,CAAC;IACD,MAAM,SAAS,CACb,YAAY,EACZ,gEAAgE;QAC9D,iFAAiF,EACnF,OAAO,CACR,CAAC;AACJ,CAAC"}

package/hermes-bundle/version.json

@@ -1,4 +1,4 @@
 {
-  "bundledAt": "2026-05-23T09:39:55.721Z",
+  "bundledAt": "2026-05-24T03:12:41.846Z",
   "kgFirstSha": "29a9ccce1b115d049e375c4a90eb5cf7c123e610e2d0590270a4db2cdbc64a28"
 }

package/host-cp/k8s/manifests/30-configmap.yaml

@@ -30,6 +30,11 @@ data:
   # the env override is mandatory here, not optional. Bind-mounted /data
   # is the writable PVC.
   OLAM_PLAN_CHAT_SECRET_PATH: "/data/plan-chat-secret"
+  # NDJSON span sink + recovery ledger — route to the writable PVC mount at
+  # /data rather than the default ~/.olam/logs (which resolves to
+  # /home/node/.olam/logs and is not writable with readOnlyRootFilesystem: true).
+  OLAM_TRACE_LOG_PATH: "/data/logs/host.trace.ndjson"
+  OLAM_RECOVERY_LEDGER_PATH: "/data/logs/recovery-ledger.ndjson"
   # Tunable defaults.
   OLAM_SECRET_CACHE_TTL_SEC: "300"
   OLAM_PR_POLL_INTERVAL_MS: "300000"

package/host-cp/k8s/manifests/50-deployment.yaml

@@ -1,7 +1,14 @@
 # Deployment for olam-host-cp.
 #
 # Image: pinned to sha256 digest (not :latest or named tag) per T4 threat model.
-# Digest resolves to ghcr.io/pleri/olam-host-cp:0.1.143 (multi-arch index).
+# Digest resolves to ghcr.io/pleri/olam-host-cp:0.1.168 (multi-arch index).
+# Pinned to the last image built before PRs #915/#919/#920/#921 introduced
+# lifecycle/, observability/, and recovery/ module directories — those PRs
+# updated server.mjs imports but the Dockerfile was not updated to COPY
+# the new directories, so all images from 0.1.169+ crash with
+# ERR_MODULE_NOT_FOUND. The Dockerfile fix (COPY lifecycle/ / observability/
+# / recovery/) lands in PR #940; the next release will ship a working image.
+# At that point, refresh this digest via the instructions below.
 # To update: resolve the new tag's digest via:
 #   TOKEN=$(curl -s "https://ghcr.io/token?scope=repository:pleri/olam-host-cp:pull&service=ghcr.io" | jq -r .token)
 #   curl -sI -H "Authorization: Bearer $TOKEN" \
@@ -111,7 +118,7 @@ spec:
         # k3d), started by `olam upgrade` Step 0.7 — not inside this Pod.
       containers:
         - name: olam-host-cp
-          image: ghcr.io/pleri/olam-host-cp@sha256:766e07263fcf7e765c3689a7b8d40c47754b4ab90c697710843265a7fc84969a
+          image: ghcr.io/pleri/olam-host-cp@sha256:1206e857af61f8907d76d9324adbe8d2d5638a94fe2411c6713ffb4f570e8f58
           imagePullPolicy: IfNotPresent
           securityContext:
             runAsNonRoot: true

package/host-cp/k8s/manifests/auth-service/50-deployment.yaml

@@ -70,7 +70,7 @@ spec:
               mountPath: /data
       containers:
         - name: olam-auth-service
-          image: ghcr.io/pleri/olam-auth@sha256:c6d163f7ac5fe1ca4652ed34afb1d8555c6f61d06398db767db65fee0944b209
+          image: ghcr.io/pleri/olam-auth@sha256:2d32d178380641bcdae11f9ad05851238bd4b121adfc9638c8abed3b25467846
           imagePullPolicy: IfNotPresent
           securityContext:
             runAsNonRoot: true

package/host-cp/k8s/manifests/kg-service/50-deployment.yaml

@@ -61,7 +61,7 @@ spec:
               mountPath: /data
       containers:
         - name: olam-kg-service
-          image: ghcr.io/pleri/olam-kg-service@sha256:77fd9b19d87c6f4cba4d33d76ff476dd7677f78725f3bf75a9076009e17355cc
+          image: ghcr.io/pleri/olam-kg-service@sha256:ee636804b8cffd40a1fb75ba3f79cc0c30a17e89c9a135864567859ccdf895d7
           imagePullPolicy: IfNotPresent
           securityContext:
             runAsNonRoot: true

package/host-cp/k8s/manifests/mcp-auth-service/50-deployment.yaml

@@ -68,7 +68,7 @@ spec:
               mountPath: /data
       containers:
         - name: olam-mcp-auth-service
-          image: ghcr.io/pleri/olam-mcp-auth@sha256:cb5b1d7caece5bca4a4723eb20522a748cd48001aa94a7e7ec106d29bd2142b0
+          image: ghcr.io/pleri/olam-mcp-auth@sha256:07cdd816ac1d991c065f2936b142a5c6909da683d9a6d4efbe7fe66f0c811821
           imagePullPolicy: IfNotPresent
           securityContext:
             runAsNonRoot: true

package/host-cp/k8s/manifests/memory-service/50-deployment.yaml

@@ -70,7 +70,7 @@ spec:
           # bootstrap-placeholder comment + run `npm run refresh:manifest-digests`
           # once ghcr.io/pleri/olam-memory-service has a real published digest.
           # bootstrap-placeholder: pre-publish; refresh after first release
-          image: ghcr.io/pleri/olam-memory-service@sha256:38b2c1f36e49183f5d36999c6519533a8402f3e784109ede8ad7f6e1a205c195
+          image: ghcr.io/pleri/olam-memory-service@sha256:20443e8e6725151f7523a8a85c73c7449767782de1d03bb172ba395df19a0939
           imagePullPolicy: IfNotPresent
           securityContext:
             runAsNonRoot: true

package/host-cp/lifecycle/classify.mjs

@@ -0,0 +1,110 @@
+// classifyStartupFailure — pure mapping from evidence shape to bucket.
+//
+// Precedence rules (walked top-down; first match wins):
+//
+//   1. processExitCode !== undefined        → ProviderProcessGone
+//      The agent process is dead; nothing else matters. This is the
+//      highest-confidence signal because it's observable from outside
+//      the container (docker exit code, child_process exit).
+//
+//   2. pluginErrors.length > 0              → PluginStartupFailed
+//      Boot-time stderr from a plugin/skill source is definitive.
+//      Comes before transport/handshake checks because a failed
+//      plugin can leave transport+mcp in 'pending' permanently.
+//
+//   3. transportStatus === 'failed'         → TransportDead
+//      Channel-open never succeeded — agent is alive but unreachable.
+//
+//   4. mcpHandshakeStatus === 'failed'      → McpHandshakeStall
+//      Channel opened, MCP handshake explicitly failed.
+//
+//   5. mcpHandshakeStatus === 'pending'
+//      AND elapsedSecondsSinceCreation > 30 → McpHandshakeStall
+//      Time-bounded inference: a never-completed handshake after 30s
+//      is the stall signal even without an explicit failure marker.
+//
+//   6. lastPhase === 'TrustRequired'
+//      AND elapsedSecondsSinceCreation > 10 → TrustGateUnanswered
+//      Agent reached the trust gate; no approval ever came back.
+//      10s is the operator's attention budget — past that, the
+//      agent is silently stuck on a human gate.
+//
+//   7. promptSentAt !== undefined
+//      AND firstThoughtAt === undefined     → PromptMisdelivery
+//      Dispatch landed on the host side but the agent never produced
+//      a first thought — the prompt didn't reach the agent process.
+//
+//   8. lastPhase === 'TrustRequired'        → TrustGateUnanswered (fallback)
+//      Stuck at the trust gate even under 10s — still the most likely
+//      explanation for a Failed transition from that phase.
+//
+//   9. fallthrough                          → PromptMisdelivery
+//      The classifier is total: every Failed transition gets a bucket.
+//      PromptMisdelivery is the most operator-actionable "we don't
+//      know why but the dispatch path is the prime suspect" default.
+//
+// Tests in __tests__/classify.test.mjs assert exactly one case per
+// bucket. The function is pure: no I/O, no side effects, deterministic
+// — same evidence in always yields the same bucket out.
+
+import { WorldStartupFailureKind } from './failure-kinds.mjs';
+
+const MCP_HANDSHAKE_STALL_THRESHOLD_SECONDS = 30;
+const TRUST_GATE_UNANSWERED_THRESHOLD_SECONDS = 10;
+
+/**
+ * Map a WorldStartupEvidence bundle to its WorldStartupFailureKind.
+ *
+ * @param {import('./evidence.mjs').WorldStartupEvidence} evidence
+ * @returns {import('./failure-kinds.mjs').WorldStartupFailureKind}
+ */
+export function classifyStartupFailure(evidence) {
+  // 1. Process exited — terminal signal, short-circuits all other checks.
+  if (evidence.processExitCode !== undefined) {
+    return WorldStartupFailureKind.ProviderProcessGone;
+  }
+
+  // 2. Plugin boot errors — definitive boot-time failure.
+  if (evidence.pluginErrors.length > 0) {
+    return WorldStartupFailureKind.PluginStartupFailed;
+  }
+
+  // 3. Transport explicitly failed — agent alive but unreachable.
+  if (evidence.transportStatus === 'failed') {
+    return WorldStartupFailureKind.TransportDead;
+  }
+
+  // 4. MCP handshake explicitly failed.
+  if (evidence.mcpHandshakeStatus === 'failed') {
+    return WorldStartupFailureKind.McpHandshakeStall;
+  }
+
+  // 5. MCP handshake pending past threshold — inferred stall.
+  if (
+    evidence.mcpHandshakeStatus === 'pending' &&
+    evidence.elapsedSecondsSinceCreation > MCP_HANDSHAKE_STALL_THRESHOLD_SECONDS
+  ) {
+    return WorldStartupFailureKind.McpHandshakeStall;
+  }
+
+  // 6. Stuck on trust gate past operator-attention threshold.
+  if (
+    evidence.lastPhase === 'TrustRequired' &&
+    evidence.elapsedSecondsSinceCreation > TRUST_GATE_UNANSWERED_THRESHOLD_SECONDS
+  ) {
+    return WorldStartupFailureKind.TrustGateUnanswered;
+  }
+
+  // 7. Prompt sent but agent never produced a first thought.
+  if (evidence.promptSentAt !== undefined && evidence.firstThoughtAt === undefined) {
+    return WorldStartupFailureKind.PromptMisdelivery;
+  }
+
+  // 8. Still at trust gate under threshold — bucket as trust-gate.
+  if (evidence.lastPhase === 'TrustRequired') {
+    return WorldStartupFailureKind.TrustGateUnanswered;
+  }
+
+  // 9. Total-function fallback.
+  return WorldStartupFailureKind.PromptMisdelivery;
+}

package/host-cp/lifecycle/emit.mjs

@@ -0,0 +1,119 @@
+// recordWorldLifecycle — the single broadcast helper every host-cp
+// surface uses to emit a lifecycle transition.
+//
+// Emits TWO event types on the host-stream:
+//
+//   1. event: 'world.lifecycle'  → live SSE consumers (SPA, MCP, etc.).
+//      Shape: { worldId, phase, at, evidence?, failureKind? }
+//
+//   2. event: 'span'             → NDJSON trace sink (PR #915 + follow-ups).
+//      Shape: { name: 'world.lifecycle', startedAt: at, endedAt: at,
+//               attributes: { worldId, phase, evidence?, failureKind? },
+//               exit: { _tag: 'Success' | 'Failure', reason? } }
+//
+// The dual-emit keeps live consumers and trace consumers on the same
+// substrate without either path coupling to the other. The README jq
+// example `select(.name == "world.lifecycle" ...)` matches the span
+// emission; the SPA's `useHostStream().subscribe('world.lifecycle', ...)`
+// matches the live emission.
+//
+// Failed transitions auto-classify via classifyStartupFailure(evidence)
+// when caller passes evidence but omits an explicit failureKind. Callers
+// MAY provide their own failureKind to override the inference (e.g.
+// docker SIGKILL — the caller knows it was ProviderProcessGone before
+// the classifier could trip its time-thresholds).
+
+import { TERMINAL_PHASES, WorldLifecyclePhase } from './phases.mjs';
+import { classifyStartupFailure } from './classify.mjs';
+import { redactSensitive } from '../observability/redactor.mjs';
+
+/**
+ * @typedef {object} HostStreamLike
+ * @property {(eventType: string, payload: unknown) => unknown} broadcast
+ */
+
+/**
+ * @typedef {object} WorldLifecycleEvent
+ * @property {string}                   worldId
+ * @property {import('./phases.mjs').WorldLifecyclePhase} phase
+ * @property {number}                   at
+ * @property {import('./evidence.mjs').WorldStartupEvidence} [evidence]
+ * @property {import('./failure-kinds.mjs').WorldStartupFailureKind} [failureKind]
+ */
+
+/**
+ * Emit a world lifecycle transition on both `world.lifecycle` and `span`
+ * host-stream channels.
+ *
+ * @param {HostStreamLike} hostStream
+ * @param {object}         args
+ * @param {string}         args.worldId
+ * @param {import('./phases.mjs').WorldLifecyclePhase} args.phase
+ * @param {number}         [args.at]
+ * @param {import('./evidence.mjs').WorldStartupEvidence} [args.evidence]
+ * @param {import('./failure-kinds.mjs').WorldStartupFailureKind} [args.failureKind]
+ * @returns {WorldLifecycleEvent} the payload that was broadcast (test convenience)
+ */
+export function recordWorldLifecycle(hostStream, args) {
+  if (!hostStream || typeof hostStream.broadcast !== 'function') {
+    throw new TypeError('recordWorldLifecycle: hostStream.broadcast is required');
+  }
+  if (typeof args?.worldId !== 'string' || args.worldId.length === 0) {
+    throw new TypeError('recordWorldLifecycle: worldId is required');
+  }
+  if (typeof args?.phase !== 'string') {
+    throw new TypeError('recordWorldLifecycle: phase is required');
+  }
+
+  const at = typeof args.at === 'number' ? args.at : Date.now();
+
+  // Resolve failureKind: explicit override > classifier inference > undefined.
+  let failureKind = args.failureKind;
+  if (
+    failureKind === undefined &&
+    args.phase === WorldLifecyclePhase.Failed &&
+    args.evidence !== undefined
+  ) {
+    failureKind = classifyStartupFailure(args.evidence);
+  }
+
+  /** @type {WorldLifecycleEvent} */
+  const livePayload = {
+    worldId: args.worldId,
+    phase: args.phase,
+    at,
+  };
+  if (args.evidence !== undefined) livePayload.evidence = redactSensitive(args.evidence);
+  if (failureKind !== undefined) livePayload.failureKind = failureKind;
+
+  hostStream.broadcast('world.lifecycle', livePayload);
+
+  // Mirror as a span so the NDJSON trace sink (PR #915) records it.
+  // Lifecycle transitions are point-in-time events — startedAt === endedAt.
+  /** @type {Record<string, unknown>} */
+  const spanAttributes = {
+    worldId: args.worldId,
+    phase: args.phase,
+  };
+  if (args.evidence !== undefined) spanAttributes.evidence = redactSensitive(args.evidence);
+  if (failureKind !== undefined) spanAttributes.failureKind = failureKind;
+
+  /** @type {{ _tag: 'Success' | 'Failure', reason?: string }} */
+  const exit =
+    args.phase === WorldLifecyclePhase.Failed
+      ? { _tag: 'Failure', reason: failureKind ?? 'unclassified' }
+      : { _tag: 'Success' };
+
+  hostStream.broadcast('span', {
+    name: 'world.lifecycle',
+    startedAt: at,
+    endedAt: at,
+    attributes: spanAttributes,
+    exit,
+  });
+
+  return livePayload;
+}
+
+/** Re-export so callers don't need to import both modules. */
+export { WorldLifecyclePhase, TERMINAL_PHASES };

package/host-cp/lifecycle/evidence.mjs

@@ -0,0 +1,45 @@
+// WorldStartupEvidence — the typed bundle the classifier consumes.
+//
+// Every Failed lifecycle transition carries one of these. Fields are
+// strict-optional (undefined, not null) so consumers can use the
+// presence/absence as a signal directly (`promptSentAt === undefined`
+// is itself the PromptMisdelivery signal).
+
+/**
+ * @typedef {'pending' | 'ok' | 'failed'} HandshakeStatus
+ */
+
+/**
+ * @typedef {object} WorldStartupEvidence
+ * @property {string}                   worldId
+ * @property {import('./phases.mjs').WorldLifecyclePhase} lastPhase
+ * @property {number}                   lastPhaseAt                epoch ms
+ * @property {number}                   [promptSentAt]             undefined if no dispatch ever sent
+ * @property {number}                   [firstThoughtAt]           undefined if no thoughts ever produced
+ * @property {HandshakeStatus}          mcpHandshakeStatus
+ * @property {HandshakeStatus}          transportStatus
+ * @property {string[]}                 pluginErrors               captured stderr lines from plugin boot
+ * @property {number}                   [processExitCode]
+ * @property {number}                   elapsedSecondsSinceCreation
+ */
+
+/**
+ * Construct an empty evidence bundle for a freshly-spawned world.
+ * Caller mutates fields as transitions happen, then passes to the
+ * classifier on Failed.
+ *
+ * @param {string} worldId
+ * @param {number} [now]
+ * @returns {WorldStartupEvidence}
+ */
+export function emptyEvidence(worldId, now = Date.now()) {
+  return {
+    worldId,
+    lastPhase: 'Spawning',
+    lastPhaseAt: now,
+    mcpHandshakeStatus: 'pending',
+    transportStatus: 'pending',
+    pluginErrors: [],
+    elapsedSecondsSinceCreation: 0,
+  };
+}

package/host-cp/lifecycle/failure-kinds.mjs

@@ -0,0 +1,56 @@
+// World startup failure buckets — the six canonical classes the
+// classifier maps every observed Failed transition into.
+//
+// Order is load-bearing: the classifier walks these in declaration
+// order on ambiguous evidence, so higher-confidence buckets
+// (PromptMisdelivery, TransportDead) come before time-bounded
+// inferences (TrustGateUnanswered, McpHandshakeStall). Adding a 7th
+// bucket requires updating the classifier precedence and the
+// `world.lifecycle.Failed` consumers in the SPA + NDJSON trace.
+
+/**
+ * @typedef {| 'PromptMisdelivery'
+ *           | 'TransportDead'
+ *           | 'TrustGateUnanswered'
+ *           | 'McpHandshakeStall'
+ *           | 'PluginStartupFailed'
+ *           | 'ProviderProcessGone'} WorldStartupFailureKind
+ */
+
+/**
+ * @type {Readonly<Record<WorldStartupFailureKind, WorldStartupFailureKind>>}
+ */
+export const WorldStartupFailureKind = Object.freeze({
+  /** Dispatch sent but agent never received it (transport mismatch). */
+  PromptMisdelivery: 'PromptMisdelivery',
+  /** stdin/stdout/IPC channel never opened. */
+  TransportDead: 'TransportDead',
+  /** Agent reached TrustRequired, no approval ever arrived. */
+  TrustGateUnanswered: 'TrustGateUnanswered',
+  /** MCP server connection initialized but never completed handshake. */
+  McpHandshakeStall: 'McpHandshakeStall',
+  /** Plugin or skill source failed to load on boot. */
+  PluginStartupFailed: 'PluginStartupFailed',
+  /** Agent (Claude Code) process exited before responding. */
+  ProviderProcessGone: 'ProviderProcessGone',
+});
+
+export const WORLD_STARTUP_FAILURE_KIND_ORDER = Object.freeze([
+  WorldStartupFailureKind.PromptMisdelivery,
+  WorldStartupFailureKind.TransportDead,
+  WorldStartupFailureKind.TrustGateUnanswered,
+  WorldStartupFailureKind.McpHandshakeStall,
+  WorldStartupFailureKind.PluginStartupFailed,
+  WorldStartupFailureKind.ProviderProcessGone,
+]);
+
+/**
+ * @param {unknown} value
+ * @returns {value is WorldStartupFailureKind}
+ */
+export function isWorldStartupFailureKind(value) {
+  return (
+    typeof value === 'string' &&
+    WORLD_STARTUP_FAILURE_KIND_ORDER.includes(/** @type {any} */ (value))
+  );
+}

package/host-cp/lifecycle/index.mjs

@@ -0,0 +1,22 @@
+// Barrel re-export for the lifecycle module. Importers should pull
+// from '@olam/host-cp/lifecycle' (or the relative path equivalent)
+// rather than reaching into individual files.
+
+export {
+  WorldLifecyclePhase,
+  WORLD_LIFECYCLE_PHASE_ORDER,
+  TERMINAL_PHASES,
+  isWorldLifecyclePhase,
+} from './phases.mjs';
+
+export {
+  WorldStartupFailureKind,
+  WORLD_STARTUP_FAILURE_KIND_ORDER,
+  isWorldStartupFailureKind,
+} from './failure-kinds.mjs';
+
+export { emptyEvidence } from './evidence.mjs';
+
+export { classifyStartupFailure } from './classify.mjs';
+
+export { recordWorldLifecycle } from './emit.mjs';