@wrongstack/core 0.284.1 → 0.285.0

package/dist/coordination/fleet-spawn.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Fleet spawn / assign / terminate / awaitTasks / remove for the Director.
+ *
+ * Owns the methods that hand work to the `MultiAgentCoordinator` and
+ * tear it down: `spawn`, `assign`, `awaitTasks`, `terminate`,
+ * `terminateAll`, `remove`. Extracted out of `director.ts` to keep
+ * that file under review-able size.
+ *
+ * Public surface (called from `Director` methods):
+ *   - `spawn`        — create a new subagent
+ *   - `assign`       — hand a task to a (possibly new) subagent
+ *   - `awaitTasks`   — block until a set of tasks resolve
+ *   - `terminate`    — stop a single subagent
+ *   - `terminateAll` — stop every subagent
+ *   - `remove`       — drop a subagent from internal indexes
+ */
+import type { DirectorStateCheckpoint } from '../storage/director-state.js';
+import type { SubagentConfig, TaskResult, TaskSpec } from '../types/multi-agent.js';
+import { InMemoryAgentBridge } from './agent-bridge.js';
+import type { ModelMatrixSource } from './director.js';
+import type { FleetBus, FleetUsageAggregator } from './fleet-bus.js';
+import type { FleetManager } from './fleet-manager.js';
+import type { InMemoryBridgeTransport } from './in-memory-transport.js';
+import type { DefaultMultiAgentCoordinator } from './multi-agent-coordinator.js';
+/**
+ * Narrow interface the helpers in this file need from the Director.
+ * Kept here (instead of importing the full Director class) to avoid a
+ * circular import: director.ts re-exports the helpers.
+ */
+export interface DirectorFleetHost {
+    readonly id: string;
+    readonly coordinator: DefaultMultiAgentCoordinator;
+    readonly fleet: FleetBus;
+    readonly transport: InMemoryBridgeTransport;
+    readonly stateCheckpoint: DirectorStateCheckpoint | null;
+    workCompleteFlag: boolean;
+    spawnCount: number;
+    readonly maxSpawns: number;
+    readonly maxSpawnDepth: number;
+    readonly spawnDepth: number;
+    readonly maxFleetCostUsd: number;
+    readonly maxFleetTokens?: number | undefined;
+    readonly maxLeaderContextLoad: number;
+    leaderContextPressure: number;
+    readonly modelMatrix?: ModelMatrixSource | undefined;
+    readonly usage: FleetUsageAggregator;
+    readonly fleetManager: FleetManager | undefined;
+    readonly manifestEntries: Map<string, unknown>;
+    readonly completed: Map<string, TaskResult>;
+    readonly subagentBridges: Map<string, InMemoryAgentBridge>;
+    readonly taskWaiters: Map<string, {
+        promise: Promise<TaskResult>;
+        resolve: (r: TaskResult) => void;
+    }>;
+    readonly subagentMeta: Map<string, {
+        provider?: string | undefined;
+        model?: string | undefined;
+    }>;
+    readonly taskDescriptions: Map<string, string>;
+    readonly taskOwners: Map<string, string>;
+    readonly priceLookups: Map<string, {
+        input?: number | undefined;
+        output?: number | undefined;
+        cacheRead?: number | undefined;
+        cacheWrite?: number | undefined;
+    }>;
+    readonly _usedNicknames: Set<string>;
+    appendSessionEvent(event: unknown): Promise<void>;
+    scheduleManifest(): void;
+    resolveMaxContext(): number;
+}
+/**
+ * Spawn a subagent. See `Director.spawn` for the full contract.
+ */
+export declare function spawn(host: DirectorFleetHost, config: SubagentConfig, priceLookup?: {
+    input?: number | undefined;
+    output?: number | undefined;
+    cacheRead?: number | undefined;
+    cacheWrite?: number | undefined;
+}): Promise<string>;
+/**
+ * Hand a task to the coordinator. Returns the assigned task id so
+ * callers can wait on it via `awaitTasks([id])`. The coordinator's
+ * concurrency limit applies — the task may queue before running.
+ *
+ * `appendTaskDescription` and `recordTaskOwner` are injected because
+ * they touch Director's `taskDescriptions` / `taskOwners` Maps which
+ * are out of scope for this file's surface.
+ */
+export declare function assign(host: DirectorFleetHost, task: TaskSpec, taskId: string, appendTaskDescription: (taskId: string, description: string | undefined) => void, recordTaskOwner: (taskId: string, subagentId: string) => void): Promise<string>;
+/** Await a set of tasks by id, preserving input order. */
+export declare function awaitTasks(host: DirectorFleetHost, taskIds: string[]): Promise<TaskResult[]>;
+/** Stop a single subagent by id. */
+export declare function terminate(host: DirectorFleetHost, subagentId: string): Promise<void>;
+/** Stop every subagent managed by the coordinator. */
+export declare function terminateAll(host: DirectorFleetHost): Promise<void>;
+/**
+ * Drop a subagent from the director's local indexes after the coordinator
+ * has already torn it down. Idempotent.
+ */
+export declare function remove(host: DirectorFleetHost, subagentId: string): Promise<void>;
+//# sourceMappingURL=fleet-spawn.d.ts.map

