chainlesschain 0.162.185 → 0.162.187

package/src/lib/agent-team/team-mailbox.js

@@ -11,16 +11,120 @@
  * receive it exactly once. Delivery cursors + the log are in the snapshot, so a
  * resumed session re-delivers only what a teammate hadn't yet drained.
  *
+ * The mailbox is bounded by message-count, total-byte, and per-message-byte
+ * limits. When an incoming message would cross a limit, messages that have
+ * already been delivered to every registered intended recipient are compacted
+ * first. Undelivered data is never evicted: if safe compaction is insufficient,
+ * `send()` throws a stable coded backpressure error.
+ *
  * Pure + deterministic: ids come from a monotonic counter (not a clock) and the
  * clock is injected only for timestamps, so ordering is stable in tests.
  */
 
+import { Buffer } from "node:buffer";
+
+export const TEAM_MAILBOX_ERROR_CODES = Object.freeze({
+  MESSAGE_INVALID: "TEAM_MAILBOX_MESSAGE_INVALID",
+  MESSAGE_TOO_LARGE: "TEAM_MAILBOX_MESSAGE_TOO_LARGE",
+  CAPACITY_EXCEEDED: "TEAM_MAILBOX_CAPACITY_EXCEEDED",
+});
+
+export const DEFAULT_TEAM_MAILBOX_LIMITS = Object.freeze({
+  maxMessageBytes: 64 * 1024,
+  maxMessages: 1000,
+  maxTotalBytes: 4 * 1024 * 1024,
+});
+
+function positiveInteger(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;
+}
+
+function nonNegativeNumber(value, fallback = 0) {
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : fallback;
+}
+
+export class TeamMailboxError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "TeamMailboxError";
+    this.code = code;
+    Object.assign(this, details);
+  }
+}
+
+function createMailboxError(code, message, details = {}) {
+  return new TeamMailboxError(code, message, details);
+}
+
 export class TeamMailbox {
-  constructor({ now = () => Date.now() } = {}) {
+  constructor({
+    now = () => Date.now(),
+    maxMessageBytes = DEFAULT_TEAM_MAILBOX_LIMITS.maxMessageBytes,
+    maxMessages = DEFAULT_TEAM_MAILBOX_LIMITS.maxMessages,
+    maxTotalBytes = DEFAULT_TEAM_MAILBOX_LIMITS.maxTotalBytes,
+    recipients = [],
+  } = {}) {
     this._now = typeof now === "function" ? now : () => now;
+    this._limits = {
+      maxMessageBytes: positiveInteger(
+        maxMessageBytes,
+        DEFAULT_TEAM_MAILBOX_LIMITS.maxMessageBytes,
+      ),
+      maxMessages: positiveInteger(
+        maxMessages,
+        DEFAULT_TEAM_MAILBOX_LIMITS.maxMessages,
+      ),
+      maxTotalBytes: positiveInteger(
+        maxTotalBytes,
+        DEFAULT_TEAM_MAILBOX_LIMITS.maxTotalBytes,
+      ),
+    };
     this._log = []; // ordered [{ id, from, to, subject, body, ts }]
+    this._entryBytes = new Map(); // id → serialized UTF-8 bytes
+    this._totalBytes = 0;
     this._seq = 0; // monotonic message id source
     this._delivered = new Map(); // recipient → highest message id already drained
+    this._recipients = new Set(); // authoritative compaction audience
+    this._counters = {
+      acceptedMessages: 0,
+      acceptedBytes: 0,
+      rejectedMessages: 0,
+      rejectedBytes: 0,
+      compactionRuns: 0,
+      compactedMessages: 0,
+      compactedBytes: 0,
+    };
+    this.registerRecipients(recipients);
+  }
+
+  /**
+   * Register the current teammate audience used for safe compaction. A direct
+   * message is compactable only after its registered target drains it; a
+   * broadcast waits for every registered recipient except its sender.
+   *
+   * Registration is additive. Newly registered teammates can receive messages
+   * that are still retained, but messages safely compacted before they joined
+   * are not replayed as history.
+   */
+  registerRecipients(recipients = []) {
+    const values =
+      typeof recipients === "string"
+        ? [recipients]
+        : recipients && typeof recipients[Symbol.iterator] === "function"
+          ? Array.from(recipients)
+          : [];
+    for (const recipient of values) {
+      if (
+        typeof recipient === "string" &&
+        recipient.trim().length > 0 &&
+        recipient !== "*"
+      ) {
+        this._recipients.add(recipient);
+      }
+    }
+    return Array.from(this._recipients);
   }
 
   /**
@@ -29,18 +133,141 @@ export class TeamMailbox {
    */
   send({ from = null, to, subject = null, body = null } = {}) {
     if (!to || typeof to !== "string") {
-      throw new Error("TeamMailbox.send: `to` recipient (or '*') is required");
+      this._recordRejection(0);
+      throw createMailboxError(
+        TEAM_MAILBOX_ERROR_CODES.MESSAGE_INVALID,
+        "TeamMailbox.send: `to` recipient (or '*') is required",
+      );
     }
-    const msg = {
-      id: ++this._seq,
+    let msg = {
+      id: this._seq + 1,
       from,
       to,
       subject,
       body,
       ts: this._now(),
     };
+    let messageBytes;
+    try {
+      const serialized = JSON.stringify(msg);
+      messageBytes = Buffer.byteLength(serialized, "utf8");
+      // Store a detached JSON value so callers cannot mutate a retained body
+      // after admission and silently invalidate the byte accounting.
+      msg = JSON.parse(serialized);
+      if (
+        !["id", "from", "to", "subject", "body", "ts"].every((field) =>
+          Object.prototype.hasOwnProperty.call(msg, field),
+        )
+      ) {
+        throw new TypeError("message fields must be JSON values");
+      }
+    } catch (cause) {
+      this._counters.rejectedMessages += 1;
+      throw createMailboxError(
+        TEAM_MAILBOX_ERROR_CODES.MESSAGE_INVALID,
+        "TeamMailbox.send: message must be JSON-serializable",
+        { cause },
+      );
+    }
+    if (messageBytes > this._limits.maxMessageBytes) {
+      this._recordRejection(messageBytes);
+      throw createMailboxError(
+        TEAM_MAILBOX_ERROR_CODES.MESSAGE_TOO_LARGE,
+        `TeamMailbox.send: message is ${messageBytes} bytes; limit is ${this._limits.maxMessageBytes}`,
+        {
+          messageBytes,
+          maxMessageBytes: this._limits.maxMessageBytes,
+        },
+      );
+    }
+    if (!this._hasCapacity(messageBytes)) {
+      this._compactDelivered();
+    }
+    if (!this._hasCapacity(messageBytes)) {
+      this._recordRejection(messageBytes);
+      throw createMailboxError(
+        TEAM_MAILBOX_ERROR_CODES.CAPACITY_EXCEEDED,
+        "TeamMailbox.send: mailbox capacity exceeded; undelivered messages were preserved",
+        {
+          messageBytes,
+          maxMessages: this._limits.maxMessages,
+          maxTotalBytes: this._limits.maxTotalBytes,
+          currentMessages: this._log.length,
+          currentBytes: this._totalBytes,
+        },
+      );
+    }
+    this._seq = msg.id;
     this._log.push(msg);
-    return { ...msg };
+    this._entryBytes.set(msg.id, messageBytes);
+    this._totalBytes += messageBytes;
+    this._counters.acceptedMessages += 1;
+    this._counters.acceptedBytes += messageBytes;
+    return this._cloneMessage(msg);
+  }
+
+  _serializedBytes(msg) {
+    return Buffer.byteLength(JSON.stringify(msg), "utf8");
+  }
+
+  _cloneMessage(msg) {
+    return JSON.parse(JSON.stringify(msg));
+  }
+
+  _recordRejection(messageBytes) {
+    this._counters.rejectedMessages += 1;
+    this._counters.rejectedBytes += nonNegativeNumber(messageBytes);
+  }
+
+  _hasCapacity(messageBytes) {
+    return (
+      this._log.length + 1 <= this._limits.maxMessages &&
+      this._totalBytes + messageBytes <= this._limits.maxTotalBytes
+    );
+  }
+
+  _fullyDelivered(msg) {
+    // Without an explicitly registered audience, removing a message could make
+    // a later-known teammate miss it. Prefer backpressure over silent loss.
+    if (this._recipients.size === 0) return false;
+
+    if (msg.to !== "*") {
+      if (!this._recipients.has(msg.to)) return false;
+      // Existing delivery semantics intentionally suppress self-messages.
+      if (msg.from === msg.to) return true;
+      return (this._delivered.get(msg.to) || 0) >= msg.id;
+    }
+
+    for (const recipient of this._recipients) {
+      if (recipient === msg.from) continue;
+      if ((this._delivered.get(recipient) || 0) < msg.id) return false;
+    }
+    return true;
+  }
+
+  _compactDelivered() {
+    let compactedMessages = 0;
+    let compactedBytes = 0;
+    const retained = [];
+    for (const msg of this._log) {
+      if (this._fullyDelivered(msg)) {
+        compactedMessages += 1;
+        const bytes =
+          this._entryBytes.get(msg.id) ?? this._serializedBytes(msg);
+        compactedBytes += bytes;
+        this._entryBytes.delete(msg.id);
+      } else {
+        retained.push(msg);
+      }
+    }
+    if (compactedMessages > 0) {
+      this._log = retained;
+      this._totalBytes = Math.max(0, this._totalBytes - compactedBytes);
+      this._counters.compactionRuns += 1;
+      this._counters.compactedMessages += compactedMessages;
+      this._counters.compactedBytes += compactedBytes;
+    }
+    return { messages: compactedMessages, bytes: compactedBytes };
   }
 
   _isFor(msg, recipient) {
@@ -55,7 +282,7 @@ export class TeamMailbox {
         (m) =>
           m.id > cursor && m.from !== recipient && this._isFor(m, recipient),
       )
-      .map((m) => ({ ...m }));
+      .map((m) => this._cloneMessage(m));
   }
 
   /**
@@ -79,28 +306,175 @@ export class TeamMailbox {
 
   /** The full ordered message log (for a status panel / audit). */
   log() {
-    return this._log.map((m) => ({ ...m }));
+    return this._log.map((m) => this._cloneMessage(m));
   }
 
   size() {
     return this._log.length;
   }
 
+  /**
+   * Current bounded-queue pressure. `ratio` is the stricter of message-count
+   * and byte pressure; `full` means a non-empty next message cannot fit without
+   * compaction.
+   */
+  pressure() {
+    const messageRatio = this._log.length / this._limits.maxMessages;
+    const byteRatio = this._totalBytes / this._limits.maxTotalBytes;
+    const ratio = Math.max(messageRatio, byteRatio);
+    const level =
+      ratio >= 1
+        ? "full"
+        : ratio >= 0.95
+          ? "critical"
+          : ratio >= 0.8
+            ? "high"
+            : "normal";
+    return {
+      ratio,
+      messageRatio,
+      byteRatio,
+      level,
+      full:
+        this._log.length >= this._limits.maxMessages ||
+        this._totalBytes >= this._limits.maxTotalBytes,
+    };
+  }
+
+  /** Queue usage, configured limits, registered audience, and lifetime counts. */
+  status() {
+    return {
+      messages: this._log.length,
+      totalBytes: this._totalBytes,
+      limits: { ...this._limits },
+      recipients: Array.from(this._recipients),
+      registeredRecipients: this._recipients.size,
+      pressure: this.pressure(),
+      counters: { ...this._counters },
+    };
+  }
+
   snapshot() {
     return {
-      log: this._log.map((m) => ({ ...m })),
+      version: 2,
+      limits: { ...this._limits },
+      log: this._log.map((m) => this._cloneMessage(m)),
       seq: this._seq,
       delivered: Array.from(this._delivered.entries()),
+      recipients: Array.from(this._recipients),
+      totalBytes: this._totalBytes,
+      counters: { ...this._counters },
     };
   }
 
-  static restore(snap, { now = () => Date.now() } = {}) {
-    const mb = new TeamMailbox({ now });
-    mb._log = Array.isArray(snap?.log) ? snap.log.map((m) => ({ ...m })) : [];
-    mb._seq =
-      Number(snap?.seq) ||
-      mb._log.reduce((max, m) => Math.max(max, m.id || 0), 0);
-    mb._delivered = new Map(snap?.delivered || []);
+  static restore(
+    snap,
+    {
+      now = () => Date.now(),
+      maxMessageBytes,
+      maxMessages,
+      maxTotalBytes,
+    } = {},
+  ) {
+    const savedLimits = snap?.limits || {};
+    const mb = new TeamMailbox({
+      now,
+      maxMessageBytes:
+        maxMessageBytes ??
+        savedLimits.maxMessageBytes ??
+        DEFAULT_TEAM_MAILBOX_LIMITS.maxMessageBytes,
+      maxMessages:
+        maxMessages ??
+        savedLimits.maxMessages ??
+        DEFAULT_TEAM_MAILBOX_LIMITS.maxMessages,
+      maxTotalBytes:
+        maxTotalBytes ??
+        savedLimits.maxTotalBytes ??
+        DEFAULT_TEAM_MAILBOX_LIMITS.maxTotalBytes,
+      recipients: snap?.recipients || [],
+    });
+    mb._log = Array.isArray(snap?.log)
+      ? snap.log.map((m) => mb._cloneMessage(m))
+      : [];
+    mb._entryBytes = new Map();
+    mb._totalBytes = 0;
+    let previousId = 0;
+    for (const msg of mb._log) {
+      if (
+        !msg ||
+        typeof msg !== "object" ||
+        !Number.isSafeInteger(msg.id) ||
+        msg.id <= previousId ||
+        typeof msg.to !== "string" ||
+        msg.to.length === 0
+      ) {
+        throw createMailboxError(
+          TEAM_MAILBOX_ERROR_CODES.MESSAGE_INVALID,
+          "TeamMailbox.restore: invalid message log",
+        );
+      }
+      const bytes = mb._serializedBytes(msg);
+      if (bytes > mb._limits.maxMessageBytes) {
+        throw createMailboxError(
+          TEAM_MAILBOX_ERROR_CODES.MESSAGE_TOO_LARGE,
+          "TeamMailbox.restore: retained message exceeds its byte limit",
+          {
+            messageBytes: bytes,
+            maxMessageBytes: mb._limits.maxMessageBytes,
+          },
+        );
+      }
+      mb._entryBytes.set(msg.id, bytes);
+      mb._totalBytes += bytes;
+      previousId = msg.id;
+    }
+    if (
+      mb._log.length > mb._limits.maxMessages ||
+      mb._totalBytes > mb._limits.maxTotalBytes
+    ) {
+      throw createMailboxError(
+        TEAM_MAILBOX_ERROR_CODES.CAPACITY_EXCEEDED,
+        "TeamMailbox.restore: retained log exceeds mailbox capacity",
+        {
+          currentMessages: mb._log.length,
+          currentBytes: mb._totalBytes,
+          maxMessages: mb._limits.maxMessages,
+          maxTotalBytes: mb._limits.maxTotalBytes,
+        },
+      );
+    }
+    const savedSeq = Number(snap?.seq);
+    mb._seq = Math.max(
+      Number.isSafeInteger(savedSeq) && savedSeq >= 0 ? savedSeq : 0,
+      previousId,
+    );
+    mb._delivered = new Map();
+    for (const entry of Array.isArray(snap?.delivered) ? snap.delivered : []) {
+      const [recipient, cursor] = Array.isArray(entry) ? entry : [];
+      if (
+        typeof recipient !== "string" ||
+        !recipient ||
+        !Number.isSafeInteger(cursor) ||
+        cursor < 0 ||
+        cursor > mb._seq
+      ) {
+        throw createMailboxError(
+          TEAM_MAILBOX_ERROR_CODES.MESSAGE_INVALID,
+          "TeamMailbox.restore: invalid delivery cursor",
+        );
+      }
+      mb._delivered.set(recipient, cursor);
+    }
+    const counters = snap?.counters;
+    mb._counters = {
+      acceptedMessages: nonNegativeNumber(counters?.acceptedMessages, mb._seq),
+      acceptedBytes: nonNegativeNumber(counters?.acceptedBytes, mb._totalBytes),
+      rejectedMessages: nonNegativeNumber(counters?.rejectedMessages),
+      rejectedBytes: nonNegativeNumber(counters?.rejectedBytes),
+      compactionRuns: nonNegativeNumber(counters?.compactionRuns),
+      compactedMessages: nonNegativeNumber(counters?.compactedMessages),
+      compactedBytes: nonNegativeNumber(counters?.compactedBytes),
+    };
     return mb;
   }
 }

package/src/lib/agent-team/team-run-state-lock.js

@@ -0,0 +1,209 @@
+/**
+ * Process-lifetime exclusive ownership for a `cc team --state` file.
+ *
+ * Atomic snapshot writes prevent torn JSON, but they do not stop two CLI
+ * processes from restoring the same leases and executing the same side effects.
+ * A lock directory is held for the entire async run. A crashed owner's lock is
+ * reclaimed only when its recorded PID is no longer alive; corrupt ownership
+ * fails closed and requires manual adjudication.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+export const TEAM_RUN_STATE_LOCK_ERROR = "TEAM_RUN_STATE_LOCK_UNAVAILABLE";
+
+export const _deps = {
+  isProcessAlive: (pid) => {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (error) {
+      return error?.code === "EPERM";
+    }
+  },
+  ownerToken: () => randomUUID(),
+  writeMarker: (markerPath, owner) =>
+    fs.writeFileSync(markerPath, JSON.stringify(owner), {
+      encoding: "utf8",
+      mode: 0o600,
+      flag: "wx",
+    }),
+};
+
+function lockError(statePath, owner = null) {
+  const error = new Error(
+    `Team state is already owned by another process: ${statePath}`,
+  );
+  error.code = TEAM_RUN_STATE_LOCK_ERROR;
+  if (owner?.pid) error.ownerPid = owner.pid;
+  return error;
+}
+
+function readOwner(ownerPath) {
+  try {
+    const owner = JSON.parse(fs.readFileSync(ownerPath, "utf8"));
+    if (
+      !owner ||
+      typeof owner !== "object" ||
+      !Number.isSafeInteger(owner.pid) ||
+      owner.pid <= 0 ||
+      !Number.isFinite(owner.startedAt) ||
+      (owner.token !== undefined &&
+        (typeof owner.token !== "string" ||
+          !/^[a-zA-Z0-9-]{16,128}$/.test(owner.token)))
+    ) {
+      return null;
+    }
+    return owner;
+  } catch {
+    return null;
+  }
+}
+
+function sameOwner(left, right) {
+  return !!(
+    left &&
+    right &&
+    left.pid === right.pid &&
+    left.startedAt === right.startedAt &&
+    (left.token || null) === (right.token || null)
+  );
+}
+
+function ownerMarker(owner) {
+  if (owner?.token) return owner.token;
+  return `legacy-${owner.pid}-${Math.trunc(owner.startedAt)}`;
+}
+
+function removeOwnMarker(markerPath, owner) {
+  const marker = readOwner(markerPath);
+  if (!sameOwner(marker, owner)) return false;
+  try {
+    fs.rmSync(markerPath, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Claim deletion inside the observed lock directory, then re-check the exact
+ * owner identity and liveness before removing it.
+ *
+ * This closes the stale-observation ABA race: if a delayed contender writes its
+ * old-owner marker into a replacement lock directory, the owner re-read
+ * mismatches and it removes only its own marker, never the replacement lock.
+ */
+function reclaimDeadLock(lockDir, owner) {
+  const markerPath = path.join(lockDir, `.reclaim-${ownerMarker(owner)}`);
+  try {
+    _deps.writeMarker(markerPath, owner);
+  } catch (error) {
+    if (error?.code === "ENOENT" || error?.code === "EEXIST") return false;
+    throw error;
+  }
+  const current = readOwner(path.join(lockDir, "owner.json"));
+  if (!sameOwner(current, owner) || _deps.isProcessAlive(owner.pid)) {
+    removeOwnMarker(markerPath, owner);
+    return false;
+  }
+  fs.rmSync(lockDir, { recursive: true, force: true });
+  return true;
+}
+
+function canonicalStatePath(statePath) {
+  const requested = path.resolve(statePath);
+  const parent = fs.realpathSync.native(path.dirname(requested));
+  const target = path.join(parent, path.basename(requested));
+  if (fs.existsSync(target)) {
+    const entry = fs.lstatSync(target);
+    if (entry.isSymbolicLink() || !entry.isFile()) {
+      throw new Error(
+        `Team state must be a regular, non-symlink file: ${target}`,
+      );
+    }
+    if (entry.nlink > 1) {
+      throw new Error(`Team state hard links are not allowed: ${target}`);
+    }
+    return fs.realpathSync.native(target);
+  }
+  return target;
+}
+
+export class TeamRunStateLock {
+  constructor(statePath, lockDir, owner) {
+    this.statePath = statePath;
+    this.lockDir = lockDir;
+    this.owner = owner;
+    this._released = false;
+  }
+
+  static acquire(statePath) {
+    if (typeof statePath !== "string" || statePath.trim() === "") {
+      throw new TypeError("team state path is required");
+    }
+    const target = canonicalStatePath(statePath);
+    const lockDir = `${target}.run-lock`;
+    const ownerPath = path.join(lockDir, "owner.json");
+    const owner = {
+      pid: process.pid,
+      startedAt: Date.now(),
+      token: _deps.ownerToken(),
+    };
+
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+      try {
+        fs.mkdirSync(lockDir);
+        try {
+          fs.writeFileSync(ownerPath, JSON.stringify(owner), {
+            encoding: "utf8",
+            mode: 0o600,
+            flag: "wx",
+          });
+        } catch (error) {
+          fs.rmSync(lockDir, { recursive: true, force: true });
+          throw error;
+        }
+        return new TeamRunStateLock(target, lockDir, owner);
+      } catch (error) {
+        if (error?.code !== "EEXIST") throw error;
+        const incumbent = readOwner(ownerPath);
+        if (!incumbent) throw lockError(target);
+        if (_deps.isProcessAlive(incumbent.pid)) {
+          throw lockError(target, incumbent);
+        }
+        // Claim deletion against the exact observed dead owner. The exact-token
+        // reclaim marker prevents a delayed concurrent reclaimer
+        // from deleting a replacement lock created at the original path.
+        reclaimDeadLock(lockDir, incumbent);
+      }
+    }
+    throw lockError(target);
+  }
+
+  release() {
+    if (this._released) return false;
+    const current = readOwner(path.join(this.lockDir, "owner.json"));
+    if (!sameOwner(current, this.owner)) return false;
+    const markerPath = path.join(
+      this.lockDir,
+      `.release-${ownerMarker(this.owner)}`,
+    );
+    try {
+      _deps.writeMarker(markerPath, this.owner);
+    } catch (error) {
+      if (error?.code !== "ENOENT" && error?.code !== "EEXIST") throw error;
+      return false;
+    }
+    const confirmed = readOwner(path.join(this.lockDir, "owner.json"));
+    if (!sameOwner(confirmed, this.owner)) {
+      removeOwnMarker(markerPath, this.owner);
+      return false;
+    }
+    this._released = true;
+    fs.rmSync(this.lockDir, { recursive: true, force: true });
+    return true;
+  }
+}