chainlesschain 0.164.0 → 0.165.2

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

@@ -5,6 +5,8 @@ import {
   BACKGROUND_AGENT_KEEPER_ARM,
   BACKGROUND_AGENT_KEEPER_ARMED,
   BACKGROUND_AGENT_KEEPER_HELLO,
+  BACKGROUND_AGENT_KEEPER_HEARTBEAT,
+  BACKGROUND_AGENT_KEEPER_HEARTBEAT_INTERVAL_MS,
   BACKGROUND_AGENT_KEEPER_PROTOCOL_VERSION,
   BACKGROUND_AGENT_KEEPER_READY,
   BACKGROUND_AGENT_KEEPER_RETIRE,
@@ -76,11 +78,17 @@ export async function connectBackgroundAgentKeeper(options = {}) {
   const retireTimeoutMs = resolveBackgroundAgentKeeperRetireTimeoutMs(
     options.retireTimeoutMs,
   );
+  const heartbeatIntervalMs = Math.max(
+    10,
+    Number(options.heartbeatIntervalMs) ||
+      BACKGROUND_AGENT_KEEPER_HEARTBEAT_INTERVAL_MS,
+  );
   const socket = await connectWithDeadline(options.pipePath, connectTimeoutMs);
   const pending = new Map();
   let ready = false;
   let closing = false;
   let activeTurn = null;
+  let heartbeatTimer = null;
   let readyResolve;
   let readyReject;
   const readyPromise = new Promise((resolve, reject) => {
@@ -89,6 +97,8 @@ export async function connectBackgroundAgentKeeper(options = {}) {
   });
 
   const failPending = (error) => {
+    clearInterval(heartbeatTimer);
+    heartbeatTimer = null;
     readyReject(error);
     for (const entry of pending.values()) {
       clearTimeout(entry.timer);
@@ -171,6 +181,23 @@ export async function connectBackgroundAgentKeeper(options = {}) {
   );
   helloTimer.unref?.();
   await readyPromise.finally(() => clearTimeout(helloTimer));
+  const sendHeartbeat = () => {
+    try {
+      writeMessage(
+        socket,
+        createBackgroundAgentKeeperMessage(BACKGROUND_AGENT_KEEPER_HEARTBEAT, {
+          id: hello.id,
+          workerGeneration: hello.workerGeneration,
+          workerPid: hello.workerPid,
+        }),
+      );
+    } catch (error) {
+      socket.destroy(error);
+    }
+  };
+  sendHeartbeat();
+  heartbeatTimer = setInterval(sendHeartbeat, heartbeatIntervalMs);
+  heartbeatTimer.unref?.();
 
   const request = (
     type,
@@ -241,6 +268,8 @@ export async function connectBackgroundAgentKeeper(options = {}) {
     close() {
       if (closing) return;
       closing = true;
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
       socket.end();
     },
     activeTurn: () => activeTurn,

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

@@ -1,22 +1,28 @@
-import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { lstatSync, mkdirSync, rmdirSync } from "node:fs";
+import { posix } from "node:path";
 
 export const BACKGROUND_AGENT_KEEPER_PROTOCOL_VERSION = 1;
 export const BACKGROUND_AGENT_KEEPER_HELLO = "background-agent-keeper-hello";
 export const BACKGROUND_AGENT_KEEPER_READY = "background-agent-keeper-ready";
+export const BACKGROUND_AGENT_KEEPER_HEARTBEAT =
+  "background-agent-keeper-heartbeat";
 export const BACKGROUND_AGENT_KEEPER_ARM = "background-agent-keeper-arm";
 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_HEARTBEAT_INTERVAL_MS = 1_000;
+export const BACKGROUND_AGENT_KEEPER_HEARTBEAT_TIMEOUT_MS = 15_000;
 
 // RETIRE is the only keeper request that performs destructive OS cleanup. Its
 // deadline is deliberately independent from the short HELLO/ARM request
 // deadline and is derived from every synchronous operation on the longest
 // Windows path:
 //
-//   2 targets * (taskkill + WMIC + PowerShell) +
-//   2 durable state-lock acquisitions + cleanup confirmation + scheduling
-//   margin = 70 seconds.
+//   2 targets * (strict identity + taskkill + cleanup confirmation identity) +
+//   2 cleanup-critical persistence retry windows + cleanup confirmation +
+//   scheduling margin = 120 seconds.
 //
 // Keeping these limits in the shared protocol contract prevents either side
 // from silently reintroducing the old 10-second client / longer keeper race.
@@ -24,15 +30,19 @@ export const BACKGROUND_AGENT_KEEPER_CLEANUP_TARGET_LIMIT = 2;
 export const BACKGROUND_AGENT_KEEPER_TASKKILL_TIMEOUT_MS = 10_000;
 export const BACKGROUND_AGENT_KEEPER_WMIC_TIMEOUT_MS = 5_000;
 export const BACKGROUND_AGENT_KEEPER_POWERSHELL_TIMEOUT_MS = 10_000;
+export const BACKGROUND_AGENT_KEEPER_IDENTITY_PROBE_TIMEOUT_MS =
+  BACKGROUND_AGENT_KEEPER_WMIC_TIMEOUT_MS +
+  BACKGROUND_AGENT_KEEPER_POWERSHELL_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;
 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 *
     (BACKGROUND_AGENT_KEEPER_TASKKILL_TIMEOUT_MS +
-      BACKGROUND_AGENT_KEEPER_WMIC_TIMEOUT_MS +
-      BACKGROUND_AGENT_KEEPER_POWERSHELL_TIMEOUT_MS) +
-  2 * BACKGROUND_AGENT_KEEPER_STATE_LOCK_TIMEOUT_MS +
+      2 * BACKGROUND_AGENT_KEEPER_IDENTITY_PROBE_TIMEOUT_MS) +
+  2 * BACKGROUND_AGENT_KEEPER_PERSIST_RETRY_TIMEOUT_MS +
   BACKGROUND_AGENT_KEEPER_CLEANUP_CONFIRM_TIMEOUT_MS +
   BACKGROUND_AGENT_KEEPER_RETIRE_TIMEOUT_MARGIN_MS;
 
@@ -49,6 +59,14 @@ export function resolveBackgroundAgentKeeperRetireTimeoutMs(value) {
 
 const SAFE_ID = /^[A-Za-z0-9_-]{1,256}$/u;
 const SAFE_TOKEN = /^[a-f0-9]{64}$/u;
+const POSIX_LOCAL_PIPE_DIRECTORY = /^cc-bg[ks]-[a-f0-9]{24}$/u;
+const POSIX_LOCAL_PIPE_SOCKET = /^[a-f0-9]{32}\.sock$/u;
+
+// Darwin's sockaddr_un.sun_path has 104 bytes including the trailing NUL.
+// Linux allows a few more bytes, but the conservative cross-platform ceiling
+// prevents a long state directory from being silently truncated into the same
+// endpoint as a concurrent keeper.
+export const POSIX_KEEPER_SOCKET_PATH_MAX_BYTES = 103;
 
 function requiredSafeString(value, label, pattern = SAFE_ID) {
   const normalized = typeof value === "string" ? value.trim() : "";
@@ -74,12 +92,142 @@ function requiredTimestamp(value, label) {
   return normalized;
 }
 
-export function backgroundAgentKeeperPipePath(id, directory) {
+function digestKeeperPath(value, length) {
+  return createHash("sha256").update(value).digest("hex").slice(0, length);
+}
+
+function requiredPosixDirectory(value, label) {
+  const normalized = typeof value === "string" ? value.trim() : "";
+  if (!normalized || normalized.includes("\0")) {
+    throw new TypeError(`invalid background agent keeper ${label}`);
+  }
+  return posix.resolve(normalized.replaceAll("\\", "/"));
+}
+
+function backgroundAgentPosixPipePath(
+  id,
+  directory,
+  options,
+  { candidateSuffix, fallbackPrefix, tooLongMessage },
+) {
   const safeId = requiredSafeString(id, "id");
-  if (process.platform === "win32") {
+  const stateDirectory = requiredPosixDirectory(directory, "state directory");
+  const candidate = posix.join(stateDirectory, `${safeId}${candidateSuffix}`);
+  if (
+    Buffer.byteLength(candidate, "utf8") <= POSIX_KEEPER_SOCKET_PATH_MAX_BYTES
+  ) {
+    return candidate;
+  }
+
+  // Keep the endpoint inside a private, state-root-specific namespace under
+  // the short POSIX /tmp alias. The full directory and id remain collision
+  // inputs even though neither long value appears in sockaddr_un.sun_path.
+  const uid =
+    options.uid ??
+    (typeof process.getuid === "function" ? process.getuid() : "unknown");
+  const shortTempDirectory = requiredPosixDirectory(
+    options.tempDirectory || "/tmp",
+    "short temp directory",
+  );
+  const namespace = digestKeeperPath(`${uid}\0${stateDirectory}`, 24);
+  const socketId = digestKeeperPath(safeId, 32);
+  const fallback = posix.join(
+    shortTempDirectory,
+    `${fallbackPrefix}-${namespace}`,
+    `${socketId}.sock`,
+  );
+  if (
+    Buffer.byteLength(fallback, "utf8") > POSIX_KEEPER_SOCKET_PATH_MAX_BYTES
+  ) {
+    throw new Error(tooLongMessage);
+  }
+  return fallback;
+}
+
+export function backgroundAgentKeeperPipePath(id, directory, options = {}) {
+  const safeId = requiredSafeString(id, "id");
+  const platform = options.platform || process.platform;
+  if (platform === "win32") {
     return `\\\\.\\pipe\\cc-bg-keeper-${safeId}`;
   }
-  return join(directory, `${safeId}.keeper.sock`);
+  return backgroundAgentPosixPipePath(id, directory, options, {
+    candidateSuffix: ".keeper.sock",
+    fallbackPrefix: "cc-bgk",
+    tooLongMessage: "background agent keeper fallback socket path is too long",
+  });
+}
+
+export function backgroundAgentSessionPipePath(id, directory, options = {}) {
+  const safeId = requiredSafeString(id, "id");
+  const platform = options.platform || process.platform;
+  if (platform === "win32") {
+    return `\\\\.\\pipe\\cc-bg-${safeId}`;
+  }
+  return backgroundAgentPosixPipePath(id, directory, options, {
+    candidateSuffix: ".sock",
+    fallbackPrefix: "cc-bgs",
+    tooLongMessage: "background agent session fallback socket path is too long",
+  });
+}
+
+function fallbackLocalPipeDirectory(pipePath) {
+  const normalized = posix.resolve(
+    String(pipePath || "").replaceAll("\\", "/"),
+  );
+  const directory = posix.dirname(normalized);
+  return POSIX_LOCAL_PIPE_DIRECTORY.test(posix.basename(directory)) &&
+    POSIX_LOCAL_PIPE_SOCKET.test(posix.basename(normalized))
+    ? directory
+    : null;
+}
+
+export function prepareBackgroundAgentLocalPipePath(
+  pipePath,
+  { platform = process.platform } = {},
+) {
+  if (platform === "win32") return pipePath;
+  const directory = fallbackLocalPipeDirectory(pipePath);
+  if (!directory) return pipePath;
+  try {
+    mkdirSync(directory, { mode: 0o700 });
+  } catch (error) {
+    if (error?.code !== "EEXIST") throw error;
+  }
+  const stat = lstatSync(directory);
+  const uid = typeof process.getuid === "function" ? process.getuid() : null;
+  if (
+    !stat.isDirectory() ||
+    stat.isSymbolicLink() ||
+    (uid !== null && stat.uid !== uid) ||
+    (stat.mode & 0o077) !== 0
+  ) {
+    throw new Error("background agent socket directory is not private");
+  }
+  return pipePath;
+}
+
+export function cleanupBackgroundAgentLocalPipeDirectory(
+  pipePath,
+  { platform = process.platform } = {},
+) {
+  if (platform === "win32") return false;
+  const directory = fallbackLocalPipeDirectory(pipePath);
+  if (!directory) return false;
+  try {
+    rmdirSync(directory);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT" || error?.code === "ENOTEMPTY") return false;
+    throw error;
+  }
+}
+
+export function prepareBackgroundAgentKeeperPipePath(pipePath, options) {
+  return prepareBackgroundAgentLocalPipePath(pipePath, options);
+}
+
+export function cleanupBackgroundAgentKeeperPipeDirectory(pipePath, options) {
+  return cleanupBackgroundAgentLocalPipeDirectory(pipePath, options);
 }
 
 export function normalizeBackgroundAgentKeeperAuthority(value = {}) {