better-dsh 0.2.4 → 0.2.5-a

package/docs/superpowers/plans/2026-10-02-ctx-navigation.md

@@ -0,0 +1,319 @@
+# ctx:// Long-Session Navigability Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make `ctx://` a navigable long-session surface: every coordinate it shows is addressable, digests are pointers not re-dumps, and landmarks/fidelity direct the model to what matters.
+
+**Architecture:** One handler file (`src/url-schemes/handlers/ctx.ts`) gains a transcript line index (single source of truth for line coordinates), transcript-relative episode windows, a digest-residence rule, a landmark/fidelity block, and `:path/`/`?q=` selector support via the existing `applySelector` in `selector.ts`.
+
+**Tech Stack:** TypeScript (ESM), Vitest, the `@deepseek-ai/dsh-*` harness peer types.
+
+**Spec:** `docs/superpowers/specs/2026-10-02-ctx-navigation-design.md` (algorithms) and `docs/specs/ctx/spec.md` (requirements). Executors read both.
+
+## Global Constraints
+
+- Coordinate invariant: every number shown is labeled (`seq=` or `lines=`) and directly addressable; transcript is the canonical line space.
+- Episode line windows are transcript-relative (`compactions[label]:N-M` ≡ `transcript:N-M`).
+- Out-of-span windows return an explicit boundary note, never a silent empty/truncated view.
+- Digest residence: latest episode's prepared face never re-dumps the digest; older episodes return their full digest; `:raw` always returns the span.
+- Landmarks and fidelity are capped to one screen and tail `… +N more`.
+- No semantic/vector retrieval. Phone book + index + pointer only.
+- `tsc --noEmit` 0 errors; `npx vitest run` green (baseline 641 passed / 1 skipped).
+
+---
+
+## Task 1: Transcript line index + episode `lines`
+
+**Files:**
+- Modify: `better-dsh/src/url-schemes/handlers/ctx.ts`
+- Test: `better-dsh/test/url-schemes/ctx.spec.ts`
+
+**Interfaces:**
+- Produces: `TranscriptIndex { text; totalLines; lineOfSeq: Map<number, {start,end}> }` (see design §3.1); each episode gains `lines: { start: number; end: number } | null` and `originalText` is derived from the transcript slice.
+
+- [ ] **Step 1: Add the failing test for episode line coordinates**
+
+```ts
+it('reports transcript line coordinates per episode and keeps the snapshot labeled', async () => {
+  const closed = { value: false }
+  const r = ctxResolver(closed)
+  const snap = JSON.parse(await r.resolve({} as ResolverEnv, 'ctx://session', null))
+  const ep0 = snap.compacted[0]
+  expect(ep0.lines).toBeTypeOf('object')
+  expect(ep0.lines.start).toBeGreaterThanOrEqual(1)
+  expect(ep0.lines.end).toBeGreaterThanOrEqual(ep0.lines.start)
+  // the manifest prints labeled lines= too
+  const manifest = await r.resolve({} as ResolverEnv, 'ctx://session/compactions', null)
+  expect(manifest).toMatch(/lines=\d+\.\.\d+/)
+  expect(manifest).toMatch(/seq=\d+\.\.\d+/)
+})
+```
+
+- [ ] **Step 2: Run it, confirm it fails** (`npx vitest run test/url-schemes/ctx.spec.ts` — `lines` is `undefined`)
+
+- [ ] **Step 3: Implement `buildTranscript` and derive episode `lines`/`originalText`**
+
+```ts
+interface TranscriptIndex {
+  text: string
+  totalLines: number
+  lineOfSeq: Map<number, { start: number; end: number }>
+}
+function buildTranscript(events: readonly PersistenceEvent[], toolNameOf: (s?: number) => string | undefined): TranscriptIndex {
+  const entries = events.map(e => ({ seq: e.seq as number, text: renderEntry(e, toolNameOf) })).filter(t => t.text !== '')
+  const lineOfSeq = new Map<number, { start: number; end: number }>()
+  let line = 1
+  for (let i = 0; i < entries.length; i++) {
+    const n = entries[i].text.split('\n').length
+    lineOfSeq.set(entries[i].seq, { start: line, end: line + n - 1 })
+    line += n + (i < entries.length - 1 ? 1 : 0)
+  }
+  return { text: entries.map(e => e.text).join('\n\n'), totalLines: line - 1, lineOfSeq }
+}
+```
+
+In `resolve`, replace the standalone `transcript()` closure with a single `const tIdx = buildTranscript(events, toolNameOf)` computed once (after `toolNameOf` is defined) and reuse `tIdx.text` everywhere `transcript()` was called. In the episode build loop, after `originalText` is assembled, set:
+
+```ts
+const shadowLines = d.shadowedSeqs
+  .map(s => tIdx.lineOfSeq.get(s)).filter((x): x is {start:number;end:number} => x !== undefined)
+const lines = shadowLines.length === 0 ? null
+  : { start: Math.min(...shadowLines.map(x => x.start)), end: Math.max(...shadowLines.map(x => x.end)) }
+const originalText = lines === null ? ''
+  : tIdx.text.split('\n').slice(lines.start - 1, lines.end).join('\n')
+```
+
+- [ ] **Step 4: Run the test, confirm it passes**
+
+- [ ] **Step 5: Commit** `git add better-dsh/src/url-schemes/handlers/ctx.ts better-dsh/test/url-schemes/ctx.spec.ts && git commit -m "feat(ctx): transcript line index + per-episode line coordinates (N1)"`
+
+---
+
+## Task 2: Transcript-relative episode windows + boundary note
+
+**Files:** `ctx.ts`, `ctx.spec.ts`
+
+**Interfaces:** Produces `applyEpisodeLines(slice: string, lineStart: number, lineEnd: number, ranges: Array<[number,number]>): string`.
+
+- [ ] **Step 1: Add failing tests**
+
+```ts
+it('episode line window is transcript-relative (≡ transcript window)', async () => {
+  const closed = { value: false }
+  const r = ctxResolver(closed)
+  const ep0 = JSON.parse(await r.resolve({} as ResolverEnv, 'ctx://session', null)).compacted[0]
+  const viaEpisode = await r.resolve({} as ResolverEnv, `ctx://session/compactions[${ep0.label}]:${ep0.lines.start}-${ep0.lines.end}`, null)
+  const viaTranscript = await r.resolve({} as ResolverEnv, `ctx://session/transcript:${ep0.lines.start}-${ep0.lines.end}`, null)
+  expect(viaEpisode).toBe(viaTranscript)
+})
+
+it('out-of-span episode window returns an explicit boundary note', async () => {
+  const closed = { value: false }
+  const r = ctxResolver(closed)
+  const ep0 = JSON.parse(await r.resolve({} as ResolverEnv, 'ctx://session', null)).compacted[0]
+  const out = await r.resolve({} as ResolverEnv, `ctx://session/compactions[${ep0.label}]:${ep0.lines.end + 1000}`, null)
+  expect(out).toMatch(/end of episode span|span is transcript lines/)
+})
+```
+
+- [ ] **Step 2: Run, confirm both fail**
+
+- [ ] **Step 3: Implement transcript-relative episode line application**
+
+```ts
+function applyEpisodeLines(slice: string, lineStart: number, lineEnd: number, ranges: Array<[number, number]>): string {
+  const lines = slice.split('\n')
+  const out: string[] = []
+  let noted = false
+  for (const [aRaw, bRaw] of ranges) {
+    const a = Math.max(1, aRaw); const b = bRaw === Infinity ? lineEnd : bRaw
+    if (b < lineStart || a > lineEnd) { noted = true; continue }
+    const la = Math.max(a, lineStart) - lineStart + 1
+    const lb = Math.min(b, lineEnd) - lineStart + 1
+    out.push(...lines.slice(la - 1, lb))
+    if (bRaw === Infinity ? false : b > lineEnd || a < lineStart) noted = true
+  }
+  const body = out.join('\n')
+  const note = noted ? `\n\n[ctx:// note: episode span is transcript lines ${lineStart}-${lineEnd}]` : ''
+  return body + note
+}
+```
+
+In the episode branch, when the episode has `lines !== null`, route `sel.kind === 'lines'` through `applyEpisodeLines(episode.originalText, episode.lines.start, episode.lines.end, sel.ranges)` instead of the shared `applyLines`.
+
+- [ ] **Step 4: Run, confirm both pass (the first test also proves the episode-span ≡ transcript-slice invariant)**
+
+- [ ] **Step 5: Commit** `git commit -am "feat(ctx): transcript-relative episode windows + explicit span bounds (N1/F10)"`
+
+---
+
+## Task 3: Digest residence rule
+
+**Files:** `ctx.ts`, `ctx.spec.ts`
+
+**Interfaces:** Produces `episodeNavigation(episode, isLatest, checkpointLines) => string` (latest → navigation block, older → digest + pointer block).
+
+- [ ] **Step 1: Add failing tests**
+
+```ts
+it('latest episode prepared face is a navigation block without the digest text', async () => {
+  const closed = { value: false }
+  const r = ctxResolver(closed)
+  const latest = await r.resolve({} as ResolverEnv, 'ctx://session/compactions[40]', null)  // label 40 is last
+  expect(latest).toMatch(/digest is already in your live context/)
+  expect(latest).toMatch(/digest resident .*seq=41/)
+  expect(latest).not.toMatch(/second round/)  // the digest body must NOT be dumped
+})
+
+it('older episode prepared face returns its full digest', async () => {
+  const closed = { value: false }
+  const r = ctxResolver(closed)
+  const older = await r.resolve({} as ResolverEnv, 'ctx://session/compactions[20]', null)
+  expect(older).toMatch(/do the thing/)       // digest body present
+  expect(older).toMatch(/lines=\d+\.\.\d+/)
+})
+```
+
+- [ ] **Step 2: Run, confirm fail**
+
+- [ ] **Step 3: Implement** the checkpoint-line lookup (the `user/message` whose `source.plugin === 'compact'` at `checkpointSeq`, via `tIdx.lineOfSeq`, fallback `undefined`) and the two branches. Latest block shape (no digest): see design §4 (N2). Older: `episode.summaryText` + the pointer block. `:raw`/`:N-M` unchanged (span).
+
+- [ ] **Step 4: Run, confirm pass**
+
+- [ ] **Step 5: Commit** `git commit -am "feat(ctx): digest residence rule — latest is a pointer, older dumps digest (N2)"`
+
+---
+
+## Task 4: Landmark roster + fidelity
+
+**Files:** `ctx.ts`, `ctx.spec.ts`
+
+**Interfaces:** Produces `landmarksOf(episodeEvents, tIdx): string` and `fidelityOf(episodeEvents): { userTurns; toolCalls }`.
+
+- [ ] **Step 1: Add failing tests**
+
+```ts
+it('landmark block lists user-turn and failure lines and touched paths', async () => {
+  const closed = { value: false }
+  const r = ctxResolver(closed)
+  const out = await r.resolve({} as ResolverEnv, 'ctx://session/compactions[20]', null)
+  expect(out).toMatch(/user turns \(\d+\): \d+/)
+  expect(out).toMatch(/touched paths:/)
+})
+
+it('manifest and snapshot carry fidelity', async () => {
+  const closed = { value: false }
+  const r = ctxResolver(closed)
+  expect(await r.resolve({} as ResolverEnv, 'ctx://session/compactions', null)).toMatch(/fidelity=\d+:\d+/)
+  const snap = JSON.parse(await r.resolve({} as ResolverEnv, 'ctx://session', null))
+  expect(snap.compacted[0].fidelity).toEqual(expect.objectContaining({ userTurns: expect.any(Number), toolCalls: expect.any(Number) }))
+})
+```
+
+- [ ] **Step 2: Run, confirm fail**
+
+- [ ] **Step 3: Implement** `landmarksOf` (user turns = `user/message` with `source.kind==='user'` → `tIdx.lineOfSeq` line; failures = `tool/result` with `data.message.isError===true` or `data.error` present → line + tool name; touched paths = path-valued strings from `tool/call` args keys `path`/`file_path`/`filePath`/`file` + `edits[].path` + `files[].path`, args > 64 000 chars skipped; prior checkpoints = count of `user/message` with `source.plugin==='compact'`). Caps: 30 / 20 / 12. `fidelityOf` = counts of user turns and `tool/call` events. Wire into the episode block (Task 3), the manifest line, and the snapshot `compacted[]`.
+
+- [ ] **Step 4: Run, confirm pass**
+
+- [ ] **Step 5: Commit** `git commit -am "feat(ctx): landmark roster + fidelity signal (N3/N4)"`
+
+---
+
+## Task 5: `:path/` + `?q=` selectors + error echo
+
+**Files:** `ctx.ts`, `ctx.spec.ts`
+
+**Interfaces:** Consumes `applySelector(text, sel)` from `../../src/url-schemes/selector.ts` (already exported).
+
+- [ ] **Step 1: Add failing tests**
+
+```ts
+it('supports :path/ on the snapshot JSON and ?q= on an index face', async () => {
+  const closed = { value: false }
+  const r = ctxResolver(closed)
+  const n = await r.resolve({} as ResolverEnv, 'ctx://session:path/totals.tool_calls', null)
+  expect(n).toMatch(/^\d+$/)
+  const q = await r.resolve({} as ResolverEnv, 'ctx://session/injections?q=agent-instructions', null)
+  expect(q).toMatch(/AGENTS\.md/)
+})
+
+```
+
+- [ ] **Step 2: Run, confirm fail**
+
+- [ ] **Step 3: Implement** — in `applyFace`, before the `lines` branch:
+
+```ts
+if (selector.kind === 'path' || selector.kind === 'query') {
+  return applySelector(face === 'canonical' ? canonical : prepared, selector)
+}
+```
+
+Import `applySelector` from `../selector.ts` (add to the existing `import { UrlSchemesError }` line). Replace the manifest special-case rejection with `return applySelector(body, sel)` so `?q=`/`:N-M`/`:path/` all work there too. Keep the now-unreachable `CTX_BAD_SELECTOR` throw but give it a support-set message (`:raw`, `:N-M`, `:path/`, `?q=`) for future kinds.
+
+- [ ] **Step 4: Run, confirm pass**
+
+- [ ] **Step 5: Commit** `git commit -am "feat(ctx): :path/ and ?q= selectors (N5/F5/F8)"`
+
+---
+
+## Task 6: `asOf`, F1 index faces, F2 result shape
+
+**Files:** `ctx.ts`, `ctx.spec.ts`
+
+- [ ] **Step 1: Add failing tests**
+
+```ts
+it('snapshot carries asOf', async () => {
+  const closed = { value: false }
+  const r = ctxResolver(closed)
+  const snap = JSON.parse(await r.resolve({} as ResolverEnv, 'ctx://session', null))
+  expect(snap.asOf).toEqual(expect.objectContaining({ seq: expect.any(Number), line: expect.any(Number) }))
+})
+
+it('bare element collections return index faces, not an empty-bracket error', async () => {
+  const closed = { value: false }
+  const r = ctxResolver(closed)
+  const idx = await r.resolve({} as ResolverEnv, 'ctx://session/user_prompts', null)
+  expect(idx).toMatch(/seq=\d+/)
+  expect(idx).toMatch(/hello world/)
+})
+
+it('flat tool-result content renders (F2)', async () => {
+  const closed = { value: false }
+  const flat: PersistenceEvent[] = [
+    { seq: 5, type: 'tool/call', time: T, data: { callId: 'c1', name: 'bash', arguments: '{"command":"echo hi"}' } },
+    { seq: 6, type: 'tool/result', time: T, sourceEventSeqs: [5], data: { message: { role: 'tool', isError: false, content: [{ type: 'text', text: 'hi' }] } } },
+  ]
+  const r = ctxResolver(closed, flat)
+  expect(await r.resolve({} as ResolverEnv, 'ctx://session/tool_calls[5]', null)).toMatch(/result: hi/)
+})
+```
+
+- [ ] **Step 2: Run, confirm fail**
+
+- [ ] **Step 3: Implement**
+  - `asOf`: add `asOf: { seq: <max seq>, line: tIdx.totalLines }` to `buildSnapshot`.
+  - F1: give `user_prompts`/`tool_calls`/`agent_responses` a bare index face (per-element `seq=<s> <preview>`), capping `tool_calls`/`agent_responses` at 20 lines with a `… +N more` tail; `[n|seq]` and `:raw` unchanged. Update the element error to name the collection + count (no `ctx://…[]`).
+  - F2: `resultTextOf` returns `nested !== '' ? nested : textOf(blocks)` (flat fallback; see design §3.3).
+
+- [ ] **Step 4: Run full suite** `npx vitest run` and `npx tsc --noEmit` — all green.
+
+- [ ] **Step 5: Commit** `git commit -am "feat(ctx): asOf, element index faces, flat tool-result rendering (N6/F1/F2)"`
+
+---
+
+## Task 7: Docs, rig verification, report
+
+**Files:** `docs/specs/ctx/spec.md` (already updated), `better-dsh/dashr/url-schemes-instruction.md` (model-facing instruction, if it lists selectors — verify and add `:path/`/`?q=`/transcript-relative note), `docs/50_test-reports/2026-10-02-ctx-navigation实测报告.md`.
+
+- [ ] **Step 1:** Grep `better-dsh/` for the model-facing `url-schemes` instruction doc and update the ctx selector list if present.
+
+- [ ] **Step 2:** Rebuild + sync: `cd better-dsh && npm run build && cd .. && rsync -a --delete better-dsh/lib/ .test/home/compat/profiles/web/node_modules/better-dsh/lib/` and restart `bash .test/seed/test123/start.sh`.
+
+- [ ] **Step 3:** First-person verify on 4999 via `dvc://browser` and a `headless` rigcheck session: snapshot has `asOf` + labeled `lines`; a deep episode windows by transcript line; `?q=` filters an index; `:path/` narrow-reads; a tool result is non-empty.
+
+- [ ] **Step 4:** Write the test report to `docs/50_test-reports/2026-10-02-ctx-navigation实测报告.md` (findings, probes, verdict).
+
+- [ ] **Step 5: Commit** `git commit -am "docs(ctx): navigation change — instruction + first-person test report"`

