rigscope 0.2.0 → 0.2.1

package/dist/collector.cjs

@@ -108,13 +108,16 @@ function filterInventory(inv, sharing) {
       swapTotalBytes: policy.swap ? inv.memory.swapTotalBytes : null
     },
     gpus: policy.gpus ? inv.gpus.map((gpu) => ({ ...gpu })) : [],
-    filesystems: policy.disks ? inv.filesystems.map((fs2) => ({ ...fs2 })) : [],
+    filesystems: policy.disks ? inv.filesystems.map((fs3) => ({ ...fs3 })) : [],
     disks: policy.disks ? inv.disks.map((disk) => ({ ...disk })) : [],
     network,
     capabilities
   };
 }
 
+// collector/destinations/queue.ts
+var DEFAULT_COLLECTOR_QUEUE_MODE = "memory";
+
 // collector/config.ts
 var ConfigError = class extends Error {
   issues;
@@ -320,6 +323,18 @@ function parseDestinations(env, issues, destinations) {
     }
   }
 }
+var QUEUE_MODES = ["memory", "durable"];
+function parseQueueMode(env, issues) {
+  const raw = env["COLLECTOR_QUEUE_MODE"]?.trim();
+  if (raw === void 0 || raw === "") {
+    return DEFAULT_COLLECTOR_QUEUE_MODE;
+  }
+  if (!QUEUE_MODES.includes(raw)) {
+    issues.push(`COLLECTOR_QUEUE_MODE must be one of ${QUEUE_MODES.join(" or ")}`);
+    return DEFAULT_COLLECTOR_QUEUE_MODE;
+  }
+  return raw;
+}
 function parseIntervalMs(env, issues) {
   const raw = env["COLLECTOR_INTERVAL_MS"]?.trim();
   if (raw === void 0 || raw === "") {
@@ -350,6 +365,7 @@ function parseCollectorConfig(env) {
   }
   const destinations = [];
   const intervalMs = parseIntervalMs(env, issues);
+  const queueMode = parseQueueMode(env, issues);
   parseDestinations(env, issues, destinations);
   if (issues.length > 0) {
     throw new ConfigError(issues);
@@ -359,7 +375,8 @@ function parseCollectorConfig(env) {
     hostname,
     hostnameIsMockDefault: rawHostname === "",
     intervalMs,
-    destinations
+    destinations,
+    queueMode
   };
 }
 
@@ -377,8 +394,8 @@ var ProcessLeaseError = class extends Error {
     this.code = code;
   }
 };
-function acquireProcessLease(path2) {
-  const absolute = (0, import_node_path.resolve)(path2);
+function acquireProcessLease(path3) {
+  const absolute = (0, import_node_path.resolve)(path3);
   (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(absolute), { recursive: true, mode: 448 });
   const parent = (0, import_node_fs.lstatSync)((0, import_node_path.dirname)(absolute));
   if (!parent.isDirectory() || (parent.mode & 63) !== 0) {
@@ -432,10 +449,10 @@ function acquireProcessLease(path2) {
     "runtime lease could not be acquired after repeated stale-lock recovery"
   );
 }
-function inspectLock(path2) {
+function inspectLock(path3) {
   let stats;
   try {
-    stats = (0, import_node_fs.lstatSync)(path2);
+    stats = (0, import_node_fs.lstatSync)(path3);
   } catch (error) {
     if (error.code === "ENOENT") return null;
     throw new ProcessLeaseError(
@@ -448,7 +465,7 @@ function inspectLock(path2) {
   }
   let raw;
   try {
-    raw = (0, import_node_fs.readFileSync)(path2, "utf8");
+    raw = (0, import_node_fs.readFileSync)(path3, "utf8");
   } catch (error) {
     if (error.code === "ENOENT") return null;
     throw new ProcessLeaseError(
@@ -485,10 +502,10 @@ function inspectLock(path2) {
     );
   }
 }
-function createRelease(path2, inode) {
+function createRelease(path3, inode) {
   let released = false;
   const cleanup = () => {
-    removeIfSameInode(path2, inode);
+    removeIfSameInode(path3, inode);
   };
   const onExit = () => {
     if (released) return;
@@ -503,10 +520,10 @@ function createRelease(path2, inode) {
     cleanup();
   };
 }
-function removeIfSameInode(path2, inode) {
+function removeIfSameInode(path3, inode) {
   try {
-    const stat = (0, import_node_fs.lstatSync)(path2);
-    if (stat.ino === inode.ino && stat.dev === inode.dev) (0, import_node_fs.unlinkSync)(path2);
+    const stat = (0, import_node_fs.lstatSync)(path3);
+    if (stat.ino === inode.ino && stat.dev === inode.dev) (0, import_node_fs.unlinkSync)(path3);
   } catch {
   }
 }
@@ -515,10 +532,10 @@ function removeIfSameInode(path2, inode) {
 function defaultStatePath() {
   return (0, import_node_path2.join)(process.env.XDG_STATE_HOME || (0, import_node_path2.join)((0, import_node_os.homedir)(), ".local", "state"), "rigscope", "collector.json");
 }
-function readState(path2) {
-  const stat = (0, import_node_fs2.lstatSync)(path2);
+function readState(path3) {
+  const stat = (0, import_node_fs2.lstatSync)(path3);
   if (!stat.isFile() || stat.size > 64 * 1024 || (stat.mode & 63) !== 0) throw new Error("collector state must be a private regular file");
-  const parsed = JSON.parse((0, import_node_fs2.readFileSync)(path2, "utf8"));
+  const parsed = JSON.parse((0, import_node_fs2.readFileSync)(path3, "utf8"));
   if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("invalid collector state");
   const raw = parsed;
   if (Object.hasOwn(raw, "version") || Object.hasOwn(raw, "formatVersion")) {
@@ -543,13 +560,13 @@ function readState(path2) {
     ...pendingEnrollments === void 0 ? {} : { pendingEnrollments }
   };
 }
-function updateInstallation(path2, change = (s) => s) {
-  (0, import_node_fs2.mkdirSync)((0, import_node_path2.dirname)(path2), { recursive: true, mode: 448 });
-  const directoryStat = (0, import_node_fs2.lstatSync)((0, import_node_path2.dirname)(path2));
+function updateInstallation(path3, change = (s) => s) {
+  (0, import_node_fs2.mkdirSync)((0, import_node_path2.dirname)(path3), { recursive: true, mode: 448 });
+  const directoryStat = (0, import_node_fs2.lstatSync)((0, import_node_path2.dirname)(path3));
   if (!directoryStat.isDirectory() || (directoryStat.mode & 63) !== 0) {
     throw new ConfigError(["collector state requires a private directory (0700)"]);
   }
-  const lock = `${path2}.lock`;
+  const lock = `${path3}.lock`;
   let releaseLock;
   try {
     releaseLock = acquireProcessLease(lock);
@@ -566,8 +583,8 @@ function updateInstallation(path2, change = (s) => s) {
   try {
     let state;
     try {
-      (0, import_node_fs2.lstatSync)(path2);
-      state = readState(path2);
+      (0, import_node_fs2.lstatSync)(path3);
+      state = readState(path3);
     } catch (error) {
       if (error.code !== "ENOENT") throw error;
       state = { collectorId: (0, import_node_crypto2.randomUUID)(), destinations: [] };
@@ -578,7 +595,7 @@ function updateInstallation(path2, change = (s) => s) {
       destinations: changed.destinations,
       ...changed.pendingEnrollments === void 0 ? {} : { pendingEnrollments: changed.pendingEnrollments }
     };
-    temporary = `${path2}.${(0, import_node_crypto2.randomUUID)()}.tmp`;
+    temporary = `${path3}.${(0, import_node_crypto2.randomUUID)()}.tmp`;
     const out = (0, import_node_fs2.openSync)(temporary, "wx", 384);
     try {
       (0, import_node_fs2.writeFileSync)(out, JSON.stringify(next) + "\n");
@@ -586,9 +603,9 @@ function updateInstallation(path2, change = (s) => s) {
     } finally {
       (0, import_node_fs2.closeSync)(out);
     }
-    (0, import_node_fs2.renameSync)(temporary, path2);
+    (0, import_node_fs2.renameSync)(temporary, path3);
     temporary = void 0;
-    const directory = (0, import_node_fs2.openSync)((0, import_node_path2.dirname)(path2), "r");
+    const directory = (0, import_node_fs2.openSync)((0, import_node_path2.dirname)(path3), "r");
     try {
       (0, import_node_fs2.fsyncSync)(directory);
     } finally {
@@ -606,14 +623,14 @@ function updateInstallation(path2, change = (s) => s) {
 
 // collector/enroll.ts
 var import_node_crypto3 = require("node:crypto");
-async function enrollCollector(path2, connectUrl, enrollmentToken, sharing, replace = false) {
+async function enrollCollector(path3, connectUrl, enrollmentToken, sharing, replace = false) {
   const issues = [];
   const url = validateHubUrl(connectUrl, "enrollment destination", issues);
   if (!url || issues.length) throw new Error("invalid enrollment destination");
   if (!/^[\x21-\x7e]{1,256}$/.test(enrollmentToken)) throw new Error("invalid enrollment token");
-  const state = updateInstallation(path2);
+  const state = updateInstallation(path3);
   if (!replace && state.destinations.some((d) => d.url === url.href) || !state.destinations.some((d) => d.url === url.href) && state.destinations.length >= 8) throw new Error("destination already enrolled or destination budget exhausted");
-  const prepared = updateInstallation(path2, (current) => {
+  const prepared = updateInstallation(path3, (current) => {
     if (current.pendingEnrollments?.some((p) => p.url === url.href)) return current;
     return { ...current, pendingEnrollments: [
       ...current.pendingEnrollments ?? [],
@@ -659,7 +676,7 @@ async function enrollCollector(path2, connectUrl, enrollmentToken, sharing, repl
   if (result.collectorId !== state.collectorId || typeof result.machineId !== "string" || !result.machineId || typeof result.token !== "string") throw new Error("invalid enrollment response");
   const destination = parseCollectorConfig({ COLLECTOR_HUBS: JSON.stringify([{ url: url.href, token: result.token, sharing }]) }).destinations[0];
   try {
-    updateInstallation(path2, (current) => {
+    updateInstallation(path3, (current) => {
       if (current.collectorId !== state.collectorId || !replace && current.destinations.some((d) => d.url === url.href) || !current.destinations.some((d) => d.url === url.href) && current.destinations.length >= 8) throw new Error("collector state changed during enrollment");
       return {
         ...current,
@@ -678,9 +695,9 @@ var nodeFs = __toESM(require("node:fs"));
 var BOOT_ID_UNAVAILABLE = "unavailable";
 var BOOT_ID_PATH = "/proc/sys/kernel/random/boot_id";
 var BOOT_ID_PATTERN = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
-function readBootIdentity(fs2 = nodeFs) {
+function readBootIdentity(fs3 = nodeFs) {
   try {
-    const raw = String(fs2.readFileSync(BOOT_ID_PATH, "utf8")).trim();
+    const raw = String(fs3.readFileSync(BOOT_ID_PATH, "utf8")).trim();
     if (BOOT_ID_PATTERN.test(raw)) {
       return { bootId: raw.toLowerCase(), available: true };
     }
@@ -758,13 +775,17 @@ var OutboxBudget = class {
     }
     return largest;
   }
-  /** Physical counterpart of `largest`, using measured main+WAL bytes. */
+  /**
+   * Physical counterpart of `largest`, using measured main+WAL bytes. A memory
+   * queue owns no file, so it is never a physical-budget victim.
+   */
   largestByDisk(exclude) {
     let largest = null;
     let largestBytes = -1;
     for (const outbox of this.outboxes) {
       if (exclude?.has(outbox)) continue;
       const bytes = outbox.diskBytes();
+      if (bytes === 0) continue;
       if (bytes > largestBytes) {
         largest = outbox;
         largestBytes = bytes;
@@ -779,6 +800,10 @@ var OutboxBudget = class {
   }
 };
 
+// collector/destinations/connection.ts
+var fs2 = __toESM(require("node:fs"));
+var path2 = __toESM(require("node:path"));
+
 // collector/destinations/outbox.ts
 var import_node_crypto5 = require("node:crypto");
 var fs = __toESM(require("node:fs"));
@@ -853,6 +878,7 @@ function asRow(value) {
   };
 }
 var DestinationOutbox = class _DestinationOutbox {
+  queueMode = "durable";
   db;
   limits;
   budget;
@@ -1101,7 +1127,8 @@ var DestinationOutbox = class _DestinationOutbox {
         inFlightRecords: 0,
         droppedRecords: this.droppedSinceOpen,
         replaying: false,
-        lastAckAt: this.lastAckAt
+        lastAckAt: this.lastAckAt,
+        queueMode: this.queueMode
       };
     }
     const pending = this.db.prepare("SELECT captured_at, bytes FROM outbox_records WHERE state = 'pending'").all();
@@ -1122,7 +1149,8 @@ var DestinationOutbox = class _DestinationOutbox {
       inFlightRecords: inFlight,
       droppedRecords: this.droppedSinceOpen,
       replaying: pending.length > 0,
-      lastAckAt: this.lastAckAt
+      lastAckAt: this.lastAckAt,
+      queueMode: this.queueMode
     };
   }
   /** Logical bytes of stored record JSON (pending plus in-flight). */
@@ -1330,8 +1358,13 @@ var DestinationOutbox = class _DestinationOutbox {
     let guard = 0;
     while (budget2.diskOverBy() > 0 && guard < 256) {
       guard += 1;
-      const target = budget2.largestByDisk(tried);
-      if (target === null) break;
+      const candidate = budget2.largestByDisk(tried);
+      if (candidate === null) break;
+      if (!(candidate instanceof _DestinationOutbox)) {
+        tried.add(candidate);
+        continue;
+      }
+      const target = candidate;
       if (!target.canReclaimPhysical()) {
         tried.add(target);
         continue;
@@ -1546,6 +1579,414 @@ var DestinationOutbox = class _DestinationOutbox {
   }
 };
 
+// collector/destinations/memory-queue.ts
+var refKey = ({ runId, sequence }) => `${runId}\0${sequence}`;
+var NO_DISK = {
+  bytes: 0,
+  mainBytes: 0,
+  walBytes: 0,
+  logicalBytes: 0,
+  limitBytes: 0,
+  overBy: 0,
+  pressure: false,
+  walBudgetBytes: 0,
+  checkpointPages: 0,
+  pageCount: 0,
+  maxPageCount: 0,
+  freePages: 0,
+  autoVacuum: 0
+};
+var MemoryDestinationQueue = class {
+  queueMode = "memory";
+  limits;
+  budget;
+  allocateSequence;
+  identity;
+  now;
+  entries = [];
+  byRef = /* @__PURE__ */ new Map();
+  nextId = 1;
+  totalBytes = 0;
+  /** id of the newest metrics record not yet offered to `takeLive`. */
+  liveId = null;
+  droppedSinceOpen = 0;
+  lastAckAt = null;
+  closed = false;
+  constructor(opts) {
+    this.limits = { ...DEFAULT_OUTBOX_LIMITS, ...opts.limits };
+    this.budget = opts.budget ?? null;
+    this.allocateSequence = opts.allocateSequence;
+    this.identity = opts.identity;
+    this.now = opts.now ?? Date.now;
+    this.budget?.register(this);
+  }
+  // -------------------------------------------------------------------------
+  // Writes
+  // -------------------------------------------------------------------------
+  /**
+   * Admit one filtered metrics record. Age and byte caps are applied first so
+   * the newest sample always wins its slot, exactly as the durable queue sheds
+   * the oldest pending telemetry under pressure. The shared budget and gap cap
+   * are then settled so admission itself keeps retained data bounded, even if
+   * the maintenance tick never runs. Never throws.
+   */
+  append(record) {
+    if (this.closed) return;
+    try {
+      const json = JSON.stringify(record);
+      const bytes = Buffer.byteLength(json, "utf8");
+      if (bytes > this.limits.maxBytes) {
+        this.droppedSinceOpen += 1;
+        this.writeGap("outbox-bytes", record.capturedAt, record.capturedAt, 1);
+        this.enforceAdmission();
+        return;
+      }
+      this.enforceAge();
+      this.enforceBytes(this.limits.maxBytes - bytes);
+      this.insertJson(record.kind, record, json, bytes);
+      this.enforceAdmission();
+    } catch {
+      this.droppedSinceOpen += 1;
+    }
+  }
+  /** Reapply the current privacy policy to every retained metrics record. */
+  filterPending(transform) {
+    if (this.closed) return;
+    for (const entry of [...this.entries]) {
+      if (entry.kind !== "metrics") continue;
+      const parsed = this.parse(entry);
+      if (parsed === null) continue;
+      const json = JSON.stringify(transform(parsed));
+      const bytes = Buffer.byteLength(json, "utf8");
+      this.totalBytes += bytes - entry.bytes;
+      entry.json = json;
+      entry.bytes = bytes;
+    }
+    this.totalBytes = Math.max(0, this.totalBytes);
+  }
+  // -------------------------------------------------------------------------
+  // Reads
+  // -------------------------------------------------------------------------
+  /**
+   * Newest metrics record appended since the last `takeLive`. It stays pending
+   * so a lost live send is still replayed later, matching the durable queue.
+   */
+  takeLive() {
+    if (this.closed || this.liveId === null) return null;
+    const id2 = this.liveId;
+    this.liveId = null;
+    const entry = this.entries.find((candidate) => candidate.id === id2);
+    if (entry === void 0 || entry.state !== "pending" || entry.kind !== "metrics") return null;
+    return this.parse(entry);
+  }
+  /**
+   * Oldest pending records, oldest first, excluding the record currently held
+   * for the live slot. Bounded by both count and bytes, but always at least one
+   * record so a single large sample cannot stall the queue.
+   */
+  takeReplay(maxRecords, maxBytes) {
+    if (this.closed || !Number.isFinite(maxRecords) || maxRecords < 1) return [];
+    const records = [];
+    let bytes = 0;
+    for (const entry of this.entries) {
+      if (records.length >= Math.floor(maxRecords)) break;
+      if (entry.state !== "pending" || entry.id === this.liveId) continue;
+      if (records.length > 0 && bytes + entry.bytes > maxBytes) break;
+      const parsed = this.parse(entry);
+      if (parsed === null) continue;
+      records.push(parsed);
+      bytes += entry.bytes;
+    }
+    return records;
+  }
+  // -------------------------------------------------------------------------
+  // Delivery state
+  // -------------------------------------------------------------------------
+  markInFlight(refs) {
+    if (this.closed) return;
+    for (const ref of refs) {
+      const entry = this.byRef.get(refKey(ref));
+      if (entry !== void 0 && entry.state === "pending") {
+        entry.state = "inflight";
+        entry.offered = true;
+      }
+    }
+  }
+  release(refs) {
+    if (this.closed) return;
+    for (const ref of refs) {
+      const entry = this.byRef.get(refKey(ref));
+      if (entry !== void 0 && entry.state === "inflight") entry.state = "pending";
+    }
+  }
+  releaseAll() {
+    if (this.closed) return;
+    for (const entry of this.entries) if (entry.state === "inflight") entry.state = "pending";
+  }
+  /** Accepted and rejected records both leave the queue. Unknown refs are ignored. */
+  acknowledge(accepted, rejected) {
+    if (this.closed) return;
+    if (accepted.length === 0 && rejected.length === 0) return;
+    for (const ref of [...accepted, ...rejected]) {
+      const key = refKey(ref);
+      const entry = this.byRef.get(key);
+      if (entry === void 0) continue;
+      this.byRef.delete(key);
+      const index = this.entries.indexOf(entry);
+      if (index >= 0) this.entries.splice(index, 1);
+      if (this.liveId === entry.id) this.liveId = null;
+      this.totalBytes = Math.max(0, this.totalBytes - entry.bytes);
+    }
+    this.lastAckAt = this.isoNow();
+  }
+  // -------------------------------------------------------------------------
+  // Retention
+  // -------------------------------------------------------------------------
+  enforceLimits() {
+    if (this.closed) return;
+    this.enforceAge();
+    this.enforceBytes(this.limits.maxBytes);
+    this.enforceAdmission();
+  }
+  /** Shared-budget victim: shed this queue's oldest pending metrics records. */
+  evictForBudget(reason) {
+    if (this.closed) return 0;
+    const victims = this.entries.filter((entry) => entry.state === "pending" && entry.kind === "metrics").slice(0, 16);
+    if (victims.length === 0) return 0;
+    const evicted = this.evict(victims, reason);
+    this.enforceGapCap();
+    return evicted;
+  }
+  status() {
+    let pendingRecords = 0;
+    let pendingBytes = 0;
+    let inFlightRecords = 0;
+    let oldest = null;
+    for (const entry of this.entries) {
+      if (entry.state === "inflight") {
+        inFlightRecords += 1;
+        continue;
+      }
+      pendingRecords += 1;
+      pendingBytes += entry.bytes;
+      if (oldest === null || entry.capturedAtMs < Date.parse(oldest)) oldest = entry.capturedAt;
+    }
+    return {
+      pendingRecords,
+      pendingBytes,
+      oldestPendingCapturedAt: oldest,
+      inFlightRecords,
+      droppedRecords: this.droppedSinceOpen,
+      replaying: pendingRecords > 0,
+      lastAckAt: this.lastAckAt,
+      queueMode: this.queueMode
+    };
+  }
+  bytes() {
+    return this.totalBytes;
+  }
+  /** A RAM queue owns no file: this is what makes the mode observable. */
+  diskBytes() {
+    return 0;
+  }
+  diskStatus() {
+    return { ...NO_DISK, logicalBytes: this.totalBytes };
+  }
+  checkpoint() {
+  }
+  attachBudget(budget2) {
+    this.budget = budget2;
+  }
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.budget?.unregister(this);
+    this.entries.length = 0;
+    this.byRef.clear();
+    this.totalBytes = 0;
+    this.liveId = null;
+  }
+  // -------------------------------------------------------------------------
+  // Internals
+  // -------------------------------------------------------------------------
+  isoNow() {
+    return new Date(this.now()).toISOString();
+  }
+  insertJson(kind, record, json, bytes) {
+    const entry = {
+      id: this.nextId++,
+      runId: record.runId,
+      sequence: record.sequence,
+      capturedAt: record.capturedAt,
+      capturedAtMs: Date.parse(record.capturedAt),
+      kind,
+      gapReason: record.kind === "gap" ? record.payload.reason : null,
+      state: "pending",
+      offered: false,
+      bytes,
+      json
+    };
+    this.entries.push(entry);
+    this.byRef.set(refKey(entry), entry);
+    this.totalBytes += bytes;
+    if (record.kind === "metrics") this.liveId = entry.id;
+    return entry;
+  }
+  remove(entry) {
+    this.byRef.delete(refKey(entry));
+    const index = this.entries.indexOf(entry);
+    if (index >= 0) this.entries.splice(index, 1);
+    if (this.liveId === entry.id) this.liveId = null;
+    this.totalBytes = Math.max(0, this.totalBytes - entry.bytes);
+  }
+  /** Fold evicted records into one coalesced gap so the hub sees the hole. */
+  evict(victims, reason) {
+    if (victims.length === 0) return 0;
+    let from = victims[0].capturedAt;
+    let to = victims[0].capturedAt;
+    let fromMs = victims[0].capturedAtMs;
+    let toMs = victims[0].capturedAtMs;
+    for (const entry of victims) {
+      this.remove(entry);
+      if (entry.capturedAtMs < fromMs) {
+        fromMs = entry.capturedAtMs;
+        from = entry.capturedAt;
+      }
+      if (entry.capturedAtMs > toMs) {
+        toMs = entry.capturedAtMs;
+        to = entry.capturedAt;
+      }
+    }
+    this.droppedSinceOpen += victims.length;
+    this.writeGap(reason, from, to, victims.length);
+    return victims.length;
+  }
+  /** Fold one dropped interval into a gap payload, keeping the widest range. */
+  extendGapPayload(target, source) {
+    if (Date.parse(source.fromCapturedAt) < Date.parse(target.fromCapturedAt)) {
+      target.fromCapturedAt = source.fromCapturedAt;
+    }
+    if (Date.parse(source.toCapturedAt) > Date.parse(target.toCapturedAt)) {
+      target.toCapturedAt = source.toCapturedAt;
+    }
+    target.droppedRecords += source.droppedRecords;
+  }
+  /**
+   * Coalesce into the newest pending gap of the same reason that has not been
+   * offered yet, so per-reason evidence stays one record while gaps queue.
+   */
+  writeGap(reason, fromCapturedAt, toCapturedAt, droppedRecords) {
+    for (let index = this.entries.length - 1; index >= 0; index -= 1) {
+      const candidate = this.entries[index];
+      if (candidate.kind !== "gap" || candidate.state !== "pending" || candidate.offered) continue;
+      if (candidate.runId !== this.identity.runId || candidate.gapReason !== reason) continue;
+      const record = this.parse(candidate);
+      if (record === null) break;
+      this.extendGapPayload(record.payload, { fromCapturedAt, toCapturedAt, droppedRecords });
+      candidate.capturedAt = record.capturedAt;
+      candidate.capturedAtMs = Date.parse(record.capturedAt);
+      const json2 = JSON.stringify(record);
+      const bytes = Buffer.byteLength(json2, "utf8");
+      this.totalBytes += bytes - candidate.bytes;
+      candidate.json = json2;
+      candidate.bytes = bytes;
+      return;
+    }
+    const gap = {
+      collectorId: this.identity.collectorId,
+      runId: this.identity.runId,
+      bootId: this.identity.bootId,
+      sequence: this.allocateSequence(),
+      capturedAt: this.isoNow(),
+      kind: "gap",
+      payload: { fromCapturedAt, toCapturedAt, droppedRecords, reason }
+    };
+    const json = JSON.stringify(gap);
+    this.insertJson("gap", gap, json, Buffer.byteLength(json, "utf8"));
+  }
+  pendingMetrics() {
+    return this.entries.filter((entry) => entry.state === "pending" && entry.kind === "metrics");
+  }
+  enforceAge() {
+    const cutoff = this.now() - this.limits.maxAgeMs;
+    const expired = this.pendingMetrics().filter((entry) => entry.capturedAtMs < cutoff);
+    if (expired.length > 0) this.evict(expired, "outbox-age");
+  }
+  /** Evict oldest pending metrics until the queue fits `targetBytes`. */
+  enforceBytes(targetBytes) {
+    if (this.totalBytes <= targetBytes) return;
+    const pending = this.pendingMetrics();
+    const victims = [];
+    for (const entry of pending) {
+      if (this.totalBytes - sumBytes(victims) <= targetBytes) break;
+      victims.push(entry);
+    }
+    if (victims.length === 0 && pending.length > 0) victims.push(pending[0]);
+    if (victims.length > 0) this.evict(victims, "outbox-bytes");
+  }
+  /** Settle the caps that can change after any admission or eviction. */
+  enforceAdmission() {
+    this.enforceBudget();
+    this.enforceGapCap();
+  }
+  enforceBudget() {
+    const budget2 = this.budget;
+    if (budget2 === null) return;
+    const tried = /* @__PURE__ */ new Set();
+    let guard = 0;
+    while (budget2.overBy() > 0 && guard < 1e4) {
+      guard += 1;
+      const target = budget2.largest(tried);
+      if (target === null) break;
+      if (target.evictForBudget("disk-budget") === 0) tried.add(target);
+    }
+  }
+  /** Hard ceiling on retained gap records: merge the oldest pending gaps. */
+  enforceGapCap() {
+    let guard = 0;
+    while (this.gapCount() > this.limits.maxGapRecords && guard < 1e4) {
+      guard += 1;
+      const gaps = this.entries.filter((entry) => entry.kind === "gap" && entry.state === "pending");
+      if (gaps.length < 2) return;
+      const older = gaps[0];
+      const newer = gaps[1];
+      const olderRecord = this.parse(older);
+      const merged = this.parse(newer);
+      if (olderRecord === null || merged === null) return;
+      this.extendGapPayload(merged.payload, olderRecord.payload);
+      merged.collectorId = this.identity.collectorId;
+      merged.runId = this.identity.runId;
+      merged.bootId = this.identity.bootId;
+      merged.sequence = this.allocateSequence();
+      merged.capturedAt = this.isoNow();
+      this.remove(newer);
+      this.remove(older);
+      const json = JSON.stringify(merged);
+      this.insertJson("gap", merged, json, Buffer.byteLength(json, "utf8"));
+    }
+  }
+  /**
+   * Read one entry as a record. Ours is always self-written, so a parse failure
+   * means an internal bug: count it as dropped and forget the row rather than
+   * stalling every later record, matching the durable queue's corrupt-row path.
+   */
+  parse(entry) {
+    try {
+      return JSON.parse(entry.json);
+    } catch {
+      this.remove(entry);
+      this.droppedSinceOpen += 1;
+      return null;
+    }
+  }
+  gapCount() {
+    return this.entries.reduce((count, entry) => entry.kind === "gap" ? count + 1 : count, 0);
+  }
+};
+function sumBytes(entries2) {
+  return entries2.reduce((total, entry) => total + entry.bytes, 0);
+}
+
 // src/contracts/telemetry.ts
 var MAX_MESSAGE_BYTES = 262144;
 var MAX_DETAIL_BYTES = 1048576;
@@ -1702,7 +2143,7 @@ function inboundText(data) {
   }
   return "";
 }
-function refKey(ref) {
+function refKey2(ref) {
   return `${ref.runId}\0${ref.sequence}`;
 }
 function toRef(record) {
@@ -2245,7 +2686,7 @@ var DestinationSession = class {
     const id2 = this.nextBatchId++;
     const entry = {
       refs,
-      keys: new Set(refs.map(refKey)),
+      keys: new Set(refs.map(refKey2)),
       mode,
       timer: setTimeout(() => this.handleAckTimeout(id2), this.ackTimeoutMs)
     };
@@ -2283,7 +2724,7 @@ var DestinationSession = class {
         `hub rejected ${message.rejected.length} record(s): ${message.rejected[0]?.reason ?? "no reason given"}`
       );
     }
-    const ackedKeys = new Set([...accepted, ...rejected].map(refKey));
+    const ackedKeys = new Set([...accepted, ...rejected].map(refKey2));
     const touched = [];
     for (const [id2, batch] of [...this.inFlight.entries()]) {
       let intersects = false;
@@ -2303,7 +2744,7 @@ var DestinationSession = class {
       for (const batch of toRelease) {
         this.inFlight.delete(this.batchIdOf(batch));
         clearTimeout(batch.timer);
-        this.outbox.release(batch.refs.filter((ref) => batch.keys.has(refKey(ref))));
+        this.outbox.release(batch.refs.filter((ref) => batch.keys.has(refKey2(ref))));
       }
       this.log(`hub asked to retry after ${delay}ms; replay paused`);
     }
@@ -2353,6 +2794,13 @@ var DestinationSession = class {
 };
 
 // collector/destinations/connection.ts
+function leftoverDurableQueue(dir) {
+  try {
+    return fs2.existsSync(path2.join(dir, "outbox.sqlite"));
+  } catch {
+    return false;
+  }
+}
 var HubConnection = class _HubConnection {
   index;
   policy;
@@ -2394,22 +2842,29 @@ var HubConnection = class _HubConnection {
     });
   }
   /**
-   * Opens this connection's durable outbox under its canonical endpoint URL
-   * and re-applies the privacy policy to recovered pending records so none of
-   * them can leave with forbidden fields. Sanitation never cadence-filters:
-   * retained samples were already cadence-selected when they were captured.
+   * Opens this connection's delivery queue in the configured mode and re-applies
+   * the privacy policy to any recovered pending record so none of them can
+   * leave with forbidden fields. Sanitation never cadence-filters: retained
+   * samples were already cadence-selected when they were captured.
+   *
+   * In `memory` mode no queue file is created at all. A durable queue left over
+   * from an earlier `durable` install is not opened or replayed; it is reported
+   * once so the operator knows unacknowledged samples are sitting on disk and
+   * how to discard them.
    */
   static open(options) {
-    const outbox = DestinationOutbox.open({
-      dir: outboxDirFor(options.stateDir, options.endpoint.url),
-      budget: options.budget,
-      allocateSequence: options.allocateSequence,
-      identity: {
-        collectorId: options.identity.collectorId,
-        runId: options.identity.runId,
-        bootId: options.identity.bootId
-      }
-    });
+    const identity = {
+      collectorId: options.identity.collectorId,
+      runId: options.identity.runId,
+      bootId: options.identity.bootId
+    };
+    const dir = outboxDirFor(options.stateDir, options.endpoint.url);
+    const outbox = options.queueMode === "durable" ? DestinationOutbox.open({ dir, budget: options.budget, allocateSequence: options.allocateSequence, identity }) : new MemoryDestinationQueue({ budget: options.budget, allocateSequence: options.allocateSequence, identity });
+    if (options.queueMode === "memory" && leftoverDurableQueue(dir)) {
+      options.onEvent?.(
+        `hub${options.index}: a durable outbox from an earlier COLLECTOR_QUEUE_MODE=durable install is unused; run rigscope upgrade, or delete it, to discard those unacknowledged samples`
+      );
+    }
     const connection = new _HubConnection(options, outbox);
     try {
       outbox.filterPending((record) => applySharing(record, connection.policy));
@@ -2523,9 +2978,9 @@ var nodeFs2 = __toESM(require("node:fs"));
 var nodeOs = __toESM(require("node:os"));
 
 // collector/sampling/procfs.ts
-function readTextOrNull(read, path2) {
+function readTextOrNull(read, path3) {
   try {
-    return read(path2);
+    return read(path3);
   } catch {
     return null;
   }
@@ -2751,8 +3206,8 @@ var CPU_HWMON_NAMES = /* @__PURE__ */ new Set([
   "cpu_thermal",
   "soc_thermal"
 ]);
-function readCounter(read, path2) {
-  const text2 = readTextOrNull(read, path2);
+function readCounter(read, path3) {
+  const text2 = readTextOrNull(read, path3);
   if (text2 === null || text2.trim() === "") return null;
   const value = Number(text2.trim());
   if (!Number.isSafeInteger(value) || value < 0) return null;
@@ -2773,8 +3228,8 @@ function hwmonOrder(name) {
   const match = /^hwmon(\d+)$/.exec(name);
   return match === null ? Number.MAX_SAFE_INTEGER : Number(match[1]);
 }
-function readCandidateTemperature(read, path2) {
-  const text2 = readTextOrNull(read, path2);
+function readCandidateTemperature(read, path3) {
+  const text2 = readTextOrNull(read, path3);
   if (text2 === null || text2.trim() === "") return null;
   const millidegrees = Number(text2.trim());
   if (!Number.isFinite(millidegrees)) return null;
@@ -2905,21 +3360,21 @@ function parsePressure(text2) {
   }
   return sawLine ? { someAvg10, fullAvg10 } : null;
 }
-function readPressure(read, path2) {
-  const text2 = readTextOrNull(read, path2);
+function readPressure(read, path3) {
+  const text2 = readTextOrNull(read, path3);
   return text2 === null ? null : parsePressure(text2);
 }
 
 // collector/sampling/sysfs-gpu.ts
-function number(read, path2, max = Number.MAX_SAFE_INTEGER, min = 0) {
-  const raw = readTextOrNull(read, path2)?.trim();
+function number(read, path3, max = Number.MAX_SAFE_INTEGER, min = 0) {
+  const raw = readTextOrNull(read, path3)?.trim();
   if (!raw || !/^[-]?\d+$/.test(raw)) return null;
   const value = Number(raw);
   return Number.isSafeInteger(value) && value >= min && value <= max ? value : null;
 }
-function entries(readers, path2) {
+function entries(readers, path3) {
   try {
-    return readers.readdir(path2).filter((name) => /^hwmon\d+$/.test(name)).sort().slice(0, 8);
+    return readers.readdir(path3).filter((name) => /^hwmon\d+$/.test(name)).sort().slice(0, 8);
   } catch {
     return [];
   }
@@ -2942,9 +3397,9 @@ function readSysfsGpu(readers, address) {
   if (values.memoryTotalBytes === 0) values.memoryTotalBytes = null;
   if (values.memoryTotalBytes === null || values.memoryUsedBytes !== null && values.memoryUsedBytes > values.memoryTotalBytes) values.memoryUsedBytes = null;
   for (const hwmon of entries(readers, `${base}/hwmon`)) {
-    const path2 = `${base}/hwmon/${hwmon}`;
-    const temp = number(read, `${path2}/temp1_input`, 2e5, -5e4);
-    const power = number(read, `${path2}/power1_average`, 1e10) ?? number(read, `${path2}/power1_input`, 1e10);
+    const path3 = `${base}/hwmon/${hwmon}`;
+    const temp = number(read, `${path3}/temp1_input`, 2e5, -5e4);
+    const power = number(read, `${path3}/power1_average`, 1e10) ?? number(read, `${path3}/power1_input`, 1e10);
     if (temp !== null && values.temperatureC === null) values.temperatureC = temp / 1e3;
     if (power !== null && values.powerWatts === null) values.powerWatts = power / 1e6;
   }
@@ -2955,9 +3410,9 @@ function readSysfsGpu(readers, address) {
 }
 
 // collector/sampling/network.ts
-function readOptional(read, path2) {
+function readOptional(read, path3) {
   try {
-    return read(path2);
+    return read(path3);
   } catch {
     return null;
   }
@@ -3476,10 +3931,10 @@ var USER_HZ = 100;
 var CPU_TOLERANCE_FRACTION = 0.05;
 var MAX_RATE_BYTES_PER_SEC = 1e13;
 var defaultReaders = {
-  readFile: (path2) => String(nodeFs2.readFileSync(path2, "utf8")),
-  readdir: (path2) => nodeFs2.readdirSync(path2),
-  statfs: (path2) => {
-    const stats = nodeFs2.statfsSync(path2);
+  readFile: (path3) => String(nodeFs2.readFileSync(path3, "utf8")),
+  readdir: (path3) => nodeFs2.readdirSync(path3),
+  statfs: (path3) => {
+    const stats = nodeFs2.statfsSync(path3);
     return {
       bsize: Number(stats.bsize),
       blocks: Number(stats.blocks),
@@ -3527,7 +3982,7 @@ function meanLatencyMs(operations, timeMs) {
 function inventorySignature(inventory) {
   return JSON.stringify({
     gpus: inventory.gpus.map((gpu) => [gpu.id, gpu.vendor, gpu.telemetry, gpu.memoryTotalBytes, gpu.pciBusId]),
-    filesystems: inventory.filesystems.map((fs2) => [fs2.id, fs2.totalBytes]),
+    filesystems: inventory.filesystems.map((fs3) => [fs3.id, fs3.totalBytes]),
     disks: inventory.disks.map((disk) => [disk.id, disk.sizeBytes]),
     network: inventory.network.map((iface) => [
       iface.id,
@@ -4694,9 +5149,9 @@ var ProcessScanner = class {
       }
     };
   }
-  async readText(path2) {
+  async readText(path3) {
     try {
-      return { ok: true, text: await import_node_fs3.promises.readFile(path2, "utf8") };
+      return { ok: true, text: await import_node_fs3.promises.readFile(path3, "utf8") };
     } catch (error) {
       return { ok: false, code: errorCode(error) };
     }
@@ -4781,8 +5236,8 @@ function parseIo(text2) {
 function parseCgroupUnit(text2) {
   for (const line of text2.split("\n")) {
     if (!line.startsWith("0::")) continue;
-    const path2 = line.slice(3);
-    const components = path2.split("/").filter((part) => part.length > 0);
+    const path3 = line.slice(3);
+    const components = path3.split("/").filter((part) => part.length > 0);
     const last = components[components.length - 1];
     if (!last) return null;
     if (!last.endsWith(".service") && !last.endsWith(".scope")) return null;
@@ -5232,7 +5687,7 @@ function budget(value, fallback) {
 // package.json
 var package_default = {
   name: "rigscope",
-  version: "0.2.0",
+  version: "0.2.1",
   private: false,
   engines: {
     node: ">=26.0.0"
@@ -5371,8 +5826,8 @@ var OperationsError = class extends Error {
 function isPrivateMode(mode) {
   return (mode & 63) === 0;
 }
-function ensurePrivateDir(path2) {
-  const absolute = (0, import_node_path3.resolve)(path2);
+function ensurePrivateDir(path3) {
+  const absolute = (0, import_node_path3.resolve)(path3);
   (0, import_node_fs4.mkdirSync)(absolute, { recursive: true, mode: PRIVATE_DIR_MODE });
   const stat = (0, import_node_fs4.lstatSync)(absolute);
   if (!stat.isDirectory() || stat.isSymbolicLink()) {
@@ -5385,23 +5840,48 @@ function ensurePrivateDir(path2) {
     );
   }
 }
+function assertPrivateRegularFile(path3, label) {
+  const absolute = (0, import_node_path3.resolve)(path3);
+  let stat;
+  try {
+    stat = (0, import_node_fs4.lstatSync)(absolute);
+  } catch (error) {
+    throw new OperationsError("missing-file", `${label} does not exist: ${absolute}`, { cause: error });
+  }
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    throw new OperationsError("unsafe-path", `${label} must be a regular file, not a symlink: ${absolute}`);
+  }
+  if (!isPrivateMode(stat.mode)) {
+    throw new OperationsError(
+      "insecure-permissions",
+      `${label} must be private (0600/0400); found ${formatMode(stat.mode)}: ${absolute}`
+    );
+  }
+  return stat;
+}
 function formatMode(mode) {
   return `0${(mode & 511).toString(8).padStart(3, "0")}`;
 }
-function writeFileAtomic(path2, content, mode) {
-  const absolute = (0, import_node_path3.resolve)(path2);
+function writePrivateFileBuffered(path3, content) {
+  const absolute = (0, import_node_path3.resolve)(path3);
   const parent = (0, import_node_path3.dirname)(absolute);
+  ensurePrivateDir(parent);
+  try {
+    assertPrivateRegularFile(absolute, "private file");
+  } catch (error) {
+    if (!(error instanceof OperationsError) || error.code !== "missing-file") throw error;
+  }
   const temporary = (0, import_node_path3.join)(parent, `.${(0, import_node_path3.basename)(absolute)}.tmp-${(0, import_node_crypto6.randomUUID)()}`);
   let fd = null;
+  let temporaryCreated = false;
   try {
-    fd = (0, import_node_fs4.openSync)(temporary, "wx", mode);
+    fd = (0, import_node_fs4.openSync)(temporary, "wx", PRIVATE_FILE_MODE);
+    temporaryCreated = true;
     (0, import_node_fs4.writeFileSync)(fd, content);
-    (0, import_node_fs4.fsyncSync)(fd);
     (0, import_node_fs4.closeSync)(fd);
     fd = null;
-    (0, import_node_fs4.chmodSync)(temporary, mode);
+    (0, import_node_fs4.chmodSync)(temporary, PRIVATE_FILE_MODE);
     (0, import_node_fs4.renameSync)(temporary, absolute);
-    fsyncDir(parent);
   } catch (error) {
     if (fd !== null) {
       try {
@@ -5409,39 +5889,24 @@ function writeFileAtomic(path2, content, mode) {
       } catch {
       }
     }
-    removeIfExists(temporary);
-    throw error;
-  }
-}
-function writePrivateFile(path2, content) {
-  ensurePrivateDir((0, import_node_path3.dirname)((0, import_node_path3.resolve)(path2)));
-  writeFileAtomic(path2, content, PRIVATE_FILE_MODE);
-}
-function fsyncDir(path2) {
-  let fd = null;
-  try {
-    fd = (0, import_node_fs4.openSync)(path2, "r");
-    (0, import_node_fs4.fsyncSync)(fd);
-  } catch {
-  } finally {
-    if (fd !== null) {
-      try {
-        (0, import_node_fs4.closeSync)(fd);
-      } catch {
-      }
+    if (temporaryCreated) removeIfExists(temporary);
+    if (error.code === "ENOENT") {
+      throw new OperationsError("missing-file", `directory does not exist: ${parent}`, { cause: error });
     }
+    throw error;
   }
 }
-function removeIfExists(path2) {
+function removeIfExists(path3) {
   try {
-    (0, import_node_fs4.unlinkSync)(path2);
+    (0, import_node_fs4.unlinkSync)(path3);
   } catch (error) {
     if (error.code !== "ENOENT") throw error;
   }
 }
 
 // collector/runtime.ts
-async function runDurableCollector(config, identity, statePath, mock) {
+var HEALTH_WRITE_INTERVAL_MS = 5e3;
+async function runCollectorLoop(config, identity, statePath, mock) {
   const temporary = mock && !process.env.COLLECTOR_STATE_FILE ? (0, import_node_fs5.mkdtempSync)((0, import_node_path4.join)((0, import_node_os2.tmpdir)(), "rigscope-mock-")) : null;
   const stateDir = temporary ?? (0, import_node_path4.dirname)(statePath);
   const releaseLease = acquireProcessLease((0, import_node_path4.join)(stateDir, "collector-runtime.lock"));
@@ -5458,6 +5923,7 @@ async function runDurableCollector(config, identity, statePath, mock) {
         stateDir,
         baseIntervalMs: config.intervalMs,
         identity,
+        queueMode: config.queueMode,
         budget: budget2,
         allocateSequence: () => sequence.next(),
         sampler,
@@ -5492,8 +5958,8 @@ async function runDurableCollector(config, identity, statePath, mock) {
       const at = performance.now();
       for (const connection of connections) connection.acceptSample(record, at);
       const healthFile = process.env.COLLECTOR_HEALTH_FILE;
-      if (healthFile && Date.now() - lastHealthWrite >= 1e3) {
-        writePrivateFile(healthFile, JSON.stringify({
+      if (healthFile && Date.now() - lastHealthWrite >= HEALTH_WRITE_INTERVAL_MS) {
+        writePrivateFileBuffered(healthFile, JSON.stringify({
           version: APPLICATION_VERSION,
           pid: process.pid,
           sampledAt: Date.now()
@@ -5520,7 +5986,7 @@ async function runDurableCollector(config, identity, statePath, mock) {
     for (const connection of connections) connection.stop();
     releaseLease();
     if (temporary) (0, import_node_fs5.rmSync)(temporary, { recursive: true, force: true });
-    console.log("collector stopping; durable pending delivery saved");
+    console.log(config.queueMode === "durable" ? "collector stopping; durable pending delivery saved" : "collector stopping; unacknowledged samples in RAM are discarded");
     setTimeout(() => process.exit(0), 250).unref();
     setTimeout(() => process.exit(0), 3e3).unref();
   };
@@ -5599,7 +6065,7 @@ async function run() {
     runId,
     bootId: boot.bootId
   };
-  await runDurableCollector(config, identity, process.env.COLLECTOR_STATE_FILE || defaultStatePath(), isMock);
+  await runCollectorLoop(config, identity, process.env.COLLECTOR_STATE_FILE || defaultStatePath(), isMock);
   return 0;
 }
 function isMainModule() {