@gavin-hu/my-pi-agent 0.15.0 → 0.16.0

package/extensions/context/types.ts

@@ -0,0 +1,122 @@
+/**
+ * The report's data contract.
+ *
+ * `ContextInputs` is what the host hands over: the effective system prompt, the
+ * tool surface, the host's usage estimate, the messages that will be sent, and
+ * the branch the compaction history is read from. `ContextReport` is what the
+ * pure builder derives from it and what the text detail and the screen render.
+ *
+ * Host types that the package root does not re-export are named through the
+ * extension surface (`ReturnType<…>`) rather than a deep import, so a peer
+ * version change fails to typecheck instead of resolving a second copy.
+ */
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/** The host's context-usage estimate (`ctx.getContextUsage()`). */
+export type ContextUsage = NonNullable<ReturnType<ExtensionContext["getContextUsage"]>>;
+
+/** The active branch entries (`sessionManager.getBranch()`). */
+export type BranchEntries = ReturnType<ExtensionContext["sessionManager"]["getBranch"]>;
+
+/** Merged global and project settings (`pi.getSettings()`). */
+export type ContextSettings = ReturnType<ExtensionAPI["getSettings"]>;
+
+/** Everything the pure report needs; collected once per open or refresh. */
+export interface ContextInputs {
+	/** The model in effect, or `null` before one is selected. */
+	model: { provider: string; id: string } | null;
+	/** The active model's context window, or `0` when unknown. */
+	window: number;
+	/** The effective system prompt for this turn (`ctx.getSystemPrompt()`). */
+	systemPrompt: string;
+	/** The active tool surface, with the definition estimate already computed. */
+	tools: { active: number; total: number; tokens: number };
+	/** The host's estimate; `tokens` is `null` between a compaction and the next reply. */
+	usage: ContextUsage | undefined;
+	/** The model-visible messages for the next request. */
+	messages: readonly AgentMessage[];
+	/** The branch the latest compaction entry and its count are read from. */
+	branch: BranchEntries;
+	/** Merged settings, for the compaction threshold. */
+	settings: ContextSettings;
+}
+
+/** One row of the composition table. */
+export interface ContextBucket {
+	/** Stable id; an injected child is `injected:<customType>`. */
+	id: string;
+	/** Display label, already plain text. */
+	label: string;
+	/** Estimated tokens. */
+	tokens: number;
+	/** Share of the composition estimate, `0..100`. */
+	share: number;
+	/** `0` for a top-level bucket, `1` for an injected child. */
+	depth: number;
+	/** A short factual suffix: `18 active of 24`, a message count. */
+	note?: string;
+}
+
+/** The latest compaction's effect. */
+export interface CompactionSummary {
+	/** `YYYY-MM-DD HH:MMZ` from the entry's ISO timestamp, in UTC. */
+	at: string;
+	/** The estimate the host recorded before compacting. */
+	tokensBefore: number;
+	/** The summary's own estimate. */
+	summaryTokens: number;
+	/** `tokensBefore - summaryTokens`, floored at zero. */
+	freed: number;
+}
+
+/** What the branch remembers about compaction. */
+export interface CompactionHistory {
+	/** How many compaction entries the branch holds. */
+	count: number;
+	/** The newest one, or `null` when the branch has never been compacted. */
+	last: CompactionSummary | null;
+}
+
+/** One of the largest single blocks in the projected context. */
+export interface LargestBlock {
+	/** Estimated tokens. */
+	tokens: number;
+	/** What kind of message it is: `user`, `assistant`, `tool result`, … */
+	role: string;
+	/** Sanitized, clipped descriptor (a tool name, the first line, a custom type). */
+	label: string;
+}
+
+/** The finished report. */
+export interface ContextReport {
+	/** The context window, `0` when unknown. */
+	window: number;
+	/** The host's estimate, `null` between a compaction and the next reply. */
+	tokens: number | null;
+	/** `tokens / window`, `null` when either is unknown. */
+	percent: number | null;
+	/** `window - tokens`, `null` when `tokens` is unknown. */
+	free: number | null;
+	/** `window - reserve - tokens`, `null` when `tokens` is unknown. */
+	headroom: number | null;
+	/** The resolved `reserveTokens` for the active model. */
+	reserve: number;
+	/** The resolved `keepRecentTokens` for the active model. */
+	keepRecentTokens: number;
+	/** Whether the host's automatic compaction is on. */
+	enabled: boolean;
+	/** `max(0, window - reserve)`: where the host would compact. */
+	autoCompactAt: number;
+	/** The composition rows, ordered for display. */
+	buckets: ContextBucket[];
+	/** Sum of the bucket estimates. */
+	estimate: number;
+	/** `tokens - estimate` when the host's estimate is known, else `null`. */
+	drift: number | null;
+	/** The branch's compaction history. */
+	compaction: CompactionHistory;
+	/** The largest projected blocks, biggest first. */
+	largest: LargestBlock[];
+}

