@wrongstack/core 0.306.0 → 0.306.3

package/dist/coordination/mailbox-codecs.d.ts

@@ -1,17 +1,36 @@
 /**
- * Shared mailbox boundary codecs.
- *
- * GM-P0.2: These are the single canonical validators that every untrusted
- * boundary (tools, HTTP bridge, WebSocket server, HQ gateway, slash commands)
- * MUST use to parse and validate mailbox inputs. They enforce:
+ * Actor-aware mailbox boundary codecs.
  *
+ * They enforce:
  *   - Type + recipient normalization and semantic validation
  *   - Known-field rejection for mutations; forward-compatible tolerance for queries
- *   - Actor-override rejection (body-supplied `from`, `readerId`, etc.)
- *   - Capability checks for directive sends
+ *   - Actor-override rejection (body-supplied `from`, `readerId`, `unreadBy`, …)
+ *   - Capability checks, via the canonical implication graph
+ *   - The shared request bounds from `mailbox-constants.ts`
+ *
+ * ## What actually uses these
+ *
+ * GM-P0.2 introduced this module as "the single canonical validator every
+ * untrusted boundary MUST use". That is not what happened, and the docstring
+ * claiming otherwise was actively dangerous — it invited new surfaces to wire
+ * themselves here on the assumption that the path was battle-tested by the
+ * HTTP bridge. Reality:
+ *
+ *   - `parseMailboxSendInput` — used by the `mail_send` tool
+ *     (`mail-tools.ts`). This is the only codec here with a production caller.
+ *   - `parseMailboxQueryInput` / `parseMailboxAckInput` — exported, no
+ *     production caller.
+ *   - `parseMailboxRegistrationInput` / `parseMailboxHeartbeatInput` — not
+ *     exported from `coordination/index.ts`, no caller anywhere.
+ *   - The HTTP bridge validates through `mailbox-http-validation.ts`; the
+ *     WebUI WebSocket server through `ws-payload-validation.ts`.
  *
- * Downstream tasks (GM-P0.5A) will make the store itself call
- * `validateSendType()` internally so direct typed calls are also gated.
+ * Unused validators rot in a way unused helpers do not: nothing exercises the
+ * rule, so a gap survives review. Two were found here — a body-supplied
+ * `unreadBy` that drove the store's leaders-only audience gate, and an
+ * unbounded `limit` — both fixed below and both pinned by tests. Keep it that
+ * way, or delete the codec: an unenforced boundary is worse than no boundary,
+ * because it reads like one.
  *
  * @module mailbox-codecs
  */
