@wrongstack/core 0.297.0 → 0.298.1

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

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 // src/coordination/mailbox-project-server.ts
+import { randomBytes as randomBytes2 } from "node:crypto";
 import * as fs5 from "node:fs";
 import * as fsPromises from "node:fs/promises";
 import * as net from "node:net";
@@ -250,6 +251,127 @@ function makePatternMatcher(pattern) {
   return (e) => e === pattern;
 }
 
+// src/utils/atomic-write.ts
+import {
+  createPersistencePrimitives
+} from "@wrongstack/persistence";
+
+// src/types/errors.ts
+var ERROR_CODES = {
+  // Provider
+  PROVIDER_RATE_LIMITED: "PROVIDER_RATE_LIMITED",
+  PROVIDER_AUTH_FAILED: "PROVIDER_AUTH_FAILED",
+  PROVIDER_OVERLOADED: "PROVIDER_OVERLOADED",
+  PROVIDER_INVALID_REQUEST: "PROVIDER_INVALID_REQUEST",
+  PROVIDER_SERVER_ERROR: "PROVIDER_SERVER_ERROR",
+  PROVIDER_NETWORK_ERROR: "PROVIDER_NETWORK_ERROR",
+  PROVIDER_CONTEXT_OVERFLOW: "PROVIDER_CONTEXT_OVERFLOW",
+  // Tool
+  TOOL_NOT_FOUND: "TOOL_NOT_FOUND",
+  TOOL_PERMISSION_DENIED: "TOOL_PERMISSION_DENIED",
+  TOOL_EXECUTION_FAILED: "TOOL_EXECUTION_FAILED",
+  TOOL_TIMEOUT: "TOOL_TIMEOUT",
+  TOOL_INPUT_INVALID: "TOOL_INPUT_INVALID",
+  // Config
+  CONFIG_INVALID: "CONFIG_INVALID",
+  CONFIG_NOT_FOUND: "CONFIG_NOT_FOUND",
+  CONFIG_PARSE_FAILED: "CONFIG_PARSE_FAILED",
+  CONFIG_MIGRATION_NEEDED: "CONFIG_MIGRATION_NEEDED",
+  // Plugin
+  PLUGIN_LOAD_FAILED: "PLUGIN_LOAD_FAILED",
+  PLUGIN_API_MISMATCH: "PLUGIN_API_MISMATCH",
+  PLUGIN_MISSING_DEPENDENCY: "PLUGIN_MISSING_DEPENDENCY",
+  // Agent
+  AGENT_ITERATION_LIMIT: "AGENT_ITERATION_LIMIT",
+  AGENT_CONTEXT_OVERFLOW: "AGENT_CONTEXT_OVERFLOW",
+  AGENT_ABORTED: "AGENT_ABORTED",
+  AGENT_RUN_FAILED: "AGENT_RUN_FAILED",
+  // Session
+  SESSION_NOT_FOUND: "SESSION_NOT_FOUND",
+  SESSION_CORRUPTED: "SESSION_CORRUPTED",
+  SESSION_WRITE_FAILED: "SESSION_WRITE_FAILED",
+  // Container / Registry
+  CONTAINER_TOKEN_ALREADY_BOUND: "CONTAINER_TOKEN_ALREADY_BOUND",
+  CONTAINER_TOKEN_NOT_BOUND: "CONTAINER_TOKEN_NOT_BOUND",
+  CONTAINER_CIRCULAR_DEPENDENCY: "CONTAINER_CIRCULAR_DEPENDENCY",
+  REGISTRY_DUPLICATE: "REGISTRY_DUPLICATE",
+  REGISTRY_NOT_FOUND: "REGISTRY_NOT_FOUND",
+  REGISTRY_INVALID: "REGISTRY_INVALID",
+  // File system
+  FS_READ_FAILED: "FS_READ_FAILED",
+  FS_WRITE_FAILED: "FS_WRITE_FAILED",
+  FS_MKDIR_FAILED: "FS_MKDIR_FAILED",
+  FS_DELETE_FAILED: "FS_DELETE_FAILED",
+  FS_ATOMIC_WRITE_FAILED: "FS_ATOMIC_WRITE_FAILED",
+  // SDD (Spec-Driven Development)
+  SDD_VALIDATION_FAILED: "SDD_VALIDATION_FAILED",
+  SDD_PARSE_FAILED: "SDD_PARSE_FAILED",
+  SDD_INVALID_STATE: "SDD_INVALID_STATE",
+  SDD_NOT_READY: "SDD_NOT_READY",
+  // General
+  VALIDATION_ERROR: "VALIDATION_ERROR",
+  PARSE_FAILED: "PARSE_FAILED",
+  UNKNOWN: "UNKNOWN"
+};
+var WrongStackError = class extends Error {
+  code;
+  subsystem;
+  severity;
+  recoverable;
+  context;
+  constructor(opts) {
+    super(opts.message, { cause: opts.cause });
+    this.name = "WrongStackError";
+    this.code = opts.code;
+    this.subsystem = opts.subsystem;
+    this.severity = opts.severity ?? "error";
+    this.recoverable = opts.recoverable ?? false;
+    this.context = opts.context;
+  }
+  /**
+   * Render a one-line user-facing description.
+   * Subclasses should override for domain-specific formatting.
+   */
+  describe() {
+    const ctx = this.context ? ` ${formatContext(this.context)}` : "";
+    return `${this.code}: ${this.message}${ctx}`;
+  }
+};
+function formatContext(ctx) {
+  const parts = Object.entries(ctx).filter(([, v]) => v !== void 0).slice(0, 3).map(([k, v]) => `${k}=${String(v)}`);
+  return parts.length > 0 ? `[${parts.join(" ")}]` : "";
+}
+var FsError = class extends WrongStackError {
+  path;
+  constructor(opts) {
+    super({
+      message: opts.message,
+      code: opts.code,
+      subsystem: "fs",
+      severity: "error",
+      recoverable: opts.code !== ERROR_CODES.FS_READ_FAILED,
+      context: { path: opts.path, ...opts.context },
+      cause: opts.cause
+    });
+    this.name = "FsError";
+    this.path = opts.path;
+  }
+};
+
+// src/utils/atomic-write.ts
+var primitives = createPersistencePrimitives({
+  createLockTimeoutError: ({ targetPath, timeoutMs }) => new FsError({
+    message: `Timed out waiting for file lock: ${targetPath}`,
+    code: "FS_ATOMIC_WRITE_FAILED",
+    path: targetPath,
+    context: { timeoutMs }
+  })
+});
+var atomicWrite = primitives.atomicWrite;
+var atomicReplaceWithWriter = primitives.atomicReplaceWithWriter;
+var ensureDir = primitives.ensureDir;
+var withFileLock = primitives.withFileLock;
+
 // src/utils/heap-watchdog.ts
 import * as fs from "node:fs";
 import * as fsp2 from "node:fs/promises";
