@agentdeck/bridge 0.2.2 → 1.0.0

package/dist/index.js

@@ -5,13 +5,18 @@
  * Uses BridgeCore for shared infrastructure.
  */
 import { BridgeCore } from './bridge-core.js';
-import { initApme } from './apme/index.js';
+import { buildDisplayStateEvent } from './display-dim.js';
+import { SERIAL_FORWARDED_EVENTS } from '@agentdeck/shared/protocol';
+import { prepareForSerial } from './esp32-serial.js';
+import { initApme, isTimelineProjectionEnabled } from './apme/index.js';
+import { FallbackTaskTimeline } from './fallback-task-timeline.js';
 import { readLastTurn as readClaudeTranscriptLastTurn } from './apme/claude-transcript-reader.js';
 import { claudeHookToSpans } from './apme/adapters/claude-hook.js';
+import { codexHookToSpans } from './apme/adapters/codex-hook.js';
+import { CodexTurnManager } from './apme/adapters/codex-turn-manager.js';
 import { claudePtyParserEventToSpans, claudePtyResponseToSpan } from './apme/adapters/claude-pty.js';
 import { timelineEntryToSpans } from './apme/adapters/timeline.js';
-import { spanNameForKind } from '@agentdeck/shared';
-import { randomUUID } from 'crypto';
+import { classifyAndEnqueueTurn } from './apme/classify-turn.js';
 import { VoiceManager } from './voice.js';
 import { checkDependencies } from './check-deps.js';
 import { enableDebugLog, log, debug, setPtyMode } from './logger.js';
@@ -22,8 +27,8 @@ import { createAdapter, ClaudeCodeAdapter, CodexCliAdapter, OpenCodeAdapter } fr
 import { MonitorAdapter } from './adapters/monitor.js';
 import { UtilityProxy } from './utility-proxy.js';
 import { BridgeLogStream } from './log-stream.js';
-import { extractTopicHint, summarizeResponse } from './timeline-summarizer.js';
-import { cleanDetailText, cleanRawText } from '@agentdeck/shared';
+import { cleanRawText, prepareMarkdownDetail, extractTopicHintWithKind, promptSnippetFallback, } from '@agentdeck/shared';
+import { injectOpenClawSession } from './openclaw-session.js';
 import { VoiceAssistantManager } from './voice-assistant.js';
 import { TerminalStatus } from './terminal-status.js';
 import { readFileSync } from 'fs';
