@wrongstack/core 0.284.1 → 0.286.0

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

@@ -0,0 +1,55 @@
+/**
+ * mailbox-hooks — Tool-execution hooks for mailbox integration.
+ *
+ * 1. Before each tool call, checks the mailbox for unread high-priority
+ *    steer messages and emits a `mailbox.unread_count` event.
+ * 2. After each tool call, updates the agent heartbeat so other agents
+ *    know this one is still alive.
+ *
+ * This gives near-real-time mailbox checking (every tool call, not just
+ * iteration boundaries) and powers the "new mail" badge in the WebUI/TUI.
+ *
+ * @module mailbox-hooks
+ */
+import type { Mailbox } from '../coordination/mailbox-types.js';
+export interface MailboxHooksOptions {
+    /** The mailbox instance. */
+    mailbox: Mailbox;
+    /** Agent id for read-receipt and unread-check purposes. */
+    agentId: string;
+    /** Whether to emit new-mail notifications. Default: true. */
+    notifyNewMail?: boolean | undefined;
+    /** Whether to update heartbeat. Default: true. */
+    heartbeat?: boolean | undefined;
+}
+/**
+ * Create a pair of hooks for the tool execution pipeline.
+ *
+ * Usage:
+ *   const hooks = createMailboxHooks({ mailbox, agentId });
+ *   // In the tool executor, before each tool call:
+ *   await hooks.beforeTool({ events });
+ *   // After each tool call:
+ *   await hooks.afterTool();
+ *
+ * The `beforeTool` hook checks for unread messages and emits
+ * `mailbox.unread_count` events. The `afterTool` hook updates
+ * the agent heartbeat.
+ */
+export declare function createMailboxHooks(opts: MailboxHooksOptions): {
+    /**
+     * Call before each tool execution. Checks mailbox and emits events.
+     * @param events — EventBus-like object with emit method.
+     */
+    beforeTool(events: {
+        emit: (type: string, payload: unknown) => void;
+    }): Promise<void>;
+    /**
+     * Call after each tool execution. Updates heartbeat and optionally
+     * current tool status.
+     */
+    afterTool(toolName?: string): Promise<void>;
+    /** Reset the cached unread count (e.g., after the agent checks manually). */
+    reset(): void;
+};
+//# sourceMappingURL=mailbox-hooks.d.ts.map

package/dist/coordination/mailbox-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox-hooks.d.ts","sourceRoot":"","sources":["../../src/coordination/mailbox-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,kCAAkC,CAAC;AAEhE,MAAM,WAAW,mBAAmB;IAClC,4BAA4B;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACpC,kDAAkD;IAClD,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACjC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,mBAAmB;IAMxD;;;OAGG;IACG,UAAU,SAAS;QAAE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAc3F;;;OAGG;IACG,SAAS,YAAY,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAajD,6EAA6E;IAC7E,KAAK;EAIR"}

package/dist/coordination/mailbox-message-codec.d.ts

@@ -0,0 +1,8 @@
+import type { MailboxMessage, MailboxMessageType } from './mailbox-types.js';
+/** Normalize message types emitted by pre-union mailbox builds. */
+export declare function normalizeMailboxMessageType(value: unknown): MailboxMessageType;
+/** Parse, migrate, and structurally validate one persisted mailbox message. */
+export declare function parseMailboxMessage(value: unknown): MailboxMessage;
+/** Parse one JSONL line and validate the decoded mailbox message. */
+export declare function parseMailboxMessageLine(line: string): MailboxMessage;
+//# sourceMappingURL=mailbox-message-codec.d.ts.map

package/dist/coordination/mailbox-message-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox-message-codec.d.ts","sourceRoot":"","sources":["../../src/coordination/mailbox-message-codec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAGnB,MAAM,oBAAoB,CAAC;AA4D5B,mEAAmE;AACnE,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAE9E;AA2DD,+EAA+E;AAC/E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CA+BlE;AAED,qEAAqE;AACrE,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAEpE"}

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

