better-dsh 0.2.4-c → 0.2.5-a

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/fs-aware/sandbox-plugin.js

@@ -1,10 +1,10 @@
-import { f as UrlSchemesError, t as buildFsLayerResolver } from "../wrap-Dr8XtIak.js";
+import { f as UrlSchemesError, t as buildFsLayerResolver } from "../wrap-Bzdimp4p.js";
 import { Context } from "@deepseek-ai/cordis";
 import { dirname, sep } from "node:path";
+import { stat } from "node:fs/promises";
 import { LocalFileSystem } from "@deepseek-ai/dsh-fs-local";
 import { FsError } from "@deepseek-ai/dsh-fs";
 import { writableRoots } from "@deepseek-ai/dsh-sandbox";
-import { stat } from "node:fs/promises";
 
 //#region ../upstream/deepseek-harness/packages/fs/fs-sandbox/lib/index.js
 /**

package/lib/url-schemes/index.js

@@ -1,5 +1,5 @@
 import { n as captureNativeTools } from "../native-capture-x_Hos2e8.js";
-import { a as createHttpHandler, c as listDvcDevices, d as UrlResolver, f as UrlSchemesError, i as HTTP_SCHEMES, l as registerDvcDevice, m as SCHEME_NAMES, n as wrapFsWithSchemes, o as createDvcHandler, p as parseUrl, r as resolveDocsDir, s as dispatchDvcWrite, u as createDshHandler } from "../wrap-Dr8XtIak.js";
+import { a as createHttpHandler, c as listDvcDevices, d as UrlResolver, f as UrlSchemesError, h as SCHEME_NAMES, i as HTTP_SCHEMES, l as registerDvcDevice, m as parseUrl, n as wrapFsWithSchemes, o as createDvcHandler, p as applySelector, r as resolveDocsDir, s as dispatchDvcWrite, u as createDshHandler } from "../wrap-Bzdimp4p.js";
 import { a as primaryServerForFile, c as serversForFile, n as findWorkspaceRoot, o as resolveCommandPath, r as installHintFor, s as serverByName } from "../lsp-server-registry-946ysdqg.js";
 import { createRequire } from "node:module";
 import { randomUUID } from "node:crypto";
@@ -11,10 +11,10 @@ import { spawn } from "node:child_process";
 import { homedir, tmpdir } from "node:os";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { defineTool } from "@deepseek-ai/dsh-tools";
-import { FsError } from "@deepseek-ai/dsh-fs";
-import { ESCALATION_TARGETS, approveEscalation, escalationHintMarker, sandboxDenialMarker, validateEscalationArgs } from "@deepseek-ai/dsh-sandbox";
 import * as fsPromises from "node:fs/promises";
 import { mkdir, mkdtemp, readFile, readdir, rename, rm, stat, unlink, writeFile } from "node:fs/promises";
+import { FsError } from "@deepseek-ai/dsh-fs";
+import { ESCALATION_TARGETS, approveEscalation, escalationHintMarker, sandboxDenialMarker, validateEscalationArgs } from "@deepseek-ai/dsh-sandbox";
 import { SessionId } from "@deepseek-ai/dsh-session";
 import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
 import "file-type";
@@ -2445,7 +2445,9 @@ function sourcePlugin(event) {
 	return event.data?.source?.plugin ?? "";
 }
 function resultTextOf(event) {
-	return blocksOf(event).flatMap((b) => b.content ?? []).map((c) => c.text ?? "").join("\n");
+	const blocks = blocksOf(event);
+	const nested = blocks.flatMap((b) => b.content ?? []).map((c) => c.text ?? "").join("\n");
+	return nested !== "" ? nested : textOf(blocks);
 }
 /** All reasoning blocks in event order (one message may carry several). */
 function thinkingItems(events) {
@@ -2530,13 +2532,137 @@ function sectionPreviews(text, n = 100) {
 }
 function applyLines(canonical, ranges) {
 	const lines = canonical.split("\n");
-	return ranges.map(([a, b]) => lines.slice(Math.max(0, a - 1), b).join("\n")).join("\n");
+	const total = lines.length;
+	const out = [];
+	let noted = false;
+	for (const [aRaw, bRaw] of ranges) {
+		const a = Math.max(1, aRaw);
+		const b = bRaw === Infinity ? total : bRaw;
+		if (b < 1 || a > total) {
+			noted = true;
+			continue;
+		}
+		out.push(...lines.slice(a - 1, Math.min(b, total)));
+		if (bRaw !== Infinity && b > total) noted = true;
+	}
+	const body = out.join("\n");
+	if (!noted) return body;
+	const note = `[ctx:// note: canonical content ends at line ${total}]`;
+	return body === "" ? note : `${body}\n\n${note}`;
 }
 function applyFace(prepared, canonical, selector, face = "prepared") {
 	if (selector === void 0 || selector === null) return face === "canonical" ? canonical : prepared;
 	if (selector.kind === "raw") return canonical;
 	if (selector.kind === "lines") return applyLines(canonical, selector.ranges);
-	throw new UrlSchemesError("CTX_BAD_SELECTOR", `ctx://: unsupported selector kind "${selector.kind}"`);
+	if (selector.kind === "path" || selector.kind === "query") return applySelector(face === "canonical" ? canonical : prepared, selector);
+	throw new UrlSchemesError("CTX_BAD_SELECTOR", `ctx://: unsupported selector kind "${selector.kind}" (supported: :raw, :N-M, :path/, ?q=)`);
+}
+function buildTranscript(events, toolNameOf) {
+	const entries = events.map((e) => ({
+		seq: e.seq,
+		text: renderEntry(e, toolNameOf)
+	})).filter((t) => t.text !== "");
+	const lineOfSeq = /* @__PURE__ */ new Map();
+	let line = 1;
+	entries.forEach((entry, i) => {
+		const n = entry.text.split("\n").length;
+		lineOfSeq.set(entry.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
+	};
+}
+/** Apply transcript-relative line ranges to one episode span slice, with a boundary note. */
+function applyEpisodeLines(slice, lineStart, lineEnd, ranges) {
+	const lines = slice.split("\n");
+	const out = [];
+	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 (b > lineEnd || a < lineStart) noted = true;
+	}
+	return out.join("\n") + (noted ? `\n\n[ctx:// note: episode span is transcript lines ${lineStart}-${lineEnd}]` : "");
+}
+function isErrorOf(event) {
+	return event.data?.message?.isError === true || event.data?.error !== void 0;
+}
+const PATH_KEYS = new Set([
+	"path",
+	"file_path",
+	"filePath",
+	"file"
+]);
+function collectPaths(node, out, depth) {
+	if (depth > 4 || node === null || node === void 0) return;
+	if (typeof node === "string") return;
+	if (Array.isArray(node)) {
+		for (const x of node) collectPaths(x, out, depth + 1);
+		return;
+	}
+	if (typeof node === "object") for (const [k, v] of Object.entries(node)) if (PATH_KEYS.has(k) && typeof v === "string" && v !== "") out.add(v);
+	else collectPaths(v, out, depth + 1);
+}
+function touchedPathsOf(events) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const e of events) {
+		if (e.type !== "tool/call") continue;
+		const args = e.data?.arguments;
+		if (args === void 0 || args.length > 64e3) continue;
+		let parsed;
+		try {
+			parsed = JSON.parse(args);
+		} catch {
+			continue;
+		}
+		const found = /* @__PURE__ */ new Set();
+		collectPaths(parsed, found, 0);
+		for (const p of found) counts.set(p, (counts.get(p) ?? 0) + 1);
+	}
+	return [...counts.entries()].sort((a, b) => b[1] - a[1]);
+}
+function landmarkBlock(ep, tIdx, toolNameOf) {
+	const lineOf = (e) => tIdx.lineOfSeq.get(e.seq)?.start;
+	const userTurns = ep.shadowEvents.filter((e) => e.type === "user/message" && sourceKind(e) === "user").map(lineOf).filter((x) => x !== void 0);
+	const failures = ep.shadowEvents.filter((e) => e.type === "tool/result" && isErrorOf(e)).map((e) => `${lineOf(e) ?? "?"} ${toolNameOf(e.sourceEventSeqs?.[0]) ?? "tool"}`);
+	const paths = touchedPathsOf(ep.shadowEvents).slice(0, 12).map(([p, n]) => `${p}×${n}`);
+	const priorCheckpoints = ep.shadowEvents.filter((e) => e.type === "user/message" && sourcePlugin(e) === "compact").length;
+	const cap = (xs, n) => xs.length > n ? `${xs.slice(0, n).join(", ")} … +${xs.length - n} more` : xs.join(", ");
+	return [
+		`user turns (${userTurns.length}): ${cap(userTurns, 30)}`,
+		`failures (${failures.length}): ${cap(failures, 20)}`,
+		`touched paths: ${paths.length > 0 ? paths.join(", ") : "(none)"}`,
+		`prior checkpoints in span: ${priorCheckpoints}`
+	].join("\n");
+}
+function episodePrepared(ep, list, tIdx, toolNameOf) {
+	const isLatest = list.length > 0 && list[list.length - 1] === ep;
+	const ls = ep.lines === null ? "<none>" : `${ep.lines.start}..${ep.lines.end}`;
+	const pointer = [
+		`[ctx://session/compactions[${ep.label}]${isLatest ? " — digest is already in your live context" : ""}]`,
+		`lines=${ls}  seq=${ep.shadowedRange.start}..${ep.shadowedRange.end}  items=${ep.shadowedSeqs.length}  tokens=${ep.shadowedTokenCount}`,
+		`fidelity=${ep.fidelity.userTurns}:${ep.fidelity.toolCalls}`
+	];
+	if (isLatest) {
+		const ck = tIdx.lineOfSeq.get(ep.checkpointSeq);
+		pointer.push(`digest resident at seq=${ep.checkpointSeq}${ck !== void 0 ? ` (transcript:${ck.start}-${ck.end})` : ""} — read it there, or use :raw here for the shadowed span`);
+	} else if (ep.replacesCheckpoint !== null) pointer.push(`replaces_checkpoint=${ep.replacesCheckpoint}`);
+	pointer.push(landmarkBlock(ep, tIdx, toolNameOf));
+	const block = pointer.join("\n");
+	return isLatest ? block : `${ep.summaryText}\n\n${block}`;
 }
 function createCtxHandler(deps) {
 	const persistence = deps.sessionPersistence;
@@ -2575,15 +2701,25 @@ function createCtxHandler(deps) {
 			const toolNameOf = (seq) => seq === void 0 ? void 0 : toolNameByCallSeq.get(seq);
 			const userPromptEvents = events.filter((e) => e.type === "user/message" && sourceKind(e) === "user");
 			const agentResponseEvents = events.filter((e) => e.type === "assistant/message");
-			const transcript = () => events.map((e) => renderEntry(e, toolNameOf)).filter((t) => t !== "").join("\n\n");
+			const tIdx = buildTranscript(events, toolNameOf);
 			const episodes = [];
 			{
 				let prevCheckpoint = null;
-				const nameOf = toolNameOf;
 				for (const e of events) {
 					if (e.type !== "compaction/summary") continue;
 					const d = e.data;
-					const originalText = d.shadowedSeqs.map((seq) => events.find((ev) => ev.seq === seq)).filter((ev) => ev !== void 0).map((ev) => renderEntry(ev, nameOf)).filter((t) => t !== "").join("\n\n");
+					const shadowSet = new Set(d.shadowedSeqs);
+					const shadowEvents = events.filter((ev) => shadowSet.has(ev.seq));
+					const shadowLines = d.shadowedSeqs.map((seq) => tIdx.lineOfSeq.get(seq)).filter((x) => x !== void 0);
+					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");
+					const fidelity = {
+						userTurns: shadowEvents.filter((ev) => ev.type === "user/message" && sourceKind(ev) === "user").length,
+						toolCalls: shadowEvents.filter((ev) => ev.type === "tool/call").length
+					};
 					episodes.push({
 						label: e.seq,
 						checkpointSeq: e.seq + 1,
@@ -2594,7 +2730,10 @@ function createCtxHandler(deps) {
 						shadowedTokenCount: d.shadowedTokenCount,
 						replacesCheckpoint: prevCheckpoint !== null && d.shadowedSeqs.includes(prevCheckpoint) ? prevCheckpoint : null,
 						summaryText: d.summary.map((s) => s.text).join(""),
-						originalText
+						originalText,
+						lines,
+						fidelity,
+						shadowEvents
 					});
 					prevCheckpoint = e.seq + 1;
 				}
@@ -2613,26 +2752,31 @@ function createCtxHandler(deps) {
 			const seg1 = segments[1] === void 0 ? void 0 : parseSeg(segments[1]);
 			if (seg0 === void 0 || seg0.name === "transcript") {
 				seg0?.name;
-				const canonical = transcript();
-				return applyFace(buildSnapshot(agent, events, episodes), canonical, sel, seg0?.name === "transcript" ? "canonical" : "prepared");
+				const canonical = tIdx.text;
+				return applyFace(buildSnapshot(agent, events, episodes, tIdx), canonical, sel, seg0?.name === "transcript" ? "canonical" : "prepared");
 			}
 			if (seg0.name === "compactions") {
 				if (seg0.bracket === void 0) {
-					if (sel !== null && sel.kind !== "raw") throw new UrlSchemesError("CTX_BAD_SELECTOR", "ctx://session/compactions: only :raw (or no selector) is supported on the manifest");
 					const body = episodes.map((e) => [
 						`label=${e.label} (checkpoint_seq=${e.checkpointSeq})`,
 						`compactionId=${e.compactionId}`,
 						`at=${new Date(e.at ?? 0).toISOString()}`,
-						`shadowed=${e.shadowedRange.start}..${e.shadowedRange.end} (${e.shadowedSeqs.length} items, ${e.shadowedTokenCount} tokens)`,
+						`seq=${e.shadowedRange.start}..${e.shadowedRange.end} (${e.shadowedSeqs.length} items, ${e.shadowedTokenCount} tokens)`,
+						`lines=${e.lines === null ? "<none>" : `${e.lines.start}..${e.lines.end}`}`,
+						`fidelity=${e.fidelity.userTurns}:${e.fidelity.toolCalls}`,
 						`replaces_checkpoint=${e.replacesCheckpoint ?? "null"}`,
 						`preview=${e.summaryText.slice(0, 120)}…`
 					].join(" | ")).join("\n");
-					return body === "" ? "(no compactions recorded)" : body;
+					const text = body === "" ? "(no compactions recorded)" : body;
+					if (sel === null || sel.kind === "raw") return text;
+					if (sel.kind === "lines") return applyLines(text, sel.ranges);
+					return applySelector(text, sel);
 				}
 				const episode = pickEpisode(episodes, seg0.bracket);
 				if (seg1 === void 0) {
 					if (sel !== null && sel.kind === "raw" && episode.originalText.length > 65536) return episode.originalText + `\n\n[ctx:// note: original span is ${episode.originalText.length} chars — page with :N-M line windows or grep this URL]`;
-					return applyFace(episode.summaryText, episode.originalText, sel, "prepared");
+					if (sel !== null && sel.kind === "lines" && episode.lines !== null) return applyEpisodeLines(episode.originalText, episode.lines.start, episode.lines.end, sel.ranges);
+					return applyFace(episodePrepared(episode, episodes, tIdx, toolNameOf), episode.originalText, sel, "prepared");
 				}
 				throw new UrlSchemesError("CTX_BAD_PATH", `ctx://${raw}: unknown sub-path "/${seg1.name}" ("/original" was superseded by the :raw / :raw:N-M selectors)`);
 			}
@@ -2671,13 +2815,19 @@ function createCtxHandler(deps) {
 				}));
 				throw new UrlSchemesError("CTX_BAD_PATH", `ctx://${raw}: unknown collection "${name$1}"`);
 			};
-			if (seg0.bracket !== void 0 || seg0.name === "user_prompts" || seg0.name === "tool_calls" || seg0.name === "agent_responses") {
+			if (seg0.name === "user_prompts" || seg0.name === "tool_calls" || seg0.name === "agent_responses") {
 				const items = collection(seg0.name);
-				const bracket = seg0.bracket ?? "";
-				const bySeq = items.find((it) => it.seq === Number(bracket));
+				const canonical = items.map((it) => it.text).join("\n\n");
+				if (seg0.bracket === void 0) {
+					const bounded = seg0.name !== "user_prompts";
+					const index = (bounded ? items.slice(0, 20) : items).map((it) => `seq=${it.seq} ${previewOf(it.text)}`).join("\n");
+					const tail = bounded && items.length > 20 ? `\n… +${items.length - 20} more — use :raw for all, ?q= to filter, [n|seq] for one` : "";
+					return applyFace(index === "" ? `(no ${seg0.name} items recorded)` : index + tail, canonical, sel, "prepared");
+				}
+				const bySeq = items.find((it) => it.seq === Number(seg0.bracket));
 				if (bySeq !== void 0) return applyFace(bySeq.text, bySeq.text, sel, "prepared");
-				const ordinal = Number(bracket);
-				if (bracket === "" || !Number.isInteger(ordinal) || ordinal < 0 || ordinal >= items.length) throw new UrlSchemesError("CTX_NO_SUCH_ELEMENT", `ctx://…[${bracket}]: no such element (collection "${seg0.name}" has ${items.length} items, 0-based; labels are event seqs)`);
+				const ordinal = Number(seg0.bracket);
+				if (!Number.isInteger(ordinal) || ordinal < 0 || ordinal >= items.length) throw new UrlSchemesError("CTX_NO_SUCH_ELEMENT", `ctx://session/${seg0.name}[${seg0.bracket}]: no such element (collection "${seg0.name}" has ${items.length} items, 0-based; labels are event seqs)`);
 				return applyFace(items[ordinal].text, items[ordinal].text, sel, "prepared");
 			}
 			throw new UrlSchemesError("CTX_UNKNOWN_KEY", `ctx://${raw}: unknown path (known: session, session/transcript, session/compactions[...], session/user_prompts[...], session/tool_calls[...], session/agent_responses[...], session/thinking[...], session/system[...], session/injections[...]; bare ctx:// lists the full roster)`);
@@ -2688,7 +2838,7 @@ function createCtxHandler(deps) {
 				if (Number.isInteger(ordinal) && ordinal >= 0 && ordinal < list.length) return list[ordinal];
 				throw new UrlSchemesError("CTX_NO_SUCH_ELEMENT", `ctx://…[${bracket}]: no such compaction episode (labels: ${list.map((e) => e.label).join(", ") || "none"})`);
 			}
-			function buildSnapshot(agent$1, all, list) {
+			function buildSnapshot(agent$1, all, list, tIdx$1) {
 				const headers = all.filter((e) => e.type === "request/header");
 				const system = (headers[headers.length - 1]?.data)?.header?.system;
 				const counts = {};
@@ -2712,9 +2862,10 @@ function createCtxHandler(deps) {
 					"tool_results"
 				]) counts[key] = counts[key] ?? 0;
 				const header = agent$1.session.header;
+				const lastSeq = all.reduce((m, e) => Math.max(m, e.seq), 0);
 				return JSON.stringify({
 					resource: "ctx://session",
-					syntax: "/sub-path [<label|n>] [:N-M]; :raw = canonical full content; :raw:N-M ≡ :N-M",
+					syntax: "/sub-path [<label|n>] [:N-M|:path/|?q=]; :raw = canonical full content; :raw:N-M ≡ :N-M",
 					session: {
 						id: header.id ?? agent$1.id,
 						createdAt: header.createdAt,
@@ -2728,19 +2879,17 @@ function createCtxHandler(deps) {
 					totals: counts,
 					segments: [...list.map((e) => ({
 						segment: `compaction:${e.label}`,
-						start: e.shadowedRange?.start ?? null,
-						end: e.shadowedRange?.end ?? null,
+						seq_start: e.shadowedRange?.start ?? null,
+						seq_end: e.shadowedRange?.end ?? null,
+						lines: e.lines,
 						items: e.shadowedSeqs.length
-					})), (() => {
-						const lastSeq = all.reduce((m, e) => Math.max(m, e.seq), 0);
-						const start = (list.at(-1)?.shadowedRange?.end ?? -1) + 1;
-						return {
-							segment: "live",
-							start,
-							end: lastSeq,
-							items: all.filter((e) => e.seq >= start).length
-						};
-					})()],
+					})), {
+						segment: "live",
+						seq_start: (list.at(-1)?.shadowedRange?.end ?? -1) + 1,
+						seq_end: lastSeq,
+						lines: null,
+						items: all.filter((e) => e.seq >= (list.at(-1)?.shadowedRange?.end ?? -1) + 1).length
+					}],
 					system_prompt: {
 						chars: system?.length ?? 0,
 						preview: system === void 0 ? "" : system.slice(0, 200)
@@ -2750,16 +2899,24 @@ function createCtxHandler(deps) {
 						checkpoint_seq: e.checkpointSeq,
 						compactionId: e.compactionId,
 						at: e.at,
-						shadowed_range: e.shadowedRange,
+						seq_start: e.shadowedRange.start,
+						seq_end: e.shadowedRange.end,
+						lines: e.lines,
 						shadowed_items: e.shadowedSeqs.length,
 						shadowed_token_count: e.shadowedTokenCount,
+						fidelity: e.fidelity,
 						replaces_checkpoint: e.replacesCheckpoint,
 						summary_preview: sectionPreviews(e.summaryText)
 					})),
+					asOf: {
+						seq: lastSeq,
+						line: tIdx$1.totalLines
+					},
 					hints: [
 						"ctx://session:raw → full transcript",
 						"ctx://session/compactions[<label>]:raw → original span",
-						"ctx://session/thinking / ctx://session/system / ctx://session/injections → index-faced collections"
+						"ctx://session/thinking / system / injections / user_prompts / tool_calls / agent_responses → index faces",
+						":path/<dot-path> narrow-reads the snapshot · ?q=<text> filters an index"
 					]
 				}, void 0, 2);
 			}