chainlesschain 0.163.8 → 0.165.1

package/src/harness/session-list-index.js

@@ -9,14 +9,23 @@
 
 import {
   appendFileSync,
+  closeSync,
+  constants as fsConstants,
   existsSync,
+  fstatSync,
+  fsyncSync,
+  lstatSync,
+  openSync,
   readFileSync,
+  renameSync,
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { basename, dirname, join } from "node:path";
 import { iterateFileLinesReverseSync } from "../lib/file-lines.js";
 import { ensurePrivateFile } from "../lib/secure-fs.js";
+import { isAffectedWindowsZeroDeviceStatRuntime } from "../lib/secure-file-identity.js";
 
 export const SESSION_INDEX_SCHEMA = 2;
 export const SESSION_INDEX_FILE = ".sessions-index-v2.ndjson";
@@ -31,6 +40,14 @@ export const SESSION_GENERATION_AUTHORITY_SCHEMA =
 // Keeping the injection immediately around the production sidecar/journal
 // boundary makes that gate deterministic without replacing either write.
 export const _sessionScaleFaultHooks = Object.seal({
+  afterMetaTempFsync: null,
+  afterMetaRename: null,
+  afterMetaDirectoryFsync: null,
+  afterTombstoneTempFsync: null,
+  afterTombstoneRename: null,
+  afterTombstoneDirectoryFsync: null,
+  afterTombstoneRemoval: null,
+  afterTombstoneRemovalDirectoryFsync: null,
   afterMetaSnapshot: null,
 });
 
@@ -40,6 +57,157 @@ function runSessionScaleFaultHook(name, payload) {
   if (typeof hook === "function") hook(payload);
 }
 
+function annotateSnapshotFailure(
+  cause,
+  { targetPath, renamed, directorySynced },
+) {
+  const error = cause instanceof Error ? cause : new Error(String(cause));
+  if (!error.commitState) {
+    // Before rename the public snapshot is unchanged. POSIX needs the parent
+    // directory fsync to make the rename durable; Windows exposes no usable
+    // directory fsync through Node, so a flushed atomic rename is its complete
+    // host boundary. A hook after that boundary models response loss.
+    error.commitState = !renamed
+      ? "not-committed"
+      : directorySynced
+        ? "committed"
+        : "unknown";
+  }
+  if (!error.persistenceTarget) error.persistenceTarget = targetPath;
+  return error;
+}
+
+function syncParentDirectory(targetPath) {
+  if (process.platform === "win32") return false;
+  let descriptor = null;
+  try {
+    const flags =
+      fsConstants.O_RDONLY |
+      Number(fsConstants.O_DIRECTORY ?? 0) |
+      Number(fsConstants.O_NOFOLLOW ?? 0);
+    descriptor = openSync(dirname(targetPath), flags);
+    if (!fstatSync(descriptor).isDirectory()) {
+      throw new Error("Session snapshot parent is not a directory");
+    }
+    fsyncSync(descriptor);
+    return true;
+  } finally {
+    if (descriptor !== null) closeSync(descriptor);
+  }
+}
+
+function assertSnapshotPathMatchesDescriptor(
+  filePath,
+  descriptorStats,
+  serialized,
+) {
+  const published = lstatSync(filePath, { bigint: true });
+  const usefulIdentity =
+    descriptorStats.dev !== 0n ||
+    descriptorStats.ino !== 0n ||
+    published.dev !== 0n ||
+    published.ino !== 0n;
+  const deviceMatches =
+    String(descriptorStats.dev) === String(published.dev) ||
+    (isAffectedWindowsZeroDeviceStatRuntime() &&
+      String(descriptorStats.dev) !== "0" &&
+      String(published.dev) === "0");
+  const identityMatches =
+    deviceMatches &&
+    String(descriptorStats.ino) === String(published.ino) &&
+    String(descriptorStats.mode) === String(published.mode);
+  const expectedBytes = BigInt(Buffer.byteLength(serialized, "utf8"));
+  if (
+    published.isSymbolicLink() ||
+    !published.isFile() ||
+    (usefulIdentity && !identityMatches) ||
+    descriptorStats.size !== expectedBytes ||
+    published.size !== expectedBytes ||
+    readFileSync(filePath, "utf8") !== serialized
+  ) {
+    throw new Error(
+      "Session snapshot path no longer identifies the flushed payload",
+    );
+  }
+}
+
+/**
+ * Publish one authority snapshot without ever exposing a partial JSON file.
+ * The temporary file lives beside the destination so rename remains atomic.
+ * Activity ordering is intentionally outside this helper: that journal is a
+ * rebuildable cache and must not be confused with the durable snapshot.
+ */
+function writeSnapshotDurably(
+  filePath,
+  serialized,
+  { kind, sessionId, status, afterTempFsync, afterRename, afterDirectoryFsync },
+) {
+  const temporaryPath = join(
+    dirname(filePath),
+    `.${basename(filePath)}.${process.pid}.${randomUUID()}.tmp`,
+  );
+  const payload = Object.freeze({
+    kind,
+    sessionId,
+    status,
+    targetPath: filePath,
+    temporaryPath,
+  });
+  let descriptor = null;
+  let descriptorStats = null;
+  let renamed = false;
+  let directorySynced = process.platform === "win32";
+  try {
+    descriptor = openSync(temporaryPath, "wx", 0o600);
+    writeFileSync(descriptor, serialized, "utf8");
+    ensurePrivateFile(temporaryPath);
+    fsyncSync(descriptor);
+    descriptorStats = fstatSync(descriptor, { bigint: true });
+    runSessionScaleFaultHook(afterTempFsync, payload);
+    assertSnapshotPathMatchesDescriptor(
+      temporaryPath,
+      descriptorStats,
+      serialized,
+    );
+
+    // Both files are in the same directory; rename atomically replaces an old
+    // snapshot or publishes a first generation without a partial target.
+    // The temp already has the final owner-only permissions before publication.
+    renameSync(temporaryPath, filePath);
+    renamed = true;
+    assertSnapshotPathMatchesDescriptor(filePath, descriptorStats, serialized);
+    closeSync(descriptor);
+    descriptor = null;
+    runSessionScaleFaultHook(afterRename, payload);
+    if (process.platform !== "win32") {
+      directorySynced = syncParentDirectory(filePath);
+      runSessionScaleFaultHook(afterDirectoryFsync, payload);
+    }
+  } catch (cause) {
+    throw annotateSnapshotFailure(cause, {
+      targetPath: filePath,
+      renamed,
+      directorySynced,
+    });
+  } finally {
+    if (descriptor !== null) {
+      try {
+        closeSync(descriptor);
+      } catch {
+        // Preserve the persistence failure that stopped publication.
+      }
+    }
+    if (!renamed) {
+      try {
+        rmSync(temporaryPath, { force: true });
+      } catch {
+        // A crash may leave an ignored same-directory temp file. Never replace
+        // the original persistence failure with best-effort cleanup failure.
+      }
+    }
+  }
+}
+
 export function sessionMetaPath(dir, sessionId) {
   return join(dir, `${sessionId}.meta.json`);
 }
@@ -189,6 +357,7 @@ function writeMetaSnapshot(dir, meta) {
   // that publication fails. Remove it only after a live generation snapshot
   // commits, so crashes can cause an extra candidate read but never hide a
   // successfully committed tombstone.
+  let tombstonePublished = false;
   if (meta.deleted === true) {
     const generation = normalizeSessionGenerationAuthority(meta.generation);
     const marker = {
@@ -206,21 +375,71 @@ function writeMetaSnapshot(dir, meta) {
         Number(meta.deleted_at_ms || meta.updated_at_ms) || 0,
       ),
     };
-    writeFileSync(tombstoneMarker, `${JSON.stringify(marker)}\n`, {
-      encoding: "utf8",
-      mode: 0o600,
+    writeSnapshotDurably(tombstoneMarker, `${JSON.stringify(marker)}\n`, {
+      kind: "tombstone",
+      sessionId: meta.id,
+      status: "deleted",
+      afterTempFsync: "afterTombstoneTempFsync",
+      afterRename: "afterTombstoneRename",
+      afterDirectoryFsync: "afterTombstoneDirectoryFsync",
     });
-    ensurePrivateFile(tombstoneMarker);
+    tombstonePublished = true;
+  }
+  try {
+    writeSnapshotDurably(filePath, `${JSON.stringify(meta)}\n`, {
+      kind: "meta",
+      sessionId: meta.id,
+      status: meta.deleted === true ? "deleted" : "live",
+      afterTempFsync: "afterMetaTempFsync",
+      afterRename: "afterMetaRename",
+      afterDirectoryFsync: "afterMetaDirectoryFsync",
+    });
+  } catch (cause) {
+    // A durable marker is already a conservative deletion fence. If the meta
+    // publication then fails, the composite mutation is partial/unknown even
+    // when the old meta path itself was left byte-for-byte unchanged.
+    if (tombstonePublished && cause?.commitState === "not-committed") {
+      cause.commitState = "unknown";
+    }
+    throw cause;
+  }
+
+  if (meta.deleted !== true && existsSync(tombstoneMarker)) {
+    const payload = Object.freeze({
+      kind: "tombstone-removal",
+      sessionId: meta.id,
+      status: "live",
+      targetPath: tombstoneMarker,
+      parentDirectory: dirname(tombstoneMarker),
+    });
+    let removed = false;
+    let directorySynced = process.platform === "win32";
+    try {
+      rmSync(tombstoneMarker, { force: true });
+      removed = true;
+      runSessionScaleFaultHook("afterTombstoneRemoval", payload);
+      if (process.platform !== "win32") {
+        directorySynced = syncParentDirectory(tombstoneMarker);
+        runSessionScaleFaultHook(
+          "afterTombstoneRemovalDirectoryFsync",
+          payload,
+        );
+      }
+    } catch (cause) {
+      const error = cause instanceof Error ? cause : new Error(String(cause));
+      if (!error.commitState) {
+        // The live meta was already durably published. Retaining the marker is
+        // fail-closed; removing it without a POSIX directory barrier is an
+        // unknown publication, while a post-barrier hook is response loss.
+        error.commitState =
+          removed && directorySynced ? "committed" : "unknown";
+      }
+      if (!error.persistenceTarget) {
+        error.persistenceTarget = tombstoneMarker;
+      }
+      throw error;
+    }
   }
-  // The owning transcript lock serializes this derived snapshot. It need not
-  // use a second temp+rename protocol: interruption can only corrupt a cache,
-  // which readSessionMeta rejects and rebuildSessionMeta regenerates.
-  writeFileSync(filePath, `${JSON.stringify(meta)}\n`, {
-    encoding: "utf8",
-    mode: 0o600,
-  });
-  ensurePrivateFile(filePath);
-  if (meta.deleted !== true) rmSync(tombstoneMarker, { force: true });
 }
 
 /**

package/src/lib/agent-authority.js

@@ -266,6 +266,12 @@ export function describeAuthorityChain(envelope = {}) {
   const parts = [`origin=${envelope.origin || "unknown"}`];
   if (envelope.principalId) parts.push(`principal=${envelope.principalId}`);
   if (envelope.sessionId) parts.push(`session=${envelope.sessionId}`);
+  if (envelope.remoteSessionId)
+    parts.push(`remote-session=${envelope.remoteSessionId}`);
+  if (envelope.sessionEpoch)
+    parts.push(`session-epoch=${envelope.sessionEpoch}`);
+  if (envelope.membershipEpoch)
+    parts.push(`membership-epoch=${envelope.membershipEpoch}`);
   if (envelope.parentAgentId) parts.push(`parent=${envelope.parentAgentId}`);
   if (envelope.correlationId) parts.push(`corr=${envelope.correlationId}`);
   parts.push(`authority=${authorityForOrigin(envelope.origin, envelope)}`);

package/src/lib/auto-mode-config.js

@@ -284,6 +284,31 @@ export function createAutoModeApprovalGate(inner, resolved, opts = {}) {
   const isActive =
     typeof opts.isActive === "function" ? opts.isActive : () => true;
   let confirm = null;
+  let authorizationConsumerRequired = false;
+  const authorityConfig = Object.freeze({
+    map: Object.freeze(
+      Object.fromEntries(
+        RISK_LEVELS.map((riskLevel) => [
+          riskLevel,
+          Object.freeze({
+            decision: map[riskLevel]?.decision || null,
+            reason: map[riskLevel]?.reason || null,
+            source: map[riskLevel]?.source || null,
+          }),
+        ]),
+      ),
+    ),
+    rules: Object.freeze(
+      rules.map((rule) =>
+        Object.freeze({
+          decision: rule.decision || null,
+          reason: rule.reason || null,
+          source: rule.source || null,
+          match: rule.match ? Object.freeze({ ...rule.match }) : null,
+        }),
+      ),
+    ),
+  });
 
   return {
     isAutoModeGate: true,
@@ -303,6 +328,37 @@ export function createAutoModeApprovalGate(inner, resolved, opts = {}) {
     hasConfirmer() {
       return typeof confirm === "function";
     },
+    setAuthorizationConsumer(fn) {
+      authorizationConsumerRequired = typeof fn === "function";
+      return inner?.setAuthorizationConsumer?.(fn);
+    },
+    hasAuthorizationConsumer() {
+      return authorizationConsumerRequired;
+    },
+    getAuthorizationPolicySnapshot(sessionId = null) {
+      return Object.freeze({
+        schema: "chainlesschain.approval-policy-authority/v1",
+        kind: "auto-mode",
+        active: isActive() === true,
+        config: authorityConfig,
+        inner:
+          inner?.getAuthorizationPolicySnapshot?.(sessionId) ||
+          Object.freeze({
+            schema: "chainlesschain.approval-policy-authority/v1",
+            kind: "unobserved-inner",
+            sessionId: sessionId ? String(sessionId) : null,
+          }),
+      });
+    },
+    consumeAuthorization(authorization, ctx) {
+      if (typeof inner?.consumeAuthorization !== "function") {
+        throw new Error("Approval authorization consumer is unavailable");
+      }
+      return inner.consumeAuthorization(authorization, ctx);
+    },
+    createAuthorizationBinder() {
+      return inner?.createAuthorizationBinder?.() || null;
+    },
     async decide(ctx = {}) {
       if (!isActive()) return inner.decide(ctx);
       const riskLevel = RISK_LEVELS.includes(ctx.riskLevel)
@@ -365,7 +421,15 @@ export function createAutoModeApprovalGate(inner, resolved, opts = {}) {
       }
       // ask — same confirm semantics as the session-core gate: no confirmer
       // means fail-closed deny (headless installs a deny-confirmer anyway).
-      if (typeof confirm !== "function") {
+      // Snapshot both mutable callbacks before the first await. A concurrent
+      // stop/start or session reconfiguration must not retarget an in-flight
+      // remote approval to a different authorization consumer generation.
+      const confirmer = confirm;
+      const consumerRequired = authorizationConsumerRequired;
+      const bindAuthorization = consumerRequired
+        ? inner?.createAuthorizationBinder?.()
+        : null;
+      if (typeof confirmer !== "function") {
         return {
           decision: "deny",
           via: "no-confirmer",
@@ -374,8 +438,38 @@ export function createAutoModeApprovalGate(inner, resolved, opts = {}) {
         };
       }
       let ok = false;
+      let authorization = null;
+      let confirmationVia = null;
       try {
-        ok = await confirm(ctx);
+        const confirmation = await confirmer(ctx);
+        if (confirmation && typeof confirmation === "object") {
+          ok = confirmation.approved === true;
+          confirmationVia = confirmation.via || null;
+          if (ok && !confirmation.authorization) {
+            return {
+              decision: "deny",
+              via: "authorization-missing",
+              base: "confirm",
+              ...common,
+            };
+          }
+          if (
+            ok &&
+            (!consumerRequired || typeof bindAuthorization !== "function")
+          ) {
+            return {
+              decision: "deny",
+              via: "authorization-consumer-missing",
+              base: "confirm",
+              ...common,
+            };
+          }
+          if (ok) {
+            authorization = bindAuthorization(confirmation.authorization);
+          }
+        } else {
+          ok = confirmation === true;
+        }
       } catch (error) {
         return {
           decision: "deny",
@@ -387,8 +481,9 @@ export function createAutoModeApprovalGate(inner, resolved, opts = {}) {
       }
       return {
         decision: ok ? "allow" : "deny",
-        via: ok ? "user-confirm" : "user-deny",
+        via: confirmationVia || (ok ? "user-confirm" : "user-deny"),
         base: "confirm",
+        ...(authorization ? { authorization } : {}),
         ...common,
       };
     },

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

@@ -0,0 +1,248 @@
+import net from "node:net";
+import { randomBytes } from "node:crypto";
+import { createNdjsonReader } from "./background-session-transport.js";
+import {
+  BACKGROUND_AGENT_KEEPER_ARM,
+  BACKGROUND_AGENT_KEEPER_ARMED,
+  BACKGROUND_AGENT_KEEPER_HELLO,
+  BACKGROUND_AGENT_KEEPER_PROTOCOL_VERSION,
+  BACKGROUND_AGENT_KEEPER_READY,
+  BACKGROUND_AGENT_KEEPER_RETIRE,
+  BACKGROUND_AGENT_KEEPER_RETIRED,
+  createBackgroundAgentKeeperMessage,
+  normalizeBackgroundAgentKeeperHello,
+  normalizeBackgroundAgentKeeperTurn,
+  resolveBackgroundAgentKeeperRetireTimeoutMs,
+  sameBackgroundAgentKeeperTurn,
+} from "./background-agent-keeper-protocol.js";
+
+const DEFAULT_CONNECT_TIMEOUT_MS = 30_000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+
+function keeperError(message, code = "BACKGROUND_AGENT_KEEPER_UNAVAILABLE") {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function writeMessage(socket, message) {
+  if (!socket || socket.destroyed) {
+    throw keeperError("background agent keeper channel is closed");
+  }
+  socket.write(`${JSON.stringify(message)}\n`);
+}
+
+function connectOnce(pipePath) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(pipePath);
+    const onError = (error) => {
+      socket.destroy();
+      reject(error);
+    };
+    socket.once("error", onError);
+    socket.once("connect", () => {
+      socket.removeListener("error", onError);
+      resolve(socket);
+    });
+  });
+}
+
+async function connectWithDeadline(pipePath, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let lastError = null;
+  while (Date.now() < deadline) {
+    try {
+      return await connectOnce(pipePath);
+    } catch (error) {
+      lastError = error;
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+  }
+  throw keeperError(
+    `timed out connecting to background agent keeper: ${lastError?.message || "unavailable"}`,
+  );
+}
+
+export async function connectBackgroundAgentKeeper(options = {}) {
+  const hello = normalizeBackgroundAgentKeeperHello(options);
+  const connectTimeoutMs = Math.max(
+    1,
+    Number(options.connectTimeoutMs) || DEFAULT_CONNECT_TIMEOUT_MS,
+  );
+  const requestTimeoutMs = Math.max(
+    1,
+    Number(options.requestTimeoutMs) || DEFAULT_REQUEST_TIMEOUT_MS,
+  );
+  const retireTimeoutMs = resolveBackgroundAgentKeeperRetireTimeoutMs(
+    options.retireTimeoutMs,
+  );
+  const socket = await connectWithDeadline(options.pipePath, connectTimeoutMs);
+  const pending = new Map();
+  let ready = false;
+  let closing = false;
+  let activeTurn = null;
+  let readyResolve;
+  let readyReject;
+  const readyPromise = new Promise((resolve, reject) => {
+    readyResolve = resolve;
+    readyReject = reject;
+  });
+
+  const failPending = (error) => {
+    readyReject(error);
+    for (const entry of pending.values()) {
+      clearTimeout(entry.timer);
+      entry.reject(error);
+    }
+    pending.clear();
+  };
+
+  socket.on(
+    "data",
+    createNdjsonReader(
+      (message) => {
+        if (
+          message?.protocolVersion !== BACKGROUND_AGENT_KEEPER_PROTOCOL_VERSION
+        ) {
+          socket.destroy(
+            keeperError("background agent keeper protocol mismatch"),
+          );
+          return;
+        }
+        if (!ready) {
+          if (
+            message.type !== BACKGROUND_AGENT_KEEPER_READY ||
+            message.id !== hello.id ||
+            message.workerGeneration !== hello.workerGeneration
+          ) {
+            socket.destroy(
+              keeperError("background agent keeper ready binding mismatch"),
+            );
+            return;
+          }
+          ready = true;
+          readyResolve();
+          return;
+        }
+        const entry = pending.get(message.requestId);
+        if (!entry) return;
+        if (message.type === "background-agent-keeper-error") {
+          pending.delete(message.requestId);
+          clearTimeout(entry.timer);
+          entry.reject(
+            keeperError(
+              message.message || "background agent keeper rejected request",
+              message.code || "BACKGROUND_AGENT_KEEPER_REJECTED",
+            ),
+          );
+          return;
+        }
+        if (message.type !== entry.expectedType) return;
+        if (!sameBackgroundAgentKeeperTurn(message, entry.turn)) {
+          socket.destroy(
+            keeperError("background agent keeper response binding mismatch"),
+          );
+          return;
+        }
+        pending.delete(message.requestId);
+        clearTimeout(entry.timer);
+        entry.resolve(message);
+      },
+      (error) => socket.destroy(error),
+    ),
+  );
+  socket.on("error", (error) => failPending(error));
+  socket.on("close", () => {
+    const error = keeperError("background agent keeper channel disconnected");
+    failPending(error);
+    if (!closing) options.onDisconnect?.(error, activeTurn);
+  });
+
+  writeMessage(
+    socket,
+    createBackgroundAgentKeeperMessage(BACKGROUND_AGENT_KEEPER_HELLO, hello),
+  );
+  const helloTimer = setTimeout(
+    () =>
+      socket.destroy(
+        keeperError("timed out waiting for background agent keeper ready"),
+      ),
+    requestTimeoutMs,
+  );
+  helloTimer.unref?.();
+  await readyPromise.finally(() => clearTimeout(helloTimer));
+
+  const request = (
+    type,
+    expectedType,
+    turnValue,
+    timeoutMs = requestTimeoutMs,
+  ) => {
+    const turn = normalizeBackgroundAgentKeeperTurn(turnValue);
+    const requestId = randomBytes(16).toString("hex");
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pending.delete(requestId);
+        reject(
+          keeperError(
+            `timed out waiting for background agent keeper ${type} after ${timeoutMs}ms`,
+          ),
+        );
+      }, timeoutMs);
+      timer.unref?.();
+      pending.set(requestId, { expectedType, reject, resolve, timer, turn });
+      try {
+        writeMessage(
+          socket,
+          createBackgroundAgentKeeperMessage(type, { requestId, ...turn }),
+        );
+      } catch (error) {
+        pending.delete(requestId);
+        clearTimeout(timer);
+        reject(error);
+      }
+    });
+  };
+
+  return Object.freeze({
+    async arm(turn) {
+      const normalized = normalizeBackgroundAgentKeeperTurn(turn);
+      if (activeTurn) {
+        throw keeperError(
+          "background agent keeper is already armed",
+          "BACKGROUND_AGENT_KEEPER_BUSY",
+        );
+      }
+      await request(
+        BACKGROUND_AGENT_KEEPER_ARM,
+        BACKGROUND_AGENT_KEEPER_ARMED,
+        normalized,
+      );
+      activeTurn = normalized;
+      return normalized;
+    },
+    async retire(turn) {
+      const normalized = normalizeBackgroundAgentKeeperTurn(turn);
+      if (!sameBackgroundAgentKeeperTurn(normalized, activeTurn)) {
+        throw keeperError(
+          "background agent keeper retire binding mismatch",
+          "BACKGROUND_AGENT_KEEPER_BINDING_MISMATCH",
+        );
+      }
+      await request(
+        BACKGROUND_AGENT_KEEPER_RETIRE,
+        BACKGROUND_AGENT_KEEPER_RETIRED,
+        normalized,
+        retireTimeoutMs,
+      );
+      activeTurn = null;
+      return true;
+    },
+    close() {
+      if (closing) return;
+      closing = true;
+      socket.end();
+    },
+    activeTurn: () => activeTurn,
+  });
+}