@wrongstack/core 0.284.0 → 0.285.0

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. */
@@ -80,7 +80,7 @@ interface MailboxMessage {
     /** Session id of the sender. Enables cross-session communication. */
     senderSessionId?: 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 +90,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 +118,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 +148,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 +180,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"). */
@@ -199,7 +199,7 @@ interface MailboxSendInput {
     /** Task context for assign-type messages. */
     taskContext?: MailboxTaskContext | undefined;
 }
-interface MailboxAckInput {
+export interface MailboxAckInput {
     /** Message id to acknowledge. */
     messageId: string;
     /** Agent id of who is reading/acking. */
@@ -219,11 +219,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 +231,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 +264,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 +284,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 +296,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 +306,7 @@ interface PurgeResult {
     /** Messages remaining in the mailbox after purge. */
     remaining: number;
 }
-interface Mailbox {
+export interface Mailbox {
     /** Send a message. Returns the created message. */
     send(input: MailboxSendInput): Promise<MailboxMessage>;
     /** Query messages matching criteria. */
@@ -381,5 +397,4 @@ interface Mailbox {
      */
     getClientStatuses(): Promise<ClientStatus[]>;
 }
-
-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,69 @@
+/**
+ * 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 { AgentHeartbeatInput, AgentRegistrationInput, 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;
+    /** 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;
+    constructor(sessionDir: string);
+    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>;
+    registerClient(_input: ClientRegistrationInput): Promise<void>;
+    clientHeartbeat(_input: ClientHeartbeatInput): Promise<void>;
+    getClientStatuses(): Promise<ClientStatus[]>;
+    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.
+     */
+    private _readNewMessagesOnly;
+    /** 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;
+}
+//# 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":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,KAAK,EACV,mBAAmB,EACnB,sBAAsB,EACtB,oBAAoB,EACpB,uBAAuB,EACvB,YAAY,EACZ,OAAO,EACP,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACZ,MAAM,oBAAoB,CAAC;AAO5B,qBAAa,cAAe,YAAW,OAAO;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,aAAa,CAAiC;IACtD,OAAO,CAAC,kBAAkB,CAAM;IAChC,OAAO,CAAC,iBAAiB,CAAM;IAC/B,8EAA8E;IAC9E,OAAO,CAAC,KAAK,CAA0C;IACvD,6EAA6E;IAC7E,OAAO,CAAC,OAAO,CAA0C;IACzD,6EAA6E;IAC7E,OAAO,CAAC,gBAAgB,CAAK;IAE7B,YAAY,UAAU,EAAE,MAAM,EAE7B;IAED,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,2EAA2E;IAC3E,IAAI,eAAe,IAAI,MAAM,CAE5B;IAIK,IAAI,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAuC3D;IAIK,KAAK,CAAC,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAuEtD;IAIK,GAAG,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAGhE;IAEK,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAM7E;IAEK,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAG7D;IAEK,OAAO,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CA8CpE;IAIK,gBAAgB,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CA8BtD;IAIK,eAAe,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAErD;IAEK,aAAa,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAEjE;IAEK,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAErD;IAEK,SAAS,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1D;IAEK,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAKrD;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAM3B;IAEK,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAW9B;IAEK,UAAU,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAmD1D;IAIK,cAAc,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAEnE;IAEK,eAAe,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAEjE;IAEK,iBAAiB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAGjD;YAIa,QAAQ;IAUtB;;;OAGG;YACW,oBAAoB;IAmClC,uEAAuE;IACvE,OAAO,CAAC,WAAW;IA0BnB;;;;;OAKG;YACW,sBAAsB;YAYtB,cAAc;IA2C5B,OAAO,CAAC,gBAAgB;IAuBxB,OAAO,CAAC,YAAY;IAcpB,qDAAqD;IACrD,OAAO,CAAC,aAAa;IAQrB,4CAA4C;IAC5C,OAAO,CAAC,SAAS;CAelB"}

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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"}

package/dist/coordination/multi-agent-coordinator.d.ts

@@ -0,0 +1,202 @@
+import { EventEmitter } from 'node:events';
+import type { AgentBridge, BridgeMessage } from '../types/agent-bridge.js';
+import type { AwaitAnyResult, CoordinatorStatus, MultiAgentConfig, MultiAgentCoordinator, SpawnResult, SubagentConfig, SubagentRunner, TaskResult, TaskSpec } from '../types/multi-agent.js';
+import { type BudgetSessionIdSource } from './subagent-budget.js';
+export interface MultiAgentCoordinatorOptions {
+    /**
+     * Callback that executes a task on behalf of a subagent. Required for
+     * `assign()` to actually run anything — without it, tasks queue forever.
+     * The coordinator provides per-subagent isolation (own budget, own signal,
+     * own bridge) and enforces timeout + concurrency.
+     */
+    runner?: SubagentRunner | undefined;
+    /**
+     * Session id for EventBus/FleetBus emissions produced by this coordinator.
+     * Accepts a getter so a long-lived coordinator follows session resume/new.
+     */
+    sessionId?: BudgetSessionIdSource | undefined;
+}
+export declare class DefaultMultiAgentCoordinator extends EventEmitter implements MultiAgentCoordinator {
+    readonly coordinatorId: string;
+    readonly config: MultiAgentConfig;
+    private runner?;
+    private readonly sessionId;
+    private fleetBus?;
+    private readonly subagents;
+    /**
+     * Base nickname keys already handed out this run (e.g. `einstein`, `tesla`).
+     * Prevents two workers sharing a name. Direct `coordinator.spawn()` callers
+     * (parallel/eternal engine, SDD parallel run) don't go through
+     * `Director.spawn()` where nicknames are normally assigned, so the
+     * coordinator upgrades placeholder names ("Executor", "slot-ab12cd", role
+     * names) to memorable ones here — that's what surfaces in the fleet monitor.
+     */
+    private readonly usedNicknames;
+    /** Maps subagentId → nickname key (e.g. 'einstein'). Used to free the slot on remove(). */
+    private readonly subagentNicknames;
+    private pendingTasks;
+    private completedResults;
+    /** Prevents completedResults from growing unbounded in long-running coordinators. */
+    private static readonly MAX_COMPLETED_RESULTS;
+    private totalIterations;
+    private inFlight;
+    /**
+     * Subagents currently being stopped. Set on entry to `stop()`, cleared
+     * once `recordCompletion` lands the terminal TaskResult. Used by
+     * `runDispatched` and `findIdleSubagent` to refuse mid-flight dispatch
+     * to a subagent the caller has already asked to terminate — closes the
+     * assign+terminate race where a fresh task could land on a worker that
+     * was about to be killed.
+     */
+    private readonly terminating;
+    constructor(config: MultiAgentConfig, options?: MultiAgentCoordinatorOptions);
+    private currentSessionId;
+    /**
+     * Replace the runner after construction. Used when the runner depends
+     * on infrastructure (e.g. FleetBus) that isn't available until after
+     * the coordinator's owning Director is built.
+     */
+    setRunner(runner: SubagentRunner): void;
+    /**
+     * Wire a FleetBus for director-mode event emission. Call after the
+     * FleetManager is constructed so the coordinator can emit lifecycle
+     * events the TUI and monitoring tools subscribe to.
+     */
+    setFleetBus(fleet: import('./fleet-bus.js').FleetBus): void;
+    /**
+     * Change the in-flight dispatch ceiling at runtime. Lowering does NOT
+     * preempt running tasks — already-dispatched subagents finish their
+     * current task; only future dispatches respect the new cap. Raising
+     * immediately tries to fill the freed slots from the pending queue.
+     */
+    setMaxConcurrent(n: number): void;
+    /**
+     * Upgrade a placeholder/role-derived name to a memorable scientist nickname
+     * (e.g. "Einstein (Executor)"). A name is treated as a placeholder when it is
+     * empty, equals the role (case-insensitive), is a generic default
+     * ("subagent"/"adhoc"/"generic"), or is an auto-generated `slot-…` id.
+     * Explicit, human-chosen names — including nicknames already assigned by
+     * `Director.spawn()` — are left untouched, so this never double-assigns.
+     */
+    private withNickname;
+    spawn(subagent: SubagentConfig): Promise<SpawnResult>;
+    assign(task: TaskSpec): Promise<void>;
+    delegate(to: string, msg: BridgeMessage): Promise<void>;
+    /**
+     * Wire up the communication bridge for a subagent. Call after spawn() once
+     * the caller has created the bidirectional connection.
+     */
+    setSubagentBridge(subagentId: string, bridge: AgentBridge): void;
+    stop(subagentId: string): Promise<void>;
+    stopAll(): Promise<void>;
+    /**
+     * Get current coordinator stats for monitoring/debugging.
+     */
+    getStats(): {
+        total: number;
+        running: number;
+        idle: number;
+        stopped: number;
+        inFlight: number;
+        pending: number;
+        completed: number;
+    };
+    /** Emit a reactive coordinator.stats event on FleetBus so the TUI can subscribe. */
+    private emitCoordinatorStats;
+    getStatus(): CoordinatorStatus;
+    /** Expose snapshot of completed results — useful for callers awaiting all done. */
+    results(): readonly TaskResult[];
+    /** Defensive snapshot of the still-queued (not yet dispatched) tasks. */
+    listPendingTasks(): readonly TaskSpec[];
+    /**
+     * Re-pin a still-PENDING task to a different subagent (`undefined` =
+     * unpin, any idle worker may take it), then try to dispatch. Returns
+     * `false` when the task is not in the pending queue — already
+     * dispatched, completed, or unknown. Running tasks can never be pulled;
+     * they can only be steered or terminated. The mutation is synchronous
+     * (same tick as the check), so it cannot race a concurrent dispatch:
+     * `tryDispatchNext` runs on this same call stack or a later one.
+     *
+     * The task keeps its id, so waiters, the report-back notifier, and
+     * checkpoint bookkeeping resolve unchanged when it eventually completes.
+     */
+    retargetPendingTask(taskId: string, subagentId: string | undefined): boolean;
+    /**
+     * Wait for one or more tasks to complete and return their results.
+     * If a task is already done when called, returns immediately.
+     * Resolves to an array in the same order as `taskIds`.
+     */
+    awaitTasks(taskIds: string[]): Promise<TaskResult[]>;
+    /**
+     * Wait until AT LEAST ONE of the named tasks completes. Returns every
+     * requested result already available at that moment (drain-what's-done)
+     * plus the ids still outstanding, so callers can loop "handle finishers,
+     * re-await the remainder" instead of blocking on the whole batch.
+     *
+     * Unlike `awaitTasks`, this never rejects and deliberately does NOT
+     * inherit `config.timeoutMs` — a "return whatever is done" call has no
+     * business timing out unless the caller asks for a window explicitly.
+     */
+    awaitTasksAny(taskIds: string[], opts?: {
+        timeoutMs?: number;
+    }): Promise<AwaitAnyResult>;
+    /**
+     * Manual completion — for callers that drive subagents without a runner
+     * (e.g. external orchestrators). When a runner is configured the coordinator
+     * calls this itself.
+     */
+    completeTask(result: TaskResult): void;
+    private tryDispatchNext;
+    private canDispatch;
+    private takeNextDispatchableTask;
+    private findIdleSubagent;
+    private isIdleSubagent;
+    /**
+     * Returns true iff at least one spawned subagent could still
+     * process a task. A "live" subagent is one that is not stopped
+     * AND not mid-termination — `running` workers count because they
+     * will eventually finish and become idle.
+     *
+     * When no subagent has ever been spawned, returns `true` so a
+     * pre-spawn `assign()` simply queues (legacy behaviour). The
+     * dead-end detection only fires after `stop()` has retired every
+     * spawned worker.
+     *
+     * Used by `tryDispatchNext` to detect a dead-end pending queue.
+     */
+    private hasLiveSubagent;
+    /**
+     * Drain every pending task with a synthetic `aborted_by_parent`
+     * completion event. Same shape as the `stopAll()` drain — we go
+     * around `recordCompletion` because pending tasks were never
+     * counted in `inFlight` and routing them through would trip the
+     * underflow guard on every task after the first.
+     */
+    private drainPendingAsAborted;
+    /**
+     * Emit a synthetic `stopped`/`aborted_by_parent` completion for a single
+     * PENDING task — one that was never counted in `inFlight`. This MUST bypass
+     * `recordCompletion`: that path does `inFlight--`, which for a pending task
+     * steals a decrement from a genuinely in-flight task and trips the underflow
+     * guard — suppressing that real task's `task.completed` and hanging its
+     * `awaitTasks()` caller. Pushes the result and fires the event directly.
+     */
+    private emitPendingAborted;
+    private runDispatched;
+    private executeWithTimeout;
+    private recordCompletion;
+    /**
+     * Stop a subagent and remove it from the coordinator. Releases all
+     * associated resources (AbortController, context, budget state).
+     * The subagent entry is deleted so the id can be reused in a future spawn.
+     */
+    remove(subagentId: string): Promise<void>;
+    private isDone;
+}
+/**
+ * Map any raw exception thrown out of a subagent's runner into a
+ * structured `SubagentError`. Delegates to the shared classifier.
+ * Re-exported for backward compatibility.
+ */
+export { classifySubagentError } from './coordinator/error-classifier.js';
+//# sourceMappingURL=multi-agent-coordinator.d.ts.map

package/dist/coordination/multi-agent-coordinator.d.ts.map

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