specrails-desktop 2.36.0 → 2.42.2

package/server/dist/code-explorer-router.js

@@ -3,9 +3,17 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.filterCodeExplorerActivityPaths = void 0;
+exports.readBoundedSource = readBoundedSource;
+exports.isDeniedRelPath = isDeniedRelPath;
+exports.gitIgnoredSet = gitIgnoredSet;
+exports.rankFindMatches = rankFindMatches;
+exports.listAllEntries = listAllEntries;
 exports.createCodeExplorerRouter = createCodeExplorerRouter;
+exports.resolveSafePath = resolveSafePath;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const node_crypto_1 = require("node:crypto");
 const child_process_1 = require("child_process");
 const express_1 = require("express");
 const feature_flags_1 = require("./feature-flags");
@@ -13,10 +21,56 @@ const build_dirs_1 = require("./build-dirs");
 const file_provenance_1 = require("./file-provenance");
 const file_summary_manager_1 = require("./file-summary-manager");
 const file_story_1 = require("./file-story");
+const project_repository_provenance_1 = require("./project-repository-provenance");
 const providers_1 = require("./providers");
+const project_repositories_1 = require("./project-repositories");
+const code_activity_1 = require("./code-activity");
 const MAX_TREE_PAGE = 2000;
+const DEFAULT_MAX_TREE_ENTRIES = 20_000;
+const DEFAULT_TREE_SCAN_MS = 5_000;
+const TREE_YIELD_EVERY = 128;
+const GIT_IGNORE_CHUNK = 1_000;
 const MAX_FILE_BYTES = 2 * 1024 * 1024;
 const BINARY_PROBE_BYTES = 8 * 1024;
+const MAX_CODE_PAGE_LINES = 500;
+const MAX_CODE_PAGE_CHARS = 20_000;
+const MAX_SEARCH_FILES = 1_000;
+const MAX_SEARCH_BYTES = 8 * 1024 * 1024;
+const MAX_SEARCH_MS = 2_000;
+/** Read a regular file through one descriptor with a hard byte ceiling, even
+ * if a writer grows it after stat. Never interpret a truncated read as text. */
+async function readBoundedSource(abs, maxBytes) {
+    const before = await fs_1.default.promises.stat(abs);
+    if (!before.isFile())
+        return 'not-file';
+    if (before.size > maxBytes)
+        return 'too-large';
+    // A FIFO swapped in between stat/open must not hang an agent request. fstat
+    // below still validates the descriptor before any bytes are read.
+    const flags = fs_1.default.constants.O_RDONLY | (process.platform === 'win32' ? 0 : fs_1.default.constants.O_NONBLOCK);
+    const handle = await fs_1.default.promises.open(abs, flags);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile())
+            return 'not-file';
+        if (stat.size > maxBytes)
+            return 'too-large';
+        const buffer = Buffer.alloc(Math.min(stat.size + 1, maxBytes + 1));
+        let offset = 0;
+        while (offset < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, offset);
+            if (!bytesRead)
+                return buffer.subarray(0, offset);
+            offset += bytesRead;
+        }
+        // Filled the extra byte: the file changed while reading. Retry a fresh
+        // snapshot instead of serving content whose completeness is unknown.
+        return 'too-large';
+    }
+    finally {
+        await handle.close();
+    }
+}
 // Hard-coded app deny-list (mirrors design D8). Dotfiles are excluded by name
 // prefix; build/dep dirs come from the shared BUILD_DIRS set (node_modules, dist,
 // build, out, coverage, target, vendor) so the on-demand tree walk skips the same
