@wrongstack/core 0.284.1 → 0.286.0

package/dist/coordination/commit-safety.d.ts

@@ -0,0 +1,72 @@
+/**
+ * commit-safety — detect when a commit would sweep up work that this session
+ * did NOT author.
+ *
+ * When several coding agents (or a separate wrongstack process, or a human)
+ * edit the same worktree at once, a blanket `git add .` / commit-all captures
+ * everyone's uncommitted changes — including half-finished work from another
+ * agent. There is no way to un-bake that once it lands in a shared commit.
+ *
+ * This module reads the working tree and cross-references it against the
+ * per-project {@link file-author-tracker} log (which records the sessionId that
+ * created/edited each file). Dirty files whose latest author is a DIFFERENT
+ * session are flagged as "foreign"; dirty files with no recorded author are
+ * "unverified" (a concurrent non-wrongstack agent, a build/format step, or a
+ * human). The result is a plain-text warning callers render before committing.
+ *
+ * Warn-only by design: this never blocks or rewrites what gets committed — it
+ * surfaces the risk so the agent (or user) can scope the commit to its own
+ * files or coordinate first.
+ *
+ * @module commit-safety
+ */
+export interface CommitSafetyOptions {
+    /** Directory to run git in (the agent's cwd is fine). */
+    cwd: string;
+    /** Project root, used to locate the file-author log. */
+    projectRoot: string;
+    /**
+     * The current session's id — the "self" key. Dirty files authored by a
+     * different sessionId are flagged as foreign. When omitted, every authored
+     * file counts as foreign (we cannot prove ownership).
+     */
+    sessionId?: string | undefined;
+    /**
+     * Directory holding the file-author log. Defaults to the resolved per-project
+     * dir (`~/.wrongstack/projects/<slug>`). Mainly an injection seam for tests.
+     */
+    storageDir?: string | undefined;
+    /** Abort signal for the git subprocesses. */
+    signal?: AbortSignal | undefined;
+}
+export interface ForeignFile {
+    /** Repo-relative path. */
+    path: string;
+    /** Human-readable name of the agent that last authored it, if known. */
+    agentName?: string | undefined;
+    /** Session that last authored it, if known. */
+    sessionId?: string | undefined;
+}
+export interface CommitSafetyReport {
+    /** Total uncommitted (staged + unstaged + untracked) paths. */
+    dirtyCount: number;
+    /** Dirty files whose latest recorded author is a DIFFERENT session. */
+    foreignFiles: ForeignFile[];
+    /** Dirty files with no recorded author for any session. */
+    unverifiedFiles: string[];
+    /** Branch names of OTHER active worktrees of this repo (excludes ours). */
+    otherWorktrees: string[];
+    /**
+     * Pre-formatted, plain-text (no ANSI) multi-line warning, or '' when there
+     * is nothing notable to surface. Callers may colorize/wrap as they see fit.
+     */
+    warning: string;
+}
+/**
+ * Assess whether committing now risks capturing another agent's work.
+ *
+ * Best-effort: any git failure (not a repo, git missing, timeout) yields an
+ * empty report rather than throwing — commit-safety must never break a commit.
+ */
+export declare function assessCommitSafety(opts: CommitSafetyOptions): Promise<CommitSafetyReport>;
+//# sourceMappingURL=commit-safety.d.ts.map

package/dist/coordination/commit-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commit-safety.d.ts","sourceRoot":"","sources":["../../src/coordination/commit-safety.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAQH,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,6CAA6C;IAC7C,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAClC;AAED,MAAM,WAAW,WAAW;IAC1B,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,2DAA2D;IAC3D,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,2EAA2E;IAC3E,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;CACjB;AAKD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAsE/F"}

package/dist/coordination/consensus-protocol.d.ts