@@ -770,7 +892,7 @@ function startHeapWatchdog(opts = {}) {
       dirReady = true;
     }
     await fsp2.appendFile(targetPath, `${line}
-`, "utf8");
+`, { encoding: "utf8", mode: 384 });
   });
   const drainWrites = async (firstLine) => {
     let line = firstLine;
@@ -956,6 +1078,72 @@ function useDaemonPerfDefaults() {
   daemonDefaults = true;
 }
 
+// src/coordination/mailbox-credential-store.ts
+import * as crypto from "node:crypto";
+var CREDENTIAL_STORE_FILE = "_mailbox_credentials.json";
+var MAX_CREDENTIAL_TTL = {
+  agent: 7 * 24 * 60 * 60 * 1e3,
+  // 7 days
+  operator: 24 * 60 * 60 * 1e3,
+  // 24 hours
+  service: 30 * 24 * 60 * 60 * 1e3
+  // 30 days
+};
+var ROTATION_OVERLAP_MS = 60 * 60 * 1e3;
+function createMailboxCredential(opts, now = Date.now()) {
+  const ttlMs = Math.min(opts.ttlMs, MAX_CREDENTIAL_TTL[opts.kind]);
+  const credentialId = crypto.randomUUID();
+  const secret = crypto.randomBytes(32).toString("hex");
+  const verifierKey = crypto.createHash("sha256").update(secret).digest();
+  const verifier = crypto.createHmac("sha256", verifierKey).update(credentialId).digest("hex");
+  return {
+    credential: {
+      credentialId,
+      verifier,
+      verifierAlgorithm: "hmac-sha256",
+      principalId: opts.principalId,
+      projectId: opts.projectId,
+      capabilities: opts.capabilities,
+      kind: opts.kind,
+      issuedAt: new Date(now).toISOString(),
+      expiresAt: new Date(now + ttlMs).toISOString(),
+      notBefore: opts.notBefore?.toISOString(),
+      status: "active",
+      statusChangedAt: new Date(now).toISOString(),
+      supersedes: opts.supersedes,
+      lastModifiedBy: opts.issuedBy
+    },
+    secret
+  };
+}
+function redactMailboxCredential(credential) {
+  const { verifier: _verifier, verifierAlgorithm: _algorithm, ...rest } = credential;
+  return rest;
+}
+function verifyMailboxCredential(credential, secret, now = Date.now()) {
+  if (credential === void 0) {
+    return { valid: false, reason: "credential not found" };
+  }
+  const rotationStillValid = credential.status === "rotated_out" && credential.rotationValidUntil !== void 0 && new Date(credential.rotationValidUntil).getTime() >= now;
+  if (credential.status !== "active" && !rotationStillValid) {
+    return { valid: false, reason: `credential is ${credential.status}`, credential };
+  }
+  if (new Date(credential.expiresAt).getTime() <= now) {
+    return { valid: false, reason: "credential expired", credential };
+  }
+  if (credential.notBefore !== void 0 && new Date(credential.notBefore).getTime() > now) {
+    return { valid: false, reason: "credential not yet valid", credential };
+  }
+  const verifierKey = crypto.createHash("sha256").update(secret).digest();
+  const expected = crypto.createHmac("sha256", verifierKey).update(credential.credentialId).digest("hex");
+  const actualBytes = Buffer.from(credential.verifier, "hex");
+  const expectedBytes = Buffer.from(expected, "hex");
+  if (actualBytes.length !== expectedBytes.length || !crypto.timingSafeEqual(actualBytes, expectedBytes)) {
+    return { valid: false, reason: "invalid secret" };
+  }
+  return { valid: true, credential };
+}
+
 // src/coordination/mailbox-events.ts
 var MailboxEventEmitter = class {
   listeners = /* @__PURE__ */ new Set();
@@ -984,7 +1172,7 @@ var MailboxEventEmitter = class {
 };
 
 // src/coordination/mailbox-project-server-endpoint.ts
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 import * as fs2 from "node:fs";
 import * as os2 from "node:os";
 import * as path4 from "node:path";
@@ -997,7 +1185,7 @@ import {
 } from "@wrongstack/persistence";
 
 // src/coordination/mailbox-project-server-protocol.ts
-var MAILBOX_PROJECT_SERVER_PROTOCOL_VERSION = 3;
+var MAILBOX_PROJECT_SERVER_PROTOCOL_VERSION = 4;
 var MAILBOX_PROJECT_SERVER_MAX_FRAME_CHARS = 16 * 1024 * 1024;
 var MAILBOX_SERVER_OPERATION_NAMES = {
   ping: true,
@@ -1113,7 +1301,7 @@ function normalizeLocalPath(value) {
   return process.platform === "win32" ? resolved.toLowerCase() : resolved;
 }
 function mailboxProjectServerKey(projectDir2) {
-  return createHash("sha256").update(normalizeLocalPath(projectDir2)).digest("hex").slice(0, 24);
+  return createHash2("sha256").update(normalizeLocalPath(projectDir2)).digest("hex").slice(0, 24);
 }
 function mailboxProjectServerEndpoint(projectDir2) {
   const key = mailboxProjectServerKey(projectDir2);
@@ -1141,19 +1329,6 @@ import { randomUUID as randomUUID2 } from "node:crypto";
 import * as fs4 from "node:fs";
 import * as path6 from "node:path";
 
-// src/coordination/mailbox-constants.ts
-var AGENT_STALE_MS = 6e4;
-var CLIENT_STALE_MS = 6e4;
-var HEARTBEAT_THROTTLE_MS = 5e3;
-var LINE_SEPARATOR = "\n";
-var AUTO_COMPACT_INTERVAL_MS = 3e5;
-var AUTO_COMPACT_READ_MAX_AGE_MS = 6e5;
-var AUTO_COMPACT_DEFAULT_TTL_MS = 864e5;
-var AUTO_COMPACT_TYPE_TTL_MS = {
-  status: 18e5
-  // 30 min
-};
-
 // src/coordination/global-mailbox-completion.ts
 function isMailboxMessageProjection(msg) {
   if (!("recipientState" in msg)) return false;
@@ -1171,6 +1346,19 @@ function isMessageCompletedForActor(msg, actorId) {
   return msg.completed === true;
 }
 
+// src/coordination/mailbox-constants.ts
+var AGENT_STALE_MS = 6e4;
+var CLIENT_STALE_MS = 6e4;
+var HEARTBEAT_THROTTLE_MS = 5e3;
+var LINE_SEPARATOR = "\n";
+var AUTO_COMPACT_INTERVAL_MS = 3e5;
+var AUTO_COMPACT_READ_MAX_AGE_MS = 6e5;
+var AUTO_COMPACT_DEFAULT_TTL_MS = 864e5;
+var AUTO_COMPACT_TYPE_TTL_MS = {
+  status: 18e5
+  // 30 min
+};
+
 // src/coordination/mailbox-types.ts
 function mailboxIdentityBase(agentId) {
   return agentId.split(/[@#]/, 1)[0].trim().toLowerCase();
@@ -1227,161 +1415,6 @@ function isMailboxReceiptRecordV2(value) {
   return true;
 }
 
-// src/coordination/mailbox-receipt-folding.ts
-function isFanOutRecipient(to) {
-  if (to === "*") return true;
-  if (to.startsWith("@session:")) return true;
-  return !to.includes("@") && !to.includes("#");
-}
-function materializeMessage(msg, msgReceipts) {
-  const recipientState = foldRecipientState(msg, msgReceipts);
-  const legacyGlobalCompletion = classifyLegacyCompletion(msg, msgReceipts);
-  return {
-    ...msg,
-    recipientState,
-    ...legacyGlobalCompletion ? { legacyGlobalCompletion: true } : {}
-  };
-}
-function foldRecipientState(msg, v2Receipts) {
-  const state = {};
-  for (const [actorId, readAt] of Object.entries(msg.readBy)) {
-    state[actorId] = { actorId, readAt };
-  }
-  if (msg.completed && msg.completedBy && !isFanOutRecipient(msg.to)) {
-    const existing = state[msg.completedBy] ?? { actorId: msg.completedBy };
-    state[msg.completedBy] = {
-      ...existing,
-      completedAt: msg.completedAt ?? msg.timestamp,
-      completedBy: msg.completedBy,
-      ...msg.outcome !== void 0 ? { outcome: msg.outcome } : {}
-    };
-  }
-  const sorted = [...v2Receipts].sort((a, b) => a.timestamp.localeCompare(b.timestamp));
-  for (const receipt of sorted) {
-    const actorId = receipt.actorId;
-    const existing = state[actorId] ?? { actorId };
-    const readAt = existing.readAt ?? (receipt.read === true ? receipt.timestamp : void 0);
-    let completedAt = existing.completedAt;
-    let completedBy = existing.completedBy;
-    if (receipt.completed === true) {
-      completedAt = receipt.timestamp;
-      completedBy = actorId;
-    } else if (receipt.completed === false) {
-      completedAt = void 0;
-      completedBy = void 0;
-    }
-    const outcome = receipt.outcome !== void 0 ? receipt.outcome : existing.outcome;
-    state[actorId] = { actorId, readAt, completedAt, completedBy, outcome };
-  }
-  return state;
-}
-function classifyLegacyCompletion(msg, v2Receipts) {
-  if (!msg.completed) return false;
-  if (v2Receipts.some((r) => r.completed === true)) return false;
-  return isFanOutRecipient(msg.to);
-}
-
-// src/coordination/mailbox-retention-state.ts
-function resolveMailboxRetentionState(message, agentStatuses) {
-  const projection = message;
-  if (projection.legacyGlobalCompletion) {
-    return { completed: true, completedAt: message.completedAt ?? message.timestamp };
-  }
-  const recipientState = projection.recipientState;
-  if (recipientState === void 0) {
-    return message.completed ? { completed: true, completedAt: message.completedAt ?? message.timestamp } : { completed: false };
-  }
-  const relevantRecipients = resolveRelevantRecipients(message, recipientState, agentStatuses);
-  if (relevantRecipients.length === 0) return { completed: false };
-  const completionTimes = [];
-  for (const actorId of relevantRecipients) {
-    const completedAt = recipientState[actorId]?.completedAt;
-    if (completedAt === void 0) return { completed: false };
-    completionTimes.push(completedAt);
-  }
-  return {
-    completed: true,
-    // Retention starts only after the last intended recipient completed.
-    completedAt: completionTimes.reduce((latest, time) => time > latest ? time : latest)
-  };
-}
-function projectMailboxCompletion(message, actorId, agentStatuses) {
-  const projection = message;
-  let state;
-  if (actorId === void 0) {
-    state = resolveMailboxRetentionState(message, agentStatuses);
-  } else if (projection.legacyGlobalCompletion) {
-    state = { completed: true, completedAt: message.completedAt ?? message.timestamp };
-  } else if (projection.recipientState !== void 0) {
-    const completedAt = projection.recipientState[actorId]?.completedAt;
-    state = completedAt === void 0 ? { completed: false } : { completed: true, completedAt };
-  } else {
-    state = message.completed ? { completed: true, completedAt: message.completedAt ?? message.timestamp } : { completed: false };
-  }
-  const result = {
-    ...projection,
-    completed: state.completed,
-    readBy: { ...message.readBy }
-  };
-  if (state.completedAt === void 0) delete result.completedAt;
-  else result.completedAt = state.completedAt;
-  return result;
-}
-function resolveRelevantRecipients(message, recipientState, agentStatuses) {
-  const statuses = agentStatuses ?? [];
-  const receiptActors = Object.keys(recipientState);
-  if (message.to === "*") {
-    if (statuses.length === 0) return [];
-    const registeredRecipients = statuses.filter((status) => isMailboxMessageVisibleTo(message, status.agentId, status.role)).map((status) => status.agentId);
-    return [.../* @__PURE__ */ new Set([...registeredRecipients, ...receiptActors])];
-  }
-  if (message.to.startsWith("@session:")) {
-    if (statuses.length === 0) return [];
-    const sessionId = message.to.slice("@session:".length);
-    const registeredRecipients = statuses.filter(
-      (status) => status.sessionId === sessionId && isMailboxMessageVisibleTo(message, status.agentId, status.role)
-    ).map((status) => status.agentId);
-    return [.../* @__PURE__ */ new Set([...registeredRecipients, ...receiptActors])];
-  }
-  if (message.to.includes("@")) return [message.to];
-  if (statuses.length === 0) return [];
-  const aliasRecipients = statuses.filter(
-    (status) => (status.role?.toLowerCase() === message.to.toLowerCase() || mailboxIdentityBase(status.agentId) === message.to.toLowerCase()) && isMailboxMessageVisibleTo(message, status.agentId, status.role)
-  ).map((status) => status.agentId);
-  return [.../* @__PURE__ */ new Set([...aliasRecipients, ...receiptActors])];
-}
-
-// src/coordination/mailbox-status-mappers.ts
-function mapRegisteredAgentsToStatuses(registry, now, staleMs) {
-  return Array.from(registry.values()).map((agent) => ({
-    agentId: agent.agentId,
-    name: agent.name,
-    role: agent.role,
-    sessionId: agent.sessionId,
-    status: agent.status,
-    currentTool: agent.currentTool,
-    currentTask: agent.currentTask,
-    iterations: agent.iterations,
-    toolCalls: agent.toolCalls,
-    lastActivityAt: agent.lastSeenAt,
-    lastSeenAt: agent.lastSeenAt,
-    online: now - new Date(agent.lastSeenAt).getTime() < staleMs,
-    pid: agent.pid,
-    source: agent.source
-  })).sort((a, b) => b.lastSeenAt.localeCompare(a.lastSeenAt));
-}
-function mapRegisteredClientsToStatuses(registry, now, staleMs) {
-  return Array.from(registry.values()).map((client) => ({
-    clientId: client.clientId,
-    name: client.name,
-    source: client.source,
-    sessionId: client.sessionId,
-    lastSeenAt: client.lastSeenAt,
-    online: now - new Date(client.lastSeenAt).getTime() < staleMs,
-    pid: client.pid
-  })).sort((a, b) => b.lastSeenAt.localeCompare(a.lastSeenAt));
-}
-
 // src/coordination/mailbox-message-codec.ts
 var MESSAGE_TYPES = /* @__PURE__ */ new Set([
   "note",
@@ -1544,6 +1577,161 @@ function applyAckToMessage(msg, ack) {
   }
 }
 
+// src/coordination/mailbox-receipt-folding.ts
+function isFanOutRecipient(to) {
+  if (to === "*") return true;
+  if (to.startsWith("@session:")) return true;
+  return !to.includes("@") && !to.includes("#");
+}
+function materializeMessage(msg, msgReceipts) {
+  const recipientState = foldRecipientState(msg, msgReceipts);
+  const legacyGlobalCompletion = classifyLegacyCompletion(msg, msgReceipts);
+  return {
+    ...msg,
+    recipientState,
+    ...legacyGlobalCompletion ? { legacyGlobalCompletion: true } : {}
+  };
+}
+function foldRecipientState(msg, v2Receipts) {
+  const state = {};
+  for (const [actorId, readAt] of Object.entries(msg.readBy)) {
+    state[actorId] = { actorId, readAt };
+  }
+  if (msg.completed && msg.completedBy && !isFanOutRecipient(msg.to)) {
+    const existing = state[msg.completedBy] ?? { actorId: msg.completedBy };
+    state[msg.completedBy] = {
+      ...existing,
+      completedAt: msg.completedAt ?? msg.timestamp,
+      completedBy: msg.completedBy,
+      ...msg.outcome !== void 0 ? { outcome: msg.outcome } : {}
+    };
+  }
+  const sorted = [...v2Receipts].sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+  for (const receipt of sorted) {
+    const actorId = receipt.actorId;
+    const existing = state[actorId] ?? { actorId };
+    const readAt = existing.readAt ?? (receipt.read === true ? receipt.timestamp : void 0);
+    let completedAt = existing.completedAt;
+    let completedBy = existing.completedBy;
+    if (receipt.completed === true) {
+      completedAt = receipt.timestamp;
+      completedBy = actorId;
+    } else if (receipt.completed === false) {
+      completedAt = void 0;
+      completedBy = void 0;
+    }
+    const outcome = receipt.outcome !== void 0 ? receipt.outcome : existing.outcome;
+    state[actorId] = { actorId, readAt, completedAt, completedBy, outcome };
+  }
+  return state;
+}
+function classifyLegacyCompletion(msg, v2Receipts) {
+  if (!msg.completed) return false;
+  if (v2Receipts.some((r) => r.completed === true)) return false;
+  return isFanOutRecipient(msg.to);
+}
+
+// src/coordination/mailbox-retention-state.ts
+function resolveMailboxRetentionState(message, agentStatuses) {
+  const projection = message;
+  if (projection.legacyGlobalCompletion) {
+    return { completed: true, completedAt: message.completedAt ?? message.timestamp };
+  }
+  const recipientState = projection.recipientState;
+  if (recipientState === void 0) {
+    return message.completed ? { completed: true, completedAt: message.completedAt ?? message.timestamp } : { completed: false };
+  }
+  const relevantRecipients = resolveRelevantRecipients(message, recipientState, agentStatuses);
+  if (relevantRecipients.length === 0) return { completed: false };
+  const completionTimes = [];
+  for (const actorId of relevantRecipients) {
+    const completedAt = recipientState[actorId]?.completedAt;
+    if (completedAt === void 0) return { completed: false };
+    completionTimes.push(completedAt);
+  }
+  return {
+    completed: true,
+    // Retention starts only after the last intended recipient completed.
+    completedAt: completionTimes.reduce((latest, time) => time > latest ? time : latest)
+  };
+}
+function projectMailboxCompletion(message, actorId, agentStatuses) {
+  const projection = message;
+  let state;
+  if (actorId === void 0) {
+    state = resolveMailboxRetentionState(message, agentStatuses);
+  } else if (projection.legacyGlobalCompletion) {
+    state = { completed: true, completedAt: message.completedAt ?? message.timestamp };
+  } else if (projection.recipientState !== void 0) {
+    const completedAt = projection.recipientState[actorId]?.completedAt;
+    state = completedAt === void 0 ? { completed: false } : { completed: true, completedAt };
+  } else {
+    state = message.completed ? { completed: true, completedAt: message.completedAt ?? message.timestamp } : { completed: false };
+  }
+  const result = {
+    ...projection,
+    completed: state.completed,
+    readBy: { ...message.readBy }
+  };
+  if (state.completedAt === void 0) delete result.completedAt;
+  else result.completedAt = state.completedAt;
+  return result;
+}
+function resolveRelevantRecipients(message, recipientState, agentStatuses) {
+  const statuses = agentStatuses ?? [];
+  const receiptActors = Object.keys(recipientState);
+  if (message.to === "*") {
+    if (statuses.length === 0) return [];
+    const registeredRecipients = statuses.filter((status) => isMailboxMessageVisibleTo(message, status.agentId, status.role)).map((status) => status.agentId);
+    return [.../* @__PURE__ */ new Set([...registeredRecipients, ...receiptActors])];
+  }
+  if (message.to.startsWith("@session:")) {
+    if (statuses.length === 0) return [];
+    const sessionId = message.to.slice("@session:".length);
+    const registeredRecipients = statuses.filter(
+      (status) => status.sessionId === sessionId && isMailboxMessageVisibleTo(message, status.agentId, status.role)
+    ).map((status) => status.agentId);
+    return [.../* @__PURE__ */ new Set([...registeredRecipients, ...receiptActors])];
+  }
+  if (message.to.includes("@")) return [message.to];
+  if (statuses.length === 0) return [];
+  const aliasRecipients = statuses.filter(
+    (status) => (status.role?.toLowerCase() === message.to.toLowerCase() || mailboxIdentityBase(status.agentId) === message.to.toLowerCase()) && isMailboxMessageVisibleTo(message, status.agentId, status.role)
+  ).map((status) => status.agentId);
+  return [.../* @__PURE__ */ new Set([...aliasRecipients, ...receiptActors])];
+}
+
+// src/coordination/mailbox-status-mappers.ts
+function mapRegisteredAgentsToStatuses(registry, now, staleMs) {
+  return Array.from(registry.values()).map((agent) => ({
+    agentId: agent.agentId,
+    name: agent.name,
+    role: agent.role,
+    sessionId: agent.sessionId,
+    status: agent.status,
+    currentTool: agent.currentTool,
+    currentTask: agent.currentTask,
+    iterations: agent.iterations,
+    toolCalls: agent.toolCalls,
+    lastActivityAt: agent.lastSeenAt,
+    lastSeenAt: agent.lastSeenAt,
+    online: now - new Date(agent.lastSeenAt).getTime() < staleMs,
+    pid: agent.pid,
+    source: agent.source
+  })).sort((a, b) => b.lastSeenAt.localeCompare(a.lastSeenAt));
+}
+function mapRegisteredClientsToStatuses(registry, now, staleMs) {
+  return Array.from(registry.values()).map((client) => ({
+    clientId: client.clientId,
+    name: client.name,
+    source: client.source,
+    sessionId: client.sessionId,
+    lastSeenAt: client.lastSeenAt,
+    online: now - new Date(client.lastSeenAt).getTime() < staleMs,
+    pid: client.pid
+  })).sort((a, b) => b.lastSeenAt.localeCompare(a.lastSeenAt));
+}
+
 // src/coordination/sqlite-mailbox-compaction.ts
 async function purgeStale(ctx, options) {
   const completedMaxAgeMs = options?.completedMaxAgeMs ?? 864e5;
@@ -1627,67 +1815,63 @@ async function autoCompact(ctx, options) {
   };
 }
 
-// src/coordination/mailbox-credential-store.ts
-import * as crypto from "node:crypto";
-var CREDENTIAL_STORE_FILE = "_mailbox_credentials.json";
-var MAX_CREDENTIAL_TTL = {
-  agent: 7 * 24 * 60 * 60 * 1e3,
-  // 7 days
-  operator: 24 * 60 * 60 * 1e3,
-  // 24 hours
-  service: 30 * 24 * 60 * 60 * 1e3
-  // 30 days
-};
-var ROTATION_OVERLAP_MS = 60 * 60 * 1e3;
-function createMailboxCredential(opts, now = Date.now()) {
-  const ttlMs = Math.min(opts.ttlMs, MAX_CREDENTIAL_TTL[opts.kind]);
-  const credentialId = crypto.randomUUID();
-  const secret = crypto.randomBytes(32).toString("hex");
-  const verifierKey = crypto.createHash("sha256").update(secret).digest();
-  const verifier = crypto.createHmac("sha256", verifierKey).update(credentialId).digest("hex");
-  return {
-    credential: {
-      credentialId,
-      verifier,
-      verifierAlgorithm: "hmac-sha256",
-      principalId: opts.principalId,
-      projectId: opts.projectId,
-      capabilities: opts.capabilities,
-      kind: opts.kind,
-      issuedAt: new Date(now).toISOString(),
-      expiresAt: new Date(now + ttlMs).toISOString(),
-      notBefore: opts.notBefore?.toISOString(),
-      status: "active",
-      statusChangedAt: new Date(now).toISOString(),
-      supersedes: opts.supersedes,
-      lastModifiedBy: opts.issuedBy
-    },
-    secret
-  };
-}
-function verifyMailboxCredential(credential, secret, now = Date.now()) {
-  if (credential === void 0) {
-    return { valid: false, reason: "credential not found" };
-  }
-  const rotationStillValid = credential.status === "rotated_out" && credential.rotationValidUntil !== void 0 && new Date(credential.rotationValidUntil).getTime() >= now;
-  if (credential.status !== "active" && !rotationStillValid) {
-    return { valid: false, reason: `credential is ${credential.status}`, credential };
+// src/coordination/mailbox-credential-throttle.ts
+var CREDENTIAL_VERIFY_MAX_FAILURES = 10;
+var CREDENTIAL_VERIFY_WINDOW_MS = 6e4;
+var CREDENTIAL_VERIFY_COOLDOWN_MS = 6e4;
+var MAX_TRACKED_IDS = 4096;
+var CredentialVerifyThrottle = class {
+  constructor(maxFailures = CREDENTIAL_VERIFY_MAX_FAILURES, windowMs = CREDENTIAL_VERIFY_WINDOW_MS, cooldownMs = CREDENTIAL_VERIFY_COOLDOWN_MS) {
+    this.maxFailures = maxFailures;
+    this.windowMs = windowMs;
+    this.cooldownMs = cooldownMs;
+  }
+  maxFailures;
+  windowMs;
+  cooldownMs;
+  records = /* @__PURE__ */ new Map();
+  /** Is this credential id allowed another attempt right now? */
+  check(credentialId, now = Date.now()) {
+    const record = this.records.get(credentialId);
+    if (record === void 0) return { allowed: true, retryAfterMs: 0 };
+    if (record.blockedUntil > now) {
+      return { allowed: false, retryAfterMs: record.blockedUntil - now };
+    }
+    return { allowed: true, retryAfterMs: 0 };
+  }
+  /** Record a failed verification. Starts the cooldown once the limit is hit. */
+  recordFailure(credentialId, now = Date.now()) {
+    const record = this.records.get(credentialId);
+    if (record === void 0 || now - record.windowStartedAt > this.windowMs) {
+      this.evictIfFull();
+      this.records.set(credentialId, { failures: 1, windowStartedAt: now, blockedUntil: 0 });
+      return;
+    }
+    record.failures += 1;
+    if (record.failures >= this.maxFailures) {
+      record.blockedUntil = now + this.cooldownMs;
+      record.failures = 0;
+      record.windowStartedAt = now;
+    }
   }
-  if (new Date(credential.expiresAt).getTime() <= now) {
-    return { valid: false, reason: "credential expired", credential };
+  /**
+   * Clear the counter after a successful verification. A legitimate holder who
+   * fluffed a few attempts is not left in a cooldown they cannot exit.
+   */
+  recordSuccess(credentialId) {
+    this.records.delete(credentialId);
   }
-  if (credential.notBefore !== void 0 && new Date(credential.notBefore).getTime() > now) {
-    return { valid: false, reason: "credential not yet valid", credential };
+  /** Test seam. */
+  reset() {
+    this.records.clear();
   }
-  const verifierKey = crypto.createHash("sha256").update(secret).digest();
-  const expected = crypto.createHmac("sha256", verifierKey).update(credential.credentialId).digest("hex");
-  const actualBytes = Buffer.from(credential.verifier, "hex");
-  const expectedBytes = Buffer.from(expected, "hex");
-  if (actualBytes.length !== expectedBytes.length || !crypto.timingSafeEqual(actualBytes, expectedBytes)) {
-    return { valid: false, reason: "invalid secret", credential };
+  evictIfFull() {
+    if (this.records.size < MAX_TRACKED_IDS) return;
+    const oldest = this.records.keys().next();
+    if (!oldest.done) this.records.delete(oldest.value);
   }
-  return { valid: true, credential };
-}
+};
+var credentialVerifyThrottle = new CredentialVerifyThrottle();
 
 // src/coordination/sqlite-mailbox-rows.ts
 var MALFORMED_TIMESTAMP = "last_seen_at NOT GLOB '[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]T*'";
@@ -1967,7 +2151,17 @@ function credentialIssue(db, transaction, options) {
   return issued;
 }
 function credentialVerify(db, credentialId, secret) {
-  return verifyMailboxCredential(credentialGet(db, credentialId) ?? void 0, secret);
+  const decision = credentialVerifyThrottle.check(credentialId);
+  if (!decision.allowed) {
+    return {
+      valid: false,
+      reason: `too many failed verification attempts \u2014 retry in ${Math.ceil(decision.retryAfterMs / 1e3)}s`
+    };
+  }
+  const result = verifyMailboxCredential(credentialGet(db, credentialId) ?? void 0, secret);
+  if (result.valid) credentialVerifyThrottle.recordSuccess(credentialId);
+  else credentialVerifyThrottle.recordFailure(credentialId);
+  return result;
 }
 function credentialRevoke(db, credentialId, reason, by) {
   const credential = credentialGet(db, credentialId);
@@ -2482,7 +2676,41 @@ var SqliteMailbox = class {
       where.push("reply_to = ?");
       params.push(query.replyTo);
     }
-    const canPreLimit = query.unreadBy === void 0 && !query.incompleteOnly;
+    if (query.unreadBy !== void 0) {
+      if (!isMailboxLeader(query.unreadBy, query.readerRole)) {
+        where.push("COALESCE(json_extract(data, '$.audience'), 'all') <> 'leaders'");
+      }
+      if (!query.incompleteOnly) {
+        where.push(`NOT EXISTS (
+          SELECT 1 FROM message_receipts AS unread_receipt
+          WHERE unread_receipt.message_id = messages.id
+            AND unread_receipt.actor_id = ?
+            AND unread_receipt.read_at IS NOT NULL
+        )`);
+        params.push(query.unreadBy);
+        where.push(`NOT EXISTS (
+          SELECT 1 FROM json_each(json_extract(data, '$.readBy')) AS legacy_read
+          WHERE legacy_read.key = ?
+        )`);
+        params.push(query.unreadBy);
+      } else {
+        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(query.unreadBy);
+        where.push(`(
+          completed = 0 OR EXISTS (
+            SELECT 1 FROM message_receipts AS any_receipt
+            WHERE any_receipt.message_id = messages.id
+          )
+        )`);
+      }
+    }
+    const canPreLimit = !query.incompleteOnly || query.unreadBy !== void 0;
     let sql = "SELECT id, data, legacy_global_completion FROM messages";
     if (where.length > 0) sql += ` WHERE ${where.join(" AND ")}`;
     sql += " ORDER BY timestamp DESC, rowid DESC";
@@ -2494,10 +2722,14 @@ var SqliteMailbox = class {
     const messages = this.materializeMessageRows(rows).filter((message) => {
       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) return false;
-      if (query.unreadBy !== void 0 && !isMailboxMessageVisibleTo(message, query.unreadBy, query.readerRole)) return false;
-      if (!query.incompleteOnly && query.unreadBy !== void 0 && query.unreadBy in message.readBy) return false;
-      if (query.incompleteOnly && (query.unreadBy === void 0 ? projectMailboxCompletion(message, void 0, statuses).completed : isMessageCompletedForActor(message, query.unreadBy))) return false;
+      if (query.sessionId !== void 0 && message.senderSessionId !== query.sessionId)
+        return false;
+      if (query.unreadBy !== void 0 && !isMailboxMessageVisibleTo(message, query.unreadBy, query.readerRole))
+        return false;
+      if (!query.incompleteOnly && query.unreadBy !== void 0 && query.unreadBy in message.readBy)
+        return false;
+      if (query.incompleteOnly && (query.unreadBy === void 0 ? projectMailboxCompletion(message, void 0, statuses).completed : isMessageCompletedForActor(message, query.unreadBy)))
+        return false;
       if (type !== void 0 && message.type !== type) return false;
       if (priorityRank[message.priority] < minimumRank) return false;
       if (query.since !== void 0 && message.timestamp <= query.since) return false;
@@ -2889,6 +3121,11 @@ var stopMemoryWatchdog = startSharedHeapWatchdog({
     pendingRequests
   })
 });
+var authToken = randomBytes2(16).toString("hex");
+var markMetadataWritten;
+var metadataWritten = new Promise((resolve5) => {
+  markMetadataWritten = resolve5;
+});
 var serverInfo = {
   protocolVersion: MAILBOX_PROJECT_SERVER_PROTOCOL_VERSION,
   pid: process.pid,
@@ -3032,7 +3269,12 @@ async function dispatch(op, rawArgs) {
     }
     case "credentialVerify": {
       const args = rawArgs;
-      return activeMailbox.credentialVerify(args.credentialId, args.secret);
+      return Promise.resolve(activeMailbox.credentialVerify(args.credentialId, args.secret)).then(
+        (result) => result.valid ? {
+          ...result,
+          credential: result.credential ? redactMailboxCredential(result.credential) : void 0
+        } : { valid: false, reason: result.reason }
+      );
     }
     case "credentialRevoke": {
       const args = rawArgs;
@@ -3047,16 +3289,33 @@ async function dispatch(op, rawArgs) {
     }
     case "credentialGet": {
       const args = rawArgs;
-      return activeMailbox.credentialGet(args.credentialId);
+      return Promise.resolve(activeMailbox.credentialGet(args.credentialId)).then(
+        (credential) => credential ? redactMailboxCredential(credential) : null
+      );
     }
     case "credentialList":
-      return activeMailbox.credentialList();
+      return Promise.resolve(activeMailbox.credentialList()).then(
+        (credentials) => credentials.map(redactMailboxCredential)
+      );
     case "credentialStatusCounts":
       return activeMailbox.credentialStatusCounts();
   }
 }
+function checkAuthToken(state, message) {
+  if (message.type === "heartbeat") return true;
+  if (message.authToken === authToken) return true;
+  send(state, {
+    type: "response",
+    id: message.id,
+    ok: false,
+    error: "Mailbox IPC request rejected: missing or invalid authToken. Reconnect to refresh metadata (.mailbox-server.json#authToken).",
+    errorName: "UnauthorizedMailboxRequest"
+  });
+  return false;
+}
 function handleMessage(state, message) {
   state.lastSeenAt = Date.now();
+  if (!checkAuthToken(state, message)) return;
   if (message.type === "heartbeat") return;
   if (message.type === "shutdown") {
     send(state, {
@@ -3124,18 +3383,9 @@ function scheduleIdleStop() {
 }
 async function writeMetadata() {
   await fsPromises.mkdir(projectDir, { recursive: true });
-  const temporary = `${metadataPath}.${process.pid}.tmp`;
-  await fsPromises.writeFile(temporary, `${JSON.stringify(serverStatus(), null, 2)}
-`, {
-    encoding: "utf8",
-    mode: 384
-  });
-  try {
-    await fsPromises.rename(temporary, metadataPath);
-  } catch {
-    await fsPromises.rm(metadataPath, { force: true });
-    await fsPromises.rename(temporary, metadataPath);
-  }
+  const metadata = { ...serverStatus(), authToken };
+  await atomicWrite(metadataPath, `${JSON.stringify(metadata, null, 2)}
+`, { mode: 384 });
 }
 async function removeOwnedMetadata() {
   try {
@@ -3151,6 +3401,7 @@ async function stop(_reason) {
   idleTimer = void 0;
   clearInterval(leaseSweep);
   stopAutoCompact?.();
+  await removeOwnedMetadata();
   const serverClosed = new Promise((resolve5) => server.close(() => resolve5()));
   for (const state of clients) state.socket.end();
   const forceCloseTimer = setTimeout(() => {
@@ -3164,7 +3415,6 @@ async function stop(_reason) {
   await mailbox?.close().catch(() => {
   });
   mailbox = void 0;
-  await removeOwnedMetadata();
   if (process.platform !== "win32") {
     await fsPromises.rm(endpoint, { force: true }).catch(() => {
     });
@@ -3182,7 +3432,9 @@ var server = net.createServer((socket) => {
   socket.setEncoding("utf8");
   const state = { socket, buffer: "", lastSeenAt: Date.now() };
   clients.add(state);
-  send(state, { type: "hello", ...serverInfo });
+  void metadataWritten.then(() => {
+    if (!socket.destroyed) send(state, { type: "hello", ...serverInfo });
+  });
   socket.on("data", (chunk) => onData(state, chunk));
   socket.on("error", () => {
   });
@@ -3244,7 +3496,10 @@ server.on("listening", () => {
     return;
   }
   stopAutoCompact = mailbox.startAutoCompactTimer();
-  void writeMetadata().then(() => scheduleIdleStop()).catch(() => {
+  void writeMetadata().then(() => {
+    markMetadataWritten?.();
+    scheduleIdleStop();
+  }).catch(() => {
     void stop("metadata-write-failed").finally(() => {
       process.exitCode = 1;
     });