chainlesschain 0.162.148 → 0.162.149

package/src/lib/agent-team/task-lease.js

@@ -0,0 +1,434 @@
+/**
+ * TaskLeaseRegistry (Phase 4 — Agent Team) — the two capabilities the existing
+ * shared task list lacks, layered on top of it rather than reinventing it:
+ *
+ *   1. EXCLUSIVE LEASES WITH TTL. session-core's `SharedTaskList.claim()` is
+ *      documented as "不互斥" (non-mutex) — it just stamps an assignee, so two
+ *      teammates can claim the same task and duplicate the work. Here a task can
+ *      be leased by AT MOST ONE holder at a time, the lease carries an expiry,
+ *      and a crashed teammate's expired lease becomes reclaimable — satisfying
+ *      the Phase 4 acceptance "多 Agent 不会重复处理已被有效 lease 的任务" and
+ *      "teammate 崩溃后任务可回收并重新分配".
+ *
+ *   2. DEPENDENCY EDGES (a DAG). A task declares `dependsOn: [key,…]`; it is not
+ *      claimable until every dependency is COMPLETED. Cycles are rejected at add
+ *      time (a cyclic dep would deadlock — it could never become claimable).
+ *
+ * It COMPOSES a real `SharedTaskList` (optimistic-lock task store, status
+ * vocabulary, snapshot/restore, terminal-state enforcement) — the lease + edges
+ * live in each task's metadata, so persistence/recovery come for free. The clock
+ * is injected (`now`) so lease expiry is fully deterministic in tests.
+ *
+ * This is the scheduling brain; the claim→execute handoff to a real agent
+ * (SubAgentContext.run in a per-teammate worktree) is wired separately.
+ */
+
+import { SharedTaskList, TASK_STATUS } from "@chainlesschain/session-core";
+
+export const DEFAULT_LEASE_TTL_MS = 60000;
+export const DEFAULT_MAX_ATTEMPTS = 3;
+
+export class TaskLeaseRegistry {
+  constructor({
+    groupId = null,
+    now = () => Date.now(),
+    defaultTtlMs = DEFAULT_LEASE_TTL_MS,
+    maxAttempts = DEFAULT_MAX_ATTEMPTS,
+  } = {}) {
+    this._now = typeof now === "function" ? now : () => now;
+    this.defaultTtlMs = defaultTtlMs > 0 ? defaultTtlMs : DEFAULT_LEASE_TTL_MS;
+    this.maxAttempts = maxAttempts > 0 ? maxAttempts : DEFAULT_MAX_ATTEMPTS;
+    this._tasks = new SharedTaskList({ groupId, now: this._now });
+    this._byKey = new Map(); // stable user key → internal SharedTaskList id
+  }
+
+  /**
+   * Add a task to the graph. `key` is a stable, user-chosen identifier so
+   * `dependsOn` can reference tasks regardless of insertion order. Rejects a
+   * duplicate key or a dependency edge that would create a cycle.
+   *
+   * @returns {{ ok:boolean, key?:string, reason?:string, cycle?:string[] }}
+   */
+  addTask({
+    key,
+    title,
+    dependsOn = [],
+    priority = "normal",
+    metadata = {},
+    createdBy = null,
+  } = {}) {
+    const k = key || `t_${this._tasks.size() + 1}`;
+    if (this._byKey.has(k)) {
+      return { ok: false, reason: `duplicate task key "${k}"` };
+    }
+    if (!title || typeof title !== "string") {
+      return { ok: false, reason: "title required" };
+    }
+    const deps = Array.isArray(dependsOn) ? dependsOn.filter(Boolean) : [];
+    // Self-dependency and (once inserted) any back-edge that closes a cycle
+    // would deadlock the task. Check against the edges already present PLUS the
+    // proposed ones.
+    const cycle = this._detectCycleIfAdded(k, deps);
+    if (cycle) {
+      return { ok: false, reason: "dependency cycle", cycle };
+    }
+    const created = this._tasks.add({
+      title,
+      priority,
+      createdBy,
+      metadata: {
+        ...metadata,
+        key: k,
+        dependsOn: deps,
+        lease: null,
+        attempts: 0,
+      },
+    });
+    this._byKey.set(k, created.id);
+    return { ok: true, key: k, id: created.id };
+  }
+
+  /** Resolve a stable key → the current task object (or null). */
+  getTask(key) {
+    const id = this._byKey.get(key);
+    if (!id) return null;
+    const t = this._tasks.get(id);
+    if (!t) return null;
+    return this._view(t);
+  }
+
+  _view(t) {
+    const lease = t.metadata?.lease || null;
+    return {
+      key: t.metadata?.key,
+      id: t.id,
+      title: t.title,
+      status: t.status,
+      priority: t.priority,
+      dependsOn: t.metadata?.dependsOn || [],
+      attempts: t.metadata?.attempts || 0,
+      lease: lease ? { ...lease } : null,
+      assignee: t.assignee,
+      rev: t.rev,
+      // Full metadata is exposed so executors can read user payload
+      // (e.g. a task's shell `command` or agent `prompt`) — it carries the
+      // internal lease/dependsOn/key too, which callers simply ignore.
+      metadata: { ...t.metadata },
+    };
+  }
+
+  list() {
+    return this._tasks.list().map((t) => this._view(t));
+  }
+
+  _statusOf(key) {
+    const id = this._byKey.get(key);
+    const t = id ? this._tasks.get(id) : null;
+    return t ? t.status : null;
+  }
+
+  /** Unmet (not-yet-completed) dependency keys for a task. */
+  unmetDependencies(key) {
+    const t = this.getTask(key);
+    if (!t) return [];
+    return t.dependsOn.filter(
+      (d) => this._statusOf(d) !== TASK_STATUS.COMPLETED,
+    );
+  }
+
+  _leaseValid(lease, now) {
+    return !!(lease && lease.expiresAt > now);
+  }
+
+  /**
+   * Keys that could be leased right now: PENDING (or a task whose lease has
+   * expired) with all dependencies COMPLETED and no currently-valid lease.
+   */
+  claimable({ now = this._now() } = {}) {
+    const out = [];
+    for (const t of this._tasks.list()) {
+      const v = this._view(t);
+      if (
+        v.status === TASK_STATUS.COMPLETED ||
+        v.status === TASK_STATUS.CANCELLED
+      ) {
+        continue;
+      }
+      if (this._leaseValid(v.lease, now)) continue; // held by a live teammate
+      if (this.unmetDependencies(v.key).length > 0) continue; // blocked by deps
+      out.push(v.key);
+    }
+    return out;
+  }
+
+  /**
+   * Acquire (or renew, or steal an expired) exclusive lease.
+   *   - blocked by unmet deps            → { ok:false, reason:"blocked_by_deps", unmet }
+   *   - terminal task                    → { ok:false, reason:"terminal" }
+   *   - validly leased by someone else   → { ok:false, reason:"leased", holder, expiresAt }
+   *   - same holder                      → renew (extend expiry, bump renewals)
+   *   - expired lease held by another    → steal (stolen:true)
+   * @returns {{ ok:boolean, reason?:string, lease?:object, unmet?:string[], holder?:string, expiresAt?:number }}
+   */
+  acquire(key, { holder, ttlMs, now = this._now() } = {}) {
+    if (!holder) return { ok: false, reason: "holder required" };
+    const id = this._byKey.get(key);
+    const task = id ? this._tasks.get(id) : null;
+    if (!task) return { ok: false, reason: "not_found" };
+    if (
+      task.status === TASK_STATUS.COMPLETED ||
+      task.status === TASK_STATUS.CANCELLED
+    ) {
+      return { ok: false, reason: "terminal" };
+    }
+    const unmet = this.unmetDependencies(key);
+    if (unmet.length > 0) {
+      return { ok: false, reason: "blocked_by_deps", unmet };
+    }
+    const existing = task.metadata?.lease || null;
+    if (this._leaseValid(existing, now) && existing.holder !== holder) {
+      return {
+        ok: false,
+        reason: "leased",
+        holder: existing.holder,
+        expiresAt: existing.expiresAt,
+      };
+    }
+    const ttl = ttlMs > 0 ? ttlMs : this.defaultTtlMs;
+    const sameHolder = existing && existing.holder === holder;
+    const lease = {
+      holder,
+      acquiredAt: sameHolder ? existing.acquiredAt : now,
+      expiresAt: now + ttl,
+      renewals: sameHolder ? (existing.renewals || 0) + 1 : 0,
+      stolen: !!(existing && existing.holder !== holder),
+    };
+    return this._write(task, {
+      status: TASK_STATUS.IN_PROGRESS,
+      assignee: holder,
+      metadata: { ...task.metadata, lease },
+    })
+      ? { ok: true, lease }
+      : { ok: false, reason: "concurrent" };
+  }
+
+  /** Extend the lease you hold. Fails if you're not the current valid holder. */
+  renew(key, { holder, ttlMs, now = this._now() } = {}) {
+    const id = this._byKey.get(key);
+    const task = id ? this._tasks.get(id) : null;
+    if (!task) return { ok: false, reason: "not_found" };
+    const lease = task.metadata?.lease || null;
+    if (!this._leaseValid(lease, now) || lease.holder !== holder) {
+      return { ok: false, reason: "not_holder_or_expired" };
+    }
+    const ttl = ttlMs > 0 ? ttlMs : this.defaultTtlMs;
+    const next = {
+      ...lease,
+      expiresAt: now + ttl,
+      renewals: (lease.renewals || 0) + 1,
+    };
+    return this._write(task, { metadata: { ...task.metadata, lease: next } })
+      ? { ok: true, lease: next }
+      : { ok: false, reason: "concurrent" };
+  }
+
+  /** Voluntarily give up a lease — the task returns to PENDING for re-claim. */
+  release(key, { holder, now = this._now() } = {}) {
+    const id = this._byKey.get(key);
+    const task = id ? this._tasks.get(id) : null;
+    if (!task) return { ok: false, reason: "not_found" };
+    const lease = task.metadata?.lease || null;
+    if (!lease || lease.holder !== holder) {
+      return { ok: false, reason: "not_holder" };
+    }
+    return this._write(task, {
+      status: TASK_STATUS.PENDING,
+      assignee: null,
+      metadata: { ...task.metadata, lease: null },
+    })
+      ? { ok: true }
+      : { ok: false, reason: "concurrent" };
+  }
+
+  /** Complete a task you hold the lease on → terminal COMPLETED. */
+  complete(key, { holder, result = null, now = this._now() } = {}) {
+    const id = this._byKey.get(key);
+    const task = id ? this._tasks.get(id) : null;
+    if (!task) return { ok: false, reason: "not_found" };
+    const lease = task.metadata?.lease || null;
+    // Only the valid holder may complete — prevents a stale teammate (whose
+    // lease already expired and was reassigned) from marking another's work done.
+    if (!this._leaseValid(lease, now) || lease.holder !== holder) {
+      return { ok: false, reason: "not_holder_or_expired" };
+    }
+    return this._write(task, {
+      status: TASK_STATUS.COMPLETED,
+      metadata: { ...task.metadata, lease: null, result },
+    })
+      ? { ok: true }
+      : { ok: false, reason: "concurrent" };
+  }
+
+  /**
+   * Report a failed attempt. Under the attempt cap the task returns to PENDING
+   * (reclaimable for retry); at the cap it is CANCELLED (terminal) so the team
+   * doesn't loop forever on a doomed task.
+   * @returns {{ ok:boolean, retry?:boolean, attempts?:number, reason?:string }}
+   */
+  fail(key, { holder, error = null, now = this._now() } = {}) {
+    const id = this._byKey.get(key);
+    const task = id ? this._tasks.get(id) : null;
+    if (!task) return { ok: false, reason: "not_found" };
+    const lease = task.metadata?.lease || null;
+    if (!lease || lease.holder !== holder) {
+      return { ok: false, reason: "not_holder" };
+    }
+    const attempts = (task.metadata?.attempts || 0) + 1;
+    const willRetry = attempts < this.maxAttempts;
+    const ok = this._write(task, {
+      status: willRetry ? TASK_STATUS.PENDING : TASK_STATUS.CANCELLED,
+      assignee: null,
+      metadata: {
+        ...task.metadata,
+        lease: null,
+        attempts,
+        lastError: error ? String(error) : null,
+      },
+    });
+    if (!ok) return { ok: false, reason: "concurrent" };
+    return { ok: true, retry: willRetry, attempts };
+  }
+
+  /**
+   * Reclaim every task whose lease has EXPIRED (a crashed/lost teammate never
+   * renewed) back to PENDING so it can be re-assigned. Returns the reclaimed
+   * keys. This is the crash-recovery sweep.
+   */
+  reclaimExpired({ now = this._now() } = {}) {
+    const reclaimed = [];
+    for (const t of this._tasks.list()) {
+      const lease = t.metadata?.lease || null;
+      if (lease && !this._leaseValid(lease, now)) {
+        const fresh = this._tasks.get(t.id); // re-read for current rev
+        if (
+          this._write(fresh, {
+            status: TASK_STATUS.PENDING,
+            assignee: null,
+            metadata: { ...fresh.metadata, lease: null },
+          })
+        ) {
+          reclaimed.push(fresh.metadata?.key);
+        }
+      }
+    }
+    return reclaimed;
+  }
+
+  stats({ now = this._now() } = {}) {
+    const base = this._tasks.stats();
+    let leased = 0;
+    let expired = 0;
+    for (const t of this._tasks.list()) {
+      const lease = t.metadata?.lease || null;
+      if (lease) {
+        if (this._leaseValid(lease, now)) leased++;
+        else expired++;
+      }
+    }
+    return {
+      ...base,
+      leased,
+      expiredLeases: expired,
+      claimable: this.claimable({ now }).length,
+    };
+  }
+
+  /** Whether the graph is fully done (all terminal). */
+  allDone() {
+    return this._tasks
+      .list()
+      .every(
+        (t) =>
+          t.status === TASK_STATUS.COMPLETED ||
+          t.status === TASK_STATUS.CANCELLED,
+      );
+  }
+
+  snapshot() {
+    return {
+      registry: {
+        defaultTtlMs: this.defaultTtlMs,
+        maxAttempts: this.maxAttempts,
+        byKey: Array.from(this._byKey.entries()),
+      },
+      tasks: this._tasks.snapshot(),
+    };
+  }
+
+  static restore(snapshot, { now = () => Date.now() } = {}) {
+    const reg = new TaskLeaseRegistry({
+      now,
+      defaultTtlMs: snapshot?.registry?.defaultTtlMs,
+      maxAttempts: snapshot?.registry?.maxAttempts,
+    });
+    reg._tasks = SharedTaskList.restore(snapshot.tasks, { now: reg._now });
+    reg._byKey = new Map(snapshot?.registry?.byKey || []);
+    return reg;
+  }
+
+  // --- internals -----------------------------------------------------------
+
+  /** Optimistic write via the underlying list; false on rev conflict. */
+  _write(task, patch) {
+    try {
+      this._tasks.update(task.id, {
+        rev: task.rev,
+        patch,
+        actor: patch.assignee,
+      });
+      return true;
+    } catch {
+      // ConcurrencyError (rev changed under us) — caller re-reads and retries.
+      return false;
+    }
+  }
+
+  /**
+   * Would adding edges `key → dependsOn[i]` create a cycle? Walks the existing
+   * edge set augmented with the proposed edges. Returns the offending path or
+   * null. A self-edge counts as a cycle.
+   */
+  _detectCycleIfAdded(key, deps) {
+    // Build adjacency from current tasks, then add the candidate.
+    const adj = new Map();
+    for (const t of this._tasks.list()) {
+      adj.set(t.metadata?.key, t.metadata?.dependsOn || []);
+    }
+    adj.set(key, deps);
+    const WHITE = 0,
+      GRAY = 1,
+      BLACK = 2;
+    const color = new Map();
+    const stack = [];
+    let found = null;
+    const visit = (node) => {
+      color.set(node, GRAY);
+      stack.push(node);
+      for (const next of adj.get(node) || []) {
+        if (!adj.has(next)) continue; // edge to a not-yet-added task: no cycle via it
+        const c = color.get(next) || WHITE;
+        if (c === GRAY) {
+          found = [...stack.slice(stack.indexOf(next)), next];
+          return true;
+        }
+        if (c === WHITE && visit(next)) return true;
+      }
+      stack.pop();
+      color.set(node, BLACK);
+      return false;
+    };
+    // Only need to start from the candidate — a new cycle must pass through it.
+    if (visit(key)) return found;
+    return null;
+  }
+}

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