@@ -0,0 +1,106 @@
+/**
+ * ConsensusProtocol — agent voting on proposed changes.
+ *
+ * Enables autonomous approval of code changes without a human. Agents register
+ * as voters with a role weight; changes gather votes; the protocol resolves
+ * the outcome based on configured quorum rules.
+ *
+ * Voting rules (configurable):
+ * - Quorum: minimum fraction of eligible voters required (default: 0.5)
+ * - Approval threshold: minimum fraction of cast votes that must be approve (default: 0.6)
+ * - Veto roles: roles whose 'reject' vote is fatal regardless of count
+ * - Auto-approve: changes with severity=critical bypass voting if the proposer is trusted
+ *
+ * The protocol is stateless — it reads from the KnowledgeGraph and writes results
+ * back to it. This makes it naturally consistent with the shared knowledge model.
+ *
+ * @module consensus-protocol
+ */
+import type { VoteRecord, VoteValue } from './knowledge-graph.js';
+import type { KnowledgeGraph } from './knowledge-graph.js';
+import type { FleetBus } from './fleet-bus.js';
+export interface VoterConfig {
+    agentId: string;
+    agentName: string;
+    role: string;
+    /** Weight multiplier for this voter's vote. Default: 1. */
+    weight: number;
+    /** If true, a 'reject' vote from this role is a hard veto. Default: false. */
+    veto?: boolean;
+    /**
+     * @deprecated Not yet implemented. Auto-approve of low-risk changes is planned
+     * but not wired up in the vote resolution logic.
+     */
+    autoApprovesLowRisk?: boolean;
+}
+export interface QuorumRule {
+    /** Fraction of eligible voters required (0-1). Default: 0.5. */
+    quorumFraction: number;
+    /** Fraction of cast votes that must be approve (0-1). Default: 0.6. */
+    approvalFraction: number;
+    /** Roles whose reject vote is a hard veto regardless of count. */
+    vetoRoles: string[];
+    /** Minimum total weight of approve votes to pass (0-1 of total eligible weight). */
+    approvalWeightFraction?: number | undefined;
+}
+export interface ConsensusResult {
+    changeId: string;
+    outcome: 'approved' | 'rejected' | 'pending' | 'vetoed' | 'quorum_not_met';
+    votes: VoteRecord[];
+    approveCount: number;
+    rejectCount: number;
+    abstainCount: number;
+    totalWeightApprove: number;
+    totalWeightReject: number;
+    eligibleVoters: string[];
+    quorumMet: boolean;
+    approvalMet: boolean;
+    vetoedBy?: string;
+    rationale: string;
+}
+export interface ConsensusOptions {
+    rules?: Partial<QuorumRule>;
+    voters: VoterConfig[];
+    graph: KnowledgeGraph;
+    fleet?: FleetBus | undefined;
+}
+/**
+ * ConsensusProtocol manages voting on ChangeNodes in the KnowledgeGraph.
+ * It is instantiated once per autonomous session and used to initiate votes,
+ * cast votes, and resolve outcomes.
+ */
+export declare class ConsensusProtocol {
+    private readonly graph;
+    private readonly fleet?;
+    private readonly rules;
+    private readonly voters;
+    constructor(opts: ConsensusOptions);
+    /**
+     * Initiate a vote on a proposed change. Updates the change node's status
+     * to 'proposed' and notifies eligible voters via FleetBus.
+     */
+    initiateVote(changeId: string): Promise<void>;
+    /**
+     * Cast a vote. Updates the change node in the graph and re-evaluates
+     * consensus. If the vote triggers a resolution, updates the change status.
+     */
+    castVote(changeId: string, voterId: string, value: VoteValue, rationale?: string): Promise<ConsensusResult>;
+    /**
+     * Resolve the current vote without waiting for all eligible voters.
+     * Useful when a timeout fires or an agent decides to finalize early.
+     */
+    resolveNow(changeId: string): Promise<ConsensusResult>;
+    /**
+     * Register or update a voter's configuration.
+     */
+    registerVoter(config: VoterConfig): void;
+    /**
+     * Get the current vote status for a change.
+     */
+    getStatus(changeId: string): ConsensusResult | null;
+    private _eligibleVoters;
+    private _resolve;
+    private _toChangeStatus;
+    private _notifyVoters;
+}
+//# sourceMappingURL=consensus-protocol.d.ts.map

package/dist/coordination/consensus-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consensus-protocol.d.ts","sourceRoot":"","sources":["../../src/coordination/consensus-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAc,UAAU,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAC9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAI/C,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,cAAc,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,gBAAgB,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,oFAAoF;IACpF,sBAAsB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7C;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,gBAAgB,CAAC;IAC3E,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IAC5B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,KAAK,EAAE,cAAc,CAAC;IACtB,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;CAC9B;AAED;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAuB;IAC9C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAElD,YAAY,IAAI,EAAE,gBAAgB,EAUjC;IAID;;;OAGG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQlD;IAED;;;OAGG;IACG,QAAQ,CACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,SAAS,EAChB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,CAAC,CA0C1B;IAED;;;OAGG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAY3D;IAED;;OAEG;IACH,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAEvC;IAED;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAKlD;IAID,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,QAAQ;IA4HhB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,aAAa;CActB"}

