@phenx-inc/ctlsurf 0.17.2 → 0.17.4

package/src/main/orchestrator.ts

@@ -15,6 +15,9 @@ import { TicketStore, type TicketInput } from './ticketStore'
 import { Observer } from './observer/observer'
 import { OBSERVER_DEFAULTS, type ObserverSettings } from './observer/types'
 import { log } from './logger'
+import { WorkMap } from './workMap/workMap'
+import type { MapCapability, MapSettings, MapSnapshot } from '../shared/workMap'
+import { initialCapability } from '../../scripts/check-work-map-gpu.cjs'
 
 // ─── Types ────────────────────────────────────────
 
@@ -29,6 +32,10 @@ export interface Profile {
 
 const DEFAULT_IDLE_TIMEOUT_MIN = 15
 
+// ON HOLD: the supervision feature is removed from the UX. Keep its engine,
+// IPC and saved settings for future work, but never run it invisibly.
+const OBSERVER_ON_HOLD = true
+
 export interface SettingsData {
   activeProfile: string
   profiles: Record<string, Profile>
@@ -39,10 +46,11 @@ export interface SettingsData {
   // Speak agent replies aloud (Electron desktop only). Drives the transcript
   // tailer the same way logChat does, independent of chat logging.
   speakReplies?: boolean
-  // Observer supervision layer (advisory; off by default). See
+  // Observer supervision layer (ON HOLD; runtime disabled). See
   // src/main/observer/. Requires an Anthropic API key for Tiers 1–2;
   // without one it still records the ledger, Tier-0 tags, and spans.
   observer?: ObserverSettings
+  workMap?: Partial<MapSettings>
   // Mirror of the renderer's appearance preference (localStorage owns the
   // authoritative copy — index.html has to read it before first paint). Kept
   // here so createWindow can pick the right backgroundColor on the next launch
@@ -54,6 +62,8 @@ export interface SettingsData {
 }
 
 export interface OrchestratorEvents {
+  onWorkMapUpdate?: (snapshot: MapSnapshot) => void
+  onWorkMapCapability?: (capability: MapCapability) => void
   onPtyData: (tabId: string, data: string) => void
   onPtyExit: (tabId: string, code: number) => void
   onWorkerStatus: (status: string) => void
@@ -118,6 +128,7 @@ export class Orchestrator {
   readonly timeTracker = new TimeTracker(this.ctlsurfApi)
   readonly ticketStore = new TicketStore(this.ctlsurfApi)
   readonly observer: Observer
+  readonly workMap: WorkMap
 
   // State
   private tabs = new Map<string, TabState>()
@@ -139,14 +150,18 @@ export class Orchestrator {
   private readonly pendingSshPasswords = new Map<string, string>()
   private readonly pendingSshPasswordTimers = new Map<string, ReturnType<typeof setTimeout>>()
 
-  constructor(settingsDir: string, events: OrchestratorEvents) {
+  constructor(settingsDir: string, events: OrchestratorEvents, options?: { appRoot?: string; desktop?: boolean }) {
     this.settingsDir = settingsDir
     this.events = events
+    this.workMap = new WorkMap(options?.appRoot || process.cwd(), snapshot => this.events.onWorkMapUpdate?.(snapshot), {}, initialCapability({ desktop: options?.desktop === true }))
 
     this.observer = new Observer({
       settingsDir,
       api: this.ctlsurfApi,
-      getSettings: () => this.settings.observer || {},
+      getSettings: () => ({
+        ...this.settings.observer,
+        enabled: !OBSERVER_ON_HOLD && !!this.settings.observer?.enabled,
+      }),
       onUpdate: (item) => this.events.onObserverUpdate?.(item),
       onActivity: (reviewing) => this.events.onObserverActivity?.(reviewing),
     })
@@ -154,6 +169,7 @@ export class Orchestrator {
     this.stateMonitor = new AgentStateMonitor(({ tabId, state, anyAwaiting }) => {
       this.events.onAgentStateChange?.(tabId, state, anyAwaiting)
       this.observer.noteAgentState(tabId, state)
+      this.workMap.noteState(tabId, state)
     })
     this.stateMonitor.start()
 
@@ -235,6 +251,19 @@ export class Orchestrator {
     this.restartActiveChatLogging()
   }
 
+  configureWorkMap(data: Partial<MapSettings>): void {
+    const capability = this.workMap.getCapability()
+    if (data.enabled && capability.state !== 'available') throw new Error(capability.reason || 'Work map is unavailable on this machine.')
+    this.settings.workMap = this.workMap.configure(data)
+    this.saveSettings()
+  }
+
+  setWorkMapCapability(capability: MapCapability): void {
+    this.workMap.setCapability(capability)
+    this.workMap.configure({ ...this.settings.workMap, enabled: capability.state === 'available' && !!this.settings.workMap?.enabled })
+    this.events.onWorkMapCapability?.(capability)
+  }
+
   // ─── Observer settings ──────────────────────────
 
   /** Summary for the settings UI — never echoes the API key back. */
@@ -242,7 +271,7 @@ export class Orchestrator {
     const o = this.settings.observer || {}
     const keySource = o.anthropicApiKey ? 'settings' : process.env.ANTHROPIC_API_KEY ? 'env' : null
     return {
-      enabled: !!o.enabled,
+      enabled: !OBSERVER_ON_HOLD && !!o.enabled,
       hasApiKey: keySource !== null,
       keySource,
       dailyCapUsd: o.dailyCapUsd ?? OBSERVER_DEFAULTS.dailyCapUsd,
@@ -428,6 +457,7 @@ export class Orchestrator {
 
     this.applyProfile(this.getActiveProfile())
     this.bridge.setLoggingEnabled(!!this.settings.logChat)
+    this.workMap.configure({ ...this.settings.workMap, enabled: !!this.events.onWorkMapUpdate && !!this.settings.workMap?.enabled })
   }
 
   saveSettings(): void {
@@ -597,6 +627,7 @@ export class Orchestrator {
       // Observer removes its tab synchronously before generating the digest;
       // time tracking must finish before a new session reuses the same tab id.
       void this.observer.endTab(tabId, existing.projectRootPath)
+      this.workMap.remove(tabId)
       existing.ptyManager.kill()
       await this.timeTracker.endSession(tabId)
     }
@@ -615,6 +646,7 @@ export class Orchestrator {
     // Track all tabs (not just the active one): a background agent finishing is
     // exactly when the dock indicator is most useful.
     this.stateMonitor.trackTab(tabId, agent.id, cwd)
+    this.workMap.attach(tabId, agent.id, agent.name, cwd)
 
     // Remote (SSH) tab with an in-app password waiting: feed it to ssh's prompt
     // once, directly over the PTY. The password is consumed here (removed from
@@ -644,6 +676,7 @@ export class Orchestrator {
       if (this.tabs.get(tabId) !== tab) return
       this.events.onPtyExit(tabId, exitCode)
       const observerEnd = this.observer.endTab(tabId, tab.projectRootPath)
+      this.workMap.end(tabId)
       await this.timeTracker.endSession(tabId)
       void observerEnd
       // The user can start a replacement while the tracking write above is in
@@ -704,6 +737,7 @@ export class Orchestrator {
 
   async killTab(tabId: string): Promise<void> {
     const tab = this.tabs.get(tabId)
+    this.workMap.remove(tabId)
     if (!tab) return
     if (tab.termStreamTimer) clearTimeout(tab.termStreamTimer)
     await this.timeTracker.endSession(tabId)
@@ -933,6 +967,7 @@ export class Orchestrator {
   // ─── Shutdown ───────────────────────────────────
 
   async shutdown(): Promise<void> {
+    this.workMap.shutdown()
     this.stopNoProjectPolling()
     this.stopChatLogging()
     this.stateMonitor.stop()

package/src/main/transcripts.ts

@@ -1,6 +1,7 @@
 import fs from 'fs'
 import path from 'path'
 import os from 'os'
+import { StringDecoder } from 'string_decoder'
 import { log } from './logger'
 
 /**
@@ -46,7 +47,7 @@ export interface TranscriptTailerOptions {
    * by cwd. Used by the Observer to see tool_use/tool_result records the
    * chat sink discards. Must never throw.
    */
-  rawSink?: (obj: unknown) => void
+  rawSink?: (obj: unknown, source: { filePath: string; sinceMs: number }) => void
   /** Override transcript roots (for tests). */
   claudeProjectsDir?: string
   codexSessionsDir?: string
@@ -56,19 +57,24 @@ const POLL_INTERVAL_MS = 1_000
 const DISCOVERY_SLACK_MS = 10_000
 const READ_CHUNK_BYTES = 64 * 1024
 const MAX_ENTRY_CHARS = 20_000
+const MAX_READ_PER_POLL = 512 * 1024
+const MAX_LINE_CHARS = 1024 * 1024
 
 interface FileTail {
   offset: number
   remainder: string
   /** Codex file whose session_meta cwd belongs to a different project. */
   excluded: boolean
+  decoder: StringDecoder
+  discardingLine: boolean
+  scoped: boolean
 }
 
 export class TranscriptTailer {
   private readonly agentId: TranscriptAgentId
   private readonly cwd: string
   private readonly sink: ChatLogSink
-  private readonly rawSink?: (obj: unknown) => void
+  private readonly rawSink?: TranscriptTailerOptions['rawSink']
   private readonly claudeProjectsDir: string
   private readonly codexSessionsDir: string
 
@@ -140,7 +146,7 @@ export class TranscriptTailer {
         try {
           const stat = fs.statSync(filePath)
           if (stat.mtimeMs >= this.sinceMs - DISCOVERY_SLACK_MS) {
-            this.files.set(filePath, { offset: 0, remainder: '', excluded: false })
+            this.files.set(filePath, { offset: 0, remainder: '', excluded: false, decoder: new StringDecoder('utf8'), discardingLine: false, scoped: this.agentId === 'claude' })
           }
         } catch { /* ignore — file may have vanished */ }
       }
@@ -177,7 +183,14 @@ export class TranscriptTailer {
     } catch {
       return
     }
-    if (size <= tail.offset) return
+    if (size < tail.offset) {
+      tail.offset = 0
+      tail.remainder = ''
+      tail.decoder = new StringDecoder('utf8')
+      tail.discardingLine = false
+      tail.scoped = this.agentId === 'claude'
+    }
+    if (size === tail.offset) return
 
     let fd: number
     try {
@@ -187,18 +200,21 @@ export class TranscriptTailer {
     }
     try {
       const buf = Buffer.alloc(READ_CHUNK_BYTES)
-      while (tail.offset < size && !tail.excluded) {
-        const bytesRead = fs.readSync(fd, buf, 0, READ_CHUNK_BYTES, tail.offset)
+      const end = Math.min(size, tail.offset + MAX_READ_PER_POLL)
+      while (tail.offset < end && !tail.excluded) {
+        const bytesRead = fs.readSync(fd, buf, 0, Math.min(READ_CHUNK_BYTES, end - tail.offset), tail.offset)
         if (bytesRead <= 0) break
         tail.offset += bytesRead
-        tail.remainder += buf.toString('utf-8', 0, bytesRead)
+        tail.remainder += tail.decoder.write(buf.subarray(0, bytesRead))
 
         const lines = tail.remainder.split('\n')
         tail.remainder = lines.pop() || ''
         for (const line of lines) {
-          this.handleLine(line, tail)
+          if (tail.discardingLine) { tail.discardingLine = false; continue }
+          if (line.length <= MAX_LINE_CHARS) this.handleLine(line, tail, filePath)
           if (tail.excluded) break
         }
+        if (tail.remainder.length > MAX_LINE_CHARS) { tail.remainder = ''; tail.discardingLine = true }
       }
     } catch (err) {
       console.error(`[transcripts] Read error for ${filePath}:`, err)
@@ -207,7 +223,7 @@ export class TranscriptTailer {
     }
   }
 
-  private handleLine(line: string, tail: FileTail): void {
+  private handleLine(line: string, tail: FileTail, filePath: string): void {
     const trimmed = line.trim()
     if (!trimmed) return
 
@@ -218,16 +234,18 @@ export class TranscriptTailer {
       return // tolerate partial/corrupt lines
     }
 
-    // Raw hook (Observer): every parsed object except replayed history.
-    // Codex lines from excluded files never reach here (drainFile stops).
+    // Scope the file before invoking raw consumers (including session_meta).
+    // Otherwise a different project's tool records could leak into its map.
+    const entry = this.agentId === 'claude' ? this.parseClaudeLine(obj) : this.parseCodexLine(obj, tail)
+    if (tail.excluded || !tail.scoped || obj?.isSidechain || obj?.isMeta) return
+    if (this.agentId === 'claude' && typeof obj?.cwd === 'string' && stripTrailingSep(obj.cwd) !== this.cwd) return
+
     if (this.rawSink) {
       const rawMs = typeof obj?.timestamp === 'string' ? Date.parse(obj.timestamp) : NaN
-      if (!Number.isFinite(rawMs) || rawMs >= this.sinceMs - DISCOVERY_SLACK_MS) {
-        try { this.rawSink(obj) } catch { /* observer errors must not break tailing */ }
+      if (obj?.type === 'session_meta' || !Number.isFinite(rawMs) || rawMs >= this.sinceMs - DISCOVERY_SLACK_MS) {
+        try { this.rawSink(obj, { filePath, sinceMs: this.sinceMs }) } catch { /* consumers must not break tailing */ }
       }
     }
-
-    const entry = this.agentId === 'claude' ? this.parseClaudeLine(obj) : this.parseCodexLine(obj, tail)
     if (!entry) return
 
     // Skip history replayed into resumed/forked session files.
@@ -269,9 +287,10 @@ export class TranscriptTailer {
 
     if (obj.type === 'session_meta') {
       const metaCwd = payload?.cwd
-      if (typeof metaCwd === 'string' && stripTrailingSep(metaCwd) !== this.cwd) {
+      if (typeof metaCwd !== 'string' || stripTrailingSep(metaCwd) !== this.cwd) {
         tail.excluded = true // another project's session sharing the date dir
       }
+      tail.scoped = !tail.excluded
       return null
     }
 

package/src/main/workMap/clef.ts

@@ -0,0 +1,156 @@
+import { spawn, type ChildProcessWithoutNullStreams } from 'child_process'
+import fs from 'fs'
+import path from 'path'
+import type { MapSettings, MapSnapshot } from '../../shared/workMap'
+
+export interface DecisionRequest {
+  model: string
+  state: string
+  questions: Record<string, { type: 'choice'; instructions: string; criteria: Record<string, string> }>
+}
+
+export interface Decision { choice: string; probabilities: Record<string, number> }
+
+export function validateDecisions(value: any, req: DecisionRequest): Record<string, Decision> {
+  const answers = value?.answers
+  if (!answers || Object.keys(answers).sort().join() !== Object.keys(req.questions).sort().join()) throw new Error('Clef returned an invalid decision schema')
+  for (const [key, q] of Object.entries(req.questions)) {
+    const a = answers[key]
+    const allowed = Object.keys(q.criteria).sort()
+    if (!a || !allowed.includes(a.choice) || !a.probabilities || Object.keys(a.probabilities).sort().join() !== allowed.join()) throw new Error('Clef returned an unknown branch or activity')
+    const values = Object.values(a.probabilities) as number[]
+    if (values.some(p => typeof p !== 'number' || !Number.isFinite(p) || p < 0 || p > 1)
+      || Math.abs(values.reduce((s, p) => s + p, 0) - 1) > 0.002
+      || a.probabilities[a.choice] < Math.max(...values) - 0.000001) throw new Error('Clef returned invalid probabilities')
+  }
+  return answers
+}
+
+/** One isolated model process shared by all tabs; the caller owns its bounded queue. */
+export class ClefWorker {
+  state: MapSnapshot['runtime'] = 'idle'
+  error: string | null = null
+  private child: ChildProcessWithoutNullStreams | null = null
+  private ready: Promise<void> | null = null
+  private rejectReady: ((err: Error) => void) | null = null
+  private pending: { id: number; resolve: (value: any) => void; reject: (err: Error) => void } | null = null
+  private seq = 0
+  private generation = 0
+  private idle: ReturnType<typeof setTimeout> | null = null
+  private loadTimeout: ReturnType<typeof setTimeout> | null = null
+  private requestTimeout: ReturnType<typeof setTimeout> | null = null
+  private stopping: Promise<void> = Promise.resolve()
+
+  constructor(private scriptPath: string, private onChange: () => void) {}
+
+  private change(state: MapSnapshot['runtime'], error: string | null = null): void {
+    this.state = state
+    this.error = error
+    this.onChange()
+  }
+
+  async predict(settings: MapSettings, request: DecisionRequest): Promise<Record<string, Decision>> {
+    const generation = this.generation
+    try {
+      await this.start(settings, generation)
+      if (!this.child || generation !== this.generation) throw new Error('Clef process stopped')
+      if (this.pending) throw new Error('Clef is already processing a batch')
+      if (this.idle) clearTimeout(this.idle)
+      this.change('thinking')
+      const response = await new Promise<any>((resolve, reject) => {
+        this.pending = { id: ++this.seq, resolve, reject }
+        this.requestTimeout = setTimeout(() => this.fail('Clef timed out; turn the map off and on to retry.'), 20_000)
+        this.child!.stdin.write(JSON.stringify({ id: this.seq, request }) + '\n', err => {
+          if (err) this.fail(`Clef input failed: ${err.message}`)
+        })
+      })
+      const answers = validateDecisions(response, request)
+      this.change('ready')
+      this.armIdle()
+      return answers
+    } catch (err) {
+      if (generation === this.generation) this.fail(err instanceof Error ? err.message : String(err))
+      throw err
+    }
+  }
+
+  private async start(settings: MapSettings, generation: number): Promise<void> {
+    await this.stopping
+    if (generation !== this.generation) throw new Error('Clef process stopped')
+    if (this.ready) return this.ready
+    if (process.platform !== 'darwin' || process.arch !== 'arm64') throw new Error('Local Clef-Flash requires an Apple Silicon Mac. Choose Rules on this machine.')
+    if (!fs.existsSync(settings.pythonPath) || !fs.existsSync(path.join(settings.modelPath, 'clef_mlx.py'))) {
+      throw new Error('Clef runtime not found. Open Local model setup and select the Python executable and downloaded Clef-Flash folder.')
+    }
+    this.change('loading')
+    const child = spawn(settings.pythonPath, ['-u', this.scriptPath, settings.modelPath], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, HF_HUB_OFFLINE: '1', TRANSFORMERS_OFFLINE: '1', PYTHONDONTWRITEBYTECODE: '1' },
+    })
+    this.child = child
+    let buffer = ''
+    let stderr = ''
+    this.ready = new Promise<void>((resolve, reject) => {
+      this.rejectReady = reject
+      this.loadTimeout = setTimeout(() => this.fail('Clef did not load within 60 seconds.'), 60_000)
+      child.stdout.on('data', chunk => {
+        if (this.child !== child) return
+        buffer += String(chunk)
+        if (buffer.length > 128_000) { this.fail('Clef response exceeded its output budget'); return }
+        let newline: number
+        while ((newline = buffer.indexOf('\n')) >= 0) {
+          const line = buffer.slice(0, newline)
+          buffer = buffer.slice(newline + 1)
+          let msg: any
+          try { msg = JSON.parse(line) } catch { continue }
+          if (msg.ready) {
+            if (this.loadTimeout) clearTimeout(this.loadTimeout)
+            this.rejectReady = null
+            this.change('ready')
+            resolve()
+          } else if (msg.error) {
+            this.fail(String(msg.error))
+          } else if (msg.id === this.pending?.id) {
+            if (this.requestTimeout) clearTimeout(this.requestTimeout)
+            const pending = this.pending
+            this.pending = null
+            pending?.resolve(msg)
+          }
+        }
+      })
+      child.stderr.on('data', chunk => { stderr = (stderr + String(chunk)).slice(-1000) })
+      child.on('error', err => { if (this.child === child) this.fail(`Cannot start Clef: ${err.message}`) })
+      child.on('exit', () => { if (this.child === child) this.fail(`Clef stopped unexpectedly. ${stderr.slice(-300)}`) })
+    })
+    return this.ready
+  }
+
+  private armIdle(): void {
+    if (this.idle) clearTimeout(this.idle)
+    this.idle = setTimeout(() => this.stop(), 60_000)
+    this.idle.unref()
+  }
+
+  private fail(message: string): void {
+    this.stop(message)
+    this.change('error', message.slice(0, 600))
+  }
+
+  stop(reason = 'Clef stopped'): void {
+    ++this.generation
+    for (const timer of [this.idle, this.loadTimeout, this.requestTimeout]) if (timer) clearTimeout(timer)
+    this.idle = this.loadTimeout = this.requestTimeout = null
+    this.rejectReady?.(new Error(reason))
+    this.rejectReady = null
+    this.pending?.reject(new Error(reason))
+    this.pending = null
+    this.ready = null
+    const child = this.child
+    this.child = null
+    if (child) {
+      this.stopping = new Promise(resolve => child.once('close', () => resolve()))
+      child.kill('SIGKILL')
+    }
+    this.change('idle')
+  }
+}

package/src/main/workMap/normalize.ts

@@ -0,0 +1,172 @@
+import { createHash } from 'crypto'
+import path from 'path'
+import type { MapActivity, MapEvidence, MapIntent, MapStatus } from '../../shared/workMap'
+
+const textOf = (value: unknown): string => {
+  if (typeof value === 'string') return value
+  if (Array.isArray(value)) return value.map(b => b?.text || '').filter(Boolean).join('\n')
+  return ''
+}
+const compact = (value: unknown): string => {
+  if (typeof value === 'string') return value.slice(0, 1800)
+  try { return JSON.stringify(value ?? {}).slice(0, 1800) } catch { return '' }
+}
+const noise = (text: string): boolean => /^\s*(?:<environment_context>|<user_instructions>|<permissions instructions>|<system-reminder>|<local-command|<command-|<task-notification>|<turn_aborted>|# AGENTS\.md)/i.test(text)
+
+const summaryText = (value: unknown): string => {
+  if (typeof value === 'string') return value
+  if (!Array.isArray(value)) return ''
+  return value.map(part => typeof part === 'string' ? part : part?.type === 'summary_text' ? part.text || '' : '').filter(Boolean).join('\n\n')
+}
+
+/** Read only the explicitly readable summary fields. Never inspect encrypted/raw content. */
+function codexThinking(raw: any): { text: string; key: string } | null {
+  const p = raw?.payload
+  if (raw?.type === 'response_item' && p?.type === 'reasoning') {
+    const text = summaryText(p.summary)
+    return { text, key: p.id || text }
+  }
+  if (raw?.type === 'event_msg' && p?.type === 'agent_reasoning') {
+    const text = typeof p.text === 'string' ? p.text : ''
+    return { text, key: p.id || text }
+  }
+  const item = raw?.type === 'event_msg' && p?.type === 'item_completed' ? p.item
+    : raw?.method === 'item/completed' ? raw.params?.item : null
+  if (item?.type === 'Reasoning' || item?.type === 'reasoning') {
+    const text = summaryText(item.summary_text ?? item.summaryText ?? item.summary)
+    return { text, key: item.id || text }
+  }
+  return null
+}
+
+export function mapThinkingStatus(raw: any, agent: string): 'available' | 'unavailable' | null {
+  if (agent === 'claude') {
+    if (raw?.type !== 'assistant' || !Array.isArray(raw.message?.content)) return null
+    const blocks = raw.message.content.filter((b: any) => b?.type === 'thinking' || b?.type === 'redacted_thinking')
+    if (!blocks.length) return null
+    return blocks.some((b: any) => b.type === 'thinking' && typeof b.thinking === 'string' && b.thinking.trim()) ? 'available' : 'unavailable'
+  }
+  const thinking = codexThinking(raw)
+  return thinking ? thinking.text.trim() ? 'available' : 'unavailable' : null
+}
+
+/** Public messages, readable thinking summaries, and tool records. */
+export function normalizeMapEvents(raw: any, file: string, agent: string, includeFullSource = false): MapEvidence[] {
+  if (!raw || typeof raw !== 'object' || raw.isSidechain || raw.isMeta) return []
+  const ts = typeof raw.timestamp === 'string' ? raw.timestamp : new Date().toISOString()
+  const source = path.basename(file)
+  const events: MapEvidence[] = []
+  const add = (kind: MapEvidence['kind'], text: string, key: string, extra: Partial<MapEvidence> = {}) => {
+    if (!text.trim() || ((kind === 'prompt' || kind === 'message') && noise(text))) return
+    const hash = createHash('sha256').update(`${file}:${key}:${kind}`).digest('hex').slice(0, 20)
+    const bounded = kind === 'thinking' && text.length > 1800 ? `${text.slice(0, 300)}\n…\n${text.slice(-1490)}` : text.trim().slice(0, 1800)
+    const segments = kind === 'thinking' || kind === 'message' ? decisionCandidates(text) : undefined
+    events.push({ id: hash, ts, kind, text: bounded, source, ...extra, ...(segments?.length ? { segments } : {}),
+      ...(includeFullSource && (kind === 'thinking' || kind === 'message') ? { fullText: text.trim() } : {}),
+    })
+  }
+  if (agent === 'claude') {
+    if (raw.type !== 'user' && raw.type !== 'assistant') return []
+    const blocks = raw.message?.content
+    const key = raw.uuid || raw.message?.id || `${ts}:${compact(blocks)}`
+    if (typeof blocks === 'string') add(raw.type === 'user' ? 'prompt' : 'message', blocks, key)
+    else if (Array.isArray(blocks)) blocks.forEach((b: any, i: number) => {
+      if (b.type === 'text') add(raw.type === 'user' ? 'prompt' : 'message', b.text || '', `${key}:${i}`)
+      if (raw.type === 'assistant' && b.type === 'thinking' && typeof b.thinking === 'string') add('thinking', b.thinking, `${key}:${i}`)
+      if (b.type === 'tool_use') add('tool', compact(b.input?.command ?? b.input?.file_path ?? b.input), b.id, { tool: b.name, toolId: b.id, status: 'running' })
+      if (b.type === 'tool_result') add('result', textOf(b.content) || 'Tool completed', b.tool_use_id, {
+        toolId: b.tool_use_id, status: b.is_error === true ? 'failed' : 'succeeded',
+      })
+    })
+    return events
+  }
+  const thinking = codexThinking(raw)
+  if (thinking) {
+    add('thinking', thinking.text, `reasoning:${thinking.key}`)
+    return events
+  }
+  const p = raw.payload
+  if (!p) return []
+  if (raw.type === 'event_msg') {
+    if (p.type === 'user_message' || p.type === 'agent_message') {
+      add(p.type === 'user_message' ? 'prompt' : 'message', textOf(p.message), `${ts}:${p.type}:${textOf(p.message)}`)
+    }
+    // New Codex app transcripts carry authoritative command/file results here.
+    const item = p.type === 'item_completed' ? p.item : null
+    if (item?.type === 'CommandExecution') {
+      const status: MapStatus = item.status === 'failed' || (typeof item.exit_code === 'number' && item.exit_code !== 0)
+        ? 'failed' : item.status === 'completed' && item.exit_code === 0 ? 'succeeded' : 'unknown'
+      const command = Array.isArray(item.command)
+        ? item.command.length >= 3 && /^-(?:l?c|cl)$/.test(item.command[1]) ? item.command.slice(2).join(' ') : item.command.join(' ')
+        : compact(item.command)
+      add('tool', command, item.id, { tool: 'shell', toolId: item.id, status: 'running' })
+      add('result', item.aggregated_output || `Command ended (${item.exit_code ?? item.status})`, item.id, { toolId: item.id, status })
+    }
+    if (item?.type === 'FileChange') {
+      add('tool', Object.keys(item.changes || {}).join('\n'), item.id, { tool: 'apply_patch', toolId: item.id, status: 'unknown' })
+    }
+  }
+  if (raw.type !== 'response_item') return events
+  if (p.type === 'message' && (p.role === 'user' || p.role === 'assistant')) {
+    const text = Array.isArray(p.content) ? p.content.filter((b: any) => ['input_text', 'output_text'].includes(b.type)).map((b: any) => b.text).join('\n') : ''
+    add(p.role === 'user' ? 'prompt' : 'message', text, p.id || `${ts}:${p.role}:${text}`)
+  }
+  if (p.type === 'function_call' || p.type === 'custom_tool_call') {
+    // The exec wrapper is orchestration code; CommandExecution records describe its actual work.
+    if (/^(?:functions\.)?exec$/.test(p.name)) return events
+    let input = p.arguments ?? p.input
+    try { const obj = JSON.parse(input); input = obj.cmd ?? obj.command ?? obj.file_path ?? obj } catch { /* plain custom-tool input */ }
+    add('tool', compact(input), p.call_id, { tool: p.name, toolId: p.call_id, status: 'running' })
+  }
+  if (p.type === 'function_call_output' || p.type === 'custom_tool_call_output') {
+    const output = textOf(p.output) || compact(p.output)
+    // Never infer success from prose; only explicit runtime metadata / exit codes.
+    const exit = output.match(/(?:Process exited with code|exit_code["']?\s*:)\s*(-?\d+)/i)
+    const status: MapStatus = p.is_error === true ? 'failed' : exit ? (Number(exit[1]) === 0 ? 'succeeded' : 'failed') : 'unknown'
+    add('result', output, p.call_id, { toolId: p.call_id, status })
+  }
+  return events
+}
+
+export function activityFor(e: MapEvidence): MapActivity {
+  if (e.kind === 'thinking') return 'thinking'
+  if (e.kind === 'prompt') return 'planning'
+  if (e.kind === 'message') return /\b(will|next|plan|investigat|checking)\b/i.test(e.text) ? 'planning' : 'reporting'
+  if (/edit|write|apply_patch|filechange/i.test(e.tool || '')) return 'editing'
+  if (/\b(?:pytest|vitest|jest|tsc|unittest|npm (?:run )?(?:test|build)|cargo test|go test|node\s+\S*test[-_.])\b/i.test(e.text)) return 'testing'
+  return 'investigating'
+}
+
+export function shortLabel(text: string, limit = 72): string {
+  const line = text.replace(/```[\s\S]*?```/g, '').replace(/^[\s#>*-]+/gm, '').replace(/\s+/g, ' ').trim()
+  return line.length > limit ? `${line.slice(0, limit - 1).trimEnd()}…` : line || 'Current work'
+}
+
+export function topicFor(e: MapEvidence): string {
+  if (e.kind === 'thinking') return 'Reasoning & decisions'
+  const paths = e.text.match(/(?:[\w.@-]+\/)+[\w.@-]+\.(?:tsx?|jsx?|py|json|css|md|rs|go|sh|cjs|mjs)\b/g)
+  if (paths?.length) return shortLabel(paths[0].split('/').slice(-2).join('/'), 48)
+  if (activityFor(e) === 'testing') return 'Build & tests'
+  if (e.kind === 'message') return 'Approach & findings'
+  return shortLabel(e.tool || 'Investigation', 48)
+}
+
+/** Candidates are exact excerpts, not invented descriptions of a thought. */
+export function decisionCandidates(text: string): string[] {
+  const parts = text.split(/\n+|(?<=[.!?])\s+|,\s+(?=(?:so|because|since|rather|instead)\b)/i)
+    .map(s => s.replace(/^[\s#>*-]+/, '').replace(/\*\*/g, '').trim()).filter(s => s.length >= 15)
+  const score = (s: string) => (intentFor(s) !== 'context' ? 10 : 0)
+    + (/\b(?:choose|decid|instead|suspect|likely|next|prefer)\w*\b/i.test(s) ? 5 : 0)
+    + (/\b(?:because|since|so|avoid|tradeoff|due to|constraint|means)\b/i.test(s) ? 8 : 0)
+  return [...new Set(parts)].map((text, index) => ({ text: text.slice(0, 320), index, score: score(text) }))
+    .sort((a, b) => b.score - a.score || a.index - b.index).slice(0, 6).map(p => p.text)
+}
+
+export function intentFor(text: string): MapIntent {
+  if (/\b(?:suspect|hypothesis|likely|probably|perhaps|maybe|might|could be|seems)\b/i.test(text)) return 'hypothesis'
+  if (/\b(?:alternative|option|versus|weigh|either|could (?:use|try))\b/i.test(text)) return 'alternative'
+  if (/\b(?:choose|decided?|prefer|instead|use .+ rather than|let['’]s use)\b/i.test(text)) return 'decision'
+  if (/\b(?:building|implementing|keeping) (?:it |this )?(?:as|with|in)\b/i.test(text)) return 'decision'
+  if (/\b(?:I['’]ll|I will|we should|need to|next|going to|plan to|first (?:check|test|inspect|read))\b/i.test(text)) return 'next_step'
+  return 'context'
+}

package/src/main/workMap/source.ts

@@ -0,0 +1,28 @@
+import fs from 'fs'
+import path from 'path'
+import { StringDecoder } from 'string_decoder'
+import type { MapSource } from '../../shared/workMap'
+import { normalizeMapEvents } from './normalize'
+
+/** Read only a recorded readable source event, without retaining entire transcripts. */
+export async function readMapSource(file: string, agent: string, eventId: string): Promise<MapSource | null> {
+  const decoder = new StringDecoder('utf8')
+  let remainder = ''
+  let discard = false
+  const stream = fs.createReadStream(file, { highWaterMark: 64 * 1024 })
+  for await (const chunk of stream) {
+    remainder += decoder.write(chunk as Buffer)
+    const lines = remainder.split('\n')
+    remainder = lines.pop() || ''
+    for (const line of lines) {
+      if (discard) { discard = false; continue }
+      if (line.length > 1024 * 1024) continue
+      let raw
+      try { raw = JSON.parse(line) } catch { continue }
+      const event = normalizeMapEvents(raw, file, agent, true).find(e => e.id === eventId)
+      if (event?.fullText !== undefined) return { text: event.fullText, source: path.basename(file) }
+    }
+    if (remainder.length > 1024 * 1024) { remainder = ''; discard = true }
+  }
+  return null
+}