@evandu/super-pi 0.1.105 → 0.1.107

package/dist/server/file-changes.js

@@ -0,0 +1,278 @@
+/**
+ * WHAT THE AGENT CHANGED, AND WHAT IT LOOKED LIKE BEFORE.
+ *
+ * WHY THIS FILE EXISTS. The Files panel could show a file, but it could not show a CHANGE - and a panel
+ * that cannot show a change is a file browser, not a workbench. The user asked for the opposite of a
+ * browser: "看得到文件才能更好地支持 ai 的改动" - being able to SEE the files is what makes the agent's
+ * edits reviewable. Reviewing an edit means seeing two things: WHICH files were touched, and WHAT
+ * changed in them. Neither existed.
+ *
+ * THE SERVICE ALREADY KNEW THE FIRST HALF AND THREW IT AWAY. `tool-calls.ts` reads a tool's target path
+ * out of its arguments to draw one line on a card ("edit src/server/files.ts"). That line was the ONLY
+ * place the information existed, and it was never sent to the Files panel - the WS protocol had no file
+ * event at all, so a file the agent rewrote looked exactly like a file it had never touched.
+ *
+ * WHY THE PATHS ARE READ FROM THE ARGUMENTS RATHER THAN GUESSED FROM A WATCHER. A watcher sees bytes
+ * changing; it does not see WHO changed them, and it cannot distinguish the agent's edit from an
+ * unrelated build step. The tool call is the agent saying "I am about to change this path" in its own
+ * words - the most reliable source available, and one that costs nothing to read.
+ *
+ * WHY THE "BEFORE" CONTENT IS CAPTURED HERE RATHER THAN RECOVERED LATER. Once the agent has written the
+ * file, the old bytes are gone from the disk. A diff needs a baseline, and the baseline has to be taken
+ * BEFORE the write. So this file keeps a copy of the content as it was, taken when the agent's write
+ * tool was announced - the last moment the old content is still on disk.
+ *
+ * WHAT THIS FILE DOES NOT DO. It does not watch the disk. An external editor saving a file is noticed by
+ * the CLIENT's existing poll (`?meta=1` on open files), not here - and that asymmetry is deliberate: this
+ * file is about the agent's changes, which is the half only the server can see. It does not keep a full
+ * copy of every file: only the files the agent actually wrote, and only until the diff is read.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+/**
+ * The tools whose arguments name a file the agent is about to WRITE.
+ *
+ * `edit` and `write` are Pi's two file-writing tools (`node_modules/@earendil-works/pi-coding-agent/
+ * dist/core/tools/`), and `notebookedit` is the third in the family that edits a notebook. The list is
+ * deliberately narrow: a `read` names a file too, and a `read` changes nothing, so treating it as a
+ * change would mark a file the agent merely LOOKED at as one it edited - and a marker that lies is worse
+ * than no marker, because the user's trust in every other marker goes with it.
+ *
+ * The names are matched case-insensitively and after trimming, because the name comes off a wire and a
+ * tool named "Edit" is the same tool.
+ */
+export const FILE_WRITING_TOOLS = new Set(["edit", "write", "notebookedit", "multiedit"]);
+/**
+ * The argument fields that name the file, in the order the tools tend to spell them.
+ *
+ * The same list `tool-calls.ts` uses to draw its one-line summary, and deliberately the same ORDER: two
+ * tables that disagree about which field wins would make the card say "src/a.ts" and the change tracker
+ * say "src/b.ts" for the same call, and the user would have no way to tell which one is right.
+ *
+ * `notebook_path` is here because the notebook tools spell it that way, and it is checked before the
+ * generic `path` only because the notebook tools have no plain `path` field to collide with.
+ */
+const PATH_KEYS = ["path", "file_path", "filePath", "target_file", "filename", "file", "notebook_path"];
+/**
+ * The path an argument names, or `undefined` when the arguments name none.
+ *
+ * NOT a display string. `describeToolCall` collapses whitespace and caps the length, which is right for
+ * a card and wrong for a path that is about to be read off the disk - a path with a run of spaces in it
+ * would be reported as a path with one space, and the file would not be found. This returns the value
+ * as the tool spelled it, so the caller can resolve it properly.
+ *
+ * The value is NOT validated here. The caller resolves it against the workspace root and refuses
+ * anything that leaves it - the containment rule lives in `files.ts` and has exactly one owner, and this
+ * module does not get a second, weaker copy of it.
+ */
+export function toolTargetPath(name, args) {
+    if (typeof name !== "string")
+        return undefined;
+    if (!FILE_WRITING_TOOLS.has(name.trim().toLowerCase()))
+        return undefined;
+    if (args === null || typeof args !== "object" || Array.isArray(args))
+        return undefined;
+    const record = args;
+    for (const key of PATH_KEYS) {
+        const value = record[key];
+        if (typeof value !== "string")
+            continue;
+        const trimmed = value.trim();
+        if (trimmed)
+            return trimmed;
+    }
+    return undefined;
+}
+/**
+ * The changes recorded for one workspace, and the old contents they need.
+ *
+ * BOUNDED ON PURPOSE, in two directions. The number of entries is capped because a long session can
+ * touch a lot of files, and the copy of every old version is the memory cost of this feature. The size
+ * of ONE old version is capped because a single 5MB file would otherwise be the whole budget.
+ *
+ * When a cap is reached, the OLDEST entry is dropped, and `dropped` counts how many were dropped. That
+ * count is reported rather than hidden: a diff view that says "this file changed" and then cannot show
+ * the change because the baseline was evicted is a worse experience than one that says "the baseline for
+ * this file is no longer available", and the second is what the count makes possible.
+ */
+const MAX_TRACKED_CHANGES = 200;
+const MAX_BASELINE_BYTES = 1024 * 1024;
+/**
+ * The identity of a file's current bytes - the same formula `files.ts` uses, so the two agree.
+ *
+ * Size, nanosecond modification time and inode: the two fields together change on any edit a human
+ * would call an edit, and `bigint` is what makes the modification time exact - the millisecond float
+ * `stat` reports by default rounds two edits inside the same millisecond into one value, and a check
+ * that misses a change is worse than no check.
+ */
+function etagOf(size, mtimeNs, ino) {
+    return createHash("sha1").update(`${size}:${mtimeNs}:${ino}`).digest("hex").slice(0, 20);
+}
+export class FileChangeTracker {
+    /** Workspace id -> path -> the change recorded for it. A path is recorded once: the LAST change to a
+     *  file wins, because a file edited three times in a turn is one file with one final state, and the
+     *  reader wants the diff from before the FIRST change to after the LAST one. */
+    #byWorkspace = new Map();
+    /** How many changes were dropped because the cap was reached, per workspace. */
+    #dropped = new Map();
+    /**
+     * Records that the agent is about to write `path`, capturing the current content as the baseline.
+     *
+     * Called when the tool call is ANNOUNCED, not when it ends. The announcement is the last moment the
+     * old bytes are still on the disk: by the time the tool has finished, the file already holds the new
+     * content and the baseline is gone forever. This is the whole reason the tracker reads the disk at
+     * all.
+     *
+     * A file that is already tracked is NOT re-baselined. Re-baselining would set the "before" to the
+     * agent's own intermediate state, and the diff would then show only the LAST edit rather than
+     * everything the agent did to the file in this turn - which is the thing a reviewer needs to see.
+     *
+     * THE READ IS SYNCHRONOUS, and that is the whole reason this feature works.
+     *
+     * Pi announces a tool call and then RUNS it, and it does not wait for this server to acknowledge the
+     * announcement. So the tool may well have written the file by the time this server gets around to
+     * reading it - and an ASYNCHRONOUS read loses that race almost every time, because the read is queued
+     * behind the very write it is trying to get ahead of. The first version of this was asynchronous, and
+     * the symptom was a diff that said "+0 / -0": the baseline it captured was the file's NEW content,
+     * because by the time the read happened the agent had already written.
+     *
+     * A synchronous read cannot lose that race in the same way - it happens in the same tick the
+     * announcement was parsed, before anything else can run - and the cost is bounded by the size cap
+     * below. A blocked event loop for the length of one small file read, once per agent write, is a far
+     * better trade than a diff that shows nothing.
+     */
+    record(workspaceId, path, options) {
+        const relativePath = this.#relative(options.root, path);
+        if (!relativePath)
+            return;
+        const changes = this.#byWorkspace.get(workspaceId) ?? new Map();
+        this.#byWorkspace.set(workspaceId, changes);
+        if (changes.has(relativePath))
+            return;
+        let before = null;
+        let beforeUnknown = false;
+        let etag;
+        try {
+            const absolute = resolve(options.root, path);
+            // The size is checked BEFORE the read, so an oversized file costs one stat rather than a buffer.
+            const info = statSync(absolute, { bigint: true });
+            if (info.size > MAX_BASELINE_BYTES) {
+                // A baseline larger than the cap is not a baseline - it is a memory cost with no diff to show
+                // for it. The change is still recorded (the file WAS changed, and that fact is worth knowing);
+                // what is dropped is the ability to show what it was, which `beforeUnknown` says out loud.
+                beforeUnknown = true;
+            }
+            else {
+                before = readFileSync(absolute, "utf8");
+                etag = etagOf(info.size, info.mtimeNs, info.ino);
+            }
+        }
+        catch (error) {
+            const code = error?.code;
+            // ENOENT is the ordinary case of a NEW file, and it is a fact rather than a failure: the file did
+            // not exist before the agent created it, so there is no "before" to show. Anything else (a
+            // permission problem, a directory) means we simply do not know, and the two are told apart by
+            // `beforeUnknown`.
+            beforeUnknown = code !== "ENOENT" && code !== "ENOTDIR";
+        }
+        changes.set(relativePath, {
+            path: relativePath,
+            before,
+            beforeUnknown,
+            ...(etag ? { etag } : {}),
+            at: Date.now(),
+            ...(options.conversationId ? { conversationId: options.conversationId } : {}),
+        });
+        if (changes.size > MAX_TRACKED_CHANGES) {
+            // The OLDEST goes, because a reviewer is looking at the most recent work. `Map` preserves
+            // insertion order, so the first key is the oldest.
+            const oldest = changes.keys().next();
+            if (!oldest.done) {
+                changes.delete(oldest.value);
+                this.#dropped.set(workspaceId, (this.#dropped.get(workspaceId) ?? 0) + 1);
+            }
+        }
+    }
+    /**
+     * CONFIRMS A BASELINE, once the agent's write has finished.
+     *
+     * The synchronous read makes the baseline correct in practice, but "in practice" is not a guarantee:
+     * if the tool somehow ran before the announcement was processed, the baseline would be the file's NEW
+     * content and the diff would show nothing at all - a diff that says "no change" about a file the
+     * agent just rewrote, which is the worst possible lie this feature could tell.
+     *
+     * So the baseline is CHECKED rather than trusted. The file's etag after the write must DIFFER from
+     * the etag the baseline was taken at - and if it does not, the baseline was taken after the write and
+     * is worthless. The change is then marked as having no usable "before", and the diff view says so
+     * instead of showing an empty diff.
+     *
+     * The one case this cannot tell apart is a write that changed nothing (the agent wrote identical
+     * bytes). There the baseline and the file agree, and the diff is empty - which is CORRECT, because
+     * nothing changed. The reader is told the before-version is unconfirmed, which is true in both cases.
+     */
+    confirm(workspaceId, path, root) {
+        const changes = this.#byWorkspace.get(workspaceId);
+        if (!changes)
+            return;
+        // The path is spelled the way the tracker spells it - workspace-relative, `/`-separated - and the
+        // caller may hold the tool's own spelling, so both are tried.
+        const relativePath = this.#relative(root, path);
+        const change = (relativePath ? changes.get(relativePath) : undefined) ?? changes.get(path);
+        if (!change || !change.etag)
+            return;
+        try {
+            const info = statSync(resolve(root, change.path), { bigint: true });
+            const current = etagOf(info.size, info.mtimeNs, info.ino);
+            if (current === change.etag) {
+                // The file is byte-for-byte what the baseline says it was, so the baseline was taken AFTER the
+                // write - or nothing changed at all. Either way it cannot be shown as "before".
+                change.before = null;
+                change.beforeUnknown = true;
+            }
+        }
+        catch {
+            // The file is gone: the agent DELETED it, which is a change of its own. The baseline stands.
+        }
+    }
+    /**
+     * The changes recorded for a workspace, newest first.
+     *
+     * `dropped` says how many baselines were evicted, so the panel can say so rather than quietly showing
+     * a shorter list than the agent actually produced.
+     */
+    list(workspaceId) {
+        const changes = [...(this.#byWorkspace.get(workspaceId)?.values() ?? [])];
+        changes.reverse();
+        return { changes, dropped: this.#dropped.get(workspaceId) ?? 0 };
+    }
+    /** The recorded change for one path, or `undefined` when there is none. */
+    get(workspaceId, path) {
+        return this.#byWorkspace.get(workspaceId)?.get(path);
+    }
+    /** Forgets a workspace's changes. Used when the workspace is deleted. */
+    forget(workspaceId) {
+        this.#byWorkspace.delete(workspaceId);
+        this.#dropped.delete(workspaceId);
+    }
+    /**
+     * The path as the rest of the app spells it: workspace-relative, `/`-separated, no leading slash.
+     *
+     * REFUSES ANYTHING OUTSIDE THE ROOT, rather than clamping it. A tool that names `../outside.txt` is
+     * either broken or hostile, and a "relative path" that silently becomes `../outside.txt` would be a
+     * path the panel would then try to read. The containment decision itself belongs to `files.ts`; this
+     * is only about the SPELLING, and it declines to spell a path it cannot vouch for.
+     */
+    #relative(root, path) {
+        const base = resolve(root);
+        const absolute = isAbsolute(path) ? resolve(path) : resolve(base, path);
+        const rel = relative(base, absolute);
+        if (rel === "")
+            return null;
+        if (isAbsolute(rel))
+            return null;
+        if (rel === ".." || rel.startsWith(`..${sep}`) || rel.startsWith("../"))
+            return null;
+        return rel.split(sep).join("/");
+    }
+}

package/dist/server/file-diff.d.ts

@@ -0,0 +1,38 @@
+import type { FileChangeTracker } from "./file-changes.js";
+/**
+ * WHERE THE "BEFORE" CAME FROM. The client renders a different label for each, because they are
+ * different claims: "this is what the agent changed" and "this is what the repository had committed"
+ * are not the same sentence, and a diff shown without knowing which one it is against is a diff the
+ * reader has to guess about.
+ */
+export type DiffBaselineKind = "agent" | "git" | "none";
+export type FileDiff = {
+    /** The file, workspace-relative and `/`-separated. */
+    path: string;
+    /** Which baseline was used. */
+    baseline: DiffBaselineKind;
+    /** The content before, or `null` when there was none - which is how a NEW file is told from an
+     *  EDITED one. */
+    before: string | null;
+    /** True when the "before" could not be READ, as opposed to not existing. A diff against an empty
+     *  "before" for a file that existed would be a lie, and this is what keeps it from being one. */
+    beforeUnknown?: boolean;
+    /** The content now, or `null` when the file is gone. */
+    after: string | null;
+    /** A sentence naming the baseline, for the view to show. */
+    label: string;
+};
+/**
+ * The diff of one file, with the best baseline available.
+ *
+ * `preferred` says which baseline the caller wants. `auto` means "pick the best one", which is what
+ * the review view asks for; naming a specific baseline means the user has been told which comparison
+ * they are looking at and it must not silently become a different one.
+ */
+export declare function computeFileDiff(options: {
+    root: string;
+    path: string;
+    preferred?: "auto" | DiffBaselineKind;
+    tracker?: FileChangeTracker;
+    workspaceId?: string;
+}): Promise<FileDiff>;

package/dist/server/file-diff.js

@@ -0,0 +1,97 @@
+/**
+ * THE DIFF BETWEEN WHAT A FILE WAS AND WHAT IT IS NOW.
+ *
+ * WHY THE SERVER SENDS TWO TEXTS RATHER THAN A DIFF. The difference between two texts is computed by
+ * an algorithm, and there are good ones (jsdiff, on the client). Sending a diff instead would mean the
+ * server owns a second implementation of that algorithm, and the two would disagree at the edges - a
+ * hunk boundary, an empty file, a file with no trailing newline. Sending the two TEXTS means there is
+ * exactly ONE implementation of "what is the difference between these two strings" in the whole
+ * product, and the server's job is reduced to the one thing only it can do: produce the "before".
+ *
+ * WHERE THE "BEFORE" COMES FROM, in the order the user cares about.
+ *
+ * 1. THE AGENT'S OWN BASELINE. The server captured the file's content at the moment the agent's write
+ *    tool was announced (`file-changes.ts`), so this is the exact content the agent started from. It is
+ *    the right answer for "what did the agent just do", and it works in a directory that is not a git
+ *    repository - which is most of them, for a user who has not initialised a repo.
+ * 2. GIT'S COMMITTED VERSION. For a file in a git repository, `HEAD` is a baseline that exists even
+ *    when the server was not running when the change was made, and it is the baseline a reviewer
+ *    already has in mind.
+ * 3. NOTHING. When neither exists - a brand new file in a directory that is not a repository, with no
+ *    agent change to reconstruct - the answer is that there is no baseline, and the view says so
+ *    rather than showing a diff against nothing.
+ *
+ * The BUFFER is the fourth baseline and it does not come from the server: the "before" of a buffer is
+ * the file on disk and the "after" is what the user has typed, and the client already holds both. So
+ * the client computes that one itself and never asks.
+ */
+import { readFile } from "node:fs/promises";
+import { gitHeadContent, isGitRepository } from "./git.js";
+import { FilesError, resolveInsideRoot } from "./files.js";
+/**
+ * The diff of one file, with the best baseline available.
+ *
+ * `preferred` says which baseline the caller wants. `auto` means "pick the best one", which is what
+ * the review view asks for; naming a specific baseline means the user has been told which comparison
+ * they are looking at and it must not silently become a different one.
+ */
+export async function computeFileDiff(options) {
+    const { root, path, preferred = "auto", tracker, workspaceId } = options;
+    const after = await readAfter(root, path);
+    // The agent's baseline. It is the RIGHT one whenever it exists, because it is the content the agent
+    // actually started from - which is not necessarily HEAD, and not necessarily what the file looked
+    // like when the server started.
+    const agentChange = tracker && workspaceId ? tracker.get(workspaceId, path) : undefined;
+    if ((preferred === "auto" || preferred === "agent") && agentChange) {
+        return {
+            path,
+            baseline: "agent",
+            before: agentChange.before,
+            ...(agentChange.beforeUnknown ? { beforeUnknown: true } : {}),
+            after,
+            label: agentChange.before === null && !agentChange.beforeUnknown
+                ? "这个文件是 agent 新建的"
+                : "agent 改动前",
+        };
+    }
+    if (preferred === "auto" || preferred === "git") {
+        if (await isGitRepository(root)) {
+            const head = await gitHeadContent(root, path);
+            if (head !== null) {
+                return { path, baseline: "git", before: head, after, label: "Git 已提交的版本" };
+            }
+        }
+    }
+    if (preferred === "agent" && !agentChange) {
+        // The caller ASKED for the agent's baseline and there is none. Saying so is the honest answer; a
+        // silent fall-back to git would show the user a comparison they did not ask for.
+        return { path, baseline: "none", before: null, after, label: "没有 agent 改动前的版本可比较" };
+    }
+    return { path, baseline: "none", before: null, after, label: "没有可比较的基线" };
+}
+/**
+ * The file's content now, or `null` when it is gone.
+ *
+ * A MISSING FILE IS NOT AN ERROR. The agent deleting a file is a change the user needs to see, and a
+ * diff view that refused to open because the file no longer exists would refuse to show exactly the
+ * change that matters most.
+ *
+ * THE PATH GOES THROUGH `resolveInsideRoot`, like every other path this server reads. The path arrives
+ * from a browser, so it is untrusted, and the question "does this resolve to somewhere inside the
+ * workspace" has exactly one owner in this codebase (`files.ts`). A second, weaker copy of the check
+ * here would be a check that is correct once.
+ */
+async function readAfter(root, path) {
+    try {
+        const target = await resolveInsideRoot(root, path);
+        return await readFile(target, "utf8");
+    }
+    catch (error) {
+        // A file that is GONE is a fact the diff reports; a path that ESCAPES the workspace is a refusal
+        // the route turns into a 403. They are told apart here so the route can do the right thing with
+        // each, rather than both becoming "no content".
+        if (error instanceof FilesError && (error.status === 403 || error.code === "outside_workspace"))
+            throw error;
+        return null;
+    }
+}

package/dist/server/file-index.d.ts

@@ -0,0 +1,56 @@
+import { type FileMeta } from "./files.js";
+export type IndexedFile = {
+    path: string;
+    kind: "file" | "directory";
+    size: number | null;
+    mtimeMs: number | null;
+    etag: string | null;
+    text: boolean | null;
+};
+export type FileIndexEvent = {
+    type: "files.index";
+    workspaceId: string;
+    version: number;
+    changed: IndexedFile[];
+    removed: string[];
+    complete: boolean;
+    skipped: string[];
+};
+export type FileIndexSnapshot = {
+    version: number;
+    builtAt: number;
+    complete: boolean;
+    changed: IndexedFile[];
+    removed: string[];
+    skipped: string[];
+};
+/**
+ * Per-workspace index. The background pass uses readdir only because measurements on this repository
+ * show directory enumeration under a second while stat for every entry costs 2-3 seconds. Most entries
+ * deliberately have no etag: an etag belongs to a file a user has opened or a known write has touched,
+ * where the existing read/write metadata already paid for it. The client polls only those open files.
+ */
+export declare class FileIndex {
+    readonly workspaceId: string;
+    private readonly broadcast;
+    readonly entries: Map<string, IndexedFile>;
+    private readonly history;
+    private root;
+    private queue;
+    private building;
+    private skipped;
+    version: number;
+    builtAt: number;
+    complete: boolean;
+    constructor(workspaceId: string, broadcast: (event: FileIndexEvent) => void);
+    start(root: string): void;
+    stop(): void;
+    snapshot(since?: number): FileIndexSnapshot;
+    refresh(path: string): Promise<void>;
+    /** Record metadata already obtained by opening, saving, or polling an open file. No second stat: the
+     * caller's file API operation has already passed the sole containment guard and read this metadata. */
+    recordFile(path: string, meta: FileMeta, mtimeMs?: number): void;
+    remove(path: string): void;
+    private scan;
+    private publish;
+}

package/dist/server/file-index.js

@@ -0,0 +1,150 @@
+import { readdir, stat } from "node:fs/promises";
+import { SEARCH_SKIP_DIRS, createRootGuard, fileMeta, isTextName, toRelative } from "./files.js";
+const MAX_DIRECTORIES = 4000;
+const MAX_FILES = 30000;
+const MAX_MS = 4000;
+/**
+ * Per-workspace index. The background pass uses readdir only because measurements on this repository
+ * show directory enumeration under a second while stat for every entry costs 2-3 seconds. Most entries
+ * deliberately have no etag: an etag belongs to a file a user has opened or a known write has touched,
+ * where the existing read/write metadata already paid for it. The client polls only those open files.
+ */
+export class FileIndex {
+    workspaceId;
+    broadcast;
+    entries = new Map();
+    history = [];
+    root = "";
+    queue = [];
+    building = false;
+    skipped = [];
+    version = 0;
+    builtAt = 0;
+    complete = false;
+    constructor(workspaceId, broadcast) {
+        this.workspaceId = workspaceId;
+        this.broadcast = broadcast;
+    }
+    start(root) {
+        if (this.building || this.builtAt)
+            return;
+        this.root = root;
+        this.building = true;
+        this.queue = [""];
+        void this.scan();
+    }
+    stop() { }
+    snapshot(since) {
+        const valid = Number.isFinite(since) && since !== undefined;
+        const deltas = valid ? this.history.filter((item) => item.version > since) : [];
+        return { version: this.version, builtAt: this.builtAt, complete: this.complete, skipped: this.skipped,
+            changed: valid ? deltas.flatMap((item) => item.changed) : [...this.entries.values()],
+            removed: valid ? deltas.flatMap((item) => item.removed) : [] };
+    }
+    async refresh(path) {
+        if (!this.root)
+            return;
+        const guard = createRootGuard(this.root);
+        try {
+            const absolute = await guard(path);
+            const info = await stat(absolute);
+            const rel = toRelative(this.root, absolute);
+            if (info.isDirectory())
+                this.publish([{ path: rel, kind: "directory", size: null, mtimeMs: null, etag: null, text: null }], []);
+            else {
+                const meta = await fileMeta(absolute);
+                this.recordFile(rel, meta, info.mtimeMs);
+            }
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ENOENT" || code === "ENOTDIR")
+                this.remove(path);
+            else
+                throw error;
+        }
+    }
+    /** Record metadata already obtained by opening, saving, or polling an open file. No second stat: the
+     * caller's file API operation has already passed the sole containment guard and read this metadata. */
+    recordFile(path, meta, mtimeMs = Date.parse(meta.modifiedAt)) {
+        const previous = this.entries.get(path);
+        if (previous?.kind === "file" && previous.etag === meta.etag)
+            return;
+        this.publish([{ path, kind: "file", size: meta.size, mtimeMs, etag: meta.etag, text: isTextName(path) }], []);
+    }
+    remove(path) { if (this.entries.delete(path))
+        this.publish([], [path]); }
+    async scan() {
+        const started = Date.now();
+        let dirs = 0;
+        let files = 0;
+        let incomplete = false;
+        const changed = [];
+        const guard = createRootGuard(this.root);
+        scan: while (this.queue.length) {
+            if (dirs >= MAX_DIRECTORIES || files >= MAX_FILES || Date.now() - started >= MAX_MS) {
+                incomplete = true;
+                break;
+            }
+            const directory = this.queue.shift();
+            let listed;
+            try {
+                listed = await readdir(await guard(directory), { withFileTypes: true });
+            }
+            catch {
+                this.skipped.push(directory || "/");
+                incomplete = true;
+                continue;
+            }
+            dirs += 1;
+            for (const entry of listed) {
+                const path = directory ? directory + "/" + entry.name : entry.name;
+                if (entry.isSymbolicLink()) {
+                    this.skipped.push(path);
+                    continue;
+                }
+                if (entry.isDirectory()) {
+                    if (SEARCH_SKIP_DIRS.has(entry.name)) {
+                        this.skipped.push(path);
+                        continue;
+                    }
+                    this.queue.push(path);
+                    changed.push({ path, kind: "directory", size: null, mtimeMs: null, etag: null, text: null });
+                }
+                else if (entry.isFile()) {
+                    if (files >= MAX_FILES || Date.now() - started >= MAX_MS) {
+                        incomplete = true;
+                        break scan;
+                    }
+                    files += 1;
+                    changed.push({ path, kind: "file", size: null, mtimeMs: null, etag: null, text: isTextName(path) });
+                }
+            }
+            await new Promise((resolve) => setTimeout(resolve, 0));
+        }
+        this.building = false;
+        this.complete = !incomplete;
+        this.builtAt = Date.now();
+        // Quick Open does not need per-directory progress. One final batch bounds WS traffic and keeps the
+        // existing on-demand tree interactive throughout the scan (including dependency directories).
+        this.publish(changed, [], true);
+    }
+    publish(changed, removed, force = false) {
+        changed = changed.map((entry) => {
+            // A targeted stat may race the cheap directory walk. Do not let the later readdir-only result erase
+            // metadata that was already paid for and verified.
+            const previous = this.entries.get(entry.path);
+            const merged = previous?.kind === entry.kind && entry.size === null ? { ...entry, size: previous.size, mtimeMs: previous.mtimeMs, etag: previous.etag } : entry;
+            this.entries.set(entry.path, merged);
+            return merged;
+        });
+        if (!changed.length && !removed.length && !force)
+            return;
+        this.version += 1;
+        const event = { type: "files.index", workspaceId: this.workspaceId, version: this.version, changed, removed, complete: this.complete, skipped: this.skipped };
+        this.history.push({ version: this.version, changed, removed });
+        if (this.history.length > 128)
+            this.history.shift();
+        this.broadcast(event);
+    }
+}

package/dist/server/files.d.ts

@@ -15,6 +15,14 @@ export declare const MAX_SEARCH_RESULTS = 500;
 /** How deep the recursive search walks. Twelve levels is past any real source tree; the cap is what
  *  turns a pathologically deep dependency tree from a hang into a result. */
 export declare const MAX_SEARCH_DEPTH = 12;
+/** Directories the recursive search skips. The TREE does not skip them - a directory the user cannot
+ *  browse is a directory they cannot inspect a file in, and the binary handling below is only reachable
+ *  if `node_modules` is reachable. A recursive filename search, by contrast, returns thousands of matches
+ *  from these and nothing a person searched for, so they are excluded from the scan and the exclusion is
+ *  reported in the response rather than being invisible. */
+/** Shared exclusion list for recursive search and the quick-open index. The directory tree intentionally
+ * does not use it: users may still browse dependencies on demand. */
+export declare const SEARCH_SKIP_DIRS: Set<string>;
 /**
  * Extensions this panel OPENS without needing a sniff. It is a hint used only to label a file in the tree
  * before it is read, and never as a permission: a `.png` is refused by name even if a sniffing pass would

package/dist/server/files.js

@@ -52,7 +52,9 @@ export const MAX_SEARCH_DEPTH = 12;
  *  if `node_modules` is reachable. A recursive filename search, by contrast, returns thousands of matches
  *  from these and nothing a person searched for, so they are excluded from the scan and the exclusion is
  *  reported in the response rather than being invisible. */
-const SEARCH_SKIP_DIRS = new Set([".git", "node_modules", "dist", "build", ".super-pi", ".next", ".cache", "coverage", ".venv"]);
+/** Shared exclusion list for recursive search and the quick-open index. The directory tree intentionally
+ * does not use it: users may still browse dependencies on demand. */
+export const SEARCH_SKIP_DIRS = new Set([".git", "node_modules", "dist", "build", ".super-pi", ".next", ".cache", "coverage", ".venv"]);
 /**
  * Extensions that are binary by definition, checked BEFORE any bytes are read.
  *