@@ -54,7 +73,7 @@ export declare function parseMailboxSendInput(payload: Record<string, unknown>,
  * Parse and validate a query payload from an untrusted boundary.
  *
  * Queries tolerate unknown fields (forward compatibility for read-only clients).
- * Actor-derived recipient forms are NOT overridden by body-supplied `readerRole`.
+ * Identity fields (`unreadBy`, `readerRole`) come from the actor, never the body.
  *
  * @throws {MailboxValidationError} on any validation failure.
  */

package/dist/coordination/mailbox-constants.d.ts

@@ -19,20 +19,11 @@ export declare const CLIENT_STALE_MS = 60000;
 /** Heartbeat updates are throttled to at most this interval (per agent/client). */
 export declare const HEARTBEAT_THROTTLE_MS = 5000;
 /**
- * How long a read may be served from the in-process registry cache before
- * re-reading the shared file. Kept well below HEARTBEAT_THROTTLE_MS so
- * cross-process registrations become visible promptly.
+ * JSONL line separator. Still live: the one-shot legacy import
+ * (`SqliteMailbox.migrateLegacyFiles`) reads `_mailbox.jsonl` through
+ * `mailbox-message-codec.ts` / `mailbox-parse-state.ts`.
  */
-export declare const REGISTRY_CACHE_TTL_MS = 2000;
-/** JSONL line separator. */
 export declare const LINE_SEPARATOR = "\n";
-/**
- * Soft cap on the in-memory message cache. The cache mirrors the JSONL
- * message file; under normal load it stays well under this. If a pathological
- * mailbox exceeds the cap we fall back to reading from disk rather than
- * holding an unbounded buffer in memory.
- */
-export declare const MESSAGE_CACHE_MAX_ENTRIES = 10000;
 /** Background mailbox awareness polling interval (cross-process fallback). */
 export declare const MAILBOX_AWARENESS_INTERVAL_MS = 30000;
 /** Agent heartbeat interval in the attach layer. */
@@ -98,8 +89,31 @@ export declare const AUTO_COMPACT_DEFAULT_TTL_MS = 86400000;
  * {@link AUTO_COMPACT_DEFAULT_TTL_MS}.
  */
 export declare const AUTO_COMPACT_TYPE_TTL_MS: Readonly<Record<string, number>>;
-/** Maximum requests per minute from a single external agent (bearer token). */
-export declare const HTTP_RATE_LIMIT_PER_MINUTE = 120;
-/** Window size for the sliding-window rate limiter. */
-export declare const HTTP_RATE_LIMIT_WINDOW_MS = 60000;
+/**
+ * Ceiling on `limit` for any query arriving from an untrusted boundary.
+ *
+ * `limit` used to be validated as "a positive integer" and nothing else, so a
+ * caller could ask for `1e9`. Read paths fan a query out across every
+ * recipient address the caller answers to and pass the limit straight through,
+ * and the store pre-limits in SQL — so an absurd limit is not clamped
+ * anywhere: it materializes every matching row (a `JSON.parse` plus a receipt
+ * fold each) once per address.
+ *
+ * 500 is far above what any real reader asks for — the agent loop uses 10,
+ * `mail_inbox` defaults to 20, the HQ snapshot to 50.
+ */
+export declare const MAILBOX_MAX_QUERY_LIMIT = 500;
+/**
+ * Ceiling on batch acknowledgement size from an untrusted boundary.
+ *
+ * `Mailbox.ackMany` applies the whole batch inside ONE `BEGIN IMMEDIATE` and
+ * does a message lookup per entry. Unbounded (except by a 256 KB body cap that
+ * still fits roughly 4,700 acks), a single request meant ~9,400 statements
+ * holding the project's only write lock while every other surface — agent
+ * loop, TUI, WebUI — waited out `busy_timeout` and then failed.
+ *
+ * The same ceiling applies to read limits because a `check` acks what it
+ * returns: an uncapped limit there is an uncapped ack batch.
+ */
+export declare const MAILBOX_MAX_ACK_BATCH = 500;
 //# sourceMappingURL=mailbox-constants.d.ts.map

package/dist/coordination/mailbox-health.d.ts

@@ -24,6 +24,22 @@
  * The watchdog is a passive observer: it does NOT start the bridge.
  * Starting the bridge is the user's job (`wstack mailbox serve` or
  * `/mailbox-serve`). The watchdog then reports on what the user did.
