@phenx-inc/ctlsurf 0.17.2 → 0.17.3

package/scripts/test-work-map.cjs

@@ -0,0 +1,352 @@
+// Exercise native transcript ingestion, evidence linkage, bounds, and the model process lifecycle.
+const assert = require('node:assert/strict')
+const fs = require('node:fs/promises')
+const os = require('node:os')
+const path = require('node:path')
+const { build } = require('esbuild')
+const { once } = require('node:events')
+const { createReadStream } = require('node:fs')
+const { createInterface } = require('node:readline')
+const pause = ms => new Promise(resolve => setTimeout(resolve, ms))
+
+async function until(check, timeout = 7000) {
+  const end = Date.now() + timeout
+  while (Date.now() < end) { if (check()) return; await pause(40) }
+  assert.fail('Timed out waiting for work map state')
+}
+
+async function main() {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'ctlsurf-map-'))
+  const repo = path.resolve(__dirname, '..')
+  let map
+  let worker
+  let tailer
+  try {
+    await build({ stdin: { contents: `export { WorkMapTree, MAP_NODE_LIMIT } from './src/main/workMap/tree';
+      export { normalizeMapEvents, mapThinkingStatus } from './src/main/workMap/normalize';
+      export { ClefWorker, validateDecisions } from './src/main/workMap/clef';
+      export { WorkMap } from './src/main/workMap/workMap';
+      export { TranscriptTailer } from './src/main/transcripts';
+      export { readMapSource } from './src/main/workMap/source';
+      export { thinkingHighlights } from './src/renderer/lib/workMapHighlights';`, resolveDir: repo },
+      bundle: true, platform: 'node', format: 'cjs', outfile: path.join(root, 'map.cjs') })
+    const { WorkMapTree, MAP_NODE_LIMIT, normalizeMapEvents, mapThinkingStatus, ClefWorker, validateDecisions, WorkMap, TranscriptTailer, readMapSource, thinkingHighlights } = require(path.join(root, 'map.cjs'))
+    const unavailableMap = new WorkMap(root, () => {})
+    unavailableMap.configure({ enabled: true, engine: 'clef-flash' })
+    unavailableMap.attach('headless-tab', 'codex', 'Codex', '/headless')
+    assert.equal(unavailableMap.snapshot('headless-tab').settings.enabled, false)
+    assert.equal(unavailableMap.snapshot('headless-tab').capability.state, 'unavailable')
+    assert.equal(unavailableMap.tabs.get('headless-tab').tailer, null, 'saved settings cannot activate collection in terminal mode')
+    assert.equal(unavailableMap.clef.child, null)
+    unavailableMap.shutdown()
+    const timestamp = new Date().toISOString()
+    const normalize = raw => normalizeMapEvents({ timestamp, ...raw }, 'session.jsonl', 'claude')
+    const tree = new WorkMapTree()
+    for (const e of normalize({ type: 'user', uuid: 'u', message: { content: 'Fix terminal scrolling' } })) tree.ingest(e)
+    for (const e of normalize({ type: 'assistant', message: { content: [{ type: 'tool_use', id: 'test-1', name: 'Bash', input: { command: 'npm test' } }] } })) tree.ingest(e)
+    for (const e of normalize({ type: 'user', message: { content: [{ type: 'tool_result', tool_use_id: 'test-1', is_error: true, content: 'All tests passed (misleading output)' }] } })) tree.ingest(e)
+    const step = tree.nodes.find(n => n.kind === 'step')
+    assert.equal(step.status, 'failed')
+    assert.equal(step.evidence.length, 2)
+    const job = tree.request([step.id])
+    const previousBranch = step.parentId
+    const answers = Object.fromEntries(Object.entries(job.request.questions).map(([key, q]) => {
+      const choice = key.startsWith('branch') ? 'new_topic' : 'editing'
+      return [key, { choice, probabilities: Object.fromEntries(Object.keys(q.criteria).map(k => [k, +(k === choice)])) }]
+    }))
+    validateDecisions({ answers }, job.request)
+    tree.apply(job, answers)
+    assert.equal(step.status, 'failed', 'model suggestions cannot overwrite runtime failures')
+    assert.equal(step.placement, 'clef-flash')
+    assert.notEqual(step.parentId, previousBranch, 'a new-topic decision must create an actual fork')
+    assert.throws(() => validateDecisions({ answers: { ...answers, invented: {} } }, job.request))
+    assert.throws(() => validateDecisions({ answers: { ...answers, branch_0: { choice: 'invented', probabilities: {} } } }, job.request))
+    assert.deepEqual(normalizeMapEvents({ type: 'response_item', payload: { type: 'reasoning', encrypted_content: 'private' } }, 'x', 'codex'), [])
+    assert.deepEqual(normalizeMapEvents({ type: 'response_item', payload: { type: 'message', role: 'developer', content: [{ type: 'input_text', text: 'injected' }] } }, 'x', 'codex'), [])
+    const modern = normalizeMapEvents({ timestamp, type: 'event_msg', payload: { type: 'item_completed', item: {
+      type: 'CommandExecution', id: 'command-1', command: ['npm', 'test'], status: 'completed', exit_code: 0, aggregated_output: 'The word FAILED is just fixture text',
+    } } }, 'codex.jsonl', 'codex')
+    assert.equal(modern.length, 2)
+    assert.equal(modern[1].status, 'succeeded')
+    const unknown = normalizeMapEvents({ timestamp, type: 'response_item', payload: { type: 'function_call_output', call_id: 'x', output: 'Looks successful' } }, 'codex.jsonl', 'codex')
+    assert.equal(unknown[0].status, 'unknown')
+    const cli = normalizeMapEvents({ timestamp, type: 'response_item', payload: { type: 'function_call_output', call_id: 'x', output: 'Process exited with code 2' } }, 'codex.jsonl', 'codex')
+    assert.equal(cli[0].status, 'failed')
+
+    const thinkingText = 'The likely cause is a stale viewport flag. I will preserve the reader position instead of forcing the viewport down. Next I will check the scroll regression.'
+    const claudeThought = { timestamp, type: 'assistant', uuid: 'thought-message', message: { content: [{ type: 'thinking', thinking: thinkingText, signature: 'SECRET_SIGNATURE' }] } }
+    const codexThought = { timestamp, type: 'response_item', payload: { type: 'reasoning', id: 'thought-1', summary: [{ type: 'summary_text', text: thinkingText }], encrypted_content: 'SECRET_ENCRYPTED' } }
+    const completedThought = { timestamp, type: 'event_msg', payload: { type: 'item_completed', item: { type: 'Reasoning', id: 'thought-1', summary_text: [thinkingText], raw_content: ['SECRET_RAW'] } } }
+    const jsonRpcThought = { timestamp, method: 'item/completed', params: { item: { type: 'reasoning', id: 'thought-1', summary: [thinkingText], content: ['SECRET_RAW'] } } }
+    const legacyThought = { timestamp, type: 'event_msg', payload: { type: 'agent_reasoning', text: thinkingText } }
+    const intentTrees = []
+    for (const [agent, record] of [['claude', claudeThought], ['codex', codexThought], ['codex', completedThought], ['codex', jsonRpcThought], ['codex', legacyThought]]) {
+      const events = normalizeMapEvents(record, 'thinking.jsonl', agent)
+      assert.equal(events.length, 1)
+      assert.equal(events[0].kind, 'thinking')
+      assert.equal(events[0].text, thinkingText)
+      assert(!JSON.stringify(events).includes('SECRET_'), 'signatures, raw content, and encrypted reasoning never reach the map')
+      assert.equal(mapThinkingStatus(record, agent), 'available')
+      const intentTree = new WorkMapTree()
+      const thoughtId = intentTree.ingest(events[0])
+      const thoughtJob = intentTree.request([thoughtId])
+      const statement = thoughtJob.statements[thoughtId].findIndex(s => s.includes('preserve'))
+      assert(statement >= 0)
+      const selections = Object.fromEntries(Object.entries(thoughtJob.request.questions).map(([key, q]) => {
+        const choice = key.startsWith('statement') ? `s${statement}` : key.startsWith('intent') ? 'hypothesis' : Object.keys(q.criteria)[0]
+        return [key, { choice, probabilities: Object.fromEntries(Object.keys(q.criteria).map(k => [k, +(k === choice)])) }]
+      }))
+      validateDecisions({ answers: selections }, thoughtJob.request)
+      intentTree.apply(thoughtJob, selections)
+      const thoughtNode = intentTree.nodes.find(n => n.id === thoughtId)
+      assert.equal(thoughtNode.activity, 'thinking')
+      assert.equal(thoughtNode.intent, 'decision', 'a model label cannot contradict explicit wording in the selected excerpt')
+      assert.match(thoughtNode.title, /preserve/)
+      assert.equal(thoughtNode.focus.text, thoughtJob.statements[thoughtId][statement])
+      assert.equal(thoughtNode.status, 'unknown', 'thinking must not count as a verified outcome')
+      const actionId = intentTree.ingest({ id: 'following-action', kind: 'tool', source: 'thinking.jsonl', ts: timestamp, tool: 'Read', text: 'src/terminal.ts', status: 'running' })
+      assert.equal(intentTree.nodes.find(n => n.id === actionId).contextId, thoughtId)
+      const actionState = JSON.parse(intentTree.request([actionId]).request.state)
+      assert.equal(actionState.events[0].preceding_intent, thinkingText)
+      intentTrees.push(intentTree)
+    }
+    const duplicateTree = new WorkMapTree()
+    for (const record of [codexThought, completedThought, jsonRpcThought, legacyThought]) {
+      for (const e of normalizeMapEvents(record, 'thinking.jsonl', 'codex')) duplicateTree.ingest(e)
+    }
+    assert.equal(duplicateTree.nodes.filter(n => n.activity === 'thinking').length, 1)
+    const redacted = { type: 'assistant', message: { content: [{ type: 'redacted_thinking', data: 'SECRET_REDACTED' }] } }
+    assert.deepEqual(normalizeMapEvents(redacted, 'x', 'claude'), [])
+    assert.equal(mapThinkingStatus(redacted, 'claude'), 'unavailable')
+    const omitted = { type: 'response_item', payload: { type: 'reasoning', summary: [], encrypted_content: 'SECRET_ENCRYPTED' } }
+    assert.deepEqual(normalizeMapEvents(omitted, 'x', 'codex'), [])
+    assert.equal(mapThinkingStatus(omitted, 'codex'), 'unavailable')
+    assert.deepEqual(normalizeMapEvents({ type: 'event_msg', payload: { type: 'agent_reasoning_raw_content', text: 'SECRET_RAW' } }, 'x', 'codex'), [])
+    console.log('PASS Claude thinking, Codex summary formats, decision excerpts, action context, deduplication and omitted thinking')
+
+    const longThinking = 'Background detail. '.repeat(150) + 'I will choose curses instead of installing pygame. Because it avoids third-party dependencies. ' + 'More routine detail. '.repeat(150)
+    const fullBlock = normalizeMapEvents({ ...claudeThought, message: { content: [{ type: 'thinking', thinking: longThinking }] } }, 'middle.jsonl', 'claude')[0]
+    assert(!fullBlock.text.includes('choose curses'))
+    assert(fullBlock.segments.some(s => s.includes('choose curses')), 'important middle segments survive display truncation')
+    const snakeText = 'Building it as a single snake.py with only the standard library, so nothing gets installed into the virtual environment.'
+    const snakeUpdate = normalizeMapEvents({ timestamp, type: 'assistant', uuid: 'snake-choice', message: { content: [{ type: 'text', text: snakeText }] } }, 'snake.jsonl', 'claude')[0]
+    const snakeTree = new WorkMapTree()
+    const snakeId = snakeTree.ingest(snakeUpdate)
+    const snakeJob = snakeTree.request([snakeId])
+    const snakeStatement = snakeJob.statements[snakeId].findIndex(s => s.includes('Building'))
+    const snakeReason = snakeJob.reasons[snakeId].findIndex(s => s.startsWith('so nothing'))
+    assert(snakeStatement >= 0 && snakeReason >= 0)
+    const snakeAnswers = Object.fromEntries(Object.entries(snakeJob.request.questions).map(([key, q]) => {
+      const choice = key.startsWith('statement') ? `s${snakeStatement}` : key.startsWith('reason') ? `r${snakeReason}` : key.startsWith('intent') ? 'decision' : Object.keys(q.criteria)[0]
+      return [key, { choice, probabilities: Object.fromEntries(Object.keys(q.criteria).map(k => [k, +(k === choice)])) }]
+    }))
+    validateDecisions({ answers: snakeAnswers }, snakeJob.request)
+    snakeTree.apply(snakeJob, snakeAnswers)
+    const snakeNode = snakeTree.nodes.find(n => n.id === snakeId)
+    assert.equal(snakeNode.intent, 'decision')
+    assert.equal(snakeNode.evidence[0].kind, 'message', 'a stated update is not mislabeled as private thinking')
+    assert.match(snakeNode.focus.text, /single snake.py/)
+    assert.match(snakeNode.focus.reason, /nothing gets installed/)
+    const snakeAction = snakeTree.ingest({ id: 'write-snake', kind: 'tool', tool: 'Write', text: 'snake.py', source: 'snake.jsonl', ts: timestamp })
+    assert.equal(snakeTree.nodes.find(n => n.id === snakeAction).contextId, snakeId)
+    const sourceText = 'Before the choice.\n**I will use `curses`** for rendering,\n  because it avoids dependencies.\nAfter the choice.'
+    const ranges = thinkingHighlights(sourceText, { text: 'I will use curses', reason: 'because it avoids dependencies.' })
+    assert.equal(ranges.length, 2)
+    assert.equal(sourceText.slice(ranges[0].start, ranges[0].end), '**I will use `curses`**')
+    assert.equal(sourceText.slice(ranges[1].start, ranges[1].end), 'because it avoids dependencies.')
+    assert.deepEqual(thinkingHighlights(sourceText, { text: 'An invented choice' }), [])
+    const sourceFile = path.join(root, 'full-thinking.jsonl')
+    const sourceRecord = { ...claudeThought, message: { content: [{ type: 'thinking', thinking: longThinking, signature: 'SECRET_SIGNATURE' }] } }
+    await fs.writeFile(sourceFile, JSON.stringify(sourceRecord) + '\n')
+    const sourceEvent = normalizeMapEvents(sourceRecord, sourceFile, 'claude')[0]
+    assert.equal(sourceEvent.fullText, undefined, 'full thinking stays out of live snapshots')
+    const fullSource = await readMapSource(sourceFile, 'claude', sourceEvent.id)
+    assert.equal(fullSource.text, longThinking.trim())
+    assert(!fullSource.text.includes('SECRET_SIGNATURE'))
+    assert.equal(await readMapSource(sourceFile, 'claude', 'missing-event'), null)
+    console.log('PASS full-block segment selection and snake-game choice with its stated reason')
+
+    for (const agent of ['claude', 'codex']) {
+      const index = process.argv.indexOf(`--replay-${agent}`)
+      if (index < 0) continue
+      const file = process.argv[index + 1]
+      assert(file && !file.startsWith('--'), 'Replay requires a transcript file path')
+      const replayTree = new WorkMapTree()
+      let records = 0, readableThoughts = 0, omittedThoughts = 0, decisions = 0
+      for await (const line of createInterface({ input: createReadStream(file), crlfDelay: Infinity })) {
+        let raw
+        try { raw = JSON.parse(line) } catch { continue }
+        records++
+        if (mapThinkingStatus(raw, agent) === 'unavailable') omittedThoughts++
+        for (const e of normalizeMapEvents(raw, file, agent)) {
+          const id = replayTree.ingest(e)
+          if (id && e.kind === 'thinking') readableThoughts++
+          if (id && replayTree.nodes.find(n => n.id === id)?.intent !== undefined && replayTree.nodes.find(n => n.id === id)?.intent !== 'context') decisions++
+        }
+      }
+      console.log('LOCAL REPLAY', JSON.stringify({ agent, records, readableThoughts, omittedThoughts, statedChoicesOrHypotheses: decisions }))
+    }
+    for (let i = 0; i < 1000; i++) {
+      tree.ingest({ id: `prompt-${i}`, kind: 'prompt', ts: timestamp, text: `Goal ${i}`, source: 'x' })
+      tree.ingest({ id: `tool-${i}`, kind: 'tool', ts: timestamp, text: `src/work-${i}.ts`, tool: 'Read', toolId: `tool-${i}`, source: 'x', status: 'running' })
+    }
+    assert(tree.nodes.length <= MAP_NODE_LIMIT)
+    const ids = new Set(tree.nodes.map(n => n.id))
+    assert(tree.nodes.every(n => !n.parentId || ids.has(n.parentId)), 'pruning leaves no orphan branches')
+    assert(tree.dropped > 0)
+    tree.end()
+    assert(!tree.nodes.some(n => n.status === 'running'))
+    console.log('PASS event normalization, linked outcomes, validated decisions, bounded trees')
+
+    const sessions = path.join(root, 'sessions')
+    const d = new Date()
+    const dateDir = path.join(sessions, String(d.getFullYear()), String(d.getMonth() + 1).padStart(2, '0'), String(d.getDate()).padStart(2, '0'))
+    await fs.mkdir(dateDir, { recursive: true })
+    const lines = events => events.map(e => JSON.stringify({ timestamp: new Date().toISOString(), ...e })).join('\n') + '\n'
+    const native = path.join(dateDir, 'rollout-main.jsonl')
+    const nativeEvents = [
+      { type: 'session_meta', payload: { cwd: '/project', thread_source: 'user', timestamp } },
+      { type: 'response_item', payload: { type: 'message', role: 'user', content: [{ type: 'input_text', text: 'Fix terminal scrolling' }] } },
+      { ...codexThought, timestamp: undefined },
+      { ...completedThought, timestamp: undefined },
+      { type: 'response_item', payload: { type: 'function_call', call_id: 'read-1', name: 'read_file', arguments: JSON.stringify({ file_path: 'src/terminal.ts' }) } },
+      { type: 'response_item', payload: { type: 'function_call_output', call_id: 'read-1', output: 'Process exited with code 0' } },
+    ]
+    await fs.writeFile(native, lines(nativeEvents))
+    await fs.writeFile(path.join(dateDir, 'rollout-foreign.jsonl'), lines([
+      { type: 'session_meta', payload: { cwd: '/other' } },
+      { type: 'response_item', payload: { type: 'function_call', call_id: 'foreign', name: 'read_file', arguments: '{}' } },
+    ]))
+    const raw = []
+    tailer = new TranscriptTailer({ agentId: 'codex', cwd: '/project', codexSessionsDir: sessions, sink() {}, rawSink: e => raw.push(e) })
+    tailer.start()
+    await until(() => raw.length >= nativeEvents.length)
+    assert(!raw.some(e => e.payload?.call_id === 'foreign' || e.payload?.cwd === '/other'))
+    // A very long line without a newline cannot grow the tailer's buffer indefinitely.
+    await fs.appendFile(native, 'x'.repeat(2 * 1024 * 1024) + '\n' + lines([{ type: 'event_msg', payload: { type: 'agent_message', message: 'After the oversized line' } }]))
+    await until(() => raw.some(e => e.payload?.message === 'After the oversized line'), 9000)
+    assert([...tailer.files.values()].every(f => f.remainder.length <= 1024 * 1024))
+    tailer.stop(); tailer = null
+    console.log('PASS project isolation and bounded transcript reading')
+
+    if (process.platform !== 'darwin' || process.arch !== 'arm64') {
+      console.log('SKIP local MLX process checks: Apple Silicon required')
+      return
+    }
+
+    // A tiny protocol fixture exercises cancellation and process cleanup without loading weights.
+    await fs.mkdir(path.join(root, 'scripts'))
+    const fake = path.join(root, 'scripts/work-map-clef.py')
+    await fs.writeFile(fake, `import json,sys,time\nprint(json.dumps({'ready':True}),flush=True)\nfor line in sys.stdin:\n r=json.loads(line); answers={}\n for k,q in r['request']['questions'].items():\n  choice=next(iter(q['criteria'])); answers[k]={'choice':choice,'probabilities':{o:int(o==choice) for o in q['criteria']}}\n time.sleep(.1)\n print(json.dumps({'id':r['id'],'answers':answers}),flush=True)\n`)
+    await fs.mkdir(path.join(root, 'model'))
+    await fs.writeFile(path.join(root, 'model/clef_mlx.py'), '')
+    const settings = { enabled: true, engine: 'clef-flash', pythonPath: '/usr/bin/python3', modelPath: path.join(root, 'model') }
+    worker = new ClefWorker(fake, () => {})
+    const req = { model: 'clef-flash', state: 'Example', questions: { topic: { type: 'choice', instructions: 'Pick', criteria: { a: 'A', b: 'B' } } } }
+    await worker.predict(settings, req)
+    const child = worker.child
+    const closed = once(child, 'close')
+    worker.stop()
+    await closed
+    assert.equal(worker.state, 'idle')
+    assert.equal(worker.child, null)
+    await assert.rejects(worker.predict({ ...settings, pythonPath: '/missing/python' }, req))
+    assert.equal(worker.state, 'error')
+    assert.match(worker.error, /runtime not found/)
+    worker.stop()
+    const cancelled = worker.predict(settings, req)
+    worker.stop()
+    await assert.rejects(cancelled)
+    assert.equal(worker.state, 'idle', 'off must not become an error when an old request settles')
+    const inFlight = worker.predict(settings, req)
+    await until(() => worker.state === 'thinking')
+    const runningChild = worker.child
+    const runningClosed = once(runningChild, 'close')
+    worker.stop()
+    await assert.rejects(inFlight)
+    await runningClosed
+    assert.equal(worker.state, 'idle', 'in-flight cancellation must release the process without a stale error')
+    worker.stop(); worker = null
+
+    await fs.writeFile(native, lines(nativeEvents))
+    await fs.writeFile(path.join(dateDir, 'rollout-foreign.jsonl'), lines([
+      { type: 'session_meta', payload: { cwd: '/other' } },
+      { type: 'response_item', payload: { type: 'function_call', call_id: 'foreign', name: 'read_file', arguments: '{}' } },
+    ]))
+    await fs.writeFile(path.join(dateDir, 'rollout-guardian.jsonl'), lines([
+      { type: 'session_meta', payload: { cwd: '/project', thread_source: 'guardian' } },
+      { type: 'response_item', payload: { type: 'function_call', call_id: 'guardian', name: 'read_file', arguments: '{}' } },
+    ]))
+    await fs.writeFile(path.join(dateDir, 'rollout-omitted.jsonl'), lines([
+      { type: 'session_meta', payload: { cwd: '/omitted-project' } }, omitted,
+    ]))
+    const claudeProjectsDir = path.join(root, 'claude')
+    await fs.mkdir(path.join(claudeProjectsDir, '-claude-project'), { recursive: true })
+    await fs.writeFile(path.join(claudeProjectsDir, '-claude-project/session.jsonl'), lines([
+      { ...claudeThought, timestamp: new Date().toISOString(), cwd: '/claude-project' },
+    ]))
+    map = new WorkMap(root, () => {}, { codexSessionsDir: sessions, claudeProjectsDir }, { state: 'available', reason: null, gpuName: 'Test GPU' })
+    map.configure(settings)
+    map.attach('tab-a', 'codex', 'Codex', '/project')
+    map.attach('tab-b', 'codex', 'Codex', '/other')
+    map.attach('tab-c', 'claude', 'Claude Code', '/claude-project')
+    map.attach('tab-omitted', 'codex', 'Codex', '/omitted-project')
+    await until(() => map.snapshot('tab-a').nodes.some(n => n.placement === 'clef-flash'), 12000)
+    assert(!map.snapshot('tab-a').nodes.some(n => n.evidence.some(e => e.toolId === 'foreign')))
+    assert(!map.snapshot('tab-a').nodes.some(n => n.evidence.some(e => e.toolId === 'guardian')))
+    assert(map.snapshot('tab-b').nodes.some(n => n.evidence.some(e => e.toolId === 'foreign')))
+    assert(map.snapshot('tab-a').nodes.some(n => n.status === 'succeeded'))
+    await until(() => map.snapshot('tab-c').nodes.some(n => n.placement === 'clef-flash'), 12000)
+    assert.equal(map.snapshot('tab-a').thinkingStatus, 'available')
+    assert.equal(map.snapshot('tab-c').thinkingStatus, 'available')
+    assert.equal(map.snapshot('tab-omitted').thinkingStatus, 'unavailable')
+    assert.equal(map.snapshot('tab-omitted').nodes.length, 0)
+    const mappedThought = map.snapshot('tab-c').nodes.find(n => n.evidence[0]?.kind === 'thinking').evidence[0]
+    assert.equal((await map.getSource('tab-c', mappedThought.id)).text, thinkingText)
+    assert.equal(await map.getSource('tab-b', mappedThought.id), null, 'a different tab cannot fetch this source record')
+    map.configure({ enabled: false })
+    const count = map.snapshot('tab-a').nodes.length
+    await fs.appendFile(native, lines([{ type: 'response_item', payload: { type: 'message', role: 'assistant', content: [{ type: 'output_text', text: 'This arrives while off' }] } }]))
+    await pause(1200)
+    assert.equal(map.snapshot('tab-a').nodes.length, count)
+    assert.equal(map.snapshot('tab-a').runtime, 'off')
+    assert.equal(map.clef.child, null)
+    map.clear('tab-a')
+    assert.equal(map.snapshot('tab-a').nodes.length, 0)
+    map.attach('tab-a', 'shell', 'Shell', '/project')
+    assert.equal(map.snapshot('tab-a').supported, false)
+    map.shutdown(); map = null
+    console.log('PASS Clef protocol, cancellation, error recovery, tab isolation, off and clear')
+    if (process.argv.includes('--real-clef')) {
+      const cache = path.join(repo, 'experiments/live-map/.cache')
+      worker = new ClefWorker(path.join(repo, 'scripts/work-map-clef.py'), () => {})
+      const intentTree = intentTrees[0]
+      const intentNode = intentTree.nodes.find(n => n.activity === 'thinking')
+      const intentJob = intentTree.request([intentNode.id])
+      const answer = await worker.predict({ enabled: true, engine: 'clef-flash',
+        pythonPath: path.join(cache, 'envs/clef-flash/bin/python'), modelPath: path.join(cache, 'models/clef-flash'),
+      }, intentJob.request)
+      intentTree.apply(intentJob, answer)
+      const realSnakeJob = snakeTree.request([snakeId])
+      const realSnakeAnswer = await worker.predict({ enabled: true, engine: 'clef-flash',
+        pythonPath: path.join(cache, 'envs/clef-flash/bin/python'), modelPath: path.join(cache, 'models/clef-flash'),
+      }, realSnakeJob.request)
+      snakeTree.apply(realSnakeJob, realSnakeAnswer)
+      assert(snakeUpdate.segments.includes(snakeNode.focus.text))
+      if (snakeNode.focus.reason) assert(snakeUpdate.segments.includes(snakeNode.focus.reason))
+      const process = worker.child
+      const closed = once(process, 'close')
+      worker.stop()
+      await closed
+      worker = null
+      assert(answer.branch_0.choice)
+      assert(intentJob.statements[intentNode.id].some(s => s.startsWith(intentNode.title.replace(/…$/, ''))))
+      console.log('PASS real offline Clef-Flash choice/reason extraction and unload:', JSON.stringify({ selectedExcerpt: answer.statement_0.choice, displayedIntent: intentNode.intent, snakeIntent: snakeNode.intent, snakeHasReason: !!snakeNode.focus.reason }))
+    }
+  } finally {
+    tailer?.stop(); map?.shutdown(); worker?.stop()
+    await fs.rm(root, { recursive: true, force: true })
+  }
+}
+
+main().catch(err => { console.error(err); process.exitCode = 1 })