package/docs/superpowers/specs/2026-10-02-ctx-navigation-design.md

@@ -0,0 +1,209 @@
+# ctx:// Long-Session Navigability — Design
+
+> Status: approved (user, 2026-10-02). Implements backlog N1–N6 plus findings F1/F2 from
+> `docs/50_test-reports/2026-09-28-ctx-scheme长会话utility实测报告.md` §八.
+> Live spec delta: `docs/specs/ctx/spec.md`. Plan: `docs/superpowers/plans/2026-10-02-ctx-navigation.md`.
+
+## 1. Scope ruling (carried from the report, §八)
+
+This tool family is **text-keyword recallable navigation** — the phone book + index + pointer
+for a long session. Semantics is out of scope: no embeddings, no semantic ranking, no
+"fuzzy" retrieval. The model is a language model; synonym/substitution/keyword work is its
+job. We guarantee only: **原文可取 + 可寻址** (原文 retrievable, and addressable).
+
+Every number this scheme shows the model MUST either be directly usable as a selector in the
+same URL family, or be explicitly labeled metadata with its unit. A bare, unlabeled number
+that *looks* like a coordinate but is not addressable is the failure mode this change
+eliminates.
+
+## 2. Coordinate model (the spine)
+
+Two coordinate systems, both labeled wherever shown:
+
+| Unit | Meaning | Used by |
+|---|---|---|
+| `seq` | event sequence number in the session log | `[<n\|seq>]` element/label addressing |
+| `line` | transcript line number (1-based) | `:N-M` windows and `grep … ctx://session/transcript` |
+
+The transcript is the **canonical coordinate space**. `grep` on `ctx://session/transcript`
+materializes the transcript and returns transcript line numbers; therefore every exposed
+`lines=` figure is a transcript line and pastes directly into `:N-M`, and episode windows are
+transcript-relative.
+
+**Decision (user, 2026-10-02): transcript-relative everywhere.** `compactions[label]:5300-5310`
+means transcript lines 5300–5310, identical to `transcript:5300-5310`. The first episode starts
+at transcript line 1, so episode-relative and transcript-relative coincide for it.
+
+## 3. Data model changes (in `better-dsh/src/url-schemes/handlers/ctx.ts`)
+
+### 3.1 Transcript line index (structural, N1)
+
+Build the transcript **once** and carry per-entry line ranges, instead of the current two
+independent renders (`transcript()` and each episode's `originalText`):
+
+```ts
+interface TranscriptIndex {
+  text: string                      // the joined transcript (canonical face)
+  totalLines: number
+  lineOfSeq: Map<number, { start: number; end: number }>   // per rendered entry, transcript lines
+}
+
+function buildTranscript(events, toolNameOf): TranscriptIndex {
+  const entries = events
+    .map(e => ({ seq: e.seq as number, text: renderEntry(e, toolNameOf) }))
+    .filter(t => t.text !== '')
+  const lineOfSeq = new Map()
+  let line = 1
+  for (let i = 0; i < entries.length; i++) {
+    const n = entries[i].text.split('\n').length
+    lineOfSeq.set(entries[i].seq, { start: line, end: line + n - 1 })
+    line += n + (i < entries.length - 1 ? 1 : 0)   // one blank separator line between entries
+  }
+  return { text: entries.map(e => e.text).join('\n\n'), totalLines: line - 1, lineOfSeq }
+}
+```
+
+The episode's canonical span is then **derived** from the index (guarantees the invariant by
+construction):
+
+```ts
+// episode lines = min/max transcript line over the shadowed events that rendered
+const lineStart = min(lineOfSeq.get(seq).start for shadowed seqs that rendered)
+const lineEnd   = max(lineOfSeq.get(seq).end   for shadowed seqs that rendered)
+const originalText = transcript.text.split('\n').slice(lineStart - 1, lineEnd).join('\n')
+```
+
+If no shadowed event rendered (degenerate), the episode has an empty span (`lines: null`).
+
+### 3.2 Episode shape
+
+Each episode gains `lines: { start, end } | null`, `fidelity: { userTurns, toolCalls }`, and a
+computed `landmarks` block. The manifest line, the snapshot `compacted[]` entry, the snapshot
+`segments[]` entry, and the episode prepared face all carry `lines=` and `seq=` labeled figures.
+
+### 3.3 `resultTextOf` shape robustness (F2)
+
+`tool/result` messages in the current session format store **flat** text blocks
+(`data.message.content: [{type:"text", text:"…"}]`); the nested `tool-result` block form is
+the older shape. Today `resultTextOf` only flattens the nested form, so every result renders
+empty. Fix: prefer nested, fall back to flat:
+
+```ts
+function resultTextOf(event: PersistenceEvent): string {
+  const blocks = blocksOf(event)
+  const nested = blocks
+    .flatMap(b => (b as { content?: ContentBlock[] }).content ?? [])
+    .map(c => c.text ?? '').join('\n')
+  if (nested !== '') return nested
+  return textOf(blocks)   // flat text blocks (current session format)
+}
+```
+
+## 4. Backlog implementation
+
+### N1 — addressable line coordinates + explicit bounds (F7/F10)
+
+- Manifest line per episode: `seq=<start>..<end> (N items, T tokens)` **and**
+  `lines=<lineStart>..<lineEnd>` (or `lines=<none>`), plus `fidelity=ut:tc`.
+- Snapshot: `segments[]` → `{ segment, seq_start, seq_end, lines: {start,end}|null, items }`;
+  `compacted[]` gains `lines`, `fidelity`.
+- Episode prepared face header prints `lines=` and `seq=` labeled.
+- Episode line windows are transcript-relative and **clamped with an explicit boundary note**
+  when a requested range reaches past the span (never silent-empty):
+
+  ```ts
+  // transcript coords -> episode-local coords
+  function applyEpisodeLines(slice, lineStart, lineEnd, ranges): string
+  // out-of-span tail appends: [ctx:// note: episode span is transcript lines <s>-<e>]
+  ```
+
+  A window entirely outside the span returns the note alone (not empty). `:raw` still returns
+  the full span.
+
+### N2 — digest residence rule (design position §八.4)
+
+- `latest` = the last episode in the chain; its digest is the compact-checkpoint message
+  already resident in live context.
+- Compute the checkpoint's transcript lines (the `user/message` with `source.plugin === 'compact'`
+  at `checkpointSeq`; fall back to the seq when no line is mapped).
+- Latest episode prepared face = **navigation block** (no digest dump):
+
+  ```text
+  [ctx://session/compactions[<label>] — digest is already in your live context]
+  lines=<ls>..<le>  seq=<ss>..<se>  items=<n>  tokens=<t>
+  fidelity=<ut>:<tc>
+  digest resident at seq=<checkpointSeq> (transcript:<start>-<end> when mapped) — read it there,
+  or use :raw here for the shadowed span
+  <landmarks>
+  ```
+
+- Older episode prepared face = **full digest** (`summaryText`) followed by the same pointer
+  block. `:raw` on any episode always returns the span, so a digest is never lost.
+
+### N3 — landmark roster (direction markers, all as line coordinates)
+
+Computed over the episode's shadowed events; capped to stay one screen:
+
+- `user turns (<n>): <line>, <line>, …` — transcript line of each rendered `user/message`
+  with `source.kind === 'user'` (cap 30, then `… +N more`).
+- `failures (<n>): <line> <tool>, …` — `tool/result` events with
+  `data.message.isError === true` or a present `data.error` (cap 20).
+- `touched paths: <path>×<count>, …` — path-valued strings extracted from `tool/call`
+  `arguments` (keys `path`/`file_path`/`filePath`/`file`, plus `edits[].path` and
+  `files[].path`; args larger than 64 000 chars skipped). Best-effort pointer, not an index.
+  (cap 12, sorted by count desc).
+- `prior checkpoints in span: <n>` — count of `user/message` with `source.plugin === 'compact'`.
+
+### N4 — fidelity line
+
+`fidelity=<userTurns>:<toolCalls>` per episode (tool-heavy ⇒ digest trustworthy and detail
+regenerable; user-intent-heavy ⇒ must drill down). Inline in manifest, snapshot `compacted[]`,
+and the episode pointer block.
+
+### N5 — `:path/` and `?q=` in ctx (F5/F8) + error echo
+
+The selector grammar already parses `path`/`query` and `applySelector()` (selector.ts) already
+implements JSON dot-path + line filter. Wire them into `applyFace`:
+
+```ts
+if (selector.kind === 'path' || selector.kind === 'query') {
+  return applySelector(face === 'canonical' ? canonical : prepared, selector)
+}
+```
+
+So `ctx://session:path/totals.tool_calls` narrow-reads the snapshot JSON, and
+`ctx://session/injections?q=subagent-settled` filters the index. The manifest route also runs
+through `applySelector` (so `?q=` and `:N-M` windowing work on it too). Update
+`CTX_BAD_SELECTOR` to echo the URL and the supported selector set.
+
+### N6 — snapshot `asOf`
+
+Snapshot gains `asOf: { seq: <max seq>, line: <totalLines> }` and a hint that totals are live
+at read time (a cached snapshot is knowingly stale).
+
+### F1 — element-collection index faces + error echo
+
+- `user_prompts` bare → index list (one line per prompt: `seq=<s> <preview>`); canonical
+  `:raw` = all joined.
+- `tool_calls` / `agent_responses` bare → bounded index (first 20 lines + `… +N more — use
+  :raw for all, ?q= to filter, [n|seq] for one`); canonical `:raw` = all joined.
+- `[n|seq]` behavior unchanged.
+- Error text for a bad element stops echoing an empty-bracket URL; it names the collection,
+  its count, and the 0-based/seq addressing (already mostly present — align the message).
+
+## 5. Out of scope
+
+- F3 (`read` offset/limit silently ignored on URIs) — harness read-tool contract, not this handler.
+- Semantic/vector retrieval; embeddings; "fuzzy" search (see §1).
+- F4 (compaction label drift) — already mitigated by the error listing current labels; the
+  `compactionId` (uuid) stable-key idea is recorded but not implemented this wave.
+
+## 6. Verification
+
+Unit: extend `better-dsh/test/url-schemes/ctx.spec.ts` (and add focused specs) with the
+invariants above — notably **episode span ≡ transcript slice** and **episode `:N-M` ≡
+`transcript:N-M`** for non-first episodes. Full `vitest run` + `tsc --noEmit` green.
+
+First-person (4999 rig, dsh 0.2.0-rc.2): a real long-session instance reads the snapshot
+(asOf + lines present), windows a deep episode by transcript line, filters an index with
+`?q=`, narrow-reads with `:path/`, and confirms a large tool result is no longer empty.

