@vellumai/assistant 0.8.9-staging.2 → 0.8.9-staging.4

package/src/runtime/routes/memory-v3-routes.ts

@@ -1,278 +1,32 @@
 /**
- * Memory v3 route definitions — tree-gardening + core-editing operations for
- * the leaf-tree memory model.
+ * Memory v3 route definitions — live-lane maintenance operations for the
+ * section-lane memory model.
  *
- * The daemon owns the live tree, so the *mutating* gardening verbs
- * (`reconcile`, `set-core --write`, `rebuild-index`) run here, inside the
- * daemon process, where the in-memory shadow lanes can be invalidated after a
- * write. The read-only `health` report and the `set-core` cost preview also
- * route through the daemon so it stays the single source of truth for the live
- * workspace tree.
+ * The daemon owns the live shadow lanes, so the maintenance verbs run here,
+ * inside the daemon process, where the in-memory lanes can be invalidated or
+ * rebuilt after a write:
  *
- * Each route's behavior lives in a small DI-friendly `handle*` function that
- * takes an optional `MemoryV3Deps` (filesystem overrides) so tests can drive it
- * against a temp workspace without mocking module globals. The exported
- * `RouteDefinition`s are thin `RouteHandlerArgs` adapters over those handlers.
+ *   - `rebuild-index` — drop the cached lanes so the next turn rebuilds.
+ *   - `backfill-sections` — one-time full embed of every page's sections into
+ *     the dense store, advancing the maintain high-water mark.
+ *
+ * Each route's behavior lives in a small DI-friendly `handle*` function (with an
+ * injectable config seam) so tests can drive it without mocking module globals.
+ * The exported `RouteDefinition`s are thin adapters over those handlers.
  */
 
-import { writeFile } from "node:fs/promises";
-import { join } from "node:path";
-
 import { z } from "zod";
 
-import { getPageIndex } from "../../memory/v2/page-index.js";
-import { loadCore } from "../../plugins/defaults/memory-v3-shadow/core.js";
-import {
-  computeV3Health,
-  renderV3Health,
-} from "../../plugins/defaults/memory-v3-shadow/health.js";
-import {
-  type LeafRef,
-  reconcileTree,
-} from "../../plugins/defaults/memory-v3-shadow/reconcile.js";
+import { getConfig } from "../../config/loader.js";
+import type { AssistantConfig } from "../../config/types.js";
+import { backfillAllSections } from "../../plugins/defaults/memory-v3-shadow/maintain-job.js";
 import { invalidateLanes } from "../../plugins/defaults/memory-v3-shadow/shadow-plugin.js";
-import {
-  coreSlugs,
-  loadLeafTree,
-  resolveDataDir,
-} from "../../plugins/defaults/memory-v3-shadow/tree.js";
-import type {
-  LeafPath,
-  LeafTree,
-  Slug,
-} from "../../plugins/defaults/memory-v3-shadow/types.js";
 import { getLogger } from "../../util/logger.js";
-import { getWorkspaceDir } from "../../util/platform.js";
 import { ACTOR_PRINCIPALS, type RoutePolicy } from "../auth/route-policy.js";
-import { RouteError } from "./errors.js";
-import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+import type { RouteDefinition } from "./types.js";
 
 const log = getLogger("memory-v3-routes");
 
