chainlesschain 0.163.8 → 0.164.0

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/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,
+  });
+}

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

@@ -0,0 +1,147 @@
+import { join } 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_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";
+
+// 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.
+//
+// Keeping these limits in the shared protocol contract prevents either side
+// from silently reintroducing the old 10-second client / longer keeper race.
+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_STATE_LOCK_TIMEOUT_MS = 5_000;
+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 +
+  BACKGROUND_AGENT_KEEPER_CLEANUP_CONFIRM_TIMEOUT_MS +
+  BACKGROUND_AGENT_KEEPER_RETIRE_TIMEOUT_MARGIN_MS;
+
+export function resolveBackgroundAgentKeeperRetireTimeoutMs(value) {
+  const requested = Number(value);
+  if (!Number.isFinite(requested) || requested <= 0) {
+    return BACKGROUND_AGENT_KEEPER_RETIRE_TIMEOUT_MS;
+  }
+  return Math.min(
+    BACKGROUND_AGENT_KEEPER_RETIRE_TIMEOUT_MS,
+    Math.max(1, Math.floor(requested)),
+  );
+}
+
+const SAFE_ID = /^[A-Za-z0-9_-]{1,256}$/u;
+const SAFE_TOKEN = /^[a-f0-9]{64}$/u;
+
+function requiredSafeString(value, label, pattern = SAFE_ID) {
+  const normalized = typeof value === "string" ? value.trim() : "";
+  if (!pattern.test(normalized)) {
+    throw new TypeError(`invalid background agent keeper ${label}`);
+  }
+  return normalized;
+}
+
+function requiredPositiveInteger(value, label) {
+  const normalized = Number(value);
+  if (!Number.isSafeInteger(normalized) || normalized < 1) {
+    throw new TypeError(`invalid background agent keeper ${label}`);
+  }
+  return normalized;
+}
+
+function requiredTimestamp(value, label) {
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized) || normalized <= 0) {
+    throw new TypeError(`invalid background agent keeper ${label}`);
+  }
+  return normalized;
+}
+
+export function backgroundAgentKeeperPipePath(id, directory) {
+  const safeId = requiredSafeString(id, "id");
+  if (process.platform === "win32") {
+    return `\\\\.\\pipe\\cc-bg-keeper-${safeId}`;
+  }
+  return join(directory, `${safeId}.keeper.sock`);
+}
+
+export function normalizeBackgroundAgentKeeperAuthority(value = {}) {
+  return Object.freeze({
+    id: requiredSafeString(value.id, "id"),
+    workerGeneration: requiredSafeString(
+      value.workerGeneration,
+      "worker generation",
+    ),
+  });
+}
+
+export function normalizeBackgroundAgentKeeperHello(value = {}) {
+  return Object.freeze({
+    ...normalizeBackgroundAgentKeeperAuthority(value),
+    token: requiredSafeString(value.token, "token", SAFE_TOKEN),
+    workerPid: requiredPositiveInteger(value.workerPid, "worker pid"),
+  });
+}
+
+export function normalizeBackgroundAgentKeeperTurn(value = {}) {
+  return Object.freeze({
+    ...normalizeBackgroundAgentKeeperAuthority(value),
+    turnLaunchToken: requiredSafeString(
+      value.turnLaunchToken,
+      "turn launch token",
+    ),
+    attempt: requiredPositiveInteger(value.attempt, "turn attempt"),
+    agentPid: requiredPositiveInteger(value.agentPid, "agent pid"),
+    agentStartedAt: requiredTimestamp(
+      value.agentStartedAt,
+      "agent start anchor",
+    ),
+    agentRuntimePid: requiredPositiveInteger(
+      value.agentRuntimePid,
+      "agent runtime pid",
+    ),
+    agentRuntimeStartedAt: requiredTimestamp(
+      value.agentRuntimeStartedAt,
+      "agent runtime start anchor",
+    ),
+  });
+}
+
+export function sameBackgroundAgentKeeperTurn(left, right) {
+  let normalizedLeft;
+  let normalizedRight;
+  try {
+    normalizedLeft = normalizeBackgroundAgentKeeperTurn(left);
+    normalizedRight = normalizeBackgroundAgentKeeperTurn(right);
+  } catch {
+    return false;
+  }
+  return Object.keys(normalizedLeft).every(
+    (key) => normalizedLeft[key] === normalizedRight[key],
+  );
+}
+
+export function createBackgroundAgentKeeperMessage(type, payload = {}) {
+  return Object.freeze({
+    type,
+    protocolVersion: BACKGROUND_AGENT_KEEPER_PROTOCOL_VERSION,
+    ...payload,
+  });
+}