@@ -0,0 +1,165 @@
+/**
+ * TeamBudget (Phase 4 — Agent Team) — a team-wide spend cap across four
+ * independent dimensions, consulted by TeamRunner BEFORE it hands a teammate a
+ * new task so a runaway graph is bounded and a resumed session keeps counting
+ * from where it left off (Phase 4 acceptance "支持 token、时间、并发数和费用预算"
+ * + "团队会话恢复后…预算保持一致").
+ *
+ *   - maxTasks    total task EXECUTIONS across all teammates (task-count cap)
+ *   - maxTokens   total (input+output) LLM tokens folded from task results
+ *   - maxUsd      total estimated USD spend — delegated to the audited CostBudget
+ *                 (same pricing/cache-token rules as `--max-budget-usd`)
+ *   - maxWallMs   wall-clock since the first task started (time cap)
+ *
+ * Because a task's cost is only known once it returns, the team may overshoot a
+ * token/USD cap by at most one task — like CostBudget, it never STARTS a task
+ * once already over. A dimension left null is simply inactive. The clock is
+ * injected so the wall-clock cap is deterministic in tests, and snapshot/restore
+ * carries the running totals so `cc team run --resume` doesn't reset the budget.
+ */
+
+import { CostBudget } from "../cost-budget.js";
+
+const pos = (n) => {
+  const v = Number(n);
+  return Number.isFinite(v) && v > 0 ? v : null;
+};
+
+export class TeamBudget {
+  constructor({
+    maxTasks = null,
+    maxTokens = null,
+    maxUsd = null,
+    maxWallMs = null,
+    table = undefined,
+    now = () => Date.now(),
+  } = {}) {
+    this._now = typeof now === "function" ? now : () => now;
+    this.maxTasks = pos(maxTasks);
+    this.maxTokens = pos(maxTokens);
+    this.maxWallMs = pos(maxWallMs);
+    this.cost = new CostBudget({ limitUsd: maxUsd, table });
+    this.tasks = 0;
+    this.tokens = 0;
+    this.startedAt = null; // set on the first recorded task
+  }
+
+  /** Any dimension active? (an all-null budget never stops anything). */
+  enabled() {
+    return (
+      this.maxTasks != null ||
+      this.maxTokens != null ||
+      this.maxWallMs != null ||
+      this.cost.enabled()
+    );
+  }
+
+  /** Begin the wall-clock window (idempotent — first call wins). */
+  start(now = this._now()) {
+    if (this.startedAt == null) this.startedAt = now;
+    return this;
+  }
+
+  /**
+   * Fold one settled task into the running totals. `usage` (an LLM token-usage
+   * event) is optional — a plain `--exec` shell task carries none, so only the
+   * task-count / wall-clock dimensions move for it.
+   * @returns {this}
+   */
+  record({ usage = null, provider, model } = {}, now = this._now()) {
+    this.start(now);
+    this.tasks += 1;
+    if (usage) {
+      this.tokens +=
+        (Number(usage.input_tokens) || 0) + (Number(usage.output_tokens) || 0);
+      this.cost.add({ provider, model, usage });
+    }
+    return this;
+  }
+
+  /**
+   * Which cap (if any) is now reached — checked BEFORE starting a new task.
+   * @returns {null|"max-tasks"|"max-tokens"|"max-usd"|"max-wall-ms"}
+   */
+  reason(now = this._now()) {
+    if (this.maxTasks != null && this.tasks >= this.maxTasks) {
+      return "max-tasks";
+    }
+    if (this.maxTokens != null && this.tokens >= this.maxTokens) {
+      return "max-tokens";
+    }
+    if (this.cost.exceeded()) return "max-usd";
+    if (
+      this.maxWallMs != null &&
+      this.startedAt != null &&
+      now - this.startedAt >= this.maxWallMs
+    ) {
+      return "max-wall-ms";
+    }
+    return null;
+  }
+
+  /** True once any active cap has been reached. */
+  shouldStop(now = this._now()) {
+    return this.reason(now) != null;
+  }
+
+  status(now = this._now()) {
+    return {
+      tasks: this.tasks,
+      maxTasks: this.maxTasks,
+      tokens: this.tokens,
+      maxTokens: this.maxTokens,
+      spentUsd: this.cost.spentUsd,
+      maxUsd: this.cost.limitUsd,
+      elapsedMs: this.startedAt == null ? 0 : now - this.startedAt,
+      maxWallMs: this.maxWallMs,
+      reason: this.reason(now),
+    };
+  }
+
+  snapshot() {
+    return {
+      limits: {
+        maxTasks: this.maxTasks,
+        maxTokens: this.maxTokens,
+        maxUsd: this.cost.limitUsd,
+        maxWallMs: this.maxWallMs,
+      },
+      totals: {
+        tasks: this.tasks,
+        tokens: this.tokens,
+        spentUsd: this.cost.spentUsd,
+        startedAt: this.startedAt,
+      },
+    };
+  }
+
+  /**
+   * Restore running totals + caps from a snapshot. `overrides` lets the current
+   * CLI invocation RAISE/lower a cap on resume — a provided (non-nullish) value
+   * wins over the snapshot's; an omitted one keeps the prior cap (so a resume
+   * with no flags can't silently drop a safety cap).
+   */
+  static restore(snap, { now = () => Date.now(), table, overrides = {} } = {}) {
+    const pick = (o, s) => (o == null ? s : o);
+    const b = new TeamBudget({
+      maxTasks: pick(overrides.maxTasks, snap?.limits?.maxTasks),
+      maxTokens: pick(overrides.maxTokens, snap?.limits?.maxTokens),
+      maxUsd: pick(overrides.maxUsd, snap?.limits?.maxUsd),
+      maxWallMs: pick(overrides.maxWallMs, snap?.limits?.maxWallMs),
+      table,
+      now,
+    });
+    b.tasks = Number(snap?.totals?.tasks) || 0;
+    b.tokens = Number(snap?.totals?.tokens) || 0;
+    // Preserve prior USD spend so the cap keeps counting across a resume.
+    const spent = Number(snap?.totals?.spentUsd);
+    b.cost.spentUsd = Number.isFinite(spent) && spent >= 0 ? spent : 0;
+    if (b.cost.spentUsd > 0) b.cost.priced = true;
+    // A time cap must NOT keep counting wall-clock across a crash gap (the
+    // process was down); restart the window on the next recorded task.
+    b.startedAt = null;
+    return b;
+  }
+}

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