package/dist/coordination/fleet-spawn.d.ts.map

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

package/dist/coordination/fleet-status-tool.d.ts

@@ -0,0 +1,36 @@
+/**
+ * fleet-status-tool — read-only live peer snapshot for any agent.
+ *
+ * The pull half of peer awareness (the push half is the fleet-pulse
+ * digest): any agent — leader or fleet subagent — can ask "who else is
+ * working on this project right now, and on what?" before starting work
+ * that might overlap, or when deciding whether to wait or proceed.
+ *
+ * Data source: the project mailbox registry (`getAgentStatuses`), which is
+ * cross-process by construction. When the host passes `getLocalAgents`
+ * (an AgentStatusTracker view), same-process entries are enriched with the
+ * richer live fields the registry doesn't carry (ctxPct, costUsd,
+ * partialText tail).
+ *
+ * @module fleet-status-tool
+ */
+import type { EventBus } from '../kernel/events.js';
+import type { AgentEntry } from '../session-registry.js';
+import type { Tool } from '../types/tool.js';
+import { type MailboxResolver } from './mailbox-tool.js';
+export interface FleetStatusToolOptions {
+    /** How to obtain a Mailbox given the execution Context (tests). */
+    resolveMailbox?: MailboxResolver | undefined;
+    /** Project dir for the shared mailbox. Prefer wpaths.projectDir. */
+    projectDir?: string | undefined;
+    /** EventBus for mailbox registration surface events. */
+    events?: EventBus | undefined;
+    /**
+     * Same-process rich agent state (AgentStatusTracker snapshot). Merged
+     * into registry rows by name when provided — cross-process peers keep
+     * registry-only fields.
+     */
+    getLocalAgents?: (() => AgentEntry[]) | undefined;
+}
+export declare function makeFleetStatusTool(opts?: FleetStatusToolOptions): Tool;
+//# sourceMappingURL=fleet-status-tool.d.ts.map

package/dist/coordination/fleet-status-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-status-tool.d.ts","sourceRoot":"","sources":["../../src/coordination/fleet-status-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAG7C,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC;AAG3B,MAAM,WAAW,sBAAsB;IACrC,mEAAmE;IACnE,cAAc,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IAC7C,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,wDAAwD;IACxD,MAAM,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC9B;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,UAAU,EAAE,CAAC,GAAG,SAAS,CAAC;CACnD;AASD,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,sBAA2B,GAAG,IAAI,CA0F3E"}

package/dist/coordination/fleet-supervisor.d.ts