package/dist/coordination/coordinator/error-classifier.d.ts

@@ -0,0 +1,15 @@
+import type { SubagentError } from '../../types/multi-agent.js';
+/**
+ * Map any raw exception thrown out of a subagent's runner into a
+ * structured `SubagentError`. This is the single point where the
+ * coordinator decides "what kind of failure was that" — so callers
+ * (delegate tool output, /agents UI, retry policies) branch on
+ * `kind` instead of substring-matching `error.message`.
+ *
+ * Exported because tests and CLI surfaces want to assert on the
+ * classification without instantiating a coordinator.
+ */
+export declare function classifySubagentError(err: unknown, hints?: {
+    parentAborted?: boolean | undefined;
+}): SubagentError;
+//# sourceMappingURL=error-classifier.d.ts.map

package/dist/coordination/coordinator/error-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-classifier.d.ts","sourceRoot":"","sources":["../../../src/coordination/coordinator/error-classifier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAqB,MAAM,4BAA4B,CAAC;AAMnF;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,OAAO,EACZ,KAAK,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAAO,GAClD,aAAa,CA8Df"}

package/dist/coordination/delegate-tool.d.ts

@@ -0,0 +1,101 @@
+import type { EventBus } from '../kernel/events.js';
+import type { SubagentConfig } from '../types/multi-agent.js';
+import type { Tool } from '../types/tool.js';
+import type { Director } from './director.js';
+/**
+ * Opaque host interface so this factory doesn't have to depend on the
+ * CLI's `MultiAgentHost`. Any caller that exposes the same three
+ * methods can wire `delegate` — including test doubles.
+ */
+export interface DelegateHost {
+    /** True if a Director is already attached and running. */
+    isDirectorMode(): boolean;
+    /** Build (or return the cached) Director when director mode is on. */
+    ensureDirector(): Promise<Director | null>;
+    /**
+     * Force-promote a non-director session into director mode at runtime.
+     * Returns the Director, or null when promotion is impossible (e.g. a
+     * non-director coordinator has already spawned subagents in the
+     * legacy code path).
+     */
+    promoteToDirector(): Promise<Director | null>;
+    /**
+     * Optional: when promotion fails, return the human-readable reason.
+     * Used to render an actionable error to the calling model instead of
+     * the prior opaque "Director could not be activated" message.
+     * Implementations may return null when they don't track the reason.
+     */
+    getPromotionBlockReason?(): string | null;
+}
+export interface CreateDelegateToolOptions {
+    host: DelegateHost;
+    /**
+     * Roster used to resolve `role` strings into full `SubagentConfig`s.
+     * Typically `FLEET_ROSTER`. When omitted, `delegate({ role })` calls
+     * fail and only the explicit `name + provider + model` path works.
+     */
+    roster?: Record<string, SubagentConfig>;
+    /**
+     * Default await timeout in milliseconds. `delegate` blocks until the
+     * subagent's task resolves; without a cap, a stuck worker would hang
+     * the host indefinitely. Set generously (default: 4 hours) so the
+     * orchestrator can run multi-step refactors / monorepo audits
+     * without being killed for being slow — the orchestrator must
+     * decide per-call when a task needs to be cut short.
+     */
+    defaultTimeoutMs?: number | undefined;
+    /**
+     * Absolute directory under which per-subagent JSONL transcripts live —
+     * matches `MultiAgentHostOptions.sessionsRoot`. When set, the delegate
+     * tool reads the subagent's transcript on timeout / budget-exhaustion
+     * to extract partial output, so the host LLM gets *something* useful
+     * back instead of just an error.
+     */
+    sessionsRoot?: string | undefined;
+    /**
+     * The directorRunId used to namespace transcripts (typically the host
+     * session id). Combined with `sessionsRoot` to locate per-subagent
+     * JSONLs at `<sessionsRoot>/<runId>/<subagentId>.jsonl`.
+     */
+    directorRunId?: string | undefined;
+    /**
+     * Buffer subtracted from the caller's `timeoutMs` before passing it
+     * to the subagent. Gives the host a window to detect a subagent that
+     * has gone silent and surface a partial result rather than a generic
+     * timeout. Default: 60_000 ms (raised from 30s to give subagents
+     * more headroom before the host kills them).
+     */
+    subagentTimeoutBufferMs?: number | undefined;
+    /**
+     * Host EventBus. When supplied, `delegate` emits `delegate.started`
+     * (before it blocks on the subagent) and `delegate.completed` (once the
+     * subagent settles) so UIs / the Telegram bridge can render readable
+     * start/finish lines instead of inferring them from the truncated
+     * `tool.executed` JSON preview. Optional — emits are best-effort and a
+     * missing bus never affects delegation behaviour.
+     */
+    events?: EventBus | undefined;
+}
+/**
+ * `delegate` — the compact multi-agent tool exposed after Director mode is
+ * enabled. It bundles spawn + assign + await into a single call.
+ *
+ * The model never has to ask "are we in director mode?" — it just calls
+ * `delegate({ role, task })` and gets back a `TaskResult`. The cost of
+ * that ergonomic packaging is that `delegate` cannot be used for
+ * parallel work as-is; the model must fire multiple `delegate` calls in
+ * parallel through the provider's parallel-tool-call surface, or escalate
+ * to the explicit `spawn_subagent` + `assign_task` + `await_tasks` flow
+ * when it wants fan-out it controls itself.
+ */
+export declare function createDelegateTool(opts: CreateDelegateToolOptions): Tool;
+/**
+ * Per-kind orchestrator hint. Returned alongside the structured error
+ * so the calling model has a concrete next step instead of "task
+ * failed, good luck". Returns undefined for success / unknown kinds —
+ * the caller checks for presence before including in output.
+ */
+export declare function hintForKind(kind: string | undefined, retryable: boolean | undefined, backoffMs: number | undefined, partial?: {
+    lastAssistantText?: string | undefined;
+} | undefined): string | undefined;
+//# sourceMappingURL=delegate-tool.d.ts.map