@@ -49,7 +103,7 @@ function isDenied(entryName) {
 // single source of truth across every surface (tree walk, touched-by-ai list,
 // and the content endpoints) — not just the top-level `all` walk.
 function isDeniedRelPath(rel) {
-    return rel.split(/[\\/]/).filter(Boolean).some(isDenied);
+    return rel.split(/[\\/]/).filter((segment) => segment !== '' && segment !== '.').some(isDenied);
 }
 // Normalize a client-supplied relative path to POSIX separators so summary
 // (sha256 of relPath), provenance (git always emits '/'), and content lookups
@@ -63,27 +117,77 @@ function normalizeRel(rel) {
 // paths reported, so the deny-list remains the only filter. `check-ignore` exits
 // 1 ("none ignored") which execFileSync throws on — the matched list still lands
 // on stdout, so both branches read stdout.
-function gitIgnoredSet(projectPath, relPaths) {
+async function gitIgnoredSet(projectPath, relPaths, maxDurationMs = Number.POSITIVE_INFINITY) {
     if (relPaths.length === 0)
         return new Set();
-    let out = '';
-    try {
-        out = (0, child_process_1.execFileSync)('git', ['check-ignore', '--stdin', '-z'], {
-            cwd: projectPath,
-            input: relPaths.join('\0') + '\0',
-            encoding: 'utf8',
-            stdio: ['pipe', 'pipe', 'ignore'],
-            maxBuffer: 16 * 1024 * 1024,
-            timeout: 15_000,
+    if ((0, project_repositories_1.legacyRepositoryKind)(projectPath) === 'folder')
+        return new Set();
+    const ignored = new Set();
+    const excludeUnverified = (offset) => {
+        ignored.incomplete = true;
+        for (const rel of relPaths.slice(offset))
+            ignored.add(rel);
+    };
+    const deadline = Date.now() + maxDurationMs;
+    for (let offset = 0; offset < relPaths.length; offset += GIT_IGNORE_CHUNK) {
+        if (Date.now() >= deadline) {
+            excludeUnverified(offset);
+            break;
+        }
+        const chunk = relPaths.slice(offset, offset + GIT_IGNORE_CHUNK);
+        const result = await new Promise((resolve) => {
+            let stdout = '';
+            let settled = false;
+            let overflow = false;
+            const child = (0, child_process_1.spawn)('git', ['check-ignore', '--stdin', '-z'], { cwd: projectPath, stdio: ['pipe', 'pipe', 'ignore'], env: (0, file_provenance_1.gitExecEnv)() });
+            const finish = (complete) => { if (!settled) {
+                settled = true;
+                resolve({ stdout, complete: complete && !overflow });
+            } };
+            const timer = setTimeout(() => { try {
+                child.kill('SIGTERM');
+            }
+            catch { /* gone */ } ; finish(false); }, Math.min(5_000, Math.max(1, deadline - Date.now())));
+            timer.unref?.();
+            child.stdout?.on('data', (data) => {
+                if (stdout.length < 4 * 1024 * 1024)
+                    stdout += data.toString('utf8');
+                else
+                    overflow = true;
+            });
+            child.once('error', () => { clearTimeout(timer); finish(false); });
+            child.once('close', code => { clearTimeout(timer); finish(code === 0 || code === 1); });
+            child.stdin?.on('error', () => { });
+            child.stdin?.end(chunk.join('\0') + '\0');
         });
+        if (!result.complete) {
+            excludeUnverified(offset);
+            break;
+        }
+        for (const rel of result.stdout.split('\0'))
+            if (rel)
+                ignored.add(rel);
     }
-    catch (err) {
-        out = (err.stdout ?? '').toString();
-    }
-    return new Set(out.split('\0').filter((p) => p.length > 0));
+    return ignored;
 }
-function isGitIgnored(projectPath, relPath) {
-    return gitIgnoredSet(projectPath, [relPath]).has(relPath);
+/** One policy for current source and historical metadata. Missing files remain
+ * eligible; unavailable roots or unverified ignore rules fail closed explicitly. */
+const filterCodeExplorerActivityPaths = async (repository, paths, remainingMs) => {
+    try {
+        if (!(await fs_1.default.promises.stat(repository.path)).isDirectory())
+            throw new Error('not a directory');
+    }
+    catch {
+        return { allowed: new Set(), unavailable: true };
+    }
+    const candidates = paths.filter(rel => !isDeniedRelPath(rel) && resolveSafePath(repository.path, rel) !== null);
+    const normalized = candidates.map(normalizeRel);
+    const ignored = await gitIgnoredSet(repository.path, normalized, remainingMs);
+    return { allowed: new Set(candidates.filter((_, index) => !ignored.has(normalized[index]))), incomplete: ignored.incomplete };
+};
+exports.filterCodeExplorerActivityPaths = filterCodeExplorerActivityPaths;
+async function isGitIgnored(projectPath, relPath) {
+    return (await gitIgnoredSet(projectPath, [relPath])).has(relPath);
 }
 function languageForExt(ext) {
     const e = ext.toLowerCase();
@@ -112,21 +216,25 @@ function languageForExt(ext) {
     }
 }
 function decodeCursor(raw) {
-    if (!raw)
-        return { skip: 0 };
+    if (raw === undefined)
+        return null;
+    if (typeof raw !== 'string' || raw.length > 1024)
+        throw new Error('invalid_tree_cursor');
     try {
-        const json = Buffer.from(raw, 'base64').toString('utf8');
-        const parsed = JSON.parse(json);
-        if (typeof parsed.skip === 'number' && parsed.skip >= 0)
-            return { skip: parsed.skip };
-    }
-    catch {
-        // fall through to default
+        const parsed = JSON.parse(Buffer.from(raw, 'base64url').toString('utf8'));
+        // Offset-only cursors from an older server cannot identify their original
+        // list. Ask the caller to refresh instead of silently mixing snapshots.
+        if (parsed.v === undefined && Number.isSafeInteger(parsed.skip))
+            return 'expired';
+        if (parsed.v === 2 && typeof parsed.snapshot === 'string' && /^[a-f0-9-]{36}$/.test(parsed.snapshot) &&
+            Number.isSafeInteger(parsed.skip) && parsed.skip > 0)
+            return parsed;
     }
-    return { skip: 0 };
+    catch { /* Invalid input is never treated as page zero. */ }
+    throw new Error('invalid_tree_cursor');
 }
-function encodeCursor(skip) {
-    return Buffer.from(JSON.stringify({ skip }), 'utf8').toString('base64');
+function encodeCursor(snapshot, skip) {
+    return Buffer.from(JSON.stringify({ v: 2, snapshot, skip }), 'utf8').toString('base64url');
 }
 function rollupProvenance(rows) {
     let createdByTicketId = null;
@@ -208,9 +316,10 @@ function parsePositiveInt(raw) {
 function parseNonEmptyString(raw) {
     return typeof raw === 'string' && raw.trim() !== '' ? raw.trim() : null;
 }
-function listTouchedRows(db, filters) {
-    const where = [];
-    const args = [];
+function listTouchedRows(db, filters, repository) {
+    const scope = (0, project_repository_provenance_1.provenanceRepositoryFilter)(db, repository);
+    const where = [scope.sql];
+    const args = [...scope.params];
     if (filters.ticketId != null) {
         where.push('ticket_id = ?');
         args.push(filters.ticketId);
@@ -228,19 +337,86 @@ function listTouchedRows(db, filters) {
      FROM file_provenance ${whereSql}
      ORDER BY file_path ASC, at DESC`).all(...args);
 }
-function listAllEntries(projectPath) {
+const DEFAULT_FIND_LIMIT = 20;
+const MAX_FIND_LIMIT = 50;
+const MAX_FIND_QUERY_LENGTH = 256;
+/**
+ * Rank the files of a scan against a name / path-suffix / fragment query.
+ * Case-insensitive, POSIX-normalised. Order: `exact` (whole relpath), `suffix`
+ * (the query is the tail of the relpath — the "path copied from a stack trace
+ * or import that is relative to some subdirectory" case), `basename` (same
+ * file name under another directory), `substring`; ties break on the shorter
+ * path. Directories never match — the caller wants something to read.
+ */
+function rankFindMatches(entries, query) {
+    const needle = query.trim().replace(/\\/g, '/').replace(/^(\.\/|\/)+/, '').toLowerCase();
+    if (!needle)
+        return [];
+    const needleBase = needle.slice(needle.lastIndexOf('/') + 1);
+    const order = { exact: 0, suffix: 1, basename: 2, substring: 3 };
+    const out = [];
+    for (const e of entries) {
+        if (e.isDir)
+            continue;
+        const rel = e.rel.toLowerCase();
+        const base = rel.slice(rel.lastIndexOf('/') + 1);
+        let match = null;
+        if (rel === needle)
+            match = 'exact';
+        else if (rel.endsWith(`/${needle}`))
+            match = 'suffix';
+        else if (needleBase && base === needleBase)
+            match = 'basename';
+        else if (rel.includes(needle))
+            match = 'substring';
+        if (match)
+            out.push({ rel: e.rel, size: e.size, match });
+    }
+    out.sort((a, b) => order[a.match] - order[b.match] || a.rel.length - b.rel.length || (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+    return out;
+}
+function positiveEnvInt(name, fallback) {
+    const parsed = Number.parseInt(process.env[name] ?? '', 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+async function listAllEntries(projectPath, budget) {
+    const started = Date.now();
+    const maxEntries = Math.min(positiveEnvInt('SPECRAILS_CODE_TREE_MAX_ENTRIES', DEFAULT_MAX_TREE_ENTRIES), budget?.maxEntries ?? Infinity);
+    const maxMs = Math.min(positiveEnvInt('SPECRAILS_CODE_TREE_MAX_MS', DEFAULT_TREE_SCAN_MS), budget?.maxDurationMs ?? Infinity);
     const out = [];
     const stack = [projectPath];
+    let visited = 0;
+    let reason = null;
     while (stack.length > 0) {
+        if (visited >= maxEntries) {
+            reason = 'entry-limit';
+            break;
+        }
+        if (Date.now() - started >= maxMs) {
+            reason = 'time-limit';
+            break;
+        }
         const dir = stack.pop();
         let entries;
         try {
-            entries = fs_1.default.readdirSync(dir, { withFileTypes: true });
+            entries = await fs_1.default.promises.readdir(dir, { withFileTypes: true });
         }
         catch {
+            reason ??= 'read-errors';
             continue;
         }
         for (const entry of entries) {
+            visited += 1;
+            if (visited % TREE_YIELD_EVERY === 0)
+                await new Promise((resolve) => setImmediate(resolve));
+            if (visited >= maxEntries) {
+                reason = 'entry-limit';
+                break;
+            }
+            if (Date.now() - started >= maxMs) {
+                reason = 'time-limit';
+                break;
+            }
             if (isDenied(entry.name))
                 continue;
             const abs = path_1.default.join(dir, entry.name);
@@ -255,7 +431,7 @@ function listAllEntries(projectPath) {
                 let size = null;
                 let mtime = null;
                 try {
-                    const st = fs_1.default.statSync(abs);
+                    const st = await fs_1.default.promises.stat(abs);
                     size = st.size;
                     mtime = st.mtimeMs;
                 }
@@ -270,12 +446,22 @@ function listAllEntries(projectPath) {
     // Directories are kept — git can't report an ignored dir without its files, and
     // an empty dir node is harmless; its ignored children are already filtered.
     const files = out.filter((e) => !e.isDir).map((e) => e.rel);
-    const ignored = gitIgnoredSet(projectPath, files);
+    const ignored = await gitIgnoredSet(projectPath, files, budget ? Math.max(1, maxMs - (Date.now() - started)) : Infinity);
+    if (ignored.incomplete)
+        reason ??= 'read-errors';
     const filtered = ignored.size > 0 ? out.filter((e) => e.isDir || !ignored.has(e.rel)) : out;
     filtered.sort((a, b) => a.rel.localeCompare(b.rel));
-    return filtered;
+    return {
+        entries: filtered,
+        truncated: reason !== null,
+        reason,
+        visited,
+        durationMs: Date.now() - started,
+        maxEntries,
+        maxDurationMs: maxMs,
+    };
 }
-function listTouchedEntries(projectPath, rowsByPath) {
+async function listTouchedEntries(projectPath, rowsByPath) {
     const seen = new Set();
     const out = [];
     // Drop gitignored files too — mirroring listAllEntries — so a gitignored
@@ -283,7 +469,9 @@ function listTouchedEntries(projectPath, rowsByPath) {
     // not deny-listed never surfaces its path / ticket-attribution / mtime. One
     // batched git check-ignore over the not-already-denied touched files.
     const candidateFiles = [...rowsByPath.keys()].filter((p) => !isDeniedRelPath(p));
-    const ignored = gitIgnoredSet(projectPath, candidateFiles);
+    const ignored = await gitIgnoredSet(projectPath, candidateFiles, DEFAULT_TREE_SCAN_MS);
+    if (ignored.incomplete)
+        throw new Error('tree_policy_unavailable');
     for (const filePath of rowsByPath.keys()) {
         // Keep touched-by-ai consistent with the `all` tree (and never surface
         // secrets like .env that an AI job happened to touch).
@@ -343,6 +531,27 @@ function readSummaryHashSet(projectPath) {
 }
 function createCodeExplorerRouter(deps) {
     const router = (0, express_1.Router)({ mergeParams: true });
+    const repository = deps.repositoryId ? { repositoryId: deps.repositoryId, includeLegacy: deps.includeLegacyProvenance === true } : undefined;
+    if (deps.repositoryId) {
+        router.use((_req, res, next) => {
+            const json = res.json.bind(res);
+            const identify = (item) => item && typeof item === 'object'
+                ? { ...item, repositoryId: deps.repositoryId } : item;
+            res.json = (body) => {
+                if (Array.isArray(body))
+                    return json(body.map(identify));
+                if (!body || typeof body !== 'object')
+                    return json(body);
+                const result = { ...body, repositoryId: deps.repositoryId };
+                for (const key of ['entries', 'matches', 'provenance', 'story']) {
+                    if (Array.isArray(result[key]))
+                        result[key] = result[key].map(identify);
+                }
+                return json(result);
+            };
+            next();
+        });
+    }
     const listByPath = deps.listProvenanceByPath ?? file_provenance_1.listProvenanceByPath;
     const listByTicket = deps.listProvenanceByTicket ?? file_provenance_1.listProvenanceByTicket;
     // Summary OUTPUT root (workspace when relocated). Source reads use projectPath.
@@ -359,21 +568,50 @@ function createCodeExplorerRouter(deps) {
         });
         return false;
     }
-    // Short-TTL per-project cache so paginating a large `all` tree reuses ONE
-    // synchronous filesystem walk instead of re-walking (and re-statting) on every
-    // page — the cursor only slices an already-materialized array. Also caches the
-    // one-readdir summary-hash set. 5s is long enough for a pagination burst and
-    // short enough that tree edits surface promptly.
+    // Short-lived discovery cache deduplicates initial tree/find/search scans.
+    // Separate bounded path snapshots keep tree pagination stable after this
+    // cache expires. Provenance and summaries are enriched per page, not retained
+    // as unbounded copies inside every snapshot.
     const WALK_CACHE_TTL_MS = 5000;
-    let allEntriesCache = null;
+    const allEntriesCache = new Map();
+    const allEntriesInFlight = new Map();
+    const TREE_SNAPSHOT_TTL_MS = 120_000;
+    const MAX_TREE_SNAPSHOTS = 4;
+    const treeSnapshots = new Map();
+    let watcherScheduled = false;
     let summaryHashCache = null;
     const nowMs = () => Date.now();
-    function getAllEntriesCached() {
-        if (allEntriesCache && nowMs() - allEntriesCache.at < WALK_CACHE_TTL_MS)
-            return allEntriesCache.entries;
-        const entries = listAllEntries(deps.projectPath);
-        allEntriesCache = { at: nowMs(), entries };
-        return entries;
+    async function getAllEntriesCached(relativeRoot = '') {
+        const cached = allEntriesCache.get(relativeRoot);
+        if (cached && nowMs() - cached.at < WALK_CACHE_TTL_MS) {
+            return { scan: cached.scan, cache: 'hit' };
+        }
+        const existing = allEntriesInFlight.get(relativeRoot);
+        if (existing)
+            return { scan: await existing, cache: 'shared' };
+        const pending = listAllEntries(relativeRoot ? path_1.default.join(deps.projectPath, relativeRoot) : deps.projectPath).then((scan) => relativeRoot
+            ? { ...scan, entries: scan.entries.map((entry) => ({ ...entry, rel: `${relativeRoot}/${entry.rel}` })) }
+            : scan);
+        allEntriesInFlight.set(relativeRoot, pending);
+        try {
+            const scan = await pending;
+            // Bound retained trees when an agent searches many different subfolders.
+            if (allEntriesCache.size >= 4 && !allEntriesCache.has(relativeRoot))
+                allEntriesCache.delete(allEntriesCache.keys().next().value);
+            allEntriesCache.set(relativeRoot, { at: nowMs(), scan });
+            console.info('[code-explorer] tree scan', JSON.stringify({
+                projectId: deps.projectId,
+                durationMs: scan.durationMs,
+                visited: scan.visited,
+                returned: scan.entries.length,
+                truncated: scan.truncated,
+                reason: scan.reason,
+            }));
+            return { scan, cache: 'miss' };
+        }
+        finally {
+            allEntriesInFlight.delete(relativeRoot);
+        }
     }
     function getSummaryHashesCached() {
         if (summaryHashCache && nowMs() - summaryHashCache.at < WALK_CACHE_TTL_MS)
@@ -392,24 +630,70 @@ function createCodeExplorerRouter(deps) {
         // provider without a native pure-output boundary must not attach it:
         // implicit file-change work and explicit POSTs both fail closed before a
         // manager or provider process can run.
-        if (aiTransformsAvailable) {
-            try {
-                deps.fileSummaryManager.attachWatcher(deps.projectId, deps.projectPath, summaryRoot());
-            }
-            catch { /* non-fatal */ }
+        if (aiTransformsAvailable && !watcherScheduled) {
+            watcherScheduled = true;
+            setImmediate(() => {
+                try {
+                    deps.fileSummaryManager.attachWatcher(deps.projectId, deps.projectPath, summaryRoot(), deps.repositoryId);
+                }
+                catch (err) {
+                    console.warn('[code-explorer] watcher startup failed', JSON.stringify({
+                        projectId: deps.projectId,
+                        error: err instanceof Error ? err.message : String(err),
+                    }));
+                }
+            });
         }
         next();
     });
-    router.get('/tree', (req, res) => {
+    router.get('/tree', async (req, res) => {
         const filter = req.query.filter ?? 'touched-by-ai';
+        if (filter !== 'all' && filter !== 'touched-by-ai') {
+            res.status(400).json({ error: 'invalid_tree_filter' });
+            return;
+        }
         const withProvenance = req.query.withProvenance === '1' || req.query.withProvenance === 'true';
-        const { skip } = decodeCursor(req.query.cursor);
+        const requestedLimit = parsePositiveInt(req.query.limit);
+        const pageLimit = Math.min(requestedLimit ?? MAX_TREE_PAGE, MAX_TREE_PAGE);
         const ticketId = parsePositiveInt(req.query.ticketId);
         const jobId = parseNonEmptyString(req.query.jobId);
-        let entries;
+        if ((req.query.ticketId !== undefined && ticketId === null) || (req.query.jobId !== undefined && jobId === null)) {
+            res.status(400).json({ error: 'invalid_tree_scope' });
+            return;
+        }
+        const scope = JSON.stringify([deps.projectId, deps.repositoryId, deps.projectPath, filter, withProvenance,
+            filter === 'touched-by-ai' ? ticketId : null, filter === 'touched-by-ai' ? jobId : null]);
+        let cursor;
+        try {
+            cursor = decodeCursor(req.query.cursor);
+        }
+        catch {
+            res.status(400).json({ error: 'invalid_tree_cursor' });
+            return;
+        }
+        for (const [id, snapshot] of treeSnapshots) {
+            if (nowMs() - snapshot.createdAt >= TREE_SNAPSHOT_TTL_MS)
+                treeSnapshots.delete(id);
+        }
+        let snapshot = cursor && cursor !== 'expired' ? treeSnapshots.get(cursor.snapshot) : undefined;
+        if (cursor && (cursor === 'expired' || !snapshot)) {
+            res.status(409).json({ error: 'tree_snapshot_expired', retryable: true });
+            return;
+        }
+        if (snapshot && snapshot.scope !== scope) {
+            res.status(400).json({ error: 'tree_cursor_scope_mismatch' });
+            return;
+        }
+        const skip = cursor ? cursor.skip : 0;
+        if (snapshot && skip >= snapshot.entries.length) {
+            res.status(400).json({ error: 'invalid_tree_cursor' });
+            return;
+        }
         const touchedRowsByPath = new Map();
-        if (filter === 'touched-by-ai') {
-            const rows = listTouchedRows(deps.db, { ticketId, jobId });
+        // Initial touched discovery needs the complete filtered file set. Later
+        // pages re-enrich the frozen paths without recomputing their positions.
+        if ((filter === 'touched-by-ai' && !snapshot) || withProvenance) {
+            const rows = listTouchedRows(deps.db, filter === 'touched-by-ai' ? { ticketId, jobId } : {}, repository);
             for (const row of rows) {
                 const existing = touchedRowsByPath.get(row.file_path);
                 if (existing)
@@ -417,47 +701,250 @@ function createCodeExplorerRouter(deps) {
                 else
                     touchedRowsByPath.set(row.file_path, [row]);
             }
-            entries = listTouchedEntries(deps.projectPath, touchedRowsByPath);
-        }
-        else {
-            entries = getAllEntriesCached();
-            // Batch-load ALL provenance once instead of a per-entry SQL query (N+1).
-            if (withProvenance) {
-                for (const row of listTouchedRows(deps.db, {})) {
-                    const existing = touchedRowsByPath.get(row.file_path);
-                    if (existing)
-                        existing.push(row);
-                    else
-                        touchedRowsByPath.set(row.file_path, [row]);
+        }
+        let cache = snapshot ? 'snapshot' : null;
+        if (!snapshot) {
+            let entries;
+            let scanMeta = null;
+            if (filter === 'touched-by-ai') {
+                try {
+                    entries = await listTouchedEntries(deps.projectPath, touchedRowsByPath);
                 }
+                catch {
+                    res.status(503).json({ error: 'tree_policy_unavailable', retryable: true });
+                    return;
+                }
+                if (entries.length > DEFAULT_MAX_TREE_ENTRIES) {
+                    scanMeta = { truncated: true, reason: 'entry-limit', visited: entries.length, durationMs: 0,
+                        maxEntries: DEFAULT_MAX_TREE_ENTRIES, maxDurationMs: DEFAULT_TREE_SCAN_MS };
+                }
+            }
+            else {
+                const result = await getAllEntriesCached();
+                entries = result.scan.entries;
+                cache = result.cache;
+                const { entries: _entries, ...metadata } = result.scan;
+                scanMeta = metadata;
+                if (entries.length > DEFAULT_MAX_TREE_ENTRIES) {
+                    scanMeta = { ...metadata, truncated: true, reason: 'entry-limit', maxEntries: DEFAULT_MAX_TREE_ENTRIES };
+                }
+            }
+            snapshot = { id: (0, node_crypto_1.randomUUID)(), scope, createdAt: nowMs(), entries: entries.slice(0, DEFAULT_MAX_TREE_ENTRIES), scanMeta };
+            if (snapshot.entries.length > pageLimit) {
+                while (treeSnapshots.size >= MAX_TREE_SNAPSHOTS)
+                    treeSnapshots.delete(treeSnapshots.keys().next().value);
+                treeSnapshots.set(snapshot.id, snapshot);
             }
         }
-        const page = entries.slice(skip, skip + MAX_TREE_PAGE);
-        const nextCursor = skip + page.length < entries.length ? encodeCursor(skip + page.length) : null;
-        // Read the summaries dir ONCE into a Set of path-hashes instead of opening +
-        // parsing a JSON file per entry just to test existence (cached per project).
+        const candidates = snapshot.entries.slice(skip, skip + pageLimit);
+        const nextCursor = skip + candidates.length < snapshot.entries.length ? encodeCursor(snapshot.id, skip + candidates.length) : null;
+        // The cursor preserves position, never access: recheck current exclusions
+        // and symlink boundaries. Directory badges must not leak excluded child
+        // provenance through their aggregate rows either.
+        const policyPaths = new Set(candidates.map(entry => entry.rel));
+        if (withProvenance && filter === 'touched-by-ai') {
+            const directories = new Set(candidates.filter(entry => entry.isDir).map(entry => entry.rel));
+            for (const entry of snapshot.entries) {
+                if (entry.isDir)
+                    continue;
+                const parts = entry.rel.split('/');
+                while (parts.length > 1) {
+                    parts.pop();
+                    if (directories.has(parts.join('/'))) {
+                        policyPaths.add(entry.rel);
+                        break;
+                    }
+                }
+            }
+        }
+        const visibility = await (0, exports.filterCodeExplorerActivityPaths)({
+            id: deps.repositoryId ?? `primary-${deps.projectId}`, projectId: deps.projectId,
+            name: deps.repositoryName ?? path_1.default.basename(deps.projectPath), path: deps.projectPath,
+            isPrimary: deps.includeLegacyProvenance !== false, kind: (0, project_repositories_1.legacyRepositoryKind)(deps.projectPath), integrationBranch: null, addedAt: '',
+        }, [...policyPaths], DEFAULT_TREE_SCAN_MS);
+        if (visibility.unavailable || visibility.incomplete) {
+            res.status(503).json({ error: 'tree_policy_unavailable', retryable: true });
+            return;
+        }
+        for (const filePath of touchedRowsByPath.keys()) {
+            if (!visibility.allowed.has(filePath))
+                touchedRowsByPath.delete(filePath);
+        }
         const summaryHashes = getSummaryHashesCached();
-        const out = page.map((e) => {
+        const out = candidates.filter(entry => visibility.allowed.has(entry.rel)).map((e) => {
             const isTouchedDir = filter === 'touched-by-ai' && e.isDir;
             const rawRows = withProvenance && !isTouchedDir ? (touchedRowsByPath.get(e.rel) ?? []) : [];
             const provenance = withProvenance && isTouchedDir
                 ? rollupDirectoryProvenance(touchedRowsByPath, e.rel)
                 : rollupProvenance(rawRows);
-            return {
-                path: e.rel,
-                kind: e.isDir ? 'dir' : 'file',
-                sizeBytes: e.size,
-                hasSummary: !e.isDir && summaryHashes.has((0, file_summary_manager_1.pathHash)(e.rel)),
-                provenance,
-                lastModifiedAt: e.mtime,
-            };
+            return { path: e.rel, kind: e.isDir ? 'dir' : 'file', sizeBytes: e.size,
+                hasSummary: !e.isDir && summaryHashes.has((0, file_summary_manager_1.pathHash)(e.rel)), provenance, lastModifiedAt: e.mtime };
+        });
+        const scanMeta = snapshot.scanMeta;
+        res.json({
+            entries: out.map(entry => ({ ...entry, provenance: treeProvenanceToJson(entry.provenance) })), nextCursor,
+            ...(scanMeta ? {
+                truncated: scanMeta.truncated, truncationReason: scanMeta.reason,
+                scan: { visited: scanMeta.visited, durationMs: scanMeta.durationMs, maxEntries: scanMeta.maxEntries,
+                    maxDurationMs: scanMeta.maxDurationMs, retryable: scanMeta.truncated, cache },
+            } : {}),
         });
+    });
+    /**
+     * Locate files by name / path-suffix / fragment across the whole scanned tree
+     * (same deny-list + .gitignore rules as `/tree?filter=all`, same cached scan).
+     * The escape hatch for a caller holding a path that is relative to some
+     * subdirectory (a stack trace, an import): `/file` 404s, `/find` says where
+     * the file actually lives.
+     */
+    router.get('/find', async (req, res) => {
+        const q = parseNonEmptyString(req.query.q);
+        if (!q) {
+            res.status(400).json({ error: 'q is required' });
+            return;
+        }
+        if (q.length > MAX_FIND_QUERY_LENGTH) {
+            res.status(400).json({ error: `q must be at most ${MAX_FIND_QUERY_LENGTH} characters` });
+            return;
+        }
+        const limit = Math.min(parsePositiveInt(req.query.limit) ?? DEFAULT_FIND_LIMIT, MAX_FIND_LIMIT);
+        const { scan } = await getAllEntriesCached();
+        const ranked = rankFindMatches(scan.entries, q);
+        res.json({
+            query: q,
+            matches: ranked.slice(0, limit).map((m) => ({ path: m.rel, sizeBytes: m.size, match: m.match })),
+            total: ranked.length,
+            truncated: scan.truncated || ranked.length > limit,
+            truncationReason: scan.reason ?? (ranked.length > limit ? 'match-limit' : null),
+        });
+    });
+    router.get('/search', async (req, res) => {
+        const query = typeof req.query.q === 'string' ? req.query.q : '';
+        if (!query.trim() || query.length > 256 || /[\r\n]/.test(query)) {
+            res.status(400).json({ error: 'q must be a non-empty literal single-line query of at most 256 characters' });
+            return;
+        }
+        const selectedPath = parseNonEmptyString(req.query.path);
+        const rawPath = selectedPath === '.' || selectedPath === './' ? null : selectedPath;
+        if (rawPath && !resolveSafePath(deps.projectPath, rawPath)) {
+            res.status(400).json({ error: 'path traversal not allowed' });
+            return;
+        }
+        if (rawPath && isDeniedRelPath(rawPath)) {
+            res.status(403).json({ error: 'path is excluded by the code-explorer deny-list' });
+            return;
+        }
+        const prefix = rawPath ? normalizeRel(rawPath).replace(/^\.\//, '') : '';
+        const caseSensitive = req.query.caseSensitive === 'true' || req.query.caseSensitive === '1';
+        const needle = caseSensitive ? query : query.toLowerCase();
+        const limit = Math.min(parsePositiveInt(req.query.limit) ?? 30, 100);
+        let scan;
+        if (prefix) {
+            // Narrowing must narrow the walk itself. Filtering an already truncated
+            // full-tree cache would make later subfolders impossible to discover.
+            try {
+                const stat = await fs_1.default.promises.stat(path_1.default.join(deps.projectPath, prefix));
+                if (stat.isDirectory())
+                    scan = (await getAllEntriesCached(prefix)).scan;
+                else if (stat.isFile())
+                    scan = { entries: [{ rel: prefix, isDir: false, size: stat.size, mtime: stat.mtimeMs }], truncated: false, reason: null, visited: 1, durationMs: 0, maxEntries: 1, maxDurationMs: DEFAULT_TREE_SCAN_MS };
+                else {
+                    res.status(400).json({ error: 'search path is not a regular file or directory' });
+                    return;
+                }
+            }
+            catch (err) {
+                res.status(err.code === 'ENOENT' ? 404 : 500).json({ error: 'search path is unavailable' });
+                return;
+            }
+        }
+        else
+            scan = (await getAllEntriesCached()).scan;
+        const candidates = scan.entries.filter((entry) => !entry.isDir && (!prefix || entry.rel === prefix || entry.rel.startsWith(`${prefix}/`)));
+        const maxFiles = Math.min(positiveEnvInt('SPECRAILS_CODE_SEARCH_MAX_FILES', MAX_SEARCH_FILES), MAX_SEARCH_FILES);
+        const maxBytes = Math.min(positiveEnvInt('SPECRAILS_CODE_SEARCH_MAX_BYTES', MAX_SEARCH_BYTES), MAX_SEARCH_BYTES);
+        const maxMs = Math.min(positiveEnvInt('SPECRAILS_CODE_SEARCH_MAX_MS', MAX_SEARCH_MS), MAX_SEARCH_MS);
+        const started = Date.now();
+        const matches = [];
+        const reasons = new Set(scan.reason ? [`tree-${scan.reason}`] : []);
+        const skipped = { binary: 0, tooLarge: 0, unreadable: 0, excluded: 0 };
+        let scannedFiles = 0;
+        let bytesRead = 0;
+        // The tree is cached. Revalidate ignore rules for this request so adding a
+        // .gitignore cannot leak newly excluded content during the cache TTL.
+        const ignored = await gitIgnoredSet(deps.projectPath, candidates.slice(0, maxFiles).map((entry) => entry.rel), maxMs);
+        if (ignored.incomplete)
+            reasons.add('ignore-rules-unavailable');
+        search: for (const entry of candidates) {
+            if (Date.now() - started >= maxMs) {
+                reasons.add('time-limit');
+                break;
+            }
+            if (scannedFiles >= maxFiles) {
+                reasons.add('file-limit');
+                break;
+            }
+            if (bytesRead >= maxBytes) {
+                reasons.add('byte-limit');
+                break;
+            }
+            scannedFiles++;
+            const abs = resolveSafePath(deps.projectPath, entry.rel);
+            if (!abs || isDeniedRelPath(entry.rel) || ignored.has(entry.rel)) {
+                skipped.excluded++;
+                continue;
+            }
+            try {
+                const data = await readBoundedSource(abs, Math.min(MAX_FILE_BYTES, maxBytes - bytesRead));
+                if (data === 'too-large') {
+                    skipped.tooLarge++;
+                    reasons.add('oversized-or-changing-files');
+                    continue;
+                }
+                if (data === 'not-file') {
+                    skipped.unreadable++;
+                    reasons.add('unreadable-files');
+                    continue;
+                }
+                bytesRead += data.length;
+                if (data.includes(0)) {
+                    skipped.binary++;
+                    continue;
+                }
+                const lines = data.toString('utf8').split('\n');
+                let hash = null;
+                for (let index = 0; index < lines.length; index++) {
+                    if (index % 128 === 0 && Date.now() - started >= maxMs) {
+                        reasons.add('time-limit');
+                        break search;
+                    }
+                    const line = lines[index].replace(/\r$/, '');
+                    const position = (caseSensitive ? line : line.toLowerCase()).indexOf(needle);
+                    if (position < 0)
+                        continue;
+                    if (matches.length >= limit) {
+                        reasons.add('match-limit');
+                        break search;
+                    }
+                    const from = Math.max(0, position - 80);
+                    const to = Math.min(line.length, from + 320);
+                    hash ??= (0, node_crypto_1.createHash)('sha256').update(data).digest('hex');
+                    matches.push({ path: entry.rel, lineNumber: index + 1, column: position + 1, snippet: line.slice(from, to), snippetTruncated: from > 0 || to < line.length, fileHash: hash });
+                }
+            }
+            catch {
+                skipped.unreadable++;
+                reasons.add('unreadable-files');
+            }
+        }
+        const truncated = reasons.size > 0;
         res.json({
-            entries: out.map((entry) => ({
-                ...entry,
-                provenance: treeProvenanceToJson(entry.provenance),
-            })),
-            nextCursor,
+            query, path: prefix || null, caseSensitive, matches, truncated,
+            truncationReasons: [...reasons],
+            scan: { candidateFiles: candidates.length, scannedFiles, bytesRead, durationMs: Date.now() - started, maxFiles, maxBytes, maxDurationMs: maxMs, skipped, treeTruncated: scan.truncated },
+            hint: truncated
+                ? 'Partial search: absence of a match is not proof of absence. Narrow path/query and retry; use read_file at a returned line with its fileHash as expectedHash.'
+                : 'Search complete for eligible text files; binary, denied and gitignored paths are excluded. Use read_file at a matching line.',
         });
     });
     router.get('/file', async (req, res) => {
@@ -477,11 +964,88 @@ function createCodeExplorerRouter(deps) {
         }
         // Canonical POSIX form for all summary/provenance/hash lookups.
         const rel = normalizeRel(relRaw);
-        if (isGitIgnored(deps.projectPath, rel)) {
+        if (await isGitIgnored(deps.projectPath, rel)) {
             res.status(403).json({ error: 'path is gitignored' });
             return;
         }
         const abs = guard;
+        // The editor keeps its existing full-preview contract. MCP callers always
+        // supply a range, which avoids spending a model context on a 2 MB response.
+        const ranged = req.query.startLine !== undefined || req.query.endLine !== undefined || req.query.startColumn !== undefined;
+        if (ranged) {
+            const startLine = req.query.startLine === undefined ? 1 : parsePositiveInt(req.query.startLine);
+            const endLine = req.query.endLine === undefined && startLine !== null ? startLine + 199 : parsePositiveInt(req.query.endLine);
+            const startColumn = req.query.startColumn === undefined ? 1 : parsePositiveInt(req.query.startColumn);
+            if (startLine === null || endLine === null || startColumn === null || endLine < startLine) {
+                res.status(400).json({ error: 'invalid line range; startLine/endLine/startColumn must be positive integers' });
+                return;
+            }
+            const expectedHash = parseNonEmptyString(req.query.expectedHash);
+            if (expectedHash && !/^[a-f0-9]{64}$/i.test(expectedHash)) {
+                res.status(400).json({ error: 'expectedHash must be a SHA-256 file hash' });
+                return;
+            }
+            let bytes;
+            try {
+                bytes = await readBoundedSource(abs, MAX_FILE_BYTES);
+            }
+            catch (err) {
+                res.status(err.code === 'ENOENT' ? 404 : 500).json({ error: err.code === 'ENOENT' ? 'file not found' : 'failed to read file' });
+                return;
+            }
+            if (bytes === 'too-large') {
+                res.status(413).json({ error: 'file exceeds the 2 MB read limit or changed while reading; use a narrower code search' });
+                return;
+            }
+            if (bytes === 'not-file') {
+                res.status(400).json({ error: 'path is not a regular file' });
+                return;
+            }
+            if (bytes.includes(0)) {
+                res.status(415).json({ error: 'binary file is not readable as source text' });
+                return;
+            }
+            const fileHash = (0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex');
+            if (expectedHash && expectedHash.toLowerCase() !== fileHash) {
+                res.status(409).json({ error: 'file_changed', fileHash, detail: 'The file changed since the previous page/search. Restart the read using the current hash.' });
+                return;
+            }
+            const lines = bytes.toString('utf8').split('\n');
+            if (startLine > lines.length || startColumn > lines[startLine - 1].length + 1) {
+                res.status(416).json({ error: 'range_out_of_bounds', totalLines: lines.length, fileHash });
+                return;
+            }
+            const lastLine = Math.min(endLine, startLine + MAX_CODE_PAGE_LINES - 1, lines.length);
+            let content = '';
+            let actualEndLine = startLine;
+            let nextLine = lastLine < lines.length ? lastLine + 1 : null;
+            let nextColumn = nextLine === null ? null : 1;
+            let reason = nextLine === null ? null : 'line-limit';
+            for (let lineNumber = startLine; lineNumber <= lastLine; lineNumber++) {
+                const column = lineNumber === startLine ? startColumn : 1;
+                const line = lines[lineNumber - 1].slice(column - 1);
+                const remaining = MAX_CODE_PAGE_CHARS - content.length;
+                actualEndLine = lineNumber;
+                if (line.length > remaining) {
+                    content += line.slice(0, remaining);
+                    nextLine = lineNumber;
+                    nextColumn = column + remaining;
+                    reason = 'character-limit';
+                    break;
+                }
+                content += line;
+                if (content.length >= MAX_CODE_PAGE_CHARS && lineNumber < lastLine) {
+                    nextLine = lineNumber + 1;
+                    nextColumn = 1;
+                    reason = 'character-limit';
+                    break;
+                }
+                if (lineNumber < lastLine)
+                    content += '\n';
+            }
+            res.json({ path: rel, content, encoding: 'utf-8', language: languageForExt(path_1.default.extname(rel)), fileHash, sizeBytes: bytes.length, startLine, startColumn, endLine: actualEndLine, totalLines: lines.length, nextLine, nextColumn, truncated: nextLine !== null, truncationReason: reason });
+            return;
+        }
         let stat;
         try {
             stat = fs_1.default.statSync(abs);
@@ -490,7 +1054,7 @@ function createCodeExplorerRouter(deps) {
             // Honour the staleness scenario: even if content is unavailable, return
             // the existing summary so the client can render a "not found" banner.
             const summary = (0, file_summary_manager_1.readSummary)(summaryRoot(), rel);
-            const provenance = listByPath(deps.db, deps.projectId, rel);
+            const provenance = listByPath(deps.db, deps.projectId, rel, repository);
             if (summary || provenance.length > 0) {
                 res.json({
                     content: null,
@@ -512,7 +1076,7 @@ function createCodeExplorerRouter(deps) {
             res.json({
                 tooLarge: true,
                 sizeBytes: stat.size,
-                provenance: provenanceRowsToJson(listByPath(deps.db, deps.projectId, rel)),
+                provenance: provenanceRowsToJson(listByPath(deps.db, deps.projectId, rel, repository)),
                 summary: (0, file_summary_manager_1.readSummary)(summaryRoot(), rel),
                 absolutePath: abs,
             });
@@ -539,7 +1103,7 @@ function createCodeExplorerRouter(deps) {
                 binary: true,
                 sizeBytes: stat.size,
                 mime: 'application/octet-stream',
-                provenance: provenanceRowsToJson(listByPath(deps.db, deps.projectId, rel)),
+                provenance: provenanceRowsToJson(listByPath(deps.db, deps.projectId, rel, repository)),
                 summary: (0, file_summary_manager_1.readSummary)(summaryRoot(), rel),
                 absolutePath: abs,
             });
@@ -554,12 +1118,12 @@ function createCodeExplorerRouter(deps) {
             return;
         }
         const summary = (0, file_summary_manager_1.readSummary)(summaryRoot(), rel);
-        const summaryStale = await computeStaleness(abs, summary);
+        const summaryStale = await computeStaleness(abs, summary, deps.fileSummaryManager.getLanguage?.() ?? 'en');
         res.json({
             content,
             encoding: 'utf-8',
             language: languageForExt(path_1.default.extname(rel)),
-            provenance: provenanceRowsToJson(listByPath(deps.db, deps.projectId, rel)),
+            provenance: provenanceRowsToJson(listByPath(deps.db, deps.projectId, rel, repository)),
             summary,
             summaryStale,
             absolutePath: abs,
@@ -572,7 +1136,7 @@ function createCodeExplorerRouter(deps) {
     // scope here. After a write the existing hash-gated `summaryStale` flag makes
     // the next GET /file surface the summary as stale (regenerate via the existing
     // POST /file/regenerate-summary).
-    router.put('/file', (req, res) => {
+    router.put('/file', async (req, res) => {
         const body = (req.body ?? {});
         const relRaw = typeof body.path === 'string' ? body.path : undefined;
         const content = typeof body.content === 'string' ? body.content : undefined;
@@ -590,7 +1154,7 @@ function createCodeExplorerRouter(deps) {
             return;
         }
         const rel = normalizeRel(relRaw);
-        if (isGitIgnored(deps.projectPath, rel)) {
+        if (await isGitIgnored(deps.projectPath, rel)) {
             res.status(403).json({ error: 'path is gitignored' });
             return;
         }
@@ -659,7 +1223,7 @@ function createCodeExplorerRouter(deps) {
             return;
         }
         const rel = normalizeRel(relRaw);
-        if (isGitIgnored(deps.projectPath, rel)) {
+        if (await isGitIgnored(deps.projectPath, rel)) {
             res.status(403).json({ error: 'path is gitignored' });
             return;
         }
@@ -670,7 +1234,7 @@ function createCodeExplorerRouter(deps) {
         }
         let summaryStale = false;
         try {
-            summaryStale = await computeStaleness(guard, summary);
+            summaryStale = await computeStaleness(guard, summary, deps.fileSummaryManager.getLanguage?.() ?? 'en');
         }
         catch {
             summaryStale = true;
@@ -682,7 +1246,7 @@ function createCodeExplorerRouter(deps) {
     // contribution paragraph when generated, and the spec's live title/status.
     // Same guards as every sibling content endpoint. Works for deleted files too
     // (their story is still worth telling), so no stat/existence requirement.
-    router.get('/file/story', (req, res) => {
+    router.get('/file/story', async (req, res) => {
         const relRaw = req.query.path;
         if (!relRaw || typeof relRaw !== 'string') {
             res.status(400).json({ error: 'path query parameter is required' });
@@ -698,11 +1262,11 @@ function createCodeExplorerRouter(deps) {
             return;
         }
         const rel = normalizeRel(relRaw);
-        if (isGitIgnored(deps.projectPath, rel)) {
+        if (await isGitIgnored(deps.projectPath, rel)) {
             res.status(403).json({ error: 'path is gitignored' });
             return;
         }
-        res.json({ path: rel, story: (0, file_story_1.getFileStory)(deps.db, rel, deps.getTicketSpec) });
+        res.json({ path: rel, story: (0, file_story_1.getFileStory)(deps.db, rel, deps.getTicketSpec, repository, deps.fileStoryManager?.getLanguage?.()) });
     });
     // Construction story: generate (budget-gated) the plain-language "what this
     // spec contributed" paragraph for ONE intervention. Awaits the single model
@@ -726,7 +1290,7 @@ function createCodeExplorerRouter(deps) {
             return;
         }
         const rel = normalizeRel(relRaw);
-        if (isGitIgnored(deps.projectPath, rel)) {
+        if (await isGitIgnored(deps.projectPath, rel)) {
             res.status(403).json({ error: 'path is gitignored' });
             return;
         }
@@ -745,8 +1309,10 @@ function createCodeExplorerRouter(deps) {
         try {
             const result = await deps.fileStoryManager.explain({
                 projectId: deps.projectId,
+                ...(repository ? { repository } : {}),
                 relPath: rel,
                 provenanceId,
+                force: body.force === true,
                 overrideBudget: body.overrideBudget === true,
             });
             if (result === 'generated') {
@@ -759,6 +1325,14 @@ function createCodeExplorerRouter(deps) {
                 res.status(200).json({ skipped: 'budget' });
                 return;
             }
+            if (result === 'skipped:hash') {
+                res.json({ ok: true, reused: true });
+                return;
+            }
+            if (result === 'skipped:no-evidence' || result === 'skipped:ttl') {
+                res.json({ skipped: result.slice('skipped:'.length) });
+                return;
+            }
             if (result === 'skipped:not-found') {
                 res.status(404).json({ error: 'intervention not found for this file' });
                 return;
@@ -788,7 +1362,7 @@ function createCodeExplorerRouter(deps) {
             return;
         }
         const rel = normalizeRel(relRaw);
-        if (isGitIgnored(deps.projectPath, rel)) {
+        if (await isGitIgnored(deps.projectPath, rel)) {
             res.status(403).json({ error: 'path is gitignored' });
             return;
         }
@@ -835,6 +1409,7 @@ function createCodeExplorerRouter(deps) {
                 summaryRoot: summaryRoot(),
                 projectId: deps.projectId,
                 projectSlug: deps.projectId,
+                ...(deps.repositoryId ? { repositoryId: deps.repositoryId } : {}),
                 relPath: rel,
                 triggeredBy: { kind: 'user', id: 'manual', ticketId: null },
                 overrideBudget: body.overrideBudget === true,
@@ -873,7 +1448,21 @@ function createCodeExplorerRouter(deps) {
             res.status(500).json({ error: 'enqueue failed', message: err.message });
         }
     });
-    router.get('/provenance', (req, res) => {
+    router.get('/activity', async (req, res) => {
+        const id = deps.repositoryId ?? `primary-${deps.projectId}`;
+        try {
+            res.json(await (0, code_activity_1.listCodeActivity)(deps.db, {
+                id: deps.projectId, path: deps.projectPath,
+                repositories: [{ id, projectId: deps.projectId, name: deps.repositoryName ?? path_1.default.basename(deps.projectPath),
+                        path: deps.projectPath, isPrimary: deps.repositoryId ? deps.includeLegacyProvenance === true : true,
+                        kind: (0, project_repositories_1.legacyRepositoryKind)(deps.projectPath), integrationBranch: null, addedAt: '' }],
+            }, (0, code_activity_1.parseCodeActivityQuery)(req.query, id), exports.filterCodeExplorerActivityPaths));
+        }
+        catch (err) {
+            res.status(err instanceof code_activity_1.CodeActivityQueryError ? err.status : 500).json({ error: err instanceof code_activity_1.CodeActivityQueryError ? err.message : 'activity_unavailable' });
+        }
+    });
+    router.get('/provenance', async (req, res) => {
         const ticketId = parsePositiveInt(req.query.ticketId);
         const jobId = parseNonEmptyString(req.query.jobId);
         const relPath = parseNonEmptyString(req.query.path);
@@ -899,11 +1488,20 @@ function createCodeExplorerRouter(deps) {
             return;
         }
         const rows = ticketId != null && !jobId && !relPath
-            ? listByTicket(deps.db, deps.projectId, ticketId)
-            : listTouchedRows(deps.db, { ticketId, jobId, path: relPath ? normalizeRel(relPath) : relPath });
-        res.json(provenanceRowsToJson(rows));
+            ? listByTicket(deps.db, deps.projectId, ticketId, repository)
+            : listTouchedRows(deps.db, { ticketId, jobId, path: relPath ? normalizeRel(relPath) : relPath }, repository);
+        const visibility = await (0, exports.filterCodeExplorerActivityPaths)({
+            id: deps.repositoryId ?? `primary-${deps.projectId}`, projectId: deps.projectId,
+            name: deps.repositoryName ?? path_1.default.basename(deps.projectPath), path: deps.projectPath,
+            isPrimary: deps.includeLegacyProvenance !== false, kind: (0, project_repositories_1.legacyRepositoryKind)(deps.projectPath), integrationBranch: null, addedAt: '',
+        }, [...new Set(rows.map(row => row.file_path))], 2_000);
+        if (visibility.unavailable || visibility.incomplete) {
+            res.status(503).json({ error: 'provenance_policy_unavailable' });
+            return;
+        }
+        res.json(provenanceRowsToJson(rows.filter(row => visibility.allowed.has(row.file_path))));
     });
-    router.get('/diff', (req, res) => {
+    router.get('/diff', async (req, res) => {
         const jobId = parseNonEmptyString(req.query.jobId);
         const relPath = parseNonEmptyString(req.query.path);
         if (!jobId || !relPath) {
@@ -924,11 +1522,11 @@ function createCodeExplorerRouter(deps) {
             return;
         }
         const rel = normalizeRel(relPath);
-        if (isGitIgnored(deps.projectPath, rel)) {
+        if (await isGitIgnored(deps.projectPath, rel)) {
             res.status(403).json({ error: 'path is gitignored' });
             return;
         }
-        const diff = (0, file_provenance_1.getProvenanceDiff)(deps.db, deps.projectId, jobId, rel);
+        const diff = (0, file_provenance_1.getProvenanceDiff)(deps.db, deps.projectId, jobId, rel, repository);
         if (!diff) {
             res.status(404).json({ error: 'diff not available' });
             return;
@@ -988,9 +1586,11 @@ function resolveSafePath(projectPath, relPath) {
         }
     }
 }
-async function computeStaleness(abs, summary) {
+async function computeStaleness(abs, summary, language) {
     if (!summary)
         return false;
+    if ((0, file_summary_manager_1.isSummaryMetadataStale)(summary, language))
+        return true;
     try {
         const currentHash = await (0, file_summary_manager_1.computeFileHash)(abs);
         return currentHash !== summary.fileHash;