@@ -0,0 +1,157 @@
+/**
+ * FleetSupervisor — brain-gated shadow watcher over the generic fleet.
+ *
+ * The Director gives a leader agent orchestration TOOLS; this module gives
+ * the fleet a SUPERVISOR that works even while the leader is deep in its
+ * own task: it continuously watches queue shape + worker activity, detects
+ * imbalance (a pending task starving behind a busy worker while a sibling
+ * idles, a deep backlog, a stuck or repeatedly-failing worker), and — after
+ * clearing every proposal through the tiered BrainArbiter (policy → LLM →
+ * human, honoring the /brain risk ceiling) — acts: retargets pending
+ * tasks ("I'm reducing your workload"), spawns a helper, steers an agent
+ * by mail, notifies the leader, or (opt-in) terminates.
+ *
+ * Design lineage: BrainMonitor (watch bus → decide → intervene, cooldowns,
+ * single engagement in flight) generalized from "steer the leader" to the
+ * full fleet action set; SddSupervisor's brain-verdict contract reused for
+ * the decision step. The SDD subsystem itself is untouched.
+ *
+ * Non-interference guarantees (also pinned by tests):
+ *   - never calls extend/deny on budget negotiations — the Director's
+ *     budgetFilter remains the sole negotiator; we only OBSERVE events
+ *   - never preempts a RUNNING task — only still-pending tasks move
+ *   - never flips autonomy mode
+ *   - dormant once the director declares work complete
+ *
+ * @module fleet-supervisor
+ */
+import type { EventBus } from '../kernel/events.js';
+import type { TaskSpec } from '../types/multi-agent.js';
+import type { FleetSupervisorConfig } from '../types/config.js';
+import type { BrainArbiter } from './brain.js';
+import type { FleetBus } from './fleet-bus.js';
+export type { FleetSupervisorConfig } from '../types/config.js';
+/** One subagent row of the snapshot the supervisor reasons over. */
+export interface SupervisedSubagent {
+    id: string;
+    name: string;
+    status: 'running' | 'idle' | 'stopped' | 'error';
+    currentTask?: string | undefined;
+}
+/** Read port — implemented over Director/coordinator state by the host. */
+export interface FleetSupervisorSource {
+    subagents(): SupervisedSubagent[];
+    listPendingTasks(): readonly TaskSpec[];
+    isWorkComplete(): boolean;
+}
+/** Action port — every mutation the supervisor may perform, brain-gated. */
+export interface FleetSupervisorActions {
+    /** Move a still-pending task to another (or any idle) worker. */
+    retargetPendingTask(taskId: string, subagentId: string | undefined): boolean | Promise<boolean>;
+    /** Spawn an additional helper worker. Return {error} to degrade gracefully. */
+    spawnHelper(input: {
+        reason: string;
+        /** Oldest queued task used to route the helper's role/tool profile. */
+        task?: TaskSpec | undefined;
+    }): Promise<{
+        subagentId: string;
+    } | {
+        error: string;
+    }>;
+    /** High-priority steer mail to one agent. */
+    steerAgent(subagentId: string, subject: string, body: string): Promise<void>;
+    /** Status/steer mail to the session leader. */
+    notifyLeader(subject: string, body: string): Promise<void>;
+    /** Abort a subagent (only used when config.allowTerminate). */
+    terminate(subagentId: string): Promise<void>;
+}
+export interface FleetSupervisorOptions {
+    events: EventBus;
+    fleet: FleetBus;
+    brain: BrainArbiter;
+    source: FleetSupervisorSource;
+    actions: FleetSupervisorActions;
+    /** Active host session id, read lazily (resume/session-swap safe). */
+    sessionId?: (() => string | undefined) | undefined;
+    config?: FleetSupervisorConfig | undefined;
+    /** Injectable clock for tests. Default Date.now. */
+    now?: (() => number) | undefined;
+}
+export interface SupervisorLogEntry {
+    at: number;
+    kind: string;
+    subagentId?: string | undefined;
+    taskId?: string | undefined;
+    proposedAction: string;
+    outcome: 'approved' | 'denied' | 'escalated' | 'skipped' | 'error';
+    detail: string;
+}
+export interface ResolvedSupervisorConfig {
+    enabled: boolean;
+    intervalMs: number;
+    cooldownMs: number;
+    maxInterventionsPerSubagent: number;
+    pinnedWaitMs: number;
+    overloadPinnedThreshold: number;
+    backlogFactor: number;
+    stuckMs: number;
+    failureStreak: number;
+    allowSpawn: boolean;
+    allowTerminate: boolean;
+}
+export declare class FleetSupervisor {
+    private readonly opts;
+    private readonly cfg;
+    private readonly now;
+    private timer;
+    private readonly offHandles;
+    private engaging;
+    private stopped;
+    /** taskId → first tick timestamp we saw it pending. */
+    private readonly pendingSince;
+    /** subagentId → last observable fleet event timestamp. */
+    private readonly lastActivityAt;
+    /** subagentId → consecutive non-success completions. */
+    private readonly failStreaks;
+    /** Consecutive ticks the backlog condition held. */
+    private backlogTicks;
+    /** `${kind}|${subject}` → last engagement ts. */
+    private readonly lastEngagedAt;
+    private readonly interventionsBySubagent;
+    /** Tasks already retargeted once — never bounced twice. */
+    private readonly retargetedTasks;
+    private readonly log;
+    constructor(opts: FleetSupervisorOptions);
+    /** Idempotent; also re-arms after a stop() so `/supervisor on` works. */
+    start(): void;
+    stop(): void;
+    history(): readonly SupervisorLogEntry[];
+    /** True while the evaluation loop is armed. */
+    isRunning(): boolean;
+    /** Resolved (defaulted) configuration — for status surfaces. */
+    configSnapshot(): Readonly<ResolvedSupervisorConfig>;
+    private nudgeTimer;
+    private scheduleNudge;
+    private isCollab;
+    /** One evaluation pass. Public for tests; production runs it on the tick. */
+    evaluate(): Promise<void>;
+    private cooldownOk;
+    private interventionBudgetOk;
+    private recordIntervention;
+    private emitSignal;
+    private record;
+    private emitAction;
+    /**
+     * Ask the brain to approve a proposal. Same contract as BrainMonitor:
+     * `source:'system'`, the rule's proposal `recommended:true`, fallback
+     * 'ask_human' (routes to the LLM tier under the risk ceiling before any
+     * human). Returns the chosen option id, or null for deny/escalate.
+     */
+    private decide;
+    private engageRebalance;
+    private engageBacklog;
+    private engageStuck;
+    private engageFailureStreak;
+    private engageIdleWithWork;
+}
+//# sourceMappingURL=fleet-supervisor.d.ts.map

