@wrongstack/core 0.284.1 → 0.286.0

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

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

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

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

package/dist/coordination/null-fleet-bus.d.ts

@@ -0,0 +1,10 @@
+import { FleetBus } from './fleet-bus.js';
+/**
+ * A no-op FleetBus that discards all events. Used when no real fleet
+ * bus is available (non-director mode) so the runner's `fleetBus`
+ * field is always valid and the `attach()` call is always safe.
+ *
+ * One singleton instance is sufficient — it has no state to reset.
+ */
+export declare const NULL_FLEET_BUS: FleetBus;
+//# sourceMappingURL=null-fleet-bus.d.ts.map

package/dist/coordination/null-fleet-bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"null-fleet-bus.d.ts","sourceRoot":"","sources":["../../src/coordination/null-fleet-bus.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,UAAiB,CAAC"}

package/dist/coordination/package-author-tracker.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 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
+ */
+export 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;
+}
+export 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;
+}
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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).
+ */
+export declare function updatePackageOutdatedStatus(opts: PackageAuthorTrackerOptions, manifestPath: string, packageName: string, outdated: boolean, latestVersion?: string | undefined): Promise<void>;
+/**
+ * Return the full log (for debugging/auditing).
+ */
+export declare function getFullPackageLog(opts: Pick<PackageAuthorTrackerOptions, 'storageDir' | 'projectRoot'>): Promise<PackageAuthorLog>;
+//# sourceMappingURL=package-author-tracker.d.ts.map

package/dist/coordination/package-author-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-author-tracker.d.ts","sourceRoot":"","sources":["../../src/coordination/package-author-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,WAAW,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC/B,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,uCAAuC;IACvC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED,MAAM,WAAW,2BAA2B;IAC1C,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAgCD;;GAEG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAwB5D;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,2BAA2B,EACjC,KAAK,EAAE,IAAI,CAAC,kBAAkB,EAAE,WAAW,CAAC,GAC3C,OAAO,CAAC,IAAI,CAAC,CAiBf;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,IAAI,CAAC,2BAA2B,EAAE,YAAY,GAAG,aAAa,CAAC,EACrE,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAczC;AAED;;GAEG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,IAAI,CAAC,2BAA2B,EAAE,YAAY,GAAG,aAAa,CAAC,EACrE,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAI/B;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,IAAI,CAAC,2BAA2B,EAAE,YAAY,GAAG,aAAa,CAAC,EACrE,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAU1C;AAED;;;GAGG;AACH,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,2BAA2B,EACjC,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,OAAO,EACjB,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,GACjC,OAAO,CAAC,IAAI,CAAC,CAiBf;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,IAAI,CAAC,2BAA2B,EAAE,YAAY,GAAG,aAAa,CAAC,GACpE,OAAO,CAAC,gBAAgB,CAAC,CAE3B"}

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

@@ -0,0 +1,83 @@
+/**
+ * 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
+ */
+import type { Mailbox } from './mailbox-types.js';
+import { type PackageAuthorTrackerOptions } from './package-author-tracker.js';
+export 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;
+}
+export interface PackageOutdatedResult {
+    /** All outdated entries. */
+    outdated: PackageOutdatedEntry[];
+    /** Packages that are up-to-date. */
+    upToDate: string[];
+    /** Whether the check failed. */
+    checkFailed: boolean;
+}
+export 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;
+}
+export 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.
+ */
+export declare function startPackageOutdatedWatcher(opts: PackageOutdatedWatcherOptions): () => void;
+//# sourceMappingURL=package-outdated-watcher.d.ts.map

package/dist/coordination/package-outdated-watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-outdated-watcher.d.ts","sourceRoot":"","sources":["../../src/coordination/package-outdated-watcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAkB,MAAM,oBAAoB,CAAC;AAElE,OAAO,EAGL,KAAK,2BAA2B,EACjC,MAAM,6BAA6B,CAAC;AAErC,MAAM,WAAW,oBAAoB;IACnC,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,uCAAuC;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,aAAa,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,4BAA4B;IAC5B,QAAQ,EAAE,oBAAoB,EAAE,CAAC;IACjC,oCAAoC;IACpC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,gCAAgC;IAChC,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,6BAA6B;IAC5C,8EAA8E;IAC9E,OAAO,EAAE,OAAO,CAAC;IACjB,sCAAsC;IACtC,kBAAkB,EAAE,IAAI,CAAC,2BAA2B,EAAE,YAAY,GAAG,aAAa,CAAC,CAAC;IACpF,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,oFAAoF;IACpF,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,iDAAiD;IACjD,QAAQ,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,6BAA6B;IAC7B,KAAK,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IAC5C,wBAAwB;IACxB,OAAO,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CAChD;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;CACrC;AA2DD;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,6BAA6B,GAAG,MAAM,IAAI,CAoG3F"}