+ *
+ * ## Scope: the HTTP bridge, NOT the project mailbox owner
+ *
+ * Do not reach for this to check whether the mailbox is up. The two processes
+ * are unrelated:
+ *
+ * - The **project mailbox owner** (`mailbox-project-server.ts`) is required
+ *   and self-healing — clients spawn it on demand and it idles out after five
+ *   minutes. Its liveness is `MailboxProjectServerConnection.probeStatus()`,
+ *   which is what the TUI/WebUI connections-health surfaces call.
+ * - The **HTTP bridge** this watchdog probes is an optional façade that exists
+ *   so EXTERNAL agents can reach the mailbox over HTTP. Since 2026-08-07 its
+ *   feature gate (`features.mailboxBridge`) defaults to `'off'`, so on a
+ *   default install there is nothing here to watch — which is why this class
+ *   has no production caller. It stays exported for operators who turn the
+ *   bridge on; construct it only alongside a bridge you actually started.
  */
 import type { Mailbox, MailboxSendInput } from './mailbox-types.js';
 export interface MailboxHealthWatchdogOptions {

package/dist/coordination/mailbox-http-validation.d.ts

@@ -1,5 +1,6 @@
 import type { AgentHeartbeatInput, AgentRegistrationInput, ClientHeartbeatInput, ClientRegistrationInput, MailboxAckBatchInput, MailboxAckInput, MailboxActorContext, MailboxMessage, MailboxQuery, MailboxSendInput } from './mailbox-types.js';
 export declare const MAILBOX_HTTP_MAX_AGE_CEILING_MS: number;
+export { MAILBOX_MAX_ACK_BATCH, MAILBOX_MAX_QUERY_LIMIT, } from './mailbox-constants.js';
 export declare class MailboxHttpValidationError extends Error {
 }
 export interface MailboxCheckInput {
@@ -40,7 +41,7 @@ export declare function requireString(object: unknown, key: string): string;
  */
 export declare function parseSinceMs(url: string, defaultMaxAgeMs: number | undefined): SinceResolution;
 export declare function filterMailboxMessagesByTimestamp(messages: readonly MailboxMessage[], minTimestampIso: string | undefined): MailboxMessage[];
-export declare function validateSend(body: unknown, actorId?: string): MailboxSendInput;
+export declare function validateSend(body: unknown, actorId?: string, actorSessionId?: string): MailboxSendInput;
 export declare function validateQuery(body: unknown): MailboxQuery;
 export declare function validateCheck(body: unknown, actorId?: string): MailboxCheckInput;
 export declare function validateAck(body: unknown, actorId?: string): MailboxAckInput;

package/dist/coordination/mailbox-parse-state.d.ts

@@ -1,16 +1,34 @@
 /**
- * Incremental parse state for the mailbox JSONL file.
+ * Parse state for the legacy mailbox JSONL file.
  *
- * `parseMailboxFile()` is a whole-file operation: it JSON-parses every line and
- * re-projects every message. That is the correct shape for a one-shot read, but
- * the read path is anything but one-shot — `unreadCount()`/`query()` consult the
- * cache on every tool call, and any append by another session invalidates it.
- * On a mailbox holding a day of fleet traffic (~3 MB / ~2.8k lines) that turned
- * into the single largest allocation source in the whole TUI process: ~78% of
- * all bytes allocated while idle, which V8 then let pile up as garbage until a
- * major GC — read as "RAM keeps growing and /clear doesn't help".
+ * ## Where this runs today
  *
- * This module keeps enough state alongside the projections that an APPEND can
+ * ONE caller: `SqliteMailbox.migrateLegacyFiles()` via `parseMailboxFile()`,
+ * i.e. the one-shot import of a pre-SQLite `_mailbox.jsonl` that runs at most
+ * once per project and is then fenced off by the `legacy_files_imported`
+ * marker. Nothing reads JSONL on the live path any more: the detached owner
+ * holds the only handle and every query is SQL.
+ *
+ * The incremental half of this module — `createMailboxParseState` +
+ * `ingestMailboxChunk` called with an appended chunk — has NO production
+ * caller. `parseMailboxFile()` is implemented on top of it (one fold, not
+ * two), so the code runs, but the append path and its invariants (stale-index
+ * tracking, `firstNewIndex`, duplicate-id fan-out) are exercised only by
+ * tests. Treat a change there as unvalidated by production traffic.
+ *
+ * ## Why it was built this way
+ *
+ * Historical, and worth keeping because the fold logic is still the thing
+ * that has to be exact: when the mailbox WAS a JSONL file, the read path was
+ * anything but one-shot — `unreadCount()`/`query()` consulted a cache on every
+ * tool call and any append by another session invalidated it. On a mailbox
+ * holding a day of fleet traffic (~3 MB / ~2.8k lines) a full re-parse per
+ * read became the single largest allocation source in the TUI process: ~78% of
+ * all bytes allocated while idle, piling up as garbage until a major GC — read
+ * as "RAM keeps growing and /clear doesn't help". That pressure is gone with
+ * the store; the exactness requirement is not.
+ *
+ * The module keeps enough state alongside the projections that an APPEND can
  * be folded in without touching the bytes that were already parsed:
  *
  *   - `messages`          — base messages in file order, v1 acks already folded

package/dist/coordination/mailbox-project-server.js

@@ -251,6 +251,14 @@ function makePatternMatcher(pattern) {
   return (e) => e === pattern;
 }
 
+// src/security/file-permissions.ts
+import {
+  restrictDirPermissions,
+  restrictFilePermissions,
+  SECRET_DIR_MODE,
+  SECRET_FILE_MODE
+} from "@wrongstack/persistence";
+
 // src/utils/atomic-write.ts
 import {
   createPersistencePrimitives
@@ -1964,16 +1972,18 @@ function persistReceipt(db, messageId, state) {
 }
 function materializeMessageRows(db, rows) {
   if (rows.length === 0) return [];
-  const useTargetedReceipts = rows.length <= 500;
-  const receiptSql = useTargetedReceipts ? `
-        SELECT message_id, actor_id, read_at, completed_at, completed_by, outcome
-        FROM message_receipts
-        WHERE message_id IN (${rows.map(() => "?").join(", ")})
-      ` : `
+  const receiptRows = [];
+  for (const ids of chunk(
+    rows.map((row) => row.id),
+    400
+  )) {
+    const receiptSql = `
         SELECT message_id, actor_id, read_at, completed_at, completed_by, outcome
         FROM message_receipts
+        WHERE message_id IN (${ids.map(() => "?").join(", ")})
       `;
-  const receiptRows = db.prepare(receiptSql).all(...useTargetedReceipts ? rows.map((row) => row.id) : []);
+    receiptRows.push(...db.prepare(receiptSql).all(...ids));
+  }
   const receiptState = /* @__PURE__ */ new Map();
   for (const row of receiptRows) {
     const states = receiptState.get(row.message_id) ?? {};
@@ -2002,8 +2012,16 @@ function materializeMessageRows(db, rows) {
   });
 }
 function deleteMessages(db, ids) {
-  const statement = db.prepare("DELETE FROM messages WHERE id = ?");
-  for (const id of ids) statement.run(id);
+  for (const chunkIds of chunk(ids, 400)) {
+    db.prepare(`DELETE FROM messages WHERE id IN (${chunkIds.map(() => "?").join(", ")})`).run(
+      ...chunkIds
+    );
+  }
+}
+function* chunk(values, size) {
+  for (let start = 0; start < values.length; start += size) {
+    yield values.slice(start, start + size);
+  }
 }
 function persistAgent(db, agent) {
   db.prepare(`
@@ -2191,17 +2209,24 @@ function credentialRevoke(db, credentialId, reason, by) {
 function credentialRotate(db, transaction, credentialId, options) {
   const old = credentialGet(db, credentialId);
   if (old === null) return null;
+  if (old.status === "revoked") return null;
   return credentialIssue(db, transaction, {
     principalId: old.principalId,
     projectId: old.projectId ?? options?.projectId,
     kind: old.kind,
     capabilities: options?.capabilities ?? old.capabilities,
-    ttlMs: options?.ttlMs ?? MAX_CREDENTIAL_TTL[old.kind],
+    ttlMs: options?.ttlMs ?? previousCredentialTtlMs(old),
     notBefore: options?.notBefore,
     supersedes: credentialId,
     issuedBy: options?.issuedBy
   });
 }
+function previousCredentialTtlMs(credential) {
+  const issuedAt = new Date(credential.issuedAt).getTime();
+  const expiresAt = new Date(credential.expiresAt).getTime();
+  const ttlMs = expiresAt - issuedAt;
+  return Number.isFinite(ttlMs) && ttlMs > 0 ? ttlMs : MAX_CREDENTIAL_TTL[credential.kind];
+}
 
 // src/coordination/sqlite-mailbox-schema.ts
 import * as fs2 from "node:fs";
@@ -2249,11 +2274,11 @@ function createMailboxParseState(raw) {
   ingestMailboxChunk(state, raw);
   return state;
 }
-function ingestMailboxChunk(state, chunk) {
+function ingestMailboxChunk(state, chunk2) {
   const firstNewIndex = state.messages.length;
   const ackRecords = [];
   const staleExisting = /* @__PURE__ */ new Set();
-  for (const line of chunk.split(LINE_SEPARATOR)) {
+  for (const line of chunk2.split(LINE_SEPARATOR)) {
     if (line.trim().length === 0) continue;
     let parsed;
     try {
@@ -2565,6 +2590,7 @@ var SqliteMailbox = class {
   lastHeartbeat = /* @__PURE__ */ new Map();
   lastClientHeartbeat = /* @__PURE__ */ new Map();
   autoCompactTimer = null;
+  autoCompactInFlight;
   closed = false;
   stmt(sql) {
     return this.db.prepare(sql);
@@ -2660,9 +2686,14 @@ var SqliteMailbox = class {
     const type = query.type === void 0 ? void 0 : normalizeMailboxMessageType(query.type);
     const priorityRank = { low: 0, normal: 1, high: 2 };
     const minimumRank = query.minPriority === void 0 ? 0 : priorityRank[query.minPriority];
+    if (query.ids !== void 0 && query.ids.length === 0) return [];
     const statuses = query.unreadBy === void 0 ? await this.getAgentStatuses() : void 0;
     const where = [];
     const params = [];
+    if (query.ids !== void 0) {
+      where.push(`id IN (${query.ids.map(() => "?").join(", ")})`);
+      params.push(...query.ids);
+    }
     if (query.to !== void 0) {
       where.push("(to_id = ? OR to_id = ?)");
       params.push(query.to, "*");
@@ -2735,7 +2766,9 @@ var SqliteMailbox = class {
       params.push(query.limit ?? 50);
     }
     const rows = this.stmt(sql).all(...params);
+    const idFilter = query.ids === void 0 ? void 0 : new Set(query.ids);
     const messages = this.materializeMessageRows(rows).filter((message) => {
+      if (idFilter !== void 0 && !idFilter.has(message.id)) return false;
       if (query.to !== void 0 && message.to !== query.to && message.to !== "*") return false;
       if (query.from !== void 0 && message.from !== query.from) return false;
       if (query.sessionId !== void 0 && message.senderSessionId !== query.sessionId)
@@ -2840,11 +2873,76 @@ var SqliteMailbox = class {
     }
     return updated;
   }
+  /**
+   * Count the messages this actor has neither read nor completed.
+   *
+   * Pushed into SQL rather than filtering `readMessages()`. The pre-tool hook
+   * asks for this repeatedly — `mailbox-hooks.ts` throttles it to once a
+   * second, which bounds the frequency but not the cost — and the JS form
+   * materialized EVERY row in `messages`, joined the whole `message_receipts`
+   * table, and folded per-actor receipt state across all of them just to
+   * return an integer.
+   *
+   * The predicate is deliberately the same one {@link query} builds for
+   * `{ unreadBy, incompleteOnly }`, because it has to agree exactly with
+   * `isMessageCompletedForActor` and `isMailboxMessageVisibleTo`:
+   *
+   * - **unread** — no per-actor receipt carrying `read_at`, and no legacy
+   *   `readBy` key. Both are checked: `ackMany` writes the receipt row AND
+   *   mirrors the timestamp into the message's `readBy` JSON.
+   * - **incomplete** — not `legacy_global_completion`, no per-actor receipt
+   *   carrying `completed_at`, and the aggregate `completed` flag counts only
+   *   when the message has no receipts at all (once any actor has a receipt,
+   *   completion is per-actor and the aggregate flag is not authoritative).
+   * - **audience** — `leaders` mail is invisible unless the actor's base
+   *   identity is `leader`. This call path carries no role, matching the
+   *   `isMailboxMessageVisibleTo(message, forAgentId)` it replaces.
+   */
   async unreadCount(forAgentId, sessionId) {
     const sessionAddress = sessionId === void 0 ? void 0 : sessionRecipient(sessionId);
-    return this.readMessages().filter(
-      (message) => (message.to === forAgentId || message.to === "*" || message.to === sessionAddress) && isMailboxMessageVisibleTo(message, forAgentId) && !(forAgentId in message.readBy) && !isMessageCompletedForActor(message, forAgentId) && message.deletedAt === void 0
-    ).length;
+    const where = [];
+    const params = [];
+    const recipients = ["to_id = ?", "to_id = '*'"];
+    params.push(forAgentId);
+    if (sessionAddress !== void 0) {
+      recipients.push("to_id = ?");
+      params.push(sessionAddress);
+    }
+    where.push(`(${recipients.join(" OR ")})`);
+    where.push("deleted_at IS NULL");
+    if (!isMailboxLeader(forAgentId)) {
+      where.push("COALESCE(json_extract(data, '$.audience'), 'all') <> 'leaders'");
+    }
+    where.push(`NOT EXISTS (
+      SELECT 1 FROM message_receipts AS read_receipt
+      WHERE read_receipt.message_id = messages.id
+        AND read_receipt.actor_id = ?
+        AND read_receipt.read_at IS NOT NULL
+    )`);
+    params.push(forAgentId);
+    where.push(`NOT EXISTS (
+      SELECT 1 FROM json_each(json_extract(data, '$.readBy')) AS legacy_read
+      WHERE legacy_read.key = ?
+    )`);
+    params.push(forAgentId);
+    where.push("legacy_global_completion = 0");
+    where.push(`NOT EXISTS (
+      SELECT 1 FROM message_receipts AS completed_receipt
+      WHERE completed_receipt.message_id = messages.id
+        AND completed_receipt.actor_id = ?
+        AND completed_receipt.completed_at IS NOT NULL
+    )`);
+    params.push(forAgentId);
+    where.push(`(
+      completed = 0 OR EXISTS (
+        SELECT 1 FROM message_receipts AS any_receipt
+        WHERE any_receipt.message_id = messages.id
+      )
+    )`);
+    const row = this.stmt(
+      `SELECT COUNT(*) AS total FROM messages WHERE ${where.join(" AND ")}`
+    ).get(...params);
+    return Number(row?.total ?? 0);
   }
   async softDelete(mailId, by) {
     const message = this.findMessage(mailId);
@@ -2936,10 +3034,14 @@ var SqliteMailbox = class {
    * heartbeat from that id simply is not throttled and writes once more.
    */
   pruneHeartbeats(map, nowMs) {
-    if (map.size <= HEARTBEAT_TRACKING_MAX_ENTRIES) return;
     for (const [id, at] of map) {
       if (nowMs - at > HEARTBEAT_TRACKING_TTL_MS) map.delete(id);
     }
+    while (map.size > HEARTBEAT_TRACKING_MAX_ENTRIES) {
+      const oldest = map.keys().next().value;
+      if (oldest === void 0) break;
+      map.delete(oldest);
+    }
   }
   async deregisterAgent(agentId) {
     this.stmt("DELETE FROM agents WHERE agent_id = ?").run(agentId);
@@ -3043,7 +3145,14 @@ var SqliteMailbox = class {
     return purgeStale(this.compactionCtx(), options);
   }
   async autoCompact(options) {
-    return autoCompact(this.compactionCtx(), options);
+    if (this.autoCompactInFlight !== void 0) return this.autoCompactInFlight;
+    const inFlight = autoCompact(this.compactionCtx(), options);
+    this.autoCompactInFlight = inFlight;
+    try {
+      return await inFlight;
+    } finally {
+      if (this.autoCompactInFlight === inFlight) this.autoCompactInFlight = void 0;
+    }
   }
   /** Bundle of store operations the retention sweeps drive. */
   compactionCtx() {
@@ -3359,9 +3468,9 @@ function handleMessage(state, message) {
     scheduleIdleStop();
   });
 }
-function onData(state, chunk) {
+function onData(state, chunk2) {
   state.lastSeenAt = Date.now();
-  state.buffer += chunk;
+  state.buffer += chunk2;
   while (true) {
     const newline = state.buffer.indexOf("\n");
     if (newline < 0) {
@@ -3402,6 +3511,13 @@ async function writeMetadata() {
   const metadata = { ...serverStatus(), authToken };
   await atomicWrite(metadataPath, `${JSON.stringify(metadata, null, 2)}
 `, { mode: 384 });
+  await restrictFilePermissions(metadataPath, {
+    label: "mailbox-server-metadata",
+    // stdio is 'ignore' for this detached process; stderr is where its other
+    // diagnostics go, so a failed hardening is at least consistent with them.
+    warn: (message) => process.stderr.write(`${message}
+`)
+  });
 }
 async function removeOwnedMetadata() {
   try {
@@ -3450,7 +3566,7 @@ var server = net.createServer((socket) => {
   void metadataWritten.then(() => {
     if (!socket.destroyed) send(state, { type: "hello", ...serverInfo });
   });
-  socket.on("data", (chunk) => onData(state, chunk));
+  socket.on("data", (chunk2) => onData(state, chunk2));
   socket.on("error", () => {
   });
   socket.on("close", () => {

package/dist/coordination/mailbox-types.d.ts

@@ -105,12 +105,14 @@ export { MAILBOX_TYPE_PROPERTIES, type MailboxMessageType, type MailboxTypeCateg
  * 6. **Awareness polling**: `btw` messages intercepted by background
  *    polling are queued via `setBtwNote()` for injection at a safe loop
  *    boundary, not folded inline.
- * 7. **Agent registry**: `getAgentStatuses()` reads the dedicated agent
- *    registry (`_mailbox.registry.json`), not mailbox message content. The
- *    registry is populated by agent heartbeat calls (not by `status`-type
- *    messages). `Mailbox.getAgentStatuses()` derives
- *    a registry snapshot from `status`-type messages as a fallback when no
- *    shared registry file exists.
+ * 7. **Agent registry**: `getAgentStatuses()` reads the dedicated `agents`
+ *    table, not mailbox message content. That table is populated by
+ *    `registerAgent` / `heartbeat` — never by `status`-type messages, which
+ *    are ordinary mail and carry no presence meaning. There is no fallback
+ *    that derives presence from message content: the registry is either the
+ *    owner's table or nothing. (It was `_mailbox.registry.json` before the
+ *    SQLite cutover; both that file and the derive-from-messages fallback are
+ *    gone.)
  * 8. **Request-scoped context**: delivered raw mailbox blocks are removed
  *    after one successful provider evaluation. Durable assistant/tool/task
  *    consequences remain; routine mail does not occupy later requests.
@@ -132,6 +134,26 @@ export type MailboxAudience = 'all' | 'leaders';
 export declare function mailboxIdentityBase(agentId: string): string;
 /** Whether a mailbox identity belongs to the session's main/leader agent. */
 export declare function isMailboxLeader(agentId: string, role?: string): boolean;
+/**
+ * Whether a sender identity belongs to a named agent family.
+ *
+ * Matches the family id exactly, or as the `<family>-<suffix>` prefix that a
+ * spawned worker carries. Both forms occur in practice for the same logical
+ * sender: a pipeline agent may post under its plain id (`dep-watcher`, which
+ * `makeDependencyWatcherConfig` sends as), or a subagent may post under the
+ * name it was spawned with — `host-subagent-factory` sets `ctx.agentId` from
+ * the spawn name, so the tech-stack worker spawned as
+ * `tech-stack-package.json` writes mail from `tech-stack-package.json@<tag>`.
+ * A consumer gating on the plain family id with `===` would silently reject
+ * its own pipeline.
+ *
+ * Same shape as the existing `chimera` / `chimera-*` check in
+ * `applyMailboxSendPolicy` and `host-subagent-factory`.
+ *
+ * Session/process qualifiers are stripped first, so `<family>@<tag>` and
+ * `<family>#<pid>` match too.
+ */
+export declare function isMailboxSenderInFamily(senderId: string, family: string): boolean;
 /** Whether a message may be consumed by the supplied agent identity. */
 export declare function isMailboxMessageVisibleTo(message: Pick<MailboxMessage, 'audience'>, agentId: string, role?: string): boolean;
 /**
@@ -381,6 +403,22 @@ export interface MailboxAgentStatus {
     source?: 'cli' | 'webui' | 'mcp' | 'acp' | 'http' | undefined;
 }
 export interface MailboxQuery {
+    /**
+     * Restrict the result to these message ids.
+     *
+     * Exists so a caller that already knows which messages it cares about can
+     * ask about exactly those instead of pulling a set and scanning it. The
+     * HTTP bridge's per-actor visibility checks did the latter — answering
+     * "is this one message mine?" by materializing every message addressed to
+     * the actor, which on a busy project meant a full table read (plus the
+     * whole receipt table, plus a retention projection per row) for every
+     * single `ack`.
+     *
+     * An empty array matches nothing. Untrusted request codecs deliberately do
+     * NOT accept this field — `validateQuery` whitelists, so it stays a
+     * server-side narrowing rather than something a caller can widen.
+     */
+    ids?: readonly string[] | undefined;
     /** Filter by recipient agent id. */
     to?: string | undefined;
     /** Filter by sender agent id. */

package/dist/coordination/package-outdated-watcher.d.ts

@@ -58,7 +58,21 @@ export interface PackageOutdatedWatcherOptions {
     pollIntervalMs?: number | undefined;
     /** Agent id that runs this watcher. Default: 'pkg-outdated-watcher'. */
     watcherAgentId?: string | undefined;
-    /** Agent id of the tech-stack agent to watch for results. Default: 'tech-stack'. */
+    /**
+     * The only sender whose `result` messages this watcher acts on. Default:
+     * `'tech-stack'`. Matched as an agent family, so the worker the tech-stack
+     * consumer spawns as `tech-stack-<manifest>` also passes — `ctx.agentId`
+     * comes from the spawn name, so its mail arrives from
+     * `tech-stack-package.json@<tag>`, not from a bare `tech-stack`.
+     *
+     * This option was declared and documented from the start but never read:
+     * it appeared exactly once in the codebase, in this interface. The watcher
+     * therefore acted on a `result` addressed to it from ANY sender, and the
+     * body chose both the package names and — through `getPackageAuthor` —
+     * whether the resulting HIGH-priority notification went to one agent or was
+     * broadcast to `*`. Any agent on the project could use it to push
+     * attacker-chosen text to everyone, under a watcher's identity.
+     */
     techStackAgentId?: string | undefined;
     /** Called to send a notification to an agent. */
     onNotify: (msg: OutdatedNotifyMessage) => Promise<void>;

package/dist/coordination/sqlite-mailbox-credentials.d.ts

@@ -29,6 +29,32 @@ export declare function credentialIssue(db: DatabaseSync, transaction: <T>(run:
  */
 export declare function credentialVerify(db: DatabaseSync, credentialId: string, secret: string): CredentialValidation;
 export declare function credentialRevoke(db: DatabaseSync, credentialId: string, reason?: string, by?: string): boolean;
+/**
+ * Rotate a credential: mint a successor for the same principal and mark the
+ * predecessor `rotated_out` with an overlap window.
+ *
+ * Two rules that are easy to get wrong, and were:
+ *
+ * 1. **A revoked credential is not rotatable.** Rotation has the same
+ *    capability requirement as issuance, so this is not a privilege boundary —
+ *    but it IS an audit and intent boundary. Rotating a revoked credential
+ *    minted a fresh ACTIVE credential carrying the revoked one's principal and
+ *    capabilities, and recorded it as an ordinary rotation
+ *    (`supersedes: <revoked-id>`). Revocation is the emergency lever; undoing
+ *    it must be an explicit re-issue that reads like one in the log, not a
+ *    rotate that reads like routine hygiene. `rotated_out` and expired-but-
+ *    active credentials stay rotatable: "my credential lapsed, roll it" is a
+ *    legitimate flow, and neither state asserts that the holder was distrusted.
+ *
+ * 2. **Rotation preserves the credential's lifetime**, it does not reset it to
+ *    the maximum for the kind. Defaulting to `MAX_CREDENTIAL_TTL` meant a
+ *    deliberately short-lived credential — a 5-minute agent token minted for
+ *    one task — silently became a 7-day one the first time it was rotated,
+ *    with nothing in the call expressing that intent. The original duration is
+ *    recoverable from the record (`expiresAt - issuedAt`), and
+ *    `createMailboxCredential` still clamps it to the per-kind maximum, so
+ *    preserving it can only ever narrow the grant.
+ */
 export declare function credentialRotate(db: DatabaseSync, transaction: <T>(run: () => T) => T, credentialId: string, options?: Partial<IssueCredentialOptions>): {
     credential: MailboxCredential;
     secret: string;

package/dist/coordination/sqlite-mailbox.d.ts

@@ -14,6 +14,7 @@ export declare class SqliteMailbox implements Mailbox {
     private readonly lastHeartbeat;
     private readonly lastClientHeartbeat;
     private autoCompactTimer;
+    private autoCompactInFlight;
     private closed;
     constructor(projectDir: string, events?: EventBus, eventEmitter?: MailboxEventEmitter);
     private stmt;
@@ -33,6 +34,31 @@ export declare class SqliteMailbox implements Mailbox {
     query(query: MailboxQuery): Promise<MailboxMessage[]>;
     ack(input: MailboxAckInput): Promise<MailboxMessage | null>;
     ackMany(input: MailboxAckBatchInput): Promise<MailboxMessage[]>;
+    /**
+     * Count the messages this actor has neither read nor completed.
+     *
+     * Pushed into SQL rather than filtering `readMessages()`. The pre-tool hook
+     * asks for this repeatedly — `mailbox-hooks.ts` throttles it to once a
+     * second, which bounds the frequency but not the cost — and the JS form
+     * materialized EVERY row in `messages`, joined the whole `message_receipts`
+     * table, and folded per-actor receipt state across all of them just to
+     * return an integer.
+     *
+     * The predicate is deliberately the same one {@link query} builds for
+     * `{ unreadBy, incompleteOnly }`, because it has to agree exactly with
+     * `isMessageCompletedForActor` and `isMailboxMessageVisibleTo`:
+     *
+     * - **unread** — no per-actor receipt carrying `read_at`, and no legacy
+     *   `readBy` key. Both are checked: `ackMany` writes the receipt row AND
+     *   mirrors the timestamp into the message's `readBy` JSON.
+     * - **incomplete** — not `legacy_global_completion`, no per-actor receipt
+     *   carrying `completed_at`, and the aggregate `completed` flag counts only
+     *   when the message has no receipts at all (once any actor has a receipt,
+     *   completion is per-actor and the aggregate flag is not authoritative).
+     * - **audience** — `leaders` mail is invisible unless the actor's base
+     *   identity is `leader`. This call path carries no role, matching the
+     *   `isMailboxMessageVisibleTo(message, forAgentId)` it replaces.
+     */
     unreadCount(forAgentId: string, sessionId?: string): Promise<number>;
     softDelete(mailId: string, by: string): Promise<MailboxMessage | null>;
     restore(mailId: string): Promise<MailboxMessage | null>;