package/lib/client/index.js

@@ -32,19 +32,12 @@ __deepseek_ai_dsh_client_ui_primitives = __toESM(__deepseek_ai_dsh_client_ui_pri
 
 //#region src/failover/config.ts
 /**
-* The `failover` general-fallback config (host-plane, per-turn latch).
-*
-* Pure module — no `@deepseek-ai/*` value imports, so both the host module and
-* the client half may import it (the client type-only) without dragging a host
-* runtime dependency into the browser bundle.
-*
-* A route is a `provider/model` string (e.g. `deepseek/deepseek-v4-flash`).
-* The empty string `''` means "not set" — the slot is skipped.
-*
-* @module dashr/failover/config
+* The Loader entry id the failover row composes under. dsh 0.1.7 collapsed the
+* settings namespace onto entry ids: `remote.settings` describe/update address
+* the row's patch entry, the entry id IS the settings namespace, and edits
+* persist as a profile-layer patch override through the config editor.
 */
-/** The settings namespace the General row reads and writes. */
-const FAILOVER_SETTINGS_NS = "failover";
+const FAILOVER_SETTINGS_ENTRY = "dashr-failover";
 
 //#endregion
 //#region src/failover/client/locales.ts
@@ -71,7 +64,7 @@ const zh = {
 };
 
 //#endregion
-//#region \0dsh-css:/home/u1/workspaces/dashr/dashr/src/failover/client/FailoverRow.module.css.mjs
+//#region \0dsh-css:/home/u1/workspaces/dashr/better-dsh/src/failover/client/FailoverRow.module.css.mjs
 const css$1 = "\n._440e1d7b_row {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  padding: 12px 0;\n}\n\n._a4f2ceec_rowText {\n  flex: 1;\n  min-width: 0;\n  display: flex;\n  flex-direction: column;\n  gap: 4px;\n}\n\n._9865b509_title {\n  font-weight: 600;\n  font-size: 14px;\n}\n\n\n._3cfec826_slots {\n  display: flex;\n  flex-direction: column;\n  align-items: flex-end;\n  gap: 6px;\n}\n\n._11c2662d_select {\n  width: 280px;\n  max-width: 100%;\n  min-width: 0;\n}\n\n._b7c358f9_alert {\n  color: var(--dsw-alias-danger, #c0392b);\n  font-size: 12px;\n}\n";
 const tagId$1 = "better-dsh/FailoverRow.module.css";
 if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId$1) + "]") === null) {
@@ -430,6 +423,13 @@ function setupMobileLayout(ctx) {
 */
 /** The settings namespace the General row reads and writes. */
 const COMPACTION_SETTINGS_NS = "compaction-tuning";
+/**
+* The Loader entry id the tuning row composes under. dsh 0.1.7 collapsed the
+* settings namespace onto entry ids: `remote.settings` describe/update address
+* the row's patch entry, the entry id IS the settings namespace, and edits
+* persist as a profile-layer patch override through the config editor.
+*/
+const COMPACTION_SETTINGS_ENTRY = "dashr-compaction-tuning";
 /** Upstream `compaction-basic`'s own default: condense at 80% of the window. */
 const DEFAULT_THRESHOLD_RATIO = .8;
 /** Whole-percent bounds for the General row's stepper. */
@@ -463,7 +463,7 @@ const zh$1 = {
 };
 
 //#endregion
-//#region \0dsh-css:/home/u1/workspaces/dashr/dashr/src/compaction/client/CompactionRow.module.css.mjs
+//#region \0dsh-css:/home/u1/workspaces/dashr/better-dsh/src/compaction/client/CompactionRow.module.css.mjs
 const css = "\n\n\n._13e3747c_thresholdRow {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  padding: 16px 0;\n  border-bottom: 0.5px solid var(--dsw-alias-border-l2);\n}\n\n._8ad3ff3f_thresholdText {\n  flex: 1;\n  min-width: 0;\n  display: flex;\n  flex-direction: column;\n  gap: 4px;\n  padding-right: 48px;\n}\n\n._9ffb627e_thresholdTitle {\n  font-size: 14px;\n  font-weight: 400;\n  line-height: 22px;\n  color: var(--dsw-alias-label-primary);\n}\n\n._01bea389_thresholdDesc {\n  font-size: 12px;\n  font-weight: 400;\n  line-height: 18px;\n  color: var(--dsw-alias-label-tertiary);\n}\n\n._7f9578de_thresholdError {\n  font-size: 12px;\n  font-weight: 400;\n  line-height: 18px;\n  color: var(--dsw-alias-danger, #c0392b);\n}\n\n\n._cddd78cd_thresholdControl {\n  display: inline-flex;\n  align-items: center;\n  gap: 8px;\n}\n\n._6058fea9_thresholdStepper {\n  position: relative; \n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  min-width: 72px;\n  height: 36px;\n  border-radius: 18px;\n  background: var(--dsw-alias-bg-module-platform);\n}\n\n._39d30469_thresholdValue {\n  min-width: 18px;\n  text-align: center;\n  font-size: 14px;\n  line-height: 22px;\n  font-variant-numeric: tabular-nums;\n  color: var(--dsw-alias-label-primary);\n}\n\n._68bd35c6_thresholdUnit {\n  font-size: 14px;\n  line-height: 22px;\n  color: var(--dsw-alias-label-secondary);\n}\n\n\n._904da366_thresholdArrows {\n  position: absolute;\n  right: 8px;\n  display: flex;\n  flex-direction: column;\n  gap: 2px;\n  opacity: 0;\n}\n\n._6058fea9_thresholdStepper:hover ._904da366_thresholdArrows,\n._6058fea9_thresholdStepper:focus-within ._904da366_thresholdArrows {\n  opacity: 1;\n}\n\n\n._ae9106b1_thresholdArrow {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  width: 17px;\n  height: 12px;\n  padding: 0;\n  border: none;\n  border-radius: 3px;\n  background: color-mix(in srgb, var(--dsw-alias-bg-layer-1) 75%, transparent);\n  color: var(--dsw-alias-label-primary);\n  cursor: pointer;\n}\n\n._ae9106b1_thresholdArrow:hover:not(:disabled) {\n  background: var(--dsw-alias-bg-layer-1);\n}\n\n._ae9106b1_thresholdArrow:disabled {\n  color: var(--dsw-alias-label-caption);\n  cursor: default;\n}\n";
 const tagId = "better-dsh/CompactionRow.module.css";
 if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
@@ -587,7 +587,7 @@ function CompactionRow({ t, loadConfig, save }) {
 						onClick: () => {
 							step(THRESHOLD_STEP_PERCENT);
 						},
-						children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(__deepseek_ai_dsh_client_ui_primitives.IconChevronUpOutline14, { size: 9 })
+						children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(__deepseek_ai_dsh_client_ui_primitives.IconChevronUpOutlineRegular, { size: 9 })
 					}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 						type: "button",
 						className: CompactionRow_module_css_default.thresholdArrow,
@@ -596,7 +596,7 @@ function CompactionRow({ t, loadConfig, save }) {
 						onClick: () => {
 							step(-THRESHOLD_STEP_PERCENT);
 						},
-						children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(__deepseek_ai_dsh_client_ui_primitives.IconChevronDownOutline14, { size: 9 })
+						children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(__deepseek_ai_dsh_client_ui_primitives.IconChevronDownOutlineRegular, { size: 9 })
 					})]
 				})]
 			}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
