@wrongstack/core 0.284.1 → 0.286.0

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

@@ -0,0 +1,295 @@
+/**
+ * GlobalMailbox — project-level inter-agent mailbox with cross-session support.
+ *
+ * Stores messages at `~/.wrongstack/projects/<slug>/_mailbox.jsonl` so all
+ * sessions (terminals, WebUIs) working on the same project share one inbox.
+ *
+ * Features:
+ * - Agent registration + heartbeat (agents go stale after 60s without heartbeat)
+ * - Per-recipient read receipts (readBy[agentId] = ISO8601)
+ * - Atomic file-locking for concurrent multi-process writes
+ * - Unread count for new-mail notifications
+ * - Online agent list
+ *
+ * @module GlobalMailbox
+ */
+import type { HqPublisher } from '../hq/publisher.js';
+import type { EventBus } from '../kernel/events.js';
+import type { MailboxEventEmitter } from './mailbox-events.js';
+import type { AgentHeartbeatInput, AgentRegistrationInput, AutoCompactOptions, AutoCompactResult, ClientHeartbeatInput, ClientRegistrationInput, ClientStatus, Mailbox, MailboxAckBatchInput, MailboxAckInput, MailboxAgentStatus, MailboxMessage, MailboxQuery, MailboxSendInput, PurgeOptions, PurgeResult } from './mailbox-types.js';
+type HqPublisherRef = HqPublisher | (() => HqPublisher | undefined);
+/**
+ * Derive the project-level mailbox directory path.
+ *
+ * Delegates to the CANONICAL `projectSlug()` from wstack-paths so every
+ * surface (CLI, TUI, WebUI, mailbox tool, loop checker) lands in the exact
+ * same `~/.wrongstack/projects/<slug>/` directory. A previous inline copy
+ * skipped the leading/trailing-hyphen strip, which silently split agents
+ * working on projects with non-alphanumeric name edges into TWO mailboxes.
+ *
+ * @param projectRoot  — absolute path to the project root
+ * @param globalRoot   — `~/.wrongstack` (or custom global root)
+ */
+export declare function resolveProjectDir(projectRoot: string, globalRoot: string): string;
+export declare function getSharedMailbox(projectDir: string, events?: EventBus, hqPublisher?: HqPublisherRef, opts?: {
+    forceNew?: boolean;
+}): GlobalMailbox;
+/** Clear the singleton registry — used by tests to avoid cross-test leakage. */
+export declare function _clearMailboxSingletons(): void;
+export declare class GlobalMailbox implements Mailbox {
+    /** Path to the JSONL message file. */
+    readonly messagePath: string;
+    /** Path to the JSON agent registry file. */
+    readonly registryPath: string;
+    /** Path to the JSON client registry file. */
+    readonly clientRegistryPath: string;
+    /** Optional event bus for emitting agent registration/heartbeat events. */
+    private readonly _events?;
+    /** Optional HQ publisher for cross-project command-center telemetry. */
+    private readonly _hqPublisher?;
+    /**
+     * Optional SSE event emitter for real-time push to HTTP bridge clients.
+     * When present, `send`/`ack`/`softDelete`/`restore` emit events that
+     * connected SSE subscribers receive instantly.
+     */
+    readonly eventEmitter?: MailboxEventEmitter | undefined;
+    /**
+     * Local cache of the agent registry to avoid re-reading on every call.
+     * Time-bounded: the registry file is shared ACROSS PROCESSES (that's the
+     * whole point of GlobalMailbox), so a cache served forever would never see
+     * agents registered by other sessions. Writers always bypass it.
+     */
+    private _registryCache;
+    /** When the registry cache was last refreshed from disk (epoch ms). */
+    private _registryCacheAt;
+    /**
+     * Local cache of the client registry to avoid re-reading on every call.
+     * Same reasoning as agent registry cache.
+     */
+    private _clientRegistryCache;
+    /** When the client registry cache was last refreshed from disk (epoch ms). */
+    private _clientRegistryCacheAt;
+    /** Last time each local agent sent a heartbeat (throttle). */
+    private _lastHeartbeat;
+    /** Last time each local client sent a heartbeat (throttle). */
+    private _lastClientHeartbeat;
+    /**
+     * In-memory mirror of the JSONL message file. The mailbox is shared
+     * ACROSS PROCESSES, so reads cannot trust the cache blindly — we pair it
+     * with an mtime check. The file lock serializes every write, so a
+     * changed mtimeMs is a definitive signal that another process (or this
+     * one) wrote; an unchanged mtimeMs guarantees no write happened and the
+     * cache is current. This collapses the per-iteration `query()` cost from
+     * O(file_size) disk + parse to O(messages) in memory.
+     */
+    private _messageCache;
+    /** mtimeMs of the file when `_messageCache` was populated. */
+    private _messageCacheMtime;
+    /** Size of the file when `_messageCache` was populated (extra guard). */
+    private _messageCacheSize;
+    /**
+     * Serializes reads of the message file so overlapping concurrent
+     * `_readMessagesCached()` calls don't both enter the incremental "file
+     * only grew" branch against the same stale `_messageCacheSize` and
+     * each push the same tail bytes onto the cache (duplicating every
+     * appended message). The chain runs each read to completion before
+     * the next starts, in issue order — readers are read-only and never
+     * conflict with each other on content, only on the cache mutation
+     * that follows the read. Pattern mirrors `DefaultMemoryStore.runSerialized`.
+     */
+    private _readChain;
+    /**
+     * Recipient → Set of indices into `_messageCache`. Maintained alongside
+     * the cache so `query({ to })` and `unreadCount(agentId)` can skip the
+     * O(N) full scan and iterate only the messages addressed to the target
+     * recipient (plus broadcasts `*`).
+     *
+     * The index is rebuilt whenever the cache array is replaced
+     * (`_setMessageCache`), extended when new messages are pushed
+     * (`_pushToCache`, `_readNewMessagesOnly`), and cleared on `close()`.
+     * It is `null` when the cache itself is null (> MESSAGE_CACHE_MAX_ENTRIES
+     * or never populated).
+     *
+     * Safety: array indices are valid only as long as the cache array
+     * reference hasn't changed. Since we rebuild the index in the same
+     * synchronous step that replaces the cache, a reader that calls
+     * `_readMessagesCached()` either gets the old array + old index, or
+     * the new array + new index — never a mismatch.
+     */
+    private _recipientIndex;
+    /**
+     * Sender → Set of indices into `_messageCache`. Same lifecycle and
+     * safety properties as `_recipientIndex`, but keyed on `msg.from`
+     * so `query({ from })` can skip the full scan.
+     */
+    private _senderIndex;
+    /**
+     * @param projectDir — `~/.wrongstack/projects/<slug>/`
+     * @param events — optional EventBus for real-time TUI/WebUI notifications
+     * @param hqPublisher — optional HQ publisher, or getter, for cross-project telemetry
+     * @param eventEmitter — optional SSE event emitter for HTTP bridge push
+     */
+    constructor(projectDir: string, events?: EventBus, hqPublisher?: HqPublisherRef, eventEmitter?: MailboxEventEmitter);
+    private get hqMailboxId();
+    private get hqPublisher();
+    private publishHqMailboxEvent;
+    private publishHqMailboxSnapshot;
+    send(input: MailboxSendInput): Promise<MailboxMessage>;
+    query(q: MailboxQuery): Promise<MailboxMessage[]>;
+    ack(input: MailboxAckInput): Promise<MailboxMessage | null>;
+    ackMany(input: MailboxAckBatchInput): Promise<MailboxMessage[]>;
+    unreadCount(forAgentId: string): Promise<number>;
+    softDelete(mailId: string, by: string): Promise<MailboxMessage | null>;
+    restore(mailId: string): Promise<MailboxMessage | null>;
+    registerAgent(input: AgentRegistrationInput): Promise<void>;
+    deregisterAgent(agentId: string): Promise<void>;
+    heartbeat(input: AgentHeartbeatInput): Promise<void>;
+    getAgentStatuses(): Promise<MailboxAgentStatus[]>;
+    getOnlineAgents(): Promise<MailboxAgentStatus[]>;
+    registerClient(input: ClientRegistrationInput): Promise<void>;
+    deregisterClient(clientId: string): Promise<void>;
+    clientHeartbeat(input: ClientHeartbeatInput): Promise<void>;
+    getClientStatuses(): Promise<ClientStatus[]>;
+    /**
+     * Explicitly purge stale clients from the registry and write back to disk.
+     * Removes client entries whose lastSeenAt is older than CLIENT_STALE_MS.
+     * Returns the number of entries purged.
+     *
+     * Idempotent — safe to call regularly. The same pruning runs implicitly
+     * inside registerClient, clientHeartbeat, and getClientStatuses, but if
+     * no client registers or heartbeats for a long time, this public method
+     * ensures the file gets cleaned up on demand.
+     */
+    purgeClients(): Promise<number>;
+    close(): Promise<void>;
+    clearAll(): Promise<void>;
+    purgeStale(opts?: PurgeOptions): Promise<PurgeResult>;
+    private _autoCompactTimer;
+    autoCompact(opts?: AutoCompactOptions): Promise<AutoCompactResult>;
+    startAutoCompactTimer(opts?: AutoCompactOptions): () => void;
+    /**
+     * Read all messages from the JSONL file. Always reads + parses the file.
+     * Callers that can tolerate a stale-by-mtime view should use
+     * {@link _readMessagesCached}; writers that need the post-lock truth
+     * should call this directly (it's what {@link _readMessagesFresh} aliases).
+     */
+    private _readMessages;
+    /**
+     * Read only newly-appended bytes from the file and append them to the
+     * in-memory cache. This avoids re-reading and re-parsing the entire file
+     * when another process appended messages since our last read.
+     *
+     * Only safe when the file grew in size (messages are append-only). When
+     * the file was rewritten (ack/purge changed existing content), callers
+     * must fall back to {@link _readMessages}.
+     *
+     * @returns The (now up-to-date) message cache.
+     */
+    private _readNewMessagesOnly;
+    private _appendIncrementalLines;
+    private _parseLine;
+    /** Parse a JSONL string into MailboxMessage[], including migration. */
+    private _parseLines;
+    /**
+     * Read messages, then adopt the result as the in-memory cache. Use this
+     * from writers that just took the file lock — the read reflects the
+     * authoritative post-lock state and should be served to subsequent
+     * queries without re-reading.
+     *
+     * The mtime/size are captured from the stat at read time so the cache
+     * trackers match exactly what was parsed. Writers that subsequently
+     * rewrite the file MUST re-stat after the write and re-promote with the
+     * post-write values (see ackMany / softDelete / restore / purgeStale /
+     * clearAll) — otherwise a concurrent reader misclassifies the rewrite
+     * as a "file only grew" append and corrupts the cache.
+     */
+    private _readMessagesFresh;
+    /**
+     * Stat the message file, returning its mtimeMs and size. Returns
+     * `-1/-1` when the file does not yet exist (ENOENT) so callers can
+     * still promote a cache snapshot — the next read will re-stat and
+     * fall through to a full re-read. Call from inside the file lock so
+     * the result reflects the post-write on-disk state, not a later
+     * intermediate state from another process.
+     */
+    private _statMessageFile;
+    /**
+     * Read messages, consulting the mtime-bounded in-memory cache first,
+     * serialized so concurrent callers don't both mutate the cache.
+     *
+     * The mailbox file is shared across processes; every `send`/`ack`/
+     * `clearAll`/`purgeStale` takes the file lock, so writes are serialized
+     * and a changed mtimeMs is a definitive freshness signal. When the
+     * stat matches the cached mtime+size we return the cached array — no
+     * file read and no JSON.parse — collapsing the per-iteration query
+     * cost on the mailbox-loop hot path.
+     *
+     * When the file only grew (new messages appended by another process),
+     * we read and parse just the tail bytes instead of the entire file.
+     * This avoids re-parsing the full 10K-message history on every check.
+     *
+     * SERIALIZATION: the actual work is chained onto `_readChain` so two
+     * overlapping calls can't both pass the `st.size > _messageCacheSize`
+     * incremental check against the same stale tracker and each push the
+     * same tail bytes onto the cache (duplicating every appended message).
+     * Readers don't conflict on file content — only on the cache mutation
+     * that follows the read — so we run them one at a time in issue order.
+     * Errors in the chain are swallowed so a failed read never poisons
+     * subsequent reads; each caller observes and re-throws its own error.
+     */
+    private _readMessagesCached;
+    /**
+     * The un-serialized body of {@link _readMessagesCached}. Reads the
+     * message file with the mtime-bounded cache + incremental-tail
+     * optimization. Must only be called from `_readMessagesCached` so the
+     * cache mutations here don't race a sibling read.
+     */
+    private _readMessagesCachedWork;
+    /**
+     * Replace the in-memory cache, setting the mtime/size trackers
+     * synchronously in the same step. Callers MUST pass the stat of the
+     * on-disk file state that produced `messages`.
+     *
+     * Why both are required (not fire-and-forget): `_readMessagesCached()`
+     * validates the cache against a fresh stat using these two trackers.
+     * If the cache array is updated but the trackers lag behind (e.g. via
+     * a deferred `stat().then(...)`), a concurrent reader landing in that
+     * window sees a mismatched mtime and falls into the incremental
+     * "file only grew" branch — parsing rewritten bytes as an appended
+     * tail and corrupting the cache with duplicates/garbage. So both
+     * values are captured under the file lock and applied synchronously
+     * here, matching the fix already shipped in DefaultMailbox.
+     */
+    private _setMessageCache;
+    /**
+     * Build the recipient AND sender indexes from the current `_messageCache`.
+     * Called only from `_setMessageCache` so both indexes are always in sync
+     * with a freshly-replaced cache array.
+     */
+    private _rebuildRecipientIndex;
+    /**
+     * Append a single just-sent message to the in-memory cache without
+     * re-reading the file. The caller must hold the file lock (or have
+     * just released it after a successful append) and MUST pass the
+     * post-append stat so the mtime/size trackers advance in lock-step
+     * with the pushed content.
+     *
+     * Why the stat is required here: without it, `_messageCacheSize`
+     * stays at the pre-append value. A concurrent `_readMessagesCached()`
+     * then sees `st.size > _messageCacheSize` (the file did grow), takes
+     * the incremental branch, and re-reads the just-appended tail —
+     * pushing the same message onto the cache a second time. Setting the
+     * trackers here closes that window for the local-process append path.
+     */
+    private _pushToCache;
+    private _ensureRegistry;
+    private _readRegistry;
+    private _pruneStaleInPlace;
+    private _writeRegistry;
+    private _ensureClientRegistry;
+    private _readClientRegistry;
+    private _pruneStaleClientsInPlace;
+    private _writeClientRegistry;
+}
+export {};
+//# sourceMappingURL=global-mailbox.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"global-mailbox.d.ts","sourceRoot":"","sources":["../../src/coordination/global-mailbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAcpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D,OAAO,KAAK,EACV,mBAAmB,EACnB,sBAAsB,EACtB,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,YAAY,EACZ,OAAO,EACP,oBAAoB,EACpB,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,WAAW,EAGZ,MAAM,oBAAoB,CAAC;AAQ5B,KAAK,cAAc,GAAG,WAAW,GAAG,CAAC,MAAM,WAAW,GAAG,SAAS,CAAC,CAAC;AAEpE;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAEjF;AAqBD,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,QAAQ,EACjB,WAAW,CAAC,EAAE,cAAc,EAC5B,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5B,aAAa,CASf;AAED,gFAAgF;AAChF,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C;AAID,qBAAa,aAAc,YAAW,OAAO;IAC3C,sCAAsC;IACtC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4CAA4C;IAC5C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,6CAA6C;IAC7C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,2EAA2E;IAC3E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAuB;IAChD,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAA6B;IAC3D;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IACxD;;;;;OAKG;IACH,OAAO,CAAC,cAAc,CAA6C;IACnE,uEAAuE;IACvE,OAAO,CAAC,gBAAgB,CAAK;IAC7B;;;OAGG;IACH,OAAO,CAAC,oBAAoB,CAA8C;IAC1E,8EAA8E;IAC9E,OAAO,CAAC,sBAAsB,CAAK;IACnC,8DAA8D;IAC9D,OAAO,CAAC,cAAc,CAA6B;IACnD,+DAA+D;IAC/D,OAAO,CAAC,oBAAoB,CAA6B;IACzD;;;;;;;;OAQG;IACH,OAAO,CAAC,aAAa,CAAiC;IACtD,8DAA8D;IAC9D,OAAO,CAAC,kBAAkB,CAAM;IAChC,yEAAyE;IACzE,OAAO,CAAC,iBAAiB,CAAM;IAC/B;;;;;;;;;OASG;IACH,OAAO,CAAC,UAAU,CAAsE;IAExF;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,eAAe,CAAyC;IAEhE;;;;OAIG;IACH,OAAO,CAAC,YAAY,CAAyC;IAE7D;;;;;OAKG;IACH,YACE,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,QAAQ,EACjB,WAAW,CAAC,EAAE,cAAc,EAC5B,YAAY,CAAC,EAAE,mBAAmB,EAQnC;IAED,OAAO,KAAK,WAAW,GAEtB;IAED,OAAO,KAAK,WAAW,GAEtB;IAED,OAAO,CAAC,qBAAqB;IAQ7B,OAAO,CAAC,wBAAwB;IAU1B,IAAI,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAkE3D;IAEK,KAAK,CAAC,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAyEtD;IAEK,GAAG,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAGhE;IAEK,OAAO,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CA4EpE;IAEK,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBrD;IAEK,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAqD3E;IAEK,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAkD5D;IAIK,aAAa,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4DhE;IAEK,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCpD;IAEK,SAAS,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6CzD;IAEK,gBAAgB,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAuCtD;IAEK,eAAe,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAGrD;IAIK,cAAc,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BlE;IAEK,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAatD;IAEK,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiChE;IAEK,iBAAiB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CA2BjD;IAED;;;;;;;;;OASG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAepC;IAIK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAS3B;IAEK,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAU9B;IAEK,UAAU,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAqD1D;IAID,OAAO,CAAC,iBAAiB,CAA+B;IAElD,WAAW,CAAC,IAAI,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAgGvE;IAED,qBAAqB,CAAC,IAAI,CAAC,EAAE,kBAAkB,GAAG,MAAM,IAAI,CAiB3D;IAID;;;;;OAKG;YACW,aAAa;IAU3B;;;;;;;;;;OAUG;YACW,oBAAoB;IA2ClC,OAAO,CAAC,uBAAuB;IA0B/B,OAAO,CAAC,UAAU;IAQlB,uEAAuE;IACvE,OAAO,CAAC,WAAW;IAUnB;;;;;;;;;;;;OAYG;YACW,kBAAkB;IAOhC;;;;;;;OAOG;YACW,gBAAgB;IAY9B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,CAAC,mBAAmB;IAU3B;;;;;OAKG;YACW,uBAAuB;IA6CrC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,gBAAgB;IAmBxB;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IA4B9B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,YAAY;YAyCN,eAAe;YAIf,aAAa;IAmC3B,OAAO,CAAC,kBAAkB;YAaZ,cAAc;YAYd,qBAAqB;YAIrB,mBAAmB;IAgCjC,OAAO,CAAC,yBAAyB;YAUnB,oBAAoB;CASnC"}

