<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel><title>Plans on Welcome to Christophe Nasarre's Blog</title><link>https://chrisnas.github.io/tags/plans/</link><description>Recent content in Plans on Welcome to Christophe Nasarre's Blog</description><generator>Hugo</generator><language>en-us</language><lastBuildDate>Sun, 15 Nov 2026 00:00:00 +0000</lastBuildDate><atom:link href="https://chrisnas.github.io/tags/plans/index.xml" rel="self" type="application/rss+xml"/><item><title>SessionViewer and Cursor: reconstructing history from JSONL, SQLite and plans</title><link>https://chrisnas.github.io/posts/2026-11-15_sessionviewer-and-cursor/</link><pubDate>Sun, 15 Nov 2026 00:00:00 +0000</pubDate><guid>https://chrisnas.github.io/posts/2026-11-15_sessionviewer-and-cursor/</guid><description>How SessionViewer combines Cursor JSONL, SQLite, workspace manifests and plans, and how CursorDBNavigator traces reconstructed turns back to physical rows.</description><content:encoded><![CDATA[<p>The first five posts examined agent harnesses (the programs that run AI coding agents) <strong>while they were running</strong>. A hook is a callback that Cursor, Claude Code, or Copilot invokes when something happens. Those hooks supplied the structure, and the previous post used the transcript path reported by a hook to fill a few gaps.</p>
<p>That live approach answers “what is my agent doing now?” The live approach does not help when I open Cursor a week later and ask two different questions:</p>
<ul>
<li>What happened in that previous session?</li>
<li>Where is the plan I created during this session?</li>
</ul>
<p>I use plans a lot, and finding one again was surprisingly difficult. Cursor stores a plan separately from the conversation that created the plan. Cursor can also split the conversation between a JSONL transcript (a text file with one JSON object per line) and SQLite (the embedded database used by Cursor Desktop).</p>
<p>This is the sixth post in the series, and the first of three about local history:</p>
<ol>
<li><a href="/posts/2026-08-23_spying-on-cursor-hooks/">Spying on Cursor: agent hooks, payloads and a simple observer</a></li>
<li><a href="/posts/2026-09-14_rebuilding-cursor-conversation/">Rebuilding the Agent conversation: sessions, turns, thoughts, tools, MCP, skills and summaries</a></li>
<li><a href="/posts/2026-09-20_spying-on-claude-code-hooks/">Spying on Claude Code: more lifecycle events, different blind spots</a></li>
<li><a href="/posts/2026-09-27_spying-on-github-copilot-twice/">Spying on GitHub Copilot twice: CLI hooks versus VS Code</a></li>
<li><a href="/posts/2026-10-09_beyond-hooks-transcript-logs/">Beyond hooks: enriching live sessions with undocumented transcript logs</a></li>
<li><strong>SessionViewer and Cursor: reconstructing history from JSONL, SQLite and plans</strong> (this post)</li>
<li>SessionViewer and Claude Code: transcripts, subagents, usage and plans</li>
<li>SessionViewer and Copilot CLI: decoding events.jsonl, turns, usage and plans</li>
</ol>
<h2 id="where-cursor-keeps-the-evidence">Where Cursor keeps the evidence</h2>
<p>Cursor does not keep sessions in one authoritative file: they are spread across transcripts, Desktop state and plan files:</p>
<p><img alt="Cursor session transcripts, Desktop stores and plan files" loading="lazy" src="/posts/2026-11-15_sessionviewer-and-cursor/cursor-session-sources.svg"></p>
<p>Cursor&rsquo;s Desktop SQLite stores contribute Composer IDs, titles, request IDs, and bubbles. Desktop SQLite and JSONL transcripts can describe the same conversation and even the same tool call. SessionViewer therefore reconciles matching records instead of concatenating them. Plan files supply current content, while transcript activity supplies ownership and historical evidence.</p>
<h2 id="a-different-application-for-a-different-question">A different application for a different question</h2>
<p><code>SessionViewer</code> is a separate desktop application in HarnessSpy with a read-only history scanner. It is not another mode of <code>CursorSpy.App</code>.</p>
<p>HarnessSpy also includes <code>CursorDBNavigator</code>, a separate Cursor-only application that explains how SQLite rows become workspaces, Composers, bubbles, turns, and events. SessionViewer remains the history browser; CursorDBNavigator is the physical-evidence browser introduced later in this post.</p>
<p>The Spy applications receive hook payloads through a named pipe, which is a local Windows communication channel. For example, a Cursor hook sends a JSON payload to <code>CursorSpy.App</code>, and that payload can identify a transcript. The Spy application inspects a transcript only after an accepted hook points to the file. The hook sequence still determines record order and correlation (which records belong to the same session or tool call).</p>
<p>SessionViewer uses a different path. It:</p>
<ul>
<li>scans files and databases owned by Cursor, Claude Code, and Copilot CLI directly;</li>
<li>scans only the harnesses selected in its filter;</li>
<li>refreshes those sources only at startup or after an explicit user action;</li>
<li>rebuilds sessions even when HarnessSpy was not running at the time;</li>
<li>reloads raw source records only when the inspector or a deep search needs them;</li>
<li>connects a plan to the session that created it when the stored evidence identifies one session;</li>
<li>can place a workspace-less session or unbound plan under a likely workspace.</li>
</ul>
<p>SessionViewer does not read HarnessSpy hook payloads or transcript sidecars, which are copies that the live Spy applications preserve beside their own data. The live pipeline has an <code>ObservationReconciler</code>, a component that combines hook notifications with transcript rows. SessionViewer does not call that component. Cursor needs a different reconciliation step described later in this post because a transcript and the Desktop database can each describe the same tool call.</p>
<p>Here, a provider means one agent harness, such as Cursor, Claude Code, or Copilot CLI. A provider scanner reads one provider&rsquo;s local files and creates normalized <code>SessionCatalogEntry</code> records. SessionViewer keeps the latest complete result from each enabled scanner as a cached catalog. The catalog merger combines compatible entries, plan binding associates plans with sessions, and workspace inference can change where an unresolved entry is displayed in the UI.</p>
<p>SessionViewer projects the catalog into a lazy tree. A lazy tree creates child nodes only when the user expands a session or turn. For example, a collapsed session with thousands of events initially occupies one session node and one <strong>Expand to load</strong> placeholder.</p>
<p>A <code>SessionCatalogEntry</code> is not a Cursor, Claude, or Copilot record. It is SessionViewer&rsquo;s normalized representation of one session, with turns, events, related files, metadata, and source provenance. Provenance points back to the original evidence, such as a JSONL byte range or a SQLite table and key. The inspector follows that origin only when raw content is requested. The catalog keeps reloadable references instead of retaining every raw JSON string in application memory. Claude and Copilot can also provide session-level events, such as a saved copy of a system prompt.</p>
<p>SessionViewer adds evidence labels that do not exist in the provider files. <code>Observed</code> means that a source states a value directly. <code>Corroborated</code> means that independent sources agree, such as a transcript and a Desktop record for the same tool call. <code>Derived</code> marks a deterministic value that SessionViewer calculated from source data. For example, Cursor transcript turns are <code>Derived</code> because SessionViewer constructs their IDs from the session identity and turn number. <code>Heuristic</code> marks a useful but uncertain match. <code>Opaque</code> means that an action is visible but its complete result is not. <code>Ambiguous</code> means that more than one match remains possible. <code>Unavailable</code> means that the provider files contain no usable evidence for that value.</p>
<p>In SessionViewer, the harness filter controls both scanning and display. Disabling Cursor removes Cursor sessions from the tree and evicts its cached catalog. Enabling Cursor again requests a cache-aware Cursor refresh. A cache-aware refresh compares the current provider file snapshot with the previous complete snapshot and reuses the retained catalog when those inputs have not changed. SessionViewer rescans if the cache was evicted or the file snapshot changed. An option named <strong>Keep disabled provider cache</strong> preserves that catalog when faster toggling matters more than memory.</p>
<h2 id="refreshing-only-when-i-ask">Refreshing only when I ask</h2>
<p>SessionViewer scans the saved enabled harnesses once at startup. After that scan, only three actions can request another refresh:</p>
<ul>
<li><strong>Refresh</strong> or F5 revalidates the enabled harnesses;</li>
<li><strong>Force full refresh</strong> ignores the source cache;</li>
<li>selecting a harness revalidates the newly enabled provider.</li>
</ul>
<p>A normal refresh first captures a recursive snapshot of the relevant file paths, lengths, and modification times under each provider root. If that snapshot matches a previous complete scan, SessionViewer reuses the cached provider catalog. <strong>Force full refresh</strong> bypasses that comparison. No <code>FileSystemWatcher</code>, recovery timer, process inventory, or background refresh queue exists, so SessionViewer is deliberately not a live view.</p>
<p>Cursor Desktop calls an IDE agent conversation a <strong>Composer</strong> and assigns it a Composer ID. A database can contain years of Composer history. Loading every old conversation body before showing the first workspace would delay the first useful result. If a cache-aware refresh finds no catalog change, SessionViewer updates the scan status without rebuilding the tree.</p>
<p>The first load is progressive. SessionViewer reads lightweight Desktop Composer shells without loading their SQLite bubble bodies. A shell contains metadata such as the Composer ID, title, timestamps, workspace, model, mode, and parent relationship. JSONL transcripts are parsed in parallel and can already contributeto  complete turns.</p>
<p>Cursor loading has two lazy layers. First, expanding a Cursor session loads that Composer&rsquo;s Desktop SQLite bubbles and merges the new evidence with any transcript-derived turns already in the catalog. SessionViewer calls this detail loading and conversion <strong>hydration</strong>, then reruns Cursor turn and event reconciliation. Second, the WPF tree creates child view models only for expanded sessions and turns. A collapsed session or turn contains one <strong>Expand to load</strong> placeholder. Collapsing the node removes those event view models from memory but keeps the hydrated catalog entry. Hovering or selecting a session can calculate its summary without creating every descendant first.</p>
<p><img alt="Header-first and on-demand stages in the Cursor Desktop branch" loading="lazy" src="/posts/2026-11-15_sessionviewer-and-cursor/cursor-session-reconstruction-chain.svg"></p>
<p>This diagram isolates the Cursor Desktop SQLite branch. The JSONL transcript scan runs in parallel and can contribute turns before Desktop bubble hydration.</p>
<h2 id="cursor-writes-more-than-one-history">Cursor writes more than one history</h2>
<p>SessionViewer currently reads these Cursor-owned locations:</p>
<table>
  <thead>
      <tr>
          <th>Source</th>
          <th>Default location</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td>Current transcript</td>
          <td><code>%USERPROFILE%\.cursor\projects\&lt;project&gt;\agent-transcripts\&lt;session&gt;\&lt;session&gt;.jsonl</code></td>
      </tr>
      <tr>
          <td>Legacy transcript</td>
          <td><code>%USERPROFILE%\.cursor\projects\&lt;project&gt;\agent-transcripts\&lt;session&gt;.jsonl</code></td>
      </tr>
      <tr>
          <td>Child agents</td>
          <td><code>...\&lt;session&gt;\subagents\*.jsonl</code></td>
      </tr>
      <tr>
          <td>Global Desktop state</td>
          <td><code>%APPDATA%\Cursor\User\globalStorage\state.vscdb</code></td>
      </tr>
      <tr>
          <td>Workspace Desktop state</td>
          <td><code>%APPDATA%\Cursor\User\workspaceStorage\&lt;id&gt;\state.vscdb</code></td>
      </tr>
      <tr>
          <td>Workspace manifests</td>
          <td><code>%APPDATA%\Cursor\User\workspaceStorage\&lt;id&gt;\workspace.json</code></td>
      </tr>
      <tr>
          <td>Plans</td>
          <td><code>%USERPROFILE%\.cursor\plans\*.plan.md</code></td>
      </tr>
  </tbody>