@@ -0,0 +1,75 @@
+/**
+ * mailbox-tool — Tool that exposes the inter-agent mailbox to agents.
+ *
+ * Sub-commands: check, send, ack, query, status, online, unread
+ *
+ * Uses the project-level GlobalMailbox for cross-session communication.
+ * Agents are auto-registered on first use with heartbeat tracking.
+ * Read receipts track who read each message and when.
+ *
+ * @module mailbox-tool
+ */
+import type { EventBus } from '../kernel/events.js';
+import type { Context } from '../core/context.js';
+import type { Tool } from '../types/tool.js';
+import type { Mailbox } from './mailbox-types.js';
+export type MailboxResolver = (ctx: Context) => Mailbox;
+export interface MailboxToolOptions {
+    /**
+     * How to obtain a Mailbox instance given the execution Context.
+     * Default: derives project dir from ctx and creates a GlobalMailbox.
+     */
+    resolveMailbox?: MailboxResolver | undefined;
+    /**
+     * Agent id of the caller — used as default "from" on send.
+     * Default: 'leader' for the main agent, or derived from ctx.meta.
+     */
+    agentId?: string | undefined;
+    /** Session id for cross-session communication. Default: derived from ctx. */
+    sessionId?: string | undefined;
+    /**
+     * Project directory where the mailbox is stored.
+     * Default: derived from ctx.projectRoot (may differ from wpaths.projectDir).
+     * For correct cross-session sharing, pass `wpaths.projectDir` from the caller.
+     */
+    projectDir?: string | undefined;
+    /**
+     * EventBus for emitting mailbox.agent_registered and mailbox.agent_heartbeat
+     * events so the TUI/WebUI can update the online agent count in the status bar.
+     * When omitted, events are not emitted and the status bar count stays at 0.
+     */
+    events?: EventBus | undefined;
+}
+export declare function defaultResolveProjectDir(ctx: Context): string;
+/**
+ * Compact, deterministic tag for a session id — 8 hex chars of its sha256.
+ * Session ids are date-sharded paths ("2026-06-11/sess_<ULID>");
+ * the tag keeps mailbox identities short, filesystem-safe, and stable for
+ * the lifetime of the session (including across process restarts/resumes).
+ */
+export declare function mailboxSessionTag(sessionId: string): string;
+/**
+ * Resolve the caller's mailbox identity from the execution Context.
+ *
+ * Shared by the `mailbox` power-tool, the thin `mail_send`/`mail_inbox`
+ * tools, the agent-loop checker, and the /mailbox slash command so every
+ * surface agrees on who is talking:
+ * - base id: ctx.meta.agentId → ctx.agentId field (subagents) → fallback
+ * - unique id: `<base>@<sessionTag>` — SESSION-bound, not pid-bound. Every
+ *   session has its own id, so two leader sessions on the same project
+ *   never collide (pids can be recycled by the OS), and a resumed session
+ *   keeps its identity: read state survives a restart instead of
+ *   re-flooding old broadcasts. Derived LIVE from ctx.session.id so an
+ *   in-process session swap (resume / session.new / project switch) moves
+ *   the identity with it. `ctx.meta.globalAgentId` remains an explicit
+ *   override for hosts that manage identity themselves.
+ */
+export declare function resolveMailboxIdentity(ctx: Context, fallbackBase?: string): {
+    baseId: string;
+    callerId: string;
+    name: string;
+    role?: string | undefined;
+    sessionId: string;
+};
+export declare function makeMailboxTool(opts?: MailboxToolOptions): Tool;
+//# sourceMappingURL=mailbox-tool.d.ts.map

package/dist/coordination/mailbox-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox-tool.d.ts","sourceRoot":"","sources":["../../src/coordination/mailbox-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAI7C,OAAO,KAAK,EAAE,OAAO,EAAsC,MAAM,oBAAoB,CAAC;AAEtF,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;AAExD,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,cAAc,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IAC7C;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC;;;;OAIG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;CAC/B;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAE7D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,OAAO,EACZ,YAAY,SAAW,GACtB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAalG;AAED,wBAAgB,eAAe,CAAC,IAAI,GAAE,kBAAuB,GAAG,IAAI,CAqGnE"}

package/dist/{mailbox-types-BGZWrYTJ.d.ts → coordination/mailbox-types.d.ts}

@@ -24,15 +24,15 @@
  *
  * @module mailbox-types
  */
-type MailboxMessageType = 'note' | 'ask' | 'assign' | 'steer' | 'btw' | 'broadcast' | 'status' | 'result' | 'review' | 'control';
+export type MailboxMessageType = 'note' | 'ask' | 'assign' | 'steer' | 'btw' | 'broadcast' | 'status' | 'result' | 'review' | 'control';
 /**
  * Per-recipient read status. `readBy` maps agentId → ISO8601 timestamp of
  * when that agent first read the message. An empty map means unread by all.
  */