package/scripts/work-map-clef.py

@@ -0,0 +1,81 @@
+"""Offline JSONL worker for the live work map. One request at a time; no HTTP listener."""
+import contextlib
+import copy
+import json
+import os
+from pathlib import Path
+import sys
+import time
+import resource
+import threading
+
+
+def emit(value):
+    print(json.dumps(value), flush=True)
+
+
+def guard_memory():
+    # Inspect our own RSS; no ps subprocess or OS process-inspection permission needed.
+    while True:
+        peak_rss = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+        rss_bytes = peak_rss if sys.platform == 'darwin' else peak_rss * 1024
+        if rss_bytes > 16 * 1024 ** 3:
+            emit({'error': 'Clef exceeded the 16 GiB process memory budget and was unloaded.'})
+            os._exit(1)
+        time.sleep(1)
+
+
+def budget_request(request, tokenizer, encode_record):
+    """Keep the typed schema and at least 256 state tokens within the fixed context budget."""
+    for length in (320, 240, 160, 100, 64, 40):
+        bounded = copy.deepcopy(request)
+        for question in bounded['questions'].values():
+            question['criteria'] = {key: text[:length] for key, text in question['criteria'].items()}
+        try:
+            encode_record(tokenizer, bounded, max_length=1792, truncate=True)
+            return bounded
+        except ValueError as exc:
+            if 'schema requires' not in str(exc):
+                raise
+    raise ValueError('Work-map schema cannot fit in its token budget')
+
+
+def main():
+    model_path = Path(sys.argv[1]).resolve(strict=True)
+    threading.Thread(target=guard_memory, daemon=True).start()
+    # Set before importing any Hub/tokenizer code. Never download during inference.
+    os.environ.update(HF_HUB_OFFLINE="1", TRANSFORMERS_OFFLINE="1", HF_HUB_DISABLE_TELEMETRY="1",
+                      TOKENIZERS_PARALLELISM="false", DO_NOT_TRACK="1",
+                      HF_HOME=str(model_path.parent / '.runtime-cache'),
+                      XDG_CACHE_HOME=str(model_path.parent / '.runtime-cache'))
+    with contextlib.redirect_stdout(sys.stderr):
+        import mlx.core as mx
+        mx.set_memory_limit(14 * 1024 ** 3)
+        mx.set_cache_limit(256 * 1024 ** 2)
+        sys.path.insert(0, str(model_path))
+        import clef_mlx
+        model = clef_mlx.load(model_path)
+    emit({"ready": True})
+    for line in sys.stdin:
+        req = {}
+        try:
+            if len(line) > 32_000:
+                raise ValueError("Work-map request exceeded its input budget")
+            req = json.loads(line)
+            start = time.monotonic()
+            with contextlib.redirect_stdout(sys.stderr):
+                request = budget_request(req['request'], model.tokenizer, clef_mlx.encode_record)
+                response = model.systemone(request, max_length=2048, truncate=True)
+                mx.clear_cache()
+            emit({"id": req["id"], "answers": response["answers"],
+                  "latency_ms": round((time.monotonic() - start) * 1000)})
+        except Exception as exc:
+            emit({"id": req.get("id"), "error": f"{type(exc).__name__}: {exc}"[:600]})
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as exc:
+        emit({"error": f"{type(exc).__name__}: {exc}"[:600]})
+        sys.exit(1)

