@phenx-inc/ctlsurf 0.17.2 → 0.17.3

package/src/main/workMap/tree.ts

@@ -0,0 +1,199 @@
+import type { MapActivity, MapEvidence, MapIntent, MapNode } from '../../shared/workMap'
+import type { DecisionRequest, Decision } from './clef'
+import { activityFor, decisionCandidates, intentFor, shortLabel, topicFor } from './normalize'
+
+const ACTIVITIES: Record<Exclude<MapActivity, 'thinking'>, string> = {
+  investigating: 'Reading files, searching, inspecting or diagnosing',
+  editing: 'Changing files, code, dependencies or configuration',
+  testing: 'Running tests, builds or validation',
+  planning: 'Discussing the approach or deciding what to do next',
+  reporting: 'Explaining findings or summarizing completed work',
+}
+const INTENTS: Record<MapIntent, string> = {
+  decision: 'A stated choice of approach or rejection of another approach',
+  hypothesis: 'An unverified explanation or suspicion to investigate',
+  alternative: 'Weighing different possible approaches without choosing yet',
+  next_step: 'A stated next action or check to perform',
+  context: 'General narration with no clear choice, hypothesis or next step',
+}
+export interface MapDecisionJob {
+  request: DecisionRequest
+  ids: string[]
+  goalId: string
+  statements: Record<string, string[]>
+  reasons: Record<string, string[]>
+}
+export const MAP_NODE_LIMIT = 240
+
+/** Bounded evidence-backed tree. Model suggestions never change execution status. */
+export class WorkMapTree {
+  nodes: MapNode[] = []
+  dropped = 0
+  private goal: string | null = null
+  private seq = 0
+  private seen = new Set<string>()
+  private tools = new Map<string, string>()
+  private lastText: { key: string; time: number } | null = null
+  private contextId: string | undefined
+
+  ingest(e: MapEvidence): string | null {
+    if (this.seen.has(e.id)) return null
+    this.seen.add(e.id)
+    if (this.seen.size > 1200) this.seen.delete(this.seen.values().next().value!)
+    if (e.kind === 'result') {
+      const id = this.tools.get(`${e.source}:${e.toolId}`)
+      const node = this.nodes.find(n => n.id === id)
+      if (node) { node.status = e.status || 'unknown'; node.evidence = [node.evidence[0], e] }
+      return null
+    }
+    if (e.kind === 'prompt' || e.kind === 'message' || e.kind === 'thinking') {
+      const key = `${e.source}:${e.kind}:${e.text}`
+      const time = Date.parse(e.ts)
+      if (this.lastText?.key === key && Math.abs(time - this.lastText.time) < 3000) return null
+      this.lastText = { key, time }
+    }
+    if (e.kind === 'prompt') {
+      this.contextId = undefined
+      this.goal = this.add({ parentId: null, kind: 'goal', title: shortLabel(e.text, 110), activity: 'planning', status: 'unknown', ts: e.ts, evidence: [e] }).id
+      this.trim()
+      return null
+    }
+    if (!this.goal) this.goal = this.add({ parentId: null, kind: 'goal', title: 'Session work', activity: 'planning', status: 'unknown', ts: e.ts, evidence: [] }).id
+    const topic = topicFor(e)
+    const branch = this.branch(this.goal, topic, e.ts)
+    const activity = activityFor(e)
+    const statement = e.kind === 'thinking' || e.kind === 'message' ? e.segments?.[0] || decisionCandidates(e.text)[0] || e.text : e.text
+    const title = e.kind === 'tool' ? `${e.tool || 'Tool'} · ${shortLabel(e.text, 65)}` : shortLabel(statement, 110)
+    const intent = e.kind === 'thinking' || e.kind === 'message' ? intentFor(statement) : undefined
+    const node = this.add({ parentId: branch.id, kind: 'step', title, activity, status: e.status || 'unknown', ts: e.ts, evidence: [e], placement: 'rules',
+      intent, ...(intent && intent !== 'context' ? { focus: { text: statement } } : {}),
+      ...(e.kind === 'tool' && this.contextId ? { contextId: this.contextId } : {}),
+    })
+    if (e.kind === 'thinking' || e.kind === 'message') this.contextId = node.id
+    if (e.toolId) this.tools.set(`${e.source}:${e.toolId}`, node.id)
+    this.trim()
+    return node.id
+  }
+
+  end(): void {
+    for (const n of this.nodes) if (n.status === 'running') n.status = 'interrupted'
+  }
+
+  request(ids: string[]): MapDecisionJob | null {
+    const nodes = ids.map(id => this.nodes.find(n => n.id === id && n.kind === 'step')).filter((n): n is MapNode => !!n)
+    if (!nodes.length) return null
+    const parent = this.nodes.find(n => n.id === nodes[0].parentId)
+    if (!parent?.parentId) return null
+    const goalId = parent.parentId
+    const sameGoal = nodes.filter(n => this.nodes.find(b => b.id === n.parentId)?.parentId === goalId)
+    // Richer thought questions get a whole bounded request; tool batches remain at most two.
+    const isIntent = (n: MapNode | undefined) => n?.evidence[0]?.kind === 'thinking' || n?.evidence[0]?.kind === 'message'
+    const selected = sameGoal.slice(0, isIntent(sameGoal[0]) || isIntent(sameGoal[1]) ? 1 : 2)
+    const goal = this.nodes.find(n => n.id === goalId)!
+    const branches = this.nodes.filter(n => n.kind === 'branch' && n.parentId === goalId).slice(-4)
+    const criteria: Record<string, string> = Object.fromEntries(branches.map(n => [n.id, n.title.slice(0, 48)]))
+    criteria.new_topic = 'A different work topic; create a new branch'
+    const questions: DecisionRequest['questions'] = {}
+    const statements: Record<string, string[]> = {}
+    const reasons: Record<string, string[]> = {}
+    selected.forEach((node, i) => {
+      questions[`branch_${i}`] = { type: 'choice', instructions: `Which work topic does event_${i} belong to? Use the goal and stated reasoning, not incidental file paths.`, criteria }
+      if (isIntent(node)) {
+        const candidates = node.evidence[0].segments || decisionCandidates(node.evidence[0].text)
+        statements[node.id] = candidates.length ? candidates : [node.evidence[0].text.slice(0, 220)]
+        questions[`statement_${i}`] = { type: 'choice', instructions: `Which excerpt best captures the agent's choice, hypothesis or next check in event_${i}?`,
+          criteria: Object.fromEntries(statements[node.id].map((s, j) => [`s${j}`, s])),
+        }
+        questions[`intent_${i}`] = { type: 'choice', instructions: `What does the selected excerpt express? A tentative explanation is not an established decision.`, criteria: INTENTS }
+        reasons[node.id] = candidates.filter(s => /\b(?:because|since|so|avoid|tradeoff|due to|constraint|rather|instead)\b/i.test(s)).slice(0, 3)
+        if (reasons[node.id].length) questions[`reason_${i}`] = { type: 'choice', instructions: 'Which excerpt states why the agent chose its approach? Choose none if no supporting reason is stated.',
+          criteria: { ...Object.fromEntries(reasons[node.id].map((s, j) => [`r${j}`, s])), none: 'No supporting reason stated' },
+        }
+      } else {
+        questions[`activity_${i}`] = { type: 'choice', instructions: `What activity does event_${i} show?`, criteria: ACTIVITIES }
+      }
+    })
+    return {
+      ids: selected.map(n => n.id), goalId, statements, reasons,
+      request: {
+        model: 'clef-flash',
+        state: JSON.stringify({ goal: goal.title, events: selected.map((n, i) => ({ id: `event_${i}`, kind: n.evidence[0]?.kind, tool: n.evidence[0]?.tool,
+          text: n.evidence[0]?.text.slice(0, 450),
+          preceding_intent: this.nodes.find(c => c.id === n.contextId)?.evidence[0]?.text.slice(-400),
+          current_topic: this.nodes.find(b => b.id === n.parentId)?.title,
+        })) }),
+        questions,
+      },
+    }
+  }
+
+  apply(job: Pick<MapDecisionJob, 'ids' | 'goalId' | 'statements' | 'reasons'>, answers: Record<string, Decision>): void {
+    job.ids.forEach((id, i) => {
+      const node = this.nodes.find(n => n.id === id)
+      if (!node || !this.nodes.some(n => n.id === job.goalId)) return
+      const decision = answers[`branch_${i}`]
+      const textSource = node.evidence[0]?.kind === 'thinking' || node.evidence[0]?.kind === 'message'
+      if (textSource) {
+        const choice = answers[`statement_${i}`]?.choice
+        const statement = job.statements[node.id]?.[Number(choice?.slice(1))]
+        if (statement) node.title = shortLabel(statement, 110)
+        // Joint decision heads can choose one excerpt but label another part
+        // of the window. Explicit wording in the chosen excerpt takes priority.
+        const statedIntent = intentFor(statement || '')
+        node.intent = statedIntent !== 'context' ? statedIntent : answers[`intent_${i}`]?.choice as MapIntent
+        const reasonChoice = answers[`reason_${i}`]?.choice
+        const reason = reasonChoice && reasonChoice !== 'none' ? job.reasons[node.id]?.[Number(reasonChoice.slice(1))] : undefined
+        node.focus = statement ? { text: statement, ...(reason && reason !== statement ? { reason } : {}) } : undefined
+      }
+      const topic = topicFor(node.evidence[0])
+      const newTitle = shortLabel(node.evidence[0].kind === 'thinking' ? node.title : node.evidence[0].text, 48)
+      const target = decision.choice === 'new_topic'
+        ? this.branch(job.goalId, newTitle === topic ? `${node.activity} · ${topic}` : newTitle, node.ts)
+        : this.nodes.find(n => n.id === decision.choice && n.kind === 'branch' && n.parentId === job.goalId)
+      if (!target) return
+      node.parentId = target.id
+      node.activity = node.evidence[0]?.kind === 'thinking' ? 'thinking' : textSource ? node.intent === 'context' ? 'reporting' : 'planning' : answers[`activity_${i}`].choice as MapActivity
+      node.placement = 'clef-flash'
+      node.confidence = decision.probabilities[decision.choice]
+    })
+    this.removeEmptyBranches()
+    this.trim()
+  }
+
+  private add(node: Omit<MapNode, 'id'>): MapNode {
+    const result = { ...node, id: `map_${++this.seq}` }
+    this.nodes.push(result)
+    return result
+  }
+
+  private branch(goal: string, title: string, ts: string): MapNode {
+    return this.nodes.find(n => n.kind === 'branch' && n.parentId === goal && n.title === title)
+      || this.add({ parentId: goal, kind: 'branch', title, activity: 'planning', status: 'unknown', ts, evidence: [] })
+  }
+
+  private removeEmptyBranches(): void {
+    const parents = new Set(this.nodes.map(n => n.parentId))
+    this.nodes = this.nodes.filter(n => n.kind !== 'branch' || parents.has(n.id))
+  }
+
+  private trim(): void {
+    while (this.nodes.length > MAP_NODE_LIMIT) {
+      const oldGoal = this.nodes.find(n => n.kind === 'goal' && n.id !== this.goal)
+      if (oldGoal) {
+        const removed = new Set([oldGoal.id, ...this.nodes.filter(n => n.parentId === oldGoal.id).map(n => n.id)])
+        const before = this.nodes.length
+        this.nodes = this.nodes.filter(n => !removed.has(n.id) && !removed.has(n.parentId || ''))
+        this.dropped += before - this.nodes.length
+      } else {
+        const oldest = this.nodes.findIndex(n => n.kind === 'step')
+        if (oldest < 0) break
+        this.nodes.splice(oldest, 1)
+        this.dropped++
+        this.removeEmptyBranches()
+      }
+    }
+    const retained = new Set(this.nodes.map(n => n.id))
+    if (this.contextId && !retained.has(this.contextId)) this.contextId = undefined
+    for (const [key, id] of this.tools) if (!retained.has(id)) this.tools.delete(key)
+  }
+}