package/dist/coordination/icoordinator.d.ts

@@ -0,0 +1,97 @@
+import type { SubagentConfig } from '../types/multi-agent.js';
+import type { TaskSpec, TaskResult, CoordinatorStatus } from '../types/multi-agent.js';
+export type { TaskSpec, TaskResult } from '../types/multi-agent.js';
+/**
+ * Interface for a fleet coordinator. Implemented by both `Director`
+ * (full LLM-driven orchestration with fleet policy) and
+ * `DefaultMultiAgentCoordinator` (direct API-driven, no fleet policy).
+ *
+ * External callers — CLI slash commands, tests, the delegate tool —
+ * use this to stay agnostic to the orchestration mode.
+ *
+ * The interface captures the **orchestration contract**: spawn, assign,
+ * terminate, await, and query. Fleet-level policy (cost caps, manifest
+ * writing, checkpointing) lives behind this surface and is optional
+ * from the caller's perspective.
+ *
+ * @example
+ * ```typescript
+ * let coordinator: ICoordinator = isDirectorMode
+ *   ? new Director({ config, ... })
+ *   : new DefaultMultiAgentCoordinator(config);
+ * const id = await coordinator.spawn({ name: 'worker', role: 'researcher' });
+ * await coordinator.assign({ id: 't-1', description: 'research X', subagentId: id });
+ * const results = await coordinator.awaitTasks(['t-1']);
+ * ```
+ */
+export interface ICoordinator {
+    /** Stable identifier for this coordinator instance. */
+    readonly coordinatorId: string;
+    /**
+     * Spawn a new subagent and return its id. In director mode this
+     * enforces fleet-wide spawn caps and cost limits; in raw coordinator
+     * mode it is a direct pass-through.
+     */
+    spawn(config: SubagentConfig): Promise<string>;
+    /**
+     * Assign a task to a subagent (or to the fleet for auto-routing).
+     * Returns the assigned task id.
+     */
+    assign(task: {
+        id: string;
+        description: string;
+        subagentId?: string | undefined;
+    }): Promise<string>;
+    /**
+     * Synchronously ask a subagent something via the in-memory bridge.
+     * The subagent must have been spawned and must handle `bridge.subscribe()`
+     * in its task loop. Returns the reply payload or throws on timeout.
+     *
+     * Only available in director mode — raw coordinator has no bridge.
+     */
+    ask<T = unknown>(subagentId: string, payload: unknown, timeoutMs?: number): Promise<T> | undefined;
+    /**
+     * 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[]>;
+    /**
+     * Gracefully stop a single subagent. The subagent finishes its current
+     * in-flight work and exits cleanly — it does not hard-kill.
+     */
+    terminate(subagentId: string): Promise<void>;
+    /**
+     * Stop all subagents. In-flight tasks are allowed to complete;
+     * no new tasks are dispatched.
+     */
+    terminateAll(): Promise<void>;
+    /**
+     * Stop a subagent and remove it from the coordinator. Releases all
+     * associated resources (AbortController, budget state). The subagent
+     * entry is deleted so the id can be reused in a future spawn.
+     */
+    remove(subagentId: string): Promise<void>;
+    /**
+     * Live coordinator status — subagent list, pending task count,
+     * completed task count, iteration totals.
+     */
+    status(): CoordinatorStatus;
+    /**
+     * Snapshot of completed task results. In director mode this returns
+     * every `TaskResult` from the fleet; in raw coordinator mode this
+     * may return an empty array if the coordinator doesn't cache results.
+     */
+    completedResults(): TaskResult[];
+    /**
+     * Subscribe to coordinator lifecycle events. Currently supports
+     * `task.completed` — the payload carries the task spec and result.
+     *
+     * Returns a disposer function; call it to unsubscribe.
+     */
+    on(event: 'task.completed', handler: (payload: {
+        task: TaskSpec;
+        result: TaskResult;
+    }) => void): () => void;
+}
+//# sourceMappingURL=icoordinator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"icoordinator.d.ts","sourceRoot":"","sources":["../../src/coordination/icoordinator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACvF,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B;;;;OAIG;IACH,KAAK,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE/C;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEpG;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAEnG;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAErD;;;OAGG;IACH,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7C;;;OAGG;IACH,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9B;;;;OAIG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1C;;;OAGG;IACH,MAAM,IAAI,iBAAiB,CAAC;IAE5B;;;;OAIG;IACH,gBAAgB,IAAI,UAAU,EAAE,CAAC;IAEjC;;;;;OAKG;IACH,EAAE,CACA,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,MAAM,EAAE,UAAU,CAAA;KAAE,KAAK,IAAI,GACjE,MAAM,IAAI,CAAC;CACf"}

