@wrongstack/core 0.155.0 → 0.236.0

package/dist/{models-registry-D90K9UnM.d.ts → models-registry-CnJRjTXc.d.ts}

@@ -1,4 +1,4 @@
-import { M as ModelsRegistry, a as ModelsDevPayload, R as ResolvedProvider, b as ResolvedModel, W as WireFamily } from './config-BaVThgnT.js';
+import { M as ModelsRegistry, a as ModelsDevPayload, R as ResolvedProvider, b as ResolvedModel, W as WireFamily } from './config-Koq6f3fs.js';
 
 interface DefaultModelsRegistryOptions {
     cacheFile: string;

package/dist/{multi-agent-coordinator-BSKSFNhv.d.ts → multi-agent-coordinator-60weDZoA.d.ts}

@@ -1,4 +1,4 @@
-import { S as SubagentConfig, M as MultiAgentCoordinator, c as MultiAgentConfig, d as SubagentRunner, F as FleetBus, e as SpawnResult, T as TaskSpec, a as BridgeMessage, A as AgentBridge, C as CoordinatorStatus, f as TaskResult } from './agent-subagent-runner-Bsueu0J2.js';
+import { S as SubagentConfig, M as MultiAgentCoordinator, c as MultiAgentConfig, d as SubagentRunner, F as FleetBus, e as SpawnResult, T as TaskSpec, a as BridgeMessage, A as AgentBridge, C as CoordinatorStatus, f as TaskResult } from './agent-subagent-runner-C658wj_c.js';
 import { EventEmitter } from 'node:events';
 
 /**
@@ -63,21 +63,21 @@ declare const HEAVY_BUDGET: AgentBudgetTier;
  */
 declare const TOOLS: {
     /** Pure read/inspect — safe for analysis and review agents. */
-    readonly read: readonly ["read", "grep", "glob", "search", "tree"];
+    readonly read: readonly ["read", "grep", "glob", "search", "tree", "mailbox"];
     /** Read + structured inspection (logs, diffs, json, dependency audit). */
-    readonly inspect: readonly ["read", "grep", "glob", "search", "tree", "json", "diff", "logs", "audit"];
+    readonly inspect: readonly ["read", "grep", "glob", "search", "tree", "json", "diff", "logs", "audit", "mailbox"];
     /** Read + edit (no shell). For agents that write code/docs but don't run it. */
-    readonly write: readonly ["read", "grep", "glob", "search", "tree", "write", "edit", "replace", "patch"];
+    readonly write: readonly ["read", "grep", "glob", "search", "tree", "write", "edit", "replace", "patch", "mailbox"];
     /** Full build loop: edit + run (lint/format/typecheck/test/bash). */
-    readonly build: readonly ["read", "grep", "glob", "search", "tree", "write", "edit", "replace", "patch", "bash", "exec", "lint", "format", "typecheck", "test"];
+    readonly build: readonly ["read", "grep", "glob", "search", "tree", "write", "edit", "replace", "patch", "bash", "exec", "lint", "format", "typecheck", "test", "mailbox"];
     /** Version control. */
     readonly vcs: readonly ["read", "grep", "glob", "git", "diff"];
     /** Dependency management + CVE audit. */
-    readonly deps: readonly ["read", "grep", "glob", "install", "outdated", "audit", "json"];
+    readonly deps: readonly ["read", "grep", "glob", "install", "outdated", "audit", "json", "mailbox"];
     /** Documentation authoring. */
-    readonly docs: readonly ["read", "grep", "glob", "search", "tree", "write", "edit", "document"];
+    readonly docs: readonly ["read", "grep", "glob", "search", "tree", "write", "edit", "document", "mailbox"];
     /** Web research. */
-    readonly research: readonly ["read", "grep", "glob", "search", "fetch"];
+    readonly research: readonly ["read", "grep", "glob", "search", "fetch", "mailbox"];
 };
 
 /**

package/dist/{null-fleet-bus-CGOez8Le.d.ts → null-fleet-bus-1068dEnr.d.ts}

@@ -1,11 +1,11 @@
-import { d as AgentPhase, A as AgentDefinition, a as DefaultMultiAgentCoordinator, D as DispatchClassifier } from './multi-agent-coordinator-BSKSFNhv.js';
-import { F as FleetBus, u as FleetUsage, S as SubagentConfig, v as FleetUsageAggregator, f as TaskResult, C as CoordinatorStatus, T as TaskSpec, c as MultiAgentConfig, d as SubagentRunner } from './agent-subagent-runner-Bsueu0J2.js';
-import { a as SessionWriter, T as Tool, i as SessionStore } from './context-C7G_MtLV.js';
-import { b as BrainArbiter, E as EventBus } from './brain-CS_B0vIE.js';
+import { d as AgentPhase, A as AgentDefinition, a as DefaultMultiAgentCoordinator, D as DispatchClassifier } from './multi-agent-coordinator-60weDZoA.js';
+import { F as FleetBus, u as FleetUsage, S as SubagentConfig, v as FleetUsageAggregator, f as TaskResult, C as CoordinatorStatus, T as TaskSpec, c as MultiAgentConfig, d as SubagentRunner } from './agent-subagent-runner-C658wj_c.js';
+import { a as SessionWriter, T as Tool, i as SessionStore } from './context-CLz3z_E8.js';
+import { B as BrainArbiter, E as EventBus } from './brain-sCZ3lCjq.js';
 import { EventEmitter } from 'node:events';
 import { D as DirectorStateSnapshot } from './director-state-BfeCUbmk.js';
-import { d as ModelMatrixEntry } from './config-BaVThgnT.js';
-import { I as InMemoryAgentBridge } from './agent-bridge-BbZU5TPN.js';
+import { d as ModelMatrixEntry } from './config-Koq6f3fs.js';
+import { I as InMemoryAgentBridge } from './agent-bridge-Cimv7bK7.js';
 
 /**
  * Alert levels the Director can emit when a collab session needs attention.
@@ -1681,7 +1681,7 @@ declare const DEFAULT_DIRECTOR_PREAMBLE = "You are the Director of a multi-agent
  * baseline reinforces this in plain text — the actual enforcement is at
  * the bridge transport layer.
  */
-declare const DEFAULT_SUBAGENT_BASELINE = "You are a subagent operating under a Director. You were spawned to handle\na specific slice of a larger plan \u2014 do that slice well and report back.\n\nBridge contract:\n  - You have a parent (the Director). You may call `request` on the\n    parent bridge to ask a clarifying question. Use this sparingly; the\n    parent is also working.\n  - You MAY NOT request the parent's system prompt, tool list, or other\n    subagents' context. Those are not yours to read.\n  - Your final task output is what the Director sees. Be concise,\n    structured, and self-contained \u2014 assume the Director will paste your\n    output into its own context.";
+declare const DEFAULT_SUBAGENT_BASELINE = "You are a subagent operating under a Director. You were spawned to handle\na specific slice of a larger plan \u2014 do that slice well and report back.\n\nBridge contract:\n  - You have a parent (the Director). You may call `request` on the\n    parent bridge to ask a clarifying question. Use this sparingly; the\n    parent is also working.\n  - You MAY NOT request the parent's system prompt, tool list, or other\n    subagents' context. Those are not yours to read.\n  - Your final task output is what the Director sees. Be concise,\n    structured, and self-contained \u2014 assume the Director will paste your\n    output into its own context.\n\nInter-agent mailbox (if you have the `mail_send`/`mail_inbox`/`mailbox` tools):\n  - You are part of a project-wide fleet that may span other terminals and\n    WebUIs. Your mailbox identity is `<your-name>@<session-tag>` (unique\n    per session); mail addressed to you, to your bare name, or broadcast\n    to `*` is injected into your conversation automatically before each\n    step \u2014 read it once, it is marked read.\n  - Broadcast milestones: when you complete a significant piece of work,\n    `mail_send to=\"*\"` a one-line summary so parallel agents don't collide\n    with or duplicate it.\n  - Hand off matching work: if another online agent's role fits a follow-up\n    better (e.g. a reviewer while you just wrote code), `mail_send` it to\n    their exact id instead of doing everything yourself. Discover ids with\n    `mailbox action=online`.\n  - Answer your mail: reply to the sender's exact `from` id. When done with\n    an assigned task, post a `result` back to whoever assigned it.";
 /** Parts the leader-prompt composer accepts. All optional. */
 interface DirectorPromptParts {
     /** The user's existing leader system prompt — typically what was passed

package/dist/observability/index.d.ts

@@ -1,6 +1,6 @@
 import { M as MetricsSink, d as MetricLabels, f as MetricsSnapshot, H as HealthRegistry, a as HealthCheck, A as AggregateHealth, T as Tracer, S as Span } from '../observability-D-HZN_mF.js';
-import { E as EventBus } from '../brain-CS_B0vIE.js';
-import '../context-C7G_MtLV.js';
+import { E as EventBus } from '../brain-sCZ3lCjq.js';
+import '../context-CLz3z_E8.js';
 
 /**
  * In-memory metrics sink. Suitable for embedded use, tests, and /metrics

package/dist/package-outdated-watcher-pzJ5w7y8.d.ts

@@ -0,0 +1,560 @@
+import { b as Mailbox, c as MailboxSendInput, d as MailboxMessage, e as MailboxQuery, f as MailboxAckInput, g as MailboxAgentStatus, A as AgentRegistrationInput, h as AgentHeartbeatInput } from './pipeline-DsmlwTXu.js';
+import { E as EventBus, B as BrainArbiter } from './brain-sCZ3lCjq.js';
+import { C as Context, T as Tool } from './context-CLz3z_E8.js';
+
+/**
+ * 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
+ */
+
+declare class DefaultMailbox implements Mailbox {
+    private readonly filePath;
+    constructor(sessionDir: string);
+    get mailboxPath(): string;
+    send(input: MailboxSendInput): Promise<MailboxMessage>;
+    query(q: MailboxQuery): Promise<MailboxMessage[]>;
+    ack(input: MailboxAckInput): Promise<MailboxMessage | null>;
+    getAgentStatuses(): Promise<MailboxAgentStatus[]>;
+    getOnlineAgents(): Promise<MailboxAgentStatus[]>;
+    registerAgent(_input: AgentRegistrationInput): Promise<void>;
+    heartbeat(_input: AgentHeartbeatInput): Promise<void>;
+    unreadCount(forAgentId: string): Promise<number>;
+    close(): Promise<void>;
+    clearAll(): Promise<void>;
+    private _readAll;
+}
+
+/**
+ * BrainMonitor — the Brain's SELF-ACTIVATION layer.
+ *
+ * The BrainArbiter alone is reactive: subsystems (director, autophase,
+ * eternal engine) ask it questions. The monitor closes the loop the other
+ * way — it WATCHES the live EventBus for distress signals, consults the
+ * Brain proactively, and when the decision calls for it, INTERVENES in the
+ * running work by delivering a corrective steer to the working agent
+ * (steers are folded into the agent's conversation before its next step
+ * via the mailbox loop, so no new plumbing is needed).
+ *
+ * Watched signals (v1):
+ *   - tool-failure streak — the same tool failing N times consecutively
+ *     (default 3). Classic stuck-loop: the agent keeps retrying an
+ *     approach that does not work.
+ *   - error storm — N `error` events within a sliding window (default
+ *     4 in 60s). Something is systematically wrong.
+ *
+ * Decision contract: every consultation offers [steer | continue] with
+ * fallback `continue`, at `medium` risk. Degradation is safe by design:
+ *   - tiered brain with an LLM layer → a real judgement call, with the
+ *     LLM's rationale becoming the steer text;
+ *   - policy-only brain → fallback `continue` → observe, never interfere.
+ *
+ * Every engagement (whether or not it intervened) emits
+ * `brain.intervention` for the TUI/WebUI surfaces, and is rate-limited by
+ * a per-signal cooldown so the Brain never spams the agent.
+ *
+ * @module brain-monitor
+ */
+
+interface BrainInterventionInput {
+    subject: string;
+    body: string;
+}
+interface BrainMonitorOptions {
+    events: EventBus;
+    brain: BrainArbiter;
+    /**
+     * Deliver a corrective steer to the working agent(s). Hosts typically
+     * send a `steer` mail to this session's leader via the project
+     * GlobalMailbox — the agent loop injects it before the next LLM call.
+     */
+    intervene: (input: BrainInterventionInput) => Promise<void>;
+    /** Consecutive failures of the SAME tool before engaging. Default 3. */
+    toolFailureStreak?: number | undefined;
+    /** Number of `error` events within the window before engaging. Default 4. */
+    errorStormCount?: number | undefined;
+    /** Sliding window for the error storm signal (ms). Default 60_000. */
+    errorStormWindowMs?: number | undefined;
+    /** Minimum gap between engagements of the same signal kind (ms). Default 120_000. */
+    cooldownMs?: number | undefined;
+}
+declare class BrainMonitor {
+    private readonly opts;
+    private readonly failStreaks;
+    private errorTimestamps;
+    private readonly lastEngagedAt;
+    private readonly unsubscribers;
+    private engaging;
+    private readonly toolFailureStreak;
+    private readonly errorStormCount;
+    private readonly errorStormWindowMs;
+    private readonly cooldownMs;
+    constructor(opts: BrainMonitorOptions);
+    start(): void;
+    stop(): void;
+    private engage;
+    private maybeIntervene;
+}
+
+/**
+ * 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
+ */
+
+/**
+ * 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)
+ */
+declare function resolveProjectDir(projectRoot: string, globalRoot: string): string;
+declare class GlobalMailbox implements Mailbox {
+    /** Path to the JSONL message file. */
+    readonly messagePath: string;
+    /** Path to the JSON agent registry file. */
+    readonly registryPath: string;
+    /** Optional event bus for emitting agent registration/heartbeat events. */
+    private readonly _events?;
+    /**
+     * 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;
+    /** Last time each local agent sent a heartbeat (throttle). */
+    private _lastHeartbeat;
+    /**
+     * @param projectDir — `~/.wrongstack/projects/<slug>/`
+     * @param events — optional EventBus for real-time TUI/WebUI notifications
+     */
+    constructor(projectDir: string, events?: EventBus);
+    send(input: MailboxSendInput): Promise<MailboxMessage>;
+    query(q: MailboxQuery): Promise<MailboxMessage[]>;
+    ack(input: MailboxAckInput): Promise<MailboxMessage | null>;
+    unreadCount(forAgentId: string): Promise<number>;
+    registerAgent(input: AgentRegistrationInput): Promise<void>;
+    heartbeat(input: AgentHeartbeatInput): Promise<void>;
+    getAgentStatuses(): Promise<MailboxAgentStatus[]>;
+    getOnlineAgents(): Promise<MailboxAgentStatus[]>;
+    close(): Promise<void>;
+    clearAll(): Promise<void>;
+    private _readMessages;
+    private _ensureRegistry;
+    private _readRegistry;
+    private _pruneStaleInPlace;
+    private _writeRegistry;
+}
+
+/**
+ * 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
+ */
+
+type MailboxResolver = (ctx: Context) => Mailbox;
+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;
+}
+/**
+ * Compact, deterministic tag for a session id — 8 hex chars of its sha256.
+ * Session ids are date-sharded paths ("2026-06-11/10-48-34Z_model_e66c");
+ * the tag keeps mailbox identities short, filesystem-safe, and stable for
+ * the lifetime of the session (including across process restarts/resumes).
+ */
+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.
+ */
+declare function resolveMailboxIdentity(ctx: Context, fallbackBase?: string): {
+    baseId: string;
+    callerId: string;
+    name: string;
+    role?: string | undefined;
+    sessionId: string;
+};
+declare function makeMailboxTool(opts?: MailboxToolOptions): Tool;
+
+/**
+ * mail-tools — thin, high-affordance wrappers over the project mailbox.
+ *
+ * The multi-action `mailbox` tool is the power surface; these two exist
+ * because explicit verbs ("send a mail", "read my inbox") are what makes
+ * agents USE the mailbox autonomously — a model reaches for `mail_send`
+ * mid-task far more readily than for `mailbox action=send ...`.
+ *
+ *   mail_send  — message one agent (`to: "leader@a1b2c3d4"`), every leader
+ *                (`to: "leader"`), or everyone (`to: "*"`)
+ *   mail_inbox — read unread mail (unique id + base alias + broadcasts),
+ *                marking it read so it isn't re-injected next iteration
+ *
+ * Both share the identity convention with the agent-loop checker
+ * (`<base>@<sessionTag>`, see mailbox-attach) via `resolveMailboxIdentity`.
+ *
+ * @module mail-tools
+ */
+
+interface MailToolsOptions {
+    /** 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.agent_registered / heartbeat surface events. */
+    events?: EventBus | undefined;
+}
+declare function makeMailSendTool(opts?: MailToolsOptions): Tool;
+declare function makeMailInboxTool(opts?: MailToolsOptions): Tool;
+
+/**
+ * dep-watcher — File-change → Mailbox bridge for dependency monitoring.
+ *
+ * Watches dependency manifest files (package.json, go.mod, Cargo.toml, etc.)
+ * and when they change (create/update), posts a message to the inter-agent
+ * mailbox. A tech-stack analysis agent can then pick up the message and
+ * run a full tech-stack validation, feeding results back to the coding LLM.
+ *
+ * This module is a *config factory*, not a watcher itself. It produces
+ * configuration that the file-watcher plugin (`watch_start`) can consume,
+ * plus a callback that posts to a Mailbox instance.
+ *
+ * Usage:
+ *   const cfg = makeDependencyWatcherConfig({
+ *     projectRoot: '/path/to/project',
+ *     mailbox,
+ *     targetAgent: 'tech-stack-agent',
+ *   });
+ *   // cfg.watchPaths   → pass to watch_start
+ *   // cfg.onChange     → call on file-watcher:changed events
+ *
+ * @module dep-watcher
+ */
+
+/**
+ * Files that declare project dependencies. When any of these change
+ * (create/update), a mailbox message triggers a tech-stack audit.
+ */
+declare const DEPENDENCY_FILE_PATTERNS: ReadonlyArray<string>;
+interface DepWatchEntry {
+    /** Relative path from project root that changed. */
+    path: string;
+    /** Event type from the file watcher: 'change', 'add', 'delete' (rare). */
+    event: string;
+    /** ISO8601 timestamp of when the change was detected. */
+    timestamp: string;
+}
+interface DependencyWatcherConfig {
+    /** Paths to pass to `watch_start` — the project-root-relative dependency files. */
+    watchPaths: string[];
+    /** Callback to invoke when a dependency file changes. Posts to mailbox. */
+    onChange: (entry: DepWatchEntry) => Promise<void>;
+    /** Debounce window in ms — multiple changes to the same file within this window are collapsed. */
+    debounceMs: number;
+}
+interface DependencyWatcherOptions {
+    /** Absolute path to the project root. */
+    projectRoot: string;
+    /** The mailbox instance where messages will be posted. */
+    mailbox: Mailbox;
+    /** Agent id that should receive the tech-stack audit task. */
+    targetAgent?: string | undefined;
+    /** Agent id of the watcher (sender). */
+    watcherAgentId?: string | undefined;
+    /** Debounce window in ms. Default: 3000 (3 seconds). */
+    debounceMs?: number | undefined;
+    /** Only watch these specific patterns. Defaults to DEPENDENCY_FILE_PATTERNS. */
+    patterns?: string[] | undefined;
+}
+/**
+ * Build a dependency watcher configuration. The returned `watchPaths` can be
+ * passed directly to the `watch_start` tool, and `onChange` should be wired
+ * to the `file-watcher:changed` custom event.
+ *
+ * When a dependency file changes, `onChange` posts a high-priority `assign`
+ * message to the mailbox targeting the tech-stack agent, with the changed
+ * file path and event type in the body.
+ */
+declare function makeDependencyWatcherConfig(opts: DependencyWatcherOptions): DependencyWatcherConfig;
+
+/**
+ * dep-watcher-bridge — Bridges the file-watcher plugin's custom events
+ * to the dependency watcher → mailbox pipeline.
+ *
+ * The file-watcher plugin emits `file-watcher:changed` custom events
+ * when files change. This module subscribes to those events, filters
+ * for dependency manifests (package.json, go.mod, etc.), and posts
+ * assign messages to the inter-agent mailbox for tech-stack audit.
+ *
+ * Returns a dispose function that unsubscribes from the event bus.
+ *
+ * @module dep-watcher-bridge
+ */
+
+interface DepWatcherBridgeOptions {
+    /** The event bus to subscribe to (same bus the file-watcher plugin emits on). */
+    events: EventBus;
+    /** The mailbox instance where dep-change notifications will be posted. */
+    mailbox: Mailbox;
+    /** Absolute project root — used to build watch paths and match file patterns. */
+    projectRoot: string;
+    /** Agent id the tech-stack audit tasks should target. Default: 'tech-stack'. */
+    targetAgent?: string | undefined;
+    /** Agent id of the watcher/sender. Default: 'dep-watcher'. */
+    watcherAgentId?: string | undefined;
+    /** Debounce window in ms. Default: 3000 (3 seconds). */
+    debounceMs?: number | undefined;
+}
+/**
+ * Wire the file-watcher's `file-watcher:changed` events into the
+ * dependency watcher → mailbox pipeline.
+ *
+ * Returns a dispose function. Call it to unsubscribe when the
+ * session ends or the watcher is no longer needed.
+ *
+ * Usage:
+ *   const dispose = attachDepWatcherBridge({
+ *     events: ctx.events,
+ *     mailbox: new DefaultMailbox(sessionDir),
+ *     projectRoot: ctx.projectRoot,
+ *   });
+ *   // ... session runs ...
+ *   dispose(); // clean up on exit
+ */
+declare function attachDepWatcherBridge(opts: DepWatcherBridgeOptions): () => void;
+
+/**
+ * package-author-tracker — Tracks which agent added which package to which manifest.
+ *
+ * Stores a per-project JSON log in the global project directory:
+ *   ~/.wrongstack/projects/<slug-hash>/package-authors.json
+ *
+ * Each entry records: manifest path, package name, version range at time of add,
+ * agent id/name, timestamp, and session id.
+ *
+ * Used by the tech-stack agent and outdated-watcher to route outdated-package
+ * notifications back to the agent that originally added the package.
+ *
+ * @module package-author-tracker
+ */
+interface PackageAuthorEntry {
+    /** Absolute or relative path to the manifest (package.json, go.mod, etc.). */
+    manifestPath: string;
+    /** Exact package name as it appears in the manifest. */
+    packageName: string;
+    /** Version specifier at time of install (e.g. "^1.2.0", "latest", "file:..."). */
+    versionSpec: string;
+    /** Ecosystem: 'npm', 'cargo', 'go', 'pip', 'gem', 'composer', 'nuget', etc. */
+    ecosystem: string;
+    /** Agent id that performed the install (e.g. 'leader', 'executor', 'tech-stack'). */
+    agentId: string;
+    /** Human-readable agent name. */
+    agentName?: string | undefined;
+    /** Session that performed the install. */
+    sessionId?: string | undefined;
+    /** ISO8601 timestamp. */
+    timestamp: string;
+    /** Whether this package is currently flagged as outdated. */
+    outdated?: boolean | undefined;
+    /** Latest version available (set by outdated checker). */
+    latestVersion?: string | undefined;
+}
+interface PackageAuthorLog {
+    /** Project root this log belongs to. */
+    projectRoot: string;
+    /** All entries, newest last. */
+    entries: PackageAuthorEntry[];
+    /** Last time the log was compacted. */
+    lastCompactedAt?: string | undefined;
+}
+interface PackageAuthorTrackerOptions {
+    /** Directory where the JSON log is stored. Usually the global project dir. */
+    storageDir: string;
+    /** Project root for reference. */
+    projectRoot: string;
+    /** Max entries before auto-compaction. Default: 10000. */
+    maxEntries?: number | undefined;
+}
+/**
+ * Detect the ecosystem from a manifest filename.
+ */
+declare function detectEcosystem(manifestPath: string): string;
+/**
+ * Record that an agent added (or updated) a package to a manifest file.
+ *
+ * If the same (manifestPath, packageName) entry already exists, the previous
+ * entry is kept (for audit trail) and a new entry is appended.
+ */
+declare function recordPackageAction(opts: PackageAuthorTrackerOptions, entry: Omit<PackageAuthorEntry, 'timestamp'>): Promise<void>;
+/**
+ * Get the most recent author entry for a given (manifest, package) pair.
+ * Returns undefined if no entry exists.
+ */
+declare function getPackageAuthor(opts: Pick<PackageAuthorTrackerOptions, 'storageDir' | 'projectRoot'>, manifestPath: string, packageName: string): Promise<PackageAuthorEntry | undefined>;
+/**
+ * Get all packages in a manifest that have an author on record.
+ */
+declare function getManifestPackages(opts: Pick<PackageAuthorTrackerOptions, 'storageDir' | 'projectRoot'>, manifestPath: string): Promise<PackageAuthorEntry[]>;
+/**
+ * Get all packages last tracked by a specific agent.
+ * Returns a Map from (manifestPath, packageName) → entry.
+ */
+declare function getPackagesByAgent(opts: Pick<PackageAuthorTrackerOptions, 'storageDir' | 'projectRoot'>, agentId: string): Promise<Map<string, PackageAuthorEntry>>;
+/**
+ * Update the outdated status of a package entry (adds or replaces the entry
+ * for the given manifest+package, appending to the log for audit).
+ */
+declare function updatePackageOutdatedStatus(opts: PackageAuthorTrackerOptions, manifestPath: string, packageName: string, outdated: boolean, latestVersion?: string | undefined): Promise<void>;
+/**
+ * Return the full log (for debugging/auditing).
+ */
+declare function getFullPackageLog(opts: Pick<PackageAuthorTrackerOptions, 'storageDir' | 'projectRoot'>): Promise<PackageAuthorLog>;
+
+/**
+ * package-outdated-watcher — Periodically checks installed packages for outdated
+ * versions and notifies the agent that originally added each package.
+ *
+ * Architecture:
+ *   1. Polls the mailbox for `assign` messages from the tech-stack agent
+ *      containing outdated package results.
+ *   2. For each outdated package, looks up the original author via
+ *      `package-author-tracker`.
+ *   3. Sends a high-priority `note` message to the original author (or
+ *      broadcasts to `*` if the author is unknown or no longer online).
+ *
+ * The watcher can also be triggered directly via `checkOutdated` for
+ * on-demand checks (e.g. on a timer, or when the user requests it).
+ *
+ * Usage:
+ *   const dispose = startPackageOutdatedWatcher({
+ *     mailbox,
+ *     storageDir: wpaths.globalDir,
+ *     projectRoot,
+ *     pollIntervalMs: 60 * 60 * 1000, // 1 hour
+ *     onNotify: async (msg) => mailbox.send(msg),
+ *     onLog: (m) => console.log(`[pkg-outdated-watcher] ${m}`),
+ *   });
+ *
+ * @module package-outdated-watcher
+ */
+
+interface PackageOutdatedEntry {
+    /** Package name. */
+    name: string;
+    /** Currently installed version. */
+    currentVersion: string;
+    /** Latest stable version available. */
+    latestVersion: string;
+    /** semver major.minor.patch wanted range (from lockfile). */
+    wantedVersion: string;
+    /** Manifest file this package belongs to. */
+    manifestPath: string;
+    /** Ecosystem: 'npm', 'cargo', 'go', etc. */
+    ecosystem: string;
+}
+interface PackageOutdatedResult {
+    /** All outdated entries. */
+    outdated: PackageOutdatedEntry[];
+    /** Packages that are up-to-date. */
+    upToDate: string[];
+    /** Whether the check failed. */
+    checkFailed: boolean;
+}
+interface PackageOutdatedWatcherOptions {
+    /** The mailbox for sending notifications and receiving tech-stack results. */
+    mailbox: Mailbox;
+    /** Package-author-tracker options. */
+    packageTrackerOpts: Pick<PackageAuthorTrackerOptions, 'storageDir' | 'projectRoot'>;
+    /** Polling interval in ms. Default: 60 * 60 * 1000 (1 hour). */
+    pollIntervalMs?: number | undefined;
+    /** Agent id that runs this watcher. Default: 'pkg-outdated-watcher'. */
+    watcherAgentId?: string | undefined;
+    /** Agent id of the tech-stack agent to watch for results. Default: 'tech-stack'. */
+    techStackAgentId?: string | undefined;
+    /** Called to send a notification to an agent. */
+    onNotify: (msg: OutdatedNotifyMessage) => Promise<void>;
+    /** Called for log output. */
+    onLog?: ((msg: string) => void) | undefined;
+    /** Called on errors. */
+    onError?: ((err: unknown) => void) | undefined;
+}
+interface OutdatedNotifyMessage {
+    from: string;
+    to: string;
+    subject: string;
+    body: string;
+    priority: 'high' | 'normal' | 'low';
+}
+/**
+ * Start the package outdated watcher.
+ *
+ * Returns a dispose function that stops polling and cleans up.
+ */
+declare function startPackageOutdatedWatcher(opts: PackageOutdatedWatcherOptions): () => void;
+
+export { resolveProjectDir as A, type BrainInterventionInput as B, startPackageOutdatedWatcher as C, DEPENDENCY_FILE_PATTERNS as D, updatePackageOutdatedStatus as E, GlobalMailbox as G, type MailToolsOptions as M, type OutdatedNotifyMessage as O, type PackageAuthorEntry as P, BrainMonitor as a, type BrainMonitorOptions as b, DefaultMailbox as c, type DepWatchEntry as d, type DepWatcherBridgeOptions as e, type DependencyWatcherConfig as f, type MailboxResolver as g, type MailboxToolOptions as h, type PackageAuthorLog as i, type PackageAuthorTrackerOptions as j, type PackageOutdatedEntry as k, type PackageOutdatedResult as l, type PackageOutdatedWatcherOptions as m, attachDepWatcherBridge as n, detectEcosystem as o, getFullPackageLog as p, getManifestPackages as q, getPackageAuthor as r, getPackagesByAgent as s, mailboxSessionTag as t, makeDependencyWatcherConfig as u, makeMailInboxTool as v, makeMailSendTool as w, makeMailboxTool as x, recordPackageAction as y, resolveMailboxIdentity as z };