@@ -142,6 +147,15 @@ export async function startSession(opts) {
     log(`Starting AgentDeck bridge on port ${port} (agent: ${agentType})...`);
     // ===== Create adapter =====
     const adapter = createAdapter(agentType, opts.gatewayUrl);
+    // Seed the resolved (git-aware) name into the Claude output parser so its
+    // legacy PROJECT_DIR scrape doesn't override it: the scrape captures the
+    // bare basename of ANY path-like terminal line (first match sticks) and
+    // flows through the state-machine snapshot, which used to win over the
+    // resolver — a monorepo-subdir session would flip from the repo name to
+    // the subdir (or to an unrelated printed path).
+    if (adapter instanceof ClaudeCodeAdapter) {
+        adapter.seedProjectName(projectName);
+    }
     // ===== Start adapter (creates HTTP server, spawns process) =====
     try {
         await adapter.start({ port, command: opts.command, gatewayUrl: opts.gatewayUrl });
@@ -162,36 +176,47 @@ export async function startSession(opts) {
         projectName,
         httpServer: adapter.getHttpServer(),
     });
+    const esp32WifiEvents = new Set([
+        ...SERIAL_FORWARDED_EVENTS,
+        'esp32_ota_begin',
+        'esp32_ota_chunk',
+        'esp32_ota_end',
+        'esp32_ota_abort',
+    ]);
+    core.wsServer.setEventTransformer((event, client) => {
+        if (!core.wsServer.isEsp32Client(client))
+            return event;
+        if (!esp32WifiEvents.has(event.type))
+            return null;
+        return prepareForSerial(event);
+    });
     // ===== APME (Agent Performance Monitoring & Evaluation) =====
     // Optional: degrades to no-op if better-sqlite3 isn't installed.
-    const apme = await initApme();
+    // emitTimeline forwards task_start/task_end so the dashboard sees the task
+    // hierarchy header rows that group turns by APME boundary signal.
+    const projectTimeline = isTimelineProjectionEnabled();
+    const apme = await initApme(undefined, {
+        emitTimeline: (entry) => core.bridgeTimeline.addEntry(entry),
+        projectSampleTimeline: projectTimeline,
+        emitProjectedTimeline: (entry) => core.bridgeTimeline.addEntry(entry, { bypassSuppression: true }),
+    });
     if (apme) {
         core.setApme(apme, process.cwd());
+        if (projectTimeline) {
+            core.bridgeTimeline.setSuppressLocalChatTool(true);
+            log('APME timeline projection ENABLED (AGENTDECK_TIMELINE_PROJECTION=1) — chat/tool rows derive from SessionSample');
+        }
         log('APME enabled — runs will be logged to ~/.agentdeck/apme.sqlite');
-        // Wire APME eval results → timeline entries (session bridge mode).
-        // Daemon has its own richer wiring; this covers standalone session bridges.
-        apme.runner.onResult(({ runId, turnId }) => {
-            if (turnId) {
-                // Turn-level eval completed
-                const run = apme.store.getRun(runId);
-                if (!run)
-                    return;
-                const turnEvals = apme.store.listEvalsForTurn(turnId);
-                const overall = turnEvals.find(e => e.metric === 'overall');
-                if (!overall)
-                    return;
-                const pct = Math.round(overall.score * 100);
-                const axes = turnEvals.filter(e => e.metric !== 'overall');
-                const axisStr = axes.map(e => `${e.metric}=${Math.round(e.score * 100)}%`).join(' ');
-                core.bridgeTimeline.addEntry({
-                    ts: Date.now(), type: 'eval_result',
-                    raw: `★ turn ${pct}% [${run.taskCategory ?? '?'}]`,
-                    detail: axisStr || `Turn eval · ${run.taskPrompt?.slice(0, 80) ?? ''}`,
-                    agentType: run.agentType,
-                });
-            }
-        });
+        // Eval results are no longer projected onto the timeline (the timeline is an
+        // activity log only). Scores are stored in apme.sqlite and surfaced via the
+        // scorecard / `apme_eval` WS event, keeping the timeline noise-free.
     }
+    // APME down (better-sqlite3 failed to load): keep the timeline's task
+    // hierarchy alive by minting fallback task_start/task_end rows from the
+    // hook boundary signals. No storage, no eval — structure only.
+    const fallbackTasks = apme
+        ? null
+        : new FallbackTaskTimeline((entry) => core.bridgeTimeline.addEntry(entry), { agentType });
     // ===== Session-specific components =====
     const voiceManager = new VoiceManager();
     const utilityProxy = new UtilityProxy();
@@ -260,26 +285,29 @@ export async function startSession(opts) {
         hookServer.setMeta({ agentType, projectName });
         hookServer.setVoiceManager(voiceManager);
         hookServer.onApiUsage(() => ({ usage: core.cachedApiUsage, fetchedAt: core.lastApiFetchTime }));
-        hookServer.pairingToken = core.authToken;
     }
     else if (adapter instanceof CodexCliAdapter) {
         hookServer = adapter.getCodexHookServer();
         hookServer.setMeta({ agentType, projectName });
         hookServer.setVoiceManager(voiceManager);
-        hookServer.pairingToken = core.authToken;
     }
     else if (adapter instanceof OpenCodeAdapter) {
         hookServer = adapter.getHookServer();
         hookServer.setMeta({ agentType, projectName });
         hookServer.setVoiceManager(voiceManager);
-        hookServer.pairingToken = core.authToken;
+        // OpenCode has no CLI-level hooks; SSE is the only event channel. Bind
+        // the adapter to the APME session so SSE-derived spans (tool_call /
+        // tool_result / task_boundary / turn_*) can reach the collector. Without
+        // this OpenCode sessions land in APME's runs table but never get
+        // per-task evaluation — every session collapses to a single session_end
+        // task boundary, defeating per-task scoring.
+        adapter.setApmeSession(core.sessionId, process.cwd());
     }
     else if (adapter instanceof MonitorAdapter) {
         hookServer = adapter.getHookServer();
         hookServer.setMeta({ agentType, projectName });
         hookServer.setVoiceManager(voiceManager);
         hookServer.onApiUsage(() => ({ usage: core.cachedApiUsage, fetchedAt: core.lastApiFetchTime }));
-        hookServer.pairingToken = core.authToken;
     }
     const broadcastSse = (event) => hookServer?.broadcastSse(event);
     core.setSseBroadcast(broadcastSse);
@@ -305,6 +333,7 @@ export async function startSession(opts) {
         adb: 'auto',
         serial: false, // daemon-only — session bridges never talk to ESP32
         pixoo: false, // daemon-only — session bridges never talk to Pixoo
+        timebox: false, // daemon-only — session bridges never talk to Timebox
     };
     const deviceModules = createDefaultModules(agentType);
     // Set up ESP32 state provider before module init
@@ -318,7 +347,7 @@ export async function startSession(opts) {
             if (lastStateEvent)
                 events.push(lastStateEvent);
             events.push(core.buildUsage());
-            events.push({ type: 'display_state', displayOn: core.displayMonitor.isDisplayOn() });
+            events.push(buildDisplayStateEvent(core.displayMonitor.isDisplayOn()));
             core.broadcastSessionsList().catch(() => { });
             return events;
         });