package/src/main/index.ts

@@ -25,6 +25,8 @@ function log(...args: unknown[]): void {
 import { AgentConfig, getDefaultAgent, getAvailableAgents } from './agents'
 import { getSettingsDir } from './settingsDir'
 import { Orchestrator } from './orchestrator'
+import type { MapSettings } from '../shared/workMap'
+import { detectCapability, usableElectronGpu } from '../../scripts/check-work-map-gpu.cjs'
 import { AttentionController } from './agentState'
 import { listSshHosts, getRecentHosts, addRecentHost, probeRemote, buildRemoteAgent, type RemoteAction } from './ssh'
 import { ResourceMonitor } from './monitor'
@@ -230,6 +232,8 @@ const orchestrator = new Orchestrator(
     onAgentMessage: (text) => mainWindow?.webContents.send('agent:message', text),
     onObserverUpdate: (item) => mainWindow?.webContents.send('observer:update', item),
     onObserverActivity: (reviewing) => mainWindow?.webContents.send('observer:activity', reviewing),
+    onWorkMapUpdate: (snapshot) => mainWindow?.webContents.send('workmap:update', snapshot),
+    onWorkMapCapability: (capability) => mainWindow?.webContents.send('workmap:capability', capability),
     onAgentStateChange: (tabId, state, anyAwaiting) => {
       log(`[agent-state] tab=${tabId} state=${state} anyAwaiting=${anyAwaiting}`)
       mainWindow?.webContents.send('agent:state', tabId, state, anyAwaiting)
@@ -242,7 +246,8 @@ const orchestrator = new Orchestrator(
       // the local launch cwd for unbound/local tabs.
       updateProjectBadge(orchestrator.getActiveTabProjectPath() || orchestrator.cwd)
     },
-  }
+  },
+  { appRoot: app.isPackaged ? process.resourcesPath : app.getAppPath(), desktop: true },
 )
 
 // ─── Window ───────────────────────────────────────