package/dist/coordination/delegate-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate-tool.d.ts","sourceRoot":"","sources":["../../src/coordination/delegate-tool.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,yBAAyB,CAAC;AAC1E,OAAO,KAAK,EAAc,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAM9C;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,cAAc,IAAI,OAAO,CAAC;IAC1B,sEAAsE;IACtE,cAAc,IAAI,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAC3C;;;;;OAKG;IACH,iBAAiB,IAAI,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAC9C;;;;;OAKG;IACH,uBAAuB,CAAC,IAAI,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,YAAY,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACxC;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC;;;;;;OAMG;IACH,uBAAuB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;CAC/B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,yBAAyB,GAAG,IAAI,CAwbxE;AAgLD;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,SAAS,EAAE,OAAO,GAAG,SAAS,EAC9B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,OAAO,CAAC,EAAE;IAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG,SAAS,GAC/D,MAAM,GAAG,SAAS,CAkDpB"}

package/dist/coordination/dep-watcher-bridge.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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
+ */
+import type { EventBus } from '../kernel/events.js';
+import type { Mailbox } from './mailbox-types.js';
+export 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
+ */
+export declare function attachDepWatcherBridge(opts: DepWatcherBridgeOptions): () => void;
+//# sourceMappingURL=dep-watcher-bridge.d.ts.map

package/dist/coordination/dep-watcher-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dep-watcher-bridge.d.ts","sourceRoot":"","sources":["../../src/coordination/dep-watcher-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAGlD,MAAM,WAAW,uBAAuB;IACtC,iFAAiF;IACjF,MAAM,EAAE,QAAQ,CAAC;IACjB,0EAA0E;IAC1E,OAAO,EAAE,OAAO,CAAC;IACjB,iFAAiF;IACjF,WAAW,EAAE,MAAM,CAAC;IACpB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,uBAAuB,GAC5B,MAAM,IAAI,CA4CZ"}

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

@@ -0,0 +1,74 @@
+/**
+ * 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
+ */
+import type { Mailbox } from './mailbox-types.js';
+/**
+ * Files that declare project dependencies. When any of these change
+ * (create/update), a mailbox message triggers a tech-stack audit.
+ */
+export declare const DEPENDENCY_FILE_PATTERNS: ReadonlyArray<string>;
+export 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;
+}
+export 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;
+    /** Cancel all in-flight debounce timers. Call when the file watcher is
+     *  stopped (session end / project switch) so pending setTimeouts — each
+     *  holding a closure over the mailbox + entry — don't leak. */
+    dispose: () => void;
+}
+export 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.
+ */
+export declare function makeDependencyWatcherConfig(opts: DependencyWatcherOptions): DependencyWatcherConfig;
+//# sourceMappingURL=dep-watcher.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dep-watcher.d.ts","sourceRoot":"","sources":["../../src/coordination/dep-watcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAIlD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,aAAa,CAAC,MAAM,CAmC1D,CAAC;AAIF,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,uBAAuB;IACtC,mFAAmF;IACnF,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,2EAA2E;IAC3E,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,kGAAkG;IAClG,UAAU,EAAE,MAAM,CAAC;IACnB;;mEAE+D;IAC/D,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,wCAAwC;IACxC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;CACjC;AAID;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,wBAAwB,GAC7B,uBAAuB,CAiHzB"}

