dsh-nerd-mode 0.4.6 → 0.5.0

package/README.md

@@ -48,7 +48,8 @@ A chat lesson ends when the answer arrives. Nothing checks that you understood i
 - **Graded checks.** Unseen questions and a graded teach-back, with the rubric written before the question. Only an answer you produced changes the record.
 - **A record that outlives the chat.** Graph, states, and dated log survive restarts, and the HTML Book has full-text search.
 - **Progress without opening a file.** The Study tab reads the Tracker for this conversation and shows one progress percentage, the previous, current, and next Section, the shaky Concepts, and the three most recent Concept cycles. It never writes.
-- **Lectures you can find again.** The Lectures tab lists the saved lectures for the selected Course, and marks read, unread, and archived rows.
+- **Lectures you can find again.** The Lectures tab keeps the course picker in the page header, lists only the courses that exist, and marks each lecture as a draft, a dated lecture, or an archived one. The archived lectures fold behind a count.
+- **Your study conversations in one place.** The Study Sessions panel in the left sidebar lists every conversation where Nerd Mode was switched on at least once, in three groups: In-depth, Quick, and Past. Each group folds from its heading, In-depth and Quick start open, Past starts closed, and a click opens that conversation.
 
 ## Install
 
@@ -225,10 +226,11 @@ package.json
 │     ├── dsh-nerd-mode → lib/index.js
 │     │     ├── session projection — on/off state, folded from the session log
 │     │     ├── prompt section — assets/section.md at order 550, while on
-│     │     └── /nerd-mode — the switch
+│     │     ├── /nerd-mode — the switch
+│     │     └── GET /api/study-sessions — the read-only session index
 │     ├── study-plus-skills — skills/ as a filesystem skill provider
 │     └── goal packages — disabled
-└── dsh.client → client.js: pill, Study tab, Lectures tab, Settings section
+└── dsh.client → client.js: pill, Study tab, Lectures tab, Study Sessions panel, Settings section
 ```
 
 **State** lives in a session projection. It folds from the session log, so compaction, resume, and fork keep it. The prompt section has text only while that state is on.
@@ -237,6 +239,8 @@ package.json
 
 **Settings** reach the model as a short defaults block appended to that section, only during a tracked session. They never change the tool set.
 
+**Session history** is a second, read-only store. `lib/study-sessions.js` scans the conversation logs in chunks, keys each file by its size and modification time, and writes `~/.dsh/study-sessions-index.json`, which sits outside every workspace. The panel reads it through one route that answers only GET, refuses a request with no session cookie (401) and a foreign host or origin (403).
+
 **Patch scope** covers the whole profile. It loads `skills/` with a `!!js` expression, so review patch changes as host-process code. It also disables the three goal packages, because the built-in goal tool turns one study answer into an auto-continuing run.
 
 ## What the switch changes
@@ -277,9 +281,10 @@ npm run check
 
 | Path | Holds |
 |---|---|
-| `lib/index.js` | plugin entry: projection, prompt section, command, session defaults |
+| `lib/index.js` | plugin entry: projection, prompt section, command, session defaults, session index route |
 | `lib/fold.js` | the state fold and its constants |
-| `client.js` | composer pill, Study and Lectures tabs, Settings section |
+| `lib/study-sessions.js` | the session history scan and its index |
+| `client.js` | composer pill, Study and Lectures tabs, Study Sessions panel, Settings section |
 | `assets/section.md` | the teaching policy prompt |
 | `skills/` | bundled skills |
 | `test/` | one file per surface, run by `node --test` |

package/README.zh.md

@@ -48,7 +48,8 @@
 - **有评分的检查。** 没见过的题加上要评分的复述，评分标准在出题之前就写好。只有你自己答出来的内容才会改写记录。
 - **记录比对话活得久。** 概念图、状态和带日期的日志能跨重启保留，HTML 书支持全文搜索。
 - **不用翻文件就能看进度。** Study 标签页读当前对话的记录文件，显示进度百分比，上一节、当前节、下一节三格，状态是 shaky 的概念，以及最近三轮概念循环。它只读，不写。
-- **讲义找得回来。** Lectures 标签页按选中的 Course 列出保存过的讲义，并标出已读、未读和已归档的行。
+- **讲义找得回来。** Lectures 标签页把课程下拉放在页头，只列出真实存在的 Course，并把每份讲义标成草稿、带日期或已归档。已归档的讲义收在一个折叠区里，标题旁显示数量。
+- **学习会话都在一处。** 左侧边栏的 Study Sessions 面板列出所有至少打开过一次 Nerd Mode 的会话，分「深入」「快速」「过去」三组。每组都能点标题折叠，深入和快速默认展开，过去默认收起，点一行就打开那个会话。
 
 ## 安装
 
@@ -225,10 +226,11 @@ package.json
 │     ├── dsh-nerd-mode → lib/index.js
 │     │     ├── session projection — 开关状态，从会话日志折叠出来
 │     │     ├── prompt section — assets/section.md，顺序 550，只在开着时注入
-│     │     └── /nerd-mode — 开关
+│     │     ├── /nerd-mode — 开关
+│     │     └── GET /api/study-sessions — 只读的学习会话索引
 │     ├── study-plus-skills — skills/ 作为文件系统技能来源
 │     └── goal packages — 已禁用
-└── dsh.client → client.js：胶囊、Study 标签页、Lectures 标签页、设置页
+└── dsh.client → client.js：胶囊、Study 标签页、Lectures 标签页、Study Sessions 面板、设置页
 ```
 
 **状态**存在一个 session projection 里，从会话日志折叠出来，所以压缩上下文、恢复会话、分叉都不丢。只有那个状态是「开着」时，提示段落才有内容。
@@ -237,6 +239,8 @@ package.json
 
 **设置**只在带记录的会话里，以一小段默认值附在那段提示后面。它们从不改变工具目录。
 
+**会话历史**是第二份只读记录。`lib/study-sessions.js` 分块扫描会话日志，按文件大小和修改时间记账，写到 `~/.dsh/study-sessions-index.json`，这个文件在每个工作区之外。面板通过一条路由读它：只接受 GET，没有会话 cookie 的请求返回 401，主机名或来源不对返回 403。
+
 **补丁范围**覆盖整个 profile。补丁用 `!!js` 表达式加载 `skills/`，改之前要按宿主进程代码来审。补丁还禁用了三个 goal 包，因为内置的 goal 工具会把一次讲解变成自动续跑的循环。
 
 ## 开关改了什么
@@ -277,9 +281,10 @@ npm run check
 
 | 路径 | 内容 |
 |---|---|
-| `lib/index.js` | 插件入口：投影、提示段落、命令、会话默认值 |
+| `lib/index.js` | 插件入口：投影、提示段落、命令、会话默认值、会话索引路由 |
 | `lib/fold.js` | 状态折叠与常量 |
-| `client.js` | 输入框胶囊、Study 与 Lectures 标签页、设置页 |
+| `lib/study-sessions.js` | 会话历史扫描与索引 |
+| `client.js` | 输入框胶囊、Study 与 Lectures 标签页、Study Sessions 面板、设置页 |
 | `assets/section.md` | 教学策略提示词 |
 | `skills/` | 随包的技能 |
 | `test/` | 每个界面一个文件，由 `node --test` 运行 |

package/client.js