package/dist/coordination/ifleet-manager.d.ts

@@ -0,0 +1,177 @@
+import type { SubagentConfig } from '../types/multi-agent.js';
+import type { FleetBus, FleetUsage } from './fleet-bus.js';
+import type { WorktreeTaskStateUpdate } from './worktree-task-runner.js';
+/**
+ * Interface for fleet-level lifecycle and policy. Covers:
+ * - Spawn lifecycle hooks (canSpawn check, recordSpawn after-effects)
+ * - Budget enforcement (fleet-wide cost cap, spawn count/depth caps)
+ * - Fleet manifest assembly and writing
+ * - Subagent metadata and usage tracking
+ *
+ * `FleetBus` is pure event fan-out and implements no policy.
+ * `FleetManager` encapsulates all fleet-level policy decisions.
+ * `Director` currently owns all of this — this interface lets us
+ * extract it into a swappable component in Phase 5.
+ */
+export interface IFleetManager {
+    /** The FleetBus this manager publishes lifecycle events to. */
+    readonly fleetBus: FleetBus;
+    /**
+     * Snapshot of fleet-wide token usage and cost rollup.
+     * Safe to call from a tool's execute() body.
+     */
+    snapshot(): FleetUsage;
+    /**
+     * Per-subagent metadata captured at spawn time (provider/model/name).
+     * Returns undefined if the subagent is not known to this manager.
+     */
+    getSubagentMeta(id: string): {
+        provider?: string | undefined;
+        model?: string | undefined;
+        name?: string | undefined;
+    } | undefined;
+    /**
+     * Called before a spawn is recorded. Returns a reason string if the
+     * spawn should be rejected (budget cap, depth limit, cost cap, context
+     * overload, etc.), or null to proceed. Director.spawn() calls this
+     * internally.
+     */
+    canSpawn(config: SubagentConfig): {
+        kind: 'max_spawns' | 'max_spawn_depth' | 'max_cost_usd' | 'max_tokens' | 'max_context_load';
+        limit: number;
+        observed: number;
+    } | null;
+    /** Current fleet-wide token/cost ceiling and remaining headroom. */
+    budgetSnapshot?: (() => {
+        maxSpawns: number;
+        usedSpawns: number;
+        remainingSpawns: number;
+        maxTokens: number;
+        usedTokens: number;
+        remainingTokens: number;
+        maxCostUsd: number;
+        usedCostUsd: number;
+        remainingCostUsd: number;
+    }) | undefined;
+    /**
+     * Update the leader agent's current context pressure (tokens used in the
+     * full API request: messages + systemPrompt + toolDefs). The fleet manager
+     * checks this before allowing a new spawn to prevent the leader from
+     * overflowing its context window while orchestrating subagents.
+     */
+    setLeaderContextPressure(tokens: number): void;
+    /**
+     * Assign a memorable nickname (e.g. "Einstein (Bug Hunter)") and mark it
+     * as used so it is never reused. The nickname is written back to `config.name`
+     * so the coordinator and manifest both see the human-readable name.
+     *
+     * NOTE: This only assigns the nickname. The caller MUST call `recordSpawn`
+     * after `coordinator.spawn()` returns with the real subagentId.
+     *
+     * Returns the assigned nickname string.
+     */
+    assignNicknameAndRecord(config: SubagentConfig): string;
+    /**
+     * Readonly view of already-assigned nickname keys. Used by `Director.spawn()`
+     * to avoid assigning the same nickname twice across the fleet.
+     */
+    readonly usedNicknames: ReadonlySet<string>;
+    /**
+     * Called after a spawn succeeds. Records metadata for the usage
+     * aggregator and manifest.
+     *
+     * @param priceLookup Per-token rate lookup for cost calculation.
+     *   When omitted the cost column in usage snapshots stays at 0.
+     */
+    recordSpawn(subagentId: string, config: SubagentConfig, priceLookup?: Record<string, number>): void;
+    /**
+     * Write the fleet manifest to disk. Returns the path written
+     * or null when no manifest path is configured.
+     */
+    writeManifest(): Promise<string | null>;
+    /**
+     * Bypass the debounce timer and write the manifest immediately.
+     * Clears any pending debounce timer before writing.
+     */
+    flushManifest(): Promise<void>;
+    /**
+     * Aggregate fleet-wide status: pending tasks with descriptions and
+     * live subagent snapshot from the coordinator. Used by
+     * `MultiAgentHost.status()` to eliminate host-side state duplication.
+     */
+    getFleetStatus(): {
+        pending: {
+            taskId: string;
+            description: string;
+            subagentId: string;
+        }[];
+        live: {
+            subagentId: string;
+            status: string;
+            task?: string | undefined;
+        }[];
+    };
+    /**
+     * Register a pending task with its description. Called by
+     * `MultiAgentHost.spawn()` after `_spawnAndAssign()` returns so
+     * the description is available in `status()` without host-side storage.
+     */
+    addPendingTask(taskId: string, subagentId: string, description: string): void;
+    /** Record the latest git-worktree lifecycle state for a task. */
+    recordTaskWorktree(update: WorktreeTaskStateUpdate): void;
+    /**
+     * Remove a pending task. Called when the task completes so the
+     * pending list stays accurate.
+     */
+    removePendingTask(taskId: string): void;
+    /**
+     * Wire the coordinator so `getFleetStats()` can delegate to it.
+     * Called by `Director` after constructing the coordinator so
+     * FleetManager's stats reflect live subagent data.
+     */
+    setCoordinator(coordinator: {
+        getStats(): {
+            total: number;
+            running: number;
+            idle: number;
+            stopped: number;
+            inFlight: number;
+            pending: number;
+            completed: number;
+        };
+    }): void;
+    /**
+     * Coordinator stats snapshot for the TUI and monitoring tools.
+     * Returns actionable counts (total/running/idle/stopped/inFlight/
+     * pending/completed) plus per-subagent status details.
+     * Delegates to the coordinator when available; returns zeros
+     * if the coordinator has not yet been set.
+     */
+    getFleetStats(): {
+        total: number;
+        running: number;
+        idle: number;
+        stopped: number;
+        inFlight: number;
+        pending: number;
+        completed: number;
+        subagentStatuses: {
+            subagentId: string;
+            taskId: string;
+            status: string;
+            assigned: boolean;
+        }[];
+    };
+    /**
+     * Called when a subagent is removed so the fleet manager can clean up
+     * associated state (nickname slots, pending tasks, etc.).
+     */
+    removeSubagent(subagentId: string): void;
+    /**
+     * Release all resources held by the fleet manager.
+     * Clears any pending manifest debounce timer and disposes the usage aggregator.
+     * Call this when the fleet manager is no longer needed (e.g. process shutdown).
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=ifleet-manager.d.ts.map

package/dist/coordination/ifleet-manager.d.ts.map

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

package/dist/coordination/in-memory-transport.d.ts

@@ -0,0 +1,12 @@
+import type { BridgeMessage, BridgeTransport } from '../types/agent-bridge.js';
+/**
+ * In-memory pub/sub transport for agent-to-agent messaging.
+ * Subscribers register by agentId and receive messages via callback.
+ */
+export declare class InMemoryBridgeTransport implements BridgeTransport {
+    private readonly subs;
+    send(msg: BridgeMessage, to: string): Promise<void>;
+    subscribe(agentId: string, handler: (msg: BridgeMessage) => void): () => void;
+    close(agentId: string): Promise<void>;
+}
+//# sourceMappingURL=in-memory-transport.d.ts.map

package/dist/coordination/in-memory-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-transport.d.ts","sourceRoot":"","sources":["../../src/coordination/in-memory-transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAE/E;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,eAAe;IAC7D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAwD;IAE7E,IAAI,CAAC,GAAG,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA0BlD;IAED,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,IAAI,GAAG,MAAM,IAAI,CAI5E;IAED,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGpC;CACF"}