-/**
- * Filesystem location overrides. Production callers omit these and the handlers
- * resolve the live workspace; tests inject a temp workspace + data dir to
- * exercise the handlers without mocking module globals.
- */
-export interface MemoryV3Deps {
-  dataDir?: string;
-  workspaceDir?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Shared loading helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Load the live leaf tree + its full slug universe.
- *
- * Page `leaves:` frontmatter is the authoritative source of page→leaf
- * membership: we build a `pageLeaves` map from the page index and union it over
- * `assignments.json` via `loadLeafTree(dataDir, pageLeaves)`, and derive the
- * slug universe (`allSlugs`) from the page index itself. This mirrors
- * `maybePrependV3Health` in `memory/v2/consolidation-job.ts` so the CLI
- * `health` / `set-core` cost computations agree with the consolidation-injected
- * health block instead of disagreeing by reading stale assignments.json only.
- */
-async function loadTreeAndSlugs(deps?: MemoryV3Deps): Promise<{
-  dataDir: string;
-  tree: LeafTree;
-  allSlugs: Slug[];
-}> {
-  const workspaceDir = deps?.workspaceDir ?? getWorkspaceDir();
-  const dataDir = deps?.dataDir ?? resolveDataDir();
-
-  // Each page contributes its `leaves:` frontmatter as the authoritative leaf
-  // set for that slug; the slug universe is every page the index knows about.
-  const pageIndex = await getPageIndex(workspaceDir);
-  const pageLeaves = new Map<Slug, LeafPath[]>();
-  const allSlugs: Slug[] = [];
-  for (const entry of pageIndex.entries) {
-    pageLeaves.set(entry.slug, entry.leaves);
-    allSlugs.push(entry.slug);
-  }
-
-  const tree = await loadLeafTree(dataDir, pageLeaves);
-  return { dataDir, tree, allSlugs };
-}
-
-// ---------------------------------------------------------------------------
-// health
-// ---------------------------------------------------------------------------
-
-const MemoryV3HealthResultSchema = z.object({
-  /** Pre-rendered, human-readable report. Empty string when all-green. */
-  rendered: z.string(),
-  /** The structural counts, for `--json` consumers. */
-  counts: z.object({
-    unassigned: z.number(),
-    danglingRefs: z.number(),
-    novelClusters: z.number(),
-    oversizedLeaves: z.number(),
-    tinyLeaves: z.number(),
-  }),
-});
-export type MemoryV3HealthResult = z.infer<typeof MemoryV3HealthResultSchema>;
-
-export async function handleMemoryV3Health(
-  deps?: MemoryV3Deps,
-): Promise<MemoryV3HealthResult> {
-  const { dataDir, tree, allSlugs } = await loadTreeAndSlugs(deps);
-  const core = await loadCore(dataDir);
-  const report = computeV3Health({ tree, allSlugs, core });
-  return {
-    rendered: renderV3Health(report),
-    counts: {
-      unassigned: report.unassigned.length,
-      danglingRefs: report.danglingRefs.length,
-      novelClusters: report.novelClusters.length,
-      oversizedLeaves: report.oversizedLeaves.length,
-      tinyLeaves: report.tinyLeaves.length,
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// set-core
-// ---------------------------------------------------------------------------
-
-const MemoryV3SetCoreBodySchema = z.object({
-  /** Leaves to add to the always-on core set. */
-  add: z.array(z.string()).optional(),
-  /** Leaves to remove from the always-on core set. */
-  remove: z.array(z.string()).optional(),
-  /**
-   * When true, persist the new core to `core.json` and invalidate the lanes.
-   * When false (default), compute the preview WITHOUT writing.
-   */
-  write: z.boolean().optional(),
-});
-export type MemoryV3SetCoreBody = z.infer<typeof MemoryV3SetCoreBodySchema>;
-
-const MemoryV3SetCoreResultSchema = z.object({
-  /** The core leaf set that would result (or did result, when `write`). */
-  nextCore: z.array(z.string()),
-  /** Number of unique page slugs the new core set pins always-on. */
-  alwaysOnPageCount: z.number(),
-  /** Whether `core.json` was written. */
-  written: z.boolean(),
-});
-export type MemoryV3SetCoreResult = z.infer<typeof MemoryV3SetCoreResultSchema>;
-
-/** Wire-format error code for a `set-core` add referencing an unknown leaf. */
-export const MEMORY_V3_UNKNOWN_LEAF_CODE = "MEMORY_V3_UNKNOWN_LEAF";
-
-/** Thrown when a `set-core` add entry does not exist in the live tree. */
-export class UnknownLeafError extends Error {
-  constructor(public readonly unknown: LeafPath[]) {
-    super(
-      `Unknown leaf path(s) — not present in the tree: ${unknown.join(", ")}`,
-    );
-    this.name = "UnknownLeafError";
-  }
-}
-
-/** Persist the always-on core set back to `<dataDir>/core.json`. */
-async function writeCore(dataDir: string, alwaysOn: LeafPath[]): Promise<void> {
-  await writeFile(
-    join(dataDir, "core.json"),
-    `${JSON.stringify({ alwaysOn }, null, 2)}\n`,
-  );
-}
-
-export async function handleMemoryV3SetCore(
-  body: MemoryV3SetCoreBody,
-  deps?: MemoryV3Deps,
-): Promise<MemoryV3SetCoreResult> {
-  const add = body.add ?? [];
-  const remove = body.remove ?? [];
-  const { dataDir, tree } = await loadTreeAndSlugs(deps);
-
-  // Validate every ADD entry exists in the live tree. Removing an entry that is
-  // already absent is a no-op (idempotent), so only adds are validated.
-  const unknown = add.filter((leaf) => !tree.leaves.has(leaf));
-  if (unknown.length > 0) throw new UnknownLeafError(unknown);
-
-  const core = await loadCore(dataDir);
-  for (const leaf of remove) core.delete(leaf);
-  for (const leaf of add) core.add(leaf);
-
-  // Drop any pre-existing core entry that no longer maps to a live leaf, so the
-  // preview reflects what the tree can actually pin. Sorted for stable output.
-  const nextCore = [...core].filter((leaf) => tree.leaves.has(leaf)).sort();
-  const nextCoreSet = new Set<LeafPath>(nextCore);
-
-  // Cost preview: the number of UNIQUE page slugs the new core pins always-on.
-  const alwaysOnPageCount = coreSlugs(tree, nextCoreSet).size;
-
-  if (body.write === true) {
-    await writeCore(dataDir, nextCore);
-    invalidateLanes();
-    log.info(
-      { coreSize: nextCore.length, alwaysOnPageCount },
-      "memory-v3 core updated",
-    );
-  }
-
-  return { nextCore, alwaysOnPageCount, written: body.write === true };
-}
-
-// ---------------------------------------------------------------------------
-// reconcile
-// ---------------------------------------------------------------------------
-
-const MemoryV3ReconcileResultSchema = z.object({
-  renames: z.array(
-    z.object({
-      id: z.string().optional(),
-      oldPath: z.string(),
-      newPath: z.string(),
-    }),
-  ),
-  deleted: z.array(z.string()),
-  prunedCore: z.array(z.string()),
-});
-export type MemoryV3ReconcileResult = z.infer<
-  typeof MemoryV3ReconcileResultSchema
->;
-
-/**
- * Reconcile page + core references against the live on-disk tree.
- *
- * `prevLeaves` describes the tree as it was BEFORE the maintainer's on-disk
- * restructuring. We derive it from the current leaf set, which makes reconcile
- * a safe convergence pass: renames/deletes already applied on disk diff to
- * nothing, while it still rewrites any page/core ref left dangling and prunes
- * stale core entries (and fail-closed restores on a residual dangling ref).
- * `reconcileTree` snapshots, applies, validates, and invalidates the lanes.
- */
-export async function handleMemoryV3Reconcile(
-  deps?: MemoryV3Deps,
-): Promise<MemoryV3ReconcileResult> {
-  const workspaceDir = deps?.workspaceDir ?? getWorkspaceDir();
-  const dataDir = deps?.dataDir ?? resolveDataDir();
-  // v1: prev == current is intentional. Without a captured prior leaf snapshot
-  // we cannot detect renames/moves/splits, so this runs as a convergence /
-  // dangling-ref prune pass. Full rename detection is a follow-up.
-  const prevLeaves = await loadPrevLeaves(dataDir);
-
-  const result = await reconcileTree({ prevLeaves, dataDir, workspaceDir });
-  return {
-    renames: result.renames,
-    deleted: result.deleted,
-    prunedCore: result.prunedCore,
-  };
-}
-
-/** The current leaf set as `LeafRef`s (path + stable id when present). */
-async function loadPrevLeaves(dataDir: string): Promise<LeafRef[]> {
-  const tree = await loadLeafTree(dataDir);
-  return [...tree.leaves.values()].map((node) => ({
-    path: node.path,
-    ...(node.frontmatter.id ? { id: node.frontmatter.id } : {}),
-  }));
-}
-
 // ---------------------------------------------------------------------------
 // rebuild-index
 // ---------------------------------------------------------------------------
@@ -285,7 +39,7 @@ export type MemoryV3RebuildIndexResult = z.infer<
 >;
 
 /**
- * Invalidate the v3 shadow lanes so the next turn rebuilds the tree/needle
+ * Invalidate the v3 shadow lanes so the next turn rebuilds the section index
  * from the current on-disk state. Runs in-daemon so it acts on the live
  * process's cached lanes (an in-CLI call would invalidate nothing).
  */
@@ -296,21 +50,47 @@ export async function handleMemoryV3RebuildIndex(): Promise<MemoryV3RebuildIndex
 }
 
 // ---------------------------------------------------------------------------
-// Route definitions (RouteHandlerArgs adapters over the handlers above)
+// backfill-sections
 // ---------------------------------------------------------------------------
 
-/** Read-only verbs (the `health` report) require only `settings.read`. */
-const READ_POLICY: RoutePolicy = {
-  requiredScopes: ["settings.read"],
-  allowedPrincipalTypes: ACTOR_PRINCIPALS,
-};
+const MemoryV3BackfillSectionsResultSchema = z.object({
+  /** Pages whose sections were embedded this pass. */
+  articles: z.number(),
+  /** Total section points upserted across all articles. */
+  sections: z.number(),
+  /** Pages whose embed threw (and was contained). */
+  failures: z.number(),
+});
+export type MemoryV3BackfillSectionsResult = z.infer<
+  typeof MemoryV3BackfillSectionsResultSchema
+>;
 
 /**
- * Mutating verbs require `settings.write`. `set-core --write`, `reconcile`, and
- * `rebuild-index` write `core.json`, rewrite page frontmatter, and invalidate
- * the live lanes, so a `settings.read`-only principal must not reach them.
- * (`set-core` without `write` is a preview, but it shares this route, so the
- * route as a whole is gated on write.)
+ * One-time full backfill of the section dense store: embed EVERY page in the
+ * index — including synthetic skill/CLI rows the incremental maintain pass
+ * skips — into the `memory_v3_sections` collection, then advance the maintain
+ * high-water mark so the next incremental run deltas from here. Runs in-daemon
+ * so it uses the live config and so the maintain checkpoint it advances is the
+ * one the daemon's incremental pass reads.
+ *
+ * `config` is injectable for tests; production resolves the live config.
+ */
+export async function handleMemoryV3BackfillSections(
+  config: AssistantConfig = getConfig(),
+): Promise<MemoryV3BackfillSectionsResult> {
+  const outcome = await backfillAllSections(config);
+  log.info(outcome, "memory-v3 section backfill complete (route)");
+  return outcome;
+}
+
+// ---------------------------------------------------------------------------
+// Route definitions (RouteHandlerArgs adapters over the handlers above)
+// ---------------------------------------------------------------------------
+
+/**
+ * Mutating verbs require `settings.write`. `rebuild-index` invalidates the live
+ * lanes and `backfill-sections` writes the dense store + advances the maintain
+ * checkpoint, so a `settings.read`-only principal must not reach them.
  */
 const WRITE_POLICY: RoutePolicy = {
   requiredScopes: ["settings.write"],
@@ -319,54 +99,24 @@ const WRITE_POLICY: RoutePolicy = {
 
 export const ROUTES: RouteDefinition[] = [
   {
-    operationId: "memory_v3_health",
-    method: "POST",
-    policy: READ_POLICY,
-    endpoint: "memory/v3/health",
-    handler: () => handleMemoryV3Health(),
-    summary: "Print the v3 structural health report (read-only)",
-    tags: ["memory"],
-    responseBody: MemoryV3HealthResultSchema,
-  },
-  {
-    operationId: "memory_v3_set_core",
+    operationId: "memory_v3_rebuild_index",
     method: "POST",
     policy: WRITE_POLICY,
-    endpoint: "memory/v3/set-core",
-    handler: async ({ body = {} }: RouteHandlerArgs) => {
-      try {
-        return await handleMemoryV3SetCore(body as MemoryV3SetCoreBody);
-      } catch (err) {
-        if (err instanceof UnknownLeafError) {
-          throw new RouteError(err.message, MEMORY_V3_UNKNOWN_LEAF_CODE, 422);
-        }
-        throw err;
-      }
-    },
-    summary: "Add/remove always-on core leaves (validates + previews cost)",
+    endpoint: "memory/v3/rebuild-index",
+    handler: () => handleMemoryV3RebuildIndex(),
+    summary: "Invalidate the v3 lanes so the next turn rebuilds",
     tags: ["memory"],
-    requestBody: MemoryV3SetCoreBodySchema,
-    responseBody: MemoryV3SetCoreResultSchema,
+    responseBody: MemoryV3RebuildIndexResultSchema,
   },
   {
-    operationId: "memory_v3_reconcile",
+    operationId: "memory_v3_backfill_sections",
     method: "POST",
     policy: WRITE_POLICY,
-    endpoint: "memory/v3/reconcile",
-    handler: () => handleMemoryV3Reconcile(),
+    endpoint: "memory/v3/backfill-sections",
+    handler: () => handleMemoryV3BackfillSections(),
     summary:
-      "v1 convergence/prune pass over page+core refs (no rename detection without a prior snapshot)",
+      "One-time: embed every page's sections (incl synthetic skill/CLI rows) into the dense store",
     tags: ["memory"],
-    responseBody: MemoryV3ReconcileResultSchema,
-  },
-  {
-    operationId: "memory_v3_rebuild_index",
-    method: "POST",
-    policy: WRITE_POLICY,
-    endpoint: "memory/v3/rebuild-index",
-    handler: () => handleMemoryV3RebuildIndex(),
-    summary: "Invalidate the v3 lanes so the next turn rebuilds",
-    tags: ["memory"],
-    responseBody: MemoryV3RebuildIndexResultSchema,
+    responseBody: MemoryV3BackfillSectionsResultSchema,
   },
 ];

package/src/runtime/routes/playground/__tests__/force-compact.test.ts

@@ -18,8 +18,8 @@ mock.module("../helpers.js", () => ({
   addPlaygroundMessage: async () => ({ id: "msg-test" }),
 }));
 
-import type { ContextWindowResult } from "../../../../context/window-manager.js";
 import type { Conversation } from "../../../../daemon/conversation.js";
+import type { ContextWindowResult } from "../../../../plugins/defaults/compaction/window-manager.js";
 import type { Message } from "../../../../providers/types.js";
 import { RouteError } from "../../errors.js";
 import { ROUTES } from "../index.js";

package/src/runtime/routes/stt-routes.ts

@@ -17,6 +17,7 @@ import { listProviderEntries } from "../../providers/speech-to-text/provider-cat
 import { resolveBatchTranscriber } from "../../providers/speech-to-text/resolve.js";
 import { normalizeSttError } from "../../stt/daemon-batch-transcriber.js";
 import type { BatchTranscriber, SttErrorCategory } from "../../stt/types.js";
+import { SttError } from "../../stt/types.js";
 import { getLogger } from "../../util/logger.js";
 import {
   FFMPEG_TRANSCODE_TIMEOUT_MS,
@@ -141,6 +142,27 @@ async function toWav(inputPath: string, isVideo: boolean): Promise<string> {
   return wavPath;
 }
 
+/**
+ * Call the provider and tag any failure as an {@link SttError} so callers can
+ * distinguish provider failures (categorized HTTP statuses) from local
+ * preprocessing failures (ffmpeg/ffprobe), which stay on the bad-gateway path.
+ */
+async function transcribeChunk(
+  transcriber: BatchTranscriber,
+  audioBuffer: Buffer,
+): Promise<string> {
+  try {
+    const result = await transcriber.transcribe({
+      audio: audioBuffer,
+      mimeType: "audio/wav",
+      signal: AbortSignal.timeout(STT_REQUEST_TIMEOUT_MS),
+    });
+    return result.text;
+  } catch (err) {
+    throw normalizeSttError(err);
+  }
+}
+
 async function transcribeWithProvider(
   audioPath: string,
   transcriber: BatchTranscriber,
@@ -151,12 +173,7 @@ async function transcribeWithProvider(
   // If small enough, send directly
   if (fileSize <= STT_CHUNK_MAX_BYTES) {
     const audioBuffer = await readFile(audioPath);
-    const result = await transcriber.transcribe({
-      audio: audioBuffer,
-      mimeType: "audio/wav",
-      signal: AbortSignal.timeout(STT_REQUEST_TIMEOUT_MS),
-    });
-    return result.text;
+    return transcribeChunk(transcriber, audioBuffer);
   }
 
   // Split into chunks for large files
@@ -175,12 +192,8 @@ async function transcribeWithProvider(
         `  Transcribing chunk ${i + 1}/${chunks.length}...\n`,
       );
       const audioBuffer = await readFile(chunks[i]);
-      const result = await transcriber.transcribe({
-        audio: audioBuffer,
-        mimeType: "audio/wav",
-        signal: AbortSignal.timeout(STT_REQUEST_TIMEOUT_MS),
-      });
-      if (result.text) parts.push(result.text);
+      const text = await transcribeChunk(transcriber, audioBuffer);
+      if (text) parts.push(text);
     }
 
     return parts.join(" ");
@@ -363,6 +376,26 @@ async function handleTranscribeFile({ body }: RouteHandlerArgs) {
       durationSeconds,
     };
   } catch (err) {
+    // Only provider failures (tagged as SttError by transcribeChunk) are
+    // categorized into HTTP statuses. Local preprocessing failures (ffmpeg/
+    // ffprobe) stay on the bad-gateway path so their stderr never decides the
+    // category (e.g. a path under a dir named "403" must not become a 401).
+    if (err instanceof SttError) {
+      // Auth/rate-limit/timeout/invalid-audio are user-config or transient
+      // conditions, not daemon defects, so log them at warn to keep them out
+      // of error telemetry. Reserve error level (with the raw err for a Sentry
+      // stack) for genuine provider/unexpected failures.
+      if (err.category === "provider-error") {
+        log.error({ err, filePath }, "File transcription failed");
+      } else {
+        log.warn(
+          { category: err.category, message: err.message, filePath },
+          "File transcription failed",
+        );
+      }
+      throw STT_ERROR_MAP[err.category]();
+    }
+
     log.error({ err, filePath }, "File transcription failed");
     throw new BadGatewayError(
       err instanceof Error ? err.message : "Transcription failed",

package/src/runtime/routes/workspace-routes.ts

@@ -46,14 +46,24 @@ const workspaceTreeEntrySchema = z.object({
 
 type TreeEntry = z.infer<typeof workspaceTreeEntrySchema>;
 
-// Total number of filesystem entries we're willing to traverse when computing
-// recursive directory sizes for a single tree listing. The budget is shared
-// across every directory in the response so a giant `repos/` checkout cannot
-// starve the request — once exhausted, remaining directories report `size:
-// null` (caller renders an unknown-size placeholder). 50k is generous for
-// typical workspaces (sounds, db, logs) while bailing fast on multi-repo
-// trees.
-const DIR_SIZE_TOTAL_ENTRY_BUDGET = 50_000;
+// Recursive directory sizing walks the filesystem synchronously, so it is
+// bounded by two caps that work together:
+//
+// - `DIR_SIZE_PER_DIR_ENTRY_BUDGET` caps a single directory. No one giant
+//   subtree (e.g. a `node_modules/` or `repos/` checkout) can consume the whole
+//   listing's budget and starve its siblings; only the oversized directory
+//   itself reports `size: null` (the caller renders an unknown-size
+//   placeholder) while every other folder still shows an accurate size.
+// - `DIR_SIZE_TOTAL_ENTRY_BUDGET` caps the listing as a whole, so a workspace
+//   with many large sibling directories still can't block the daemon event loop
+//   for an unbounded amount of time. Once it is exhausted, the remaining
+//   directories report `size: null`.
+//
+// Each directory is allotted `min(per-dir cap, remaining listing budget)`
+// entries, and whatever it actually consumes is deducted from the listing
+// budget.
+const DIR_SIZE_PER_DIR_ENTRY_BUDGET = 250_000;
+const DIR_SIZE_TOTAL_ENTRY_BUDGET = 1_000_000;
 
 interface DirSizeBudget {
   remaining: number;
@@ -61,13 +71,13 @@ interface DirSizeBudget {
 
 /**
  * Recursively sum the byte size of every regular file under `absPath`,
- * sharing a single entry budget across all directories in the same listing.
+ * traversing up to `budget.remaining` filesystem entries.
  *
  * Returns:
  * - the total size in bytes when the entire subtree was traversed within
  *   budget
- * - `null` if the shared budget was exhausted before completion (the caller
- *   surfaces that as an unknown size in the UI)
+ * - `null` if the budget was exhausted before completion (the caller surfaces
+ *   that as an unknown size in the UI)
  *
  * Symlinks are not followed. We rely on `withFileTypes` so we never `stat`
  * directories purely to discover their type.
@@ -108,6 +118,27 @@ function computeDirSize(absPath: string, budget: DirSizeBudget): number | null {
   return total;
 }
 
+/**
+ * Compute a directory's recursive size while drawing from a shared listing
+ * budget. The directory is allotted at most `DIR_SIZE_PER_DIR_ENTRY_BUDGET`
+ * entries — and never more than the listing has left — and whatever it consumes
+ * is deducted from `listingBudget` so the next sibling sees the reduced
+ * remainder. Returns `null` (unknown size) when the allotment is exhausted.
+ */
+function computeDirSizeWithinListing(
+  absPath: string,
+  listingBudget: DirSizeBudget,
+): number | null {
+  const allotment = Math.min(
+    DIR_SIZE_PER_DIR_ENTRY_BUDGET,
+    listingBudget.remaining,
+  );
+  const dirBudget: DirSizeBudget = { remaining: allotment };
+  const size = computeDirSize(absPath, dirBudget);
+  listingBudget.remaining -= allotment - dirBudget.remaining;
+  return size;
+}
+
 const SOUNDS_WORKSPACE_PATH = "data/sounds";
 
 function normaliseWorkspacePathForSync(path: string): string {
@@ -153,9 +184,11 @@ function handleWorkspaceTree({ queryParams }: RouteHandlerArgs) {
     const dirents = readdirSync(resolved, { withFileTypes: true });
     const workspaceDir = getWorkspaceDir();
 
-    // Shared budget across every directory in this listing. When opted out,
-    // we never construct one, so directories report `size: null` as before.
-    const dirSizeBudget: DirSizeBudget | undefined = includeDirSizes
+    // Listing-wide budget, only constructed when sizes are requested. Each
+    // directory draws a per-directory allotment from it so one oversized
+    // subtree can't starve its siblings, while the shared remainder still caps
+    // total synchronous traversal for the whole listing.
+    const listingBudget: DirSizeBudget | undefined = includeDirSizes
       ? { remaining: DIR_SIZE_TOTAL_ENTRY_BUDGET }
       : undefined;
 
@@ -176,7 +209,9 @@ function handleWorkspaceTree({ queryParams }: RouteHandlerArgs) {
       const relativePath = fullPath.slice(workspaceDir.length + 1);
 
       const dirSize =
-        isDir && dirSizeBudget ? computeDirSize(fullPath, dirSizeBudget) : null;
+        isDir && listingBudget
+          ? computeDirSizeWithinListing(fullPath, listingBudget)
+          : null;
 
       entries.push({
         name: entry.name,