package/dist/coordination/single-instance-mailbox.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Single-instance mailbox-bridge lock.
+ *
+ * Per-project isolation: each project (resolved via
+ * `resolveProjectDir`) gets its own lock file under
+ * `<projectDir>/.mailbox-bridge.lock`. Two projects on the same
+ * machine never collide — different slugs, different lock files,
+ * and (with default port 0) different OS-assigned ports.
+ *
+ * The lock holds:
+ *  - pid          process id of the owning `wstack mailbox serve`
+ *  - host, port   what the owner actually bound (port may be OS-assigned)
+ *  - url          convenience copy for callers
+ *  - token        the bearer token (so external agents don't have to
+ *                 re-read it from .mailbox.token separately)
+ *  - generation   monotonically increasing counter; bumped on every
+ *                 acquire. Lets a release() call identify whether the
+ *                 current lock file still belongs to *this* process
+ *                 (e.g. after a stale cleanup raced with us).
+ *  - spawnedAt    ISO timestamp — for observability, not load-bearing.
+ *
+ * Concurrency model:
+ *  - `acquireOrJoin` is atomic via rename(2). Two concurrent spawns
+ *    race to write a tmpfile then rename; one wins, the other reads
+ *    the winner's lock and joins.
+ *  - PID liveness is checked via `process.kill(pid, 0)` (POSIX) or
+ *    `tasklist` (Windows). A live PID means another instance owns
+ *    this project; a dead PID means the lock is stale and gets cleaned.
+ *  - `release` is best-effort: a missing lock file at shutdown is
+ *    fine (someone else already took over). A generation mismatch means
+ *    we lost the race and another instance owns it now — also fine.
+ *
+ * Token persistence: the token in the lock always matches the token in
+ * `.mailbox.token`, so an external agent that reads either file gets the
+ * same value. While an instance stays alive, every joining caller
+ * (`kind: 'joined'`) reuses that one token. A cold (re)start — no lock,
+ * or a lock whose owner PID is dead/unhealthy — mints a FRESH token and
+ * rewrites both files atomically. External agents must therefore re-read
+ * `.mailbox.token` after a bridge restart (a stale token returns 401).
+ */
+export declare const MAILBOX_BRIDGE_LOCK_FILENAME = ".mailbox-bridge.lock";
+export declare const MAILBOX_BRIDGE_TOKEN_FILENAME = ".mailbox.token";
+export interface MailboxBridgeLock {
+    pid: number;
+    host: string;
+    port: number;
+    url: string;
+    token: string;
+    generation: number;
+    spawnedAt: string;
+}
+export type AcquireResult = {
+    kind: 'acquired';
+    lock: MailboxBridgeLock;
+    tokenPath: string;
+} | {
+    kind: 'joined';
+    lock: MailboxBridgeLock;
+    tokenPath: string;
+} | {
+    kind: 'port-conflict';
+    existing: MailboxBridgeLock;
+};
+export interface AcquireOptions {
+    /** Project dir (already resolved by caller via resolveProjectDir). */
+    projectDir: string;
+    /** Bind host. Required when acquiring. */
+    host: string;
+    /** Explicit port. Pass null/undefined to mean "OS-assigned" (read it after listen). */
+    requestedPort: number | null;
+    /** When true, fail loud on EADDRINUSE. When false, fall back to OS-assigned. */
+    strictPort: boolean;
+}
+/**
+ * Try to acquire the mailbox-bridge lock for `projectDir`. If another
+ * instance is already alive and healthy, join it. Otherwise claim
+ * the slot for ourselves.
+ *
+ * Two-phase contract:
+ *  1. Caller invokes `acquireOrJoin(...)` BEFORE calling
+ *     `server.listen()`. The returned lock either:
+ *       - `kind: 'joined'`     → another instance is alive, the caller
+ *                                should NOT bind; just print the URL/token
+ *                                and exit cleanly (return 0).
+ *       - `kind: 'acquired'`   → caller is the owner, proceeds to bind.
+ *       - `kind: 'port-conflict'` → caller asked for an explicit port
+ *                                that's already taken by an unrelated
+ *                                process; we return the existing owner
+ *                                but the caller decides what to do
+ *                                (loud-fail).
+ *  2. After `server.listen()` resolves with a real port, the caller
+ *     invokes `finalize(lock, boundPort)` to atomically write the
+ *     final lock + token file with the OS-assigned port.
+ *
+ * The two-phase split keeps the listen() call out of the lock module —
+ * the caller owns the HTTP server instance; the lock module owns
+ * the on-disk contract.
+ */
+export declare function acquireOrJoin(opts: AcquireOptions): Promise<AcquireResult>;
+/**
+ * Phase 2 — after server.listen() resolves, write the final lock
+ * with the actually-bound port and the same token. Also writes the
+ * .mailbox.token file with mode 0600 so external agents can read it.
+ *
+ * Returns the finalized lock so the caller can use the resolved URL.
+ */
+export declare function finalize(projectDir: string, tentative: MailboxBridgeLock, boundPort: number): Promise<MailboxBridgeLock>;
+/**
+ * Phase 3 — best-effort cleanup on shutdown. Removes the lock + token
+ * files IF this process is still the recorded owner (generation match).
+ *
+ * If the generation doesn't match, another acquire() has already
+ * superseded us — we must NOT delete their lock.
+ */
+export declare function release(projectDir: string, generation: number): Promise<void>;
+/**
+ * Read the lock file and return it, with enough information for the
+ * caller to distinguish:
+ *  - 'live'        — PID alive, /healthz reachable; safe to use.
+ *  - 'probe-failed' — PID alive (or recently was) but /healthz
+ *                     unreachable. Caller can still return the URL
+ *                     + token to the host so its request layer can
+ *                     retry; the host's fetch timeout will surface
+ *                     the real error if the bridge is truly dead.
+ *  - 'absent'      — no lock file existed, or it was malformed
+ *                     (cleaned up best-effort).
+ *
+ * Distinguishing 'probe-failed' from 'absent' matters for the
+ * "joined vs spawned" decision in tryAcquireMailboxBridge — we
+ * don't want to spawn a second bridge just because /healthz flaked.
+ */
+export type LiveLockResult = {
+    kind: 'live';
+    lock: MailboxBridgeLock;
+}
+/**
+ * The lock exists but isn't usable. `pidAlive` tells the caller
+ * which recovery to pick:
+ *  - `pidAlive: false` — the owning process is dead (stale lock).
+ *    Callers should treat this like `absent` and spawn a fresh
+ *    bridge rather than surfacing a dead URL.
+ *  - `pidAlive: true`  — the process is alive but /healthz didn't
+ *    respond (booting/wedged/PID-reuse). Callers may return the
+ *    recorded URL/token and let a real request confirm liveness.
+ */
+ | {
+    kind: 'probe-failed';
+    lock: MailboxBridgeLock;
+    pidAlive: boolean;
+} | {
+    kind: 'absent';
+};
+export declare function readLiveLock(projectDir: string): Promise<LiveLockResult>;
+//# sourceMappingURL=single-instance-mailbox.d.ts.map