package/dist/coordination/director/director-errors.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Director-specific error types. Extracted to keep the Director class
+ * focused on orchestration logic.
+ */
+export declare class FleetSpawnBudgetError extends Error {
+    readonly kind: 'max_spawns' | 'max_spawn_depth';
+    readonly limit: number;
+    readonly observed: number;
+    constructor(kind: 'max_spawns' | 'max_spawn_depth', limit: number, observed: number, message?: string | undefined);
+}
+export declare class FleetCostCapError extends Error {
+    readonly kind: 'max_cost_usd';
+    readonly limit: number;
+    readonly observed: number;
+    constructor(limit: number, observed: number);
+}
+export declare class FleetTokenCapError extends Error {
+    readonly kind: 'max_tokens';
+    readonly limit: number;
+    readonly observed: number;
+    constructor(limit: number, observed: number);
+}
+export declare class FleetContextOverflowError extends Error {
+    readonly kind: 'max_context_load';
+    readonly limit: number;
+    readonly observed: number;
+    constructor(limit: number, observed: number);
+}
+//# sourceMappingURL=director-errors.d.ts.map

package/dist/coordination/director/director-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"director-errors.d.ts","sourceRoot":"","sources":["../../../src/coordination/director/director-errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,iBAAiB,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,YACE,IAAI,EAAE,YAAY,GAAG,iBAAiB,EACtC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,EAW7B;CACF;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,YAAY,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAQ1C;CACF;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,YAAY,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAQ1C;CACF;AAED,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,YAAY,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAQ1C;CACF"}

