@nimbus-sh/core 0.4.0 → 0.6.0

package/src/vfs/sqlite-vfs.ts

@@ -43,27 +43,33 @@
 import { VfsEventEmitter, type VfsEventType } from './events.js';
 import { normalizeVfsPath } from './path.js';
 import {
-  CHUNK_SIZE,
   LRU_MAX_ENTRIES,
   BATCH_SIZE,
+  FS_LIST_PAGE_LIMIT,
+} from '../constants.js';
+import {
+  CHUNK_SIZE,
   MAX_TX_BLOB_BYTES,
   MAX_TX_LOGICAL_ROWS,
   MAX_TX_SQL_EXECS,
   MAX_GLOBAL_WRITE_STREAM_CREDIT_BYTES,
-  FS_LIST_PAGE_LIMIT,
-} from '../constants.js';
-import { recordFailure } from '../observability/oom-discriminator.js';
-import { classifyError } from '../observability/oom-classify.js';
-import { acquireSupervisorAllocation } from '../observability/heavy-alloc-coord.js';
+} from '@nimbus-sh/platform/limits.js';
+import { recordFailure } from '@nimbus-sh/platform/oom-discriminator.js';
+import { classifyError } from '@nimbus-sh/platform/oom-classify.js';
+import { acquireSupervisorAllocation } from '@nimbus-sh/platform/heavy-alloc-coord.js';
 import { enc, dec } from '../_shared/bytes.js';
 import {
   decodeWriteBatchStream,
+  type BatchChunkEntry,
+  type BatchInodeEntry,
+  type BatchWritePayload,
+  type VfsInodeKind,
   type W7DecodedRecord,
-} from '../_shared/w7-frame.js';
+} from '@nimbus-sh/platform/w7-frame.js';
 import {
   WeightedCreditPool,
   type CreditLease,
-} from '../_shared/weighted-credit-pool.js';
+} from '@nimbus-sh/platform/weighted-credit-pool.js';
 import { LEGACY_SYMLINK_REGISTRY_PATH } from './symlink-registry.js';
 import {
   CRED_KERNEL,
@@ -83,9 +89,37 @@ const CONTENT_ID_ALLOCATION_ATTEMPTS = 8;
 // generateGitNetworkFacetCode (git-network-facet.ts) and the parallel
 // preamble (parallel/generated-workers.ts).
 
-// ── Types ───────────────────────────────────────────────────────────────────
+/**
+ * The Node `process` global as far as this file probes it. workerd provides
+ * no `process`, so every member stays optional and every read stays guarded.
+ */
+interface NodeProcessLike {
+  env?: Record<string, string | undefined>;
+  memoryUsage?: () => { heapUsed: number };
+}
+
+/**
+ * Live view of the global object. `process` is not in the Workers lib, so its
+ * shape is declared here rather than assumed present.
+ */
+const nodeHost = globalThis as { process?: NodeProcessLike };
+
+/** Single gate for the W2.5b install-pipeline diagnostics below. */
+function installPipelineDiagEnabled(): boolean {
+  return nodeHost.process?.env?.NIMBUS_DIAG_INSTALL_PIPELINE === '1';
+}
 
-export type VfsInodeKind = 'file' | 'directory' | 'symlink';
+// ── Types ───────────────────────────────────────────────────────────────────
+// VfsInodeKind and the writeBatch payload types (BatchInodeEntry,
+// BatchChunkEntry, BatchWritePayload) live with the wire format that encodes
+// them: @nimbus-sh/platform/w7-frame.js. Forwarded here because core@0.5.0
+// published them from this module; platform stays the definition.
+export type {
+  BatchChunkEntry,
+  BatchInodeEntry,
+  BatchWritePayload,
+  VfsInodeKind,
+} from '@nimbus-sh/platform/w7-frame.js';
 
 export interface ExclusiveMutationLease {
   readonly root: string;
@@ -113,22 +147,6 @@ interface INode {
   contentId: string | null;
 }
 
-/** Entry for bulk inode creation via writeBatch(). */
-export interface BatchInodeEntry {
-  path: string;
-  parentPath: string;
-  /** Defaults to isDir ? directory : file for legacy/non-symlink producers. */
-  kind?: VfsInodeKind;
-  isDir: boolean;
-  size: number;
-  atime?: number;
-  mtime: number;
-  mode: number;
-  uid?: number;
-  gid?: number;
-  chunkCount: number;
-}
-
 export interface VfsStat {
   type: VfsInodeKind;
   size: number;
@@ -213,21 +231,6 @@ export interface CredentialedVfs {
   readonly epoch: string;
 }
 
-/** Entry for bulk chunk creation via writeBatch(). */
-export interface BatchChunkEntry {
-  path: string;
-  chunkId: number;
-  data: Uint8Array;
-}
-
-/** Payload for writeBatch() — all inodes + chunks written in ONE transactionSync(). */
-export interface BatchWritePayload {
-  inodes: BatchInodeEntry[];
-  chunks: BatchChunkEntry[];
-  /** Paths to delete before writing (for clean reinstall). */
-  deletePaths?: string[];
-}
-
 export interface WriteBatchStreamProgress {
   /** 1-based sequence of the last durable publish group; zero means none. */
   committedGroupSequence: number;
@@ -254,6 +257,8 @@ const CHUNK_ROWS_PER_SQL_EXEC = 33;
 const CONTENT_IDS_PER_SQL_EXEC = 50;
 const TRANSACTION_DURATION_SAMPLE_COUNT = 128;
 const CONTENT_SCHEMA_MIGRATION = 'content_generations_v1';
+/** Storage key of the shared scratch tree. `normalizeVfsPath` drops the slash. */
+const TMP_ROOT = 'tmp';
 export const VFS_APPEND_RECEIPT_LIMIT = 2048;
 const INODE_KIND_FILE = 0;
 const INODE_KIND_DIRECTORY = 1;
@@ -679,6 +684,9 @@ export class SqliteVFS {
   private readonly activeStagingContentIds = new Set<string>();
   /** True only while durable GC work or a known abandoned staging row exists. */
   private maintenancePending = false;
+  // Keyset cursor for the orphan scan: each maintenance call reads one bounded
+  // page of distinct content ids past this bound, wrapping to '' at the end.
+  private orphanScanCursor = '';
 
   // Stage 2 transaction/phase telemetry. Scalar writes stay cheap; the
   // percentile is computed from the fixed ring only when diagnostics read it.
@@ -1317,7 +1325,7 @@ export class SqliteVFS {
   private blobToUint8Array(blob: unknown): Uint8Array {
     if (blob instanceof Uint8Array) return blob;
     if (blob instanceof ArrayBuffer) return new Uint8Array(blob);
-    if (ArrayBuffer.isView(blob)) return new Uint8Array((blob as any).buffer, (blob as any).byteOffset, (blob as any).byteLength);
+    if (ArrayBuffer.isView(blob)) return new Uint8Array(blob.buffer, blob.byteOffset, blob.byteLength);
     return new Uint8Array(0);
   }
 
@@ -1338,6 +1346,82 @@ export class SqliteVFS {
     return this.blobToUint8Array(rows[0].data);
   }
 
+  /**
+   * Principals whose `/tmp` is private, keyed by uid, valued by the storage
+   * root their `/tmp` resolves to.
+   *
+   * `/tmp` keeps its path in every view and only the bytes behind it differ,
+   * so nothing has to be told which principal it is. The credential is the
+   * only per-process state visible where paths are RESOLVED — there is no pid
+   * and no cwd down here — so it is what the private view is keyed on.
+   *
+   * Resolution rather than a mount, because a mount diverges the two planes:
+   * the shell writing `/tmp/a` and the file API writing `/tmp/b` landed in
+   * different trees under the same name. `resolvePath` already takes `cred`,
+   * and every plane goes through it.
+   *
+   * Registration is also what makes a principal CONFINED for `chmod`. The two
+   * properties travel together because they answer one question: is this
+   * principal a guest in this filesystem. Nothing here applies to an
+   * unregistered credential, so the ordinary session user is untouched.
+   */
+  private confinedTmpRoots = new Map<number, string>();
+
+  /**
+   * Confine a principal. `tmpRoot` is a storage key, not a logical path — the
+   * caller owns creating and chowning it, because a per-principal `chown` is
+   * uid-0 only and a guest cannot provision its own.
+   */
+  confinePrincipal(uid: number, tmpRoot: string): void {
+    const root = normalizeVfsPath(tmpRoot);
+    if (root === '') throw vfsError('EINVAL', 'a private /tmp root cannot be the filesystem root');
+    this.confinedTmpRoots.set(uid, root);
+  }
+
+  /** Drop a confinement. A principal's `/tmp` dies with it; its home does not. */
+  releasePrincipal(uid: number): void {
+    this.confinedTmpRoots.delete(uid);
+  }
+
+  /**
+   * Logical path -> storage key, for one credential.
+   *
+   * Everything under `/tmp` belongs to the caller's own private root, which is
+   * what makes the same path mean different bytes per principal. Idempotent: a
+   * key already inside that root is returned untouched, so the several methods
+   * that derive a key before handing it on cannot stack the rewrite.
+   */
+  private storageKey(path: string, cred: VfsCred): string {
+    const key = normalizeVfsPath(path);
+    const root = this.confinedTmpRoots.get(cred.uid);
+    if (root === undefined) return key;
+    if (key === root || key.startsWith(`${root}/`)) return key;
+    if (key === TMP_ROOT) return root;
+    if (!key.startsWith(`${TMP_ROOT}/`)) return key;
+    return `${root}/${key.slice(TMP_ROOT.length + 1)}`;
+  }
+
+  /**
+   * Storage key -> the name this credential knows it by, or `null` when it has
+   * none. The inverse of {@link storageKey}, for the one surface that reports
+   * paths it was not asked about: {@link list}.
+   *
+   * A confined caller has no name for the shared scratch tree — `/tmp` is its
+   * own root — nor for another principal's, so both answer `null` and are
+   * omitted. An unconfined caller sees storage as it is, which is what the
+   * kernel and the session user need.
+   */
+  private logicalPath(key: string, cred: VfsCred): string | null {
+    const root = this.confinedTmpRoots.get(cred.uid);
+    if (root === undefined) return key;
+    if (key === root) return TMP_ROOT;
+    if (key.startsWith(`${root}/`)) return `${TMP_ROOT}/${key.slice(root.length + 1)}`;
+    // The SHARED scratch root has no name here — this caller's `/tmp` is its
+    // own root, which already supplied that entry. Returning it too would
+    // enumerate one name twice, for two different directories.
+    return key === TMP_ROOT || key.startsWith(`${TMP_ROOT}/`) ? null : key;
+  }
+
   // ── Filesystem operations ─────────────────────────────────────────────
 
   as(cred: VfsCred): CredentialedVfs {
@@ -1399,7 +1483,7 @@ export class SqliteVFS {
       writeBatch: (payload) => this.writeBatch(payload, bound),
       writeStream: (stream, options) => this.writeStream(stream, options, bound),
       mkdirBatch: (paths) => this.mkdirBatch(paths, bound),
-      revision: (path) => this.revision(path),
+      revision: (path) => this.revision(path, bound),
       epoch: this._epoch,
     };
   }
@@ -1430,7 +1514,7 @@ export class SqliteVFS {
     followLeaf: boolean,
     allowMissing: boolean,
   ): { path: string; inode: INode | undefined } {
-    let current = normalizeVfsPath(path);
+    let current = this.storageKey(path, cred);
     const seen = new Set<string>();
     for (let hops = 0; hops <= 40; hops++) {
       const parts = current.split('/').filter(Boolean);
@@ -1449,8 +1533,13 @@ export class SqliteVFS {
           seen.add(prefix);
           const target = dec.decode(this.readInodeBytes(prefix, inode));
           const suffix = parts.slice(index + 1).join('/');
+          // An ABSOLUTE target is a logical path the same way the caller's
+          // was, so it goes through the same rewrite: otherwise a symlink to
+          // /tmp/y stored inside a private tree would read the shared one,
+          // which is the one way out of the confinement. A RELATIVE target
+          // resolves against a key that is already private, so it stays there.
           const resolvedTarget = target.startsWith('/')
-            ? normalizeVfsPath(target)
+            ? this.storageKey(target, cred)
             : normalizeVfsPath(`${this.parentPath(prefix)}/${target}`);
           current = suffix ? normalizeVfsPath(`${resolvedTarget}/${suffix}`) : resolvedTarget;
           restarted = true;
@@ -1496,6 +1585,27 @@ export class SqliteVFS {
     if (resolved.inode?.kind !== 'directory') throw vfsError('ENOTDIR', parent);
   }
 
+  /**
+   * POSIX sticky-bit restriction on a shared directory.
+   *
+   * Write permission on a directory is normally enough to remove or rename
+   * anything inside it, which is why `/tmp` is `1777` and not `0777`: the
+   * sticky bit narrows that to the entry's owner, the directory's owner, and
+   * root. Nothing enforced it here, so a world-writable shared directory gave
+   * every principal the ability to delete every other principal's files —
+   * the mode said one thing and the filesystem did another.
+   */
+  private checkStickyParentMutation(path: string, inode: INode, cred: VfsCred): void {
+    if (cred.uid === 0) return;
+    const parent = this.parentPath(normalizeVfsPath(path));
+    if (parent === '') return;
+    const parentInode = this.inodes.get(parent);
+    if (!parentInode || (parentInode.mode & 0o1000) === 0) return;
+    if (cred.uid !== parentInode.uid && cred.uid !== inode.uid) {
+      throw vfsError('EPERM', normalizeVfsPath(path));
+    }
+  }
+
   /**
    * Shared resolver for the boolean probes (exists/isDirectory/isFile/
    * isSymlink). Resolution-structure failures — a missing or non-directory
@@ -1536,9 +1646,11 @@ export class SqliteVFS {
    * under it changed in this DO lifetime). `revision('')` equals the
    * global clock by construction (every mutation stamps all ancestors).
    */
-  revision(path?: string): number {
+  revision(path?: string, cred?: VfsCred): number {
     if (path === undefined) return this._revision;
-    const p = normalizeVfsPath(path);
+    // A credentialed caller asks about its own view; a confined one asking
+    // after /tmp/x means its own file, so the counter must be that file's.
+    const p = cred === undefined ? normalizeVfsPath(path) : this.storageKey(path, cred);
     if (p === '') return this._revision;
     return this._pathRevisions.get(p) ?? 0;
   }
@@ -1726,7 +1838,7 @@ export class SqliteVFS {
   }
 
   private mkdir(path: string, options: { recursive?: boolean; mode?: number } | undefined, cred: VfsCred): void {
-    const normalized = normalizeVfsPath(path);
+    const normalized = this.storageKey(path, cred);
     this.assertMutationsAllowed([normalized]);
     if (this.exists(normalized, cred)) return;
 
@@ -1832,7 +1944,7 @@ export class SqliteVFS {
 
   private symlink(target: string, path: string, cred: VfsCred): void {
     this.assertMutationsAllowed([path]);
-    const normalized = normalizeVfsPath(path);
+    const normalized = this.storageKey(path, cred);
     const prior = this.checkAccess(normalized, 0, cred, { followLeaf: false, allowMissingLeaf: true });
     if (prior.inode) throw vfsError('EEXIST', normalized);
     this.checkParentAccess(normalized, cred);
@@ -2816,6 +2928,25 @@ export class SqliteVFS {
     const inode = resolved.inode;
     if (!inode) throw vfsError('ENOENT', path);
     if (cred.uid !== 0 && cred.uid !== inode.uid) throw vfsError('EPERM', resolved.path);
+    // A confined principal owns its own triad and nothing else. Refusing chmod
+    // outright would be simpler and wrong: execution is gated on the x bit, so
+    // a guest that writes build.sh and cannot chmod it cannot run it. What
+    // must not happen is WIDENING past its own principal, so the group, other
+    // and setuid/setgid/sticky bits keep the value they were provisioned with
+    // while the owner triad moves freely. `u+x` works; `+x` and `777` do not.
+    //
+    // Refused, never clamped. Quietly narrowing a mutation to the part that
+    // was allowed reports success for something other than what was asked, so
+    // the refusal names the spelling that works instead.
+    if (cred.uid !== 0 && this.confinedTmpRoots.has(cred.uid)) {
+      const beyondOwner = (mode & 0o7777) & ~0o700;
+      if (beyondOwner !== ((inode.mode & 0o7777) & ~0o700)) {
+        throw vfsError(
+          'EPERM',
+          `${resolved.path}: mode change would grant permission outside your own principal; use u+x`,
+        );
+      }
+    }
     this.assertMutationsAllowed([inode.path]);
     const full = inodeTypeBits(inode.kind) | (mode & 0o7777);
     inode.mode = full;
@@ -2886,7 +3017,7 @@ export class SqliteVFS {
     // Before the walk, deliberately — see VfsListPage.
     const epoch = this._epoch;
     const rev = this._revision;
-    const from = after === null || after === undefined ? '' : normalizeVfsPath(after);
+    const from = after === null || after === undefined ? '' : this.storageKey(after, cred);
     // this.inodes is insertion-ordered, not path-ordered, so the sort is what
     // makes `after` a resume key at all. Paid once per page against a map the
     // DO already holds whole.
@@ -2908,8 +3039,15 @@ export class SqliteVFS {
       } catch {
         continue;
       }
+      // Reported in the caller's OWN path space. Enumerating raw storage keys
+      // would name a private root the caller cannot address and does not know
+      // it has, and a caller feeding such a path back would be asking about
+      // someone else's tree. `null` means the path has no name for this
+      // caller, which is the same OMIT the access check above performs.
+      const logical = this.logicalPath(path, cred);
+      if (logical === null) continue;
       entries.push({
-        path,
+        path: logical,
         kind: inode.kind,
         size: inode.size,
         rev: this._pathRevisions.get(path) ?? 0,
@@ -2919,7 +3057,7 @@ export class SqliteVFS {
   }
 
   private readdir(path: string, cred: VfsCred): { name: string; type: VfsInodeKind }[] {
-    const np = path.replace(/^\/+/, '').replace(/\/+$/, '');
+    const np = this.storageKey(path, cred);
     const resolved = np ? this.checkAccess(np, 0o4, cred) : { path: '', inode: undefined };
     const inode = resolved.inode;
     if (inode && inode.kind !== 'directory') throw vfsError('ENOTDIR', path);
@@ -2927,7 +3065,7 @@ export class SqliteVFS {
     if (!kids) {
       // W2.5b diagnostic: empty children-set for a directory we expected
       // to be populated.
-      if ((globalThis as any).process?.env?.NIMBUS_DIAG_INSTALL_PIPELINE === '1') {
+      if (installPipelineDiagEnabled()) {
         // eslint-disable-next-line no-console
         console.warn(
           '[sqlite-vfs/W2.5b] readdir miss path=' + np +
@@ -2949,7 +3087,7 @@ export class SqliteVFS {
     // This distinguishes (a) "children index broken" from (b) "inodes
     // map lost entries".
     if (
-      (globalThis as any).process?.env?.NIMBUS_DIAG_INSTALL_PIPELINE === '1' &&
+      installPipelineDiagEnabled() &&
       kids.size !== results.length
     ) {
       // eslint-disable-next-line no-console
@@ -2977,22 +3115,24 @@ export class SqliteVFS {
     const inode = resolved.inode;
     if (!inode) throw vfsError('ENOENT', path);
     this.checkParentAccess(resolved.path, cred);
+    this.checkStickyParentMutation(resolved.path, inode, cred);
     if (inode.isDir) throw vfsError('EISDIR', resolved.path);
     this.writeBatch({ inodes: [], chunks: [], deletePaths: [resolved.path] }, cred);
   }
 
   private rmdir(path: string, cred: VfsCred): void {
     this.assertMutationsAllowed([path]);
-    const np = path.replace(/^\/+/, '').replace(/\/+$/, '');
+    const np = this.storageKey(path, cred);
     const resolved = this.checkAccess(np, 0, cred, { followLeaf: false });
     this.checkParentAccess(resolved.path, cred);
+    const inode = this.inodes.get(np);
+    if (!inode) throw vfsError('ENOENT', path);
+    this.checkStickyParentMutation(resolved.path, inode, cred);
     // Check if empty using children index (O(1) instead of O(N))
     const kids = this.children.get(np);
     if (kids && kids.size > 0) {
       throw vfsError('ENOTEMPTY', path);
     }
-    const inode = this.inodes.get(np);
-    if (!inode) throw vfsError('ENOENT', path);
     if (!inode.isDir) throw vfsError('ENOTDIR', path);
     this.writeBatch({ inodes: [], chunks: [], deletePaths: [np] }, cred);
   }
@@ -3018,6 +3158,7 @@ export class SqliteVFS {
     const resolved = this.checkAccess(path, 0, cred, { followLeaf: false });
     if (!resolved.inode) throw vfsError('ENOENT', normalizeVfsPath(path));
     this.checkParentAccess(resolved.path, cred);
+    this.checkStickyParentMutation(resolved.path, resolved.inode, cred);
 
     const removable = this.collectSubtreeInodes([resolved.path]);
     // The directories the recursive walk used to enumerate are exactly the
@@ -3067,6 +3208,7 @@ export class SqliteVFS {
     }
     const inode = this.inodes.get(oldPath);
     if (!inode) throw new Error("ENOENT: " + oldPath);
+    this.checkStickyParentMutation(oldPath, inode, cred);
 
     // W-3 (WASI filesystem WASI): if newPath already exists, unlink it first so the
     // SQL UPDATE doesn't conflict on inodes.path uniqueness. POSIX rename(2)
@@ -3077,6 +3219,7 @@ export class SqliteVFS {
     // (the latter is rare but POSIX permits it for empty dirs).
     const destInode = this.inodes.get(newPath);
     if (destInode) {
+      this.checkStickyParentMutation(newPath, destInode, cred);
       if (destInode.isDir) {
         // POSIX semantics: rename onto a non-empty dir is an error
         // (ENOTEMPTY); rename onto an empty dir is allowed. We surface
@@ -3283,14 +3426,14 @@ export class SqliteVFS {
   // ── Batch write (npm install fast path) ───────────────────────────────
 
   private normalizeBatchInode(entry: BatchInodeEntry, cred: VfsCred): NormalizedBatchInodeEntry {
-    const path = normalizeVfsPath(entry.path);
+    const path = this.storageKey(entry.path, cred);
     const prior = this.inodes.get(path);
     const newUid = cred.uid === 0 ? (entry.uid ?? 1000) : cred.uid;
     const newGid = cred.uid === 0 ? (entry.gid ?? 1000) : cred.gid;
     return {
       ...entry,
       path,
-      parentPath: normalizeVfsPath(entry.parentPath),
+      parentPath: this.storageKey(entry.parentPath, cred),
       mode: prior
         ? prior.mode
         : inodeKind(entry) === 'symlink'
@@ -3324,7 +3467,7 @@ export class SqliteVFS {
     };
 
     for (const path of payload.deletePaths ?? []) {
-      const normalized = normalizeVfsPath(path);
+      const normalized = this.storageKey(path, cred);
       const existing = this.checkAccess(normalized, 0, cred, {
         followLeaf: false,
         allowMissingLeaf: true,
@@ -3337,13 +3480,13 @@ export class SqliteVFS {
       else checkParent(entry.path);
     }
     for (const chunk of payload.chunks) {
-      const path = normalizeVfsPath(chunk.path);
+      const path = this.storageKey(chunk.path, cred);
       if (!pending.has(path)) this.checkAccess(path, 0o2, cred, { followLeaf: false });
     }
     return {
       ...payload,
       inodes,
-      deletePaths: payload.deletePaths?.map(normalizeVfsPath),
+      deletePaths: payload.deletePaths?.map((path) => this.storageKey(path, cred)),
     };
   }
 
@@ -4118,21 +4261,34 @@ export class SqliteVFS {
     let stagingScanComplete = true;
 
     if (transactions < maximum) {
-      const orphanRows = [...this.sql.exec(
-        `SELECT chunks.content_id
-         FROM file_chunks AS chunks
-         WHERE NOT EXISTS (
-             SELECT 1 FROM content_lifecycle AS lifecycle
-             WHERE lifecycle.content_id = chunks.content_id
-           )
-           AND ${sqlNoInodeContentReference('chunks.content_id')}
-         GROUP BY chunks.content_id
-         ORDER BY chunks.content_id
-         LIMIT ?`,
+      // The page is selected before the orphan predicates so a scan that finds
+      // nothing still reads only one page, not the whole covering index.
+      const pageRows = [...this.sql.exec(
+        `SELECT page.content_id AS content_id,
+                (NOT EXISTS (
+                   SELECT 1 FROM content_lifecycle AS lifecycle
+                   WHERE lifecycle.content_id = page.content_id
+                 )
+                 AND ${sqlNoInodeContentReference('page.content_id')}) AS orphaned
+         FROM (
+           SELECT chunks.content_id
+           FROM file_chunks AS chunks
+           WHERE chunks.content_id > ?
+           GROUP BY chunks.content_id
+           ORDER BY chunks.content_id
+           LIMIT ?
+         ) AS page
+         ORDER BY page.content_id`,
+        this.orphanScanCursor,
         CONTENT_IDS_PER_SQL_EXEC,
       )];
-      orphanScanComplete = orphanRows.length < CONTENT_IDS_PER_SQL_EXEC;
-      const contentIds = orphanRows.map((row) => String(row.content_id));
+      orphanScanComplete = pageRows.length < CONTENT_IDS_PER_SQL_EXEC;
+      this.orphanScanCursor = orphanScanComplete
+        ? ''
+        : String(pageRows[pageRows.length - 1].content_id);
+      const contentIds = pageRows
+        .filter((row) => Number(row.orphaned) === 1)
+        .map((row) => String(row.content_id));
       if (contentIds.length > 0) {
         const candidates = contentIds
           .map((_, index) => index === 0 ? 'SELECT ? AS content_id' : 'SELECT ?')
@@ -4341,7 +4497,7 @@ export class SqliteVFS {
   /** Best-effort process.memoryUsage().heapUsed; 0 in DO contexts. */
   private _safeHeapUsed(): number {
     try {
-      const mu = (globalThis as any).process?.memoryUsage?.();
+      const mu = nodeHost.process?.memoryUsage?.();
       return Number(mu?.heapUsed) || 0;
     } catch {
       return 0;
@@ -4536,7 +4692,7 @@ export class SqliteVFS {
     // `_addToChildrenIndex` uses Set.add so repeated calls are idempotent;
     // gating it on `prior === undefined` was the bug. Counters remain
     // gated correctly so they don't double-count.
-    const __diag = ((globalThis as any).process?.env?.NIMBUS_DIAG_INSTALL_PIPELINE === '1');
+    const __diag = installPipelineDiagEnabled();
     const replacedPaths = new Set<string>();
     for (const entry of plan.inodes) {
       const prior = this.inodes.get(entry.path);

package/dist/_shared/install-phase.d.ts

@@ -1,47 +0,0 @@
-/**
- * _shared/install-phase.ts — single source of truth for the npm-install
- * state-machine phase enum.
- *
- * History: CLN-1 (2026-05-11) — consolidated from two diverged copies.
- *   - `npm/installer.ts:93-95` was the progress-event variant. Included
- *     'lock-check' (a real progress event emitted while parsing
- *     package-lock.json) but lacked 'idle'.
- *   - `observability/diag-counters.ts:33-35` was the counter-state variant.
- *     Included 'idle' (the resting state when no install is in flight)
- *     but lacked 'lock-check'. The diag-counter's `setInstallPhase()`
- *     was actually called with 'idle' (installer.ts:184,201) — passing
- *     a value not declared in installer.ts's local type. The type check
- *     fell through to diag-counters' type because installer.ts imports
- *     setInstallPhase from there; the local `InstallPhase` definition
- *     in installer.ts was only used by `InstallProgress.phase`.
- *
- * Going forward both consumers import from this module; any new phase
- * value added here is automatically available everywhere.
- *
- * Phase semantics (chronological order for a single install run):
- *
- *   idle         resting state, no install in flight
- *     ↓
- *   lock-check   parsing existing package-lock.json (if present)
- *     ↓
- *   resolve      walking the dep tree, fetching packuments
- *     ↓
- *   hoist        hoisting peer-deps + flattening node_modules
- *     ↓
- *   diff         comparing target tree against current install state
- *     ↓
- *   fetch        downloading missing tarballs
- *     ↓
- *   write        extracting tarballs into the VFS
- *     ↓
- *   link-bins    creating bin/ symlinks
- *     ↓
- *   bundle       (post-install) pre-bundling for esbuild fast path
- *     ↓
- *   done         install complete; about to return to 'idle'
- *
- * The phase strings are surfaced via /api/_diag/install-pipeline and
- * displayed in the install-progress UI; treat them as a public API.
- */
-export type InstallPhase = 'idle' | 'lock-check' | 'resolve' | 'hoist' | 'diff' | 'fetch' | 'write' | 'link-bins' | 'bundle' | 'done';
-//# sourceMappingURL=install-phase.d.ts.map

package/dist/_shared/install-phase.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"install-phase.d.ts","sourceRoot":"","sources":["../../src/_shared/install-phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,YAAY,GACZ,SAAS,GACT,OAAO,GACP,MAAM,GACN,OAAO,GACP,OAAO,GACP,WAAW,GACX,QAAQ,GACR,MAAM,CAAC"}

package/dist/_shared/install-phase.js

@@ -1 +0,0 @@
-export {};

package/dist/_shared/rpc-dispose.d.ts

@@ -1,4 +0,0 @@
-export declare function disposeRpcResource(value: unknown): boolean;
-export declare function disposeRpcResources(values: Iterable<unknown>): void;
-export declare function useRpcResource<T, R>(promise: Promise<T>, use: (value: T) => R | Promise<R>): Promise<R>;
-//# sourceMappingURL=rpc-dispose.d.ts.map

package/dist/_shared/rpc-dispose.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"rpc-dispose.d.ts","sourceRoot":"","sources":["../../src/_shared/rpc-dispose.ts"],"names":[],"mappings":"AAEA,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAY1D;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,IAAI,CAEnE;AAED,wBAAsB,cAAc,CAAC,CAAC,EAAE,CAAC,EACvC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAChC,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/_shared/rpc-dispose.js

@@ -1,30 +0,0 @@
-export function disposeRpcResource(value) {
-    if ((typeof value !== 'object' && typeof value !== 'function') || value === null)
-        return false;
-    const disposerKey = Symbol.dispose;
-    if (!disposerKey)
-        return false;
-    const disposer = Reflect.get(value, disposerKey);
-    if (typeof disposer !== 'function')
-        return false;
-    try {
-        Reflect.apply(disposer, value, []);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-export function disposeRpcResources(values) {
-    for (const value of values)
-        disposeRpcResource(value);
-}
-export async function useRpcResource(promise, use) {
-    const value = await promise;
-    try {
-        return await use(value);
-    }
-    finally {
-        disposeRpcResource(value);
-    }
-}