@wrongstack/core 0.303.0 → 0.305.1

package/dist/coordination/agents/project-agent-consolidation.d.ts

@@ -28,6 +28,11 @@ export interface ConsolidationMetadata {
 }
 /** Structured directives in the raw buffer, with legacy-format fallback. */
 export declare function readRawLearnedEntries(role: string, projectRoot?: string): StructuredLearnedEntry[];
+/**
+ * The role document's path, for callers that need to rewrite it in place
+ * without going through the full save-and-record-metadata pass.
+ */
+export declare function consolidatedDocumentPath(role: string, projectRoot?: string): string;
 export declare function loadProjectAgentConsolidated(role: string, projectRoot?: string): string;
 export declare function loadConsolidationMetadata(role: string, projectRoot?: string): ConsolidationMetadata | undefined;
 export declare function isConsolidated(role: string, projectRoot?: string): boolean;

package/dist/coordination/agents/project-agent-directive-outcome.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Outcome attribution for captured directives.
+ *
+ * Capture answers "what did the agent conclude?". This module answers the
+ * question the loop was missing: **did that conclusion help?** Without it the
+ * environment's reward reached `affinity.json` and stopped there, so a directive
+ * that made every task worse was injected forever and could only ever leave the
+ * buffer by growing old.
+ *
+ * The attribution is deliberately cheap and model-free. When a task finishes,
+ * its final report is scanned for evidence that each already-stored directive
+ * was actually exercised — its anchors (commands, paths, package names, which
+ * capture already extracts into `entry.how`) appearing verbatim, or enough of
+ * its distinctive wording to be unambiguous. Every directive that was exercised
+ * takes the task's outcome onto its own record.
+ *
+ * This is correlation, not proof: a directive can be mentioned and irrelevant,
+ * or decisive and unmentioned. It is used accordingly — to order eviction, to
+ * protect proven rules from being overwritten, to retire rules that keep losing,
+ * and to tell the distillation pass which directives earned their place. None of
+ * those decisions is safe to make on age alone, which is what they used before.
+ */
+import { type StructuredLearnedEntry } from './project-agent-learning-structured.js';
+/** Trials a directive must have before a bad record can retire it. */
+export declare const DIRECTIVE_QUARANTINE_MIN_APPLIED = 8;
+/** Utility below which a directive with enough trials is retired. */
+export declare const DIRECTIVE_QUARANTINE_MAX_UTILITY = 0.3;
+/**
+ * Whether `report` shows this directive was exercised.
+ *
+ * One anchor is enough: anchors are exact commands, paths and package names, so
+ * their appearance in a report is a direct statement that the thing the
+ * directive is about was touched. Directives with no anchors fall back to
+ * wording, which needs a high bar because generic prose overlaps easily.
+ */
+export declare function directiveWasApplied(entry: StructuredLearnedEntry, report: string): boolean;
+export interface DirectiveOutcomeResult {
+    role: string;
+    /** Directives credited with this task's outcome. */
+    attributed: number;
+    /** Directives retired into `quarantine.md` by this update. */
+    quarantined: string[];
+}
+/**
+ * Fold one completed task's outcome into the record of every directive it
+ * exercised, then retire the ones whose record has become bad enough.
+ *
+ * Must run **before** the same output is captured: a directive written by this
+ * task has not been tested by this task, and crediting it here would let every
+ * new directive vouch for itself.
+ *
+ * Can throw on an invalid role or an unwritable role directory. Callers on the
+ * task-completion path must swallow it: a lost outcome costs ranking quality,
+ * which is never worth failing a completed task over.
+ */
+export declare function recordDirectiveOutcomes(role: string, report: string, succeeded: boolean, projectRoot?: string): DirectiveOutcomeResult;
+//# sourceMappingURL=project-agent-directive-outcome.d.ts.map

package/dist/coordination/agents/project-agent-identity.d.ts

@@ -24,22 +24,22 @@ import { type ConsolidationMetadata } from './project-agent-consolidation.js';
 import type { LearnedCaptureResult, ProjectAgentConfig, RoleKnowledgeManifest } from './project-agent-identity-types.js';
 import { type ProjectAgentLearningPolicy } from './project-agent-learning-policy.js';
 import { type StructuredLearnedEntry } from './project-agent-learning-structured.js';
-export { validateProjectAgentConfig } from './project-agent-config-validation.js';
-export { loadProjectAgentConfig } from './project-agent-config-io.js';
-export { CAPTURE_SESSION_WINDOW_MS, resetCaptureWindow, resetCaptureWindows, } from './project-agent-capture-window.js';
-export { CAPTURE_COOLDOWN_MS, CAPTURE_MAX_PER_SESSION };
-export { buildSkillDistillInstruction, clearProjectSkillAugmentation, DEFAULT_EAGER_SKILL_LIMIT, listProjectSkillAugmentations, loadProjectSkillAugmentation, loadSkillAffinity, rankRoleSkills, recordSkillLoad, recordSkillOutcome, renderSkillAugmentation, resolveRoleSkillCandidates, routeDirectiveToSkill, saveProjectSkillAugmentation, setSkillPinned, SKILL_AUGMENTATION_MAX_BYTES, type SkillAffinity, type SkillAffinityEntry, } from './project-agent-skill-layer.js';
-export { readRawLearnedEntries, type SaveConsolidationOptions } from './project-agent-consolidation.js';
 export { type AutoOptimizeDecision, type AutoOptimizeEvent, type AutoOptimizePolicy, type AutoOptimizePolicyOverrides, DEFAULT_AUTO_OPTIMIZE_POLICY, evaluateAutoOptimize, LearningOptimizationScheduler, type LearningOptimizationSchedulerOptions, resolveAutoOptimizePolicy, } from './project-agent-auto-optimize.js';
