@wrongstack/core 0.303.0 → 0.305.0

package/dist/execution/council-orchestrator.d.ts

@@ -53,23 +53,13 @@ export declare class CouncilOrchestrator {
     private readonly fallbackProfileManager;
     private readonly seatCaller;
     private readonly judgeCaller;
-    /**
-     * Normalized ad-hoc profiles keyed by the caller's config object identity.
-     * The Brain adapter reuses ONE profile object for every decision, so this
-     * avoids re-validating + re-freezing it on every ask() without caching
-     * string-keyed registry lookups (those are already O(1)).
-     *
-     * Hosts must treat ad-hoc profile configs as IMMUTABLE once passed to
-     * ask(): the cache is keyed by object identity and never invalidated, so
-     * mutating a cached profile would silently serve the first snapshot.
-     */
-    private readonly profileCache;
     constructor(opts: CouncilOrchestratorOptions);
     /**
      * Resolve the effective profile for a question. String ids and the default
      * go through the registry (already O(1)); ad-hoc config objects are
-     * normalized once per stable object identity and cached, because hosts such
-     * as the Brain adapter pass the same profile object on every ask().
+     * normalized on each call. Callers are allowed to reuse and mutate an
+     * ad-hoc object between decisions, so object-identity caching would serve a
+     * stale snapshot.
      */
     private resolveProfile;
     ask(question: CouncilQuestion): Promise<CouncilResult>;

package/dist/execution/index.js

@@ -480,6 +480,12 @@ function getModelFamilyRatio(calibrationKey) {
 }
 
 // src/core/conversation-state.ts
+function hasToolResultBlock(message) {
+  return message !== void 0 && Array.isArray(message.content) && message.content.some((block) => block.type === "tool_result");
+}
+function hasToolUseBlock(message) {
+  return message?.role === "assistant" && Array.isArray(message.content) && message.content.some((block) => block.type === "tool_use");
+}
 var ConversationState = class {
   ctx;
   listeners = /* @__PURE__ */ new Set();
@@ -547,15 +553,32 @@ var ConversationState = class {
    */
   overflowCount(arr) {
     let drop = Context.MAX_MESSAGES > 0 ? Math.max(0, arr.length - Context.MAX_MESSAGES) : 0;
-    if (Context.MAX_MESSAGE_TOKENS <= 0) return drop;
+    if (Context.MAX_MESSAGE_TOKENS <= 0) return this.protocolSafeDropCount(arr, drop);
     let total = 0;
     for (let i = drop; i < arr.length; i++) total += arr[i]?._estTokens ?? 0;
-    if (total <= Context.MAX_MESSAGE_TOKENS) return drop;
+    if (total <= Context.MAX_MESSAGE_TOKENS) return this.protocolSafeDropCount(arr, drop);
     while (drop < arr.length - 1 && total > Context.MAX_MESSAGE_TOKENS) {
       total -= arr[drop]?._estTokens ?? 0;
       drop++;
     }
-    return drop;
+    return this.protocolSafeDropCount(arr, drop);
+  }
+  /**
+   * Front eviction must not retain a `tool_result` after evicting the
+   * immediately preceding assistant `tool_use`. Long tool-heavy sessions sit
+   * at the retention cap, so an unsafe boundary would create a fresh orphan on
+   * nearly every append and make the request-time repair discard protocol
+   * history continuously.
+   *
+   * Move the boundary backward to retain the complete exchange for one more
+   * eviction cycle. Moving it forward would also drop non-protocol text/images
+   * that may share either message. The temporary one-message cap overshoot is
+   * the minimum lossless representation; once enough newer messages exist, the
+   * next eviction boundary naturally moves past both halves together.
+   */
+  protocolSafeDropCount(arr, drop) {
+    if (drop <= 0 || drop >= arr.length) return drop;
+    return hasToolResultBlock(arr[drop]) && hasToolUseBlock(arr[drop - 1]) ? drop - 1 : drop;
   }
   /**
    * Append a content block to the trailing user message's content array.
@@ -960,6 +983,28 @@ var Context = class _Context {
       return _Context.CONVERSATION_JOURNAL_MAX_BYTES + 1;
     }
   }
+  _journalDropCount = 0;
+  _journalDropWarnAt = 0;
+  /** Throttled notice that a conversation event never reached the journal. */
+  warnConversationJournalDrop(eventType) {
+    this._journalDropCount++;
+    const now = Date.now();
+    if (now - this._journalDropWarnAt < 5e3) return;
+    this._journalDropWarnAt = now;
+    const dropped = this._journalDropCount;
+    this._journalDropCount = 0;
+    console.warn(
+      JSON.stringify({
+        level: "error",
+        event: "session.conversation_journal_drop",
+        sessionId: this.session?.id,
+        eventType,
+        droppedEvents: dropped,
+        message: "Session writer is not draining; replay of this session will be incomplete.",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      })
+    );
+  }
   enqueueConversationJournal(event, writer) {
     const bytes = this.conversationJournalBytes(event);
     const shouldSnapshot = event.type === "messages_replaced" || this._conversationJournalQueue.length >= _Context.CONVERSATION_JOURNAL_MAX_EVENTS || this._conversationJournalBytes + bytes > _Context.CONVERSATION_JOURNAL_MAX_BYTES;
@@ -977,18 +1022,21 @@ var Context = class _Context {
         this._conversationJournalBytes = Math.max(0, this._conversationJournalBytes - queued.bytes);
         this._conversationJournalQueue.splice(index, 1);
       }
-      if (snapshotBytes <= _Context.CONVERSATION_JOURNAL_MAX_BYTES) {
-        this._conversationJournalQueue.push({ event: snapshot, bytes: snapshotBytes, writer });
-        this._conversationJournalBytes += snapshotBytes;
-      }
+      this._conversationJournalQueue.push({ event: snapshot, bytes: snapshotBytes, writer });
+      this._conversationJournalBytes += snapshotBytes;
     } else {
       this._conversationJournalQueue.push({ event, bytes, writer });
       this._conversationJournalBytes += bytes;
     }
     while (this._conversationJournalQueue.length > _Context.CONVERSATION_JOURNAL_MAX_EVENTS || this._conversationJournalBytes > _Context.CONVERSATION_JOURNAL_MAX_BYTES) {
-      const dropped = this._conversationJournalQueue.shift();
+      const index = this._conversationJournalQueue.findIndex(
+        (queued) => queued.event.type !== "messages_replaced"
+      );
+      if (index === -1) break;
+      const [dropped] = this._conversationJournalQueue.splice(index, 1);
       if (!dropped) break;
       this._conversationJournalBytes = Math.max(0, this._conversationJournalBytes - dropped.bytes);
+      this.warnConversationJournalDrop(dropped.event.type);
     }
     this.startConversationJournalDrain();
   }
@@ -5042,12 +5090,97 @@ var FallbackProfileManager = class {
     return this.resolveRefs([ref], exclude);
   }
   /**
-   * Resolve every usable configured target as an uncapped last-resort chain.
+   * Resolve every usable configured target as a bounded last-resort chain.
    * Normal smart defaults stay bounded; callers append this only after the
-   * preferred chain and only when automatic fallback is enabled.
+   * preferred chain and only when automatic fallback is enabled. The cap
+   * ({@link MAX_LAST_RESORT_CANDIDATES}) prevents a config with many providers
+   * from producing a degenerate chain of doomed requests during a systemic
+   * outage — by this point the smart default, bridge, and default profile
+   * have already failed.
    */
   resolveAllConfigured(exclude) {
-    return this.smartDefault(exclude, Number.POSITIVE_INFINITY);
+    return this.smartDefault(exclude, this.lastResortCap());
+  }
+  /**
+   * Effective cap for the last-resort append. Reads the user-configurable
+   * {@link Config.fallbackMaxLastResortCandidates} when set and valid;
+   * otherwise falls back to the compiled-in default
+   * {@link MAX_LAST_RESORT_CANDIDATES}.
+   */
+  lastResortCap() {
+    const configured = this.config.fallbackMaxLastResortCandidates;
+    if (typeof configured === "number" && Number.isFinite(configured) && configured >= 0) {
+      return Math.floor(configured);
+    }
+    return MAX_LAST_RESORT_CANDIDATES;
+  }
+  /**
+   * Build the complete fallback candidate chain shared by the agent-loop
+   * extension and the one-shot orchestrator. Centralizes the bridge → primary →
+   * selected → default-profile → all-configured ladder and the fromExplicitSource
+   * gate so both consumers produce identical ordering and depth semantics.
+   *
+   * Layering (each step deduped against all prior):
+   *  1. Bridge (emergency continuity route).
+   *  2. Configured primary, when the live context drifted from it.
+   *  3. The selected chain (explicit refs → named profile → smart default),
+   *     via {@link resolveEffective}.
+   *  4. The "default" profile — extra depth, ONLY when the chain was auto-derived.
+   *  5. Every other configured provider — last resort, ONLY when the chain was
+   *     auto-derived AND `effectiveFallbackAuto` is true.
+   *
+   * Returns the empty chain when `closedWorld` is true and no explicit
+   * refs/profile resolved — a model allowlist never leaks to unlisted models.
+   *
+   * @internal caller-aware options (primary, closedWorld) are accepted because
+   *   the agent loop has context the manager does not own; the resolution
+   *   pipeline itself is identical for both callers.
+   */
+  resolveCandidates(current, opts = {}) {
+    const configuredPrimary = opts.primary ?? {
+      providerId: this.config.provider,
+      model: this.config.model
+    };
+    const configFallbackAuto = this.config.fallbackAuto;
+    const effectiveFallbackAuto = configFallbackAuto !== void 0 && configFallbackAuto !== null ? configFallbackAuto : !opts.closedWorld;
+    const explicitRefs = opts.fallbackModels ?? this.config.fallbackModels;
+    const explicitUsable = explicitRefs !== void 0 && explicitRefs.length > 0 && this.resolveRefs(explicitRefs, current).length > 0;
+    const profileUsable = opts.fallbackProfile !== void 0 && this.hasProfile(opts.fallbackProfile) && this.resolve(opts.fallbackProfile, { exclude: current }).length > 0;
+    const fromExplicitSource = explicitUsable || profileUsable;
+    const selectedChain = opts.closedWorld ? explicitRefs && explicitRefs.length > 0 ? this.resolveRefs(explicitRefs, current) : opts.fallbackProfile ? this.resolve(opts.fallbackProfile, { exclude: current }) : FREEZER_EMPTY : this.resolveEffective({
+      fallbackModels: explicitRefs,
+      fallbackProfile: opts.fallbackProfile,
+      fallbackAuto: effectiveFallbackAuto,
+      exclude: current
+    });
+    const candidates = [];
+    if (opts.closedWorld) {
+      candidates.push(...selectedChain);
+    } else {
+      candidates.push(...this.resolveBridge(current));
+      if (!(configuredPrimary.providerId === current.providerId && configuredPrimary.model === current.model)) {
+        candidates.push({
+          providerId: configuredPrimary.providerId,
+          model: configuredPrimary.model,
+          providerSwitched: configuredPrimary.providerId !== current.providerId
+        });
+      }
+      candidates.push(...selectedChain);
+      if (!fromExplicitSource && effectiveFallbackAuto && opts.fallbackProfile !== "default") {
+        candidates.push(...this.resolve("default", { exclude: current }));
+      }
+      if (!fromExplicitSource && effectiveFallbackAuto) {
+        const cap = this.lastResortCap();
+        if (cap > 0) {
+          const usedKeys = new Set(
+            candidates.map((c) => `${c.providerId}/${c.model}`)
+          );
+          const lastResort = this.smartDefault(current, Number.POSITIVE_INFINITY).filter((c) => !usedKeys.has(`${c.providerId}/${c.model}`)).slice(0, cap);
+          candidates.push(...lastResort);
+        }
+      }
+    }
+    return dedupeChain(candidates, current);
   }
   // ── Provider availability (read-only) ──────────────────────────────────
   checkProvider(providerId) {
@@ -5171,7 +5304,20 @@ var FallbackProfileManager = class {
     );
   }
 };
+var MAX_LAST_RESORT_CANDIDATES = 12;
 var FREEZER_EMPTY = Object.freeze([]);
+function dedupeChain(entries, current) {
+  const seen = /* @__PURE__ */ new Set();
+  const currentKey = `${current.providerId}/${current.model}`;
+  return Object.freeze(
+    entries.filter((entry) => {
+      const key = `${entry.providerId}/${entry.model}`;
+      if (key === currentKey || seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    })
+  );
+}
 
 // src/core/fallback-model.ts
 function effectiveFallbackChain(config) {
@@ -5762,17 +5908,6 @@ var CouncilOrchestrator = class {
   fallbackProfileManager;
   seatCaller;
   judgeCaller;
-  /**
-   * Normalized ad-hoc profiles keyed by the caller's config object identity.
-   * The Brain adapter reuses ONE profile object for every decision, so this
-   * avoids re-validating + re-freezing it on every ask() without caching
-   * string-keyed registry lookups (those are already O(1)).
-   *
-   * Hosts must treat ad-hoc profile configs as IMMUTABLE once passed to
-   * ask(): the cache is keyed by object identity and never invalidated, so
-   * mutating a cached profile would silently serve the first snapshot.
-   */
-  profileCache = /* @__PURE__ */ new WeakMap();
   constructor(opts) {
     if (!opts.caller && !opts.seatCaller && !opts.judgeCaller) {
       throw new Error("CouncilOrchestrator: provide `caller`, `seatCaller`, or `judgeCaller`.");
@@ -5792,8 +5927,9 @@ var CouncilOrchestrator = class {
   /**
    * Resolve the effective profile for a question. String ids and the default
    * go through the registry (already O(1)); ad-hoc config objects are
-   * normalized once per stable object identity and cached, because hosts such
-   * as the Brain adapter pass the same profile object on every ask().
+   * normalized on each call. Callers are allowed to reuse and mutate an
+   * ad-hoc object between decisions, so object-identity caching would serve a
+   * stale snapshot.
    */
   resolveProfile(profile) {
     if (typeof profile === "string" || profile === void 0) {
@@ -5803,15 +5939,11 @@ var CouncilOrchestrator = class {
         defaultProfile: this.defaultProfile
       });
     }
-    const cached = this.profileCache.get(profile);
-    if (cached) return cached;
-    const resolved = resolveCouncilProfile(profile, {
+    return resolveCouncilProfile(profile, {
       registry: this.profiles,
       personas: this.personas,
       defaultProfile: this.defaultProfile
     });
-    this.profileCache.set(profile, resolved);
-    return resolved;
   }
   async ask(question) {
     const startedAt = Date.now();
@@ -11643,52 +11775,24 @@ var OneShotOrchestrator = class {
   }
   /**
    * Build the fallback model chain from input + config + current target.
+   * Delegates to {@link FallbackProfileManager.resolveCandidates} — the
+   * shared constructor used by both the agent loop and the one-shot path,
+   * so both produce identical ordering, depth, and fromExplicitSource
+   * semantics.
+   *
    * The injected {@link OneShotOrchestratorOptions.fallbackProfileManager}
    * is the only allowed manager — OneShot never owns a private snapshot
    * so a live `ConfigStore` change reaches every call without rebuilding
    * the manager.
    */
   resolveFallbackChain(input, config, target) {
-    const mgr = this.opts.fallbackProfileManager;
-    let fromExplicitSource = false;
-    let selected = mgr.resolveEffective({
-      fallbackAuto: false,
-      exclude: target
+    return this.opts.fallbackProfileManager.resolveCandidates(target, {
+      fallbackModels: input.fallbackModels && input.fallbackModels.length > 0 ? input.fallbackModels : config.fallbackModels,
+      // The one-shot already tried `target` as the primary before entering
+      // the chain. Passing it as `primary` suppresses the primary-insertion
+      // step in resolveCandidates (primary === current → not pushed).
+      primary: target
     });
-    if (input.fallbackModels && input.fallbackModels.length > 0) {
-      const resolved = mgr.resolveEffective({
-        fallbackModels: input.fallbackModels,
-        fallbackAuto: false,
-        exclude: target
-      });
-      selected = resolved;
-      fromExplicitSource = resolved.length > 0;
-    } else if (config.fallbackModels && config.fallbackModels.length > 0) {
-      const resolved = mgr.resolveEffective({
-        fallbackModels: config.fallbackModels,
-        fallbackAuto: false,
-        exclude: target
-      });
-      selected = resolved;
-      fromExplicitSource = resolved.length > 0;
-    } else if (config.fallbackAuto !== false) {
-      selected = mgr.resolveEffective({
-        fallbackAuto: true,
-        exclude: target
-      });
-    }
-    if (config.fallbackAuto === false) return selected;
-    if (fromExplicitSource) return selected;
-    const combined = [...selected, ...mgr.resolveAllConfigured(target)];
-    const seen = /* @__PURE__ */ new Set();
-    return Object.freeze(
-      combined.filter((entry) => {
-        const key = `${entry.providerId}/${entry.model}`;
-        if (seen.has(key)) return false;
-        seen.add(key);
-        return true;
-      })
-    );
   }
   /** Attempt a provider call while preserving the actual failure for callers. */
   async tryCall(provider, request, signal, providerId, model) {
@@ -12972,6 +13076,12 @@ function normalizeForComparison(text) {
 }
 
 // src/coordination/agents/project-agent-learning-structured.ts
+function directiveTrials(entry) {
+  const count = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0 ? Math.floor(n) : 0;
+  const applied = count(entry.applied);
+  const wins = Math.min(applied, count(entry.wins));
+  return { applied, wins, losses: applied - wins };
+}
 function parseLearnedEntryStamp(entry) {
   const structuredMatch = entry.match(
     /<!--\s*learned-stamp:\s*category=([\w-]+);\s*capturedAt=([^;]+?)\s*-->/
@@ -13090,6 +13200,10 @@ function parseStructuredLearnedEntriesFromContent(raw, legacyEntries = splitLear
     const category = parseLearnedCategory(attributes["category"]) ?? "fact";
     const capturedAt = attributes["capturedAt"] ?? "";
     const skill = attributes["skill"];
+    const trials = directiveTrials({
+      applied: Number(attributes["applied"]),
+      wins: Number(attributes["wins"])
+    });
     const start = (stamp.index ?? 0) + stamp[0].length;
     const end = stamps[index + 1]?.index ?? raw.length;
     const parsed = parseEntryBody(raw.slice(start, end));
@@ -13101,7 +13215,8 @@ function parseStructuredLearnedEntriesFromContent(raw, legacyEntries = splitLear
       why: parsed.why || WHY_BY_CATEGORY[category],
       how: parsed.how,
       capturedAt,
-      ...skill ? { skill } : {}
+      ...skill ? { skill } : {},
+      ...trials.applied > 0 ? { applied: trials.applied, wins: trials.wins } : {}
     });
   }
   if (structured.length === 0) {
@@ -13231,7 +13346,8 @@ function loadProjectAgentLearningPolicy(role, projectRoot) {
       enabled: parsed.enabled !== false,
       lifetimeCaptureCount: typeof parsed.lifetimeCaptureCount === "number" && Number.isInteger(parsed.lifetimeCaptureCount) && parsed.lifetimeCaptureCount >= 0 ? parsed.lifetimeCaptureCount : 0,
       ...typeof parsed.lastCaptureAt === "string" ? { lastCaptureAt: parsed.lastCaptureAt } : {},
-      ...parsed.lastCaptureSource === "automatic" || parsed.lastCaptureSource === "manual" || parsed.lastCaptureSource === "taught" ? { lastCaptureSource: parsed.lastCaptureSource } : {}
+      ...parsed.lastCaptureSource === "automatic" || parsed.lastCaptureSource === "manual" || parsed.lastCaptureSource === "taught" ? { lastCaptureSource: parsed.lastCaptureSource } : {},
+      ...typeof parsed.lastOptimizeAt === "string" ? { lastOptimizeAt: parsed.lastOptimizeAt } : {}
     };
   } catch {
     return { ...DEFAULT_LEARNING_POLICY };
@@ -13641,6 +13757,8 @@ The file below stores **learning data for this project's "${role}" agent** \u201
 - **Self-contained** \u2014 understandable without the surrounding session context.
 - **Front-load concrete anchors** \u2014 commands in backticks, package names like \`@wrongstack/core\`, file paths like \`packages/core/src/.../foo.ts\`. The structured-list renderer extracts these as the "how" for the entry.
 
+**Your directives are scored against real outcomes.** After every task the runtime checks which stored directives were actually exercised \u2014 it matches their anchors against the report \u2014 and folds that task's success or failure into each one's record. A directive that keeps correlating with success outlives newer arrivals and survives rewording; one that has been exercised repeatedly and kept correlating with failure is retired and stops being injected. Two consequences for how you write them: anchors are what make a directive *measurable*, not just runnable, so an anchorless directive can never earn a record; and a directive you are unsure about costs nothing to write, because the loop will find out.
+
 **Tag the skill you are developing.** When a directive refines one of your skills, mark it: \`## LEARNED [skill: testing]\`. Tagged directives are distilled into that skill's project addendum, so the lesson arrives as part of the skill itself on every future run instead of as a loose fact. Untagged directives are routed automatically when the wording makes the target obvious, and stay role-level otherwise.
 
 **Bad** (session log \u2014 rejected at capture time):
@@ -13925,8 +14043,16 @@ var TOOLS = {
     "test",
     "mailbox"
   ],
-  /** Version control. */
-  vcs: ["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.
+   */
+  vcs: ["read", "grep", "glob", "git", "diff", "mailbox"],
   /** Dependency management + CVE audit. */
   deps: ["read", "grep", "glob", "install", "outdated", "audit", "json", "mailbox"],
   /** Documentation authoring. */
@@ -16610,6 +16736,14 @@ var SHADOW_AGENT = {
 };
 var CRITIC_AGENT = defineAgent("critic", "Critic");
 var GENERIC_AGENT = defineAgent("generic", "Generic Project Agent");
+function withDispatchMetadata(definition) {
+  const summary = definition.capability?.summary?.trim();
+  if (!summary) return definition.config;
+  return {
+    ...definition.config,
+    dispatch: { summary, keywords: [...definition.capability.keywords ?? []] }
+  };
+}
 var FLEET_ROSTER = {
   "audit-log": AUDIT_LOG_AGENT,
   "bug-hunter": BUG_HUNTER_AGENT,
@@ -16619,7 +16753,7 @@ var FLEET_ROSTER = {
   generic: GENERIC_AGENT,
   "shadow-agent": SHADOW_AGENT,
   ...Object.fromEntries(
-    ALL_AGENT_DEFINITIONS.map((d) => [d.config.role, d.config])
+    ALL_AGENT_DEFINITIONS.map((d) => [d.config.role, withDispatchMetadata(d)])
   )
 };
 var DEFAULT_IDLE_TIMEOUT_MS = 10 * 60 * 1e3;
@@ -21244,7 +21378,7 @@ async function evaluateToolKanbanBoundary(tool, input, ctx, options = {}) {
     } : { decision: "allow" };
   }
   const task = identity.taskId ? board.tasks.find((candidate) => candidate.id === identity.taskId) : void 0;
-  if (governanceRequired) {
+  if (governanceRequired && board.lifecycle?.mode === "managed") {
     if (!identity.taskId) {
       return {
         decision: "block",
@@ -21270,9 +21404,11 @@ async function evaluateToolKanbanBoundary(tool, input, ctx, options = {}) {
       };
     }
     if (task.lifecycle?.currentStage !== "running" || task.assignment?.status !== "running") {
+      const lifecycleStage = task.lifecycle?.currentStage ?? "missing";
+      const assignmentStatus = task.assignment?.status ?? "missing";
       return {
         decision: "block",
-        reason: "Active card must be in Running with a live assignment before product mutation. Call kanban start_task after completing the required card details.",
+        reason: `Active card must be in Running with a live assignment before product mutation (lifecycle: ${lifecycleStage}; assignment: ${assignmentStatus}). Call kanban start_task after completing the required card details.`,
         boardId: board.id,
         taskId: task.id
       };

package/dist/execution/one-shot-llm.d.ts

@@ -44,6 +44,11 @@ export declare class OneShotOrchestrator {
     private resolveSignal;
     /**
      * Build the fallback model chain from input + config + current target.
+     * Delegates to {@link FallbackProfileManager.resolveCandidates} — the
+     * shared constructor used by both the agent loop and the one-shot path,
+     * so both produce identical ordering, depth, and fromExplicitSource
+     * semantics.
+     *
      * The injected {@link OneShotOrchestratorOptions.fallbackProfileManager}
      * is the only allowed manager — OneShot never owns a private snapshot
      * so a live `ConfigStore` change reaches every call without rebuilding

package/dist/hq/index.js

@@ -86,7 +86,7 @@ var MAX_HQ_KANBAN_BOARD_BYTES = 75e4;
 function isHqKanbanSnapshotPayload(value) {
   if (typeof value !== "object" || value === null) return false;
   const payload = value;
-  if (typeof payload.projectId !== "string" || payload.projectId.length === 0 || typeof payload.generatedAt !== "string" || !Number.isFinite(Date.parse(payload.generatedAt)) || !Array.isArray(payload.boards) || !Array.isArray(payload.tombstones) || payload.boards.length > MAX_HQ_KANBAN_BOARDS || payload.tombstones.length > MAX_HQ_KANBAN_BOARDS) {
+  if (typeof payload.projectId !== "string" || payload.projectId.length === 0 || typeof payload.generatedAt !== "string" || !Number.isFinite(Date.parse(payload.generatedAt)) || !Array.isArray(payload.boards) || !Array.isArray(payload.tombstones) || payload.boards.length > MAX_HQ_KANBAN_BOARDS || payload.tombstones.length > MAX_HQ_KANBAN_BOARDS || !isOptionalChunkOrdinal(payload.chunkIndex) || !isOptionalChunkOrdinal(payload.chunkCount)) {
     return false;
   }
   const seen = /* @__PURE__ */ new Set();
@@ -100,6 +100,9 @@ function isHqKanbanSnapshotPayload(value) {
   }
   return true;
 }
+function isOptionalChunkOrdinal(value) {
+  return value === void 0 || Number.isSafeInteger(value) && value >= 0;
+}
 function isBoardRecord(value) {
   if (typeof value !== "object" || value === null) return false;
   const record = value;
@@ -1140,12 +1143,11 @@ function redactHqValueInternal(value, options, preserveRawContentKeys) {
 function redactHqValue(value, options = {}) {
   return redactHqValueInternal(value, options, false);
 }
+function redactHqEventPayload(type, payload, options = {}) {
+  return redactHqValueInternal(payload, options, HQ_PROJECT_STATE_EVENT_TYPES.has(type));
+}
 function redactHqEvent(event, options = {}) {
-  const payload = redactHqValueInternal(
-    event.payload,
-    options,
-    HQ_PROJECT_STATE_EVENT_TYPES.has(event.type)
-  );
+  const payload = redactHqEventPayload(event.type, event.payload, options);
   const nextEvent = {
     ...event,
     payload: payload.value
@@ -1322,7 +1324,9 @@ function queuedFrameCoalesceKey(frame) {
   if (frame.type !== "client.event" || !frame.event.type.endsWith(".snapshot")) {
     return void 0;
   }
-  return [frame.event.type, frame.event.sessionId ?? "", frame.event.runId ?? ""].join("|");
+  const payload = frame.event.payload;
+  const chunk = typeof payload?.chunkIndex === "number" && Number.isFinite(payload.chunkIndex) ? String(payload.chunkIndex) : "";
+  return [frame.event.type, frame.event.sessionId ?? "", frame.event.runId ?? "", chunk].join("|");
 }
 function defaultSocketFactory(url) {
   const WebSocketCtor = globalThis.WebSocket;
@@ -1655,6 +1659,10 @@ var HqPublisher = class {
     if (bytes > this.maxQueuedBytes) {
       this.droppedFrames += 1;
       this.droppedBytes += bytes;
+      process.emitWarning(
+        `HQ telemetry frame of ${bytes} bytes exceeds the ${this.maxQueuedBytes}-byte offline queue cap and was dropped.`,
+        { code: "WRONGSTACK_HQ_FRAME_TOO_LARGE" }
+      );
       return;
     }
     if (coalesceKey !== void 0) {
@@ -5086,6 +5094,7 @@ export {
   HqSimpleLog,
   HqSnapshotStore,
   HqTimeseriesStore,
+  MAX_HQ_KANBAN_BOARD_BYTES,
   appendHqAuthAudit,
   assessHqExposure,
   buildTranscriptFromEvents,
@@ -5134,6 +5143,7 @@ export {
   readHqAuthFile,
   readHqRuntimeFileSync,
   redactHqEvent,
+  redactHqEventPayload,
   redactHqValue,
   resolveHqConfig,
   resolveHqConfigFromEnv,

package/dist/hq/protocol/kanban.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Largest single board record HQ will accept, in bytes of serialized board JSON.
+ *
+ * Exported because the sender has to know it. `isHqKanbanSnapshotPayload`
+ * rejects the *whole* snapshot when one board is over the limit, and the
+ * rejection is silent from the sender's point of view — so a publisher that
+ * does not check this first can lose every board in the chunk, permanently.
+ */
+export declare const MAX_HQ_KANBAN_BOARD_BYTES = 750000;
 export interface HqKanbanBoardRecord {
     boardId: string;
     revision: number;
@@ -16,6 +25,18 @@ export interface HqKanbanSnapshotPayload {
     generatedAt: string;
     boards: HqKanbanBoardRecord[];
     tombstones: HqKanbanTombstone[];
+    /**
+     * Position of this payload within a multi-part publish, present only when the
+     * publish was split. It exists so the offline frame queue can tell chunks of
+     * one snapshot apart from successive versions of the same snapshot — coalesce
+     * on `chunkIndex`, not on the event type alone, or every chunk but the last
+     * is evicted before the socket reconnects.
+     *
+     * Receivers do not need it: chunks are independent record sets, and each
+     * record carries its own revision.
+     */
+    chunkIndex?: number | undefined;
+    chunkCount?: number | undefined;
 }
 /** Server-to-client snapshot after HQ has merged all known project writers. */
 export interface HqServerKanbanSnapshotMessage {

package/dist/hq/protocol.js

@@ -86,7 +86,7 @@ var MAX_HQ_KANBAN_BOARD_BYTES = 75e4;
 function isHqKanbanSnapshotPayload(value) {
   if (typeof value !== "object" || value === null) return false;
   const payload = value;
-  if (typeof payload.projectId !== "string" || payload.projectId.length === 0 || typeof payload.generatedAt !== "string" || !Number.isFinite(Date.parse(payload.generatedAt)) || !Array.isArray(payload.boards) || !Array.isArray(payload.tombstones) || payload.boards.length > MAX_HQ_KANBAN_BOARDS || payload.tombstones.length > MAX_HQ_KANBAN_BOARDS) {
+  if (typeof payload.projectId !== "string" || payload.projectId.length === 0 || typeof payload.generatedAt !== "string" || !Number.isFinite(Date.parse(payload.generatedAt)) || !Array.isArray(payload.boards) || !Array.isArray(payload.tombstones) || payload.boards.length > MAX_HQ_KANBAN_BOARDS || payload.tombstones.length > MAX_HQ_KANBAN_BOARDS || !isOptionalChunkOrdinal(payload.chunkIndex) || !isOptionalChunkOrdinal(payload.chunkCount)) {
     return false;
   }
   const seen = /* @__PURE__ */ new Set();
@@ -100,6 +100,9 @@ function isHqKanbanSnapshotPayload(value) {
   }
   return true;
 }
+function isOptionalChunkOrdinal(value) {
+  return value === void 0 || Number.isSafeInteger(value) && value >= 0;
+}
 function isBoardRecord(value) {
   if (typeof value !== "object" || value === null) return false;
   const record = value;
@@ -673,6 +676,7 @@ export {
   HQ_RESUME_GAP_MAX_ENVELOPES,
   HQ_RESUME_GAP_MAX_STALE_MS,
   HQ_TRANSCRIPT_TEXT_CAP,
+  MAX_HQ_KANBAN_BOARD_BYTES,
   createHqEventEnvelope,
   isHqGovernanceSnapshotPayload,
   isHqKanbanSnapshotPayload,

package/dist/hq/redaction.d.ts

@@ -25,6 +25,20 @@ export declare function tightenHqRedactionPolicy(publisherPolicy: HqRedactionPol
  */
 export declare function scrubAndTruncateHqPreview(value: unknown, maxLength?: number): string | undefined;
 export declare function redactHqValue<T>(value: T, options?: HqRedactOptions): HqRedactionResult<T>;
+/**
+ * Redact a payload exactly as it would be redacted when published under `type`.
+ *
+ * Exported because a sender sometimes needs to know what will go on the wire
+ * before it commits to sending — the Kanban→HQ sync measures a board against
+ * HQ's per-board byte limit, and HQ drops an over-limit frame without a reply.
+ * That measurement has to run the SAME transform as the send, because the
+ * event type decides whether raw-content keys survive: `kanban.snapshot` is a
+ * project-state event and keeps them, while the generic `redactHqValue` path
+ * replaces them with a short marker. Measuring through the generic path made
+ * the estimate smaller than reality, so an oversized board could pass the check
+ * and still be rejected — the exact silent loss the check exists to prevent.
+ */
+export declare function redactHqEventPayload<TPayload>(type: string, payload: TPayload, options?: HqRedactOptions): HqRedactionResult<TPayload>;
 export declare function redactHqEvent<TPayload>(event: HqEventEnvelope<TPayload>, options?: HqRedactOptions): HqRedactionResult<HqEventEnvelope<TPayload>>;
 export declare function summarizeHqToolArgs(value: unknown, options?: HqRedactOptions): unknown;
 //# sourceMappingURL=redaction.d.ts.map

package/dist/index.d.ts

@@ -60,6 +60,7 @@ export { runProviderWithRetry } from './core/provider-runner.js';
 export { buildQueuedMessagesBlock, consumeQueuedMessagesUpdate, peekQueuedMessages, setQueuedMessagesSnapshot, } from './core/queued-messages.js';
 export { extractRunEnv, type RunEnv } from './core/run-env.js';
 export { DefaultSystemPromptBuilder, type DefaultSystemPromptBuilderOptions, LAYER_1_IDENTITY, SYSTEM_BLOCK_SOURCE, type SystemBlockSource, } from './core/system-prompt-builder.js';
+export { type DomainGlossary, type DomainGlossaryOptions, makeDomainGlossaryContributor, renderDomainGlossary, } from './core/system-prompt-glossary.js';
 export * from './defaults/index.js';
 export { AutoCompactionMiddleware, type CompactorOptions, type CompactorStrategy, createStrategyCompactor, HybridCompactor, IntelligentCompactor, type IntelligentCompactorOptions, installSubagentAutoCompaction, SelectiveCompactor, type SelectiveCompactorOptions, type StrategyCompactorOptions, } from './defaults/index.js';
 export { type AutonomyBrainOptions, type BrainAutoRisk, type BrainLlmTarget, buildBrainUserMessage, completeBrainLlm, createAutonomyBrain, createTieredBrainArbiter, formatDecisionSummary, parseOptionDecision, type TieredBrainArbiterOptions, } from './execution/autonomy-brain.js';