package/dist/coordination/fleet-supervisor.d.ts.map

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

package/dist/coordination/fleet.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Pre-built subagent role configurations for the WrongStack fleet.
+ * These can be passed to `MultiAgentHost.spawn()` or used as templates
+ * for the director's roster.
+ */
+import type { SubagentConfig } from '../types/multi-agent.js';
+/**
+ * Audit Log Agent — analyzes session logs, event streams, and traces.
+ * Use for: post-mortems, trend analysis, operational insights.
+ */
+export declare const AUDIT_LOG_AGENT: SubagentConfig;
+/**
+ * Bug Hunter Agent — systematic bug and code smell detection.
+ * Use for: pre-refactoring health checks, code review, regression prevention.
+ */
+export declare const BUG_HUNTER_AGENT: SubagentConfig;
+/**
+ * Refactor Planner Agent — structured refactoring planning.
+ * Use for: large rewrites, technical debt reduction, architecture improvements.
+ */
+export declare const REFACTOR_PLANNER_AGENT: SubagentConfig;
+/**
+ * Security Scanner Agent — vulnerability and secret detection.
+ * Use for: CI checks, pre-release audits, dependency vulnerability scanning.
+ */
+export declare const SECURITY_SCANNER_AGENT: SubagentConfig;
+/**
+ * Shadow Agent — one-shot fleet monitoring and intervention.
+ * Use for: quiet anomaly checks and on-demand intervention.
+ */
+export declare const SHADOW_AGENT: SubagentConfig;
+/**
+ * Critic Agent — evaluates code quality, architecture decisions, and
+ * refactoring plans against project conventions and engineering standards.
+ * Use for: real-time evaluation of bug reports, refactor plans, and
+ * architectural proposals during collaborative debugging sessions.
+ */
+export declare const CRITIC_AGENT: SubagentConfig;
+/**
+ * All agents in a map for easy lookup by role. The four legacy pre-built
+ * agents plus the phase 1-9 catalog (`ALL_AGENT_DEFINITIONS`). Catalog roles
+ * are guaranteed collision-free by the catalog builder; none overlap the
+ * legacy four.
+ */
+export declare const FLEET_ROSTER: Record<string, SubagentConfig>;
+export interface FleetRosterBudget {
+    timeoutMs?: number | undefined;
+    /** Idle reap window (ms). Resets on activity — see `applyRosterBudget`. */
+    idleTimeoutMs?: number | undefined;
+    maxIterations?: number | undefined;
+    maxToolCalls?: number | undefined;
+    maxTokens?: number | undefined;
+    maxCostUsd?: number | undefined;
+}
+/**
+ * Default idle window for delegated subagents: reap only after this long with
+ * NO activity (no iteration / tool call / streamed progress). An actively-
+ * working agent resets this clock continuously, so it runs until its task
+ * naturally ends — no more wall-clock kills of productive runs. Power users
+ * can still impose a hard `timeoutMs` per delegate.
+ */
+export declare const DEFAULT_IDLE_TIMEOUT_MS: number;
+export declare const FLEET_ROSTER_BUDGETS: Record<string, FleetRosterBudget>;
+export declare function applyRosterBudget(cfg: SubagentConfig): SubagentConfig;
+/** Quick-access list for spawning all at once. */
+export declare const ALL_FLEET_AGENTS: SubagentConfig[];
+/**
+ * Cline — ACP-compatible coding agent by @asonix.
+ * Spawned as: `npx @agentify/cline`
+ */
+export declare const CLINE_AGENT: SubagentConfig;
+/**
+ * Gemini CLI — Google's ACP-compatible command-line agent.
+ * Spawned as: `gemini` (when gemini CLI is installed and in PATH)
+ */
+export declare const GEMINI_CLI_AGENT: SubagentConfig;
+/**
+ * GitHub Copilot (public preview) — ACP-compatible Copilot CLI agent.
+ * Spawned as: `gh copilot` (when gh CLI with copilot extension is installed)
+ */
+export declare const COPILOT_AGENT: SubagentConfig;
+/**
+ * OpenHands — AI coding agent by all-in.ai, ACP-compatible.
+ * Spawned as: `openhands` (when installed)
+ */
+export declare const OPENHANDS_AGENT: SubagentConfig;
+/**
+ * Goose — IDE agent by ExoRL, ACP-compatible.
+ * Spawned as: `goose` (when goose CLI is installed)
+ */
+export declare const GOOSE_AGENT: SubagentConfig;
+/** All ACP external agents. */
+export declare const ACP_AGENTS: SubagentConfig[];
+/** Extended roster including ACP agents. */
+export declare const FLEET_ROSTER_WITHACP: Record<string, SubagentConfig>;
+//# sourceMappingURL=fleet.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fleet.d.ts","sourceRoot":"","sources":["../../src/coordination/fleet.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAI9D;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,cAW7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,cAO9B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,cAOpC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,cAOpC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,cAO1B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,cAO1B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAUvD,CAAC;AAiBF,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,2EAA2E;IAC3E,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,QAAiB,CAAC;AAEtD,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAgBlE,CAAC;AAiBF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,cAAc,CAmBrE;AAED,kDAAkD;AAClD,eAAO,MAAM,gBAAgB,kBAA8B,CAAC;AAS5D;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,cAMzB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,cAM9B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,cAM3B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,cAM7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,cAMzB,CAAC;AAEF,+BAA+B;AAC/B,eAAO,MAAM,UAAU,EAAE,cAAc,EAMtC,CAAC;AAWF,4CAA4C;AAC5C,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAG/D,CAAC"}

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

@@ -0,0 +1,234 @@
+/**
+ * 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 { AgentHeartbeatInput, AgentRegistrationInput, 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 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?;
+    /**
+     * 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;
+    /**
+     * @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
+     */
+    constructor(projectDir: string, events?: EventBus, hqPublisher?: HqPublisherRef);
+    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>;
+    clientHeartbeat(input: ClientHeartbeatInput): Promise<void>;
+    getClientStatuses(): Promise<ClientStatus[]>;
+    close(): Promise<void>;
+    clearAll(): Promise<void>;
+    purgeStale(opts?: PurgeOptions): Promise<PurgeResult>;
+    /**
+     * 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;
+    /** 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;
+    /**
+     * 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":"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"}