-export { type LearningOptimizerLlm, type OptimizeLearningOptions, type OptimizeLearningResult, optimizeProjectAgentLearning, unwrapWholeDocumentFence, } from './project-agent-optimizer.js';
-export { buildConsolidationInstruction, type ConsolidationMetadata, clearProjectAgentConsolidated, isConsolidated, loadConsolidationMetadata, loadProjectAgentConsolidated, saveProjectAgentConsolidated, } from './project-agent-consolidation.js';
+export { CAPTURE_SESSION_WINDOW_MS, resetCaptureWindow, resetCaptureWindows, } from './project-agent-capture-window.js';
+export { loadProjectAgentConfig } from './project-agent-config-io.js';
+export { validateProjectAgentConfig } from './project-agent-config-validation.js';
+export { buildConsolidationInstruction, type ConsolidationMetadata, clearProjectAgentConsolidated, consolidatedDocumentPath, isConsolidated, loadConsolidationMetadata, loadProjectAgentConsolidated, readRawLearnedEntries, type SaveConsolidationOptions, saveProjectAgentConsolidated, } from './project-agent-consolidation.js';
+export { DIRECTIVE_QUARANTINE_MAX_UTILITY, DIRECTIVE_QUARANTINE_MIN_APPLIED, type DirectiveOutcomeResult, directiveWasApplied, recordDirectiveOutcomes, } from './project-agent-directive-outcome.js';
 export type { CreateProjectAgentInput, LearnedCaptureResult, ProjectAgentConfig, ProjectAgentProfile, RoleKnowledgeManifest, } from './project-agent-identity-types.js';
+export { splitLearnedEntries, tokenOverlap } from './project-agent-learning-entries.js';
 export { classifyLearnedEntry, LEARNED_ENTRY_MAX_CHARS, LEARNED_HARD_LIMIT, LEARNED_SOFT_LIMIT, type LearnedEntryCategory, normalizeLearnedEntry, } from './project-agent-learning-normalize.js';
-export { loadProjectAgentLearningPolicy, type ProjectAgentLearningPolicy, updateProjectAgentLearningPolicy, } from './project-agent-learning-policy.js';
-export { decomposeLearnedEntry, enforceLearnedBudget, mergeStructuredEntries, parseLearnedEntryStamp, renderLearnedInstructions, type StructuredLearnedEntry, } from './project-agent-learning-structured.js';
+export { loadProjectAgentLearningPolicy, type ProjectAgentLearningPolicy, recordProjectAgentOptimizePass, updateProjectAgentLearningPolicy, } from './project-agent-learning-policy.js';
+export { DIRECTIVE_PROVEN_MIN_APPLIED, DIRECTIVE_PROVEN_MIN_UTILITY, decomposeLearnedEntry, directiveTrials, directiveUtility, enforceLearnedBudget, isProvenDirective, mergeStructuredEntries, parseLearnedEntryStamp, parseStructuredLearnedEntriesFromContent, renderLearnedInstructions, type StructuredLearnedEntry, } from './project-agent-learning-structured.js';
+export { type LearningOptimizerLlm, type OptimizeLearningOptions, type OptimizeLearningResult, optimizeProjectAgentLearning, unwrapWholeDocumentFence, } from './project-agent-optimizer.js';
 export { assertProjectAgentRole } from './project-agent-paths.js';
-export { splitLearnedEntries, tokenOverlap } from './project-agent-learning-entries.js';
-export { parseStructuredLearnedEntriesFromContent } from './project-agent-learning-structured.js';
+export { type QuarantinedDirective, quarantinePath, readQuarantinedDirectives, retiredDirectivesToWarnAbout, scrubRetiredLines, } from './project-agent-quarantine.js';
+export { buildSkillDistillInstruction, clearProjectSkillAugmentation, DEFAULT_EAGER_SKILL_LIMIT, listProjectSkillAugmentations, loadProjectSkillAugmentation, loadSkillAffinity, rankRoleSkills, recordSkillLoad, recordSkillOutcome, renderSkillAugmentation, resolveRoleSkillCandidates, routeDirectiveToSkill, SKILL_AUGMENTATION_MAX_BYTES, SKILL_EVIDENCE_HALF_LIFE_DAYS, type SkillAffinity, type SkillAffinityEntry, saveProjectSkillAugmentation, scoreSkillAffinity, setSkillPinned, } from './project-agent-skill-layer.js';
+export { CAPTURE_COOLDOWN_MS, CAPTURE_MAX_PER_SESSION };
 export { listProjectAgentRoles, refreshProjectAgentIdentity, resetProjectAgentIdentity, updateProjectAgentConfig, updateProjectAgentIdentity, updateProjectAgentKnowledge, updateProjectAgentLearned, } from './project-agent-files.js';
 export { createProjectAgent, loadProjectAgentProfile, slugifyProjectAgentRole, } from './project-agent-profile.js';
 /**
@@ -129,6 +129,20 @@ export interface ProjectAgentLearnStats {
     skills: string[];
     /** Directives already routed to a skill and awaiting distillation. */
     skilledEntryCount: number;
