chainlesschain 0.166.46 → 0.166.48

package/src/lib/background-agent-list-index.js

@@ -0,0 +1,222 @@
+import {
+  chmodSync,
+  lstatSync,
+  openSync,
+  closeSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import { join } from "node:path";
+
+export const BACKGROUND_AGENT_LIST_INDEX_SCHEMA =
+  "chainlesschain.background-agent-list-index/v1";
+export const BACKGROUND_AGENT_LIST_INDEX_FILE =
+  ".background-agent-list-index-v1";
+
+const STATE_FILE = /^(bg-[A-Za-z0-9-]+)\.json$/u;
+const MAX_INDEX_BYTES = 64 * 1024 * 1024;
+const MAX_INDEX_ENTRIES = 1_000_000;
+
+function sha256(value, domain) {
+  return `sha256:${createHash("sha256")
+    .update(domain)
+    .update("\0")
+    .update(value)
+    .digest("hex")}`;
+}
+
+function stateFileSignature(directory, name, id) {
+  const target = join(directory, name);
+  const link = lstatSync(target);
+  if (!link.isFile() || link.isSymbolicLink()) {
+    throw new TypeError(`background agent state is not a regular file: ${id}`);
+  }
+  const stat = statSync(target, { bigint: true });
+  return {
+    id,
+    name,
+    size: String(stat.size),
+    mtimeNs: String(stat.mtimeNs),
+    ctimeNs: String(stat.ctimeNs),
+    dev: String(stat.dev),
+    ino: String(stat.ino),
+  };
+}
+
+function collectInventory(directory) {
+  const files = readdirSync(directory, { withFileTypes: true })
+    .map((entry) => {
+      const match = STATE_FILE.exec(entry.name);
+      if (!match || entry.name.includes(".job.")) return null;
+      if (!entry.isFile()) {
+        throw new TypeError(
+          `background agent state is not a regular file: ${match[1]}`,
+        );
+      }
+      return stateFileSignature(directory, entry.name, match[1]);
+    })
+    .filter(Boolean)
+    .sort((left, right) => left.name.localeCompare(right.name, "en"));
+  if (files.length > MAX_INDEX_ENTRIES) {
+    throw new RangeError(
+      `background agent list index exceeds ${MAX_INDEX_ENTRIES} entries`,
+    );
+  }
+  const encoded = JSON.stringify(files);
+  return {
+    files,
+    digest: sha256(encoded, "cc.background-agent-list-inventory/v1"),
+  };
+}
+
+function normalizeEntry(value, inventoryIds) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  if (!inventoryIds.has(value.id)) return null;
+  const startedAt = Number(value.startedAt);
+  if (!Number.isFinite(startedAt) || startedAt < 0) return null;
+  if (
+    typeof value.status !== "string" ||
+    value.status.length === 0 ||
+    value.status.length > 64
+  ) {
+    return null;
+  }
+  return { id: value.id, startedAt, status: value.status };
+}
+
+function readCachedIndex(directory, inventory) {
+  const target = join(directory, BACKGROUND_AGENT_LIST_INDEX_FILE);
+  try {
+    const stat = lstatSync(target);
+    if (
+      !stat.isFile() ||
+      stat.isSymbolicLink() ||
+      stat.size <= 0 ||
+      stat.size > MAX_INDEX_BYTES
+    ) {
+      return null;
+    }
+    const parsed = JSON.parse(readFileSync(target, "utf8"));
+    if (
+      !parsed ||
+      typeof parsed !== "object" ||
+      Array.isArray(parsed) ||
+      parsed.schema !== BACKGROUND_AGENT_LIST_INDEX_SCHEMA ||
+      parsed.inventoryDigest !== inventory.digest ||
+      parsed.fileCount !== inventory.files.length ||
+      !Array.isArray(parsed.entries) ||
+      parsed.entries.length > inventory.files.length
+    ) {
+      return null;
+    }
+    const inventoryIds = new Set(inventory.files.map((file) => file.id));
+    const entries = parsed.entries.map((entry) =>
+      normalizeEntry(entry, inventoryIds),
+    );
+    if (entries.some((entry) => entry === null)) return null;
+    if (new Set(entries.map((entry) => entry.id)).size !== entries.length) {
+      return null;
+    }
+    const contentDigest = sha256(
+      JSON.stringify({
+        schema: parsed.schema,
+        inventoryDigest: parsed.inventoryDigest,
+        fileCount: parsed.fileCount,
+        entries,
+      }),
+      "cc.background-agent-list-index/v1",
+    );
+    if (parsed.digest !== contentDigest) return null;
+    return entries;
+  } catch {
+    return null;
+  }
+}
+
+function writeCachedIndex(directory, inventory, entries) {
+  const target = join(directory, BACKGROUND_AGENT_LIST_INDEX_FILE);
+  const value = {
+    schema: BACKGROUND_AGENT_LIST_INDEX_SCHEMA,
+    inventoryDigest: inventory.digest,
+    fileCount: inventory.files.length,
+    entries,
+  };
+  value.digest = sha256(
+    JSON.stringify(value),
+    "cc.background-agent-list-index/v1",
+  );
+  const temporary = `${target}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+  try {
+    const descriptor = openSync(temporary, "wx", 0o600);
+    try {
+      writeFileSync(descriptor, `${JSON.stringify(value)}\n`, "utf8");
+    } finally {
+      closeSync(descriptor);
+    }
+    if (process.platform !== "win32") chmodSync(temporary, 0o600);
+    renameSync(temporary, target);
+  } catch {
+    rmSync(temporary, { force: true });
+  }
+}
+
+function projectState(state, id) {
+  if (!state || typeof state !== "object" || String(state.id) !== id) {
+    return null;
+  }
+  const startedAt = Number(state.startedAt || 0);
+  if (!Number.isFinite(startedAt) || startedAt < 0) return null;
+  if (
+    typeof state.status !== "string" ||
+    state.status.length === 0 ||
+    state.status.length > 64
+  ) {
+    return null;
+  }
+  return { id, startedAt, status: state.status };
+}
+
+/**
+ * Load a content-free projection when it exactly matches every authority-file
+ * identity. A miss rebuilds from authority and retries the inventory fence;
+ * callers must fall back to their authoritative scan if a concurrent writer
+ * prevents a stable rebuild.
+ */
+export function loadBackgroundAgentListIndex({ directory, readState }) {
+  if (typeof directory !== "string" || !directory) {
+    throw new TypeError("background agent list index directory is required");
+  }
+  if (typeof readState !== "function") {
+    throw new TypeError("background agent list index readState is required");
+  }
+  const inventory = collectInventory(directory);
+  const cached = readCachedIndex(directory, inventory);
+  if (cached) {
+    return Object.freeze({
+      source: "index",
+      entries: Object.freeze(cached.map((entry) => Object.freeze(entry))),
+    });
+  }
+
+  const entries = inventory.files
+    .map((file) => projectState(readState(file.id), file.id))
+    .filter(Boolean);
+  const verifiedInventory = collectInventory(directory);
+  if (verifiedInventory.digest !== inventory.digest) {
+    const error = new Error(
+      "background agent authority changed while rebuilding the list index",
+    );
+    error.code = "BACKGROUND_AGENT_LIST_INDEX_RACE";
+    throw error;
+  }
+  writeCachedIndex(directory, inventory, entries);
+  return Object.freeze({
+    source: "rebuilt",
+    entries: Object.freeze(entries.map((entry) => Object.freeze(entry))),
+  });
+}

package/src/lib/background-agent-supervisor.js

@@ -60,9 +60,12 @@ import {
   cleanupBackgroundAgentKeeperPipeDirectory,
   prepareBackgroundAgentKeeperPipePath,
 } from "./background-agent-keeper-protocol.js";
+import { loadBackgroundAgentListIndex } from "./background-agent-list-index.js";
 
 export const DEFAULT_HEARTBEAT_INTERVAL_MS = 5000;
 export const DEFAULT_HEARTBEAT_STALE_MS = 120000;
+export const DEFAULT_BACKGROUND_AGENT_PAGE_LIMIT = 50;
+export const MAX_BACKGROUND_AGENT_PAGE_LIMIT = 200;
 
 /**
  * Pid identity tolerance (Gap 1: OS pid reuse). A pid alone does not identify
@@ -1370,7 +1373,14 @@ export function mutateBackgroundAgentState(id, updater, options = {}) {
       // A live numeric pid can belong to a later process after the lock owner
       // was killed. Use the lock acquisition timestamp as a one-sided identity
       // fence so only an owner which existed before acquisition still blocks.
-      _isOwnerAlive: isBackgroundAgentStateLockOwnerAlive,
+      // Periodic telemetry may request a strict try-lock. In that mode an
+      // incumbent is deliberately retained without a Windows PID/start-time
+      // probe: a heartbeat must never synchronously stall a control channel
+      // merely to determine whether it could reclaim a lock.
+      _isOwnerAlive:
+        options.probeLockOwner === false
+          ? () => true
+          : isBackgroundAgentStateLockOwnerAlive,
     },
   );
 }
@@ -1458,57 +1468,65 @@ export async function deliverBackgroundNeedsInputNotification(
  * the only authority to start or continue a turn: a terminal, deleted,
  * corrupt, differently-generated or already-owned record is never revived.
  */
-export function claimBackgroundAgentHeartbeat(id, heartbeat = {}) {
+export function claimBackgroundAgentHeartbeat(
+  id,
+  heartbeat = {},
+  options = {},
+) {
   const workerPid = Number(heartbeat.workerPid ?? heartbeat.pid);
   const workerGeneration = heartbeat.workerGeneration;
   if (!Number.isInteger(workerPid) || workerPid <= 0) {
     throw new Error(`Invalid background worker pid: ${heartbeat.workerPid}`);
   }
-  return mutateBackgroundAgentState(id, (current) => {
-    if (!current || current.status !== "running") return null;
-    if (current.stopRequestedAt) return null;
-    if (
-      current.workerGeneration &&
-      current.workerGeneration !== workerGeneration
-    ) {
-      return null;
-    }
-    const claimedWorkerPid = Number(current.workerClaimedPid);
-    if (
-      current.workerClaimedPid != null &&
-      Number.isInteger(claimedWorkerPid) &&
-      claimedWorkerPid > 0 &&
-      claimedWorkerPid !== workerPid
-    ) {
-      return null;
-    }
-    const currentWorkerPid = Number(current.workerPid ?? current.pid);
-    if (
-      !current.workerGeneration &&
-      Number.isInteger(currentWorkerPid) &&
-      currentWorkerPid > 0 &&
-      currentWorkerPid !== workerPid &&
-      current.launchFinalizationUncertain !== true
-    ) {
-      return null;
-    }
-    return {
-      ...current,
-      ...heartbeat,
-      id,
-      pid: workerPid,
-      workerPid,
-      workerClaimedPid:
+  return mutateBackgroundAgentState(
+    id,
+    (current) => {
+      if (!current || current.status !== "running") return null;
+      if (current.stopRequestedAt) return null;
+      if (
+        current.workerGeneration &&
+        current.workerGeneration !== workerGeneration
+      ) {
+        return null;
+      }
+      const claimedWorkerPid = Number(current.workerClaimedPid);
+      if (
         current.workerClaimedPid != null &&
         Number.isInteger(claimedWorkerPid) &&
-        claimedWorkerPid > 0
-          ? claimedWorkerPid
-          : workerPid,
-      workerClaimedAt: current.workerClaimedAt || Date.now(),
-      status: "running",
-      heartbeatAt: heartbeat.heartbeatAt ?? Date.now(),
-    };
-  });
+        claimedWorkerPid > 0 &&
+        claimedWorkerPid !== workerPid
+      ) {
+        return null;
+      }
+      const currentWorkerPid = Number(current.workerPid ?? current.pid);
+      if (
+        !current.workerGeneration &&
+        Number.isInteger(currentWorkerPid) &&
+        currentWorkerPid > 0 &&
+        currentWorkerPid !== workerPid &&
+        current.launchFinalizationUncertain !== true
+      ) {
+        return null;
+      }
+      return {
+        ...current,
+        ...heartbeat,
+        id,
+        pid: workerPid,
+        workerPid,
+        workerClaimedPid:
+          current.workerClaimedPid != null &&
+          Number.isInteger(claimedWorkerPid) &&
+          claimedWorkerPid > 0
+            ? claimedWorkerPid
+            : workerPid,
+        workerClaimedAt: current.workerClaimedAt || Date.now(),
+        status: "running",
+        heartbeatAt: heartbeat.heartbeatAt ?? Date.now(),
+      };
+    },
+    options,
+  );
 }
 
 function deleteBackgroundAgentState(id, predicate = () => true) {
@@ -2038,7 +2056,21 @@ export function effectiveBackgroundAgentState(state, options = {}) {
   return next;
 }
 
-export function listBackgroundAgents(options = {}) {
+function backgroundAgentStartedAt(state) {
+  const startedAt = Number(state?.startedAt);
+  return Number.isFinite(startedAt) && startedAt >= 0 ? startedAt : 0;
+}
+
+function compareBackgroundAgentListEntries(a, b) {
+  const newestFirst = backgroundAgentStartedAt(b) - backgroundAgentStartedAt(a);
+  if (newestFirst !== 0) return newestFirst;
+  return String(a.id).localeCompare(String(b.id));
+}
+
+function listBackgroundAgentEntries(
+  options = {},
+  { stableTieBreak = false } = {},
+) {
   return (
     readdirSync(backgroundAgentsDir())
       .filter((name) => name.endsWith(".json") && !name.includes(".job."))
@@ -2046,7 +2078,11 @@ export function listBackgroundAgents(options = {}) {
       .filter(Boolean)
       .map((state) => effectiveBackgroundAgentState(state, options))
       .filter((state) => options.all || state.status === "running")
-      .sort((a, b) => (b.startedAt || 0) - (a.startedAt || 0))
+      .sort(
+        stableTieBreak
+          ? compareBackgroundAgentListEntries
+          : (a, b) => (b.startedAt || 0) - (a.startedAt || 0),
+      )
       // Display-only enrichment: attach the canonical unified lifecycle state.
       // This is a list feed (never written back to disk), so the derived field
       // cannot leak into the on-disk schema the way it would in the mutate paths.
@@ -2054,6 +2090,155 @@ export function listBackgroundAgents(options = {}) {
   );
 }
 
+function normalizeBackgroundAgentPageLimit(value) {
+  if (value === undefined || value === null) {
+    return DEFAULT_BACKGROUND_AGENT_PAGE_LIMIT;
+  }
+  const limit =
+    typeof value === "string" && /^\d+$/u.test(value) ? Number(value) : value;
+  if (
+    !Number.isSafeInteger(limit) ||
+    limit < 1 ||
+    limit > MAX_BACKGROUND_AGENT_PAGE_LIMIT
+  ) {
+    throw new TypeError(
+      `background agent page limit must be an integer from 1 to ${MAX_BACKGROUND_AGENT_PAGE_LIMIT}`,
+    );
+  }
+  return limit;
+}
+
+function encodeBackgroundAgentPageCursor(state, all) {
+  const payload = JSON.stringify({
+    version: 1,
+    all: all === true,
+    startedAt: backgroundAgentStartedAt(state),
+    id: safeId(state?.id),
+  });
+  return `bg1.${Buffer.from(payload).toString("base64url")}`;
+}
+
+function decodeBackgroundAgentPageCursor(value) {
+  if (value === undefined || value === null) return null;
+  if (
+    typeof value !== "string" ||
+    value.length > 768 ||
+    !/^bg1\.[A-Za-z0-9_-]+$/u.test(value)
+  ) {
+    throw new TypeError("background agent page cursor is invalid");
+  }
+  let payload;
+  try {
+    const encoded = value.slice(4);
+    const decoded = Buffer.from(encoded, "base64url");
+    if (decoded.toString("base64url") !== encoded) {
+      throw new Error("cursor encoding is not canonical");
+    }
+    payload = JSON.parse(decoded.toString("utf8"));
+  } catch {
+    throw new TypeError("background agent page cursor is invalid");
+  }
+  if (
+    !payload ||
+    typeof payload !== "object" ||
+    Array.isArray(payload) ||
+    Object.keys(payload).length !== 4 ||
+    payload.version !== 1 ||
+    typeof payload.all !== "boolean" ||
+    !Number.isSafeInteger(payload.startedAt) ||
+    payload.startedAt < 0
+  ) {
+    throw new TypeError("background agent page cursor is invalid");
+  }
+  let id;
+  try {
+    id = safeId(payload.id);
+  } catch {
+    throw new TypeError("background agent page cursor is invalid");
+  }
+  return { all: payload.all, startedAt: payload.startedAt, id };
+}
+
+function isBackgroundAgentAfterCursor(state, cursor) {
+  const startedAt = backgroundAgentStartedAt(state);
+  if (startedAt !== cursor.startedAt) return startedAt < cursor.startedAt;
+  return String(state.id).localeCompare(cursor.id) > 0;
+}
+
+/**
+ * Return one stable, bounded page from the newest-first background session
+ * feed. The cursor is an opaque ordering fence, not an authority token.
+ *
+ * State files are still read to preserve the current authoritative lifecycle
+ * reconciliation. A future read-only index may reduce that I/O, but this API
+ * immediately bounds the object graph and protocol response retained by a
+ * caller.
+ */
+export function listBackgroundAgentsPage(options = {}) {
+  const limit = normalizeBackgroundAgentPageLimit(options.limit);
+  const cursor = decodeBackgroundAgentPageCursor(options.cursor);
+  if (cursor && cursor.all !== (options.all === true)) {
+    throw new TypeError(
+      "background agent page cursor does not match the requested filter",
+    );
+  }
+  let indexed = null;
+  try {
+    indexed = loadBackgroundAgentListIndex({
+      directory: backgroundAgentsDir(),
+      readState: readBackgroundAgentState,
+    });
+  } catch {
+    // The index is a disposable, content-free projection. Authority races,
+    // corruption, or an unwritable cache must retain the full-scan behavior.
+  }
+  if (indexed) {
+    const projected = [];
+    const summaries = [...indexed.entries]
+      .filter((state) => options.all || state.status === "running")
+      .sort(compareBackgroundAgentListEntries);
+    for (const summary of summaries) {
+      if (cursor && !isBackgroundAgentAfterCursor(summary, cursor)) continue;
+      const state = readBackgroundAgentState(summary.id);
+      if (!state) continue;
+      const effective = effectiveBackgroundAgentState(state, options);
+      if (!effective || (!options.all && effective.status !== "running")) {
+        continue;
+      }
+      if (cursor && !isBackgroundAgentAfterCursor(effective, cursor)) continue;
+      projected.push(withLifecycleState(effective));
+      if (projected.length > limit) break;
+    }
+    const sessions = projected.slice(0, limit);
+    const nextCursor =
+      projected.length > sessions.length
+        ? encodeBackgroundAgentPageCursor(sessions.at(-1), options.all)
+        : null;
+    return Object.freeze({
+      sessions: Object.freeze(sessions),
+      nextCursor,
+    });
+  }
+  const eligible = cursor
+    ? listBackgroundAgentEntries(options, { stableTieBreak: true }).filter(
+        (state) => isBackgroundAgentAfterCursor(state, cursor),
+      )
+    : listBackgroundAgentEntries(options, { stableTieBreak: true });
+  const sessions = eligible.slice(0, limit);
+  const nextCursor =
+    eligible.length > sessions.length
+      ? encodeBackgroundAgentPageCursor(sessions.at(-1), options.all)
+      : null;
+  return Object.freeze({
+    sessions: Object.freeze(sessions),
+    nextCursor,
+  });
+}
+
+export function listBackgroundAgents(options = {}) {
+  return listBackgroundAgentEntries(options);
+}
+
 function sleepSyncMs(ms) {
   try {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);