@@ -632,7 +632,7 @@ function setupCompactionRow(ctx) {
 				loadConfig: async () => {
 					const response = await ctx.remote.settings.describe();
 					if (!response.ok) throw new Error(`${response.error.code}: ${response.error.message}`);
-					const view = response.value.namespaces.find((entry) => entry.ns === COMPACTION_SETTINGS_NS);
+					const view = response.value.namespaces.find((entry) => entry.ns === COMPACTION_SETTINGS_ENTRY);
 					if (view === void 0) return null;
 					const value = view.value;
 					return {
@@ -641,7 +641,7 @@ function setupCompactionRow(ctx) {
 					};
 				},
 				save: async (patch, revision) => {
-					const response = await ctx.remote.settings.update(COMPACTION_SETTINGS_NS, patch, revision);
+					const response = await ctx.remote.settings.update(COMPACTION_SETTINGS_ENTRY, patch, revision);
 					if (!response.ok) throw new Error(`${response.error.code}: ${response.error.message}`);
 					return response.value.revision;
 				}
@@ -686,7 +686,7 @@ function apply(ctx) {
 				loadConfig: async () => {
 					const response = await ctx.remote.settings.describe();
 					if (!response.ok) throw new Error(`${response.error.code}: ${response.error.message}`);
-					const view = response.value.namespaces.find((entry) => entry.ns === FAILOVER_SETTINGS_NS);
+					const view = response.value.namespaces.find((entry) => entry.ns === FAILOVER_SETTINGS_ENTRY);
 					if (view === void 0) return null;
 					const value = view.value;
 					return {
@@ -696,7 +696,7 @@ function apply(ctx) {
 					};
 				},
 				save: async (patch, revision) => {
-					const response = await ctx.remote.settings.update(FAILOVER_SETTINGS_NS, patch, revision);
+					const response = await ctx.remote.settings.update(FAILOVER_SETTINGS_ENTRY, patch, revision);
 					if (!response.ok) throw new Error(`${response.error.code}: ${response.error.message}`);
 					return response.value.revision;
 				}