+    /**
+     * How the buffer is actually performing, not just how big it is.
+     *
+     * `lifetimeCaptureCount` measures volume, which says nothing about whether
+     * the role is learning the right things. These three do:
+     * `provenEntryCount` is directives with a real track record, `deadEntryCount`
+     * is directives that have never been exercised at all (a high share means the
+     * agent is writing things nobody uses), and `directiveHitRate` is the share
+     * of applications that ended in a successful task.
+     */
+    appliedEntryCount: number;
+    deadEntryCount: number;
+    /** `null` until at least one directive has been exercised. */
+    directiveHitRate: number | null;
 }
 export declare function getProjectAgentLearnStats(role: string, projectRoot?: string): ProjectAgentLearnStats;
 /**

package/dist/coordination/agents/project-agent-learning-policy.d.ts

@@ -5,7 +5,28 @@ export interface ProjectAgentLearningPolicy {
     lifetimeCaptureCount: number;
     lastCaptureAt?: string | undefined;
     lastCaptureSource?: 'automatic' | 'manual' | 'taught' | undefined;
+    /**
+     * When an optimization pass last ran to completion for this role, whatever it
+     * managed to do.
+     *
+     * The auto-optimize cooldown used to read `consolidation.json` alone, which is
+     * only written when a model produced a role document. A pass that ran without
+     * a model still rewrote every skill addendum and still left no trace, so on a
+     * headless box `minIntervalMs` never applied and a full pass re-ran after
+     * every capture.
+     */
+    lastOptimizeAt?: string | undefined;
 }
 export declare function loadProjectAgentLearningPolicy(role: string, projectRoot?: string): ProjectAgentLearningPolicy;
-export declare function updateProjectAgentLearningPolicy(role: string, patch: Partial<Pick<ProjectAgentLearningPolicy, 'enabled'>>, projectRoot?: string): ProjectAgentLearningPolicy;
+/**
+ * Merge a patch into the persisted policy.
+ *
+ * Always re-reads immediately before writing. Capture and the optimization pass
+ * both own fields in this file and run on independent schedules, so writing a
+ * whole object built from a value read earlier in the call silently reverts
+ * whatever the other one recorded in between.
+ */
+export declare function updateProjectAgentLearningPolicy(role: string, patch: Partial<ProjectAgentLearningPolicy>, projectRoot?: string): ProjectAgentLearningPolicy;
+/** Stamp the completion of an optimization pass so the cooldown can see it. */
+export declare function recordProjectAgentOptimizePass(role: string, projectRoot?: string, at?: string): void;
 //# sourceMappingURL=project-agent-learning-policy.d.ts.map

package/dist/coordination/agents/project-agent-learning-structured.d.ts

@@ -27,7 +27,43 @@ export interface StructuredLearnedEntry {
      * the optimization pass; unrouted entries stay role-level.
      */
     skill?: string | undefined;
+    /**
+     * Completed tasks where this directive was injected **and** the agent's
+     * report showed it was actually exercised (its anchors or distinctive
+     * wording appeared in the output).
+     *
+     * Optional so an entry can be constructed without a track record; treat a
+     * missing value as 0 by reading it through {@link directiveTrials}.
+     */
+    applied?: number | undefined;
+    /** Of those, the ones that ended in a successful task. */
+    wins?: number | undefined;
 }