-interface ReadReceipts {
+export interface ReadReceipts {
     [agentId: string]: string;
 }
-interface MailboxMessage {
+export interface MailboxMessage {
     /** Unique message id (UUID). */
     id: string;
     /** Sender agent id. */
@@ -79,8 +79,16 @@ interface MailboxMessage {
     taskContext?: MailboxTaskContext | undefined;
     /** Session id of the sender. Enables cross-session communication. */
     senderSessionId?: string | undefined;
+    /**
+     * ISO8601 — when the message expires. Set at send time from `ttlMs`
+     * (default: 24h via AUTO_COMPACT_DEFAULT_TTL_MS). The auto-compaction
+     * sweep removes messages whose `expiresAt` is in the past. When
+     * undefined, the compaction sweep uses the default TTL from the
+     * caller's options.
+     */
+    expiresAt?: string | undefined;
 }
-interface MailboxTaskContext {
+export interface MailboxTaskContext {
     /** The role that should handle this task (e.g. "tech-stack", "audit-log"). */
     agentRole?: string | undefined;
     /** Human-readable agent name (e.g. "Tesla (Executor)"). */
@@ -90,7 +98,7 @@ interface MailboxTaskContext {
     /** Current task status. */
     status?: 'pending' | 'in_progress' | 'completed' | 'failed' | undefined;
 }
-interface RegisteredAgent {
+export interface RegisteredAgent {
     /** Unique agent id. */
     agentId: string;
     /** Session id this agent belongs to. */
@@ -118,7 +126,7 @@ interface RegisteredAgent {
     /** Where the agent is running (e.g. "cli", "webui"). */
     source?: 'cli' | 'webui' | 'mcp' | 'acp' | 'http' | undefined;
 }
-interface MailboxAgentStatus {
+export interface MailboxAgentStatus {
     /** Agent id. */
     agentId: string;
     /** Human-readable name. */
@@ -148,7 +156,7 @@ interface MailboxAgentStatus {
     /** Source. */
     source?: 'cli' | 'webui' | 'mcp' | 'acp' | 'http' | undefined;
 }
-interface MailboxQuery {
+export interface MailboxQuery {
     /** Filter by recipient agent id. */
     to?: string | undefined;
     /** Filter by sender agent id. */
@@ -180,8 +188,8 @@ interface MailboxQuery {
  * "all" recipient would otherwise be deliverable to nobody. The word is
  * therefore RESERVED: no agent may register under the base id "all".
  */
-declare function normalizeRecipient(to: string): string;
-interface MailboxSendInput {
+export declare function normalizeRecipient(to: string): string;
+export interface MailboxSendInput {
     /** Sender agent id. */
     from: string;
     /** Recipient agent id, '*' for broadcast (alias: "all"). */
@@ -198,8 +206,14 @@ interface MailboxSendInput {
     replyTo?: string | undefined;
     /** Task context for assign-type messages. */
     taskContext?: MailboxTaskContext | undefined;
+    /**
+     * Time-to-live in milliseconds. When set, the message's `expiresAt` is
+     * computed as `now + ttlMs` at send time. The auto-compaction sweep
+     * removes expired messages. Default: none (use compaction sweep default).
+     */
+    ttlMs?: number | undefined;
 }
-interface MailboxAckInput {
+export interface MailboxAckInput {
     /** Message id to acknowledge. */
     messageId: string;
     /** Agent id of who is reading/acking. */
@@ -219,11 +233,11 @@ interface MailboxAckInput {
  * once (the common case in the mailbox loop) — it collapses N full-file
  * rewrites into one.
  */
-interface MailboxAckBatchInput {
+export interface MailboxAckBatchInput {
     /** Ack entries to apply. */
     acks: MailboxAckInput[];
 }
-interface AgentRegistrationInput {
+export interface AgentRegistrationInput {
     agentId: string;
     sessionId: string;
     name: string;
@@ -231,8 +245,24 @@ interface AgentRegistrationInput {
     pid: number;
     source?: 'cli' | 'webui' | 'mcp' | 'acp' | 'http' | undefined;
 }
-type ClientSource = 'repl' | 'tui' | 'webui' | 'http';
-interface ClientStatus {
+export type ClientSource = 'repl' | 'tui' | 'webui' | 'http';
+export interface RegisteredClient {
+    /** Unique client id. */
+    clientId: string;
+    /** Session/project context id. */
+    sessionId: string;
+    /** Human-readable name (e.g. "TUI [main]", "WebUI [chrome]"). */
+    name: string;
+    /** Client type. */
+    source: ClientSource;
+    /** ISO8601 — registered at. */
+    registeredAt: string;
+    /** ISO8601 — last heartbeat. */
+    lastSeenAt: string;
+    /** Which process. */
+    pid: number;
+}
+export interface ClientStatus {
     /** Client id. */
     clientId: string;
     /** Human-readable name. */
@@ -248,19 +278,19 @@ interface ClientStatus {
     /** Which process. */
     pid: number;
 }
-interface ClientRegistrationInput {
+export interface ClientRegistrationInput {
     clientId: string;
     sessionId: string;
     name: string;
     source: ClientSource;
     pid: number;
 }
-interface ClientHeartbeatInput {
+export interface ClientHeartbeatInput {
     clientId: string;
     /** Active session id for this client. When present, updates the registry entry. */
     sessionId?: string | undefined;
 }
-interface AgentHeartbeatInput {
+export interface AgentHeartbeatInput {
     agentId: string;
     status?: RegisteredAgent['status'] | undefined;
     currentTool?: string | undefined;
@@ -268,7 +298,7 @@ interface AgentHeartbeatInput {
     iterations?: number | undefined;
     toolCalls?: number | undefined;
 }
-interface PurgeOptions {
+export interface PurgeOptions {
     /**
      * Purge completed messages older than this many milliseconds.
      * Default: 1 day (86_400_000 ms)
@@ -280,7 +310,7 @@ interface PurgeOptions {
      */
     incompleteMaxAgeMs?: number | undefined;
 }
-interface PurgeResult {
+export interface PurgeResult {
     /** Messages removed because they were completed and too old. */
     completedPurged: number;
     /** Messages removed because they were incomplete and too old. */
@@ -290,7 +320,53 @@ interface PurgeResult {
     /** Messages remaining in the mailbox after purge. */
     remaining: number;
 }
-interface Mailbox {
+export interface AutoCompactOptions {
+    /**
+     * Remove messages read by ALL currently-online agents that are older
+     * than this many milliseconds since the last read receipt was stamped.
+     * Default: 10 minutes (AUTO_COMPACT_READ_MAX_AGE_MS).
+     */
+    readMaxAgeMs?: number | undefined;
+    /**
+     * Default TTL for messages without an explicit `expiresAt`. Messages
+     * whose `timestamp` is older than `now - defaultTtlMs` are removed.
+     * Default: 24 hours (AUTO_COMPACT_DEFAULT_TTL_MS).
+     */
+    defaultTtlMs?: number | undefined;
+    /**
+     * Also run `purgeStale` logic in the same pass — purge completed
+     * messages older than this many ms. Default: 1 day.
+     */
+    completedMaxAgeMs?: number | undefined;
+    /**
+     * Also run `purgeStale` logic in the same pass — purge incomplete
+     * messages older than this many ms. Default: 7 days.
+     */
+    incompleteMaxAgeMs?: number | undefined;
+    /**
+     * Interval for the background auto-compact timer.
+     * Default: 5 minutes (AUTO_COMPACT_INTERVAL_MS).
+     */
+    intervalMs?: number | undefined;
+    /**
+     * Also run `purgeStale` logic in the same pass (completed > 1 day,
+     * incomplete > 7 days). Default: true.
+     */
+    includePurgeStale?: boolean | undefined;
+}
+export interface AutoCompactResult {
+    /** Messages removed because they were read by all online agents. */
+    readByAllRemoved: number;
+    /** Messages removed because their TTL expired (explicit or default). */
+    expiredRemoved: number;
+    /** Messages removed by the purgeStale pass (if enabled). */
+    stalePurged: number;
+    /** Total messages removed. */
+    totalRemoved: number;
+    /** Messages remaining in the mailbox after compaction. */
+    remaining: number;
+}
+export interface Mailbox {
     /** Send a message. Returns the created message. */
     send(input: MailboxSendInput): Promise<MailboxMessage>;
     /** Query messages matching criteria. */
@@ -314,10 +390,6 @@ interface Mailbox {
      * {@link restore}. The default `query()` filter hides the message
      * once `deletedAt` is set; pass `includeDeleted: true` to see the
      * trash.
-     *
-     * Phase 2 skeleton — the method signature is declared here so the
-     * WebUI client and the server route handler can compile against
-     * it; the implementation lands in the same PR.
      */
     softDelete(mailId: string, by: string): Promise<MailboxMessage | null>;
     /**
@@ -367,6 +439,26 @@ interface Mailbox {
      * This does NOT touch agent registrations or client registry.
      */
     purgeStale(opts?: PurgeOptions): Promise<PurgeResult>;
+    /**
+     * Auto-compact: remove messages that are no longer needed.
+     *
+     * Two cleanup passes run in a single file rewrite:
+     *  1. **Read-by-all**: Messages read by every currently-online agent,
+     *     older than `readMaxAgeMs` (default 10 min).
+     *  2. **Expired**: Messages whose `expiresAt` is in the past, or whose
+     *     `timestamp` is older than `defaultTtlMs` (default 24h) when no
+     *     explicit `expiresAt` is set.
+     *
+     * Also runs `purgeStale` logic (completed > 1 day, incomplete > 7 days)
+     * in the same pass to avoid a second rewrite.
+     */
+    autoCompact(opts?: AutoCompactOptions): Promise<AutoCompactResult>;
+    /**
+     * Start a background timer that periodically calls `autoCompact`.
+     * Returns a dispose function that stops the timer. Idempotent —
+     * calling start twice replaces the prior timer.
+     */
+    startAutoCompactTimer(opts?: AutoCompactOptions): () => void;
     /**
      * Register a client (REPL/TUI/WebUI). Called once per client on startup.
      * Subsequent calls are idempotent — they update lastSeenAt.
@@ -376,10 +468,17 @@ interface Mailbox {
      * Update client heartbeat. Called periodically (every 15s for clients).
      */
     clientHeartbeat(input: ClientHeartbeatInput): Promise<void>;
+    /** Remove a client immediately on clean shutdown. */
+    deregisterClient(clientId: string): Promise<void>;
     /**
      * Get snapshot of online/offline clients and their last activity.
      */
     getClientStatuses(): Promise<ClientStatus[]>;
+    /**
+     * Explicitly purge stale clients from the registry.
+     * Removes client entries whose lastSeenAt is older than CLIENT_STALE_MS.
+     * Returns the number of entries purged.
+     */
+    purgeClients(): Promise<number>;
 }
-
-export { type AgentRegistrationInput as A, type ClientRegistrationInput as C, type MailboxMessage as M, type PurgeOptions as P, type ReadReceipts as R, type MailboxAgentStatus as a, type Mailbox as b, type MailboxSendInput as c, type MailboxQuery as d, type MailboxAckInput as e, type MailboxAckBatchInput as f, type AgentHeartbeatInput as g, type ClientHeartbeatInput as h, type ClientStatus as i, type PurgeResult as j, type ClientSource as k, type MailboxMessageType as l, type MailboxTaskContext as m, type RegisteredAgent as n, normalizeRecipient as o };
+//# sourceMappingURL=mailbox-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox-types.d.ts","sourceRoot":"","sources":["../../src/coordination/mailbox-types.ts"],"names":[],"mappings":"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"}

package/dist/coordination/mailbox.d.ts

@@ -0,0 +1,88 @@
+/**
+ * DefaultMailbox — append-only JSONL inter-agent mailbox (per-session).
+ *
+ * Stores messages under `<sessionDir>/_mailbox.jsonl`. Every send appends
+ * one line. Query reads and filters all lines. Ack rewrites changed
+ * messages in-place via atomic write.
+ *
+ * For cross-session communication, use GlobalMailbox instead.
+ *
+ * @module DefaultMailbox
+ */
+import type { Logger } from '../types/logger.js';
+import type { AgentHeartbeatInput, AgentRegistrationInput, AutoCompactOptions, AutoCompactResult, ClientHeartbeatInput, ClientRegistrationInput, ClientStatus, Mailbox, MailboxAckBatchInput, MailboxAckInput, MailboxAgentStatus, MailboxMessage, MailboxQuery, MailboxSendInput, PurgeOptions, PurgeResult } from './mailbox-types.js';
+export declare class DefaultMailbox implements Mailbox {
+    private readonly filePath;
+    private _messageCache;
+    private _messageCacheMtime;
+    private _messageCacheSize;
+    /** True when the cache is only the newest MESSAGE_CACHE_MAX_ENTRIES records. */
+    private _messageCacheTruncated;
+    /** Primary index: recipient → Set of messages (points into _messageCache). */
+    private _byTo;
+    /** Secondary index: sender → Set of messages (points into _messageCache). */
+    private _byFrom;
+    /** Counts malformed JSONL lines skipped during parsing for observability. */
+    private _corruptionCount;
+    private readonly logger;
+    constructor(sessionDir: string, opts?: {
+        logger?: Logger | undefined;
+    });
+    get mailboxPath(): string;
+    /** Returns the count of malformed JSONL lines encountered during reads. */
+    get corruptionCount(): number;
+    send(input: MailboxSendInput): Promise<MailboxMessage>;
+    query(q: MailboxQuery): Promise<MailboxMessage[]>;
+    ack(input: MailboxAckInput): Promise<MailboxMessage | null>;
+    softDelete(_mailId: string, _by: string): Promise<MailboxMessage | null>;
+    restore(_mailId: string): Promise<MailboxMessage | null>;
+    ackMany(input: MailboxAckBatchInput): Promise<MailboxMessage[]>;
+    getAgentStatuses(): Promise<MailboxAgentStatus[]>;
+    getOnlineAgents(): Promise<MailboxAgentStatus[]>;
+    registerAgent(_input: AgentRegistrationInput): Promise<void>;
+    deregisterAgent(_agentId: string): Promise<void>;
+    heartbeat(_input: AgentHeartbeatInput): Promise<void>;
+    unreadCount(forAgentId: string): Promise<number>;
+    close(): Promise<void>;
+    clearAll(): Promise<void>;
+    purgeStale(opts?: PurgeOptions): Promise<PurgeResult>;
+    autoCompact(_opts?: AutoCompactOptions): Promise<AutoCompactResult>;
+    startAutoCompactTimer(_opts?: AutoCompactOptions): () => void;
+    registerClient(_input: ClientRegistrationInput): Promise<void>;
+    clientHeartbeat(_input: ClientHeartbeatInput): Promise<void>;
+    deregisterClient(_clientId: string): Promise<void>;
+    getClientStatuses(): Promise<ClientStatus[]>;
+    purgeClients(): Promise<number>;
+    private _readAll;
+    /**
+     * Read only newly-appended bytes from the file and append them to the
+     * in-memory cache, avoiding a full re-read when the file only grew.
+     *
+     * Guards against a half-written tail: when the tail doesn't end with
+     * LINE_SEPARATOR, another process may be mid-append. Parsing a partial
+     * JSON line would throw (caught below), but worse: the NEXT incremental
+     * read would skip that same line because the size tracker already advanced.
+     */
+    private _readNewMessagesOnly;
+    private _appendIncrementalLines;
+    private _parseLine;
+    /** Parse a JSONL string into MailboxMessage[], including migration. */
+    private _parseLines;
+    /**
+     * Stat the mailbox file under the assumption that we are holding the
+     * file lock, and that a write to the file has just completed. Returns
+     * the (mtimeMs, size) pair, or (-1, -1) if the file does not exist
+     * (e.g. ackMany/purgeStale on a session that has never sent a message).
+     */
+    private _statUnderLockOrAbsent;
+    private _readAllCached;
+    private _setMessageCache;
+    private _pushToCache;
+    /** Rebuild both indexes from a full message list. */
+    private _buildIndexes;
+    /** Add a single message to both indexes. */
+    private _indexMsg;
+    /** Remove an evicted message from both indexes without rebuilding them. */
+    private _unindexMsg;
+}
+//# sourceMappingURL=mailbox.d.ts.map

package/dist/coordination/mailbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox.d.ts","sourceRoot":"","sources":["../../src/coordination/mailbox.ts"],"names":[],"mappings":"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"}

package/dist/coordination/model-matrix.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Per-task model matrix resolution.
+ *
+ * The matrix (Config.modelMatrix) maps a catalog **role**, a **phase** name, or
+ * the `*` default to a {@link ModelMatrixEntry} (model + optional provider).
+ * At subagent spawn time we resolve the most specific match so different task
+ * types can run on different models — e.g. `security-scanner` on one model,
+ * `documentation` on another — while the leader keeps its own model.
+ *
+ * Resolution precedence (most → least specific):
+ *   1. exact role          (matrix["security-scanner"])
+ *   2. the role's phase     (matrix["review"])
+ *   3. the `*` default      (matrix["*"])
+ *   4. undefined            (caller falls back to the leader model)
+ *
+ * Set via the `/setmodel` slash command; this module is the single source of
+ * truth both that command and the spawn path use to validate + resolve keys.
+ */
+import type { Config, ModelMatrixEntry } from '../types/config.js';
+/** All valid phase keys, in catalog order. */
+export declare const MATRIX_PHASE_KEYS: readonly string[];
+/** The phase a catalog role belongs to, or undefined for unknown roles. */
+export declare function phaseForRole(role: string | undefined): string | undefined;
+export type ModelMatrixResolutionSource = 'role' | 'phase' | 'default';
+export interface ModelMatrixResolution {
+    entry: ModelMatrixEntry;
+    source: ModelMatrixResolutionSource;
+    key: string;
+}
+/**
+ * Resolve the matrix entry plus the key tier it came from. Use this when the
+ * caller needs to distinguish an explicit role/phase pin from the global `*`
+ * default.
+ */
+export declare function resolveModelMatrixResolution(matrix: Record<string, ModelMatrixEntry> | undefined, role: string | undefined): ModelMatrixResolution | undefined;
+/**
+ * Resolve the matrix entry for a subagent role. Returns the most specific
+ * match (role → phase → `*`), or undefined when nothing matches.
+ */
+export declare function resolveModelMatrix(matrix: Record<string, ModelMatrixEntry> | undefined, role: string | undefined): ModelMatrixEntry | undefined;
+export interface ResolvedModelTarget {
+    provider?: string | undefined;
+    model?: string | undefined;
+    modelRuntime?: Config['modelRuntime'] | undefined;
+    fallbackModels?: string[] | undefined;
+    fallbackProfile?: string | undefined;
+}
+export interface ResolvedSubagentModelTarget extends ResolvedModelTarget {
+    /** Where the concrete provider/model came from. */
+    source: 'matrix' | 'diversity' | 'none';
+    /** Matrix tier used before any reviewer diversity adjustment. */
+    matrixSource?: ModelMatrixResolutionSource | undefined;
+    /** True when a reviewer model was shifted away from the implementation model. */
+    diversified?: boolean | undefined;
+}
+/**
+ * Expand a matrix entry into a concrete primary model plus optional fallback
+ * chain. A profile-only matrix entry treats the first profile model as primary
+ * and the remaining profile entries as that subagent's fallback chain.
+ */
+export declare function resolveModelTargetFromEntry(config: Config, entry: ModelMatrixEntry | undefined): ResolvedModelTarget | undefined;
+export interface ModelReference {
+    provider?: string | undefined;
+    model?: string | undefined;
+}
+/**
+ * Roles whose output is meant to challenge an implementer. When these roles
+ * would otherwise use the same provider/model as the implementation path,
+ * WrongStack tries to pick a different available model to reduce correlated
+ * model-family mistakes. Exact role/phase `/setmodel` entries still win.
+ */
+export declare function roleNeedsIndependentReviewModel(role: string | undefined): boolean;
+/**
+ * Resolve a subagent's matrix target with the reviewer diversity rule applied.
+ *
+ * Precedence:
+ *   1. Exact role or phase matrix entry.
+ *   2. Global `*` matrix entry when it is already different from the
+ *      implementation model.
+ *   3. A different configured provider/model for review roles.
+ *   4. The matrix/leader fallback.
+ */
+export declare function resolveSubagentModelTarget(config: Config, role: string | undefined, opts?: {
+    implementationTarget?: ModelReference | undefined;
+}): ResolvedSubagentModelTarget | undefined;
+/**
+ * Resolve the default implementation lane. The generic Executor is the closest
+ * stable proxy for "the implementer" when a reviewer is spawned without a
+ * concrete sibling id.
+ */
+export declare function resolveImplementationModelTarget(config: Config): ModelReference;
+export declare function sameModelReference(a: ModelReference | undefined, b: ModelReference | undefined): boolean;
+export type MatrixKeyKind = 'role' | 'phase' | 'default' | 'unknown';
+/** Classify a matrix key so `/setmodel` can reject typos before persisting. */
+export declare function matrixKeyKind(key: string): MatrixKeyKind;
+/** True when `key` is a usable matrix key (role, phase, or `*`). */
+export declare function isValidMatrixKey(key: string): boolean;
+//# sourceMappingURL=model-matrix.d.ts.map

package/dist/coordination/model-matrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-matrix.d.ts","sourceRoot":"","sources":["../../src/coordination/model-matrix.ts"],"names":[],"mappings":"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"}