@@ -1556,52 +1556,37 @@ window.__ModuleLoader__.load({
       return model;
     }
 
-    // The page fills the dock body so the picker and course name stay in view
-    // while only the lecture rows scroll. The scrollport owns the side padding,
-    // so its bar sits at the page edge rather than inside the text.
-    const lecturesPanelStyle = { ...panelStyle, height: '100%', padding: '24px 0 0' };
-    const lecturesHeaderStyle = { ...panelHeaderStyle, padding: '0 16px' };
-    const lecturesMessageStyle = { ...panelMutedStyle, padding: '0 16px' };
-    const lecturesHeadingStyle = { ...panelHeadingStyle, padding: '0 16px' };
-    const lecturesSectionStyle = { ...panelSectionStyle, flex: 1, minHeight: 0 };
-    const lecturesScrollStyle = {
-      display: 'flex',
-      flex: 1,
-      flexDirection: 'column',
-      gap: 10,
-      minHeight: 0,
-      overflowY: 'auto',
-      padding: '0 16px 40px',
-    };
-
-    // The rows and the fold are the only elements the host cannot style for us.
-    const LECTURES_CSS = '.lectures-entry:focus-visible,.lectures-fold:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary, currentColor);outline-offset:2px}';
-    const lectureRowStyle = {
-      background: 'none',
-      border: 'none',
-      borderRadius: 'var(--dsw-radius-sm, 6px)',
-      color: 'inherit',
-      cursor: 'pointer',
-      font: 'inherit',
-      lineHeight: '22px',
-      overflowWrap: 'anywhere',
-      padding: '2px 4px',
-      textAlign: 'left',
-      whiteSpace: 'normal',
-      width: '100%',
-    };
-    const lectureFoldStyle = {
-      background: 'none',
-      border: '1px solid var(--dsw-alias-border-l2)',
-      borderRadius: 'var(--dsw-radius-sm, 6px)',
-      color: 'var(--dsw-alias-label-tertiary)',
-      cursor: 'pointer',
-      font: 'inherit',
-      lineHeight: '22px',
-      padding: '6px 10px',
-      textAlign: 'left',
-      width: '100%',
-    };
+    // The picker and Course name stay in view while only the lecture rows
+    // scroll. The scroller owns the side padding, so its bar sits at the page
+    // edge rather than inside the text.
+    const LECTURES_CSS = `.lectures-page{box-sizing:border-box;height:100%;display:flex;flex-direction:column;color:var(--dsw-alias-label-primary);font-family:var(--dsw-font-family,inherit)}
+.lectures-head{display:flex;align-items:center;gap:12px;padding:24px 32px 0}
+.lectures-picker{display:flex;align-items:center;gap:8px;flex:1;min-width:0;font-size:13px;line-height:20px;color:var(--dsw-alias-label-secondary)}
+.lectures-select{flex:1;min-width:0;height:32px;padding:0 8px;border:1px solid var(--dsw-alias-border-l3);border-radius:var(--dsw-radius-sm,8px);background:var(--dsw-alias-bg-layer-1);color:var(--dsw-alias-label-primary);font:inherit}
+.lectures-group{display:flex;flex-direction:column;flex:1;min-height:0}
+.lectures-group-head{display:flex;align-items:center;gap:8px;padding:20px 32px 8px}
+.lectures-group-title{margin:0;font-size:14px;line-height:22px;font-weight:500;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.lectures-count{flex:none;font-size:13px;line-height:20px;font-weight:400;color:var(--dsw-alias-label-tertiary)}
+.lectures-scroll{flex:1;min-height:0;overflow-y:auto;display:flex;flex-direction:column;gap:2px;padding:0 32px 32px}
+.lectures-rows{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:2px}
+.lectures-item{margin:0 -8px}
+.lectures-row{position:relative;width:100%;box-sizing:border-box;display:grid;grid-template-columns:28px minmax(0,1fr);grid-template-areas:"tile title" "tile meta";column-gap:12px;row-gap:2px;align-items:start;padding:8px;border:none;border-radius:var(--dsw-radius-xl,20px);background:transparent;color:inherit;font:inherit;text-align:left;cursor:pointer;white-space:normal}
+.lectures-row:hover{background:var(--dsw-alias-interactive-bg-hover)}
+.lectures-row:focus-visible{outline:none}
+.lectures-row:focus-visible::after{content:"";position:absolute;inset:0;border-radius:inherit;outline:2px solid var(--dsw-focus-ring-color,var(--dsw-alias-state-business-primary));outline-offset:2px}
+.lectures-tile{grid-area:tile;align-self:center;width:28px;height:28px;display:grid;place-items:center;border-radius:6px;background:var(--dsw-alias-fill-tsp-secondary);color:var(--dsw-alias-label-secondary);font:600 11px/1 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-variant-numeric:tabular-nums}
+.lectures-title{grid-area:title;font-size:14px;line-height:20px;font-weight:500;overflow-wrap:anywhere}
+.lectures-meta{grid-area:meta;display:flex;align-items:center;gap:6px;min-width:0;font-size:13px;line-height:18px;color:var(--dsw-alias-label-tertiary)}
+.lectures-chip{display:inline-flex;align-items:center;height:18px;padding:0 7px;font-size:11px;line-height:17px;border:.5px solid var(--dsw-alias-border-l3);border-radius:999px;color:var(--dsw-alias-label-tertiary);white-space:nowrap}
+.lectures-fold{align-self:flex-start;display:inline-flex;align-items:center;gap:8px;margin-top:12px;padding:0;border:none;background:none;font-size:14px;line-height:22px;font-weight:500;color:var(--dsw-alias-label-primary);cursor:pointer}
+.lectures-fold:focus-visible{outline:2px solid var(--dsw-focus-ring-color,var(--dsw-alias-state-business-primary));outline-offset:2px}
+.lectures-chev{color:var(--dsw-alias-label-tertiary);transition:transform 120ms}
+.lectures-fold[aria-expanded="false"] .lectures-chev{transform:rotate(-90deg)}
+.lectures-status{margin:0;padding:8px 32px;font-size:13px;line-height:20px;color:var(--dsw-alias-label-secondary)}
+.lectures-error{display:flex;align-items:center;gap:8px;margin:0;padding:8px 32px;font-size:13px;line-height:20px;color:var(--dsw-alias-state-error-primary)}
+.lectures-dot{flex:none;width:6px;height:6px;border-radius:50%;background:currentColor}
+.lectures-empty{margin:0;padding:48px 20px;text-align:center;font-size:14px;line-height:22px;color:var(--dsw-alias-label-tertiary)}
+.lectures-empty code{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12px;line-height:18px;background:var(--dsw-alias-bg-layer-2);border-radius:6px;padding:1px 6px}`;
 
     const LECTURE_MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
 
@@ -1636,26 +1621,38 @@ window.__ModuleLoader__.load({
       return `${FILE_ADDRESS_PREFIX}session/${encodeSegment(sessionId)}/${encodePath(normalized)}`;
     }
 
-    // The whole row is the button, so its text is also its accessible name.
+    // The visible title is clipped, so the label repeats it in full.
     function lectureRow(entry, onOpen) {
       const mark = lectureMark(entry);
-      return React.createElement('li', { key: entry.number },
+      const label = mark === null
+        ? `${entry.number}, ${entry.title}`
+        : `${entry.number}, ${entry.title}, ${mark}`;
+      return React.createElement('li', { key: entry.number, className: 'lectures-item' },
         React.createElement('button', {
           type: 'button',
-          className: 'lectures-entry',
+          className: 'lectures-row',
+          'aria-label': label,
           onClick: () => onOpen(entry),
-          style: lectureRowStyle,
-        }, `${entry.number} · ${entry.title}${mark === null ? '' : ` · ${mark}`}`));
+        },
+        React.createElement('span', { className: 'lectures-tile', 'aria-hidden': 'true' }, entry.number),
+        React.createElement('span', { className: 'lectures-title' }, entry.title),
+        mark === null
+          ? null
+          : React.createElement('span', { className: 'lectures-meta' },
+              entry.mark === 'dated'
+                ? mark
+                : React.createElement('span', { className: 'lectures-chip' }, mark))));
     }
 
     function lectureTopic(group, open, onToggle, onOpen) {
       const main = group.entries.filter((entry) => entry.mark !== 'archived');
       const archived = group.entries.filter((entry) => entry.mark === 'archived');
+      const archiveId = `lectures-archive-${group.topic}`;
       const rows = [];
       if (group.entries.length === 0) {
-        rows.push(React.createElement('p', { key: 'empty', style: panelMutedStyle }, 'No lectures yet.'));
+        rows.push(React.createElement('p', { key: 'empty', className: 'lectures-empty' }, 'No lectures yet.'));
       } else if (main.length > 0) {
-        rows.push(React.createElement('ul', { key: 'main', style: panelListStyle }, ...main.map((entry) => lectureRow(entry, onOpen))));
+        rows.push(React.createElement('ul', { key: 'main', className: 'lectures-rows' }, ...main.map((entry) => lectureRow(entry, onOpen))));
       }
       if (archived.length > 0) {
         rows.push(React.createElement('button', {
@@ -1663,17 +1660,35 @@ window.__ModuleLoader__.load({
           type: 'button',
           className: 'lectures-fold',
           'aria-expanded': open,
+          // A closed fold has no list to control, so the reference would dangle.
+          'aria-controls': open ? archiveId : undefined,
+          'aria-label': `Archived lectures ${archived.length}`,
           onClick: () => onToggle(group.topic),
-          style: lectureFoldStyle,
-        }, `Archived lectures (${archived.length})`));
+        },
+        React.createElement('span', null, 'Archived lectures'),
+        React.createElement('span', { className: 'lectures-count' }, String(archived.length)),
+        React.createElement('svg', {
+          'aria-hidden': 'true',
+          className: 'lectures-chev',
+          fill: 'none',
+          height: 12,
+          stroke: 'currentColor',
+          strokeLinecap: 'round',
+          strokeLinejoin: 'round',
+          strokeWidth: 1.6,
+          viewBox: '0 0 16 16',
+          width: 12,
+        }, React.createElement('path', { d: 'M3.5 6 8 10.5 12.5 6' }))));
         if (open) {
-          rows.push(React.createElement('ul', { key: 'archive', style: panelListStyle }, ...archived.map((entry) => lectureRow(entry, onOpen))));
+          rows.push(React.createElement('ul', { key: 'archive', className: 'lectures-rows', id: archiveId }, ...archived.map((entry) => lectureRow(entry, onOpen))));
         }
       }
       // The Course key remounts the section on a switch, so its scrollport starts at the top.