@@ -0,0 +1,106 @@
+/**
+ * TeamMailbox (Phase 4 — Agent Team) — directed + broadcast messaging between
+ * teammates so a coordinating agent can hand off context, flag a finding, or ask
+ * a peer to redo work (Phase 4 work-item "支持 Agent 间直接消息和定向通知",
+ * acceptance "团队会话恢复后…消息…保持一致").
+ *
+ * A message is addressed to a specific recipient (`to`) or broadcast (`to:"*"`).
+ * `drain(recipient)` returns that recipient's undelivered messages (direct +
+ * broadcasts it hasn't seen) and marks them delivered FOR THAT RECIPIENT — a
+ * broadcast is delivered independently to each teammate, so two teammates each
+ * 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.
+ *
+ * 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.
+ */
+
+export class TeamMailbox {
+  constructor({ now = () => Date.now() } = {}) {
+    this._now = typeof now === "function" ? now : () => now;
+    this._log = []; // ordered [{ id, from, to, subject, body, ts }]
+    this._seq = 0; // monotonic message id source
+    this._delivered = new Map(); // recipient → highest message id already drained
+  }
+
+  /**
+   * Post a message. `to` is a teammate id or "*" (broadcast). Returns the stored
+   * message (with its assigned id).
+   */
+  send({ from = null, to, subject = null, body = null } = {}) {
+    if (!to || typeof to !== "string") {
+      throw new Error("TeamMailbox.send: `to` recipient (or '*') is required");
+    }
+    const msg = {
+      id: ++this._seq,
+      from,
+      to,
+      subject,
+      body,
+      ts: this._now(),
+    };
+    this._log.push(msg);
+    return { ...msg };
+  }
+
+  _isFor(msg, recipient) {
+    return msg.to === recipient || msg.to === "*";
+  }
+
+  /** Peek at a recipient's undelivered messages WITHOUT marking them delivered. */
+  peek(recipient) {
+    const cursor = this._delivered.get(recipient) || 0;
+    return this._log
+      .filter(
+        (m) =>
+          m.id > cursor && m.from !== recipient && this._isFor(m, recipient),
+      )
+      .map((m) => ({ ...m }));
+  }
+
+  /**
+   * Return a recipient's undelivered messages and advance its delivery cursor so
+   * they are not returned again. A teammate never receives its own broadcast.
+   */
+  drain(recipient) {
+    const pending = this.peek(recipient);
+    if (pending.length > 0) {
+      const highest = pending[pending.length - 1].id;
+      const cursor = this._delivered.get(recipient) || 0;
+      this._delivered.set(recipient, Math.max(cursor, highest));
+    }
+    return pending;
+  }
+
+  /** How many messages a recipient has yet to drain. */
+  pendingCount(recipient) {
+    return this.peek(recipient).length;
+  }
+
+  /** The full ordered message log (for a status panel / audit). */
+  log() {
+    return this._log.map((m) => ({ ...m }));
+  }
+
+  size() {
+    return this._log.length;
+  }
+
+  snapshot() {
+    return {
+      log: this._log.map((m) => ({ ...m })),
+      seq: this._seq,
+      delivered: Array.from(this._delivered.entries()),
+    };
+  }
+
+  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 || []);
+    return mb;
+  }
+}