</table>
<p>When both transcript layouts exist for the same project and session, SessionViewer uses the nested transcript and ignores the legacy flat copy.</p>
<p>SessionViewer enumerates all of the workspace manifests independently, including a storage directory that no longer contains <code>state.vscdb</code>. Those manifests provide the known roots used for workspace inference. Cursor plan discovery is currently limited to the top level of <code>%USERPROFILE%\.cursor\plans</code>; workspace-local plan directories remain disabled until an observed <code>isProject: true</code> artifact establishes that layout.</p>
<p>The two conversation sources complement each other:</p>
<ul>
<li><strong>JSONL transcripts</strong> are close to Cursor&rsquo;s agent stream. Cursor rows can contain prompts, assistant text, thinking, tool requests, results, and child-agent files. Many rows omit IDs or timestamps.</li>
<li><strong>SQLite state</strong> contains Cursor Desktop Composer records. Cursor can store titles, workspaces, selected Composer IDs, request IDs, parent/child agent relationships, and conversation bubbles. A bubble is Cursor&rsquo;s stored record for one user or assistant message. The SQLite schema is private and changes between Cursor versions.</li>
</ul>
<p>The next sections use both Cursor-native and SessionViewer terms. A native value is written by Cursor rather than created by SessionViewer. Cursor calls one IDE conversation a <strong>Composer</strong> and writes its native <code>composerId</code>. A <strong>conversation header</strong> is a lightweight ordered reference to one Cursor bubble. SessionViewer converts those Cursor records into a normalized <strong>session</strong> containing <strong>turns</strong> and <strong>events</strong>. A turn is one user prompt and the work caused by that prompt. An event is one normalized prompt, thought, tool request, result, or assistant response.</p>
<p>A sparse transcript can look like this:</p>
<div class="highlight"><div class="chroma">
<table class="lntable"><tr><td class="lntd">
<pre tabindex="0" class="chroma"><code><span class="lnt">1
</span><span class="lnt">2
</span><span class="lnt">3
</span><span class="lnt">4
</span></code></pre></td>
<td class="lntd">
<pre tabindex="0" class="chroma"><code class="language-json" data-lang="json"><span class="line"><span class="cl"><span class="p">{</span><span class="nt">&#34;role&#34;</span><span class="p">:</span><span class="s2">&#34;user&#34;</span><span class="p">,</span><span class="nt">&#34;message&#34;</span><span class="p">:{</span><span class="nt">&#34;content&#34;</span><span class="p">:[{</span><span class="nt">&#34;type&#34;</span><span class="p">:</span><span class="s2">&#34;text&#34;</span><span class="p">,</span><span class="nt">&#34;text&#34;</span><span class="p">:</span><span class="s2">&#34;&lt;user_query&gt;inspect the project&lt;/user_query&gt;&#34;</span><span class="p">}]}}</span>
</span></span><span class="line"><span class="cl"><span class="p">{</span><span class="nt">&#34;role&#34;</span><span class="p">:</span><span class="s2">&#34;assistant&#34;</span><span class="p">,</span><span class="nt">&#34;message&#34;</span><span class="p">:{</span><span class="nt">&#34;content&#34;</span><span class="p">:[{</span><span class="nt">&#34;type&#34;</span><span class="p">:</span><span class="s2">&#34;thinking&#34;</span><span class="p">,</span><span class="nt">&#34;thinking&#34;</span><span class="p">:</span><span class="s2">&#34;Inspect two areas.&#34;</span><span class="p">},{</span><span class="nt">&#34;type&#34;</span><span class="p">:</span><span class="s2">&#34;tool_use&#34;</span><span class="p">,</span><span class="nt">&#34;id&#34;</span><span class="p">:</span><span class="s2">&#34;call-1&#34;</span><span class="p">,</span><span class="nt">&#34;name&#34;</span><span class="p">:</span><span class="s2">&#34;Read&#34;</span><span class="p">,</span><span class="nt">&#34;input&#34;</span><span class="p">:{</span><span class="nt">&#34;path&#34;</span><span class="p">:</span><span class="s2">&#34;README.md&#34;</span><span class="p">}}]}}</span>
</span></span><span class="line"><span class="cl"><span class="p">{</span><span class="nt">&#34;role&#34;</span><span class="p">:</span><span class="s2">&#34;assistant&#34;</span><span class="p">,</span><span class="nt">&#34;message&#34;</span><span class="p">:{</span><span class="nt">&#34;content&#34;</span><span class="p">:[{</span><span class="nt">&#34;type&#34;</span><span class="p">:</span><span class="s2">&#34;text&#34;</span><span class="p">,</span><span class="nt">&#34;text&#34;</span><span class="p">:</span><span class="s2">&#34;Done.&#34;</span><span class="p">}]}}</span>
</span></span><span class="line"><span class="cl"><span class="p">{</span><span class="nt">&#34;type&#34;</span><span class="p">:</span><span class="s2">&#34;turn_ended&#34;</span><span class="p">,</span><span class="nt">&#34;status&#34;</span><span class="p">:</span><span class="s2">&#34;success&#34;</span><span class="p">}</span>
</span></span></code></pre></td></tr></table>
</div>
</div><p>The fields in this example are Cursor transcript fields, not SessionViewer fields. The first Cursor <code>user</code> row starts the turn, the <code>tool_use</code> block requests a <code>Read</code>, and the Cursor <code>turn_ended</code> row closes the turn. The example contains enough information to build that group, but not enough to timestamp every block or identify the matching Desktop bubble.</p>
<h2 id="following-one-selected-composer-through-sqlite">Following one selected Composer through SQLite</h2>
<p>A concrete workspace makes the SQLite relationships easier to see. One Cursor workspace-storage directory on my machine was:</p>
<div class="highlight"><div class="chroma">
<table class="lntable"><tr><td class="lntd">
<pre tabindex="0" class="chroma"><code><span class="lnt">1
</span><span class="lnt">2
</span></code></pre></td>
<td class="lntd">
<pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">%APPDATA%\Cursor\User\workspaceStorage\
</span></span><span class="line"><span class="cl">    2f4a4dd9b247ee19ce12fb78b89e3710\
</span></span></code></pre></td></tr></table>
</div>
</div><p>The directory name is Cursor&rsquo;s opaque workspace-storage ID. Its <code>workspace.json</code> contained:</p>
<div class="highlight"><div class="chroma">
<table class="lntable"><tr><td class="lntd">
<pre tabindex="0" class="chroma"><code><span class="lnt">1
</span><span class="lnt">2
</span><span class="lnt">3
</span></code></pre></td>
<td class="lntd">
<pre tabindex="0" class="chroma"><code class="language-json" data-lang="json"><span class="line"><span class="cl"><span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;folder&#34;</span><span class="p">:</span> <span class="s2">&#34;file:///c%3A/dev/dd-win-prof&#34;</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span></code></pre></td></tr></table>
</div>
</div><p>That manifest maps the storage ID to <code>C:\dev\dd-win-prof</code>. In the adjacent workspace <code>state.vscdb</code>, the <code>ItemTable</code> row whose key was <code>composer.composerData</code> contained this list of IDs:</p>
<div class="highlight"><div class="chroma">
<table class="lntable"><tr><td class="lntd">
<pre tabindex="0" class="chroma"><code><span class="lnt">1
</span><span class="lnt">2
</span><span class="lnt">3
</span><span class="lnt">4
</span><span class="lnt">5
</span><span class="lnt">6
</span><span class="lnt">7
</span></code></pre></td>
<td class="lntd">
<pre tabindex="0" class="chroma"><code class="language-json" data-lang="json"><span class="line"><span class="cl"><span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;selectedComposerIds&#34;</span><span class="p">:</span> <span class="p">[</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;90f37e83-0aa8-4d76-8e3a-094322899a3e&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;050aff2e-6911-4c50-8886-6afb0c9b2323&#34;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">    <span class="s2">&#34;ad9b6b12-6295-48f6-b2a9-6ac755e7a855&#34;</span>
</span></span><span class="line"><span class="cl">  <span class="p">]</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span>
</span></span></code></pre></td></tr></table>
</div>
</div><p>Each value is a <code>composerId</code>, so each value can identify one Cursor conversation/session. To investigate one selected composer/session manually, I called the ID <code>X</code> and followed matching records in the global database:</p>
<ol>
<li><code>composerHeaders.composerId = X</code> supplied a lightweight session shell with fields such as title, timestamps, workspace and parent relationship.</li>
<li><code>cursorDiskKV.key = composerData:X</code> supplied the detailed Composer object.</li>
<li><code>fullConversationHeadersOnly[n]</code> supplied the ordered bubble references. Each element contained a <code>bubbleId</code> and a <code>type</code>.</li>
<li><code>cursorDiskKV.key = bubbleId:X:&lt;bubbleId&gt;</code> supplied the full bubble body.</li>
</ol>
<p><img alt="Following one selected Cursor Composer through workspace and global SQLite" loading="lazy" src="/posts/2026-11-15_sessionviewer-and-cursor/cursor-selected-composer-reconstruction.svg"></p>
<p>This figure follows one selected Composer through one observed modern layout.</p>
<p>The array position inside <code>fullConversationHeadersOnly</code> is the conversation order. Sorting <code>bubbleId:*</code> keys would sort UUID-like identities rather than messages. A <code>type</code> value of <code>1</code> identifies a user bubble, and <code>2</code> identifies an assistant bubble. Every user bubble starts a new SessionViewer turn. Assistant bubbles contribute thoughts, tool calls, results, or responses to the current turn until the next user bubble appears. If an assistant bubble appears before any user bubble, SessionViewer preserves that evidence in a synthetic turn with an empty prompt. A Cursor <code>requestId</code> or <code>generationId</code> supplies a stable turn identity when present; neither ID starts the turn.</p>
<p>The following read-only queries verify the three physical joins for one Composer:</p>
<div class="highlight"><div class="chroma">
<table class="lntable"><tr><td class="lntd">
<pre tabindex="0" class="chroma"><code><span class="lnt"> 1
</span><span class="lnt"> 2
</span><span class="lnt"> 3
</span><span class="lnt"> 4
</span><span class="lnt"> 5
</span><span class="lnt"> 6
</span><span class="lnt"> 7
</span><span class="lnt"> 8
</span><span class="lnt"> 9
</span><span class="lnt">10
</span><span class="lnt">11
</span><span class="lnt">12
</span><span class="lnt">13
</span><span class="lnt">14
</span></code></pre></td>
<td class="lntd">
<pre tabindex="0" class="chroma"><code class="language-sql" data-lang="sql"><span class="line"><span class="cl"><span class="n">PRAGMA</span><span class="w"> </span><span class="n">query_only</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">ON</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="k">SELECT</span><span class="w"> </span><span class="o">*</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="k">FROM</span><span class="w"> </span><span class="n">composerHeaders</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="k">WHERE</span><span class="w"> </span><span class="n">composerId</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">&#39;90f37e83-0aa8-4d76-8e3a-094322899a3e&#39;</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="k">SELECT</span><span class="w"> </span><span class="n">value</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="k">FROM</span><span class="w"> </span><span class="n">cursorDiskKV</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="k">WHERE</span><span class="w"> </span><span class="k">key</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s1">&#39;composerData:90f37e83-0aa8-4d76-8e3a-094322899a3e&#39;</span><span class="p">;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="k">SELECT</span><span class="w"> </span><span class="k">key</span><span class="p">,</span><span class="w"> </span><span class="n">value</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="k">FROM</span><span class="w"> </span><span class="n">cursorDiskKV</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="k">WHERE</span><span class="w"> </span><span class="k">key</span><span class="w"> </span><span class="k">LIKE</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="s1">&#39;bubbleId:90f37e83-0aa8-4d76-8e3a-094322899a3e:%&#39;</span><span class="p">;</span><span class="w">
</span></span></span></code></pre></td></tr></table>
</div>
</div><p>The similarly named containers serve different purposes. The <code>composerHeaders</code> table contains session-level rows. An <code>ItemTable</code> value named <code>composer.composerHeaders</code> can contain aggregate session summaries. Inside one detailed Composer, <code>fullConversationHeadersOnly[]</code> contains ordered bubble references.</p>
<h2 id="probing-sqlite-instead-of-trusting-one-schema">Probing SQLite instead of trusting one schema</h2>
<p>I could not assume that every <code>state.vscdb</code> had the same tables, columns, or keys. The SQLite reader therefore performs a capability probe: it checks what the database contains before choosing a query. The implementation currently recognizes these forms:</p>
<ul>
<li><code>cursorDiskKV</code> is a Cursor key/value table. A <code>composerData:&lt;composer-id&gt;</code> key identifies one detailed Composer record, and a <code>bubbleId:&lt;composer-id&gt;:&lt;bubble-id&gt;</code> key identifies one bubble body.</li>
<li><code>ItemTable</code> is another key/value table. Values named <code>composer.composerHeaders</code> and <code>composer.composerData</code> can contain aggregate Composer summaries and data.</li>
<li><code>composerHeaders</code> is an alternative table layout with one Composer summary per row.</li>
<li>An aggregate payload can be a JSON array, an object containing <code>allComposers[]</code>, <code>composerHeaders[]</code>, or <code>headers[]</code>, or one Composer object.</li>
<li>One Composer can list ordered bubble references under <code>fullConversationHeadersOnly[]</code>, <code>conversationHeaders[]</code>, <code>fullConversation[]</code>, or <code>conversation[]</code>.</li>
</ul>
<p>SessionViewer opens each database in read-only mode with a two-second command timeout. SQLite can place recent committed changes in a separate write-ahead log file, abbreviated WAL. When <code>state.vscdb-wal</code> is present and accessible beside <code>state.vscdb</code>, the read-only SQLite connection can consult that sidecar. SessionViewer does not copy or manage the WAL. An offline snapshot made by copying only the main database while Cursor is active can therefore omit recent committed data. A value larger than the active profile&rsquo;s per-record limit (4 MiB in Balanced or 16 MiB in Complete), malformed JSON, or an unsupported layout marks the scan as incomplete and adds a warning instead of aborting the whole catalog refresh.</p>
<p>This is archaeology rather than relying on a supported Cursor storage API.</p>
<h2 id="making-the-reconstruction-inspectable-with-cursordbnavigator">Making the reconstruction inspectable with CursorDBNavigator</h2>
<p>SessionViewer answers “what happened in my local agent history?” Since I wanted to present how Cursor was storing the sessions/turns during conferences, I vibe coded a new companion application named <strong>CursorDBNavigator</strong> to answer a narrower question: “which physical Cursor row and which reconstruction rule produced this workspace, Composer, bubble, turn, or event?”</p>
<p>CursorDBNavigator is a separate Cursor-only WPF application in HarnessSpy. Its default <strong>Reconstruction</strong> tab follows four stages:</p>
<ol>
<li>workspace;</li>
<li>Composer/session;</li>
<li>ordered bubbles;</li>
<li>turns, thoughts, tools and responses.</li>
</ol>
<p>Startup uses the Desktop header scanner to create normalized workspace and Composer shells without bubble bodies. Selecting one session first indexes the <code>composerData:&lt;id&gt;</code> record and <code>bubbleId:&lt;id&gt;:*</code> rows for that Composer. Reconstruction then reloads the bounded JSON values by exact table and key and runs the same Desktop bubble-to-turn conversion used by SessionViewer. Selecting a bubble, turn, or event shows the applied rule, the relevant IDs, and a bounded raw-source preview. <strong>Go to source bubble</strong> moves from a turn or event back to the bubble that produced it. <strong>Go to physical row</strong> opens the exact SQLite table and key.</p>
<p>The separate <strong>Physical storage</strong> tab keeps the database visible as a database. It displays every discovered database and table, pages rows without loading an entire table into the grid, and shows columns, formatted JSON, and raw values. Known Cursor rows receive semantic inbound and outbound relations. A full store discovery can also correlate a SQLite row with a <code>workspace.json</code> manifest or a matching transcript. Missing and ambiguous relation targets remain visible instead of being silently guessed.</p>
<p>CursorDBNavigator does not replace SessionViewer. Its reconstructed tree uses the Desktop SQLite branch so that each logical node can stay attached to one physical row. It does not perform SessionViewer&rsquo;s full transcript/Desktop event reconciliation, plan binding, Claude or Copilot scanning, or presentation-only workspace inference. But it helps during conference demos  :^)</p>
<h2 id="inferring-a-likely-workspace-without-changing-identity">Inferring a likely workspace without changing identity</h2>
<p>Conservative identity matching can leave a real session under <strong>Unknown workspace</strong>. A transcript directory can be encoded ambiguously, a Desktop record can contain only an opaque workspace ID, and a session can operate on files outside the repository in which it started. SessionViewer now treats “which session is this?” and “where should I display it?” as separate questions.</p>
<p>For a session with an unknown or synthesized multi-root workspace, <code>CursorSessionWorkspaceInferrer</code> builds candidates from every known <code>workspace.json</code> manifest and from the single-root workspaces already observed in the catalog. Cursor derives a project-directory key from a workspace path, so one encoded transcript directory can sometimes match one manifest path. The inferrer adds independently inspectable signals:</p>
<ol>
<li>another record with the same native session ID and one known workspace scores 95;</li>
<li>one workspace whose Cursor project-key encoding matches the transcript directory scores 90;</li>
<li>a tool target or working path inside the most specific known root scores 75;</li>
<li>each root in a synthesized multi-root observation scores 70;</li>
<li>a rooted Windows path in the user prompt scores 65.</li>
</ol>
<p>Child-agent target paths do not move their parent session. A provider-observed single-root workspace needs no inference, and explicit multi-root workspace data is left alone.</p>
<p>For each candidate, SessionViewer starts with its strongest signal and adds five points for every additional kind of evidence, capped at 99. A candidate needs at least 60 points. The winner also needs a 15-point lead; otherwise the result remains <code>Ambiguous</code>.</p>
<p>For example, a unique project-key match starts at 90. Independent tool-path evidence adds five points, producing 95. If the next candidate scores 75, the 20-point lead exceeds the required margin of 15, so the 95-point candidate wins. One cross-repository tool operation cannot by itself outweigh the matching project identity.</p>
<p>A clear winning candidate places the session under that candidate workspace with an amber <code>?</code> overlay. Competing candidates keep the session under <strong>Unknown workspace</strong> with an amber <code>~</code>. The inspector still shows the provider-observed workspace separately from the likely workspace, score, evidence and alternatives. Workspace inference does not change the catalog key, does not participate in session merging, and does not turn an inferred folder into provider fact.</p>
<h2 id="one-tool-call-observed-twice">One tool call, observed twice</h2>
<p>Merging sessions and turns is not enough. A transcript and a Desktop bubble can each contain the same logical tool request under different native names:</p>
<div class="highlight"><div class="chroma">
<table class="lntable"><tr><td class="lntd">
<pre tabindex="0" class="chroma"><code><span class="lnt">1
</span><span class="lnt">2
</span></code></pre></td>
<td class="lntd">
<pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl">Transcript:  Shell
</span></span><span class="line"><span class="cl">Desktop:     run_terminal_command_v2
</span></span></code></pre></td></tr></table>
</div>
</div><p>If I simply concatenated both event lists, the tree and dashboard would report two shell calls even though Cursor ran one.</p>
<p><code>CursorSessionEventReconciler</code> is the Cursor-specific component that removes this second layer of duplication. <code>ToolCallId</code> is SessionViewer&rsquo;s normalized field for a provider-native tool-call identifier. A correlation key is SessionViewer&rsquo;s fallback grouping of equivalent tool categories or equivalent MCP server-and-tool identities. First in, first out (FIFO) means that the first unmatched transcript call is paired with the first unmatched Desktop call in the same group. The reconciler works inside each merged turn:</p>
<ol>
<li>pair transcript and Desktop requests by an exact native tool-call ID, stored in SessionViewer&rsquo;s <code>ToolCallId</code> field;</li>
<li>when no ID exists, calculate a SessionViewer correlation key from the tool category or Model Context Protocol (MCP) server-and-tool identity, then pair calls first in, first out (FIFO) within that key;</li>
<li>create one SessionViewer event with the timing, status, duration and result linkage observed in the Desktop bubble;</li>
<li>preserve the tool name, arguments and assistant-row grouping observed in the transcript;</li>
<li>attach the other source record as supplemental provenance.</li>
</ol>
<p>For example, suppose a transcript contains shell calls <code>T1</code> and <code>T2</code>, while Desktop contains equivalent calls <code>D1</code> and <code>D2</code>, and none has a native tool-call ID. All four calls receive the same SessionViewer shell correlation key. FIFO pairs <code>T1</code> with <code>D1</code>, then <code>T2</code> with <code>D2</code>. SessionViewer marks each combined event <code>Corroborated</code> and lists both origins in its provenance metadata without duplicating either call in the tree. The same pass removes duplicate assistant responses after collapsing leading, trailing, and repeated whitespace.</p>
<p>Many transcript rows have no timestamp. After the reconciler pairs a transcript tool request with a timed Desktop request, later transcript-only thoughts, responses, and the turn-ending row use the most recent paired Desktop time as a sorting hint. For example, if the paired Desktop request occurred at 10:03, an untimed transcript thought that follows the request can sort after 10:03. SessionViewer does not claim that Cursor timestamped the thought.</p>
<p>SessionViewer runs this reconciliation after the startup merge and again after session expansion adds Desktop bubble details.</p>
<p>MCP tools need one more distinction. Cursor transcript records named <code>GetDynamicTools</code> and Desktop records named <code>get_mcp_tools</code> only discover which MCP tools are available. SessionViewer displays those records as ordinary tool calls but does not count them as MCP executions. A transcript <code>CallDynamicTool</code> record and the matching Desktop <code>mcp-&lt;server&gt;-&lt;tool&gt;</code> record represent an actual MCP execution, so reconciliation counts that execution once.</p>
<p>That difference fixed a very visible problem: discovering ten MCP tools must not become ten MCP executions in the Summary dashboard.</p>
<h2 id="side-chats-and-child-agents">Side chats and child agents</h2>
<p>A Cursor side chat is a child Composer seeded with copies of turns from its parent. Cursor Desktop also stores background child Composers, while Cursor transcripts put child-agent logs in a <code>subagents</code> directory.</p>
<p>SessionViewer keeps a side chat as a separate session and uses Cursor&rsquo;s native <code>sideChatSeedTurnCount</code> value to remove the copied parent turns. For example, a value of <code>3</code> means that the first three side-chat turns are inherited copies and are removed from the side-chat session. For a background child, SessionViewer instead attaches the child&rsquo;s files and turns to the parent. The attached records retain the child Composer ID and type. When the transcript and SQLite sources both expose a relationship, SessionViewer removes inherited child or side-chat turns again before reconciling individual events.</p>
<p>SessionViewer does not invent a parent when Composer relationships form a cycle or refer to a missing Composer. The child remains visible as a separate session entry, and the scan reports a warning.</p>
<p>SessionViewer also removes empty, workspace-less Composer shells with no turns. Those unused “new chat” records otherwise add noise, while an orphaned session that contains conversation events remains visible.</p>
<h2 id="reconnecting-plans">Reconnecting plans</h2>
<p>Cursor plan files contain YAML front matter followed by Markdown. YAML front matter is the metadata block between the opening and closing <code>---</code> lines:</p>
<div class="highlight"><div class="chroma">
<table class="lntable"><tr><td class="lntd">
<pre tabindex="0" class="chroma"><code><span class="lnt">1
</span><span class="lnt">2
</span><span class="lnt">3
</span><span class="lnt">4
</span><span class="lnt">5
</span><span class="lnt">6
</span><span class="lnt">7
</span><span class="lnt">8
</span><span class="lnt">9
</span></code></pre></td>
<td class="lntd">
<pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nn">---</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Add session history</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">overview</span><span class="p">:</span><span class="w"> </span><span class="l">Rebuild local sessions and plans</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">todos</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span>- <span class="nt">id</span><span class="p">:</span><span class="w"> </span><span class="l">scan</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">content</span><span class="p">:</span><span class="w"> </span><span class="l">Scan provider files</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">status</span><span class="p">:</span><span class="w"> </span><span class="l">completed</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">isProject</span><span class="p">:</span><span class="w"> </span><span class="kc">false</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nn">---</span><span class="w">
</span></span></span></code></pre></td></tr></table>
</div>
</div><p>These front-matter fields belong to Cursor&rsquo;s plan file. A file can also begin with an HTML comment containing a native session UUID, but SessionViewer treats that marker as a workspace hint rather than proof of ownership. Ownership still comes from transcript activity. SessionViewer binds a plan only when one of these conditions identifies exactly one session:</p>
<ol>
<li>the session wrote or patched the plan&rsquo;s explicit <code>.plan.md</code> path;</li>
<li>a successful <code>CreatePlan</code> or <code>UpdatePlan</code> call from the session matches the plan&rsquo;s normalized <code>name</code>, <code>overview</code>, and todo ID/content pairs.</li>
</ol>
<p>SessionViewer calls the second rule a structured match. The structured-match key comes from the plan&rsquo;s <code>name</code>, <code>overview</code>, and todo ID/content pairs, not its Markdown body. For example, a successful <code>CreatePlan</code> call with the same name, overview and todos as the file establishes one ownership candidate even if the current todo status has changed. Similar Markdown prose without the matching structured fields does not establish ownership. A failed or aborted plan call does not establish ownership. A read, search or prompt attachment is recorded as a reference, not as ownership. If two sessions remain candidates, SessionViewer leaves the plan unbound and adds its own <code>Ambiguous</code> label.</p>
<p>Revision history has similar limits. A successful structured <code>CreatePlan</code> or <code>UpdatePlan</code> call can preserve a complete plan body, and the current file supplies the latest complete body. Revisions compare the body rather than front-matter todo status. A file edit may expose only a patch, not the complete document after the patch. SessionViewer calls that update opaque because the source proves that an edit occurred but does not contain the complete resulting plan body. SessionViewer marks the revision history as partial instead of inventing an intermediate version.</p>
<p>An unbound plan can still receive a presentation-only workspace. SessionViewer considers a unique native session marker, a session whose prompt attached the plan, and rooted file links or inline paths in the plan document. All usable signals must resolve to the same observed workspace; conflicting evidence leaves the workspace unknown. A uniquely placed plan appears under that workspace in <strong>Unbound plans (inferred)</strong> with a <code>?</code> overlay, but it remains unbound. Plans without one likely workspace stay under <strong>Orphan Plans</strong>. Bound plans remain under their owning session, and the session icon receives a small plan-document overlay.</p>
<h2 id="selected-does-not-mean-open">Selected does not mean open</h2>
<p>A recently modified file is not proof that a session is active. Neither is Cursor&rsquo;s persisted <code>selectedComposerId</code> or <code>selectedComposerIds</code> field. A selected Composer ID states which Composer was selected in Cursor when it wrote the workspace state. For example, the ID remains in <code>state.vscdb</code> after Cursor closes. SessionViewer exposes the Cursor-native selection as metadata; SessionViewer does not convert selection into an <code>Open</code> lifecycle state.</p>
<p>SessionViewer never enumerates processes or reads process command lines. Cursor transcript and SQLite entries therefore remain conservatively <strong>Closed</strong>. A Cursor transcript record whose <code>type</code> is <code>turn_ended</code> provides observed evidence that one turn ended; the record does not prove whether Cursor is still running. The absence of <code>turn_ended</code> does not change the session to <strong>Open</strong>.</p>
<p>When you select <strong>Open Session</strong> on a Desktop node, SessionViewer runs <code>cursor --reuse-window &quot;&lt;workspace&gt;&quot;</code>. The <code>cursor --reuse-window</code> command focuses or opens the workspace. Cursor exposes no supported public command that selects an arbitrary local Composer by ID inside that window, so SessionViewer does not claim that the exact conversation was selected. A Cursor Agent CLI entry can instead use <code>agent --resume=&lt;session-id&gt;</code> when its metadata identifies that CLI entry point.</p>
<h2 id="three-tools-for-three-questions">Three tools for three questions</h2>
<p>The reconstruction work now needs three deliberately different tools:</p>
<ul>
<li><strong>SessionViewer</strong> answers “what happened?” It combines provider sources into a normalized, reconciled history with plans and workspace placement.</li>
<li><strong>CursorDBNavigator</strong> answers “why does this interpretation exist?” It exposes the Cursor SQLite rows, keys, relations, reconstruction rules and source evidence behind one result.</li>
<li><strong>Cursor Session Explorer</strong> answers “how do I find or reopen this session inside Cursor?” It emphasizes navigation rather than a complete event timeline.</li>
</ul>
<p>This work also led me to build <strong>Cursor Session Explorer</strong>, a Windows-first extension that runs inside Cursor but this will probably be the topics of another post.</p>
<h2 id="what-remains-uncertain">What remains uncertain</h2>
<p>Cursor&rsquo;s passive history still has hard limits:</p>
<ul>
<li>transcript and SQLite formats are undocumented and version-dependent;</li>
<li>transcript rows can lack timestamps, IDs, results, usage and skill evidence;</li>
<li>likely-workspace placement can remain ambiguous when project, prompt and tool-path evidence disagree;</li>
<li>event pairing falls back to FIFO when two calls have the same SessionViewer correlation key;</li>
<li>child transcripts are scanned only one level below <code>subagents</code>;</li>
<li>portable or alternate user-data roots, remote stores, and cloud agents are not covered;</li>
<li>every discovery profile has finite limits, so the incomplete-scan warning matters.</li>
</ul>
<p>Raw provenance can also contain prompts, source code, commands, results, and secrets. SessionViewer does not modify the provider files, but anyone who can use its inspector can read that stored content. The optional snapshot cache is compressed, not encrypted, so cached records need the same protection as the original files.</p>
<h2 id="conclusion">Conclusion</h2>
<p>Cursor history is not one transcript waiting to be displayed:</p>
<ol>
<li><strong>Identity and placement are different decisions.</strong> A matching Composer ID can join records only when the workspace also matches or no competing record exists. A likely workspace can organize an unresolved session without changing that identity.</li>
<li><strong>Turn merging does not remove event duplicates.</strong> Transcript and Desktop tool requests must be paired again inside each turn.</li>
<li><strong>Plan ownership and plan placement are different too.</strong> An explicit write path or one unique structured-content match can identify an owner; references and document paths can suggest a workspace but cannot bind the plan.</li>
<li><strong>Persisted selection does not prove that a session is active.</strong> SessionViewer keeps Cursor sessions closed because a recent file or selected Composer cannot prove that a process still exists.</li>
<li><strong>Large history needs staged, reloadable evidence.</strong> Startup reads Composer shells, session expansion loads Desktop bubbles, and the inspector reloads raw records only when needed.</li>
<li><strong>A logical reconstruction still needs a path back to physical evidence.</strong> CursorDBNavigator keeps the workspace, Composer, bubble, turn and event views connected to the original database table and key.</li>
</ol>
<p>The next post applies the same SessionViewer model to Claude Code, whose archive is split between prompt history, transcripts, subagents and plan artifacts.</p>
<h2 id="references">References</h2>
<ul>
<li><a href="https://github.com/chrisnas/HarnessSpy">HarnessSpy source code</a></li>
<li><a href="https://github.com/chrisnas/HarnessSpy/blob/main/src/architecture.md">Current SessionViewer and CursorDBNavigator architecture</a></li>
<li><a href="https://github.com/chrisnas/HarnessSpy/tree/main/src/Shared/HarnessSpy.Core/Sessions/Cursor">Cursor session source implementation</a></li>
<li><a href="https://github.com/chrisnas/HarnessSpy/tree/main/src/Apps/CursorDBNavigator">CursorDBNavigator application</a></li>
<li><a href="/posts/2026-08-23_spying-on-cursor-hooks/">Part 1: Spying on Cursor</a></li>
<li><a href="/posts/2026-09-14_rebuilding-cursor-conversation/">Part 2: Rebuilding the Agent conversation</a></li>
<li><a href="/posts/2026-09-20_spying-on-claude-code-hooks/">Part 3: Spying on Claude Code</a></li>
<li><a href="/posts/2026-09-27_spying-on-github-copilot-twice/">Part 4: Spying on GitHub Copilot twice</a></li>
<li><a href="/posts/2026-10-09_beyond-hooks-transcript-logs/">Part 5: Beyond hooks</a></li>
</ul>
]]></content:encoded></item></channel></rss>