package/dist/coordination/director-construction.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Director construction helpers.
+ *
+ * The `Director` constructor was historically a single 300+ line function
+ * that interleaved field assignments with two pieces of event-listener
+ * wiring: the `task.completed` listener on the coordinator (which mirrors
+ * completions into the in-memory wait table, the on-disk checkpoint, and
+ * the session JSONL event stream) and the `budget.threshold_reached`
+ * filter on the FleetBus (which implements the heartbeat-driven timeout
+ * policy and the per-kind auto-extension logic).
+ *
+ * Both wirings were inlined because they close over a lot of Director
+ * private state (`completed`, `taskWaiters`, `taskDescriptions`,
+ * `appendSessionEvent`, `scheduleManifest`, `recordExtension`,
+ * `maxBudgetExtensions`, `maxFleetCostUsd`, etc.). Pulling them out
+ * without losing the closures requires a narrow `DirectorInternals`
+ * shape — exactly what this module exposes.
+ *
+ * The constructor itself stays a member-initializer; the helpers below
+ * are called *during* construction, after the relevant fields are
+ * populated. Each helper ends with `coordinator.on(...)` /
+ * `fleet.filter(...)` registration so the listener is wired exactly
+ * once, at construction time.
+ */
+import type { TaskResult, TaskSpec } from '../types/multi-agent.js';
+/** Cap on the in-memory `completed` map. Trimmed oldest-first when exceeded. */
+export declare const MAX_COMPLETED = 10000;
+/** Narrow shape the wiring helpers need from a partially-constructed Director.
+ *  The helpers accept a `Director` instance (structural typing — the class
+ *  exposes every field this interface requires), so the constructor can pass
+ *  `this` directly without an explicit cast.
+ *
+ *  Note: Private/protected members cannot be picked via Pick<> because keyof
+ *  only returns public keys. We define the interface explicitly rather than
+ *  deriving from Director to include private fields the wiring code needs. */
+export interface DirectorInternals {
+    id: string;
+    directorRunId: string;
+    completed: Map<string, import('../types/multi-agent.js').TaskResult>;
+    taskWaiters: Map<string, {
+        promise: Promise<import('../types/multi-agent.js').TaskResult>;
+        resolve: (r: import('../types/multi-agent.js').TaskResult) => void;
+    }>;
+    taskDescriptions: Map<string, string>;
+    stateCheckpoint: import('../storage/director-state.js').DirectorStateCheckpoint | null;
+    usage: import('./fleet-bus.js').FleetUsageAggregator;
+    fleetManager: import('./fleet-manager.js').FleetManager | undefined;
+    fleet: import('./fleet-bus.js').FleetBus;
+    coordinator: import('./icoordinator.js').ICoordinator;
+    maxBudgetExtensions: number;
+    maxFleetCostUsd: number;
+    recordExtension: (subagentId: string, taskId: string | undefined, kind: string, newLimit: number) => void;
+    appendSessionEvent: (event: Parameters<import('../types/session.js').SessionWriter['append']>[0]) => Promise<void>;
+    scheduleManifest: () => void;
+    brain: import('./brain.js').BrainArbiter | undefined;
+}
+export { TIMEOUT_PREEMPT_FRACTION } from './subagent-budget.js';
+/**
+ * Wire the coordinator's `task.completed` event into the Director's
+ * in-memory wait table, the on-disk state checkpoint, and the session
+ * JSONL event stream.
+ *
+ * Mirrors coordinator completion events into:
+ * - `d.completed` (capped at `Director.MAX_COMPLETED`, oldest-first trim)
+ * - `d.taskWaiters` (resolve and clear the matching waiter)
+ * - `d.stateCheckpoint.recordTaskStatus(...)` + `setUsage(...)`
+ * - session event stream via `d.appendSessionEvent(...)`
+ * - fleet manifest via `d.fleetManager?.flushManifest()` or `d.scheduleManifest()`
+ *
+ * Returns the listener so the Director can call `coordinator.off(...)`
+ * during `shutdown()`.
+ */
+export declare function wireTaskCompletedListener(d: DirectorInternals): (payload: {
+    task: TaskSpec;
+    result: TaskResult;
+}) => void;
+/**
+ * Wire the FleetBus's `budget.threshold_reached` filter with the
+ * Director's auto-extend/deny policy. Implements:
+ *
+ * - Heartbeat-driven timeout policy: while a subagent keeps executing
+ *   tools it never dies on time; once it stops making progress between
+ *   grants, deny. Wall-clock time alone is never a reliable "stuck" signal.
+ * - Per-kind auto-extension with `maxBudgetExtensions` cap.
+ * - Brain-decision routing when a brain arbiter is configured.
+ * - Collab-subagent passthrough (BugHunter / RefactorPlanner / Critic
+ *   own their own budget routing via the CollabSession).
+ */
+export declare function wireBudgetHandler(d: DirectorInternals): void;
+//# sourceMappingURL=director-construction.d.ts.map

package/dist/coordination/director-construction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"director-construction.d.ts","sourceRoot":"","sources":["../../src/coordination/director-construction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEpE,gFAAgF;AAChF,eAAO,MAAM,aAAa,QAAS,CAAC;AAEpC;;;;;;;8EAO8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,yBAAyB,EAAE,UAAU,CAAC,CAAC;IACrE,WAAW,EAAE,GAAG,CACd,MAAM,EACN;QAAE,OAAO,EAAE,OAAO,CAAC,OAAO,yBAAyB,EAAE,UAAU,CAAC,CAAC;QAAC,OAAO,EAAE,CAAC,CAAC,EAAE,OAAO,yBAAyB,EAAE,UAAU,KAAK,IAAI,CAAA;KAAE,CACvI,CAAC;IACF,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,EAAE,OAAO,8BAA8B,EAAE,uBAAuB,GAAG,IAAI,CAAC;IACvF,KAAK,EAAE,OAAO,gBAAgB,EAAE,oBAAoB,CAAC;IACrD,YAAY,EAAE,OAAO,oBAAoB,EAAE,YAAY,GAAG,SAAS,CAAC;IACpE,KAAK,EAAE,OAAO,gBAAgB,EAAE,QAAQ,CAAC;IACzC,WAAW,EAAE,OAAO,mBAAmB,EAAE,YAAY,CAAC;IACtD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1G,kBAAkB,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,qBAAqB,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnH,gBAAgB,EAAE,MAAM,IAAI,CAAC;IAC7B,KAAK,EAAE,OAAO,YAAY,EAAE,YAAY,GAAG,SAAS,CAAC;CACtD;AAyBD,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAShE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,iBAAiB,GAAG,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,KAAK,IAAI,CAiEzH;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,iBAAiB,GAAG,IAAI,CA8J5D"}