dsh-session-recall 0.7.4 → 0.7.5

package/lib/index.d.ts

@@ -56,6 +56,19 @@ interface RecallConfig {
    * same project are invisible unless this is set to `false`.
    */
   callerTreeOnly?: boolean;
+  /**
+   * When the session index itself fails (`SESSION_QUERY_PERSISTENCE_FAILED`,
+   * e.g. one un-migratable artifact failing every indexed search —
+   * deepseek-harness discussion #7995), retry with a direct scan of the
+   * persisted session logs instead of failing the call. Default `true`.
+   */
+  rawScanFallback?: boolean;
+  /** Max persisted sessions visited by one degraded raw scan. Default `200`. */
+  rawScanMaxSessions?: number;
+  /** Wall-clock ceiling (ms) for one degraded raw scan. Default `20000`. */
+  rawScanMaxDurationMs?: number;
+  /** Compressed-size ceiling (bytes) per session log in a degraded scan. Default 8 MiB. */
+  rawScanMaxSessionBytes?: number;
 }
 /** Validated, fully defaulted configuration. */
 interface NormalizedRecallConfig {
@@ -72,6 +85,10 @@ interface NormalizedRecallConfig {
   readonly recencyHalfLifeDays: number | undefined;
   readonly pinnedCwds: readonly string[];
   readonly callerTreeOnly: boolean;
+  readonly rawScanFallback: boolean;
+  readonly rawScanMaxSessions: number;
+  readonly rawScanMaxDurationMs: number;
+  readonly rawScanMaxSessionBytes: number;
 }
 /** Default, clamp, and cross-check every optional field. */
 declare function normalizeRecallConfig(config?: RecallConfig): NormalizedRecallConfig;
@@ -107,7 +124,7 @@ interface RecallScope {
 /** How the matches in a result were produced (v0.5 diagnostics). */
 interface RecallDiagnostics {
   /** Which engine produced the matches. */
-  readonly source: 'fts' | 'cjk-fallback' | 'session-scan';
+  readonly source: 'fts' | 'cjk-fallback' | 'session-scan' | 'raw-scan';
   /** Sessions visited by the fallback scan, when it ran. */
   readonly scanned?: number;
   /** The fallback scan budget (`cjkFallbackScanMax`), when a scan ran. */
@@ -244,6 +261,70 @@ declare function cjkFallbackHint(matched: number, enabled: boolean): string | nu
 /** The zero-hit hint, shown only when both the full-text and substring paths miss. */
 declare function cjkZeroHitHint(query: string, zeroHits: boolean, enabled: boolean): string | null;
 //#endregion
+//#region src/resilient.d.ts
+/** Default scan budget (sessions visited per degraded call). */
+declare const RAW_SCAN_DEFAULT_MAX_SESSIONS = 300;
+/** Hard ceiling for the scan budget. */
+declare const RAW_SCAN_MAX_SESSIONS_MAX = 2000;
+/** Where the harness persists sessions: `$DSH_HOME/sessions` (default `~/.dsh/sessions`). */
+declare function discoverSessionsRoot(): string;
+/** True when an error means "the index is unavailable", not "the query was bad". */
+declare function isIndexOutage(error: unknown): boolean;
+interface RawScanOptions {
+  /** Sessions root (workspace directories below this). */
+  root: string;
+  /** Normalized search query; whitespace-separated terms, all must match. */
+  query: string;
+  /** Restrict to sessions started in this cwd (unless `allProjects`). */
+  cwd: string | null;
+  /** Ignore the cwd scope. */
+  allProjects: boolean;
+  /** Restrict to one session id (the `session_id` argument), or null. */
+  sessionId: string | null;
+  /** Only sessions newer than this many days (0 = no time filter). */
+  sinceDays: number;
+  /** Only tool events whose tool name contains one of these substrings. */
+  tools: readonly string[] | null;
+  /** Only failed tool calls (tool results carrying an error flag). */
+  errorsOnly: boolean;
+  /** Max sessions to return. */
+  limit: number;
+  /** Scan budget: max sessions visited. */
+  maxSessions: number;
+  /** Wall-clock ceiling in ms for the whole pass (0 = no ceiling). */
+  maxDurationMs: number;
+  /** Compressed-size ceiling per session log; larger logs are skipped (pure-JS zstd is slow). */
+  maxSessionBytes: number;
+}
+interface RawScanResult {
+  items: RecallItem[];
+  /** Sessions whose events were actually scanned. */
+  scanned: number;
+  /** The scan budget that applied. */
+  budget: number;
+  /** Sessions skipped because their log could not be decompressed or parsed. */
+  unreadable: number;
+  /** False when the scan stopped early (budget/ceiling): results cover the newest sessions only. */
+  coveredAll: boolean;
+  /** In-scope sessions skipped because their log exceeded `maxSessionBytes`. */
+  skippedOversized: number;
+  /** Session directories that existed under the root when the scan started. */
+  totalCandidates: number;
+}
+/**
+ * Scan persisted session logs directly, honoring the same scope filters as
+ * the indexed path. Never throws for per-session problems; returns what it
+ * found plus scan counters.
+ *
+ * Cost model (newest-first): the header line of every session is read
+ * through the streaming decompressor (milliseconds each); only sessions
+ * passing the scope filters are decompressed fully, and only sessions whose
+ * bytes mention every term are parsed line by line. `maxDurationMs` puts a
+ * wall-clock ceiling on the pass — when it trips, `coveredAll` is false and
+ * the caller should say so (results cover the newest sessions only).
+ */
+declare function rawScanSessions(options: RawScanOptions): Promise<RawScanResult>;
+//#endregion
 //#region src/util.d.ts
 /** Small pure helpers shared by the recall tool and its renderers. */
 /** Clamp `n` into the inclusive `[lo, hi]` range. */
@@ -274,4 +355,4 @@ declare const inject: string[];
 /** Plugin entry: mount the `recall` tool on the global tool registry. */
 declare function apply(ctx: Context, config?: RecallConfig): void;
 //#endregion
-export { ALL_PROJECTS_POLICIES, type AllProjectsPolicy, type NormalizedRecallConfig, RECALL_TOOL_DESCRIPTION, REDACTION_MODES, type RankableItem, type RankingOptions, type RecallApprovalVerdict, type RecallApprover, type RecallArgs, type RecallBestMatch, type RecallConfig, type RecallDiagnostics, type RecallItem, type RecallQueryEngine, type RecallResult, type RecallScope, type RedactionMode, apply, cjkFallbackHint, cjkZeroHitHint, clamp, createRecallTool, cwdAllowed, firstLineClipped, formatDate, hasCJK, id8, inject, name, normalizeQuery, normalizeRecallConfig, normalizeRedactionMode, rankItems, rankingActive, recallContentBlocks, recallPresentationMeta, redactText, renderRecallText, snippetAround };
+export { ALL_PROJECTS_POLICIES, type AllProjectsPolicy, type NormalizedRecallConfig, RAW_SCAN_DEFAULT_MAX_SESSIONS, RAW_SCAN_MAX_SESSIONS_MAX, RECALL_TOOL_DESCRIPTION, REDACTION_MODES, type RankableItem, type RankingOptions, type RawScanOptions, type RawScanResult, type RecallApprovalVerdict, type RecallApprover, type RecallArgs, type RecallBestMatch, type RecallConfig, type RecallDiagnostics, type RecallItem, type RecallQueryEngine, type RecallResult, type RecallScope, type RedactionMode, apply, cjkFallbackHint, cjkZeroHitHint, clamp, createRecallTool, cwdAllowed, discoverSessionsRoot, firstLineClipped, formatDate, hasCJK, id8, inject, isIndexOutage, name, normalizeQuery, normalizeRecallConfig, normalizeRedactionMode, rankItems, rankingActive, rawScanSessions, recallContentBlocks, recallPresentationMeta, redactText, renderRecallText, snippetAround };

package/lib/index.js

@@ -1,7 +1,420 @@
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import { SessionSearchCursor } from "@deepseek-ai/dsh-session-query";
 import { SessionId } from "@deepseek-ai/dsh-session";
+import { closeSync, openSync, readFileSync, readSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
 import { createHash } from "node:crypto";
+//#region src/util.ts
+/** Small pure helpers shared by the recall tool and its renderers. */
+/** Clamp `n` into the inclusive `[lo, hi]` range. */
+function clamp(n, lo, hi) {
+	return Math.min(hi, Math.max(lo, n));
+}
+/**
+* Short session slug for humans: strips the web-profile `session-` prefix and
+* keeps the first 8 characters of what remains.
+*/
+function id8(sessionId) {
+	return (sessionId.startsWith("session-") ? sessionId.slice(8) : sessionId).slice(0, 8);
+}
+/** Format Unix epoch milliseconds as a local `YYYY-MM-DD` date. */
+function formatDate(epochMs) {
+	const d = new Date(epochMs);
+	const m = String(d.getMonth() + 1).padStart(2, "0");
+	const day = String(d.getDate()).padStart(2, "0");
+	return `${d.getFullYear()}-${m}-${day}`;
+}
+const CJK_RE = /[\u{3400}-\u{4DBF}\u{4E00}-\u{9FFF}\u{F900}-\u{FAFF}\u{3040}-\u{30FF}\u{AC00}-\u{D7AF}\u{3000}-\u{303F}]/u;
+/** Whether `text` contains at least one CJK ideograph, kana, or hangul character. */
+function hasCJK(text) {
+	return CJK_RE.test(text);
+}
+/** Collapse every whitespace run and trim; used to normalize model-supplied queries. */
+function normalizeQuery(text) {
+	return text.trim().replaceAll(/\s+/g, " ");
+}
+/** Split into whitespace-separated terms, dropping empty pieces. */
+function splitTerms(text) {
+	return text.split(/\s+/u).filter((term) => term.length > 0);
+}
+/** First line of `text` with control characters stripped, clipped to `limit` code points. */
+function firstLineClipped(text, limit) {
+	const line = text.split("\n", 1)[0] ?? "";
+	let out = "";
+	for (const ch of line) {
+		if ((ch.codePointAt(0) ?? 0) < 32) continue;
+		out += ch;
+		if (out.length >= limit) break;
+	}
+	return out;
+}
+/**
+* Single-line snippet clipped around the first case-insensitive occurrence of
+* `query`, with ellipses at either end when text was cut. Falls back to a
+* head clip when the query is empty or absent.
+*/
+function snippetAround(text, query, limit) {
+	const flat = text.replaceAll(/\s+/g, " ");
+	const q = normalizeQuery(query).toLowerCase();
+	const idx = q === "" ? -1 : flat.toLowerCase().indexOf(q);
+	if (idx < 0) return flat.slice(0, limit);
+	const pad = Math.floor(limit / 3);
+	const start = Math.max(0, idx - pad);
+	const end = Math.min(flat.length, start + limit);
+	return `${start > 0 ? "…" : ""}${flat.slice(start, end)}${end < flat.length ? "…" : ""}`;
+}
+//#endregion
+//#region src/resilient.ts
+/**
+* Resilient raw-log scan: the recall tool's degraded mode.
+*
+* When the session index itself is unavailable — most notably
+* `SESSION_QUERY_PERSISTENCE_FAILED`, where one un-migratable session
+* artifact fails every indexed search (see deepseek-harness discussion
+* #7995: the v0→v1 migration gate rejects `subagent/descriptor` version 2,
+* the only version the writer emits) — recall degrades to scanning the
+* persisted session logs directly instead of failing the whole call.
+*
+* Design rules, in order:
+* 1. Never throw on a bad session: a session that cannot be decompressed or
+*    parsed is counted as unreadable and skipped. The whole point of this
+*    module is that no single artifact can take the search down.
+* 2. Scope first, scan second: the header line (cwd, createdAt) is read
+*    before the event scan, so cwd/time/session_id filters cost one line.
+* 3. Same match semantics as the indexed path: whitespace-separated terms,
+*    all must match; ASCII terms match on word boundaries, CJK terms match
+*    as substrings.
+*
+* @module dsh-session-recall/resilient
+*/
+let fzstdModule = null;
+async function getFzstd() {
+	if (fzstdModule == null) fzstdModule = await import("./esm-DyxhIKe9.js");
+	return fzstdModule;
+}
+/** Default scan budget (sessions visited per degraded call). */
+const RAW_SCAN_DEFAULT_MAX_SESSIONS = 300;
+/** Hard ceiling for the scan budget. */
+const RAW_SCAN_MAX_SESSIONS_MAX = 2e3;
+/** Characters of context around the first matched term. */
+const SNIPPET_CHARS$1 = 200;
+/** Where the harness persists sessions: `$DSH_HOME/sessions` (default `~/.dsh/sessions`). */
+function discoverSessionsRoot() {
+	const dshHome = process.env.DSH_HOME ?? join(homedir(), ".dsh");
+	return join(dshHome, "sessions");
+}
+/** True when an error means "the index is unavailable", not "the query was bad". */
+function isIndexOutage(error) {
+	return typeof error === "object" && error !== null && "code" in error && String(error.code) === "SESSION_QUERY_PERSISTENCE_FAILED";
+}
+/** Tolerant single-line JSON parse: garbage lines yield null, never throw. */
+function parseLine(line) {
+	try {
+		const value = JSON.parse(line);
+		return typeof value === "object" && value !== null ? value : null;
+	} catch {
+		return null;
+	}
+}
+/** Pull the searchable text, tool name, and error flag out of one event. */
+function eventFacts(event) {
+	const data = event["data"];
+	if (typeof data !== "object" || data === null) return null;
+	const record = data;
+	const type = typeof event["type"] === "string" ? event["type"] : "";
+	const texts = [];
+	const pushBlocks = (blocks) => {
+		if (!Array.isArray(blocks)) return;
+		for (const block of blocks) if (typeof block === "string") texts.push(block);
+		else if (typeof block === "object" && block !== null) {
+			const b = block;
+			if (typeof b["text"] === "string") texts.push(b["text"]);
+			if (Array.isArray(b["content"])) pushBlocks(b["content"]);
+		}
+	};
+	let tool = null;
+	if (type === "tool/call" && typeof record["name"] === "string") {
+		tool = record["name"];
+		if (typeof record["arguments"] === "string") texts.push(record["arguments"]);
+	}
+	const message = record["message"];
+	if (typeof message === "object" && message !== null) {
+		const m = message;
+		if (Array.isArray(m["content"])) pushBlocks(m["content"]);
+	}
+	if (Array.isArray(record["content"])) pushBlocks(record["content"]);
+	if (texts.length === 0 && typeof record["label"] === "string") texts.push(record["label"]);
+	const isError = typeof message === "object" && message !== null && (message["isError"] === true || message["is_error"] === true) || record["isError"] === true || record["is_error"] === true;
+	const text = texts.join("\n");
+	if (text === "" && tool == null) return null;
+	return {
+		text,
+		tool,
+		isError
+	};
+}
+/** All terms must match: ASCII on word boundaries, CJK as substrings. */
+function textMatches(text, terms) {
+	if (terms.length === 0) return false;
+	const haystack = text.toLowerCase();
+	for (const term of terms) {
+		const needle = term.toLowerCase();
+		if (/[\u3400-\u9fff\uf900-\ufaff\u3040-\u30ff]/.test(term)) {
+			if (!haystack.includes(needle)) return false;
+		} else {
+			const escaped = needle.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+			if (!new RegExp(`(^|[^a-z0-9_])${escaped}([^a-z0-9_]|$)`, "u").test(haystack)) return false;
+		}
+	}
+	return true;
+}
+/** List session directories under the root, newest first. */
+function listSessionDirs(root) {
+	const out = [];
+	let workspaces = [];
+	try {
+		workspaces = readdirSync(root, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+	} catch {
+		return out;
+	}
+	for (const ws of workspaces) {
+		const wsDir = join(root, ws);
+		let sessions = [];
+		try {
+			sessions = readdirSync(wsDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+		} catch {
+			continue;
+		}
+		for (const id of sessions) {
+			const dir = join(wsDir, id);
+			try {
+				out.push({
+					dir,
+					mtimeMs: statSync(dir).mtimeMs
+				});
+			} catch {}
+		}
+	}
+	out.sort((a, b) => b.mtimeMs - a.mtimeMs);
+	return out;
+}
+/** Decompress one session log fully. Plain `.jsonl` is read as-is; `.zstd` via fzstd. */
+async function readSessionLog(dir) {
+	for (const name of ["session.jsonl.zstd", "session.jsonl"]) {
+		let bytes;
+		try {
+			bytes = readFileSync(join(dir, name));
+		} catch {
+			continue;
+		}
+		if (name.endsWith(".zstd")) try {
+			const fzstd = await getFzstd();
+			return Buffer.from(fzstd.decompress(new Uint8Array(bytes)));
+		} catch {
+			return null;
+		}
+		return bytes;
+	}
+	return null;
+}
+/**
+* Read just the session header line without decompressing the whole log:
+* zstd input is pushed through the streaming decompressor in small chunks
+* and stops at the first newline. Costs milliseconds per session, which is
+* what makes scanning a whole store affordable.
+*/
+async function readSessionHeaderStreaming(dir) {
+	const fromLine = (line) => {
+		const header = parseLine(line);
+		if (header == null) return null;
+		const id = typeof header["id"] === "string" ? header["id"] : null;
+		if (id == null) return null;
+		return {
+			id,
+			createdAt: typeof header["createdAt"] === "number" ? header["createdAt"] : NaN,
+			cwd: typeof header["cwd"] === "string" ? header["cwd"] : null
+		};
+	};
+	for (const name of ["session.jsonl.zstd", "session.jsonl"]) {
+		const path = join(dir, name);
+		let fd;
+		try {
+			fd = openSync(path, "r");
+		} catch {
+			continue;
+		}
+		try {
+			const chunks = [];
+			const input = Buffer.alloc(16384);
+			let fzstd = null;
+			for (;;) {
+				let bytes;
+				try {
+					bytes = readSync(fd, input, 0, input.length, null);
+				} catch {
+					return null;
+				}
+				if (bytes <= 0) break;
+				if (name.endsWith(".zstd")) {
+					if (fzstd == null) try {
+						fzstd = await getFzstd();
+					} catch {
+						return null;
+					}
+					try {
+						new fzstd.Decompress((chunk) => {
+							chunks.push(Buffer.from(chunk));
+						}).push(input.subarray(0, bytes));
+					} catch {
+						return null;
+					}
+				} else chunks.push(Buffer.from(input.subarray(0, bytes)));
+				const soFar = Buffer.concat(chunks);
+				const nl = soFar.indexOf(10);
+				if (nl >= 0) return fromLine(soFar.subarray(0, nl).toString("utf-8"));
+				if (soFar.length > 1048576) return null;
+			}
+			return fromLine(Buffer.concat(chunks).toString("utf-8"));
+		} finally {
+			closeSync(fd);
+		}
+	}
+	return null;
+}
+/** The persisted log file of a session dir: path + compressed size, or null when none exists. */
+function sessionLogPath(dir) {
+	for (const name of ["session.jsonl.zstd", "session.jsonl"]) try {
+		const path = join(dir, name);
+		return {
+			path,
+			size: statSync(path).size
+		};
+	} catch {
+		continue;
+	}
+	return null;
+}
+/**
+* Cheap superset gate: every term must appear in the decompressed bytes
+* (exact or lowercase form) before the expensive line-by-line parse runs.
+* Word-boundary semantics are still enforced by `textMatches` later.
+*/
+function bytesMentionAllTerms(buf, terms) {
+	for (const term of terms) if (buf.indexOf(term, 0, "utf-8") < 0 && buf.indexOf(term.toLowerCase(), 0, "utf-8") < 0) return false;
+	return true;
+}
+/**
+* Scan persisted session logs directly, honoring the same scope filters as
+* the indexed path. Never throws for per-session problems; returns what it
+* found plus scan counters.
+*
+* Cost model (newest-first): the header line of every session is read
+* through the streaming decompressor (milliseconds each); only sessions
+* passing the scope filters are decompressed fully, and only sessions whose
+* bytes mention every term are parsed line by line. `maxDurationMs` puts a
+* wall-clock ceiling on the pass — when it trips, `coveredAll` is false and
+* the caller should say so (results cover the newest sessions only).
+*/
+async function rawScanSessions(options) {
+	const terms = splitTerms(options.query);
+	const sinceMs = options.sinceDays > 0 ? Date.now() - options.sinceDays * 24 * 60 * 60 * 1e3 : 0;
+	const toolsFilter = options.tools != null && options.tools.length > 0 ? options.tools.map((t) => t.toLowerCase()) : null;
+	const deadline = options.maxDurationMs > 0 ? Date.now() + options.maxDurationMs : 0;
+	const candidates = listSessionDirs(options.root);
+	const items = [];
+	let scanned = 0;
+	let unreadable = 0;
+	let skippedOversized = 0;
+	let coveredAll = true;
+	for (const candidate of candidates) {
+		if (items.length >= options.limit) break;
+		if (scanned >= options.maxSessions || deadline > 0 && Date.now() > deadline) {
+			coveredAll = false;
+			break;
+		}
+		const logInfo = sessionLogPath(candidate.dir);
+		if (logInfo == null) continue;
+		const header = await readSessionHeaderStreaming(candidate.dir);
+		if (header == null) {
+			unreadable += 1;
+			continue;
+		}
+		if (options.sessionId != null && header.id !== options.sessionId) continue;
+		if (!options.allProjects && options.cwd != null && header.cwd !== options.cwd) continue;
+		if (sinceMs > 0 && !(header.createdAt >= sinceMs)) continue;
+		if (logInfo.size > options.maxSessionBytes) {
+			skippedOversized += 1;
+			continue;
+		}
+		const log = await readSessionLog(candidate.dir);
+		if (log == null) {
+			unreadable += 1;
+			continue;
+		}
+		scanned += 1;
+		if (!bytesMentionAllTerms(log, terms)) continue;
+		const callTools = /* @__PURE__ */ new Map();
+		let best = null;
+		for (const line of log.toString("utf-8").split("\n")) {
+			if (line === "") continue;
+			const event = parseLine(line);
+			if (event == null) continue;
+			const type = typeof event["type"] === "string" ? event["type"] : "";
+			const facts = eventFacts(event);
+			if (facts == null) continue;
+			let tool = facts.tool;
+			if (tool == null && type === "tool/result") {
+				const source = event["data"]?.["message"];
+				const callId = typeof source === "object" && source !== null ? source["source"]?.["callId"] : void 0;
+				if (typeof callId === "string") tool = callTools.get(callId) ?? null;
+			} else if (tool != null) {
+				const data = event["data"];
+				const callId = typeof data?.["callId"] === "string" ? data["callId"] : null;
+				if (callId != null) callTools.set(callId, tool);
+			}
+			if (toolsFilter != null || options.errorsOnly) {
+				if (!(type === "tool/call" || type === "tool/result")) continue;
+				if (toolsFilter != null && (tool == null || !toolsFilter.some((t) => tool.toLowerCase().includes(t)))) continue;
+				if (options.errorsOnly && !(type === "tool/result" && facts.isError)) continue;
+			}
+			if (!textMatches(facts.text, terms)) continue;
+			const seq = typeof event["seq"] === "number" ? event["seq"] : 0;
+			const time = typeof event["time"] === "number" ? event["time"] : 0;
+			if (best == null || seq < best.seq) best = {
+				seq,
+				type,
+				time,
+				text: facts.text
+			};
+		}
+		if (best != null) items.push({
+			sessionId: header.id,
+			id8: id8(header.id),
+			title: null,
+			createdAt: Number.isFinite(header.createdAt) ? header.createdAt : 0,
+			cwd: header.cwd,
+			live: false,
+			persisted: true,
+			bestMatch: {
+				seq: best.seq,
+				type: best.type,
+				time: best.time,
+				snippet: snippetAround(best.text, terms[0] ?? "", SNIPPET_CHARS$1)
+			}
+		});
+	}
+	return {
+		items,
+		scanned,
+		budget: options.maxSessions,
+		unreadable,
+		skippedOversized,
+		coveredAll,
+		totalCandidates: candidates.length
+	};
+}
+//#endregion
 //#region src/redact.ts
 /**
 * Redaction for recall output text (snippets and titles).
@@ -98,7 +511,11 @@ function normalizeRecallConfig(config) {
 		allProjectsPolicy: normalizePolicy(config?.allProjectsPolicy),
 		recencyHalfLifeDays: typeof config?.recencyHalfLifeDays === "number" && Number.isFinite(config.recencyHalfLifeDays) && config.recencyHalfLifeDays > 0 ? Math.min(3650, Math.trunc(config.recencyHalfLifeDays)) : void 0,
 		pinnedCwds: stringList(config?.pinnedCwds),
-		callerTreeOnly: config?.callerTreeOnly !== false
+		callerTreeOnly: config?.callerTreeOnly !== false,
+		rawScanFallback: config?.rawScanFallback !== false,
+		rawScanMaxSessions: intIn(config?.rawScanMaxSessions, 200, 1, 2e3),
+		rawScanMaxDurationMs: intIn(config?.rawScanMaxDurationMs, 2e4, 1e3, 12e4),
+		rawScanMaxSessionBytes: intIn(config?.rawScanMaxSessionBytes, 8388608, 262144, 67108864)
 	};
 }
 /** Whether a session cwd is searchable under the allowlist/denylist policy. */
@@ -146,66 +563,6 @@ function rankItems(items, options) {
 	return decorated.map((entry) => entry.item);
 }
 //#endregion
-//#region src/util.ts
-/** Small pure helpers shared by the recall tool and its renderers. */
-/** Clamp `n` into the inclusive `[lo, hi]` range. */
-function clamp(n, lo, hi) {
-	return Math.min(hi, Math.max(lo, n));
-}
-/**
-* Short session slug for humans: strips the web-profile `session-` prefix and
-* keeps the first 8 characters of what remains.
-*/
-function id8(sessionId) {
-	return (sessionId.startsWith("session-") ? sessionId.slice(8) : sessionId).slice(0, 8);
-}
-/** Format Unix epoch milliseconds as a local `YYYY-MM-DD` date. */
-function formatDate(epochMs) {
-	const d = new Date(epochMs);
-	const m = String(d.getMonth() + 1).padStart(2, "0");
-	const day = String(d.getDate()).padStart(2, "0");
-	return `${d.getFullYear()}-${m}-${day}`;
-}
-const CJK_RE = /[\u{3400}-\u{4DBF}\u{4E00}-\u{9FFF}\u{F900}-\u{FAFF}\u{3040}-\u{30FF}\u{AC00}-\u{D7AF}\u{3000}-\u{303F}]/u;
-/** Whether `text` contains at least one CJK ideograph, kana, or hangul character. */
-function hasCJK(text) {
-	return CJK_RE.test(text);
-}
-/** Collapse every whitespace run and trim; used to normalize model-supplied queries. */
-function normalizeQuery(text) {
-	return text.trim().replaceAll(/\s+/g, " ");
-}
-/** Split into whitespace-separated terms, dropping empty pieces. */
-function splitTerms(text) {
-	return text.split(/\s+/u).filter((term) => term.length > 0);
-}
-/** First line of `text` with control characters stripped, clipped to `limit` code points. */
-function firstLineClipped(text, limit) {
-	const line = text.split("\n", 1)[0] ?? "";
-	let out = "";
-	for (const ch of line) {
-		if ((ch.codePointAt(0) ?? 0) < 32) continue;
-		out += ch;
-		if (out.length >= limit) break;
-	}
-	return out;
-}
-/**
-* Single-line snippet clipped around the first case-insensitive occurrence of
-* `query`, with ellipses at either end when text was cut. Falls back to a
-* head clip when the query is empty or absent.
-*/
-function snippetAround(text, query, limit) {
-	const flat = text.replaceAll(/\s+/g, " ");
-	const q = normalizeQuery(query).toLowerCase();
-	const idx = q === "" ? -1 : flat.toLowerCase().indexOf(q);
-	if (idx < 0) return flat.slice(0, limit);
-	const pad = Math.floor(limit / 3);
-	const start = Math.max(0, idx - pad);
-	const end = Math.min(flat.length, start + limit);
-	return `${start > 0 ? "…" : ""}${flat.slice(start, end)}${end < flat.length ? "…" : ""}`;
-}
-//#endregion
 //#region src/render.ts
 const SNIPPET_CHARS = 120;
 function sessionLabel(result, index) {
@@ -545,7 +902,8 @@ const recallOutputSchema = {
 					enum: [
 						"fts",
 						"cjk-fallback",
-						"session-scan"
+						"session-scan",
+						"raw-scan"
 					]
 				},
 				scanned: { type: "integer" },
@@ -605,7 +963,7 @@ function createRecallTool(config, engine, approver) {
 	return defineTool({
 		name: "recall",
 		description: RECALL_TOOL_DESCRIPTION,
-		timeoutMs: 1e4,
+		timeoutMs: 3e4,
 		isConcurrencySafe: () => true,
 		parameters: {
 			query: {
@@ -815,6 +1173,42 @@ function createRecallTool(config, engine, approver) {
 					diagnostics
 				};
 			} catch (error) {
+				if (cfg.rawScanFallback && isIndexOutage(error)) try {
+					const scan = await rawScanSessions({
+						root: discoverSessionsRoot(),
+						query,
+						cwd: agentCwd,
+						allProjects: wantAll,
+						sessionId: args.session_id ?? null,
+						sinceDays: args.since_days ?? 0,
+						tools: args.tools ?? null,
+						errorsOnly: args.errors_only === true,
+						limit,
+						maxSessions: cfg.rawScanMaxSessions,
+						maxDurationMs: cfg.rawScanMaxDurationMs,
+						maxSessionBytes: cfg.rawScanMaxSessionBytes
+					});
+					let scanItems = scan.items.filter((item) => cwdAllowed(item.cwd, cfg));
+					if (allowedIds != null) scanItems = scanItems.filter((item) => allowedIds.has(item.sessionId));
+					scanItems = scanItems.slice(0, limit);
+					const red = applyRedaction(scanItems);
+					return {
+						query,
+						scope,
+						count: red.items.length,
+						hasMore: false,
+						items: red.items,
+						nextCursor: null,
+						hint: joinHints(`degraded mode: the session index is unavailable (${errCode(error) ?? "persistence failure"}), so recall scanned ${scan.scanned} persisted session log(s) directly — order is by session recency, live sessions are not included${scan.unreadable > 0 ? `, ${scan.unreadable} unreadable log(s) were skipped` : ""}${scan.skippedOversized > 0 ? `, ${scan.skippedOversized} oversized log(s) beyond rawScanMaxSessionBytes were skipped` : ""}${scan.coveredAll ? "" : `, and the wall-clock budget stopped the pass after the newest ${scan.scanned} of ${scan.totalCandidates} sessions — narrow the scope (since_days, session_id) or raise rawScanMaxDurationMs to reach older history`}.`, red.hint),
+						redacted: red.redacted,
+						diagnostics: {
+							source: "raw-scan",
+							scanned: scan.scanned,
+							scanBudget: scan.budget,
+							ranked: false
+						}
+					};
+				} catch {}
 				return recallError(query, error);
 			}
 		},
@@ -872,4 +1266,4 @@ function apply(ctx, config) {
 	}, "session-recall lifecycle");
 }
 //#endregion
-export { ALL_PROJECTS_POLICIES, RECALL_TOOL_DESCRIPTION, REDACTION_MODES, apply, cjkFallbackHint, cjkZeroHitHint, clamp, createRecallTool, cwdAllowed, firstLineClipped, formatDate, hasCJK, id8, inject, name, normalizeQuery, normalizeRecallConfig, normalizeRedactionMode, rankItems, rankingActive, recallContentBlocks, recallPresentationMeta, redactText, renderRecallText, snippetAround };
+export { ALL_PROJECTS_POLICIES, RAW_SCAN_DEFAULT_MAX_SESSIONS, RAW_SCAN_MAX_SESSIONS_MAX, RECALL_TOOL_DESCRIPTION, REDACTION_MODES, apply, cjkFallbackHint, cjkZeroHitHint, clamp, createRecallTool, cwdAllowed, discoverSessionsRoot, firstLineClipped, formatDate, hasCJK, id8, inject, isIndexOutage, name, normalizeQuery, normalizeRecallConfig, normalizeRedactionMode, rankItems, rankingActive, rawScanSessions, recallContentBlocks, recallPresentationMeta, redactText, renderRecallText, snippetAround };