@wrongstack/core 0.303.0 → 0.305.0

package/dist/storage/session-store/load-cache.d.ts

@@ -9,6 +9,17 @@ export declare class SessionLoadCache {
     constructor(entries?: Map<string, LoadCacheEntry>);
     private bytes;
     clear(sessionId?: string): void;
+    /**
+     * A hit hands back fresh `messages` / `events` arrays over the cached
+     * contents.
+     *
+     * The entry outlives every caller, and callers treat what they get as their
+     * own: `resume()` passes `messages` straight into a live conversation, and
+     * anything walking `events` may splice it. Returning the cached arrays
+     * themselves let one caller's edit rewrite what the next one loads. The
+     * elements are still shared — copying them would defeat the cache — so
+     * entries remain read-only *contents* behind private containers.
+     */
     getFresh(id: string, stat: FileStatSnapshot, full: boolean): SessionData | null;
     set(id: string, stat: FileStatSnapshot, data: SessionData): void;
     private delete;

package/dist/storage/session-store/prune-helpers.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Prunable === is a transcript. This module held the only complete sidecar
+ * list in the codebase while the listing scans held shorter ones; sharing the
+ * predicate is what stops them disagreeing again.
+ */
 export declare function isPrunableSessionJsonl(name: string): boolean;
 export declare function pruneSessionFiles(storeDir: string, maxAgeDays: number, deleteSession: (id: string) => Promise<void>): Promise<number>;
 //# sourceMappingURL=prune-helpers.d.ts.map

package/dist/storage/session-store.d.ts

@@ -57,6 +57,18 @@ export declare class DefaultSessionStore implements SessionStore {
     private ensureShardDir;
     create(meta: Omit<SessionMetadata, 'startedAt'>): Promise<SessionWriter>;
     fork(id: string, opts?: SessionForkOptions): Promise<ForkedSession>;
+    /**
+     * Implements {@link SessionForkHost.readRawEvents} — the parent stream a fork
+     * inherits, unmodified.
+     *
+     * Deliberately NOT `load()`: that loader empties superseded snapshot payloads
+     * in place and front-drops events past its retention budget, both of which
+     * are correct for reconstructing a conversation and wrong for copying a
+     * journal prefix into a child. Streaming with an accept-everything predicate
+     * keeps the scrubbing contract (`searchEvents` scrubs each line the same way
+     * `load()` does) without either transformation.
+     */
+    readRawEvents(id: string): Promise<SessionEvent[]>;
     /**
      * Capture the deterministic post-tool workspace identity through the store-owned CAS.
      */
@@ -167,6 +179,12 @@ export declare class DefaultSessionStore implements SessionStore {
     private listFromDirectoryScan;
     private collectShardKeys;
     private readOrBuildShardManifest;
+    /**
+     * Shard manifests are invalidated by other store processes via atomic
+     * delete/rebuild. Validate the in-memory projection against the persisted
+     * file so one long-lived process cannot retain another process's stale view.
+     */
+    private freshShardManifestCacheEntry;
     private collectSessionFilesInShard;
     private collectSessionFiles;
     /** Recursively collect session IDs from date-shard subdirectories.

package/dist/tools/index.js

@@ -614,17 +614,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`.");
@@ -644,8 +633,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) {
@@ -655,15 +645,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();
@@ -2164,12 +2150,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) {
@@ -2293,7 +2364,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 fallbackProfileChain(config, profileName) {
@@ -2869,6 +2953,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*-->/
@@ -2987,6 +3077,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));
@@ -2998,7 +3092,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) {
@@ -3128,7 +3223,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 };
@@ -3538,6 +3634,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):
@@ -3822,8 +3920,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. */
@@ -6992,7 +7098,9 @@ ${content}`);
         }
         if (typeof config.maxConcurrent === "number") {
           if (!Number.isFinite(config.maxConcurrent) || config.maxConcurrent < 0) {
-            issues.push(`maxConcurrent must be a non-negative number (got ${config.maxConcurrent})`);
+            issues.push(
+              `maxConcurrent must be a non-negative number (got ${config.maxConcurrent})`
+            );
           } else if (config.maxConcurrent === 0) {
             warnings.push("maxConcurrent is 0 \u2014 subagent concurrency effectively disabled");
           } else {
@@ -7004,12 +7112,28 @@ ${content}`);
             const v = fleetBudget[key];
             if (v === void 0) continue;
             if (typeof v !== "number" || !Number.isFinite(v) || v < 0) {
-              issues.push(`fleet.budget.${key} must be a non-negative number (got ${JSON.stringify(v)})`);
+              issues.push(
+                `fleet.budget.${key} must be a non-negative number (got ${JSON.stringify(v)})`
+              );
             } else {
               ok.push(`fleet.budget.${key} ${v}`);
             }
           }
         }