@@ -728,6 +733,33 @@ ipcMain.handle('speak:set', (_event, enabled: boolean) => {
   return { enabled: orchestrator.speakRepliesEnabled }
 })
 
+// ─── Work map IPC ─────────────────────────────────
+
+ipcMain.handle('workmap:get', (_event, tabId: string) => orchestrator.workMap.snapshot(String(tabId)))
+ipcMain.handle('workmap:capability', () => orchestrator.workMap.getCapability())
+ipcMain.handle('workmap:source', (_event, tabId: string, eventId: string) => orchestrator.workMap.getSource(String(tabId), String(eventId)))
+ipcMain.handle('workmap:set', (_event, tabId: string, data: unknown) => {
+  if (!data || typeof data !== 'object') throw new Error('Invalid work map settings')
+  const input = data as Record<string, unknown>
+  const clean: MapSettings = {
+    ...orchestrator.workMap.snapshot(String(tabId)).settings,
+  }
+  if (typeof input.enabled === 'boolean') clean.enabled = input.enabled
+  if (input.engine === 'rules' || input.engine === 'clef-flash') clean.engine = input.engine
+  for (const key of ['pythonPath', 'modelPath'] as const) {
+    if (typeof input[key] === 'string') {
+      if (input[key].length > 4096 || !path.isAbsolute(input[key])) throw new Error('Model paths must be absolute local paths')
+      clean[key] = input[key]
+    }
+  }
+  orchestrator.configureWorkMap(clean)
+  return orchestrator.workMap.snapshot(String(tabId))
+})
+ipcMain.handle('workmap:clear', (_event, tabId: string) => {
+  orchestrator.workMap.clear(String(tabId))
+  return orchestrator.workMap.snapshot(String(tabId))
+})
+
 // ─── Observer IPC ─────────────────────────────────
 
 ipcMain.handle('observer:get', () => orchestrator.getObserverSettingsSummary())
@@ -824,6 +856,8 @@ app.whenReady().then(() => {
 
   orchestrator.loadSettings()
   createWindow()
+  void detectCapability({ desktop: true, verifyGpu: async () => usableElectronGpu(await app.getGPUInfo('complete')) })
+    .then(capability => { if (!shutdownStarted) orchestrator.setWorkMapCapability(capability) })
 
   // Kick off an initial npm update check shortly after launch, then poll periodically.
   setTimeout(() => { void checkForUpdate() }, 3000)

package/src/main/observer/observer.ts

@@ -26,6 +26,8 @@ import { createModelCaller } from './anthropic'
 
 /**
  * Observer — supervision layer over the session ledger (spec v0.1, Phase 1).
+ * ON HOLD: retained engine; the app's orchestrator disables runtime and the
+ * renderer does not expose the feature. Standalone test harnesses still work.
  *
  * Consumes the agent's native transcript (via its own TranscriptTailer) and
  * pty-derived activity signals, normalizes them into a local append-only