chainlesschain 0.165.2 → 0.165.4

package/src/lib/artifact-store.js

@@ -24,6 +24,7 @@ import fs from "fs";
 import os from "os";
 import path from "path";
 import crypto from "crypto";
+import { withFileLock } from "./with-file-lock.js";
 
 export const ARTIFACT_KINDS = Object.freeze([
   "report",
@@ -62,6 +63,7 @@ export function publicArtifactMetadata(entry) {
     expiresAt,
     immutable,
     recordDigest,
+    lineage,
   } = entry;
   return {
     id,
@@ -76,6 +78,7 @@ export function publicArtifactMetadata(entry) {
     expiresAt,
     immutable: immutable === true,
     recordDigest: recordDigest || null,
+    ...(lineage ? { lineage } : {}),
   };
 }
 
@@ -120,10 +123,36 @@ function normalizeKind(kind) {
   return ARTIFACT_KINDS.includes(k) ? k : "other";
 }
 
+function normalizeLineage(lineage) {
+  if (lineage == null) return null;
+  if (typeof lineage !== "object" || Array.isArray(lineage)) {
+    throw new Error("artifact lineage must be an object");
+  }
+  let normalized;
+  try {
+    normalized = JSON.parse(JSON.stringify(lineage));
+  } catch {
+    throw new Error("artifact lineage must be JSON serializable");
+  }
+  if (
+    !normalized ||
+    typeof normalized !== "object" ||
+    Array.isArray(normalized)
+  ) {
+    throw new Error("artifact lineage must be a JSON object");
+  }
+  return normalized;
+}
+
 export class ArtifactStore {
-  constructor({ dir = null, now = () => Date.now() } = {}) {
+  constructor({
+    dir = null,
+    now = () => Date.now(),
+    indexLock = withFileLock,
+  } = {}) {
     this.dir = dir || artifactsDir();
     this._now = typeof now === "function" ? now : () => now;
+    this._indexLock = indexLock;
   }
 
   _indexFile() {
@@ -138,6 +167,31 @@ export class ArtifactStore {
     fs.mkdirSync(this._filesDir(), { recursive: true });
   }
 
+  _withIndexLock(callback) {
+    this._ensureDirs();
+    return this._indexLock(this._indexFile(), callback, {
+      failIfUnavailable: true,
+      timeoutMs: 30_000,
+      retryMs: 1,
+      maxRetryMs: 8,
+      retryJitterMs: 4,
+    });
+  }
+
+  /**
+   * Run a read-only callback against one locked index generation. The callback
+   * may inspect stored bytes before it returns; all ArtifactStore mutations use
+   * this same lock and therefore cannot replace that generation mid-read.
+   */
+  withIndexSnapshot(callback) {
+    if (typeof callback !== "function") {
+      throw new TypeError("artifact index snapshot requires a callback");
+    }
+    return this._withIndexLock(() =>
+      callback(Object.freeze(this._readEntries())),
+    );
+  }
+
   /**
    * Publish a file as an artifact (copy + metadata row).
    * @param {{ filePath: string, title?: string, kind?: string,
@@ -162,14 +216,16 @@ export class ArtifactStore {
       );
     }
     const body = fs.readFileSync(abs);
-    return this._publishData(body, {
-      fileName: path.basename(abs),
-      title,
-      kind,
-      sessionId,
-      ttlDays,
-      sourcePath: abs,
-    });
+    return this._withIndexLock(() =>
+      this._publishDataUnlocked(body, {
+        fileName: path.basename(abs),
+        title,
+        kind,
+        sessionId,
+        ttlDays,
+        sourcePath: abs,
+      }),
+    );
   }
 
   /**
@@ -191,20 +247,78 @@ export class ArtifactStore {
     if (typeof data !== "string" && !Buffer.isBuffer(data)) {
       throw new Error("publishData requires string or Buffer data");
     }
-    return this._publishData(Buffer.from(data), {
-      fileName,
-      title,
-      kind,
-      mime,
-      sessionId,
-      ttlDays,
-      immutable,
-      recordDigest,
-      sourcePath: null,
+    return this._withIndexLock(() =>
+      this._publishDataUnlocked(Buffer.from(data), {
+        fileName,
+        title,
+        kind,
+        mime,
+        sessionId,
+        ttlDays,
+        immutable,
+        recordDigest,
+        sourcePath: null,
+      }),
+    );
+  }
+
+  /**
+   * Publish generated bytes once for a stable authority digest.
+   *
+   * The strict cross-process index lock makes response-loss retries return the
+   * same metadata row instead of creating duplicate managed artifacts. The
+   * caller still owns the semantic validation of the persisted lineage and
+   * must verifyIntegrity() before treating the returned entry as readable.
+   */
+  publishDataOnce({
+    data,
+    fileName = "artifact.bin",
+    title,
+    kind,
+    mime,
+    sessionId = null,
+    ttlDays,
+    immutable = false,
+    recordDigest,
+    lineage,
+  } = {}) {
+    if (typeof data !== "string" && !Buffer.isBuffer(data)) {
+      throw new Error("publishDataOnce requires string or Buffer data");
+    }
+    const stableDigest = String(recordDigest || "");
+    if (!/^sha256:[a-f0-9]{64}$/u.test(stableDigest)) {
+      throw new Error("publishDataOnce requires a canonical recordDigest");
+    }
+    const normalizedLineage = normalizeLineage(lineage);
+    return this._withIndexLock(() => {
+      const matches = this._readEntries().filter(
+        (entry) => entry.recordDigest === stableDigest,
+      );
+      if (matches.length > 1) {
+        throw new Error(
+          `artifact authority ${stableDigest} has duplicate index rows`,
+        );
+      }
+      if (matches.length === 1) {
+        return Object.freeze({ entry: matches[0], published: false });
+      }
+      const entry = this._publishDataUnlocked(Buffer.from(data), {
+        fileName,
+        title,
+        kind,
+        mime,
+        sessionId,
+        ttlDays,
+        immutable,
+        recordDigest: stableDigest,
+        lineage: normalizedLineage,
+        sourcePath: null,
+      });
+      return Object.freeze({ entry, published: true });
     });
   }
 
-  _publishData(
+  _publishDataUnlocked(
     body,
     {
       fileName,
@@ -215,6 +329,7 @@ export class ArtifactStore {
       ttlDays,
       immutable = false,
       recordDigest = null,
+      lineage = null,
       sourcePath = null,
     },
   ) {
@@ -247,10 +362,15 @@ export class ArtifactStore {
       expiresAt: new Date(createdAt + days * 24 * 60 * 60 * 1000).toISOString(),
       immutable: immutable === true,
       recordDigest: recordDigest ? String(recordDigest) : null,
+      ...(lineage ? { lineage: normalizeLineage(lineage) } : {}),
     };
     this._ensureDirs();
     const storedPath = path.join(this._filesDir(), entry.file);
-    fs.writeFileSync(storedPath, body, { flag: "wx" });
+    fs.writeFileSync(storedPath, body, {
+      flag: "wx",
+      mode: 0o600,
+      flush: true,
+    });
     if (entry.immutable) {
       try {
         fs.chmodSync(storedPath, 0o444);
@@ -259,12 +379,37 @@ export class ArtifactStore {
         // support; immutable here means append-only/no update API, not WORM.
       }
     }
-    fs.appendFileSync(this._indexFile(), JSON.stringify(entry) + "\n", "utf-8");
+    let descriptor = null;
+    try {
+      descriptor = fs.openSync(
+        this._indexFile(),
+        fs.constants.O_WRONLY |
+          fs.constants.O_APPEND |
+          fs.constants.O_CREAT |
+          Number(fs.constants.O_NOFOLLOW || 0),
+        0o600,
+      );
+      const indexStat = fs.fstatSync(descriptor);
+      if (!indexStat.isFile() || Number(indexStat.nlink) !== 1) {
+        throw new Error("artifact index identity is invalid");
+      }
+      fs.writeFileSync(descriptor, `${JSON.stringify(entry)}\n`, "utf-8");
+      fs.fsyncSync(descriptor);
+    } catch (error) {
+      try {
+        this._deleteStoredFile(entry);
+      } catch {
+        /* best-effort rollback of an unpublished stored copy */
+      }
+      throw error;
+    } finally {
+      if (descriptor !== null) fs.closeSync(descriptor);
+    }
     return entry;
   }
 
   /** All (non-corrupt) metadata rows, oldest first. */
-  list({ sessionId } = {}) {
+  _readEntries({ sessionId } = {}) {
     let raw;
     try {
       raw = fs.readFileSync(this._indexFile(), "utf-8");
@@ -285,6 +430,10 @@ export class ArtifactStore {
     return sessionId ? out.filter((e) => e.sessionId === sessionId) : out;
   }
 
+  list(options = {}) {
+    return this._withIndexLock(() => this._readEntries(options));
+  }
+
   /** One entry by id (or null). */
   get(id) {
     return this.list().find((e) => e.id === id) || null;
@@ -348,47 +497,103 @@ export class ArtifactStore {
 
   /** Remove one artifact (file + index row). @returns {boolean} found */
   remove(id) {
-    const entries = this.list();
-    const target = entries.find((e) => e.id === id);
-    if (!target) return false;
-    try {
-      this._deleteStoredFile(target);
-    } catch {
-      /* best-effort — the index row is the source of truth */
-    }
-    this._rewrite(entries.filter((e) => e.id !== id));
-    return true;
+    return this._withIndexLock(() => {
+      const entries = this._readEntries();
+      const matches = entries.filter((entry) => entry.id === id);
+      if (matches.length === 0) return false;
+      if (matches.length > 1) {
+        throw new Error(`artifact id ${id} has duplicate index rows`);
+      }
+      const target = matches[0];
+      this._rewriteUnlocked(entries.filter((entry) => entry.id !== id));
+      try {
+        this._deleteStoredFile(target);
+      } catch {
+        /* best-effort — the locked index generation is the source of truth */
+      }
+      return true;
+    });
   }
 
   /**
-   * Remove expired artifacts (expiresAt in the past).
+   * Low-level legacy primitive for removing expired artifacts.
+   * Official CLI and WebSocket callers must use artifact cleanup settlement so
+   * retries preserve a frozen scope and leave content-free audit evidence.
    * @returns {{ removed: number }}
    */
   cleanupExpired() {
-    const entries = this.list();
-    const now = this._now();
-    const keep = [];
-    let removed = 0;
-    for (const e of entries) {
-      const exp = Date.parse(e.expiresAt || "");
-      if (Number.isFinite(exp) && exp <= now) {
+    return this._withIndexLock(() => {
+      const entries = this._readEntries();
+      const now = this._now();
+      const keep = [];
+      const expired = [];
+      for (const entry of entries) {
+        const exp = Date.parse(entry.expiresAt || "");
+        if (Number.isFinite(exp) && exp <= now) {
+          expired.push(entry);
+        } else {
+          keep.push(entry);
+        }
+      }
+      if (expired.length > 0) this._rewriteUnlocked(keep);
+      for (const entry of expired) {
         try {
-          this._deleteStoredFile(e);
+          this._deleteStoredFile(entry);
         } catch {
-          /* best-effort */
+          /* best-effort — the locked index generation is the source of truth */
         }
-        removed += 1;
-      } else {
-        keep.push(e);
       }
-    }
-    if (removed > 0) this._rewrite(keep);
-    return { removed };
+      return { removed: expired.length };
+    });
   }
 
-  _rewrite(entries) {
+  _rewriteUnlocked(entries) {
     this._ensureDirs();
     const text = entries.map((e) => JSON.stringify(e)).join("\n");
-    fs.writeFileSync(this._indexFile(), text ? text + "\n" : "", "utf-8");
+    const indexFile = this._indexFile();
+    const temporary = `${indexFile}.${process.pid}.${crypto
+      .randomBytes(8)
+      .toString("hex")}.tmp`;
+    let descriptor = null;
+    try {
+      descriptor = fs.openSync(
+        temporary,
+        fs.constants.O_WRONLY |
+          fs.constants.O_CREAT |
+          fs.constants.O_EXCL |
+          Number(fs.constants.O_NOFOLLOW || 0),
+        0o600,
+      );
+      fs.writeFileSync(descriptor, text ? `${text}\n` : "", "utf-8");
+      fs.fsyncSync(descriptor);
+      fs.closeSync(descriptor);
+      descriptor = null;
+      fs.renameSync(temporary, indexFile);
+      this._syncIndexDirectory();
+    } finally {
+      if (descriptor !== null) fs.closeSync(descriptor);
+      try {
+        fs.rmSync(temporary, { force: true });
+      } catch {
+        /* best-effort cleanup of an unpublished index generation */
+      }
+    }
+  }
+
+  _syncIndexDirectory() {
+    let descriptor = null;
+    try {
+      descriptor = fs.openSync(this.dir, "r");
+      fs.fsyncSync(descriptor);
+    } catch (error) {
+      if (
+        process.platform !== "win32" ||
+        !["EACCES", "EINVAL", "ENOTSUP", "EPERM"].includes(error?.code)
+      ) {
+        throw error;
+      }
+    } finally {
+      if (descriptor !== null) fs.closeSync(descriptor);
+    }
   }
 }

package/src/lib/background-agent-keeper-protocol.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { lstatSync, mkdirSync, rmdirSync } from "node:fs";
-import { posix } from "node:path";
+import { join, posix, resolve } from "node:path";
 
 export const BACKGROUND_AGENT_KEEPER_PROTOCOL_VERSION = 1;
 export const BACKGROUND_AGENT_KEEPER_HELLO = "background-agent-keeper-hello";
@@ -12,8 +12,22 @@ export const BACKGROUND_AGENT_KEEPER_ARMED = "background-agent-keeper-armed";
 export const BACKGROUND_AGENT_KEEPER_RETIRE = "background-agent-keeper-retire";
 export const BACKGROUND_AGENT_KEEPER_RETIRED =
   "background-agent-keeper-retired";
+export const BACKGROUND_AGENT_KEEPER_LAUNCH_CLAIM =
+  "background-agent-keeper-launch-claim";
 export const BACKGROUND_AGENT_KEEPER_HEARTBEAT_INTERVAL_MS = 1_000;
-export const BACKGROUND_AGENT_KEEPER_HEARTBEAT_TIMEOUT_MS = 15_000;
+// Do not launch an OS process-identity probe while authenticated application
+// heartbeats are fresh. On Windows the cached WMIC/CIM fallback can otherwise
+// make 20 keepers synchronously spawn probe helpers together every ten seconds.
+export const BACKGROUND_AGENT_KEEPER_IDENTITY_PROBE_DELAY_MS = 15_000;
+// This application-level fence is a backstop for the rare case where Windows
+// retains both the named-pipe handle and an exact process object after worker
+// death. Normal death still closes the socket immediately; a stale channel
+// gets the delayed PID/start-time probe before this final fence. A 20-worker
+// hosted Windows launch has demonstrated
+// 37-second scheduling tails, so 15 seconds could kill a live, healthy worker
+// while it was merely descheduled. Keep the backstop bounded but above that
+// measured contention window.
+export const BACKGROUND_AGENT_KEEPER_HEARTBEAT_TIMEOUT_MS = 60_000;
 
 // RETIRE is the only keeper request that performs destructive OS cleanup. Its
 // deadline is deliberately independent from the short HELLO/ARM request
@@ -22,7 +36,7 @@ export const BACKGROUND_AGENT_KEEPER_HEARTBEAT_TIMEOUT_MS = 15_000;
 //
 //   2 targets * (strict identity + taskkill + cleanup confirmation identity) +
 //   2 cleanup-critical persistence retry windows + cleanup confirmation +
-//   scheduling margin = 120 seconds.
+//   scheduling margin = 128 seconds.
 //
 // Keeping these limits in the shared protocol contract prevents either side
 // from silently reintroducing the old 10-second client / longer keeper race.
@@ -36,7 +50,12 @@ export const BACKGROUND_AGENT_KEEPER_IDENTITY_PROBE_TIMEOUT_MS =
 export const BACKGROUND_AGENT_KEEPER_STATE_LOCK_TIMEOUT_MS = 5_000;
 export const BACKGROUND_AGENT_KEEPER_PERSIST_RETRY_TIMEOUT_MS =
   3 * BACKGROUND_AGENT_KEEPER_STATE_LOCK_TIMEOUT_MS;
-export const BACKGROUND_AGENT_KEEPER_CLEANUP_CONFIRM_TIMEOUT_MS = 2_000;
+// A 20-Agent macOS formal run can leave successfully SIGKILLed process groups
+// observable for several seconds while launchd reaps their orphaned leaders.
+// Two seconds made that bounded kernel/reaper delay look like an escaped tree.
+// Ten seconds stays inside the formal observer's 150-second budget while
+// retaining a finite fail-closed confirmation window.
+export const BACKGROUND_AGENT_KEEPER_CLEANUP_CONFIRM_TIMEOUT_MS = 10_000;
 export const BACKGROUND_AGENT_KEEPER_RETIRE_TIMEOUT_MARGIN_MS = 8_000;
 export const BACKGROUND_AGENT_KEEPER_RETIRE_TIMEOUT_MS =
   BACKGROUND_AGENT_KEEPER_CLEANUP_TARGET_LIMIT *
@@ -92,6 +111,58 @@ function requiredTimestamp(value, label) {
   return normalized;
 }
 
+export function backgroundAgentKeeperLaunchClaimPath(
+  id,
+  keeperGeneration,
+  directory,
+) {
+  const safeId = requiredSafeString(id, "id");
+  const safeGeneration = requiredSafeString(
+    keeperGeneration,
+    "keeper generation",
+  );
+  const requestedDirectory =
+    typeof directory === "string" ? directory.trim() : "";
+  if (!requestedDirectory || requestedDirectory.includes("\0")) {
+    throw new TypeError("invalid background agent keeper state directory");
+  }
+  const stateDirectory = resolve(requestedDirectory);
+  return join(
+    stateDirectory,
+    `.${safeId}.keeper-${safeGeneration}.launch-claim.json`,
+  );
+}
+
+export function createBackgroundAgentKeeperLaunchClaim(binding = {}) {
+  return Object.freeze({
+    type: BACKGROUND_AGENT_KEEPER_LAUNCH_CLAIM,
+    protocolVersion: BACKGROUND_AGENT_KEEPER_PROTOCOL_VERSION,
+    id: requiredSafeString(binding.id, "id"),
+    workerGeneration: requiredSafeString(
+      binding.workerGeneration,
+      "worker generation",
+    ),
+    keeperGeneration: requiredSafeString(
+      binding.keeperGeneration,
+      "keeper generation",
+    ),
+    keeperPid: requiredPositiveInteger(binding.keeperPid, "keeper pid"),
+    token: requiredSafeString(binding.token, "token", SAFE_TOKEN),
+  });
+}
+
+export function matchesBackgroundAgentKeeperLaunchClaim(value, expected = {}) {
+  let actual;
+  let binding;
+  try {
+    actual = createBackgroundAgentKeeperLaunchClaim(value);
+    binding = createBackgroundAgentKeeperLaunchClaim(expected);
+  } catch {
+    return false;
+  }
+  return Object.keys(binding).every((key) => actual[key] === binding[key]);
+}
+
 function digestKeeperPath(value, length) {
   return createHash("sha256").update(value).digest("hex").slice(0, length);
 }

package/src/lib/background-agent-launch-barrier.js

@@ -0,0 +1,74 @@
+/**
+ * Read-only startup barrier shared by the detached background worker and its
+ * keeper. The launcher publishes both exact child PIDs in one state
+ * transaction before clearing `launchFinalizationUncertain`. Until then the
+ * children must not contend for the same state lock.
+ */
+
+export const BACKGROUND_AGENT_LAUNCH_BARRIER_TIMEOUT_MS = 30_000;
+
+const DEFAULT_POLL_MS = 25;
+const PID_FIELDS = new Set(["workerPid", "keeperPid"]);
+
+function delay(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+export async function waitForBackgroundAgentLaunchBarrier(options = {}) {
+  const id = String(options.id || "").trim();
+  const workerGeneration = String(options.workerGeneration || "").trim();
+  const expectedPid = Number(options.expectedPid);
+  const pidField = String(options.pidField || "");
+  const readState = options.readState;
+  const readyWhen = options.readyWhen;
+  const now = options.now || Date.now;
+  const sleep = options.sleep || delay;
+  const timeoutMs = Math.max(
+    1,
+    Number(options.timeoutMs) || BACKGROUND_AGENT_LAUNCH_BARRIER_TIMEOUT_MS,
+  );
+  const pollMs = Math.max(1, Number(options.pollMs) || DEFAULT_POLL_MS);
+
+  if (!id) {
+    throw new TypeError("background launch barrier id is required");
+  }
+  if (!PID_FIELDS.has(pidField)) {
+    throw new TypeError("background launch barrier pid field is invalid");
+  }
+  if (!Number.isSafeInteger(expectedPid) || expectedPid <= 0) {
+    throw new TypeError("background launch barrier pid is invalid");
+  }
+  if (typeof readState !== "function") {
+    throw new TypeError("background launch barrier state reader is required");
+  }
+  if (readyWhen !== undefined && typeof readyWhen !== "function") {
+    throw new TypeError("background launch barrier readiness check is invalid");
+  }
+
+  const deadline = now() + timeoutMs;
+  for (;;) {
+    const state = readState(id);
+    if (!state || state.status !== "running") {
+      return Object.freeze({ status: "terminal", state: state || null });
+    }
+    // Jobs written before generation fencing are allowed to observe an
+    // already-terminal record above, but can never enter a running record.
+    if (!workerGeneration || state.workerGeneration !== workerGeneration) {
+      return Object.freeze({ status: "terminal", state });
+    }
+    if (state.launchFinalizationUncertain !== true) {
+      if (Number(state[pidField]) !== expectedPid) {
+        return Object.freeze({ status: "identity-mismatch", state });
+      }
+      if (!readyWhen || readyWhen(state)) {
+        return Object.freeze({ status: "ready", state });
+      }
+    }
+
+    const remaining = deadline - now();
+    if (remaining <= 0) {
+      return Object.freeze({ status: "timeout", state });
+    }
+    await sleep(Math.min(pollMs, remaining));
+  }
+}