package/dist/coordination/single-instance-mailbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"single-instance-mailbox.d.ts","sourceRoot":"","sources":["../../src/coordination/single-instance-mailbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAQH,eAAO,MAAM,4BAA4B,yBAAyB,CAAC;AACnE,eAAO,MAAM,6BAA6B,mBAAmB,CAAC;AAE9D,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC9D;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAO3D,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,gFAAgF;IAChF,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAmDhF;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAC5B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,iBAAiB,EAC5B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,iBAAiB,CAAC,CAe5B;AAED;;;;;;GAMG;AACH,wBAAsB,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAenF;AA0ED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE;AAC3C;;;;;;;;;GASG;GACD;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,iBAAiB,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEvB,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAU9E"}

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

@@ -0,0 +1,6 @@
+/** Absolute recursion ceiling. Configuration may narrow this, never widen it. */
+export declare const HARD_MAX_SPAWN_DEPTH = 2;
+/** CLI fleet default; core embedders retain their historical Infinity default. */
+export declare const DEFAULT_MAX_FLEET_SPAWNS = 64;
+export declare function resolveMaxSpawnDepth(requested?: number | undefined): number;
+//# sourceMappingURL=spawn-budget.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spawn-budget.d.ts","sourceRoot":"","sources":["../../src/coordination/spawn-budget.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,kFAAkF;AAClF,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C,wBAAgB,oBAAoB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAG3E"}