package/src/main/workMap/workMap.ts

@@ -0,0 +1,244 @@
+import path from 'path'
+import fs from 'fs'
+import os from 'os'
+import type { MapCapability, MapSettings, MapSnapshot, MapSource } from '../../shared/workMap'
+import { initialCapability } from '../../../scripts/check-work-map-gpu.cjs'
+import { TranscriptTailer, supportsTranscriptLogging, type TranscriptTailerOptions } from '../transcripts'
+import { ClefWorker } from './clef'
+import { mapThinkingStatus, normalizeMapEvents } from './normalize'
+import { WorkMapTree } from './tree'
+import { readMapSource } from './source'
+
+interface MapTab {
+  agentId: string
+  agentName: string
+  cwd: string
+  tree: WorkMapTree
+  tailer: TranscriptTailer | null
+  ended: boolean
+  state: string
+  source: string | null
+  ignored: Set<string>
+  pending: Set<string>
+  thinkingStatus: MapSnapshot['thinkingStatus']
+  sources: Map<string, string>
+}
+
+export class WorkMap {
+  private tabs = new Map<string, MapTab>()
+  private owners = new Map<string, string>()
+  private settings: MapSettings
+  private clef: ClefWorker
+  private revision = 0
+  private epoch = 0
+  private timer: ReturnType<typeof setTimeout> | null = null
+  private publishing: ReturnType<typeof setTimeout> | null = null
+  private working = false
+  private round = 0
+
+  constructor(appRoot: string, private onUpdate: (snapshot: MapSnapshot) => void,
+    private roots: Pick<TranscriptTailerOptions, 'claudeProjectsDir' | 'codexSessionsDir'> = {},
+    private capability: MapCapability = initialCapability()) {
+    const cache = path.join(appRoot, 'experiments/live-map/.cache')
+    const prepared = path.join(os.homedir(), '.ctlsurf/clef-flash')
+    const pilotPython = path.join(cache, 'envs/clef-flash/bin/python')
+    this.settings = {
+      enabled: false, engine: 'clef-flash',
+      pythonPath: process.env.CTLSURF_CLEF_PYTHON || (fs.existsSync(pilotPython) ? pilotPython : path.join(prepared, 'env/bin/python')),
+      modelPath: process.env.CTLSURF_CLEF_MODEL || (fs.existsSync(pilotPython) ? path.join(cache, 'models/clef-flash') : path.join(prepared, 'model')),
+    }
+    this.clef = new ClefWorker(path.join(appRoot, 'scripts/work-map-clef.py'), () => this.publish())
+  }
+
+  configure(value: Partial<MapSettings>): MapSettings {
+    ++this.epoch
+    const previous = this.settings
+    this.settings = {
+      enabled: this.capability.state === 'available' && (typeof value.enabled === 'boolean' ? value.enabled : previous.enabled),
+      engine: value.engine === 'rules' || value.engine === 'clef-flash' ? value.engine : previous.engine,
+      pythonPath: typeof value.pythonPath === 'string' && value.pythonPath.trim() ? value.pythonPath.trim() : previous.pythonPath,
+      modelPath: typeof value.modelPath === 'string' && value.modelPath.trim() ? value.modelPath.trim() : previous.modelPath,
+    }
+    this.clef.stop()
+    if (this.timer) clearTimeout(this.timer)
+    this.timer = null
+    for (const tab of this.tabs.values()) {
+      tab.pending.clear()
+      if (this.settings.enabled && !tab.ended) this.start(tab)
+      else { tab.tailer?.stop(); tab.tailer = null; tab.tree.end() }
+      if (this.settings.enabled && this.settings.engine === 'clef-flash') {
+        tab.tree.nodes.filter(n => n.kind === 'step' && n.placement !== 'clef-flash').slice(-24).forEach(n => tab.pending.add(n.id))
+      }
+    }
+    this.publish()
+    this.schedule()
+    return { ...this.settings }
+  }
+
+  attach(tabId: string, agentId: string, agentName: string, cwd: string): void {
+    this.remove(tabId)
+    const tab: MapTab = { agentId, agentName, cwd, tree: new WorkMapTree(), tailer: null, ended: false, state: 'idle', source: null, ignored: new Set(), pending: new Set(), thinkingStatus: 'waiting', sources: new Map() }
+    this.tabs.set(tabId, tab)
+    if (this.settings.enabled) this.start(tab)
+    this.publish()
+  }
+
+  getCapability(): MapCapability {
+    return { ...this.capability }
+  }
+
+  setCapability(capability: MapCapability): void {
+    this.capability = { ...capability }
+    if (capability.state !== 'available') this.configure({ enabled: false })
+    this.publish()
+  }
+
+  end(tabId: string): void {
+    const tab = this.tabs.get(tabId)
+    if (!tab) return
+    tab.ended = true
+    tab.tailer?.stop()
+    tab.tailer = null
+    tab.pending.clear()
+    tab.tree.end()
+    for (const [source, owner] of this.owners) if (owner === tabId) this.owners.delete(source)
+    if (![...this.tabs.values()].some(t => !t.ended)) this.clef.stop()
+    this.publish()
+  }
+
+  remove(tabId: string): void {
+    this.end(tabId)
+    this.tabs.delete(tabId)
+    for (const [source, owner] of this.owners) if (owner === tabId) this.owners.delete(source)
+  }
+
+  clear(tabId: string): void {
+    const tab = this.tabs.get(tabId)
+    if (tab) { tab.tree = new WorkMapTree(); tab.pending.clear() }
+    this.publish()
+  }
+
+  noteState(tabId: string, state: string): void {
+    const tab = this.tabs.get(tabId)
+    if (tab && tab.state !== state) { tab.state = state; this.publish() }
+  }
+
+  snapshot(tabId: string): MapSnapshot {
+    const tab = this.tabs.get(tabId)
+    return {
+      revision: ++this.revision, tabId, agentName: tab?.agentName || null,
+      supported: !!tab && supportsTranscriptLogging(tab.agentId), ended: !!tab?.ended,
+      state: tab?.state || 'idle', settings: { ...this.settings },
+      runtime: !this.settings.enabled ? 'off' : this.settings.engine === 'rules' ? 'ready' : this.clef.state,
+      error: this.settings.engine === 'clef-flash' ? this.clef.error : null,
+      nodes: tab?.tree.nodes || [], dropped: tab?.tree.dropped || 0,
+      thinkingStatus: tab?.thinkingStatus || 'waiting',
+      capability: this.getCapability(),
+    }
+  }
+
+  async getSource(tabId: string, eventId: string): Promise<MapSource | null> {
+    const tab = this.tabs.get(tabId)
+    const event = tab?.tree.nodes.flatMap(n => n.evidence).find(e => e.id === eventId && (e.kind === 'thinking' || e.kind === 'message'))
+    const file = event && tab?.sources.get(event.source)
+    if (!event || !file || !tab) return null
+    return readMapSource(file, tab.agentId, event.id)
+  }
+
+  private start(tab: MapTab): void {
+    if (tab.tailer || !supportsTranscriptLogging(tab.agentId)) return
+    tab.tailer = new TranscriptTailer({
+      ...this.roots,
+      agentId: tab.agentId, cwd: tab.cwd, sink: () => {},
+      rawSink: (raw: any, source) => {
+        if (!source || !this.settings.enabled || tab.ended) return
+        const file = source.filePath
+        if (tab.ignored.has(file)) return
+        if (raw.type === 'session_meta') {
+          const meta = raw.payload || {}
+          if ((meta.thread_source && meta.thread_source !== 'user') || (meta.source && typeof meta.source === 'object') || (meta.agent_path && meta.agent_path !== '/root')) {
+            tab.ignored.add(file)
+            return
+          }
+        }
+        const tabId = [...this.tabs].find(([, candidate]) => candidate === tab)?.[0]
+        if (!tabId) return
+        if (this.owners.has(file) && this.owners.get(file) !== tabId) return
+        // Pin a source; a newly created session (/new or /clear) may replace it.
+        if (tab.source && tab.source !== file) {
+          if (raw.type !== 'session_meta' || Date.parse(raw.payload?.timestamp || raw.timestamp) < source.sinceMs) return
+          this.owners.delete(tab.source)
+        }
+        tab.source = file
+        this.owners.set(file, tabId)
+        const thinking = mapThinkingStatus(raw, tab.agentId)
+        const statusChanged = thinking !== null && thinking !== tab.thinkingStatus && (thinking === 'available' || tab.thinkingStatus === 'waiting')
+        if (statusChanged) tab.thinkingStatus = thinking
+        const events = normalizeMapEvents(raw, file, tab.agentId)
+        for (const e of events) {
+          tab.sources.set(e.source, file)
+          const id = tab.tree.ingest(e)
+          if (id && this.settings.engine === 'clef-flash') {
+            tab.pending.add(id)
+            // A burst cannot create an unbounded inference backlog.
+            if (tab.pending.size > 24) tab.pending.delete(tab.pending.values().next().value!)
+          }
+        }
+        const retainedSources = new Set(tab.tree.nodes.flatMap(n => n.evidence.map(e => e.source)))
+        for (const name of tab.sources.keys()) if (!retainedSources.has(name)) tab.sources.delete(name)
+        if (events.length || statusChanged) { this.publish(); this.schedule() }
+      },
+    })
+    tab.tailer.start()
+  }
+
+  private schedule(): void {
+    if (this.timer || this.working || !this.settings.enabled || this.settings.engine !== 'clef-flash' || this.clef.state === 'error') return
+    if (![...this.tabs.values()].some(t => t.pending.size)) return
+    this.timer = setTimeout(() => { this.timer = null; void this.infer() }, 1000)
+  }
+
+  private async infer(): Promise<void> {
+    const candidates = [...this.tabs].filter(([, t]) => t.pending.size && !t.ended)
+    const candidate = candidates[this.round++ % candidates.length]
+    if (!candidate || !this.settings.enabled || this.settings.engine !== 'clef-flash') return
+    const [tabId, tab] = candidate
+    const tree = tab.tree
+    const ids = [...tab.pending].slice(0, 2)
+    const job = tree.request(ids)
+    const consumed = job?.ids || ids
+    consumed.forEach(id => tab.pending.delete(id))
+    if (!job) { this.schedule(); return }
+    const epoch = this.epoch
+    this.working = true
+    try {
+      const answers = await this.clef.predict(this.settings, job.request)
+      if (epoch === this.epoch && this.tabs.get(tabId) === tab && !tab.ended && tab.tree === tree) tree.apply(job, answers)
+    } catch { /* The worker exposes errors in snapshots; never affect the working agent. */ }
+    finally {
+      this.working = false
+      this.publish()
+      this.schedule()
+    }
+  }
+
+  private publish(): void {
+    if (this.publishing) return
+    this.publishing = setTimeout(() => {
+      this.publishing = null
+      for (const tabId of this.tabs.keys()) this.onUpdate(this.snapshot(tabId))
+    }, 120)
+  }
+
+  shutdown(): void {
+    this.settings.enabled = false
+    ++this.epoch
+    for (const tab of this.tabs.values()) tab.tailer?.stop()
+    this.clef.stop()
+    if (this.timer) clearTimeout(this.timer)
+    if (this.publishing) clearTimeout(this.publishing)
+    this.timer = this.publishing = null
+    this.tabs.clear()
+    this.owners.clear()
+  }
+}