package/extensions/file-browse/README.md

@@ -83,6 +83,16 @@ pi -e .                                    # load the whole @gavin-hu/my-pi-agen
   `worktree`; untracked files show as all-add, an unborn `HEAD` falls back to the
   index, and a non-repository is a plain empty state. Read-only, capped, and
   rendered with the shared diff colors.
+- **Live status.** A page left open keeps up with the session: a `◉ live`
+  chip beside `read-only` says whether status is flowing (green), still
+  connecting (accent), stalled (amber, after three missed frames), or offline
+  (red); the branch chip, the `● N changes +A −D` chip, and the change markers in
+  the tree and the listing update in place; and the footer line reports `up 2m
+  14s · 37 requests`. The chip names its state and never counts, so nothing is
+  repainted between frames. One Server-Sent Events stream per page carries it, on
+  the same loopback server, so nothing extra is opened and nothing is written;
+  that stream is also how the server notices the last page closing its window,
+  after which it stops listening.
 - **No dependencies.** `node:http` plus the inline sprite, CSS, and client
   script.
 
@@ -103,7 +113,10 @@ pi -e .                                    # load the whole @gavin-hu/my-pi-agen
   port; a busy port is reported, not silently changed.
 - Starting while already running with the same root reprints the URL without
   restarting; a different root (or a changed pinned port) restarts the server.
-- The server is closed on `session_shutdown`.
+- The server is closed when its last page has been gone for ten seconds, so
+  closing the browser window ends the session's browse server and `/browse`
+  starts it again on the same port. A reload or a new tab inside that grace keeps
+  it. `session_shutdown` closes it too, and `/browse stop` closes it at once.
 
 ### Status
 
@@ -114,6 +127,26 @@ beside `⎇ branch` and `⑂ worktree`; it
 is cleared on stop and on `session_shutdown`. The chip is session-local: it
 reflects only this session's server, with no cross-session sharing.
 
+The page has its own live status, which is what a left-open tab reads. The
+header chip starts hidden and is painted by the client from `/events`: `◉ live`
+in the success colour while frames arrive, `◉ connecting` before the first
+one, `◉ stale` in the warning colour when three intervals pass without a frame
+on an open connection, and `◉ offline` in the danger colour once the stream
+errors. The chip names its state rather than counting, so it is repainted only
+when that state changes. The same frame carries the branch (or detached head), the
+uncommitted-change totals and paths, the server's uptime, and the requests it
+has answered, so the branch chip, the changes chip, the markers, and the footer
+line are painted from one snapshot rather than four requests. Losing the stream
+leaves everything the page last showed in place: it is read-only, so a stale
+label is never a stale action. `"live": false` turns the whole surface off — no
+chip, no stream, no `/events` route — and so does JavaScript off.
+
+The stream is also how the server knows a page is still there: when the last one
+leaves, the port is released after ten seconds and the chip is cleared, because
+nothing is left to serve. That is why a page with JavaScript off — or with live
+status off — never counts as a reader, and the server then waits for
+`/browse stop` or the end of the session.
+
 ## Routes
 
 | Route | Result |
@@ -126,6 +159,7 @@ reflects only this session's server, with no cross-session sharing.
 | `/diff/<rel>[?mode=…]` | one file's unified diff |
 | `/api/tree?path=<rel>` | JSON children for lazy tree expansion |
 | `/api/files?q=<query>` | JSON fuzzy path matches for the quick-open palette |
+| `/events` | Server-Sent Events stream of `status` frames for the open page |
 | `/app.js` | the first-party client script |
 | `/theme.js` | the pre-paint theme bootstrap |
 | `/favicon.ico` | `204` (the icon is a data URI) |
@@ -150,7 +184,9 @@ document and the project document (project wins):
   "maxIndexEntries": 20000,  // files collected for quick open before truncation
   "gitDiff": true,           // offer the read-only diff view
   "diffContext": 3,          // unified diff context lines
