chainlesschain 0.163.7 → 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/agent-schedule-store.js

@@ -258,6 +258,21 @@ function agendaStoreError(code, message, { retryable = false, retryAt } = {}) {
   return error;
 }
 
+function agendaPersistenceError(
+  code,
+  message,
+  cause,
+  { filePath, commitState } = {},
+) {
+  const error = new Error(message, { cause });
+  error.name = "AgendaScheduleStoreError";
+  error.code = code;
+  error.filePath = filePath;
+  if (typeof cause?.code === "string") error.fsCode = cause.code;
+  if (commitState) error.commitState = commitState;
+  return error;
+}
+
 function applyScheduledAgentSuccess(entry, atMs) {
   if (entry.kind === "wakeup") {
     entry.status = "fired";
@@ -666,9 +681,16 @@ export function previousCronTime(expr, fromMs, options = {}) {
 // ─── store ───────────────────────────────────────────────────────────────
 
 export class AgentScheduleStore {
-  constructor({ dir = null, now = () => Date.now() } = {}) {
+  constructor({
+    dir = null,
+    now = () => Date.now(),
+    fileSystem = fs,
+    platform = process.platform,
+  } = {}) {
     this.dir = dir || agentScheduleDir();
     this._now = typeof now === "function" ? now : () => now;
+    this._fs = fileSystem;
+    this._platform = platform;
   }
 
   _file(kind) {
@@ -676,37 +698,124 @@ export class AgentScheduleStore {
   }
 
   _ensureDir() {
-    fs.mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+    this._fs.mkdirSync(this.dir, { recursive: true, mode: 0o700 });
   }
 
-  _readAll(kind) {
+  _readAll(kind, { failOnMalformed = false } = {}) {
+    const filePath = this._file(kind);
     let raw;
     try {
-      raw = fs.readFileSync(this._file(kind), "utf-8");
-    } catch {
-      return [];
+      raw = this._fs.readFileSync(filePath, "utf-8");
+    } catch (cause) {
+      if (cause?.code === "ENOENT") return [];
+      throw agendaPersistenceError(
+        "AGENDA_SCHEDULE_STORE_READ_FAILED",
+        `Agenda schedule store read failed (${filePath})`,
+        cause,
+        { filePath },
+      );
     }
     const entries = [];
+    let lineNumber = 0;
     for (const line of raw.split("\n")) {
+      lineNumber += 1;
       const trimmed = line.trim();
       if (!trimmed) continue;
       try {
-        entries.push(JSON.parse(trimmed));
-      } catch {
+        const entry = JSON.parse(trimmed);
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+          throw new TypeError("schedule entry must be an object");
+        }
+        entries.push(entry);
+      } catch (cause) {
+        if (failOnMalformed) {
+          throw agendaPersistenceError(
+            "AGENDA_SCHEDULE_STORE_MALFORMED",
+            `Agenda schedule store contains malformed JSONL (${filePath}:${lineNumber})`,
+            cause,
+            { filePath },
+          );
+        }
         // Skip a corrupt line rather than throwing — one bad append must not
-        // poison the whole store (per-row resilience, like the JSON.parse sweep).
+        // poison advisory reads. Authoritative mutations opt into strict mode
+        // so they never replace a store after silently dropping durable rows.
       }
     }
     return entries;
   }
 
   _writeAll(kind, entries) {
-    this._ensureDir();
+    const filePath = this._file(kind);
     const body = entries.map((entry) => JSON.stringify(entry)).join("\n");
-    fs.writeFileSync(this._file(kind), body ? body + "\n" : "", {
-      encoding: "utf-8",
-      mode: 0o600,
-    });
+    const contents = Buffer.from(body ? `${body}\n` : "", "utf8");
+    const temporaryPath = path.join(
+      this.dir,
+      `.${path.basename(filePath)}.${process.pid}.${randomUUID()}.tmp`,
+    );
+    let descriptor = null;
+    let renamed = false;
+
+    try {
+      this._ensureDir();
+      descriptor = this._fs.openSync(temporaryPath, "wx", 0o600);
+      let offset = 0;
+      while (offset < contents.length) {
+        const written = this._fs.writeSync(
+          descriptor,
+          contents,
+          offset,
+          contents.length - offset,
+          null,
+        );
+        if (!Number.isSafeInteger(written) || written <= 0) {
+          const cause = new Error("write returned no progress");
+          cause.code = "EIO";
+          throw cause;
+        }
+        offset += written;
+      }
+      this._fs.fsyncSync(descriptor);
+      this._fs.closeSync(descriptor);
+      descriptor = null;
+      this._fs.renameSync(temporaryPath, filePath);
+      renamed = true;
+
+      if (this._platform !== "win32") {
+        const directoryDescriptor = this._fs.openSync(this.dir, "r");
+        try {
+          this._fs.fsyncSync(directoryDescriptor);
+        } finally {
+          this._fs.closeSync(directoryDescriptor);
+        }
+      }
+    } catch (cause) {
+      if (descriptor !== null) {
+        try {
+          this._fs.closeSync(descriptor);
+        } catch {
+          // Preserve the original persistence failure.
+        }
+      }
+      if (!renamed) {
+        try {
+          this._fs.unlinkSync(temporaryPath);
+        } catch {
+          // Best-effort orphan cleanup; the authoritative file is untouched.
+        }
+      }
+      throw agendaPersistenceError(
+        "AGENDA_SCHEDULE_STORE_WRITE_FAILED",
+        `Agenda schedule store write failed (${filePath})`,
+        cause,
+        {
+          filePath,
+          // A failure before rename leaves the old generation authoritative.
+          // A directory-fsync failure after rename makes crash durability
+          // unknowable even though an immediate read sees the new generation.
+          commitState: renamed ? "unknown" : "not-committed",
+        },
+      );
+    }
   }
 
   // ── create ──────────────────────────────────────────────────────────────
@@ -741,7 +850,7 @@ export class AgentScheduleStore {
       createdAt: now,
       status: "pending",
     };
-    const entries = this._readAll("wakeup");
+    const entries = this._readAll("wakeup", { failOnMalformed: true });
     entries.push(entry);
     this._writeAll("wakeup", entries);
     return entry;
@@ -786,7 +895,7 @@ export class AgentScheduleStore {
       runs: 0,
       status: "active",
     };
-    const entries = this._readAll("cron");
+    const entries = this._readAll("cron", { failOnMalformed: true });
     entries.push(entry);
     this._writeAll("cron", entries);
     return entry;
@@ -882,7 +991,7 @@ export class AgentScheduleStore {
       checks: 0,
       status: "active",
     };
-    const entries = this._readAll("monitor");
+    const entries = this._readAll("monitor", { failOnMalformed: true });
     entries.push(entry);
     this._writeAll("monitor", entries);
     return entry;
@@ -917,7 +1026,7 @@ export class AgentScheduleStore {
       path.join(this.dir, ".agenda-claims"),
       () => {
         for (const kind of SCHEDULE_KINDS) {
-          const entries = this._readAll(kind);
+          const entries = this._readAll(kind, { failOnMalformed: true });
           const entry = entries.find((candidate) => candidate.id === id);
           if (!entry) continue;
           if (!isSchedulableStatus(entry)) {
@@ -993,7 +1102,7 @@ export class AgentScheduleStore {
       path.join(this.dir, ".agenda-claims"),
       () => {
         for (const kind of SCHEDULE_KINDS) {
-          const entries = this._readAll(kind);
+          const entries = this._readAll(kind, { failOnMalformed: true });
           const entry = entries.find((candidate) => candidate.id === id);
           if (!entry) continue;
           const prior = entry.schedulerMigration;
@@ -1079,7 +1188,7 @@ export class AgentScheduleStore {
       path.join(this.dir, ".agenda-claims"),
       () => {
         for (const kind of SCHEDULE_KINDS) {
-          const entries = this._readAll(kind);
+          const entries = this._readAll(kind, { failOnMalformed: true });
           const entry = entries.find((candidate) => candidate.id === id);
           if (!entry) continue;
           const migration = entry.schedulerMigration;
@@ -1171,7 +1280,9 @@ export class AgentScheduleStore {
       () => {
         const claimed = [];
         for (const scheduleKind of kinds) {
-          const entries = this._readAll(scheduleKind);
+          const entries = this._readAll(scheduleKind, {
+            failOnMalformed: true,
+          });
           let changed = false;
           for (const entry of entries) {
             if (!isSchedulableStatus(entry) || isEntryExpired(entry, now))
@@ -1242,7 +1353,7 @@ export class AgentScheduleStore {
       path.join(this.dir, ".agenda-claims"),
       () => {
         for (const kind of SCHEDULE_KINDS) {
-          const entries = this._readAll(kind);
+          const entries = this._readAll(kind, { failOnMalformed: true });
           const entry = entries.find((candidate) => candidate.id === id);
           if (!entry) continue;
           const prior = entry.schedulerExecution;
@@ -1330,7 +1441,7 @@ export class AgentScheduleStore {
       path.join(this.dir, ".agenda-claims"),
       () => {
         for (const kind of SCHEDULE_KINDS) {
-          const entries = this._readAll(kind);
+          const entries = this._readAll(kind, { failOnMalformed: true });
           const entry = entries.find((candidate) => candidate.id === id);
           if (!entry) continue;
           const evidence = entry.schedulerExecution;
@@ -1408,7 +1519,7 @@ export class AgentScheduleStore {
       path.join(this.dir, ".agenda-claims"),
       () => {
         for (const kind of SCHEDULE_KINDS) {
-          const entries = this._readAll(kind);
+          const entries = this._readAll(kind, { failOnMalformed: true });
           const entry = entries.find((candidate) => candidate.id === id);
           if (!entry) continue;
           const evidence = entry.schedulerExecution;
@@ -1484,7 +1595,7 @@ export class AgentScheduleStore {
     const now = atMs != null ? atMs : this._now();
     const retired = [];
     for (const kind of SCHEDULE_KINDS) {
-      const entries = this._readAll(kind);
+      const entries = this._readAll(kind, { failOnMalformed: true });
       let changed = false;
       for (const entry of entries) {
         if (isSchedulableStatus(entry) && isEntryExpired(entry, now)) {
@@ -1501,7 +1612,7 @@ export class AgentScheduleStore {
 
   cancel(id) {
     for (const kind of SCHEDULE_KINDS) {
-      const entries = this._readAll(kind);
+      const entries = this._readAll(kind, { failOnMalformed: true });
       const idx = entries.findIndex((entry) => entry.id === id);
       if (idx >= 0) {
         const [removed] = entries.splice(idx, 1);
@@ -1522,7 +1633,7 @@ export class AgentScheduleStore {
   pruneTerminal({ before = Infinity } = {}) {
     const removed = [];
     for (const kind of SCHEDULE_KINDS) {
-      const entries = this._readAll(kind);
+      const entries = this._readAll(kind, { failOnMalformed: true });
       const keep = entries.filter((entry) => {
         const prunable =
           TERMINAL_SET.has(entry.status) && terminalAt(entry) <= before;
@@ -1586,7 +1697,7 @@ export class AgentScheduleStore {
   }
 
   _mutate(kind, id, fn) {
-    const entries = this._readAll(kind);
+    const entries = this._readAll(kind, { failOnMalformed: true });
     const entry = entries.find((e) => e.id === id);
     if (!entry) return null;
     fn(entry);