package/src/preload/index.ts

@@ -1,4 +1,5 @@
 import { contextBridge, ipcRenderer } from 'electron'
+import type { MapCapability, MapSettings, MapSnapshot, MapSource } from '../shared/workMap'
 
 export interface AgentConfig {
   id: string
@@ -161,6 +162,22 @@ const api = {
   setSpeakReplies: (enabled: boolean): Promise<{ enabled: boolean }> =>
     ipcRenderer.invoke('speak:set', enabled),
 
+  getWorkMap: (tabId: string): Promise<MapSnapshot> => ipcRenderer.invoke('workmap:get', tabId),
+  getWorkMapCapability: (): Promise<MapCapability> => ipcRenderer.invoke('workmap:capability'),
+  onWorkMapCapability: (callback: (capability: MapCapability) => void) => {
+    const listener = (_event: Electron.IpcRendererEvent, capability: MapCapability) => callback(capability)
+    ipcRenderer.on('workmap:capability', listener)
+    return () => ipcRenderer.removeListener('workmap:capability', listener)
+  },
+  getWorkMapSource: (tabId: string, eventId: string): Promise<MapSource | null> => ipcRenderer.invoke('workmap:source', tabId, eventId),
+  setWorkMap: (tabId: string, settings: Partial<MapSettings>): Promise<MapSnapshot> => ipcRenderer.invoke('workmap:set', tabId, settings),
+  clearWorkMap: (tabId: string): Promise<MapSnapshot> => ipcRenderer.invoke('workmap:clear', tabId),
+  onWorkMapUpdate: (callback: (snapshot: MapSnapshot) => void) => {
+    const listener = (_event: Electron.IpcRendererEvent, snapshot: MapSnapshot) => callback(snapshot)
+    ipcRenderer.on('workmap:update', listener)
+    return () => ipcRenderer.removeListener('workmap:update', listener)
+  },
+
   // Observer supervision layer (global). The API key is write-only over IPC:
   // the getter reports only whether one is configured and from where.
   getObserverSettings: (): Promise<{ enabled: boolean; hasApiKey: boolean; keySource: 'settings' | 'env' | null; dailyCapUsd: number }> =>

package/src/renderer/App.tsx

@@ -17,7 +17,9 @@ import { StatusBar } from './components/StatusBar'
 import type { ResourceSnapshot } from './components/Resources'
 import { SettingsDialog } from './components/SettingsDialog'
 import { TicketPane } from './components/TicketPanel'
-import { ObserverPane } from './components/ObserverPanel'
+import { WorkMapPanel } from './components/WorkMapPanel'
+import { WorkMapToggle, canOpenWorkMap } from './components/WorkMapToggle'
+import type { MapCapability, MapSettings, MapSnapshot, MapSource } from '../shared/workMap'
 
 interface AgentConfig {
   id: string
@@ -71,6 +73,13 @@ declare global {
       getLogChat: () => Promise<{ enabled: boolean }>
       setLogChat: (enabled: boolean) => Promise<{ enabled: boolean }>
       getSpeakReplies: () => Promise<{ enabled: boolean }>
+      getWorkMap: (tabId: string) => Promise<MapSnapshot>
+      getWorkMapCapability: () => Promise<MapCapability>
+      onWorkMapCapability: (callback: (capability: MapCapability) => void) => () => void
+      getWorkMapSource: (tabId: string, eventId: string) => Promise<MapSource | null>
+      setWorkMap: (tabId: string, settings: Partial<MapSettings>) => Promise<MapSnapshot>
+      clearWorkMap: (tabId: string) => Promise<MapSnapshot>
+      onWorkMapUpdate: (callback: (snapshot: MapSnapshot) => void) => () => void
       setSpeakReplies: (enabled: boolean) => Promise<{ enabled: boolean }>
       getObserverSettings: () => Promise<{ enabled: boolean; hasApiKey: boolean; keySource: 'settings' | 'env' | null; dailyCapUsd: number }>
       setObserverSettings: (data: { enabled: boolean; anthropicApiKey?: string; dailyCapUsd?: number; sensitivity?: 'severe' | 'balanced' | 'all' }) => Promise<{ enabled: boolean; hasApiKey: boolean; keySource: 'settings' | 'env' | null; dailyCapUsd: number }>
@@ -520,6 +529,7 @@ export default function App() {
 
   // Toggle pane: hide removes from layout tree, show re-inserts
   const togglePane = useCallback((id: string) => {
+    if (id === 'workmap' && !visiblePaneIds.includes(id) && !canOpenWorkMap()) return
     if (visiblePaneIds.includes(id)) {
       // Hide: remove from tree
       const newLayout = removePane(layout, id)
@@ -575,6 +585,7 @@ export default function App() {
           case 'T': e.preventDefault(); togglePane('terminal'); break
           case 'P': e.preventDefault(); togglePane('ctlsurf'); break
           case 'K': e.preventDefault(); togglePane('tickets'); break
+          case 'M': e.preventDefault(); togglePane('workmap'); break
         }
       }
     }
@@ -670,7 +681,7 @@ export default function App() {
     },
     { id: 'ctlsurf', label: 'ctlsurf', content: <CtlsurfPanel navigate={ctlsurfNav} /> },
     { id: 'tickets', label: 'Tickets', content: <TicketPane onSendToTerminal={handleSendToTerminal} /> },
-    { id: 'observer', label: 'Observer', content: <ObserverPane /> },
+    { id: 'workmap', label: 'Work map', content: <WorkMapPanel key={activeTabId} tabId={activeTabId} /> },
   ]
 
   return (
@@ -707,20 +718,6 @@ export default function App() {
             </svg>
             <span>Tickets</span>
           </button>
-          <button
-            className={`titlebar-btn titlebar-icon-btn ${visiblePaneIds.includes('observer') ? 'active' : ''}`}
-            onClick={() => togglePane('observer')}
-            title="Toggle Observer pane — live session review"
-            aria-label="Observer"
-          >
-            <svg viewBox="0 0 24 24" width="13" height="13"
-              fill="none" stroke="currentColor" strokeWidth="2"
-              strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
-              <path d="M1 12s4-8 11-8 11 8 11 8-4 8-11 8-11-8-11-8z" />
-              <circle cx="12" cy="12" r="3" />
-            </svg>
-            <span>Observer</span>
-          </button>
           <button
             className={`titlebar-btn titlebar-icon-btn ${showFloatingMic ? 'active' : ''}`}
             onClick={() => setFloatingMicVisible(!showFloatingMic)}
@@ -735,6 +732,8 @@ export default function App() {
               <line x1="8" y1="23" x2="16" y2="23" />
             </svg>
           </button>
+          <WorkMapToggle visible={visiblePaneIds.includes('workmap')} onToggle={() => togglePane('workmap')}
+            onUnavailable={() => setLayout(previous => removePane(previous, 'workmap') || { type: 'leaf', paneId: 'terminal' })} />
           <SpeakControls remote={activeAgentIsRemote} />
           <span className="titlebar-separator" />
           <button

package/src/renderer/components/ObserverPanel.tsx

@@ -1,6 +1,9 @@
 import { useState, useEffect, useCallback } from 'react'
 
 /**
+ * ON HOLD: retained for future work; not mounted in the app or exposed in Settings.
+ * Runtime is disabled by OBSERVER_ON_HOLD in the orchestrator.
+ *
  * Observer side pane — live supervision feed for the current session.
  *
  * Shares the drawer chrome with the Tickets pane but renders its own card