-  "maxDiffLines": 4000       // diff lines rendered before truncation
+  "maxDiffLines": 4000,      // diff lines rendered before truncation
+  "live": true,              // stream live status to open pages
+  "liveIntervalMs": 3000     // ms between status frames while a page is connected
 }
 ```
 
@@ -185,6 +221,13 @@ document and the project document (project wins):
 - **Highlighting safety.** The highlighter escapes every literal before it
   wraps it in a token span, so a code file's content cannot inject markup or
   attributes; only the fixed `tok-*` class names reach the page.
+- **Event stream.** `/events` is a `GET` on the same loopback server, behind
+  the same method and `Host` checks, and it only reads: the frame is the branch,
+  the change paths, an uptime, and a request count, all of which the page it
+  feeds already renders. It carries no page policy (`text/event-stream` is not a
+  document), sends `Cache-Control: no-store`, and cannot be cached or replayed.
+  A tick runs only while a page is attached, and the timer is `unref`ed, so an
+  idle server does no work and a forgotten tab cannot hold the process open.
 - **Caps.** `maxFileBytes` (inline rendering), `maxTextLines` (rendered lines),
   `maxThumbBytes` (thumbnails), and `maxDirEntries` (listings) bound every read.
 - **Git reads.** The header chip and the diff view run read-only git
@@ -200,6 +243,11 @@ document and the project document (project wins):
   type renders exactly as before. State that the tokenizer does not carry
   across lines (shell heredocs, interpolation inside a template literal) is
   approximated rather than parsed.
+- Live status updates what the page already contains: the header chips, the
+  markers on the rows it rendered, and the footer line. A file that appears on
+  disk joins the listing on the next reload, the `/diff` table and a file page's
+  `changes` action stay page-load snapshots, and the branch chip is only patched
+  when the page was served inside a repository.
 - `/browse` has no auth; a malicious local page could probe the port. The `Host`
   allowlist and the absence of CORS headers mitigate reads, and the server is
   read-only.
@@ -221,7 +269,7 @@ document and the project document (project wins):
 |---|---|
 | Command | `/browse` registers a single command from the factory; no tools are exposed. |
 | State | The running server, its root, and the session port live in a module-local closure; nothing is persisted and no session entries are written. |
-| Lifecycle | The factory opens no socket; the server is created on `/browse` and closed idempotently by `/browse stop` and `session_shutdown`. |
+| Lifecycle | The factory opens no socket; the server is created on `/browse` and closed idempotently by `/browse stop`, by `session_shutdown`, and once its last page has been gone for the idle grace, which also ends every attached status stream. |
 
 ## Design notes
 
@@ -232,7 +280,10 @@ document and the project document (project wins):
   wins, otherwise a random port is drawn and cached after the first successful
   bind, so later starts reuse it (a conflict is reported and the next `/browse`
   rolls another). `/browse stop` and `session_shutdown` await the idempotent
-  `close()`; `session_shutdown` also clears the cached port.
+  `close()`; `session_shutdown` also clears the cached port. The page is the
+  server's only reader, so the channel reports the last page's departure after
+  `IDLE_STOP_MS` and the command closes the server and clears the chip — the
+  cached port survives, so the next `/browse` binds the same one.
 - **Pure routing.** `handleRequest(context, method, rawUrl, headers)` validates
   method and `Host`, parses the URL, matches a route, and runs every path
   through `paths.ts`. It returns a plain `ServeResponse`, so routing is tested
@@ -309,6 +360,21 @@ document and the project document (project wins):
   with the file view. `git diff --stat` supplies the chip totals and
   `changeDirs` derives the directory markers; the changed lines are highlighted
   per hunk by rebuilding the old and new sides for `lib/highlight`.
+- **Live status.** `live.ts` builds one snapshot per tick — the git status,
+  the `head` change index, the server's uptime, and its request count — and
+  `frameOf` serializes it as one `status` event. `createLiveChannel` holds the
+  attached pages and starts the ticker on the first attach, so an idle server
+  does no work; it shares a single in-flight snapshot between pages, drops a
+  page whose write fails, and stops on the last detach and on `close()`, which
+  `server.ts` calls before closing the socket. The last detach also arms one
+  idle-stop timer — a reload re-attaches and cancels it — and `server.ts` turns
+  that into the extension's `close()` and a cleared chip. Both providers are already
+  TTL-cached, so a tick re-reads at most one `git status`, and every read
+  failure degrades to `null` rather than a failed frame. The event-stream
+  headers and the `retry:` preamble live in `lib/http` with the rest of the
+  loopback policy, shared with plan's review page. The client half is
+  `live-client.ts`: one `EventSource`, one snapshot paint (`textContent` only,
+  never markup), one staleness timeout armed per frame, and a `pagehide` cleanup.
 - **Streaming responses.** The server streams `filePath` responses and
   suppresses bodies for `HEAD`, so large `/raw` files are not buffered.
 - **Root confinement over feature breadth.** The root is deliberately confined
@@ -325,7 +391,7 @@ document and the project document (project wins):
 | [`../../lib/escape.ts`](../../lib/escape.ts) | `escapeHtml`, the shared HTML escaping used by every renderer |
 | [`../../lib/highlight.ts`](../../lib/highlight.ts) | First-party escape-first syntax tokenizer for the code view (shared with `plan`) |
 | [`../../lib/web/index.ts`](../../lib/web/index.ts) | The shared Bytefly web brand system: tokens, base, components, layout, runtime, and markup |
-| `files.ts` | Classification (incl. Markdown), listings, text reads, sidebar tree |
+| `files.ts` | Classification (incl. Markdown), text reads, and one page-level walk (`directoryView`) that returns a directory's listing and its sidebar tree |
 | `diff.ts` | Pure unified-diff and porcelain-status parsing for the diff view |
 | `fuzzy.ts` | Fuzzy path matching and ranking for the quick-open palette |
 | `markdown.ts` | First-party escape-first Markdown-to-HTML renderer (fenced code highlighted; raw HTML through `raw-html.ts`) |
@@ -334,10 +400,13 @@ document and the project document (project wins):
 | `git.ts` | Read-only branch/dirty provider for the header chip |
 | `icons.ts` | Inline SVG sprite and the per-language mapping |
 | `client.ts` | The `/app.js` source (tree toggle, filter, sort, wrap, copy, quick open) |
-| `html.ts` | Page renderers, sortable headers, and the page-only `browse-*` CSS (the `bf-*` kit comes from `lib/web`) |
+| `live-client.ts` | The client's live status block: the event stream, the chips, the markers, and the footer line (interpolated into `client.ts`) |
+| `live.ts` | The live status snapshot, its frame, and the fan-out channel that ticks it |
+| `styles.ts` | The page-only `browse-*` stylesheet (the `bf-*` kit comes from `lib/web`) |
+| `html.ts` | Page renderers: the shared shell, the two-pane layout, the listing, the cards, and the diff body |
 | `router.ts` | Pure request handler: routes, the `/raw` sandbox policy, and the error page |
 | `server.ts` | `node:http` server: this extension's handler over the shared bind, writer, and close |
-| [`../../lib/http/index.ts`](../../lib/http/index.ts) | Loopback HTTP layer shared with `plan`: page/script/JSON headers, `ServeResponse`, the request-envelope helpers, bind/respond/close |
+| [`../../lib/http/index.ts`](../../lib/http/index.ts) | Loopback HTTP layer shared with `plan`: page/script/JSON/event-stream headers, `ServeResponse`, the request-envelope helpers, bind/respond/close, and `openEventStream` |
 | [`../../lib/browser.ts`](../../lib/browser.ts) | Cross-platform browser opener (shared with `plan`) |
 
 ## Testing
@@ -360,5 +429,11 @@ on first start, reused, and re-rolled after a conflict), the git status provider
 and provider (line kinds, line numbers, status and rename parsing, mode
 filtering, untracked all-add, unborn-HEAD fallback, literal pathspec, and TTL
 cache), the diff renderers (highlighted changed lines, marker sets, and chip
-totals), and the command
+totals), the live status feed (snapshot fields, degraded providers, the frame,
+and the channel's ticker driven by an injected timer, plus the idle stop armed on
+the last detach and cancelled by the next page or by `close()`), the `/events`
+route and
+its 404 when the channel is off, a real socket that reads a page's first frame
+and the ticker's next one and sees the stream end when the server closes, the
+live chrome a page renders when on and not when off, and the command
 lifecycle with injected seams.

package/extensions/file-browse/client.ts

@@ -12,6 +12,7 @@
  */
 
 import { keysDialogScript, SIDEBAR_COLLAPSE_MAX, THEME_TOGGLE_JS } from "../../lib/web/index.ts";
+import { LIVE_CLIENT_JS } from "./live-client.ts";
 
 export const CLIENT_JS = `(function () {
 	"use strict";
@@ -716,5 +717,6 @@ export const CLIENT_JS = `(function () {
 
 	// The control starts in the state the rendered tree implies.
 	syncFoldButton();
-})();
+
+${LIVE_CLIENT_JS}})();
 `;

package/extensions/file-browse/config.ts

@@ -36,6 +36,10 @@ export interface ServeConfig {
 	diffContext: number;
 	/** Diff lines rendered before the view is truncated. */
 	maxDiffLines: number;
+	/** Push live status to open pages over `/events`. */
+	live: boolean;
+	/** How often a connected page is sent a status frame, in ms. */
+	liveIntervalMs: number;
 }
 
 export const DEFAULT_CONFIG: ServeConfig = {
@@ -52,6 +56,8 @@ export const DEFAULT_CONFIG: ServeConfig = {
 	gitDiff: true,
 	diffContext: 3,
 	maxDiffLines: 4000,
+	live: true,
+	liveIntervalMs: 3000,
 };
 
 /** Base of the per-session port range. */
@@ -60,6 +66,21 @@ export const PORT_BASE = 4780;
 /** Number of ports in the per-session range. */
 export const PORT_RANGE = 1000;
 
+/** Fastest live-status cadence a page may be given, short enough to watch and
+ * long enough that the 2 s provider caches absorb most ticks. */
+export const LIVE_INTERVAL_MIN = 250;
+
+/** Slowest live-status cadence, so a page cannot look abandoned. */
+export const LIVE_INTERVAL_MAX = 60_000;
+
+/**
+ * How long the server keeps listening once the last page has gone. A reload or a
+ * navigation detaches the stream and re-attaches within a moment, so the grace has
+ * to outlast one; a closed window never re-attaches, and the port is released
+ * instead of listening for nobody until the session ends.
+ */
+export const IDLE_STOP_MS = 10_000;
+
 /** A random port in the per-session range `PORT_BASE`–`PORT_BASE + PORT_RANGE - 1`. */
 export function randomPort(): number {
 	return PORT_BASE + randomInt(PORT_RANGE);
@@ -85,6 +106,8 @@ export function normalizeConfig(
 		gitDiff: asBoolean(raw.gitDiff, base.gitDiff),
 		diffContext: clampInteger(raw.diffContext, base.diffContext, 0, 100),
 		maxDiffLines: clampInteger(raw.maxDiffLines, base.maxDiffLines, 1, 1_000_000),
+		live: asBoolean(raw.live, base.live),
+		liveIntervalMs: clampInteger(raw.liveIntervalMs, base.liveIntervalMs, LIVE_INTERVAL_MIN, LIVE_INTERVAL_MAX),
 	};
 }
 

package/extensions/file-browse/files.ts

@@ -8,6 +8,7 @@
 import type { Dirent, Stats } from "node:fs";
 import { readFile, readdir, stat, lstat } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
+import { mapConcurrent } from "../../lib/pool.ts";
 import { HttpError } from "./paths.ts";
 
 export type EntryKind = "directory" | "text" | "image" | "binary";
@@ -188,63 +189,168 @@ function toAbs(root: string, rel: string): string {
 	return rel ? join(root, ...rel.split("/")) : root;
 }
 
-/** List a directory, sorted (directories first, then case-insensitive name). */
-export async function listDirectory(root: string, relDir: string, limit: number): Promise<Listing> {
+/** The `Dirent` fields a listing reads; a test's fake need not be a real `Dirent`. */
+export interface DirectoryEntryInfo {
+	name: string;
+	isDirectory(): boolean;
+	isSymbolicLink(): boolean;
+}
+
+/** The `Stats` fields a listing reads. */
+export interface DirectoryStats {
+	size: number;
+	mtimeMs: number;
+	isDirectory(): boolean;
+}
+
+/**
+ * The three filesystem reads a listing makes.
+ *
+ * Injected so a test can observe them: the interesting property — a directory is
+ * read once per entry, not once per entry *and* once per row drawn — is a count,
+ * not a value, and a wall-clock assertion would be flaky on a loaded machine.
+ */
+export interface DirectoryFs {
+	readdir(path: string): Promise<DirectoryEntryInfo[]>;
+	lstat(path: string): Promise<DirectoryStats>;
+	stat(path: string): Promise<DirectoryStats>;
+}
+
+/** Production reads; a symlink's size and kind come from the target. */
+const NODE_DIRECTORY_FS: DirectoryFs = {
+	readdir: (path) => readdir(path, { withFileTypes: true }),
+	lstat: (path) => lstat(path),
+	stat: (path) => stat(path),
+};
+
+/** Reads in flight per listing: enough to hide latency, bounded against a burst. */
+const LISTING_CONCURRENCY = 32;
+
+/** A row while it is still missing its metadata. */
+interface Row {
+	name: string;
+	rel: string;
+	isDir: boolean;
+	isSymlink: boolean;
+	broken: boolean;
+	size: number;
+	mtimeMs: number;
+}
+
+/**
+ * Resolve one symlink: the link's own stat, then the target's.
+ *
+ * A symlink's directory-ness is the target's, so this cannot wait until after
+ * the sort; it is also the only entry whose classification needs a read.
+ */
+async function resolveSymlink(fs: DirectoryFs, absDir: string, row: Row): Promise<void> {
+	const abs = join(absDir, row.name);
+	try {
+		const info = await fs.lstat(abs);
+		row.size = info.size;
+		row.mtimeMs = info.mtimeMs;
+	} catch {
+		// Vanished between readdir and lstat: the target read decides below.
+	}
+	try {
+		const target = await fs.stat(abs);
+		row.isDir = target.isDirectory();
+		row.size = target.size;
+		row.mtimeMs = target.mtimeMs;
+	} catch {
+		row.broken = true;
+	}
+}
+
+/**
+ * List a directory, sorted (directories first, then case-insensitive name).
+ *
+ * A listing is latency per entry, not work per entry, so it is read in three
+ * passes instead of one entry at a time:
+ *
+ * 1. `readdir`, whose dirents already say whether each name is a directory;
+ * 2. the symlinks only, resolved through the pool, because their kind is the
+ *    target's and the sort needs it;
+ * 3. the kept rows only, `stat`ed through the pool — so a directory of three
+ *    thousand names pays for the two thousand it draws, not for every name, and
+ *    pays them concurrently instead of in turn.
+ *
+ * `total` is still the directory's full entry count and `truncated` its `> limit`
+ * flip, so the page can say how many were dropped. Ties keep `readdir` order:
+ * `sort` is stable and the rows arrive unsorted.
+ */
+export async function listDirectory(
+	root: string,
+	relDir: string,
+	limit: number,
+	fs: DirectoryFs = NODE_DIRECTORY_FS,
+): Promise<Listing> {
 	const absDir = toAbs(root, relDir);
-	let dirents: Dirent[];
+	let dirents: DirectoryEntryInfo[];
 	try {
-		dirents = await readdir(absDir, { withFileTypes: true });
+		dirents = await fs.readdir(absDir);
 	} catch {
 		throw new HttpError(404, "That folder could not be read.");
 	}
 
-	const entries: DirEntry[] = [];
-	for (const dirent of dirents) {
-		const abs = join(absDir, dirent.name);
-		const isSymlink = dirent.isSymbolicLink();
-		let isDir = dirent.isDirectory();
-		let broken = false;
-		let size = 0;
-		let mtimeMs = 0;
-		try {
-			const info = isSymlink ? await lstat(abs) : await stat(abs);
-			size = info.size;
-			mtimeMs = info.mtimeMs;
-		} catch {
-			// Directory entry vanished between readdir and stat.
-		}
-		if (isSymlink) {
-			try {
-				const target = await stat(abs);
-				isDir = target.isDirectory();
-				size = target.size;
-				mtimeMs = target.mtimeMs;
-			} catch {
-				broken = true;
-			}
-		}
-		const kind: EntryKind = isDir ? "directory" : classifyByName(dirent.name);
-		entries.push({
+	const links: Row[] = [];
+	const rows: Row[] = dirents.map((dirent) => {
+		const row: Row = {
 			name: dirent.name,
 			rel: relDir ? `${relDir}/${dirent.name}` : dirent.name,
-			isDir,
-			isSymlink,
-			broken,
-			size,
-			mtimeMs,
-			kind,
-			isImage: !isDir && kind === "image",
-		});
-	}
+			isDir: dirent.isDirectory(),
+			isSymlink: dirent.isSymbolicLink(),
+			broken: false,
+			size: 0,
+			mtimeMs: 0,
+		};
+		if (row.isSymlink) links.push(row);
+		return row;
+	});
+
+	await mapConcurrent(links, LISTING_CONCURRENCY, (row) => resolveSymlink(fs, absDir, row));
 
-	entries.sort((a, b) => {
+	// Directories first, then case-insensitive name. The sort runs before the cap,
+	// so the rows that survive it are the rows that would have been drawn.
+	rows.sort((a, b) => {
 		if (a.isDir !== b.isDir) return a.isDir ? -1 : 1;
 		return a.name.toLowerCase().localeCompare(b.name.toLowerCase());
 	});
 
-	const total = entries.length;
+	const total = rows.length;
 	const truncated = total > limit;
-	return { entries: truncated ? entries.slice(0, limit) : entries, total, truncated };
+	const kept = truncated ? rows.slice(0, limit) : rows;
+
+	await mapConcurrent(
+		kept.filter((row) => !row.isSymlink),
+		LISTING_CONCURRENCY,
+		async (row) => {
+			try {
+				const info = await fs.stat(join(absDir, row.name));
+				row.size = info.size;
+				row.mtimeMs = info.mtimeMs;
+			} catch {
+				// Directory entry vanished between readdir and stat.
+			}
+		},
+	);
+
+	const entries: DirEntry[] = kept.map((row) => {
+		const kind: EntryKind = row.isDir ? "directory" : classifyByName(row.name);
+		return {
+			name: row.name,
+			rel: row.rel,
+			isDir: row.isDir,
+			isSymlink: row.isSymlink,
+			broken: row.broken,
+			size: row.size,
+			mtimeMs: row.mtimeMs,
+			kind,
+			isImage: !row.isDir && kind === "image",
+		};
+	});
+
+	return { entries, total, truncated };
 }
 
 /** Read a file into a renderable view, honouring the size and line caps. */
@@ -305,12 +411,37 @@ export async function buildTree(root: string, currentRel: string, limit: number)
 	return buildNode(root, "", currentRel, basename(root) || root, limit);
 }
 
+/** A directory page's two views of one directory. */
+export interface DirectoryView {
+	/** The current directory's own rows, for the page's listing. */
+	listing: Listing;
+	/** The sidebar tree, with the current path expanded. */
+	tree: TreeNode;
+}
+
+/**
+ * One walk for a directory page: the listing it draws, and the tree that shows
+ * where it sits.
+ *
+ * `listDirectory` is what decides whether the directory can be read at all, so it
+ * runs first and its 404 is the page's error. The walk then reuses that listing
+ * for the same directory instead of reading it a second time; the ancestors are
+ * still read once each, which is what the tree needs.
+ */
+export async function directoryView(root: string, currentRel: string, limit: number): Promise<DirectoryView> {
+	const listing = await listDirectory(root, currentRel, limit);
+	const tree = await buildNode(root, "", currentRel, basename(root) || root, limit, { rel: currentRel, listing });
+	return { listing, tree };
+}
+
 async function buildNode(
 	root: string,
 	relDir: string,
 	currentRel: string,
 	label: string,
 	limit: number,
+	/** A listing the caller already read for this directory, so it is not re-read. */
+	known?: { rel: string; listing: Listing },
 ): Promise<TreeNode> {
 	const node: TreeNode = {
 		name: label,
@@ -322,10 +453,14 @@ async function buildNode(
 		children: [],
 	};
 	let listing: Listing;
-	try {
-		listing = await listDirectory(root, relDir, limit);
-	} catch {
-		return node;
+	if (known && known.rel === relDir) {
+		listing = known.listing;
+	} else {
+		try {
+			listing = await listDirectory(root, relDir, limit);
+		} catch {
+			return node;
+		}
 	}
 	for (const entry of listing.entries) {
 		const child: TreeNode = {
@@ -340,7 +475,7 @@ async function buildNode(
 		if (entry.isDir) {
 			const onPath = currentRel === entry.rel || currentRel.startsWith(`${entry.rel}/`);
 			if (onPath) {
-				child.children = (await buildNode(root, entry.rel, currentRel, entry.name, limit)).children;
+				child.children = (await buildNode(root, entry.rel, currentRel, entry.name, limit, known)).children;
 			}
 		}
 		node.children.push(child);