+/** Normalized track record. A missing counter reads as 0, never as NaN. */
+export declare function directiveTrials(entry: Pick<StructuredLearnedEntry, 'applied' | 'wins'>): {
+    applied: number;
+    wins: number;
+    losses: number;
+};
+/**
+ * Laplace-smoothed success rate of a directive: the fraction of tasks that
+ * succeeded among those where the directive was actually exercised.
+ *
+ * An unproven directive scores exactly 0.5 — a neutral prior, not a penalty.
+ * That matters everywhere this is used as a ranking key: "no evidence" must
+ * never sort below "evidence of harm", which is the inversion the skill-level
+ * score used to have.
+ */
+export declare function directiveUtility(entry: Pick<StructuredLearnedEntry, 'applied' | 'wins'>): number;
+/** Trials before a directive's record is trusted enough to protect or retire it. */
+export declare const DIRECTIVE_PROVEN_MIN_APPLIED = 5;
+/** Utility at or above which a directive is treated as proven. */
+export declare const DIRECTIVE_PROVEN_MIN_UTILITY = 0.7;
+/**
+ * A directive that has earned the right not to be overwritten by a near
+ * duplicate: exercised enough times, and correlated with success when it was.
+ */
+export declare function isProvenDirective(entry: StructuredLearnedEntry): boolean;
 export declare function parseLearnedEntryStamp(entry: string): {
     capturedAt: string;
     category: LearnedEntryCategory | null;
@@ -47,7 +83,16 @@ export declare function mergeStructuredEntries(existing: StructuredLearnedEntry[
 export declare function renderLearnedInstructions(role: string, entries: StructuredLearnedEntry[], capturedAt: string): string;
 /**
  * Keep the rendered buffer within `maxBytes` by evicting the least valuable
- * entries — oldest first, plain facts before hard-won warnings.
+ * entries: plain facts before hard-won warnings, then the worst track record,
+ * then the oldest.
+ *
+ * Track record before age is the point of the ordering. Age says when a
+ * directive arrived; utility says whether it has ever helped. A directive that
+ * has been exercised eight times and correlated with failure every time is the
+ * cheapest thing in the buffer no matter how recently it was written, and a
+ * directive that keeps working should outlive newer arrivals. Entries with no
+ * record sit at the neutral 0.5 prior, so this reduces to the previous
+ * age-ordered behaviour for any buffer that predates outcome tracking.
  *
  * This replaces the old "block every automatic capture once the file passes
  * 8 KB" gate. That gate had no way to ever clear itself (consolidation wrote a

package/dist/coordination/agents/project-agent-quarantine.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The retired-directive log, and the surgery that keeps a retired directive
+ * from surviving inside a document that was distilled while it was still
+ * believed.
+ *
+ * Retirement removes a directive from the capture buffer, but by then it may
+ * already have been folded into `skills/<skill>.md` and `consolidated.md` —
+ * both of which are injected into every spawn and neither of which is rebuilt
+ * until the next optimization pass, up to six hours later. Without the scrub
+ * below, "stops being injected" was only true of the buffer, which is the one
+ * copy the agent was least likely to be reading.
+ *
+ * Its own module so both the writer (`project-agent-directive-outcome`) and the
+ * reader (`project-agent-consolidation`, building the distillation prompt) can
+ * depend on it without depending on each other.
+ */
+import { type StructuredLearnedEntry } from './project-agent-learning-structured.js';
+/** Ceiling on the retired-directive log. Local audit only; never injected. */
+export declare const QUARANTINE_MAX_BYTES: number;
+export interface QuarantinedDirective {
+    what: string;
+    skill?: string | undefined;
+}
+export declare function quarantinePath(role: string, projectRoot?: string): string;
+/**
+ * Append retired directives to the role's log.
+ *
+ * They are kept rather than deleted: a directive can be right about a project
+ * that has since changed, and the log is the only place to see what the loop
+ * decided to stop believing.
+ */
+export declare function appendQuarantine(role: string, retired: readonly StructuredLearnedEntry[], at: string, projectRoot?: string): void;
+/** Every directive this role has retired, newest last. */
+export declare function readQuarantinedDirectives(role: string, projectRoot?: string): QuarantinedDirective[];
+/**
+ * Remove any line that states one of the retired directives, together with the
+ * indented lines that hang off it.
+ *
+ * Line-oriented rather than model-driven on purpose: this runs on the task
+ * completion path, where a provider call is not affordable and a failure to
+ * scrub means the agent keeps being told to do the thing that kept failing.
+ */
+export declare function scrubRetiredLines(text: string, retired: readonly string[]): string;
+/**
+ * Whether a scrubbed document still says anything actionable.
+ *
+ * Chrome does not count. A skill addendum keeps its title and its standing
+ * "read these as refinements of the bundled skill" blockquote no matter how
+ * many rules are removed, so testing for "any long line" would report an
+ * addendum with nothing left in it as still having content.
+ */
+export declare function hasDirectiveContent(text: string): boolean;
+/**
+ * Retired directives worth warning the distiller about: the ones it could only
+ * resurrect from an existing document.
+ *
+ * A directive the agent has since written again is deliberately excluded. The
+ * whole reason retirement archives rather than deletes is that a rule can be
+ * right about a project that has since changed; if the role re-learned it, it
+ * is back in the buffer with a fresh record and has earned its second chance.
+ */
+export declare function retiredDirectivesToWarnAbout(role: string, currentDirectives: readonly string[], projectRoot?: string, skill?: string): string[];
+//# sourceMappingURL=project-agent-quarantine.d.ts.map

package/dist/coordination/agents/project-agent-skill-layer.d.ts

@@ -33,16 +33,27 @@ export declare function clearProjectSkillAugmentation(role: string, skill?: stri
 /** Skill names that have a project addendum for this role. */
 export declare function listProjectSkillAugmentations(role: string, projectRoot?: string): string[];
 /**
- * Render a distilled skill addendum. Used as the deterministic fallback when
- * no LLM is available — the directives are already instructive, so emitting
- * them verbatim under a stable header is strictly better than no addendum.
+ * Render a distilled skill addendum. Used as the deterministic fallback when no
+ * LLM is available — the directives are already instructive, so emitting them
+ * verbatim under a stable header is strictly better than no addendum.
+ *
+ * `existing` is **not optional in practice**: this renderer only ever sees the
+ * directives currently sitting in the capture buffer, and the buffer is pruned
+ * after every successful optimization. Rendering from the buffer alone and
+ * writing the result over the file therefore deleted every directive distilled
+ * by an earlier pass. That happened silently on any headless box, and on a
+ * model-backed one whenever a single per-skill call timed out and the role-level
+ * consolidation then pruned; the only remaining copy was under `archive/`.
+ *
+ * Passing the current addendum in keeps it: prior body first, new directives
+ * appended, near-duplicates of lines already present dropped.
  */
-export declare function renderSkillAugmentation(role: string, skill: string, directives: readonly string[], updatedAt: string): string;
+export declare function renderSkillAugmentation(role: string, skill: string, directives: readonly string[], updatedAt: string, existing?: string): string;
 /**
  * Instruction for the optimization pass: turn the directives that capture
  * routed to one skill into that skill's project addendum.
  */
-export declare function buildSkillDistillInstruction(role: string, skill: string, directives: readonly string[], existing?: string): string;
+export declare function buildSkillDistillInstruction(role: string, skill: string, directives: readonly string[], existing?: string, retired?: readonly string[]): string;
 export interface SkillAffinityEntry {
     /** Times this skill was eagerly loaded into a spawn of this role. */
     loaded: number;
@@ -63,17 +74,51 @@ export interface SkillAffinity {
 export declare function loadSkillAffinity(role: string, projectRoot?: string): SkillAffinity;
 /** Record that these skills were loaded into a spawn of `role`. */
 export declare function recordSkillLoad(role: string, skills: readonly string[], projectRoot?: string): void;
-/** Record the outcome of a task that ran with these skills loaded. */
+/**
+ * Record the outcome of a task that ran with these skills loaded.
+ *
+ * Also stamps `lastUsedAt`: an outcome is the strongest evidence that a skill
+ * was in use, and the recency decay in {@link scoreSkillAffinity} reads that
+ * stamp. Leaving it to `recordSkillLoad` alone meant an affinity file written
+ * only through this path looked like it had never been touched.
+ */
 export declare function recordSkillOutcome(role: string, skills: readonly string[], ok: boolean, projectRoot?: string): void;
 /** Record that a learned directive was routed to this skill. */
 export declare function recordSkillLearned(role: string, skill: string, projectRoot?: string): void;
 export declare function setSkillPinned(role: string, skill: string, pinned: boolean, projectRoot?: string): SkillAffinity;
+/** Half-life of outcome evidence, in days. Older evidence fades toward neutral. */
+export declare const SKILL_EVIDENCE_HALF_LIFE_DAYS = 30;
 /**
- * Score a skill for this role. Higher wins. Deterministic and monotone:
- * with no recorded history every candidate scores the same, so ranking falls
- * back to the curated order and behaviour matches a fresh project exactly.
+ * Score a skill for this role. Higher wins. Deterministic and monotone: with no
+ * recorded history every candidate scores exactly the same, so ranking falls
+ * back to the curated order and a fresh project behaves as if this layer did
+ * not exist.
+ *
+ * Four properties the previous scoring got wrong, each of which showed up as a
+ * skill that could not be dislodged:
+ *
+ * 1. **Failure counts against a skill.** The old form skipped Laplace smoothing
+ *    when there were no outcomes, so "no evidence" scored 0 while ten straight
+ *    failures scored 0.25 — failure ranked as evidence of relevance. The
+ *    success rate is now centred on the 0.5 prior, so a losing record is
+ *    negative and an untried skill is exactly neutral.
+ * 2. **Exposure is not merit.** `min(loaded, 10) * 0.1` paid a skill up to a
+ *    full point for having been selected, which is a loop: selected skills
+ *    out-scored unselected ones because they had been selected. The term is now
+ *    an exploration bonus that *decays* with load count, so a skill that has
+ *    never been tried is the one with something to prove.
+ * 3. **Evidence goes stale.** Counters are lifetime totals; a project that
+ *    switched test runners four months ago still carried the old runner's wins
+ *    at full weight. Outcome evidence now decays with a
+ *    {@link SKILL_EVIDENCE_HALF_LIFE_DAYS}-day half-life.
+ * 4. **One chatty skill could pin the top slot.** `learned * 2` is unbounded, so
+ *    a skill that attracts routing dominates every other signal forever. It is
+ *    now logarithmic: still the strongest single term, no longer a lock.
+ *
+ * A missing `lastUsedAt` means "unknown", not "ancient" — legacy affinity files
+ * written before the field existed must not have their evidence zeroed.
  */
-export declare function scoreSkillAffinity(entry: SkillAffinityEntry | undefined): number;
+export declare function scoreSkillAffinity(entry: SkillAffinityEntry | undefined, now?: number): number;
 /**
  * Rank the candidate skills for a role by project affinity, keeping the
  * curated order as a stable tie-break, and return at most `limit` names.

package/dist/coordination/agents/types.d.ts

@@ -91,8 +91,16 @@ export declare const TOOLS: {
     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", "mailbox"];
-    /** Version control. */
-    readonly vcs: readonly ["read", "grep", "glob", "git", "diff"];
+    /**
+     * Version control.
+     *
+     * `mailbox` is in every preset on purpose: a subagent that hits a wall must
+     * be able to say so. This was the one preset without it, which left the `git`
+     * and `release` roles able to fail but not to ask — the two roles whose work
+     * most often needs a decision from the leader (force-push, tag collision,
+     * dirty tree) and least often has a safe default.
+     */
+    readonly vcs: readonly ["read", "grep", "glob", "git", "diff", "mailbox"];
     /** Dependency management + CVE audit. */
     readonly deps: readonly ["read", "grep", "glob", "install", "outdated", "audit", "json", "mailbox"];
     /** Documentation authoring. */

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

@@ -101,13 +101,22 @@ export interface SubagentPromptParts {
  */
 export declare function composeSubagentPrompt(parts?: SubagentPromptParts): string;
 /**
- * Render a short bullet list summarising a roster — useful for stuffing
- * into `composeDirectorPrompt({ rosterSummary })` so the director model
- * can see available roles without scanning tool descriptions.
+ * Render a bullet list summarising a roster — stuffed into
+ * `composeDirectorPrompt({ rosterSummary })` so the leader can see the roles it
+ * may spawn without scanning tool descriptions.
  *
- * Each entry: `- <role-id>: <name>[ (provider/model)] — <prompt-headline>`
- * The prompt headline is the first non-empty line of `config.prompt`,
- * truncated to 80 chars. Skipped entirely when the role has no prompt.
+ * Each entry: `- <role-id>[ (<name>)][ (provider/model)] — <capability>`
+ *
+ * The capability comes from `dispatch.summary`, the curated one-liner the
+ * catalog already writes for every agent and the dispatcher already routes on.
+ * It used to come from the first 80 characters of `config.prompt`, which is
+ * how a 77-role menu came to read as 77 variations of "You are the X agent.
+ * Your job is…" with the discriminating half cut off. A leader given that list
+ * can only reliably pick the roles whose id spells out the job — and the usage
+ * data matched exactly that: 57 of the 77 roles had never once been chosen.
+ *
+ * The prompt headline stays as the fallback for roles with no dispatch
+ * metadata, so a hand-written project role is still listed.
  */
 export declare function rosterSummaryFromConfigs(roster: Record<string, {
     name: string;
@@ -115,5 +124,9 @@ export declare function rosterSummaryFromConfigs(roster: Record<string, {
     model?: string | undefined;
     prompt?: string | undefined;
     role?: string | undefined;
+    dispatch?: {
+        summary: string;
+        keywords: string[];
+    } | undefined;
 }>): string;
 //# sourceMappingURL=director-prompts.d.ts.map

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

@@ -1,9 +1,9 @@
 import type { SubagentConfig } from '../types/multi-agent.js';
 import type { Tool } from '../types/tool.js';
 import type * as Host from './director-host-contracts.js';
-export { makeQualityGateTool } from './director-quality-gate-tool.js';
-export { makeCollabDebugTool, makeFleetEmitTool, makeWorkCompleteTool, } from './director-collab-tools.js';
 export { makeAskResultTool, makeAskTool, makeAssignTool, makeAwaitTasksTool, makeFleetTool, makeRollUpTool, makeTerminateAllTool, makeTerminateTool, } from './director-basic-tools.js';
+export { makeCollabDebugTool, makeFleetEmitTool, makeWorkCompleteTool, } from './director-collab-tools.js';
+export { makeQualityGateTool } from './director-quality-gate-tool.js';
 export declare function makeSpawnTool(director: Host.DirectorAdmissionPort, roster?: Record<string, SubagentConfig>): Tool;
 export declare function makeKanbanQueueTool(director: Host.DirectorLeaseRecoveryPort, roster?: Record<string, SubagentConfig>): Tool;
 //# sourceMappingURL=director-tools.d.ts.map

package/dist/coordination/fleet.d.ts

@@ -26,12 +26,6 @@ export declare const REFACTOR_PLANNER_AGENT: SubagentConfig;
 export declare const SECURITY_SCANNER_AGENT: SubagentConfig;
 /** Generic template used directly or cloned into project-specific roles. */
 export declare const GENERIC_AGENT: SubagentConfig;
-/**
- * All agents in a map for easy lookup by role. The 75-role phase catalog
- * (`ALL_AGENT_DEFINITIONS`) already includes `critic` and the historical
- * audit/review specialists. Adding standalone `generic` and `shadow-agent`
- * roles produces 77 unique built-in role ids.
- */
 export declare const FLEET_ROSTER: Record<string, SubagentConfig>;
 export interface FleetRosterBudget {
     timeoutMs?: number | undefined;

package/dist/coordination/index.d.ts

@@ -1,6 +1,6 @@
 export { createMessage, InMemoryAgentBridge, InMemoryBridgeTransport, } from './agent-bridge.js';
 export { type AgentFactory, type AgentFactoryResult, type AgentRunnerOptions, makeAgentSubagentRunner, withDisabledToolFiltering, } from './agent-subagent-runner.js';
-export { AGENT_CATALOG, AGENTS_BY_PHASE, type AgentBudgetTier, type AgentCapability, type AgentDefinition, type AgentPhase, ALL_AGENT_DEFINITIONS, applyProjectAgentConfig, assertProjectAgentRole, BUILD_AGENTS, buildConsolidationInstruction, buildProjectContextualizedPrompt, buildSkillDistillInstruction, CAPTURE_COOLDOWN_MS, CAPTURE_MAX_PER_SESSION, CAPTURE_SESSION_WINDOW_MS, type ConsolidationMetadata, type CreateProjectAgentInput, canCaptureNewLearned, captureLearnedFromAgentOutput, captureLearnedFromAgentOutputDetailed, clearProjectAgentConsolidated, clearProjectSkillAugmentation, createProjectAgent, createProjectAgentRoster, DEFAULT_EAGER_SKILL_LIMIT, DELIVERY_AGENTS, DISCOVERY_AGENTS, DOMAIN_AGENTS, detectLearnedConflicts, getAgentDefinition, getProjectAgentLearnStats, HEAVY_BUDGET, hintLearnedNeedsSummarization, isConsolidated, KNOWLEDGE_AGENTS, LEARNED_HARD_LIMIT, LEARNED_SOFT_LIMIT, type LearnedCaptureResult, type AutoOptimizeDecision, type AutoOptimizeEvent, type AutoOptimizePolicy, type AutoOptimizePolicyOverrides, DEFAULT_AUTO_OPTIMIZE_POLICY, evaluateAutoOptimize, LearningOptimizationScheduler, type LearningOptimizationSchedulerOptions, resolveAutoOptimizePolicy, type LearningOptimizerLlm, LIGHT_BUDGET, type OptimizeLearningOptions, type OptimizeLearningResult, optimizeProjectAgentLearning, unwrapWholeDocumentFence, listProjectAgentLearnedEntries, listProjectAgentRoles, listProjectSkillAugmentations, loadConsolidationMetadata, loadProjectAgentConfig, loadProjectAgentConsolidated, loadProjectAgentIdentity, loadProjectAgentLearned, loadProjectAgentLearningPolicy, loadProjectAgentProfile, loadProjectSkillAugmentation, loadRoleKnowledgeManifest, loadSkillAffinity, MEDIUM_BUDGET, META_AGENTS, PLANNING_AGENTS, type ProjectAgentConfig, type ProjectAgentLearningPolicy, type ProjectAgentProfile, REVIEW_AGENTS, type RoleKnowledgeManifest, rankRoleSkills, readRawLearnedEntries, recordSkillLoad, recordSkillOutcome, refreshProjectAgentIdentity, renderSkillAugmentation, resetCaptureWindow, resetCaptureWindows, resetProjectAgentIdentity, resolveRoleSkillCandidates, routeDirectiveToSkill, SKILL_AUGMENTATION_MAX_BYTES, type SaveConsolidationOptions, type SkillAffinity, type SkillAffinityEntry, saveProjectAgentConsolidated, saveProjectSkillAugmentation, setSkillPinned, slugifyProjectAgentRole, updateProjectAgentConfig, updateProjectAgentIdentity, updateProjectAgentKnowledge, updateProjectAgentLearned, updateProjectAgentLearningPolicy, VERIFY_AGENTS, validateProjectAgentConfig, } from './agents/index.js';
+export { AGENT_CATALOG, AGENTS_BY_PHASE, type AgentBudgetTier, type AgentCapability, type AgentDefinition, type AgentPhase, ALL_AGENT_DEFINITIONS, type AutoOptimizeDecision, type AutoOptimizeEvent, type AutoOptimizePolicy, type AutoOptimizePolicyOverrides, applyProjectAgentConfig, assertProjectAgentRole, BUILD_AGENTS, buildConsolidationInstruction, buildProjectContextualizedPrompt, buildSkillDistillInstruction, CAPTURE_COOLDOWN_MS, CAPTURE_MAX_PER_SESSION, CAPTURE_SESSION_WINDOW_MS, type ConsolidationMetadata, type CreateProjectAgentInput, canCaptureNewLearned, captureLearnedFromAgentOutput, captureLearnedFromAgentOutputDetailed, clearProjectAgentConsolidated, clearProjectSkillAugmentation, consolidatedDocumentPath, createProjectAgent, createProjectAgentRoster, DEFAULT_AUTO_OPTIMIZE_POLICY, DEFAULT_EAGER_SKILL_LIMIT, DELIVERY_AGENTS, DIRECTIVE_QUARANTINE_MAX_UTILITY, DIRECTIVE_QUARANTINE_MIN_APPLIED, DISCOVERY_AGENTS, type DirectiveOutcomeResult, DOMAIN_AGENTS, detectLearnedConflicts, directiveTrials, directiveUtility, directiveWasApplied, evaluateAutoOptimize, getAgentDefinition, getProjectAgentLearnStats, HEAVY_BUDGET, hintLearnedNeedsSummarization, isConsolidated, isProvenDirective, KNOWLEDGE_AGENTS, LEARNED_HARD_LIMIT, LEARNED_SOFT_LIMIT, type LearnedCaptureResult, LearningOptimizationScheduler, type LearningOptimizationSchedulerOptions, type LearningOptimizerLlm, LIGHT_BUDGET, listProjectAgentLearnedEntries, listProjectAgentRoles, listProjectSkillAugmentations, loadConsolidationMetadata, loadProjectAgentConfig, loadProjectAgentConsolidated, loadProjectAgentIdentity, loadProjectAgentLearned, loadProjectAgentLearningPolicy, loadProjectAgentProfile, loadProjectSkillAugmentation, loadRoleKnowledgeManifest, loadSkillAffinity, MEDIUM_BUDGET, META_AGENTS, type OptimizeLearningOptions, type OptimizeLearningResult, optimizeProjectAgentLearning, PLANNING_AGENTS, type ProjectAgentConfig, type ProjectAgentLearningPolicy, type ProjectAgentProfile, type QuarantinedDirective, quarantinePath, REVIEW_AGENTS, type RoleKnowledgeManifest, rankRoleSkills, readQuarantinedDirectives, readRawLearnedEntries, recordDirectiveOutcomes, recordSkillLoad, recordSkillOutcome, refreshProjectAgentIdentity, renderSkillAugmentation, resetCaptureWindow, resetCaptureWindows, resetProjectAgentIdentity, resolveAutoOptimizePolicy, resolveRoleSkillCandidates, retiredDirectivesToWarnAbout, routeDirectiveToSkill, type SaveConsolidationOptions, SKILL_AUGMENTATION_MAX_BYTES, type SkillAffinity, type SkillAffinityEntry, saveProjectAgentConsolidated, saveProjectSkillAugmentation, scoreSkillAffinity, scrubRetiredLines, setSkillPinned, slugifyProjectAgentRole, unwrapWholeDocumentFence, updateProjectAgentConfig, updateProjectAgentIdentity, updateProjectAgentKnowledge, updateProjectAgentLearned, updateProjectAgentLearningPolicy, VERIFY_AGENTS, validateProjectAgentConfig, } from './agents/index.js';
 export { type AutoExtendCeiling, type AutoExtendPolicy, attachAutoExtend, } from './auto-extend.js';
 export { type BrainArbiter, type BrainDecision, type BrainDecisionOption, BrainDecisionQueue, type BrainDecisionRequest, type BrainDecisionSource, type BrainEscalationMode, type BrainFallback, type BrainRisk, DefaultBrainArbiter, type DefaultBrainArbiterOptions, EscalationRoutingBrainArbiter, formatHumanPrompt, HumanEscalatingBrainArbiter, ObservableBrainArbiter, terminalPolicyDecision, } from './brain.js';
 export { BrainDecisionLedger, type BrainDecisionLedgerOptions, type BrainLedgerEntry, brainDecisionKey, createLedgerGuardBrainArbiter, type LedgerGuardBrainArbiterOptions, } from './brain-ledger.js';
@@ -34,6 +34,7 @@ export type { MailboxCredentialVerifier, RedactedMailboxCredential, } from './ma
 export { redactMailboxCredential } from './mailbox-credential-store.js';
 export { CREDENTIAL_VERIFY_COOLDOWN_MS, CREDENTIAL_VERIFY_MAX_FAILURES, CREDENTIAL_VERIFY_WINDOW_MS, CredentialVerifyThrottle, credentialVerifyThrottle, } from './mailbox-credential-throttle.js';
 export { MailboxEventEmitter } from './mailbox-events.js';
+export { mailboxProjectServerEndpoint, mailboxProjectServerMetadataPath, } from './mailbox-project-server-endpoint.js';
 export { buildDownAlert, buildRecoveryAlert, type DownAlertInput, MAILBOX_HEALTH_DEFAULT_FAILURE_THRESHOLD, MAILBOX_HEALTH_DEFAULT_FROM, MAILBOX_HEALTH_DEFAULT_INTERVAL_MS, MAILBOX_HEALTH_DEFAULT_TIMEOUT_MS, type MailboxHealthEvent, MailboxHealthWatchdog, type MailboxHealthWatchdogOptions, type RecoveryAlertInput, validateWatchdogOptions, type WatchdogConfig, } from './mailbox-health.js';
 export { createMailboxHooks, type MailboxHooksOptions, } from './mailbox-hooks.js';
 export { authorizeMailboxBearerToken, authorizePersistedMailboxCredential, createMailboxHttpRouter, MAILBOX_HTTP_DEFAULT_MAX_AGE_MS, MAILBOX_HTTP_MAX_AGE_CEILING_MS, MAILBOX_HTTP_MAX_BODY_BYTES, MAILBOX_HTTP_RATE_LIMIT_PER_MINUTE, MAILBOX_HTTP_RATE_LIMIT_WINDOW_MS, type MailboxHttpAccessDecision, MailboxHttpRateLimiter, type MailboxHttpRouter, type MailboxHttpRouterOptions, } from './mailbox-http-router.js';