oh-my-opencode 4.7.5 → 4.8.1

package/packages/omo-codex/plugin/components/start-work-continuation/directive.md

@@ -18,11 +18,12 @@ You are mid-flight on a Prometheus work plan. The turn just ended without finish
 1. Read `{{PLAN_PATH}}` AND `{{LEDGER_PATH}}` first — ground truth for what remains and what evidence has already been recorded. The plan checkbox and the ledger are the only sources of truth; do not trust your own memory of prior turns.
 2. Pick the FIRST unchecked top-level checkbox in `## TODOs` or `## Final Verification Wave`. Ignore nested checkboxes under Acceptance Criteria / Evidence / Definition of Done.
 3. Follow the `start-work` skill in full. The skill is already loaded from your earlier turn — re-read its file at `packages/omo-codex/plugin/skills/start-work/SKILL.md` if you have lost context.
-4. Decompose the checkbox into atomic sub-tasks. Dispatch them in PARALLEL via `spawn_agent` calls in this same response unless a sub-task has a NAMED blocking dependency (input from another sub-task or shared file). Prefer `fork_turns: "none"` unless full history is truly required. Every dispatch sets `agent_type`; `model` + `reasoning_effort` alone creates a default agent, not the requested role.
+4. Decompose the checkbox into atomic sub-tasks. Dispatch them in PARALLEL via `spawn_agent` calls in this same response unless a sub-task has a NAMED blocking dependency (input from another sub-task or shared file). Prefer `fork_turns: "none"` unless full history is truly required. Put role and specialty instructions inside `message`; the Codex tool schema only accepts `task_name`, `message`, and `fork_turns`.
 5. Every sub-task message MUST be self-contained and start with `TASK: <imperative assignment>`, then name `DELIVERABLE`, `SCOPE`, and `VERIFY`. State that it is an executable assignment, not a context handoff. It must include all 7 sections and name one Manual-QA channel with its exact tool and exact invocation (the literal `curl` / `send-keys` / `page.click` with concrete inputs and the binary PASS/FAIL observable), plus the applicable ultraqa adversarial classes, a captured artifact, and a cleanup receipt. Channels: HTTP call (`curl -i`); tmux (`send-keys` + `capture-pane`); browser use — use Chrome to drive the page, else download and use agent-browser (https://github.com/vercel-labs/agent-browser); computer use — OS-level GUI automation for a desktop app. Tests are the floor; the channel artifact plus probed adversarial classes are the ceiling. All are required.
-6. Use `wait_agent` for completion signals, but treat `wait_agent` as a mailbox signal, not proof of completion, content, or errors. After two waits with no substantive result, send one targeted followup: `TASK STILL ACTIVE: return <deliverable> or BLOCKED: <reason>`. If still silent or ack-only, record inconclusive, do not count it as pass/review approval, close if safe, and respawn a smaller `fork_turns: "none"` task with the missing deliverable.
-7. After verification of ALL sub-tasks under this checkbox: `apply_patch` the plan to change `- [ ]` → `- [x]`, re-read the plan to confirm the count decreased, append a `task-completed` line to the ledger, then continue.
-8. Do not start fresh on a sub-agent failure. Re-dispatch the same `task_name` with a fix-message: `FAILED: <exact error>` + `Diagnosis: <observation>` + `Fix: <instruction>`.
+6. Treat every worker DoneClaim as untrusted input. Run independent AdversarialVerify before any checkbox can become FullyDone; `confirmed` is the only pass verdict, while `false-positive`, `needs-fix`, and `needs-human-review` loop back to the executor with exact feedback.
+7. Use `wait_agent` for mailbox signals, not proof of completion. For sub-tasks likely to exceed one wait cycle, require `WORKING: <task> - <current phase>` before long passes and `BLOCKED: <reason>` only when progress stops. A timeout only means no new mailbox update arrived; after a timeout, run a single `list_agents` check for the named child when you need reassurance. If it is running or its latest message is `WORKING:`, treat it as alive. Do not use `list_agents` as a polling loop. Send `TASK STILL ACTIVE: return <deliverable> or BLOCKED: <reason>` only when the child is completed without the deliverable, ack-only, or no longer running. If that followup is still silent or ack-only, record inconclusive, do not count it as pass/review approval, close if safe, and respawn a smaller `fork_turns: "none"` task with the missing deliverable.
+8. After verification of ALL sub-tasks under this checkbox: `apply_patch` the plan to change `- [ ]` → `- [x]`, re-read the plan to confirm the count decreased, append a `task-completed` line to the ledger, then continue.
+9. Do not start fresh on a sub-agent failure. Re-dispatch the same `task_name` with a fix-message: `FAILED: <exact error>` + `Diagnosis: <observation>` + `Fix: <instruction>`.
 
 # Hard constraints
 
@@ -34,12 +35,18 @@ You are mid-flight on a Prometheus work plan. The turn just ended without finish
 - The worktree path (if set in boulder.json) governs every file edit and command. Do not stray into the main repo.
 - session_ids you write to boulder.json MUST be prefixed `codex:`. Bare ids on read are legacy `opencode:`.
 
+# Global Review and Debugging Gate
+
+Before completion, run `review-work` and a `debugging` runtime audit. Treat timeout, missing deliverable, ack-only, `BLOCKED:`, and inconclusive review lanes as failures, not progress. Record at least three debugging hypotheses and the runtime evidence that confirms or refutes each one.
+
+Do not print `ORCHESTRATION COMPLETE`. Do not create a PR, PR handoff, or branch handoff. Do not write a final completion answer until this gate passes. Always redact secrets, tokens, credentials, auth headers, cookies, env dumps, private logs, and PII from ledgers, PR bodies, and handoffs.
+
 # Stop conditions for THIS turn
 
 - A top-level checkbox flipped to `- [x]` after the 5-phase QA gate (Phase 1 read, Phase 2 automated, Phase 3 channel scenario, Phase 4 adversarial-class probing, Phase 5 gate decision). Then the Stop hook will re-evaluate; if more checkboxes remain you will be continued again.
-- 3 same-failure cycles on one sub-task → escalate via `spawn_agent(agent_type="codex-ultrawork-reviewer", fork_turns="none", ...)` and stop dispatch.
+- 3 same-failure cycles on one sub-task → escalate via `spawn_agent({"task_name":"failure_escalation_review","message":"TASK: act as a rigorous reviewer. DELIVERABLE: diagnose the repeated sub-task failure and recommend the next safe action. VERIFY: cite the failing evidence.","fork_turns":"none"})` and stop dispatch.
 - Safety boundary (destructive command, secret exfiltration, production write) → stop and surface a safe substitute.
-- All top-level checkboxes `- [x]` AND (if gate triggered) `codex-ultrawork-reviewer` approved unconditionally → print the ORCHESTRATION COMPLETE block and end.
+- All top-level checkboxes `- [x]` AND the Global Review and Debugging Gate passed → print the ORCHESTRATION COMPLETE block and end.
 
 # Output discipline
 

package/packages/omo-codex/plugin/components/start-work-continuation/src/codex-hook.ts

@@ -6,6 +6,7 @@ import type { ReadonlyFileSystem, StopHookEventName, StopHookOutput, StopInput }
 export function runStopHook(input: unknown, fs: ReadonlyFileSystem): string {
 	if (!isStopInput(input)) return "";
 	if (input.stop_hook_active) return "";
+	if (transcriptHasContextPressureMarker(input.transcript_path, fs)) return "";
 	const state = readContinuationState(input.cwd, input.session_id, fs);
 	if (state === null) return "";
 	return JSON.stringify({
@@ -38,6 +39,26 @@ function renderDirective(state: ContinuationState, sessionId: string): string {
 	return rendered;
 }
 
+const CONTEXT_PRESSURE_MARKERS = [
+	"context compacted",
+	"context_length_exceeded",
+	"skill descriptions were shortened",
+	"context_too_large",
+	"codex ran out of room in the model's context window",
+	"your input exceeds the context window",
+	"long threads and multiple compactions",
+] as const;
+
+function transcriptHasContextPressureMarker(transcriptPath: string, fs: ReadonlyFileSystem): boolean {
+	try {
+		const transcript = fs.readFileSync(transcriptPath, "utf8").toLowerCase();
+		return CONTEXT_PRESSURE_MARKERS.some((marker) => transcript.includes(marker));
+	} catch (error) {
+		if (error instanceof Error) return false;
+		throw error;
+	}
+}
+
 function isStopInput(value: unknown): value is StopInput {
 	return (
 		isRecord(value) &&

package/packages/omo-codex/plugin/components/start-work-continuation/test/codex-hook.test.ts

@@ -22,6 +22,21 @@ describe("start-work Stop hook", () => {
 		expect(output).toBe("");
 	});
 
+	it("#given no boulder state and start work prompt #when stop hook runs #then it stays quiet", () => {
+		// given
+		const fs = createMemoryFs();
+		const input = {
+			...createStopInput(),
+			last_assistant_message: "I'll start work on this plan now.",
+		};
+
+		// when
+		const output = runStopHook(input, fs);
+
+		// then
+		expect(output).toBe("");
+	});
+
 	it("#given active codex work with remaining top-level tasks #when hook runs #then returns block JSON", () => {
 		// given
 		const fs = createMemoryFs({
@@ -49,6 +64,38 @@ describe("start-work Stop hook", () => {
 		expect(parsed.reason).toContain("- Your session id in boulder.json: `codex:sess_abc`");
 	});
 
+	it("#given context-window pressure in transcript #when hook runs #then it does not inject continuation text", () => {
+		// given
+		const transcriptPath = "/repo/transcript.jsonl";
+		const fs = createMemoryFs({
+			[BOULDER_PATH]: createBoulderJson({
+				sessionIds: ["codex:sess_abc"],
+				status: "active",
+			}),
+			[PLAN_PATH]: ["# Plan", "", "## TODOs", "- [ ] First"].join("\n"),
+			[transcriptPath]: [
+				JSON.stringify({
+					type: "message",
+					payload: {
+						content: {
+							error: {
+								code: "context_too_large",
+							},
+						},
+					},
+				}),
+				"Your input exceeds the context window of this model.",
+				"",
+			].join("\n"),
+		});
+
+		// when
+		const output = runStopHook({ ...createStopInput(), transcript_path: transcriptPath }, fs);
+
+		// then
+		expect(output).toBe("");
+	});
+
 	it("#given active codex work #when continuation directive is emitted #then subagent guidance is reliable", () => {
 		// given
 		const fs = createMemoryFs({
@@ -66,9 +113,11 @@ describe("start-work Stop hook", () => {
 		const parsed = parseBlockOutput(output);
 		expect(parsed.reason).toMatch(/TASK:/);
 		expect(parsed.reason).toMatch(/fork_turns:\s*"none"/);
-		expect(parsed.reason).toMatch(/wait_agent.*signal, not proof/);
-		expect(parsed.reason).toMatch(/one targeted followup/);
+		expect(parsed.reason).toMatch(/wait_agent.*mailbox signals/);
+		expect(parsed.reason).toMatch(/TASK STILL ACTIVE/);
 		expect(parsed.reason).toMatch(/respawn.*smaller/);
+		expect(parsed.reason).toMatch(/WORKING:/);
+		expect(parsed.reason).toMatch(/single `list_agents`/);
 	});
 
 	it("#given active work belongs to another harness #when hook runs #then returns empty output", () => {
@@ -113,6 +162,19 @@ describe("start-work Stop hook", () => {
 		expect(output).toBe("");
 	});
 
+	it("#given malformed boulder JSON #when hook runs #then returns empty output", () => {
+		// given
+		const fs = createMemoryFs({
+			[BOULDER_PATH]: "{",
+		});
+
+		// when
+		const output = runStopHook(createStopInput(), fs);
+
+		// then
+		expect(output).toBe("");
+	});
+
 	it("#given malformed input #when hook runs #then returns empty output", () => {
 		// given
 		const fs = createMemoryFs();

package/packages/omo-codex/plugin/components/telemetry/README.md

@@ -76,7 +76,17 @@ containing `{ "lastActiveDayUTC": "YYYY-MM-DD" }`. If the stored day matches tod
 
 ## Failure Behavior
 
-Every telemetry path is wrapped in `try`/`catch`. The hook always exits 0 with no stdout output, even when PostHog construction, capture, or shutdown fails. Codex session startup is never blocked or slowed by telemetry failures.
+Every telemetry path is wrapped in `try`/`catch`. The hook always exits 0 with no stdout or stderr output, even when PostHog construction, capture, or shutdown fails. Codex session startup is never blocked or slowed by telemetry failures.
+
+Handled telemetry failures are written only to a local diagnostics file:
+
+```
+$XDG_DATA_HOME/omo-codex/telemetry-diagnostics.jsonl
+# or, when XDG_DATA_HOME is unset:
+~/.local/share/omo-codex/telemetry-diagnostics.jsonl
+```
+
+The diagnostics file keeps JSONL rows for recent telemetry failures, prunes stale rows during writes, and caps itself at 256 KiB by dropping the oldest complete rows. Diagnostics are never sent to PostHog and do not include prompt contents, transcript contents, raw hostnames, API keys, tokens, or full hook payloads.
 
 ## Endpoint Overrides
 

package/packages/omo-codex/plugin/components/telemetry/biome.json

@@ -34,6 +34,18 @@
 		"includes": ["src/**/*.ts", "test/**/*.ts", "vitest.config.ts", "!**/node_modules/**/*", "!**/dist/**/*"]
 	},
 	"overrides": [
+		{
+			"includes": [
+				"src/atomic-write.ts",
+				"src/data-path.ts",
+				"src/diagnostics.ts",
+				"src/env-flags.ts",
+				"src/posthog-activity-state.ts"
+			],
+			"formatter": {
+				"enabled": false
+			}
+		},
 		{
 			"includes": ["vitest.config.ts"],
 			"linter": {

package/packages/omo-codex/plugin/components/telemetry/src/codex-hook.ts

@@ -1,3 +1,8 @@
+import {
+	type TelemetryDiagnosticErrorKind,
+	type TelemetryDiagnosticEvent,
+	writeTelemetryDiagnostic,
+} from "./diagnostics.js";
 import {
 	createPluginPostHog,
 	getPostHogDistinctId,
@@ -22,6 +27,19 @@ export type CodexTelemetryHookOptions = {
 
 const SESSION_START_REASON: PostHogActivityReason = "session_start";
 
+function writeHookDiagnostic(
+	event: TelemetryDiagnosticEvent,
+	error: unknown,
+	errorKind: TelemetryDiagnosticErrorKind,
+): void {
+	writeTelemetryDiagnostic({
+		event,
+		source: "plugin",
+		error,
+		errorKind,
+	});
+}
+
 export async function runSessionStartHook(
 	_input: CodexSessionStartInput,
 	options: CodexTelemetryHookOptions = {},
@@ -29,10 +47,18 @@ export async function runSessionStartHook(
 	const createClient = options.createClient ?? createPluginPostHog;
 	const getDistinctId = options.getDistinctId ?? getPostHogDistinctId;
 
-	const client = await createClient();
+	let client: PostHogClient;
+	try {
+		client = await createClient();
+	} catch (error) {
+		writeHookDiagnostic("telemetry_posthog_init_failed", error, error instanceof Error ? "error" : "non_error");
+		return "";
+	}
+
 	try {
 		client.trackActive(getDistinctId(), SESSION_START_REASON);
-	} catch {
+	} catch (error) {
+		writeHookDiagnostic("telemetry_capture_failed", error, error instanceof Error ? "error" : "non_error");
 		await safeShutdown(client);
 		return "";
 	}
@@ -43,7 +69,8 @@ export async function runSessionStartHook(
 async function safeShutdown(client: PostHogClient): Promise<void> {
 	try {
 		await client.shutdown();
-	} catch {
+	} catch (error) {
+		writeHookDiagnostic("telemetry_shutdown_failed", error, error instanceof Error ? "error" : "non_error");
 		return;
 	}
 }

package/packages/omo-codex/plugin/components/telemetry/src/diagnostics.ts

@@ -0,0 +1,154 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { writeFileAtomically } from "./atomic-write.js"
+import { getActivityStateDir } from "./data-path.js"
+
+export type TelemetryDiagnosticEvent =
+  | "telemetry_activity_state_read_failed"
+  | "telemetry_activity_state_write_failed"
+  | "telemetry_capture_failed"
+  | "telemetry_cpu_info_unavailable"
+  | "telemetry_posthog_import_failed"
+  | "telemetry_posthog_init_failed"
+  | "telemetry_shutdown_failed"
+
+export type TelemetryDiagnosticSource = "cli" | "install" | "plugin" | "shared"
+
+export type TelemetryDiagnosticErrorKind = "error" | "non_error"
+
+export type TelemetryDiagnosticInput = {
+  readonly event: TelemetryDiagnosticEvent
+  readonly source: TelemetryDiagnosticSource
+  readonly error?: unknown
+  readonly errorKind?: TelemetryDiagnosticErrorKind
+}
+
+const DIAGNOSTICS_FILE_NAME = "telemetry-diagnostics.jsonl"
+const DIAGNOSTICS_RETENTION_MS = 7 * 24 * 60 * 60 * 1000
+const DIAGNOSTICS_MAX_BYTES = 256 * 1024
+
+export function getTelemetryDiagnosticsFilePath(): string {
+  return join(getActivityStateDir(), DIAGNOSTICS_FILE_NAME)
+}
+
+export function writeTelemetryDiagnostic(input: TelemetryDiagnosticInput, now: Date = new Date()): void {
+  try {
+    cleanupTelemetryDiagnostics(now)
+    mkdirSync(getActivityStateDir(), { recursive: true })
+    appendFileSync(getTelemetryDiagnosticsFilePath(), `${JSON.stringify(toDiagnosticRecord(input, now))}\n`, "utf-8")
+  } catch {
+    return
+  }
+}
+
+export function cleanupTelemetryDiagnostics(now: Date = new Date()): void {
+  const diagnosticsFilePath = getTelemetryDiagnosticsFilePath()
+  if (!existsSync(diagnosticsFilePath)) {
+    return
+  }
+
+  try {
+    const cutoffMs = now.getTime() - DIAGNOSTICS_RETENTION_MS
+    const retainedLines = trimToMaxBytes(
+      readFileSync(diagnosticsFilePath, "utf-8")
+        .split("\n")
+        .filter((line) => shouldRetainLine(line, cutoffMs)),
+    )
+    writeFileAtomically(diagnosticsFilePath, retainedLines.length === 0 ? "" : `${retainedLines.join("\n")}\n`)
+  } catch {
+    return
+  }
+}
+
+function toDiagnosticRecord(
+  input: TelemetryDiagnosticInput,
+  now: Date,
+): Record<string, string> {
+  return {
+    timestamp: now.toISOString(),
+    event: input.event,
+    source: input.source,
+    ...serializeError(input.error, input.errorKind),
+  }
+}
+
+function serializeError(
+  error: unknown,
+  errorKind?: TelemetryDiagnosticErrorKind,
+): Record<string, string> {
+  if (error instanceof Error) {
+    return {
+      error_kind: errorKind ?? "error",
+      error_name: error.name,
+      error_message: error.message,
+    }
+  }
+
+  if (error === undefined) {
+    return {}
+  }
+
+  return {
+    error_kind: errorKind ?? "non_error",
+    error_name: typeof error,
+    error_message: String(error),
+  }
+}
+
+function shouldRetainLine(line: string, cutoffMs: number): boolean {
+  if (line.length === 0) {
+    return false
+  }
+
+  const parsed = parseDiagnosticLine(line)
+  if (parsed === null) {
+    return false
+  }
+
+  const timestamp = parsed["timestamp"]
+  if (typeof timestamp !== "string") {
+    return false
+  }
+
+  const timestampMs = Date.parse(timestamp)
+  return Number.isFinite(timestampMs) && timestampMs >= cutoffMs
+}
+
+function parseDiagnosticLine(line: string): Record<string, unknown> | null {
+  try {
+    const parsed: unknown = JSON.parse(line)
+    if (!isRecord(parsed)) {
+      return null
+    }
+    return parsed
+  } catch {
+    return null
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+}
+
+function trimToMaxBytes(lines: ReadonlyArray<string>): ReadonlyArray<string> {
+  const retained: string[] = []
+  let totalBytes = 0
+
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const line = lines[index]
+    if (line === undefined) {
+      continue
+    }
+
+    const lineBytes = Buffer.byteLength(`${line}\n`, "utf-8")
+    if (totalBytes + lineBytes > DIAGNOSTICS_MAX_BYTES) {
+      break
+    }
+
+    retained.unshift(line)
+    totalBytes += lineBytes
+  }
+
+  return retained
+}

package/packages/omo-codex/plugin/components/telemetry/src/posthog-activity-state.ts

@@ -3,6 +3,7 @@ import { join } from "node:path"
 
 import { writeFileAtomically } from "./atomic-write.js"
 import { getActivityStateDir } from "./data-path.js"
+import { type TelemetryDiagnosticErrorKind, type TelemetryDiagnosticEvent, writeTelemetryDiagnostic } from "./diagnostics.js"
 
 export type PostHogActivityState = {
   readonly lastActiveDayUTC?: string
@@ -27,6 +28,19 @@ function isPostHogActivityState(value: unknown): value is PostHogActivityState {
   return value !== null && typeof value === "object" && !Array.isArray(value)
 }
 
+function writeActivityStateDiagnostic(
+  event: TelemetryDiagnosticEvent,
+  error: unknown,
+  errorKind: TelemetryDiagnosticErrorKind,
+): void {
+  writeTelemetryDiagnostic({
+    event,
+    source: "shared",
+    error,
+    errorKind,
+  })
+}
+
 function readPostHogActivityState(): PostHogActivityState {
   const stateFilePath = getPostHogActivityStateFilePath()
 
@@ -43,7 +57,8 @@ function readPostHogActivityState(): PostHogActivityState {
     }
 
     return stateJson
-  } catch {
+  } catch (error) {
+    writeActivityStateDiagnostic("telemetry_activity_state_read_failed", error, error instanceof Error ? "error" : "non_error")
     return {}
   }
 }
@@ -55,7 +70,8 @@ function writePostHogActivityState(nextState: PostHogActivityState): void {
   try {
     mkdirSync(stateDir, { recursive: true })
     writeFileAtomically(stateFilePath, `${JSON.stringify(nextState, null, 2)}\n`)
-  } catch {
+  } catch (error) {
+    writeActivityStateDiagnostic("telemetry_activity_state_write_failed", error, error instanceof Error ? "error" : "non_error")
     return
   }
 }

package/packages/omo-codex/plugin/components/telemetry/src/posthog.ts

@@ -3,6 +3,12 @@ import os from "node:os";
 
 import type { PostHog } from "posthog-node";
 
+import {
+	type TelemetryDiagnosticErrorKind,
+	type TelemetryDiagnosticEvent,
+	type TelemetryDiagnosticSource,
+	writeTelemetryDiagnostic,
+} from "./diagnostics.js";
 import { getPostHogApiKey, getPostHogHost, hasPostHogApiKey, shouldDisablePostHog } from "./env-flags.js";
 import { getPostHogActivityCaptureState } from "./posthog-activity-state.js";
 import {
@@ -44,6 +50,15 @@ function resolveActivityStateProvider(): ActivityStateProvider {
 	return activityStateProviderOverride ?? getPostHogActivityCaptureState;
 }
 
+function writePostHogDiagnostic(
+	event: TelemetryDiagnosticEvent,
+	source: TelemetryDiagnosticSource,
+	error: unknown,
+	errorKind: TelemetryDiagnosticErrorKind,
+): void {
+	writeTelemetryDiagnostic({ event, source, error, errorKind });
+}
+
 function getSafeCpuInfo(): { readonly count: number; readonly model: string | undefined } {
 	try {
 		const cpuInfo = resolveOsProvider().cpus();
@@ -51,7 +66,13 @@ function getSafeCpuInfo(): { readonly count: number; readonly model: string | un
 			count: cpuInfo.length,
 			model: cpuInfo[0]?.model,
 		};
-	} catch {
+	} catch (error) {
+		writePostHogDiagnostic(
+			"telemetry_cpu_info_unavailable",
+			"plugin",
+			error,
+			error instanceof Error ? "error" : "non_error",
+		);
 		return {
 			count: 0,
 			model: undefined,
@@ -96,8 +117,13 @@ export async function createPluginPostHog(): Promise<PostHogClient> {
 		const module = await import("posthog-node");
 		PostHogClientConstructor = module.PostHog;
 	} catch (error) {
-		if (error instanceof Error) return NO_OP_POSTHOG;
-		throw error;
+		writePostHogDiagnostic(
+			"telemetry_posthog_import_failed",
+			"plugin",
+			error,
+			error instanceof Error ? "error" : "non_error",
+		);
+		return NO_OP_POSTHOG;
 	}
 
 	let client: PostHog;
@@ -112,7 +138,13 @@ export async function createPluginPostHog(): Promise<PostHogClient> {
 			host: getPostHogHost(),
 			disableGeoip: false,
 		});
-	} catch {
+	} catch (error) {
+		writePostHogDiagnostic(
+			"telemetry_posthog_init_failed",
+			"plugin",
+			error,
+			error instanceof Error ? "error" : "non_error",
+		);
 		return NO_OP_POSTHOG;
 	}
 

package/packages/omo-codex/plugin/components/telemetry/test/codex-hook-diagnostics.test.ts

@@ -0,0 +1,115 @@
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { type CodexSessionStartInput, runSessionStartHook } from "../src/codex-hook.js";
+import { getTelemetryDiagnosticsFilePath } from "../src/diagnostics.js";
+import type { PostHogClient } from "../src/posthog.js";
+
+const tempDirectories: string[] = [];
+const originalXdgDataHome = process.env["XDG_DATA_HOME"];
+
+afterEach(() => {
+	if (originalXdgDataHome === undefined) {
+		delete process.env["XDG_DATA_HOME"];
+	} else {
+		process.env["XDG_DATA_HOME"] = originalXdgDataHome;
+	}
+
+	for (const directory of tempDirectories.splice(0)) {
+		rmSync(directory, { recursive: true, force: true });
+	}
+});
+
+function makeSessionStartInput(overrides: Partial<CodexSessionStartInput> = {}): CodexSessionStartInput {
+	return {
+		session_id: "session-123",
+		transcript_path: null,
+		cwd: "/tmp/project",
+		hook_event_name: "SessionStart",
+		model: "gpt-5.5",
+		permission_mode: "default",
+		source: "startup",
+		...overrides,
+	};
+}
+
+function createDiagnosticsDataDir(): string {
+	const dataDir = mkdtempSync(path.join(tmpdir(), "codex-telemetry-diagnostics-"));
+	tempDirectories.push(dataDir);
+	process.env["XDG_DATA_HOME"] = dataDir;
+	return dataDir;
+}
+
+describe("runSessionStartHook diagnostics", () => {
+	describe("#given a client whose trackActive throws", () => {
+		it("#when invoked #then swallows the error, writes diagnostics, still shuts down, and returns empty string", async () => {
+			let shutdownCalls = 0;
+			createDiagnosticsDataDir();
+			const throwingClient: PostHogClient = {
+				trackActive: () => {
+					throw new Error("trackActive failed");
+				},
+				shutdown: async () => {
+					shutdownCalls += 1;
+				},
+			};
+
+			const output = await runSessionStartHook(makeSessionStartInput(), {
+				createClient: () => throwingClient,
+				getDistinctId: () => "distinct-id-abc",
+			});
+
+			expect(output).toBe("");
+			expect(shutdownCalls).toBe(1);
+			const diagnostics = readFileSync(getTelemetryDiagnosticsFilePath(), "utf-8");
+			expect(diagnostics).toContain('"event":"telemetry_capture_failed"');
+			expect(diagnostics).toContain('"error_message":"trackActive failed"');
+		});
+
+		it("#when invoked with a non-Error throw #then writes diagnostics and still returns empty string", async () => {
+			let shutdownCalls = 0;
+			const failure = Symbol("trackActive failed");
+			createDiagnosticsDataDir();
+			const throwingClient: PostHogClient = {
+				trackActive: () => {
+					throw failure;
+				},
+				shutdown: async () => {
+					shutdownCalls += 1;
+				},
+			};
+
+			const output = await runSessionStartHook(makeSessionStartInput(), {
+				createClient: () => throwingClient,
+				getDistinctId: () => "distinct-id-abc",
+			});
+
+			expect(output).toBe("");
+			expect(shutdownCalls).toBe(1);
+			const diagnostics = readFileSync(getTelemetryDiagnosticsFilePath(), "utf-8");
+			expect(diagnostics).toContain('"event":"telemetry_capture_failed"');
+			expect(diagnostics).toContain('"error_name":"symbol"');
+			expect(diagnostics).toContain('"error_message":"Symbol(trackActive failed)"');
+		});
+	});
+
+	describe("#given a client whose shutdown rejects", () => {
+		it("#when invoked #then swallows the rejection and returns empty string", async () => {
+			const rejectingClient: PostHogClient = {
+				trackActive: () => undefined,
+				shutdown: async () => {
+					throw new Error("shutdown failed");
+				},
+			};
+
+			const output = await runSessionStartHook(makeSessionStartInput(), {
+				createClient: () => rejectingClient,
+				getDistinctId: () => "distinct-id-abc",
+			});
+
+			expect(output).toBe("");
+		});
+	});
+});