@phenx-inc/ctlsurf 0.13.5 → 0.14.0

package/out/renderer/assets/{index-BEekQe3-.css → index-BpCORklm.css}

@@ -9768,3 +9768,220 @@ html, body, #root {
   box-shadow: 0 8px 24px rgba(0, 0, 0, 0.45);
   pointer-events: none;
 }
+
+/* ─── Observer pane ─────────────────────────────── */
+
+/* Header on/off switch */
+.observer-switch { display: inline-flex; align-items: center; cursor: pointer; padding-top: 2px; }
+.observer-switch input { position: absolute; opacity: 0; width: 0; height: 0; }
+.observer-switch-track {
+  width: 34px; height: 19px; border-radius: 10px;
+  background: #3b4261; position: relative; transition: background 0.15s ease;
+  display: inline-block; flex-shrink: 0;
+}
+.observer-switch-thumb {
+  position: absolute; top: 2px; left: 2px; width: 15px; height: 15px;
+  border-radius: 50%; background: #c0caf5; transition: transform 0.15s ease;
+}
+.observer-switch input:checked + .observer-switch-track { background: #9ece6a; }
+.observer-switch input:checked + .observer-switch-track .observer-switch-thumb {
+  transform: translateX(15px); background: #1a1b26;
+}
+.observer-switch input:disabled + .observer-switch-track { opacity: 0.5; }
+
+.obs-feed { gap: 6px; }
+
+/* Finding / digest cards */
+.obs-card {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  gap: 5px;
+  width: 100%;
+  text-align: left;
+  appearance: none;
+  font: inherit;
+  color: inherit;
+  cursor: pointer;
+  background: #15161f;
+  border: 1px solid #262a3f;
+  border-left: 3px solid #565f89;
+  border-radius: 9px;
+  padding: 9px 26px 9px 12px;
+  transition: border-color 0.12s ease, background 0.12s ease;
+}
+.obs-card:hover { background: #181a26; border-color: #323752; border-left-width: 3px; }
+.obs-card:active { transform: scale(0.995); }
+
+.obs-card-top {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  min-width: 0;
+}
+.obs-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  flex-shrink: 0;
+  font-size: 9.5px;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  padding: 2px 7px 2px 6px;
+  border: 1px solid;
+  border-radius: 999px;
+  line-height: 1.4;
+}
+.obs-chip-dot { width: 5px; height: 5px; border-radius: 50%; flex-shrink: 0; }
+.obs-card-cat {
+  font-size: 10px;
+  color: #565f89;
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.obs-card-time {
+  margin-left: auto;
+  flex-shrink: 0;
+  font-size: 10px;
+  color: #414868;
+  font-variant-numeric: tabular-nums;
+}
+.obs-card-title {
+  font-size: 12.5px;
+  font-weight: 600;
+  color: #c0caf5;
+  line-height: 1.4;
+  word-break: break-word;
+}
+.obs-card-body {
+  font-size: 11.5px;
+  color: #9aa5ce;
+  line-height: 1.5;
+  word-break: break-word;
+}
+.obs-card-body p { margin: 0 0 6px; white-space: pre-wrap; }
+.obs-card-facts { display: flex; flex-wrap: wrap; gap: 6px; }
+.obs-fact {
+  font-size: 10px;
+  color: #565f89;
+  background: #1c1e2b;
+  border: 1px solid #262a3f;
+  border-radius: 5px;
+  padding: 1px 6px;
+  font-variant-numeric: tabular-nums;
+}
+.obs-card-caret {
+  position: absolute;
+  right: 10px;
+  top: 10px;
+  font-size: 10px;
+  color: #414868;
+  transition: transform 0.12s ease;
+}
+.obs-card-caret.open { transform: rotate(90deg); }
+
+/* One-line heartbeats (reviews ran, attach/detach) and health warnings */
+.obs-line {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  padding: 3px 12px 3px 14px;
+  font-size: 11px;
+  color: #565f89;
+  line-height: 1.45;
+}
+.obs-line-dot {
+  flex-shrink: 0;
+  width: 4px; height: 4px;
+  border-radius: 50%;
+  background: #3b4261;
+  align-self: center;
+}
+.obs-line.health { color: #e0af68; }
+.obs-line.health .obs-line-dot { background: #e0af68; }
+.obs-line-text { min-width: 0; word-break: break-word; }
+.obs-line-time {
+  margin-left: auto;
+  flex-shrink: 0;
+  font-size: 10px;
+  color: #414868;
+  font-variant-numeric: tabular-nums;
+}
+
+/* Sensitivity lever + processing indicator row */
+.obs-toolbar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  padding: 8px 14px;
+  border-bottom: 1px solid #23263a;
+}
+.obs-sensitivity {
+  display: inline-flex;
+  background: #15161f;
+  border: 1px solid #262a3f;
+  border-radius: 7px;
+  padding: 2px;
+  gap: 2px;
+}
+.obs-sens-btn {
+  appearance: none;
+  border: none;
+  background: transparent;
+  color: #565f89;
+  font: inherit;
+  font-size: 10.5px;
+  font-weight: 600;
+  padding: 3px 9px;
+  border-radius: 5px;
+  cursor: pointer;
+  transition: background 0.12s ease, color 0.12s ease;
+  white-space: nowrap;
+}
+.obs-sens-btn:hover { color: #9aa5ce; }
+.obs-sens-btn.active { background: #2a2f4a; color: #c0caf5; }
+
+/* "reviewing" bouncing dots */
+.obs-reviewing {
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+  font-size: 10.5px;
+  color: #7aa2f7;
+  letter-spacing: 0.03em;
+}
+.obs-reviewing-dot {
+  width: 4px; height: 4px;
+  border-radius: 50%;
+  background: #7aa2f7;
+  animation: obs-dot-bounce 1.1s ease-in-out infinite;
+}
+.obs-reviewing-dot:nth-child(2) { animation-delay: 0.15s; }
+.obs-reviewing-dot:nth-child(3) { animation-delay: 0.3s; margin-right: 4px; }
+@keyframes obs-dot-bounce {
+  0%, 60%, 100% { transform: translateY(0); opacity: 0.5; }
+  30% { transform: translateY(-3px); opacity: 1; }
+}
+
+/* Pulsing eye badge while a model review is in flight */
+.obs-badge { position: relative; }
+.obs-badge.reviewing { color: #7aa2f7; }
+.obs-badge.reviewing::after {
+  content: '';
+  position: absolute;
+  inset: -1px;
+  border-radius: inherit;
+  border: 1px solid #7aa2f7;
+  animation: obs-badge-pulse 1.6s ease-out infinite;
+  pointer-events: none;
+}
+@keyframes obs-badge-pulse {
+  0% { opacity: 0.9; transform: scale(1); }
+  70% { opacity: 0; transform: scale(1.35); }
+  100% { opacity: 0; transform: scale(1.35); }
+}

package/out/renderer/assets/{javascript-8RyFDDdk.js → javascript-B7CCdfuW.js}

@@ -1,5 +1,5 @@
-import { conf as conf$1, language as language$1 } from "./typescript-BrdIiKZf.js";
-import "./index-CMb4AqkZ.js";
+import { conf as conf$1, language as language$1 } from "./typescript-BuVaU7i3.js";
+import "./index-BhrV6ld-.js";
 const conf = conf$1;
 const language = {
   // Set defaultToken to invalid to see what you do not tokenize yet

package/out/renderer/assets/{jsonMode-CqspkWCb.js → jsonMode-ut9LWBMJ.js}

@@ -1,6 +1,6 @@
-import { c as createWebWorker, l as languages, e as editor } from "./index-CMb4AqkZ.js";
-import { f as DocumentFormattingEditProvider, g as DocumentRangeFormattingEditProvider, C as CompletionAdapter, H as HoverAdapter, b as DocumentSymbolAdapter, d as DocumentColorAdapter, F as FoldingRangeAdapter, S as SelectionRangeAdapter, e as DiagnosticsAdapter } from "./lspLanguageFeatures-Czkp5sZb.js";
-import { a, D, h, R, c, i, j, t, k } from "./lspLanguageFeatures-Czkp5sZb.js";
+import { c as createWebWorker, l as languages, e as editor } from "./index-BhrV6ld-.js";
+import { f as DocumentFormattingEditProvider, g as DocumentRangeFormattingEditProvider, C as CompletionAdapter, H as HoverAdapter, b as DocumentSymbolAdapter, d as DocumentColorAdapter, F as FoldingRangeAdapter, S as SelectionRangeAdapter, e as DiagnosticsAdapter } from "./lspLanguageFeatures-BbMj8Wsc.js";
+import { a, D, h, R, c, i, j, t, k } from "./lspLanguageFeatures-BbMj8Wsc.js";
 const STOP_WHEN_IDLE_FOR = 2 * 60 * 1e3;
 class WorkerManager {
   constructor(defaults) {

package/out/renderer/assets/{liquid-DaEnAsYY.js → liquid-DVDJ0lKt.js}

@@ -1,4 +1,4 @@
-import { l as languages } from "./index-CMb4AqkZ.js";
+import { l as languages } from "./index-BhrV6ld-.js";
 const EMPTY_ELEMENTS = [
   "area",
   "base",

package/out/renderer/assets/{lspLanguageFeatures-Czkp5sZb.js → lspLanguageFeatures-BbMj8Wsc.js}

@@ -1,4 +1,4 @@
-import { R as Range$1, l as languages, e as editor, U as Uri, M as MarkerSeverity } from "./index-CMb4AqkZ.js";
+import { R as Range$1, l as languages, e as editor, U as Uri, M as MarkerSeverity } from "./index-BhrV6ld-.js";
 var DocumentUri;
 (function(DocumentUri2) {
   function is(value) {

package/out/renderer/assets/{mdx-Q-qSZsFg.js → mdx-CcQzYB0J.js}

@@ -1,4 +1,4 @@
-import { l as languages } from "./index-CMb4AqkZ.js";
+import { l as languages } from "./index-BhrV6ld-.js";
 const conf = {
   comments: {
     blockComment: ["{/*", "*/}"]

package/out/renderer/assets/{python-Sw0S0BJV.js → python-Byy7wKMv.js}

@@ -1,4 +1,4 @@
-import { l as languages } from "./index-CMb4AqkZ.js";
+import { l as languages } from "./index-BhrV6ld-.js";
 const conf = {
   comments: {
     lineComment: "#",

package/out/renderer/assets/{razor-C7zQmabz.js → razor-D1xi_wMM.js}

@@ -1,4 +1,4 @@
-import { l as languages } from "./index-CMb4AqkZ.js";
+import { l as languages } from "./index-BhrV6ld-.js";
 const EMPTY_ELEMENTS = [
   "area",
   "base",

package/out/renderer/assets/{tsMode-BWdOxk6v.js → tsMode-DJPzbn5i.js}

@@ -1,4 +1,4 @@
-import { c as createWebWorker, e as editor, U as Uri, a as MarkerTag, M as MarkerSeverity, l as languages, t as typescriptDefaults, R as Range } from "./index-CMb4AqkZ.js";
+import { c as createWebWorker, e as editor, U as Uri, a as MarkerTag, M as MarkerSeverity, l as languages, t as typescriptDefaults, R as Range } from "./index-BhrV6ld-.js";
 class WorkerManager {
   constructor(_modeId, _defaults) {
     this._modeId = _modeId;

package/out/renderer/assets/{typescript-BrdIiKZf.js → typescript-BuVaU7i3.js}

@@ -1,4 +1,4 @@
-import { l as languages } from "./index-CMb4AqkZ.js";
+import { l as languages } from "./index-BhrV6ld-.js";
 const conf = {
   wordPattern: /(-?\d*\.\d\w*)|([^\`\~\!\@\#\%\^\&\*\(\)\-\=\+\[\{\]\}\\\|\;\:\'\"\,\.\<\>\/\?\s]+)/g,
   comments: {

package/out/renderer/assets/{xml-DbKLNPOq.js → xml-rzc91O3d.js}

@@ -1,4 +1,4 @@
-import { l as languages } from "./index-CMb4AqkZ.js";
+import { l as languages } from "./index-BhrV6ld-.js";
 const conf = {
   comments: {
     blockComment: ["<!--", "-->"]

package/out/renderer/assets/{yaml-ehupJBsZ.js → yaml-fAOzQMge.js}

@@ -1,4 +1,4 @@
-import { l as languages } from "./index-CMb4AqkZ.js";
+import { l as languages } from "./index-BhrV6ld-.js";
 const conf = {
   comments: {
     lineComment: "#"

package/out/renderer/index.html

@@ -49,8 +49,8 @@
       color: #565f89;
     }
   </style>
-  <script type="module" crossorigin src="./assets/index-CMb4AqkZ.js"></script>
-  <link rel="stylesheet" crossorigin href="./assets/index-BEekQe3-.css">
+  <script type="module" crossorigin src="./assets/index-BhrV6ld-.js"></script>
+  <link rel="stylesheet" crossorigin href="./assets/index-BpCORklm.css">
 </head>
 <body>
   <div id="boot-splash">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phenx-inc/ctlsurf",
-  "version": "0.13.5",
+  "version": "0.14.0",
   "description": "Agent-agnostic terminal and desktop app for ctlsurf — run Claude Code, Codex, or any coding agent with live session logging and remote control",
   "main": "out/main/index.js",
   "bin": {
@@ -43,6 +43,7 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.110.0",
     "@huggingface/transformers": "^4.2.0",
     "@monaco-editor/react": "^4.7.0",
     "@xterm/addon-fit": "^0.10.0",

package/src/main/index.ts

@@ -213,6 +213,8 @@ const orchestrator = new Orchestrator(
     onWorkerRegistered: (data) => mainWindow?.webContents.send('worker:registered', data),
     onProjectChanged: (name) => mainWindow?.webContents.send('app:projectChanged', name),
     onAgentMessage: (text) => mainWindow?.webContents.send('agent:message', text),
+    onObserverUpdate: (item) => mainWindow?.webContents.send('observer:update', item),
+    onObserverActivity: (reviewing) => mainWindow?.webContents.send('observer:activity', reviewing),
     onAgentStateChange: (tabId, state, anyAwaiting) => {
       log(`[agent-state] tab=${tabId} state=${state} anyAwaiting=${anyAwaiting}`)
       mainWindow?.webContents.send('agent:state', tabId, state, anyAwaiting)
@@ -283,16 +285,29 @@ function createWindow(): void {
 // ─── IPC Handlers ──────────────────────────────────
 
 // Write a rich-HTML table (plus plain-text fallback) to the clipboard so it
-// can be pasted as a formatted table into an email client.
+// can be pasted as a formatted table into an email client. Verify the write
+// landed by reading the plain-text side back — clipboard.write never throws on
+// macOS even when the pasteboard write is dropped, so a read-back is the only
+// reliable success signal.
 ipcMain.handle('clipboard:writeTable', (_event, html: string, text: string) => {
-  clipboard.write({ html, text })
-  return { ok: true }
+  try {
+    clipboard.write({ html, text })
+    return { ok: clipboard.readText() === text }
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) }
+  }
 })
 
-// Plain-text clipboard write, for the terminal right-click "Copy" item.
+// Plain-text clipboard write, for the terminal right-click "Copy" item and the
+// snapshot panel. Read the value back and report whether it actually stuck, so
+// the renderer can show an honest toast instead of claiming success blindly.
 ipcMain.handle('clipboard:writeText', (_event, text: string) => {
-  clipboard.writeText(text)
-  return { ok: true }
+  try {
+    clipboard.writeText(text)
+    return { ok: clipboard.readText() === text }
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) }
+  }
 })
 
 ipcMain.handle('pty:spawn', async (_event, tabId: string, agent: AgentConfig, cwd: string) => {
@@ -606,6 +621,19 @@ ipcMain.handle('speak:set', (_event, enabled: boolean) => {
   orchestrator.setSpeakReplies(!!enabled)
   return { enabled: orchestrator.speakRepliesEnabled }
 })
+
+// ─── Observer IPC ─────────────────────────────────
+
+ipcMain.handle('observer:get', () => orchestrator.getObserverSettingsSummary())
+ipcMain.handle('observer:set', (_event, data: { enabled: boolean; anthropicApiKey?: string; dailyCapUsd?: number; sensitivity?: 'severe' | 'balanced' | 'all' }) => {
+  orchestrator.saveObserverSettings(data)
+  return orchestrator.getObserverSettingsSummary()
+})
+ipcMain.handle('observer:feed', () => orchestrator.observer.getFeed())
+ipcMain.handle('observer:toggle', (_event, enabled: boolean) => {
+  orchestrator.setObserverEnabled(!!enabled)
+  return orchestrator.observer.getFeed()
+})
 // Latest assistant reply from the active tab's transcript, for on-demand TTS.
 ipcMain.handle('agent:getLastReply', () => orchestrator.getLastReply())
 
@@ -696,9 +724,28 @@ app.whenReady().then(() => {
   setInterval(() => { void checkForUpdate() }, UPDATE_CHECK_INTERVAL_MS)
 })
 
+// Shutdown is async (final Tier-1 flush, session digest, time-tracker
+// writes). Hold the quit until it settles — capped so a hung network call
+// can never trap the process — otherwise that work is lost. before-quit
+// covers Cmd+Q; window-all-closed covers closing the last window.
+let shutdownStarted = false
+function shutdownThenQuit(): void {
+  if (shutdownStarted) return
+  shutdownStarted = true
+  void Promise.race([
+    orchestrator.shutdown(),
+    new Promise((resolve) => setTimeout(resolve, 10_000)),
+  ]).finally(() => app.quit())
+}
+
+app.on('before-quit', (event) => {
+  if (shutdownStarted) return // second pass: let the quit proceed
+  event.preventDefault()
+  shutdownThenQuit()
+})
+
 app.on('window-all-closed', () => {
-  orchestrator.shutdown()
-  app.quit()
+  shutdownThenQuit()
 })
 
 app.on('activate', () => {

package/src/main/observer/anthropic.ts

@@ -0,0 +1,48 @@
+import Anthropic from '@anthropic-ai/sdk'
+import type { ModelCaller, ModelCallRequest, ModelCallResult } from './types'
+
+/**
+ * Production ModelCaller backed by @anthropic-ai/sdk.
+ *
+ * The system block carries a cache_control marker so the 5-min prompt cache
+ * is refreshed by the Tier-1 call cadence (spec §3.2). Structured output
+ * (output_config.format json_schema) enforces the strict-JSON contract when
+ * a schema is provided.
+ */
+export function createModelCaller(apiKey: string): ModelCaller {
+  const client = new Anthropic({ apiKey })
+
+  return async (req: ModelCallRequest): Promise<ModelCallResult> => {
+    const params: Record<string, unknown> = {
+      model: req.model,
+      max_tokens: req.maxTokens,
+      system: [
+        { type: 'text', text: req.system, cache_control: { type: 'ephemeral' } },
+      ],
+      messages: [{ role: 'user', content: req.user }],
+    }
+    if (req.schema) {
+      params.output_config = { format: { type: 'json_schema', schema: req.schema } }
+    }
+
+    // The SDK's create() is typed narrowly around output_config across
+    // versions; pass through as any to keep the wire shape authoritative.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const response: any = await (client.messages.create as any)(params)
+
+    const text = (response.content || [])
+      .filter((b: any) => b?.type === 'text' && typeof b.text === 'string')
+      .map((b: any) => b.text)
+      .join('')
+
+    return {
+      text,
+      usage: {
+        inputTokens: response.usage?.input_tokens ?? 0,
+        outputTokens: response.usage?.output_tokens ?? 0,
+        cacheReadTokens: response.usage?.cache_read_input_tokens ?? 0,
+        cacheWriteTokens: response.usage?.cache_creation_input_tokens ?? 0,
+      },
+    }
+  }
+}

package/src/main/observer/budget.ts

@@ -0,0 +1,79 @@
+import fs from 'fs'
+import path from 'path'
+
+/**
+ * Daily spend guard (spec §9). Tracks approximate model cost in a small
+ * JSON file; on cap breach Tier 1 degrades to Tier-0-tagged events only
+ * and an observer.health event is emitted by the caller.
+ */
+
+interface Usage {
+  inputTokens: number
+  outputTokens: number
+  cacheReadTokens: number
+  cacheWriteTokens: number
+}
+
+/** $/MTok — input, output. Cache reads 0.1x input, writes 1.25x input. */
+const PRICES: Record<string, { in: number; out: number }> = {
+  'claude-haiku-4-5': { in: 1, out: 5 },
+  'claude-sonnet-4-6': { in: 3, out: 15 },
+  'claude-sonnet-5': { in: 3, out: 15 },
+}
+const DEFAULT_PRICE = { in: 3, out: 15 }
+
+export function estimateCostUsd(model: string, usage: Usage): number {
+  const p = PRICES[model] || DEFAULT_PRICE
+  return (
+    (usage.inputTokens * p.in +
+      usage.outputTokens * p.out +
+      usage.cacheReadTokens * p.in * 0.1 +
+      usage.cacheWriteTokens * p.in * 1.25) /
+    1_000_000
+  )
+}
+
+export class ObserverBudget {
+  private readonly filePath: string
+  private readonly capUsd: number
+  private date: string
+  private spentUsd = 0
+
+  constructor(dir: string, capUsd: number, now: () => Date = () => new Date()) {
+    this.filePath = path.join(dir, 'budget.json')
+    this.capUsd = capUsd
+    this.date = localDay(now())
+    try {
+      const raw = JSON.parse(fs.readFileSync(this.filePath, 'utf-8'))
+      if (raw?.date === this.date && typeof raw.spentUsd === 'number') {
+        this.spentUsd = raw.spentUsd
+      }
+    } catch { /* fresh day / first run */ }
+  }
+
+  addUsage(model: string, usage: Usage, now: () => Date = () => new Date()): void {
+    const today = localDay(now())
+    if (today !== this.date) {
+      this.date = today
+      this.spentUsd = 0
+    }
+    this.spentUsd += estimateCostUsd(model, usage)
+    try {
+      fs.mkdirSync(path.dirname(this.filePath), { recursive: true })
+      fs.writeFileSync(this.filePath, JSON.stringify({ date: this.date, spentUsd: this.spentUsd }))
+    } catch { /* best-effort */ }
+  }
+
+  overCap(now: () => Date = () => new Date()): boolean {
+    if (localDay(now()) !== this.date) return false // new day resets on next addUsage
+    return this.spentUsd >= this.capUsd
+  }
+
+  get spent(): number {
+    return this.spentUsd
+  }
+}
+
+function localDay(d: Date): string {
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`
+}

package/src/main/observer/ledger.ts

@@ -0,0 +1,61 @@
+import fs from 'fs'
+import path from 'path'
+import type { LedgerEvent, LedgerEventType } from './types'
+
+/**
+ * Session Ledger
+ *
+ * Append-only JSONL file per observed session — the substrate everything
+ * else consumes (spec §1, §6). Events get monotonic `evt_N` ids; Observer
+ * outputs (findings, spans, digests, health) are appended to the same file
+ * with their own id prefixes so receipts always resolve within the file.
+ *
+ * A bounded in-memory tail is kept for ground-truth lookback (e.g. "was a
+ * test command actually run since the last user message?").
+ */
+
+const MEMORY_TAIL_EVENTS = 500
+
+export class SessionLedger {
+  readonly sessionId: string
+  readonly filePath: string
+
+  private seq = 0
+  private tail: LedgerEvent[] = []
+
+  constructor(dir: string, sessionId: string) {
+    this.sessionId = sessionId
+    this.filePath = path.join(dir, `${sessionId}.jsonl`)
+    try { fs.mkdirSync(dir, { recursive: true }) } catch { /* ignore */ }
+  }
+
+  /** Append a normalized event; assigns id + session and persists it. */
+  append(partial: Omit<LedgerEvent, 'id' | 'session'> & { id?: string }): LedgerEvent {
+    const event: LedgerEvent = {
+      ...partial,
+      id: partial.id || this.nextId(partial.type),
+      session: this.sessionId,
+    }
+    this.tail.push(event)
+    if (this.tail.length > MEMORY_TAIL_EVENTS) {
+      this.tail.splice(0, this.tail.length - MEMORY_TAIL_EVENTS)
+    }
+    try {
+      fs.appendFileSync(this.filePath, JSON.stringify(event) + '\n')
+    } catch { /* best-effort: observation must never break the session */ }
+    return event
+  }
+
+  /** Recent events, oldest first (bounded to the in-memory tail). */
+  recent(limit = MEMORY_TAIL_EVENTS): LedgerEvent[] {
+    return limit >= this.tail.length ? [...this.tail] : this.tail.slice(-limit)
+  }
+
+  private nextId(type: LedgerEventType): string {
+    if (type === 'observer.finding') return `fnd_${this.sessionId.slice(4, 10)}_${++this.seq}`
+    if (type === 'observer.span') return `spn_${this.sessionId.slice(4, 10)}_${++this.seq}`
+    if (type === 'observer.digest') return `dig_${this.sessionId.slice(4, 10)}_${++this.seq}`
+    if (type === 'observer.health') return `hlt_${this.sessionId.slice(4, 10)}_${++this.seq}`
+    return `evt_${++this.seq}`
+  }
+}