@@ -337,8 +366,12 @@ export async function startSession(opts) {
     if (wifiConfig?.autoProvision) {
         const lanIp = getLanIp();
         onESP32Message((portPath, msg) => {
-            if (msg.type === 'device_info' && !msg.wifiConnected) {
-                sendWifiProvisionToAll({
+            const shouldRefreshIps10Endpoint = msg.type === 'device_info' &&
+                msg.board === 'ips_10' &&
+                msg.wifiConnected &&
+                !msg.wifiRadioParked;
+            if (msg.type === 'device_info' && (!msg.wifiConnected || shouldRefreshIps10Endpoint)) {
+                const sent = sendWifiProvisionToAll({
                     type: 'wifi_provision',
                     ssid: wifiConfig.ssid,
                     password: wifiConfig.password,
@@ -346,7 +379,8 @@ export async function startSession(opts) {
                     bridgePort: port,
                     authToken: core.authToken,
                 });
-                log(`WiFi provision sent to ESP32 on ${portPath}`);
+                if (sent > 0)
+                    log(`WiFi provision sent to ${sent} ESP32 device(s) after ${portPath}`);
             }
             else if (msg.type === 'wifi_provision_ack') {
                 log(msg.success ? `ESP32 WiFi connected: ${msg.ip} \u2713` : `ESP32 WiFi failed: ${msg.error || 'unknown'}`);
@@ -365,7 +399,11 @@ export async function startSession(opts) {
         ],
     }));
     // Pixoo live preview frame getter for GET /pixoo/frame
-    hookServer?.setPixooFrameGetter(() => getLastFrame() ?? renderPreviewFrame());
+    hookServer?.setPixooFrameGetter((size, layout) => 
+    // The frame cache holds the standard terrarium, so render micro fresh.
+    layout === 'micro'
+        ? renderPreviewFrame(size, 'micro')
+        : (getLastFrame(size) ?? renderPreviewFrame(size)));
     // ===== Diagnostics =====
     adapter.onDiag((tail) => createDiagDump(core.stateMachine, core.wsServer, journal, ptyRingBuffer, tail));
     adapter.onRawData((data) => {
@@ -400,14 +438,17 @@ export async function startSession(opts) {
         switch (evt.source) {
             case 'hook':
                 journal.write('hook', 'hook', { event: evt.event, data: evt.data });
-                // APME ingestion via the shared TelemetrySpan envelope. The Claude
-                // hook adapter handles `/clear` (emits a `task_boundary` span) so
-                // there's no separate splitRun branch here. Path B/C below preserve
-                // the existing PTY-vs-hook race coordination — that's about timing,
-                // not ingestion semantics, so it stays in this file.
+                // APME ingestion via the shared TelemetrySpan envelope. Codex
+                // CLI sessions go through codexHookToSpans (codex_* event prefix);
+                // Claude Code goes through claudeHookToSpans. Both adapters detect
+                // `/clear` and emit a `task_boundary` span so there's no separate
+                // splitRun branch here.
                 if (apme) {
                     const ctx = makeApmeAdapterCtx(apme, core.sessionId, agentType);
-                    for (const span of claudeHookToSpans(ctx, evt.event, evt.data ?? {})) {
+                    const spans = agentType === 'codex-cli'
+                        ? codexHookToSpans(ctx, evt.event, evt.data ?? {})
+                        : claudeHookToSpans(ctx, evt.event, evt.data ?? {});
+                    for (const span of spans) {
                         apme.collector.ingestSpan(core.sessionId, span);
                     }
                 }
@@ -433,6 +474,9 @@ export async function startSession(opts) {
                 }
                 if (evt.event === 'Stop')
                     pendingPtyResponse = null; // Stop has cleaner response
+                // APME-off fallback: task rows from boundary hooks alone.
+                if (fallbackTasks)
+                    fallbackTasks.ingestHook(core.sessionId, evt.event, evt.data ?? {});
                 if (evt.event === 'shutdown') {
                     shutdown();
                     return;
@@ -613,10 +657,15 @@ export async function startSession(opts) {
             if (core.wsServer.getClientCount() > 0 && Date.now() - core.lastApiFetchTime > 10_000) {
                 core.fetchAndUpdateUsage().catch(() => { });
             }
-            // Voice assistant: if processing a wake-word prompt, speak the response
+            // Voice assistant: if processing a wake-word prompt, speak the response.
+            // Prefer chat_response (the turn's primary completion row now that a
+            // paired chat_end is no longer emitted for turns that have response
+            // text); fall back to chat_end for response-less turns. Read detail
+            // (full markdown) first, then the raw snippet.
             if (voiceAssistant?.getState() === 'processing') {
-                const lastEntry = core.bridgeTimeline.getLastEntry('chat_end');
-                const responseText = lastEntry?.detail;
+                const lastEntry = core.bridgeTimeline.getLastEntry('chat_response')
+                    ?? core.bridgeTimeline.getLastEntry('chat_end');
+                const responseText = lastEntry?.detail ?? lastEntry?.raw;
                 if (responseText) {
                     voiceAssistant.handleResponse(responseText).catch((err) => {
                         debug('agentdeck', `Voice assistant TTS error: ${err}`);
@@ -653,6 +702,7 @@ export async function startSession(opts) {
             }
             core.broadcast({
                 type: 'prompt_options',
+                sessionId: core.sessionId,
                 promptType,
                 question: snapshot.question ?? undefined,
                 options: snapshot.options,
@@ -752,11 +802,17 @@ export async function startSession(opts) {
     });
     // Deck slot map relay
     core.wsServer.onRawMessage((msg, sender) => {
+        if (msg.type === 'device_info') {
+            core.wsServer.markEsp32Client(sender);
+            return false;
+        }
         if (msg.type === 'deck_slot_map') {
             cachedSlotMap = msg;
             core.wsServer.broadcastExcept(cachedSlotMap, sender);
             broadcastSse(cachedSlotMap);
             core.broadcast(computeButtonState());
+            // Re-broadcast sessions_list so slot buttons populate after plugin startup race
+            core.broadcastSessionsList().catch(() => { });
             return true;
         }
         return false;
@@ -809,6 +865,7 @@ export async function startSession(opts) {
             }
             extraEvents.push({
                 type: 'prompt_options',
+                sessionId: core.sessionId,
                 promptType: initPromptType,
                 question: snapshot.question ?? undefined,
                 options: snapshot.options,
@@ -843,20 +900,12 @@ export async function startSession(opts) {
     core.startGatewayProbe(800);
     core.startGatewayHealthCheck();
     core.startSessionsListPolling();
-    // Inject virtual OpenClaw session when Gateway is detected (same as daemon-server.ts)
-    core.setSessionsEnricher((sessions) => {
-        if (!core.cachedGatewayAvailable)
-            return sessions;
-        if (sessions.some(s => s.agentType === 'openclaw'))
-            return sessions;
-        return [...sessions, {
-                id: 'openclaw-gateway',
-                port: 18789,
-                projectName: 'OpenClaw',
-                agentType: 'openclaw',
-                alive: true,
-            }];
-    });
+    // Inject virtual OpenClaw session only after Gateway authentication succeeds
+    // (gatewayConnected). Reachability alone (cachedGatewayAvailable) is a
+    // topology signal, not proof commands can route — gating on it kept a phantom
+    // OpenClaw session alive whenever anything held port 18789 open. Shared
+    // injector with daemon-server.ts; mirror of Swift buildSessionsListEvent.
+    core.setSessionsEnricher((sessions) => injectOpenClawSession(sessions, { gatewayConnected: core.cachedGatewayConnected }));
     // ===== Encoder state computation =====
     function computeEncoderState() {
         const snapshot = core.stateMachine.getSnapshot();
@@ -1133,110 +1182,60 @@ export async function startSession(opts) {
         core.shutdown();
     }
 }
-// Mid-session classify + turn-level eval enqueue.
-// Shared between Claude spinner_stop, OpenClaw/OpenCode chat_response, and Codex spinner_stop
-// so all agents get the same turns.task_category stamping and non-code turn_judge evals.
-async function classifyAndEnqueueTurn(apme, sid) {
-    const turnId = apme.collector.getActiveTurnId(sid);
-    const runId = apme.collector.getRunId(sid);
-    if (!turnId || !runId)
-        return;
-    const run = apme.store.getRun(runId);
-    if (!run)
-        return;
-    let category = run.taskCategory ?? null;
-    if (!category) {
-        try {
-            const { classifyRun } = await import('./apme/classifier.js');
-            const { category: c, signals } = classifyRun(apme.store, run.id);
-            if (c && c !== 'unknown') {
-                category = c;
-                apme.store.updateRun(run.id, {
-                    taskCategory: c,
-                    taskSignals: JSON.stringify(signals),
-                    taskCategorySource: 'rule',
-                });
-            }
-        }
-        catch (err) {
-            debug('APME', `mid-session classify failed: ${String(err)}`);
-        }
-    }
-    if (category) {
-        try {
-            apme.store.updateTurn(turnId, { taskCategory: category });
-        }
-        catch { /* ignore */ }
-    }
-    const NON_CODE = new Set(['conversation', 'planning', 'research', 'review']);
-    if (category && NON_CODE.has(category)) {
-        apme.runner.enqueueTurn({ runId: run.id, turnId, category });
-    }
-}
 // ===== Non-Claude agent APME wiring =====
 // For OpenCode, Codex, OpenClaw: intercepts adapter timeline events to create
 // APME turns with prompts and responses. Claude Code uses hooks instead.
 function wireAgentApme(adapter, agentType, apme, core, ptyRingBuffer) {
     const sid = core.sessionId;
+    // Codex turn boundaries (hook-primary, PTY-fallback) live in their own
+    // module. The class encapsulates the seven-state-variable PTY-only
+    // machine plus the hook-fresh shortcut so non-codex sessions allocate
+    // nothing here.
+    const codexManager = agentType === 'codex-cli'
+        ? new CodexTurnManager(core, apme, ptyRingBuffer, sid, agentType)
+        : null;
     adapter.on('event', (evt) => {
         // ── Timeline events (OpenCode / OpenClaw) ──
         // Both adapters emit { source: 'timeline', entry: TimelineEntry }.
         // The timeline adapter normalizes them to AgentDeck telemetry spans.
         if (evt.source === 'timeline' && evt.entry) {
             const entry = evt.entry;
-            const ctx = makeApmeAdapterCtx(apme, sid, agentType);
-            for (const span of timelineEntryToSpans(ctx, entry)) {
-                apme.collector.ingestSpan(sid, span);
+            // Upserts refine an already-ingested row (chat_start topic hint, async
+            // LLM summary) — converting them to spans again would open a phantom
+            // turn or overwrite the captured response with a summary label.
+            if (evt.upsert)
+                return;
+            // Adapters bound to APME directly (OpenCode via setApmeSession) ingest
+            // richer spans from their native event stream; converting their
+            // timeline rows as well double-counted every turn and tool (the tool
+            // sample dedupCore is counter-based, so storage-time dedup can't
+            // collapse the second copy). Timeline conversion is the fallback for
+            // sessions without a direct binding.
+            const directApme = adapter
+                .hasDirectApmeIngestion?.() === true;
+            if (!directApme) {
+                const ctx = makeApmeAdapterCtx(apme, sid, agentType);
+                for (const span of timelineEntryToSpans(ctx, entry)) {
+                    apme.collector.ingestSpan(sid, span);
+                }
             }
-            // Mid-session classification still runs once we've captured a response.
+            // Mid-session classification still runs once we've captured a response
+            // (both ingestion paths write the turn response before this fires).
             if (entry.type === 'chat_response') {
                 void classifyAndEnqueueTurn(apme, sid);
             }
         }
-        // ── Codex: PTY parser fallback ──
-        if (evt.source === 'parser' && agentType === 'codex-cli') {
-            const ctx = makeApmeAdapterCtx(apme, sid, agentType);
-            if (evt.event === 'user_prompt') {
-                const text = evt.data?.text;
-                if (text) {
-                    // PTY-derived prompt = synthetic turn_start span. We construct it
-                    // inline rather than reusing claudeHookToSpans because the source
-                    // is a parser event, not a hook payload.
-                    const span = {
-                        traceId: ctx.traceId,
-                        spanId: randomUUID(),
-                        parentSpanId: ctx.activeTurnId,
-                        name: spanNameForKind('turn_start'),
-                        kind: 'turn_start',
-                        ts: Date.now(),
-                        attributes: {
-                            'agentdeck.agent_type': ctx.agentType,
-                            'agentdeck.prompt_text': text,
-                            ...(ctx.cwd ? { 'agentdeck.cwd': ctx.cwd } : {}),
-                        },
-                    };
-                    apme.collector.ingestSpan(sid, span);
-                }
-            }
-            if (evt.event === 'spinner_stop') {
-                setTimeout(() => {
-                    const tail = ptyRingBuffer.getTail(5000);
-                    const lines = tail.split('\n').map(l => l.trim()).filter(Boolean);
-                    // Filter out spinner/UI artifacts from tail (Codex PTY output)
-                    const clean = lines.filter(l => !/^[✢✳✶✻✽⏸⏵❯─>]/.test(l) &&
-                        !/planmode|plan\s*mode|shift\+tab|accept\s*edits/i.test(l) &&
-                        !/\?\s*for\s*shortcuts/.test(l));
-                    const response = clean.slice(-5).join('\n');
-                    if (response.length > 2) {
-                        const span = claudePtyResponseToSpan(ctx, response);
-                        if (span)
-                            apme.collector.ingestSpan(sid, span);
-                        void classifyAndEnqueueTurn(apme, sid);
-                    }
-                }, 500);
-            }
+        // ── Codex: hook (primary) + PTY-parser fallback ──
+        if (codexManager) {
+            if (evt.source === 'hook')
+                codexManager.onHookEvent(evt);
+            else if (evt.source === 'parser')
+                codexManager.onParserEvent(evt);
         }
     });
+    if (codexManager) {
+        core.onShutdown(() => codexManager.cleanup());
+    }
 }
 /** Build the AdapterContext used by every APME ingestion adapter. The
  *  trace id mirrors the active run id so future OTLP exports tie spans
@@ -1251,6 +1250,9 @@ function makeApmeAdapterCtx(apme, sid, agentType) {
         activeTurnId: apme.collector.getActiveTurnId(sid) ?? undefined,
     };
 }
+function isClaudeTaskNotificationPrompt(text) {
+    return text.trim().toLowerCase().startsWith('<task-notification>');
+}
 // ===== Claude Code timeline wiring =====
 function wireClaudeCodeTimeline(adapter, core, journal, ptyRingBuffer) {
     let ccChatStart = null;
@@ -1266,6 +1268,10 @@ function wireClaudeCodeTimeline(adapter, core, journal, ptyRingBuffer) {
             ccPendingChatStartTimer = null;
         }
         ccPendingChatStart = false;
+        if (isClaudeTaskNotificationPrompt(text)) {
+            ccLastPromptText = null;
+            return;
+        }
         ccLastPromptText = text || null;
         const snippet = text.length > 500 ? text.slice(0, 497) + '...' : text;
         const detail = text.length > 100 ? (text.length > 1000 ? text.slice(0, 1000) + '...' : text) : undefined;
@@ -1274,11 +1280,16 @@ function wireClaudeCodeTimeline(adapter, core, journal, ptyRingBuffer) {
             const proj = core.stateMachine.getSnapshot().projectName;
             return proj ? `Prompt \u00B7 ${proj}` : 'Prompt sent';
         })();
+        // taskId/runId are filled in by BridgeCore's timeline attributor
+        // (wireTimeline → setAttributor) from the active APME task for this
+        // session, so managed-session chat rows nest under their task header
+        // without threading the id through here.
         core.bridgeTimeline.addEntry({
             ts: ccChatStart ?? Date.now(), type: 'chat_start',
             raw: snippet || fallbackRaw,
             ...(detail ? { detail } : {}),
             agentType: 'claude-code',
+            startedAt: ccChatStart ?? Date.now(),
         });
     };
     /** Extract response text from PTY ringbuffer after ⏺ marker (same pattern as APME) */
@@ -1306,59 +1317,86 @@ function wireClaudeCodeTimeline(adapter, core, journal, ptyRingBuffer) {
         }
         return clean.join('\n').trim();
     };
-    /** Emit chat_response + chat_end from response text (shared by Stop hook and PTY fallback) */
+    /**
+     * Emit a single Claude turn-close row (shared by Stop hook and PTY fallback):
+     * a `chat_response` when there is meaningful response text, otherwise a
+     * `chat_end`. The two are mutually exclusive so a turn never produces both —
+     * the paired dimmed `chat_end` used to fragment every turn into three rows on
+     * the flat surfaces (plugin / TUI / timeline.json).
+     */
     const emitCompletion = (responseText, duration, toolSummary) => {
         const now = Date.now();
+        const startedAt = ccChatStart ?? undefined;
         // Change 5: emit chat_response if meaningful response text exists
         if (responseText.length > 20) {
             const respRaw = responseText.length > 200 ? responseText.slice(0, 197) + '...' : responseText;
             core.bridgeTimeline.addEntry({
                 ts: now - 1, type: 'chat_response',
                 raw: cleanRawText(respRaw),
-                detail: cleanDetailText(responseText.slice(0, 3000)) || undefined,
+                // Preserve markdown so the dashboard renderer can apply heading /
+                // table / bold / code styles. cleanDetailText would have stripped
+                // all of that before it ever reached the client.
+                detail: prepareMarkdownDetail(responseText.slice(0, 3000)) || undefined,
                 agentType: 'claude-code',
+                ...(startedAt ? { startedAt } : {}),
+                endedAt: now,
             });
         }
-        const topicHint = responseText ? extractTopicHint(responseText) : null;
-        const promptTopic = ccLastPromptText ? extractTopicHint(ccLastPromptText) : null;
-        const completedLabel = topicHint || promptTopic || 'Completed';
+        // Pick a summary label.
+        //   - 'topic' kind from response \u2192 real heuristic content
+        //   - 'topic' kind from prompt \u2192 still meaningful, mark as heuristic
+        //   - 'fallback' kind (politeness-only) or prompt snippet \u2192 mark as 'none'
+        //     (clients use this to decide whether the detail pane is worth showing)
+        //   - literal "Completed" only when prompt is also empty
+        const respHint = responseText ? extractTopicHintWithKind(responseText) : { hint: null, kind: null };
+        const promptHint = ccLastPromptText ? extractTopicHintWithKind(ccLastPromptText) : { hint: null, kind: null };
+        let completedLabel;
+        let summaryKind;
+        if (respHint.kind === 'topic' && respHint.hint) {
+            completedLabel = respHint.hint;
+            summaryKind = 'heuristic';
+        }
+        else if (promptHint.kind === 'topic' && promptHint.hint) {
+            completedLabel = promptHint.hint;
+            summaryKind = 'heuristic';
+        }
+        else if (respHint.hint || promptHint.hint) {
+            completedLabel = (respHint.hint || promptHint.hint);
+            summaryKind = 'none';
+        }
+        else {
+            const fallback = promptSnippetFallback(ccLastPromptText, 60);
+            completedLabel = fallback ?? 'Completed';
+            summaryKind = 'none';
+        }
         let summary = duration != null ? `${completedLabel} \u00B7 ${duration}s` : completedLabel;
         if (toolSummary)
             summary += ` \u00B7 ${toolSummary}`;
         const chatEndDetail = responseText
-            ? (() => { const c = cleanDetailText(responseText); return c ? (c.length > 1000 ? c.slice(0, 1000) + '...' : c) : undefined; })()
+            ? (() => { const c = prepareMarkdownDetail(responseText); return c ? (c.length > 1000 ? c.slice(0, 1000) + '...' : c) : undefined; })()
             : ccLastPromptText
                 ? `Prompt: ${ccLastPromptText.length > 200 ? ccLastPromptText.slice(0, 200) + '...' : ccLastPromptText}`
                 : undefined;
         const chatEndTs = now;
         ccChatStart = null;
         ccLastPromptText = null;
-        core.bridgeTimeline.addEntry({
-            ts: chatEndTs, type: 'chat_end', raw: summary,
-            ...(chatEndDetail ? { detail: chatEndDetail } : {}),
-            agentType: 'claude-code',
-        });
-        // Async LLM summarization — fire-and-forget, upsert chat_end when ready
-        if (responseText && responseText.length > 30) {
-            const savedDuration = duration;
-            const savedToolSummary = toolSummary;
-            const savedDetail = chatEndDetail;
-            summarizeResponse(responseText).then((llmSummary) => {
-                if (llmSummary) {
-                    const enrichedParts = [llmSummary];
-                    if (savedDuration != null)
-                        enrichedParts.push(`${savedDuration}s`);
-                    if (savedToolSummary)
-                        enrichedParts.push(savedToolSummary);
-                    debug('timeline', `CC LLM summary: ${llmSummary}`);
-                    core.bridgeTimeline.upsertEntry({
-                        ts: chatEndTs, type: 'chat_end',
-                        raw: enrichedParts.join(' \u00B7 '),
-                        ...(savedDetail ? { detail: savedDetail } : {}),
-                        agentType: 'claude-code',
-                    });
-                }
-            }).catch(() => { });
+        // Only emit a chat_end turn-close row when there is NO chat_response to act
+        // as the turn's completion row (a tool-only turn, or a Stop hook with no
+        // last_assistant_message). When a chat_response exists it already marks the
+        // turn complete; the extra dimmed "Completed · Ns · topic" row is redundant
+        // metadata — the dashboard already drops it on render — and on the flat
+        // surfaces (Stream Deck plugin / TUI / persisted timeline.json) it
+        // fragmented every Claude turn into three rows. Keeping chat_start +
+        // chat_response matches the cleaner OpenClaw turn shape.
+        if (responseText.length <= 20) {
+            core.bridgeTimeline.addEntry({
+                ts: chatEndTs, type: 'chat_end', raw: summary,
+                ...(chatEndDetail ? { detail: chatEndDetail } : {}),
+                agentType: 'claude-code',
+                ...(startedAt ? { startedAt } : {}),
+                endedAt: chatEndTs,
+                summaryKind,
+            });
         }
     };
     // Change 4: late upsert — user_prompt metadata arriving after 500ms timer