-      return React.createElement('section', { key: group.topic, style: lecturesSectionStyle },
-        React.createElement('h2', { key: 'heading', style: lecturesHeadingStyle }, group.topic),
-        React.createElement('div', { style: lecturesScrollStyle }, ...rows));
+      return React.createElement('section', { key: group.topic, className: 'lectures-group' },
+        React.createElement('div', { className: 'lectures-group-head' },
+          React.createElement('h2', { className: 'lectures-group-title' }, group.topic),
+          React.createElement('span', { className: 'lectures-count' }, String(main.length))),
+        React.createElement('div', { className: 'lectures-scroll' }, ...rows));
     }
 
     function LecturesPage({ useTabInfo, sessionId, workspaceFiles }) {
@@ -1707,15 +1722,18 @@ window.__ModuleLoader__.load({
 
       let nodes;
       if (content.status === 'loading') {
-        nodes = [React.createElement('p', { role: 'status', 'aria-busy': true, style: lecturesMessageStyle }, 'Loading the lectures…')];
+        nodes = [React.createElement('p', { role: 'status', 'aria-busy': true, className: 'lectures-status' }, 'Loading the lectures…')];
       } else if (content.error === null && !content.rootFound) {
-        nodes = [React.createElement('p', { style: lecturesMessageStyle }, `No Course in ${TRACKER_ROOT}/. Run /study-plus to create one.`)];
+        nodes = [React.createElement('p', { className: 'lectures-empty' },
+          `No Course in ${TRACKER_ROOT}/. Run `,
+          React.createElement('code', null, '/study-plus'),
+          ' to create one.')];
       } else {
         nodes = content.error === null
           ? []
-          : [React.createElement('p', { role: 'alert', style: lecturesMessageStyle }, `The lecture library could not be read: ${content.error}.`)];
-        const picker = topicPicker(content.courses, content.course ?? selected, choose);
-        if (picker !== null) nodes.push(React.createElement('div', { style: lecturesHeaderStyle }, picker));
+          : [React.createElement('p', { role: 'alert', className: 'lectures-error' },
+              React.createElement('span', { className: 'lectures-dot', 'aria-hidden': 'true' }),
+              `The lecture library could not be read: ${content.error}.`)];
         if (content.course !== null) {
           nodes.push(lectureTopic(
             { topic: content.course, entries: content.entries },
@@ -1725,11 +1743,24 @@ window.__ModuleLoader__.load({
           ));
         }
       }
+
+      // One Course needs no picker: the page already shows that Course.
+      const courses = content.courses ?? [];
+      const picker = courses.length < 2 ? null : React.createElement('label', { className: 'lectures-picker' },
+        React.createElement('span', null, 'Course'),
+        React.createElement('select', {
+          'aria-label': 'Course',
+          className: 'lectures-select',
+          value: content.course ?? selected,
+          onChange: (event) => choose(event.target.value),
+        }, ...courses.map((course) => React.createElement('option', { key: course, value: course }, course))));
       return React.createElement('div', {
         role: 'region',
         'aria-label': LECTURES_LABEL,
-        style: lecturesPanelStyle,
-      }, React.createElement('style', null, LECTURES_CSS), ...nodes);
+        className: 'lectures-page',
+      }, React.createElement('style', null, LECTURES_CSS),
+      React.createElement('header', { className: 'lectures-head' }, picker),
+      ...nodes);
     }
 
     // A page type names no resource pattern and no `multiple`, so the host
@@ -1747,6 +1778,365 @@ window.__ModuleLoader__.load({
       }],
     };
 
+    // --- Study Sessions panel ------------------------------------------------
+
+    const STUDY_SESSIONS_ID = 'study-sessions';
+    const STUDY_SESSIONS_ORDER = 30;
+    const STUDY_SESSIONS_API = '/dsh-nerd-mode/api/study-sessions';
+    const STUDY_SESSIONS_TITLE = { en: 'Study Sessions', zh: '学习会话' };
+    const STUDY_QUICK = { en: 'Quick', zh: '快速' };
+    const STUDY_IN_DEPTH = { en: 'In-depth', zh: '深入' };
+    const STUDY_PAST = { en: 'Past', zh: '过去' };
+
+    // A host without the session package still gets the page and its empty line.
+    const NO_SESSIONS_HOOK = () => null;
+
+    // A failed rescan or a remount must not blank the panel, so the last good scan outlives the component.
+    let studySessionsCache = null;
+
+    /**
+     * Read one history chunk from the host route.
+     *
+     * Returns `{ phase, done, total, sessions, cursor }`. Throws an Error whose message names the failure:
+     * a missing route (404/405 or a body that is not JSON) and any non-OK reply both count.
+     */
+    async function readSessionChunk(cursor) {
+      const response = await fetch(`${STUDY_SESSIONS_API}?cursor=${cursor}`);
+      // The static fallback owns an unregistered path, so it answers with an empty body.
+      if (response.status === 404 || response.status === 405) throw new Error('the host route is not available');
+      // A rejected request carries plain text, so name the status before the body is parsed.
+      if (response.status === 401 || response.status === 403) {
+        throw new Error(`the host denied the request (HTTP ${response.status})`);
+      }
+      const body = await response.json().catch(() => null);
+      if (body === null) throw new Error('the host returned no JSON');
+      if (!response.ok) throw new Error(body?.error ?? `HTTP ${response.status}`);
+      const sessions = body?.sessions;
+      if (typeof sessions !== 'object' || sessions === null) throw new Error('the host returned no session history');
+      return {
+        phase: body.phase === 'ready' ? 'ready' : 'scanning',
+        done: Number.isFinite(body.done) ? body.done : 0,
+        total: Number.isFinite(body.total) ? body.total : 0,
+        sessions,
+        // The spec names no cursor field, so accept one or fall back to the processed count.
+        cursor: Number.isFinite(body.cursor) ? body.cursor : Number.isFinite(body.done) ? body.done : cursor,
+      };
+    }
+
+    /**
+     * Scan the host history index from cursor 0, merging each chunk into `sessions`.
+     *
+     * Calls `onChunk` after every reply so the page can move its progress line. Returns the final
+     * scan state. A host that repeats a cursor cannot make progress, so the loop stops there.
+     */
+    async function scanSessionHistory(sessions, onChunk) {
+      let state = { status: 'scanning', sessions, done: 0, total: 0, cursor: 0 };
+      let previous = 0;
+      for (;;) {
+        const chunk = await readSessionChunk(state.cursor);
+        state = {
+          status: chunk.phase,
+          // A ready reply carries the host's whole index, so it replaces stale cached ids.
+          sessions: chunk.phase === 'ready' ? chunk.sessions : { ...state.sessions, ...chunk.sessions },
+          done: chunk.done,
+          total: chunk.total,
+          cursor: chunk.cursor,
+        };
+        onChunk(state);
+        if (state.status === 'ready' || chunk.cursor <= previous) return state;
+        previous = chunk.cursor;
+      }
+    }
+
+    /** Return the last folder in a workspace path; Windows and POSIX separators both count. */
+    function workspaceName(cwd) {
+      if (typeof cwd !== 'string') return '';
+      return cwd.split(/[\\/]+/).filter((part) => part !== '').pop() ?? '';
+    }
+
+    const RELATIVE_UNITS = [
+      ['year', 31536000000],
+      ['month', 2592000000],
+      ['day', 86400000],
+      ['hour', 3600000],
+      ['minute', 60000],
+      ['second', 1000],
+    ];
+
+    /** Return a locale-aware relative time such as `2 hours ago`; a missing time reads as an empty string. */
+    function relativeTime(updatedAt, language) {
+      if (!Number.isFinite(updatedAt)) return '';
+      const elapsed = updatedAt - Date.now();
+      const [unit, size] = RELATIVE_UNITS.find(([, step]) => Math.abs(elapsed) >= step) ?? RELATIVE_UNITS[5];
+      return new Intl.RelativeTimeFormat(language, { numeric: 'auto' }).format(Math.round(elapsed / size), unit);
+    }
+
+    /** Join the live session list with the history index. A history id with no live row is dropped. */
+    function sessionRows(snapshot, history) {
+      const ids = Array.isArray(snapshot?.ids) ? snapshot.ids : [];
+      const byId = snapshot?.byId ?? {};
+      const rows = [];
+      for (const id of ids) {
+        const row = byId[id];
+        if (row === undefined || !Object.hasOwn(history, id)) continue;
+        rows.push({
+          id,
+          title: String(row.displayTitle ?? id),
+          workspace: workspaceName(row.cwd),
+          updatedAt: Number.isFinite(row.updatedAt) ? row.updatedAt : 0,
+          active: row.projectionValues?.studyMode?.active === true,
+          studyPlus: history[id]?.studyPlus === true,
+        });
+      }
+      return rows.sort((left, right) => right.updatedAt - left.updatedAt);
+    }
+
+    /** Split rows into Quick, In-depth, and Past; a missing live switch value counts as off. */
+    function groupSessionRows(rows) {
+      const groups = { quick: [], inDepth: [], past: [] };
+      for (const row of rows) {
+        if (!row.active) groups.past.push(row);
+        else if (row.studyPlus) groups.inDepth.push(row);
+        else groups.quick.push(row);
+      }
+      return groups;
+    }
+
+    // The tile is decoration; the group heading and the row label carry the meaning.
+    function studyTile(kind) {
+      const glyph = (children) => React.createElement('svg', {
+        fill: 'none',
+        height: 16,
+        stroke: 'currentColor',
+        strokeLinecap: 'round',
+        strokeLinejoin: 'round',
+        strokeWidth: 1.6,
+        viewBox: '0 0 16 16',
+        width: 16,
+      }, ...children);
+      if (kind === 'book') return glyph(BOOK.props.children);
+      if (kind === 'quick') {
+        return glyph([
+          React.createElement('path', { d: 'M13.4 8.9a3.7 3.7 0 0 1-3.7 3.7H6.4L3.4 14.6v-2.5A3.7 3.7 0 0 1 1.8 9V7.5a3.7 3.7 0 0 1 3.7-3.7h4.2a3.7 3.7 0 0 1 3.7 3.7Z' }),
+          React.createElement('path', { d: 'M5.2 7.3h5.6M5.2 9.3h3.4' }),
+        ]);
+      }
+      return glyph([
+        React.createElement('circle', { cx: 8, cy: 8, r: 5.6 }),
+        React.createElement('path', { d: 'M8 5.2V8l1.9 1.3' }),
+      ]);
+    }
+
+    // Inline because the client bundle cannot read assets/.
+    function StudySessionsIcon({ size = 16, active = false }) {
+      return React.createElement(
+        'svg',
+        {
+          'aria-hidden': 'true',
+          fill: 'none',
+          height: size,
+          stroke: 'currentColor',
+          strokeLinecap: 'round',
+          strokeLinejoin: 'round',
+          strokeWidth: active ? 2 : 1.6,
+          viewBox: '0 0 16 16',
+          width: size,
+        },
+        React.createElement('path', { d: 'M2.5 4h11M2.5 8h11M2.5 12h7' }),
+        React.createElement('circle', {
+          cx: 12.5,
+          cy: 12,
+          fill: 'currentColor',
+          opacity: active ? 1 : 0.45,
+          r: 1.2,
+          stroke: 'none',
+        }),
+      );
+    }
+
+    function StudySessionsPage({ useSessions, locale, openSession }) {
+      const t = useT(locale);
+      const language = locale.getSnapshot()?.active ?? 'en';
+      const [scan, setScan] = React.useState(() => studySessionsCache === null
+        ? { status: 'scanning', sessions: {}, done: 0, total: 0, cursor: 0 }
+        : { ...studySessionsCache, status: 'scanning' });
+      // Only a folded key reads true: In-depth and Quick start open, Past starts folded.
+      const [folded, setFolded] = React.useState({ inDepth: false, quick: false, past: true });
+      const snapshot = useSessions((state) => state);
+
+      React.useEffect(() => {
+        let live = true;
+        // A cached list seeds the scan, so rows stay while the host rescans.
+        scanSessionHistory(studySessionsCache?.sessions ?? {}, (chunk) => {
+          if (!live) return;
+          studySessionsCache = chunk;
+          setScan(chunk);
+        }).catch((error) => {
+          if (!live) return;
+          setScan((previous) => ({
+            ...previous,
+            status: 'failed',
+            reason: error?.message ?? 'the host did not answer',
+          }));
+        });
+        return () => { live = false; };
+      }, []);
+
+      const grouped = groupSessionRows(sessionRows(snapshot, scan.sessions));
+
+      // The row is one target, so its label names the title, workspace, time, and mode.
+      const rowNode = (row, past) => {
+        const time = relativeTime(row.updatedAt, language);
+        const chip = past ? t(row.studyPlus ? STUDY_IN_DEPTH : STUDY_QUICK) : null;
+        const label = [row.title, row.workspace, time, chip]
+          .filter((part) => part !== '' && part !== null)
+          .join(', ');
+        return React.createElement('li', { className: 'study-ss-item', key: row.id },
+          React.createElement('button', {
+            type: 'button',
+            className: 'study-ss-row',
+            'aria-label': label,
+            onClick: () => openSession(row.id),
+          },
+          React.createElement('span', { className: 'study-ss-tile', 'aria-hidden': 'true' },
+            studyTile(past ? 'past' : row.studyPlus ? 'book' : 'quick')),
+          React.createElement('span', { className: 'study-ss-title' }, row.title),
+          React.createElement('span', { className: 'study-ss-meta' },
+            row.workspace === '' ? null : React.createElement('span', { className: 'study-ss-workspace' }, row.workspace),
+            chip === null ? null : React.createElement('span', {
+              className: 'study-ss-chip',
+              'data-study-chip': '',
+            }, chip)),
+          time === '' ? null : React.createElement('span', { className: 'study-ss-time' }, time)));
+      };
+
+      const nodes = [];
+      if (scan.status === 'scanning') {
+        const percent = scan.total > 0 ? Math.round((scan.done / scan.total) * 100) : 0;
+        nodes.push(React.createElement('div', { key: 'progress', className: 'study-ss-scan' },
+          React.createElement('p', {
+            role: 'status',
+            'aria-busy': true,
+            className: 'study-ss-status',
+          }, t({
+            en: `Scanning session history… ${scan.done} of ${scan.total}`,
+            zh: `正在扫描会话历史… ${scan.done} / ${scan.total}`,
+          })),
+          React.createElement('div', { className: 'study-ss-track', 'aria-hidden': 'true' },
+            React.createElement('div', { className: 'study-ss-fill', style: { width: `${percent}%` } }))));
+      }
+      if (scan.status === 'failed') {
+        nodes.push(React.createElement('p', {
+          key: 'failure',
+          role: 'alert',
+          className: 'study-ss-error',
+        },
+        React.createElement('span', { className: 'study-ss-dot', 'aria-hidden': 'true' }),
+        t({
+          en: `The session index could not be read: ${scan.reason}`,
+          zh: `无法读取会话索引：${scan.reason}`,
+        })));
+      }
+      if (scan.status === 'ready' && Object.keys(scan.sessions).length === 0) {
+        nodes.push(React.createElement('p', { key: 'empty', className: 'study-ss-empty' },
+          t({
+            en: 'No study session yet. Turn on Nerd Mode from the composer bar, or run',
+            zh: '还没有学习会话。在输入栏打开 Nerd Mode，或运行',
+          }),
+          ' ',
+          React.createElement('code', null, '/nerd-mode on'),
+          t({ en: '.', zh: '。' })));
+      }
+
+      const group = (key, label, list, past) => {
+        if (list.length === 0) return null;
+        const open = folded[key] === false;
+        const listId = `study-ss-rows-${key}`;
+        return React.createElement('section', { key, className: 'study-ss-group' },
+          React.createElement('h2', { className: 'study-ss-group-title' },
+            React.createElement('button', {
+              type: 'button',
+              className: 'study-ss-fold',
+              'aria-expanded': open,
+              // A folded group has no list to control, so the reference would dangle.
+              'aria-controls': open ? listId : undefined,
+              'aria-label': `${t(label)} ${list.length}`,
+              onClick: () => setFolded((previous) => ({ ...previous, [key]: !previous[key] })),
+            },
+            React.createElement('span', null, t(label)),
+            React.createElement('span', { className: 'study-ss-count' }, String(list.length)),
+            React.createElement('svg', {
+              'aria-hidden': 'true',
+              className: 'study-ss-chev',
+              fill: 'none',
+              height: 12,
+              stroke: 'currentColor',
+              strokeLinecap: 'round',
+              strokeLinejoin: 'round',
+              strokeWidth: 1.6,
+              viewBox: '0 0 16 16',
+              width: 12,
+            }, React.createElement('path', { d: 'M3.5 6 8 10.5 12.5 6' })))),
+          open
+            ? React.createElement('ul', { className: 'study-ss-rows', id: listId },
+                ...list.map((row) => rowNode(row, past)))
+            : null);
+      };
+      nodes.push(group('inDepth', STUDY_IN_DEPTH, grouped.inDepth, false));
+      nodes.push(group('quick', STUDY_QUICK, grouped.quick, false));
+      nodes.push(group('past', STUDY_PAST, grouped.past, true));
+
+      return React.createElement('div', {
+        role: 'region',
+        'aria-label': t(STUDY_SESSIONS_TITLE),
+        className: 'study-ss-page',
+      }, React.createElement('style', null, STUDY_SESSIONS_CSS),
+      React.createElement('header', { className: 'study-ss-head', 'data-window-drag': '' },
+        React.createElement('h1', { className: 'study-ss-title' }, t(STUDY_SESSIONS_TITLE)),
+        React.createElement('p', { className: 'study-ss-intro' }, t({
+          en: 'Every conversation where Nerd Mode was on.',
+          zh: '开启过 Nerd Mode 的会话都在这里。',
+        }))),
+      ...nodes);
+    }
+
+    // The page shell, rows, and fold live in CSS so a container query can fold
+    // the time under the title on narrow panes. Tokens come from the host theme.
+    const STUDY_SESSIONS_CSS = `.study-ss-page{box-sizing:border-box;height:100%;overflow:auto;display:flex;flex-direction:column;align-items:center;gap:32px;padding:0 clamp(24px,4vw,48px) 48px;color:var(--dsw-alias-label-primary);font-family:var(--dsw-font-family,inherit);container-type:inline-size}
+.study-ss-page>*{width:100%;max-width:960px}
+.study-ss-head{display:flex;flex-direction:column;padding-top:28px}
+[data-platform="darwin"] .study-ss-head{padding-top:calc(28px + var(--dsh-frame-top-clearance,0px))}
+.study-ss-title{font-size:20px;line-height:28px;font-weight:500;margin:0}
+.study-ss-intro{font-size:13px;line-height:20px;color:var(--dsw-alias-label-secondary);margin:4px 0 0}
+.study-ss-group{display:flex;flex-direction:column;gap:8px}
+.study-ss-group-title{font-size:14px;line-height:22px;font-weight:500;margin:0}
+.study-ss-fold{display:inline-flex;align-items:center;gap:8px;padding:0;background:none;border:none;font:inherit;color:inherit;cursor:pointer}
+.study-ss-fold:focus-visible{outline:2px solid var(--dsw-focus-ring-color,var(--dsw-alias-state-business-primary));outline-offset:2px}
+.study-ss-count{font-size:13px;line-height:20px;font-weight:400;color:var(--dsw-alias-label-tertiary)}
+.study-ss-chev{color:var(--dsw-alias-label-tertiary);transition:transform 120ms}
+.study-ss-fold[aria-expanded="false"] .study-ss-chev{transform:rotate(-90deg)}
+.study-ss-rows{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:2px}
+.study-ss-item{margin:0 -8px}
+.study-ss-row{position:relative;width:100%;box-sizing:border-box;display:grid;grid-template-columns:32px minmax(0,1fr) auto;grid-template-areas:"tile title time" "tile meta time";column-gap:12px;row-gap:2px;align-items:start;padding:8px;border:none;border-radius:var(--dsw-radius-xl,20px);background:transparent;color:inherit;font:inherit;text-align:left;cursor:pointer;white-space:normal}
+.study-ss-row:hover{background:var(--dsw-alias-interactive-bg-hover)}
+.study-ss-row:focus-visible{outline:none}
+.study-ss-row:focus-visible::after{content:"";position:absolute;inset:0;border-radius:inherit;outline:2px solid var(--dsw-focus-ring-color,var(--dsw-alias-state-business-primary));outline-offset:2px}
+.study-ss-tile{grid-area:tile;align-self:center;width:32px;height:32px;display:grid;place-items:center;border-radius:8px;background:color-mix(in srgb,var(--dsw-alias-state-business-primary) 10%,transparent);color:var(--dsw-alias-state-business-primary)}
+.study-ss-title{grid-area:title;font-size:14px;line-height:20px;font-weight:500;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.study-ss-meta{grid-area:meta;display:flex;align-items:center;gap:6px;min-width:0;font-size:13px;line-height:18px;color:var(--dsw-alias-label-tertiary);flex-wrap:wrap}
+.study-ss-workspace{min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.study-ss-time{grid-area:time;font-size:12px;line-height:18px;color:var(--dsw-alias-label-tertiary);white-space:nowrap;margin-top:2px}
+.study-ss-chip{display:inline-flex;align-items:center;height:18px;padding:0 7px;font-size:11px;line-height:17px;border:.5px solid var(--dsw-alias-border-l3);border-radius:999px;color:var(--dsw-alias-label-tertiary);white-space:nowrap}
+@container (max-width:520px){.study-ss-row{grid-template-areas:"tile title title" "tile meta time"}.study-ss-time{margin-top:0}}
+.study-ss-scan{display:flex;flex-direction:column;gap:10px}
+.study-ss-status{font-size:13px;line-height:20px;color:var(--dsw-alias-label-secondary);margin:0}
+.study-ss-track{height:2px;background:var(--dsw-alias-border-l3);border-radius:999px;overflow:hidden}
+.study-ss-fill{height:100%;background:var(--dsw-alias-state-business-primary)}
+.study-ss-error{display:flex;align-items:center;gap:8px;font-size:13px;line-height:20px;color:var(--dsw-alias-state-error-primary);margin:0}
+.study-ss-dot{flex:none;width:6px;height:6px;border-radius:50%;background:currentColor}
+.study-ss-empty{text-align:center;padding:48px 20px;font-size:14px;line-height:22px;color:var(--dsw-alias-label-tertiary);margin:0}
+.study-ss-empty code{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12px;line-height:18px;background:var(--dsw-alias-bg-layer-2);border-radius:6px;padding:1px 6px}`;
+
     return {
       inject: ['slots', 'remote', 'remote.commands', 'remote.workspaceFiles', 'configForms'],
       apply(ctx) {
@@ -1774,6 +2164,35 @@ window.__ModuleLoader__.load({
               locale: localeCtx.locale,
             })),
           );
+          // One id addresses both seats: the sidebar row selects the keyed main page.
+          ctx.slots.inject('sidebar.panellist', () =>
+            ctx.slots.register({
+              name: 'sidebar.panellist',
+              id: STUDY_SESSIONS_ID,
+              order: STUDY_SESSIONS_ORDER,
+              // The label owns its translator: the slot's `t` prop belongs to the icon.
+              label: () => localeCtx.locale.resolveText(STUDY_SESSIONS_TITLE),
+            }, StudySessionsIcon),
+          );
+          ctx.slots.inject('main', () =>
+            ctx.slots.register({
+              name: 'main',
+              key: STUDY_SESSIONS_ID,
+              inject: () => ({
+                locale: localeCtx.locale,
+                openSession: (id) => {
+                  try {
+                    ctx.get('uiWorkspace')?.openSession(id);
+                  } catch {
+                    // A stale row must not take the panel down.
+                  }
+                },
+              }),
+            }, (props) => React.createElement(StudySessionsPage, {
+              ...props,
+              useSessions: typeof props.useSessions === 'function' ? props.useSessions : NO_SESSIONS_HOOK,
+            })),
+          );
         });
         ctx.slots.inject(VIEW_SLOT, () =>
           ctx.slots.register({

package/lib/index.js

@@ -11,6 +11,7 @@
 import { readFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { COMMAND, KEY, fold, init } from './fold.js'
+import { scan } from './study-sessions.js'
 import z from '@deepseek-ai/schemastery'
 
 export const name = 'dsh-nerd-mode'
@@ -38,6 +39,7 @@ export const Config = z.object({
 const SECTION = 'study:policy'
 // Between PLAN_POLICY (500) and TEAM_POLICY (600).
 const SECTION_ORDER = 550
+const STUDY_SESSIONS_PATH = '/dsh-nerd-mode/api/study-sessions'
 const studyPlusDefaultsBySession = new WeakMap()
 const directStudyPlusBySession = new WeakMap()
 // A PTC skill load leaves no message in the history, so keep its id for later
@@ -162,6 +164,53 @@ const projection = {
   },
 }
 
+function sendJson(res, status, body) {
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+  })
+  res.end(JSON.stringify(body))
+}
+
+function cursorOf(req) {
+  const match = /[?&]cursor=(\d+)/.exec(req?.url ?? '')
+  return match === null ? 0 : Number.parseInt(match[1], 10)
+}
+
+/**
+ * Build the read-only history route handler.
+ *
+ * `webServer.register` adds no auth fence, so the connection service decides
+ * first: a missing cookie is 401 and a bad Host or Origin is 403.
+ *
+ * @param options
+ * @param options.connection - the host connection service
+ * @param options.indexFile - forwarded to `scan`; tests point it at a temp file
+ * @param options.sessionsRoot - forwarded to `scan`; tests point it at a temp tree
+ * @returns {(req, res) => Promise<void>} replies `{ phase, cursor, done,
+ * total, sessions }` with `no-store`, `{ error }` with status 500, or the
+ * rejection status
+ */
+export function createStudySessionsHandler({ connection, ...scanOptions }) {
+  return async function studySessionsRoute(req, res) {
+    const rejection = connection.requestRejection(req)
+    if (rejection !== undefined) {
+      res.writeHead(rejection)
+      res.end(rejection === 401 ? 'unauthorized' : 'forbidden')
+      return
+    }
+    if (req.method !== 'GET') {
+      sendJson(res, 405, { error: 'Method not allowed.' })
+      return
+    }
+    try {
+      sendJson(res, 200, scan({ ...scanOptions, cursor: cursorOf(req) }))
+    } catch (error) {
+      sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) })
+    }
+  }
+}
+
 /**
  * @param config - `section` is an optional overlay text; a missing value uses
  * the bundled `assets/section.md`.
@@ -220,4 +269,18 @@ export function apply(ctx, config) {
       },
     })
   })
+
+  // The web server is optional: a host without it still loads the switch and
+  // the prompt section, and the panel shows its failure line.
+  ctx.inject(['webServer', 'connection'], (webCtx) => {
+    webCtx.effect(
+      () =>
+        webCtx.webServer.register({
+          kind: 'exact',
+          path: STUDY_SESSIONS_PATH,
+          handler: createStudySessionsHandler({ connection: webCtx.connection }),
+        }),
+      'dsh-nerd-mode: study sessions route',
+    )
+  })
 }

package/lib/study-sessions.js

@@ -0,0 +1,283 @@
+/**
+ * The Study Sessions history index. It reads the session logs the host writes
+ * and caches the two facts the panel needs: whether Nerd Mode was ever on, and
+ * whether a completed `/study-plus` invocation appears. Kept free of host
+ * imports like `lib/fold.js`, so it runs under plain node. See ADR 0021.
+ */
+
+import { mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { zstdDecompressSync } from 'node:zlib'
+
+const COMMAND = 'nerd-mode'
+const STUDY_PLUS = 'study-plus'
+const SESSION_FILE = 'session.v4.jsonl.zstd'
+const DEFAULT_INDEX_FILE = join(homedir(), '.dsh', 'study-sessions-index.json')
+const DEFAULT_SESSIONS_ROOT = join(homedir(), '.dsh', 'sessions')
+const DEFAULT_CHUNK_SIZE = 20
+const MAGIC = [0x28, 0xb5, 0x2f, 0xfd]
+// The token must stand alone: `not/study-plus` and `/study-plussed` are not
+// invocations. This is the same boundary the live command parser uses.
+const DIRECT_COMMAND = /(^|\s)\/study-plus(?=\s|$)/
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function messageText(message) {
+  const content = message?.content
+  if (!Array.isArray(content)) return ''
+  return content
+    .filter((block) => block?.type === 'text' && typeof block.text === 'string')
+    .map((block) => block.text)
+    .join('\n')
+}
+
+function skillNameOf(argumentText) {
+  if (typeof argumentText !== 'string') return undefined
+  try {
+    return JSON.parse(argumentText)?.name
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Read the two history facts from one session's decoded events.
+ * @param events - decoded session log events, in log order
+ * @returns {{ nerd: boolean, studyPlus: boolean }} `nerd` means Nerd Mode was
+ * switched on at least once, `studyPlus` means a completed `/study-plus`
+ * invocation appears. Malformed events are ignored.
+ */
+export function classify(events) {
+  const successfulCommands = new Set()
+  const wantedCommands = new Set()
+  const skillCalls = new Set()
+  const completedCalls = new Set()
+  let studyPlus = false
+
+  for (const event of events) {
+    const data = event?.data
+    if (event?.type === 'command/run') {
+      if (data?.name !== COMMAND) continue
+      // A bare /nerd-mode means on, matching lib/fold.js.
+      const args = typeof data.args === 'string' ? data.args : ''
+      if (args.trim().toLowerCase() !== 'off' && typeof data.commandId === 'string') {
+        wantedCommands.add(data.commandId)
+      }
+    } else if (event?.type === 'command/done') {
+      if (data?.kind === 'success' && typeof data.commandId === 'string') {
+        successfulCommands.add(data.commandId)
+      }
+    } else if (event?.type === 'user/message') {
+      const source = data?.source
+      if (source?.kind === 'skill-invocation') {
+        if (source.name === STUDY_PLUS) studyPlus = true
+      } else if (source?.kind === 'user' && DIRECT_COMMAND.test(messageText(data))) {
+        studyPlus = true
+      }
+    } else if (event?.type === 'tool/call') {
+      if (data?.name === 'skill' && typeof data.callId === 'string' && skillNameOf(data.arguments) === STUDY_PLUS) {
+        skillCalls.add(data.callId)
+      }
+    } else if (event?.type === 'tool/result') {
+      const message = data?.message
+      if (message?.isError !== true && typeof message?.source?.callId === 'string') {
+        completedCalls.add(message.source.callId)
+      }
+    } else if (event?.type === 'tool/ptc-dispatch') {
+      // A skill load inside run_code arrives as a dispatch and carries its own outcome.
+      if (data?.name === 'skill' && data?.arguments?.name === STUDY_PLUS && data?.isError !== true) {
+        studyPlus = true
+      }
+    }
+  }
+
+  if (!studyPlus) {
+    studyPlus = [...skillCalls].some((callId) => completedCalls.has(callId))
+  }
+  return {
+    nerd: [...wantedCommands].some((commandId) => successfulCommands.has(commandId)),
+    studyPlus,
+  }
+}
+
+/**
+ * Decode a session log into events.
+ *
+ * The file is a chain of zstd frames, one per append batch. Whole-file
+ * decompression stops at the first frame, which holds only the header, so each
+ * frame is decoded on its own.
+ *
+ * @param file - path to a `session.v4.jsonl.zstd` file
+ * @returns the decoded events; malformed frames and lines are dropped
+ * @throws when the file itself cannot be read
+ */
+export function decodeSessionFile(file) {
+  const bytes = readFileSync(file)
+  const starts = []
+  for (let offset = 0; offset <= bytes.length - MAGIC.length; offset += 1) {
+    if (MAGIC.every((byte, index) => bytes[offset + index] === byte)) starts.push(offset)
+  }
+
+  const events = []
+  for (let index = 0; index < starts.length; index += 1) {
+    let text
+    try {
+      text = zstdDecompressSync(bytes.subarray(starts[index], starts[index + 1] ?? bytes.length)).toString('utf8')
+    } catch {
+      // A magic byte sequence can occur inside compressed data, so a failed
+      // slice is expected. See docs/agents/dsh-session-api.md.
+      continue
+    }
+    for (const line of text.split('\n')) {
+      if (line === '') continue
+      try {
+        events.push(JSON.parse(line))
+      } catch {
+        // A crash can leave a partial trailing line. One bad record must not
+        // hide the rest of the log.
+      }
+    }
+  }
+  return events
+}
+
+function readIndex(file) {
+  let text
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch (error) {
+    if (error?.code === 'ENOENT') return {}
+    // A missing index is a first run. Any other failure reaches the panel.
+    throw error
+  }
+  try {
+    const index = JSON.parse(text)
+    return isRecord(index) ? index : {}
+  } catch {
+    // A corrupt cache is rebuilt from the logs, not reported as a failure.
+    return {}
+  }
+}
+
+function writeIndex(file, index) {
+  mkdirSync(dirname(file), { recursive: true })
+  const temp = `${file}.tmp`
+  writeFileSync(temp, JSON.stringify(index))
+  // Rename keeps the previous index readable if the process dies mid-write.
+  renameSync(temp, file)
+}
+
+function listSessionFiles(root) {
+  let workspaces
+  try {
+    workspaces = readdirSync(root, { withFileTypes: true })
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { files: [], complete: true }
+    throw error
+  }
+
+  const files = []
+  let complete = true
+  for (const workspace of workspaces) {
+    if (!workspace.isDirectory()) continue
+    let sessions
+    try {
+      sessions = readdirSync(join(root, workspace.name), { withFileTypes: true })
+    } catch {
+      // One locked workspace must not blank the others, and must not prune them.
+      complete = false
+      continue
+    }
+    for (const session of sessions) {
+      if (!session.isDirectory()) continue
+      const file = join(root, workspace.name, session.name, SESSION_FILE)
+      try {
+        const stat = statSync(file)
+        if (stat.isFile()) {
+          files.push({ id: session.name, file, mtimeMs: stat.mtimeMs, size: stat.size })
+        }
+      } catch {
+        // A session folder without a readable log is not a session yet.
+      }
+    }
+  }
+  files.sort((left, right) => (left.file < right.file ? -1 : left.file > right.file ? 1 : 0))
+  return { files, complete }
+}
+
+/**
+ * Classify one chunk of the session tree and persist the index.
+ *
+ * @param options
+ * @param options.cursor - index of the first file in the sorted session list to
+ * process; negative and non-integer values read as 0
+ * @param options.indexFile - index path; defaults to
+ * `~/.dsh/study-sessions-index.json`
+ * @param options.sessionsRoot - session tree; defaults to `~/.dsh/sessions`
+ * @param options.chunkSize - files to process per call; defaults to 20
+ * @param options.decode - decoder override for tests; defaults to
+ * `decodeSessionFile`
+ * @returns {{ phase: 'pending' | 'ready', cursor: number, done: number,
+ * total: number, sessions: Record<string, { studyPlus: boolean }> }} `cursor`
+ * is the next call's starting index and equals `total` once `phase` is
+ * `ready`. `done` counts files visited so far. A key in `sessions` means Nerd
+ * Mode was on at least once for that id.
+ * @throws when the index or the session tree cannot be read or written
+ */
+export function scan({
+  cursor = 0,
+  indexFile = DEFAULT_INDEX_FILE,
+  sessionsRoot = DEFAULT_SESSIONS_ROOT,
+  chunkSize = DEFAULT_CHUNK_SIZE,
+  decode = decodeSessionFile,
+} = {}) {
+  const { files, complete } = listSessionFiles(sessionsRoot)
+  const index = readIndex(indexFile)
+  if (complete) {
+    const live = new Set(files.map(({ id }) => id))
+    for (const id of Object.keys(index)) {
+      if (!live.has(id)) delete index[id]
+    }
+  }
+
+  const start = Number.isInteger(cursor) && cursor > 0 ? cursor : 0
+  const size = Number.isInteger(chunkSize) && chunkSize > 0 ? chunkSize : DEFAULT_CHUNK_SIZE
+  const end = Math.min(start + size, files.length)
+  for (let position = start; position < end; position += 1) {
+    const { id, file, mtimeMs, size: bytes } = files[position]
+    const previous = index[id]
+    if (previous?.mtimeMs === mtimeMs && previous?.size === bytes) continue
+
+    let flags
+    try {
+      flags = classify(decode(file))
+    } catch {
+      // An unreadable session keeps its previous record and retries next scan.
+      continue
+    }
+    index[id] = {
+      mtimeMs,
+      size: bytes,
+      // Compaction can drop the original event. A fact that disappeared from a
+      // rewritten log must not resurface as a missing session.
+      nerd: flags.nerd || previous?.nerd === true,
+      studyPlus: flags.studyPlus,
+    }
+  }
+  writeIndex(indexFile, index)
+
+  const sessions = {}
+  for (const [id, entry] of Object.entries(index)) {
+    if (entry?.nerd === true) sessions[id] = { studyPlus: entry.studyPlus === true }
+  }
+  return {
+    phase: end >= files.length ? 'ready' : 'pending',
+    cursor: end,
+    done: end,
+    total: files.length,
+    sessions,
+  }
+}

package/package.json

@@ -1,70 +1,70 @@
-{
-  "name": "dsh-nerd-mode",
-  "version": "0.4.6",
-  "description": "A study switch and study skills for DeepSeek Harness.",
-  "license": "MIT",
-  "type": "module",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/bocchii-the-code/dsh-nerd-mode.git"
-  },
-  "homepage": "https://github.com/bocchii-the-code/dsh-nerd-mode#readme",
-  "bugs": {
-    "url": "https://github.com/bocchii-the-code/dsh-nerd-mode/issues"
-  },
-  "main": "./lib/index.js",
-  "exports": {
-    ".": "./lib/index.js",
-    "./client": "./client.js",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib",
-    "client.js",
-    "assets",
-    "cordis.patch.yml",
-    "skills",
-    "README.md",
-    "README.zh.md",
-    "NOTICE.md",
-    "LICENSE"
-  ],
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    },
-    "client": {
-      "platform": "web",
-      "immediately": true,
-      "inject": [
-        "@deepseek-ai/dsh-client-ui-conversation"
-      ]
-    }
-  },
-  "scripts": {
-    "test": "node --test",
-    "lint": "eslint .",
-    "check": "npm run lint && npm test"
-  },
-  "peerDependencies": {
-    "@deepseek-ai/schemastery": "^3.18.5"
-  },
-  "engines": {
-    "node": "^22.19.0 || >=24.0.0"
-  },
-  "keywords": [
-    "dsh-plugin",
-    "deepseek-harness",
-    "study",
-    "tutor",
-    "agent-skill"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "devDependencies": {
-    "@deepseek-ai/schemastery": "^3.18.5",
-    "eslint": "^10.13.0",
-    "globals": "^17.13.0"
-  }
-}
+{
+  "name": "dsh-nerd-mode",
+  "version": "0.5.0",
+  "description": "A study switch and study skills for DeepSeek Harness.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bocchii-the-code/dsh-nerd-mode.git"
+  },
+  "homepage": "https://github.com/bocchii-the-code/dsh-nerd-mode#readme",
+  "bugs": {
+    "url": "https://github.com/bocchii-the-code/dsh-nerd-mode/issues"
+  },
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "client.js",
+    "assets",
+    "cordis.patch.yml",
+    "skills",
+    "README.md",
+    "README.zh.md",
+    "NOTICE.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ]
+    }
+  },
+  "scripts": {
+    "test": "node --test",
+    "lint": "eslint .",
+    "check": "npm run lint && npm test"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/schemastery": "^3.18.5"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "study",
+    "tutor",
+    "agent-skill"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@deepseek-ai/schemastery": "^3.18.5",
+    "eslint": "^10.13.0",
+    "globals": "^17.13.0"
+  }
+}

package/skills/study/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: study
-description: "[v0.4.6] Teach one concept or help complete one task, using the supplied material as scope and defaulting to chat output."
+description: "[v0.5.0] Teach one concept or help complete one task, using the supplied material as scope and defaulting to chat output."
 argument-hint: "<concept or task>"
 ---
 # Study

package/skills/study-plus/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: study-plus
-description: "[v0.4.6] Run one tracked session against a dated learning record. Load for an explicit command or after the user chooses tracked study in the upper router."
+description: "[v0.5.0] Run one tracked session against a dated learning record. Load for an explicit command or after the user chooses tracked study in the upper router."
 argument-hint: "<course-slug>, or empty to continue the current Course"
 ---
 # Study Plus