+        const lastResortCap = config.fallbackMaxLastResortCandidates;
+        if (lastResortCap !== void 0) {
+          if (typeof lastResortCap !== "number" || !Number.isFinite(lastResortCap) || lastResortCap < 0) {
+            issues.push(
+              `fallbackMaxLastResortCandidates must be a non-negative number (got ${String(lastResortCap)})`
+            );
+          } else if (Math.floor(lastResortCap) === 0) {
+            warnings.push(
+              `fallbackMaxLastResortCandidates is ${lastResortCap} \u2014 floors to 0, last-resort auto-discovery append is disabled`
+            );
+          } else {
+            ok.push(`fallbackMaxLastResortCandidates ${Math.floor(lastResortCap)}`);
+          }
+        }
         for (const [key, entry] of Object.entries(matrix)) {
           const eProvider = entry.provider ?? config.provider;
           const eModel = entry.model;
@@ -8281,19 +8405,23 @@ function badge(state) {
 var GOVERNED_TOOL_EXECUTOR_META_KEY = "toolExecutor.executeGoverned";
 
 // src/utils/tool-name.ts
+import { createHash as createHash2 } from "node:crypto";
 var WIRE_TOOL_NAME_MAX_LENGTH = 128;
-function sanitizeWireToolName(name) {
-  const replaced = name.replace(/[^a-zA-Z0-9_-]/g, "_");
-  const clamped = replaced.slice(0, WIRE_TOOL_NAME_MAX_LENGTH);
-  return clamped.length > 0 ? clamped : "tool";
+var MCP_SERVER_SEGMENT_MAX_LENGTH = 48;
+var MCP_IDENTITY_HASH_LENGTH = 10;
+function collisionSafeMcpSegment(value, maxLength) {
+  const replaced = value.replace(/[^a-zA-Z0-9_-]/g, "_") || "tool";
+  if (replaced === value && replaced.length <= maxLength) return replaced;
+  const suffix = `_${createHash2("sha256").update(value, "utf8").digest("hex").slice(0, MCP_IDENTITY_HASH_LENGTH)}`;
+  return `${replaced.slice(0, Math.max(1, maxLength - suffix.length))}${suffix}`;
 }
 function mcpServerToolPrefix(serverName) {
-  return `mcp__${sanitizeWireToolName(serverName)}__`;
+  return `mcp__${collisionSafeMcpSegment(serverName, MCP_SERVER_SEGMENT_MAX_LENGTH)}__`;
 }
 function mcpQualifiedToolName(serverName, toolName) {
-  return sanitizeWireToolName(
-    `${mcpServerToolPrefix(serverName)}${sanitizeWireToolName(toolName)}`
-  );
+  const prefix = mcpServerToolPrefix(serverName);
+  const toolSegment = collisionSafeMcpSegment(toolName, WIRE_TOOL_NAME_MAX_LENGTH - prefix.length);
+  return `${prefix}${toolSegment}`;
 }
 
 // src/tools/mcp-use.ts
@@ -8565,52 +8693,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) {

package/dist/types/config/mcp-features.d.ts

@@ -281,10 +281,40 @@ export interface SageConfig {
          * many days. Undefined/0 disables purge (default).
          */
         purgeDeletedAfterDays?: number | undefined;
+        /**
+         * How deep periodic hygiene verifies anchors.
+         * - `existence` (default): file/path still exists (`fs.access` only).
+         * - `content`: also content-hash / symbol / command resolution.
+         * - `git`: content checks plus git blob hash comparison when available.
+         */
+        verifyDepth?: 'existence' | 'content' | 'git' | undefined;
     } | undefined;
     embeddings?: {
-        /** Optional future semantic layer. Disabled by default and never required. */
+        /**
+         * When true, retrieval re-ranks lexical candidates with the offline
+         * hashing embedding provider (hybrid). Default: false. Fail-open:
+         * lexical results are always available if embeddings fail.
+         */
         enabled?: boolean | undefined;
     } | undefined;
+    /**
+     * Opt-in automatic capture of durable tool outcomes into SAGE.
+     * Off by default — operators enable per-project when they want
+     * command success notes recorded without an explicit `remember` call.
+     */
+    capture?: {
+        /** Persist successful command/tool outcomes as `tool_outcome` memories. Default: false. */
+        toolOutcomes?: boolean | undefined;
+        /** Persist recurring error signatures as `error_pattern` memories. Default: false. */
+        errorPatterns?: boolean | undefined;
+    } | undefined;
+    /**
+     * Optional automated triage scheduling. When true, `setupSage` schedules a
+     * daily job (1h after boot, then every 24h): hygiene + bounded triage that
+     * files review proposals (never auto-deletes). Default: false.
+     */
+    triage?: {
+        dailyDryRun?: boolean | undefined;
+    } | undefined;
 }
 //# sourceMappingURL=mcp-features.d.ts.map

package/dist/types/config/root.d.ts

@@ -144,6 +144,18 @@ export interface Config {
         primaryProbeInterval?: number | undefined;
         stickyFallbackTurns?: number | undefined;
     } | undefined;
+    /**
+     * Maximum number of candidates appended by the last-resort fallback sweep
+     * (`resolveAllConfigured`). When the smart default, bridge, and named/default
+     * profiles have all failed, every other configured provider is appended —
+     * this cap bounds the chain so a config with many providers does not produce
+     * a degenerate sequence of doomed requests during a systemic outage.
+     *
+     * Set to a higher value for rich multi-provider configs that want maximum
+     * diversity; set to 0 to disable the last-resort append entirely. The
+     * compiled-in default is exposed as `MAX_LAST_RESORT_CANDIDATES` (12).
+     */
+    fallbackMaxLastResortCandidates?: number | undefined;
     /**
      * Lifecycle command/HTTP hooks, keyed by event. Commands receive HookInput
      * JSON on stdin; HTTP hooks receive the same object as a POST body. A typed

package/dist/types/config/tools.d.ts

@@ -39,6 +39,28 @@ export interface ToolsConfig {
      * `/settings` ("Filesystem access").
      */
     restrictToProjectRoot?: boolean | undefined;
+    /**
+     * Require a ready, running **managed** Kanban card before any product
+     * mutation. Default: **false** — Kanban records work, it does not permit it,
+     * and that is the shipped contract the system prompt and the `kanban` tool
+     * description both state.
+     *
+     * Turning this on inverts that for this installation: a mutating tool
+     * (`write`, `edit`, `exec`, …) is refused until the run is bound to a card
+     * that is on a managed board, passes `evaluateContractGraphReadiness`, and
+     * sits in Running with a live assignment. Control tools (`kanban`, `todo`,
+     * `plan`, `task`) are always exempt so the agent can always record evidence
+     * or start the next card.
+     *
+     * Non-managed boards — session mirrors, SDD mirrors, plain imports — are
+     * skipped rather than blocked: they structurally cannot carry a lifecycle,
+     * so demanding one would deadlock every mutation with no reachable remedy.
+     * They still fall through to their path-scoped `boundary` policy.
+     *
+     * Independent of the two checks that are ALWAYS on regardless of this flag:
+     * the dispatch lease fence and the board/task filesystem `boundary`.
+     */
+    kanbanGovernance?: boolean | undefined;
     /**
      * Per-command policy for the `exec` tool's allowlist. The tool ships a
      * curated default allowlist of dev/build commands; this extends or trims it.

package/dist/types/default-config.d.ts

@@ -14,6 +14,7 @@ export declare const DEFAULT_TOOLS_CONFIG: Readonly<{
     disabledTools: readonly string[];
     autoExtendLimit: true;
     restrictToProjectRoot: true;
+    kanbanGovernance: false;
     loopDetection: Readonly<{
         mode: 'steer-then-cut' | 'cut' | 'off';
         steerThreshold: number;

package/dist/types/index.js

@@ -734,6 +734,9 @@ var DEFAULT_TOOLS_CONFIG = Object.freeze({
   disabledTools: Object.freeze([]),
   autoExtendLimit: true,
   restrictToProjectRoot: true,
+  // Off by default: the board is a record of the work, not a permit for it.
+  // See ToolsConfig.kanbanGovernance for what turning it on costs and gates.
+  kanbanGovernance: false,
   loopDetection: Object.freeze({
     mode: "steer-then-cut",
     steerThreshold: 3,

package/dist/types/session.d.ts

@@ -8,7 +8,15 @@ export interface SessionMetadata {
     provider?: string | undefined;
     startedAt: string;
     endedAt?: string | undefined;
-    /** Set when a session is closed with open tool calls — used to restore pending state on resume. */
+    /**
+     * Tool calls the previous run had issued but not resolved when it closed,
+     * as recorded on `session_end`.
+     *
+     * Diagnostic only. Resume does NOT restore pending state from this: it
+     * derives the same fact from the replayed conversation
+     * ({@link SessionData.pendingToolUseCount}), which also covers the crash
+     * case where no `session_end` was ever written. Nothing re-executes these.
+     */
     pendingToolUses?: string[] | undefined;
     /** Parent journal metadata when this session was created by fork(). */
     forkedFrom?: {

package/dist/utils/index.d.ts

@@ -31,6 +31,7 @@ export { isSafePathSegment, MAX_PATH_SEGMENT_LENGTH, resolveContainedPath, } fro
 export { getPerfProfile, indexParallelBatchSize, isFrugalPerf, type PerfProfile, SageCachePragmas, sqliteCachePragmas, tuiStreamFlushMs, useDaemonPerfDefaults, } from './perf-profile.js';
 export { isPidAlive } from './pid.js';
 export * from './project-identity.js';
+export { activateProjectStateGuard, type ProjectStateGuard, type ProjectStateGuardOptions, startProjectStateGuard, } from './project-state-guard.js';
 export { type ProjectWatchEvent, type ProjectWatchSubscription, watchProjectTree, } from './project-watch.js';
 export { capSubject, type CompileFail, type CompileResult, compileUserRegex, MAX_SUBJECT_LEN, } from './regex-guard.js';
 export * from './safe-json.js';