@wrongstack/core 0.308.6 → 0.309.0

package/dist/plugin/loader.d.ts

@@ -49,8 +49,12 @@ export interface LoadPluginsOptions {
      * method that contradicts its declared `capabilities` — instead of
      * just logging a warning. Use in CI/strict deployments to enforce
      * manifest honesty. Default: false (log-only, backward-compatible).
+     *
+     * A predicate form is also accepted so hosts can enforce selectively —
+     * e.g. strictly for external (third-party) plugins while keeping
+     * first-party plugins warn-only.
      */
-    enforceCapabilities?: boolean | undefined;
+    enforceCapabilities?: boolean | ((plugin: Plugin) => boolean) | undefined;
     /**
      * Timeout in milliseconds for each plugin's `setup()` call. If the
      * plugin's setup exceeds this deadline it is treated as a failure

package/dist/plugin/trust.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Trust-on-first-use (TOFU) pinning for external plugins.
+ *
+ * In-process plugins run with full host privileges, so the only practical
+ * supply-chain signal available before plugin code executes is "has this
+ * plugin's entry file changed since the user first ran it?". On first load
+ * the host records a SHA-256 of the resolved entry file in
+ * `~/.wrongstack/plugin-trust.json`. Later loads compare hashes:
+ *
+ *   - match            → plugin loads silently
+ *   - no pin yet       → pin is written now, plugin loads (first use)
+ *   - hash mismatch    → plugin is REFUSED until the user re-pins it with
+ *                        `wstack plugin trust <name>`
+ *
+ * The pin covers the entry file only (not the whole dependency tree) —
+ * it catches swapped/updated plugin builds, not deep transitive changes.
+ * It is a tamper signal, not a signature scheme.
+ *
+ * Disable entirely with `features.pluginsTrust: false` in config.
+ */
+export interface PluginTrustEntry {
+    /** Absolute entry file path that was hashed at pin time. */
+    entry: string;
+    /** `sha256-<hex>` of the entry file contents at pin time. */
+    integrity: string;
+    /** ISO timestamp of when the pin was written. */
+    pinnedAt: string;
+    /** Optional provenance — the config spec/path the plugin was loaded from. */
+    spec?: string | undefined;
+}
+export interface PluginTrustStore {
+    pinned: Record<string, PluginTrustEntry>;
+}
+export type PluginTrustVerification = {
+    status: 'unpinned';
+    integrity: string;
+} | {
+    status: 'trusted';
+    integrity: string;
+} | {
+    status: 'changed';
+    expected: string;
+    actual: string;
+    pinnedAt: string;
+};
+/** Default trust store location: `~/.wrongstack/plugin-trust.json`. */
+export declare function defaultPluginTrustPath(globalRoot: string): string;
+/**
+ * Canonical pin-key form: forward slashes on every platform, so a plugin
+ * pinned by discovery (forward-slash paths) and re-pinned from a config
+ * entry (backslashes on Windows) addresses the same store key.
+ */
+export declare function normalizeTrustKey(path: string): string;
+export declare function hashFileContents(entryPath: string, readFileFn?: (path: string) => Promise<Buffer>): Promise<string>;
+/**
+ * Read the trust store. A missing file is an empty store (first run).
+ * A corrupt file is a hard error — silently ignoring it would downgrade
+ * every existing pin to "unpinned" and re-trust changed code, which is
+ * exactly the attack this file exists to catch.
+ */
+export declare function readPluginTrustStore(storePath: string, readFileFn?: (path: string) => Promise<string>): Promise<PluginTrustStore>;
+/**
+ * Write the trust store atomically (temp file + rename, 0o600 — it is a
+ * security-relevant record, same treatment as the profile config).
+ */
+export declare function writePluginTrustStore(storePath: string, store: PluginTrustStore): Promise<void>;
+/**
+ * Pure verification: compare a freshly computed integrity hash against the
+ * pinned entry. Keyed by plugin name; the pinned `entry` path is advisory
+ * (an npm update can legitimately move the entry inside node_modules while
+ * the content hash is what decides trust).
+ */
+export declare function verifyPluginTrust(name: string, integrity: string, store: PluginTrustStore): PluginTrustVerification;
+/** Insert or replace the pin for `name` and persist the store. */
+export declare function pinPluginTrust(storePath: string, name: string, entry: string, integrity: string, spec?: string): Promise<PluginTrustStore>;
+/** Remove the pin for `name` (if present) and persist the store. */
+export declare function unpinPluginTrust(storePath: string, name: string): Promise<PluginTrustStore>;
+//# sourceMappingURL=trust.d.ts.map

package/dist/tools/index.js

@@ -3499,6 +3499,7 @@ function inferRuntimeCapabilities(toolNames) {
 var skillSet = (...names) => names;
 var ROLE_SKILL_SETS = {
   explore: skillSet("research-web", "node-modern", "typescript-strict"),
+  "explore-companion": skillSet("node-modern", "typescript-strict"),
   search: skillSet("bug-hunter", "typescript-strict", "research-web"),
   research: skillSet("research-web", "tech-stack", "security-scanner", "api-design"),
   analyst: skillSet("sdd", "api-design", "testing", "security-scanner"),

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

@@ -79,6 +79,17 @@ export interface PluginConfig {
     name: string;
     enabled?: boolean | undefined;
     options?: Record<string, unknown>;
+    /**
+     * Load this plugin from an explicit location instead of resolving the
+     * npm specifier through the host's own module resolution. Accepts:
+     *   - a relative path (resolved against the project root),
+     *   - an absolute path,
+     *   - a `file:` URL.
+     * The target may be an entry file (`plugin.js`) or a directory that
+     * contains `package.json` / `index.js`. External plugins loaded through
+     * `path` are subject to the TOFU trust pin (`~/.wrongstack/plugin-trust.json`).
+     */
+    path?: string | undefined;
 }
 /**
  * Human-owned policy for the LLM-facing `plugin_manager` tool.
@@ -105,6 +116,16 @@ export interface FeaturesConfig {
     mcp: boolean;
     /** Load + initialise npm plugins declared in `plugins`. */
     plugins: boolean;
+    /**
+     * Trust-on-first-use pinning for external (third-party) plugins.
+     * The first load of an external plugin records a SHA-256 of its entry
+     * file in `~/.wrongstack/plugin-trust.json`; subsequent loads refuse to
+     * run the plugin when the hash changes until the user re-pins it via
+     * `wstack plugin trust <name>`. Set to false to disable pinning
+     * (not recommended — this is the only supply-chain signal for in-process
+     * plugins). Default: true.
+     */
+    pluginsTrust?: boolean | undefined;
     /** Register `remember` / `forget` tools backed by memory store. */
     memory: boolean;
     /**

package/dist/types/config/skills-fleet-brain.d.ts

@@ -128,6 +128,13 @@ export interface FleetConfig {
     } | undefined;
     /** Brain-gated fleet supervisor (rebalance/steer/spawn-helper). */
     supervisor?: FleetSupervisorConfig | undefined;
+    /**
+     * Explore Companion — state-triggered background codebase explorer behind
+     * the leader. Watches the leader's in-progress work state and assigns
+     * read-only exploration probes to a resident `explore-companion`
+     * subagent; findings return via mailbox. Default enabled.
+     */
+    exploreCompanion?: ExploreCompanionConfig | undefined;
     /** Roster-agent self-learning: capture → optimize → per-skill addenda. */
     learning?: AgentLearningConfig | undefined;
 }
@@ -188,6 +195,17 @@ export interface FleetSupervisorConfig {
     /** Allow the supervisor to terminate subagents (highest risk). Default false. */
     allowTerminate?: boolean | undefined;
 }
+/** Config surface for the ExploreCompanion host wiring. */
+export interface ExploreCompanionConfig {
+    /** Kill switch. Default true. */
+    enabled?: boolean | undefined;
+    /** Min gap between probes on the same subject (ms). Default 120000. */
+    cooldownMs?: number | undefined;
+    /** Pending probe queue cap (drop oldest when full). Default 8. */
+    maxPending?: number | undefined;
+    /** Mailbox poll interval for explicit asks (ms). Default 5000. */
+    pollIntervalMs?: number | undefined;
+}
 /**
  * One member of the Brain's LLM pool or council. String entries elsewhere
  * (`Config.brain.models`, council voters) parse with the same `parseModelRef`

package/dist/types/index.d.ts

@@ -34,7 +34,7 @@ export { BUILTIN_PROMPT_CATEGORIES, isBuiltinCategory, PROMPT_CATEGORY_LABELS }
 export type { InstalledPromptEntry, ManifestValidation, PromptManifestData, PromptRegistryManifest, PromptRegistryRef, RegistryDiff, } from './prompt-registry.js';
 export { diffRegistry, validateRegistryManifest } from './prompt-registry.js';
 export type { CacheTtl, Capabilities, JsonSchemaSpec, Provider, ProviderContextLimit, ProviderErrorBody, ProviderErrorKind, ReasoningConfig, ReasoningEffort, ReasoningRequest, Request, RequestCacheControl, Response, ResponseFormat, SafetySetting, StopReason, StreamEvent, Usage, } from './provider.js';
-export { classifyProviderError, effectiveInputTokens, isContextOverflowShaped, isFallbackWorthy, isRetryableKind, ProviderError, StreamHangError, } from './provider.js';
+export { classifyProviderError, effectiveInputTokens, isContextOverflowShaped, isFallbackWorthy, isReasoningEffort, isRetryableKind, ProviderError, REASONING_EFFORT_LEVELS, StreamHangError, } from './provider.js';
 export type { ProviderRunner, RunProviderOptions } from './provider-runner.js';
 export type { Renderer } from './renderer.js';
 export type { SecretScrubber } from './secret-scrubber.js';

package/dist/types/index.js

@@ -914,6 +914,18 @@ function truncate(s, max) {
 var QUOTA_EXHAUSTED_RE = /(?:insufficient|exhausted|depleted|exceeded|no|not enough)[-_\s]*(?:quota|credit|balance)|(?:quota|credit|balance)(?:\s+(?:has|have))?(?:\s+been)?[-_\s]*(?:exhausted|depleted|exceeded|insufficient)|billing[_\s-]*(?:hard[_\s-]*)?limit|payment required|spending limit|plan limit|usage[-_\s]*limit[-_\s]*(?:reached|exceeded)/i;
 
 // src/types/provider.ts
+var REASONING_EFFORT_LEVELS = [
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max"
+];
+function isReasoningEffort(value) {
+  return typeof value === "string" && REASONING_EFFORT_LEVELS.includes(value);
+}
 function effectiveInputTokens(usage) {
   return usage.input + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0);
 }
@@ -1346,6 +1358,7 @@ export {
   ParseError,
   PluginError,
   ProviderError,
+  REASONING_EFFORT_LEVELS,
   SESSION_MARKER_EVENT_TYPES,
   SYSTEM_INJECTION_PREFIXES,
   SddError,
@@ -1377,6 +1390,7 @@ export {
   isImageBlock,
   isParseError,
   isPluginError,
+  isReasoningEffort,
   isRetryableKind,
   isSddError,
   isSessionError,

package/dist/types/multi-agent.d.ts

@@ -142,6 +142,21 @@ export interface SubagentConfig {
         end: string;
         mode?: 'advisory' | 'enforce' | undefined;
     } | undefined;
+    /**
+     * Model-driven completion policy. When set, this subagent is NEVER killed
+     * by the wall-clock watchdog at its deadline: instead the deadline (or an
+     * explicit `Director.requestFinish()`) triggers an in-band
+     * `subagent.finish_requested` notification that the agent loop folds into
+     * the conversation between tool batches — the model then finishes its task
+     * in its own turn within `graceMs` of legitimate working time. Only after
+     * that grace window elapses does the existing terminal stop apply, so the
+     * subagent still has a bounded maximum lifetime.
+     *
+     * `undefined` (default) keeps the legacy watchdog behavior unchanged.
+     */
+    gracefulFinish?: boolean | {
+        graceMs?: number | undefined;
+    } | undefined;
     /**
      * Runtime request overrides for THIS subagent. When present, these are merged
      * over the leader's `Config.modelRuntime` before the subagent request pipeline

package/dist/types/provider.d.ts

@@ -23,6 +23,21 @@ import type { Tool } from './tool.js';
  * cached tokens twice and skew cache-hit-ratio reporting.
  */
 export type ReasoningEffort = 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+/**
+ * The canonical runtime list of {@link ReasoningEffort} values, in
+ * menu/display order. Single source of truth for every surface that needs to
+ * iterate the levels (CLI `/settings` + `/setmodel`, the TUI picker, the
+ * WebUI dropdown) — import this instead of re-declaring a local array, which
+ * is how drift crept in before.
+ *
+ * `satisfies` pins the literal to the union: a value here core's type doesn't
+ * know is a compile error. Note the reverse is NOT caught — core adding a
+ * level does not force this array to grow, so consumers validating user input
+ * against it must decide deliberately whether to expose the new level.
+ */
+export declare const REASONING_EFFORT_LEVELS: readonly ["none", "minimal", "low", "medium", "high", "xhigh", "max"];
+/** Type guard for untrusted strings (CLI args, WS payloads, config files). */
+export declare function isReasoningEffort(value: unknown): value is ReasoningEffort;
 export type CacheTtl = '5m' | '1h';
 /**
  * Provider-agnostic response-format directive.
@@ -119,7 +134,20 @@ export interface RequestCacheControl {
 export interface ReasoningConfig {
     default: 'enabled' | 'disabled' | 'adaptive' | 'always_on';
     disableSupported: boolean;
-    effortSupported: boolean;
+    /**
+     * Tri-state effort support:
+     *   `true`      — the catalog documents this model's effort levels
+     *                 (`effortLevels` is authoritative).
+     *   `false`     — the catalog documents effort control as absent
+     *                 (toggle-only or budget_tokens-only reasoning options).
+     *   `undefined` — the model is known to reason (`reasoning: true`) but its
+     *                 effort vocabulary is not documented. The resolver forwards
+     *                 the requested effort; each wire adapter then applies its
+     *                 own transport-level gating (allowlist, mapping, or omit),
+     *                 so an undocumented model can only match-or-omit — never
+     *                 receive a field shape it did not advertise.
+     */
+    effortSupported?: boolean | undefined;
     effortLevels: ReasoningEffort[];
     preserveThinking: 'unsupported' | 'optional' | 'always_on';
 }

package/instructions/agents/chaos-monkey.md

@@ -0,0 +1,57 @@
+You are the Chaos Monkey ("Kaos Maymunu") — a mutation-testing saboteur for the
+WrongStack fleet. Your job is to prove whether a test suite actually pins down
+the code it claims to cover, by deliberately breaking that code and watching
+which mutants survive.
+
+Core belief: green tests prove nothing if they cannot detect sabotage. A mutant
+that survives means the tests are fake or insufficient — and that is the most
+valuable finding you can return.
+
+## Your task contract
+
+The director hands you a mutation plan: an exact list of mutation ids, each with
+file, line, column, kind, original token and replacement token. The plan is
+authoritative — you NEVER invent, move, or "improve" mutations. Your freedom is
+execution order and diagnosis, never the mutation set.
+
+## Check pass (per mutant)
+
+1. Apply exactly ONE mutation from the plan to its anchored (file, line, column).
+   If the anchored token no longer matches `original`, mark the mutant
+   `skipped` with the drift as evidence — do not hunt for a "similar" site.
+2. Run the provided test command exactly as given.
+3. Record the outcome:
+   - Tests fail → mutant `killed` (quote the first failing assertion).
+   - Tests pass → mutant `survived` (this is a weak-test finding, not your failure).
+4. Restore the original source byte-for-byte before moving to the next mutant.
+   The suite is only honest if every mutant ran against pristine code except
+   its own single mutation.
+
+## Hard rules
+
+- **One mutation at a time.** Never stack mutants; a stacked run measures nothing.
+- **Always restore.** Your worktree must be clean of sabotage at the end of the
+  pass. If restore fails, stop and report which file is left mutated.
+- **Stay inside the plan's files.** No refactors, no fixes, no formatting churn
+  — even when the mutated code looks wrong to you. You are the saboteur, not
+  the reviewer.
+- **Deterministic.** Same plan + same suite → same report.
+- **One-shot lifecycle.** Finish the assigned pass, submit the report, stop.
+
+## Report
+
+Submit via `submit_result`, then repeat it as your final text (fenced JSON):
+
+```json
+{
+  "summary": "<one line: N killed / M survived / K skipped>",
+  "mutants": [
+    { "id": "<plan id>", "file": "...", "line": 0, "kind": "...",
+      "status": "killed | survived | skipped",
+      "evidence": "<failing assertion, or 'suite green' for survivors>" }
+  ]
+}
+```
+
+Order survivors first — they are the actionable findings. For each survivor,
+name the boundary or behavior the tests failed to assert.

package/instructions/agents/explore-companion.md

@@ -0,0 +1,35 @@
+You are the Explore Companion — a read-only reconnaissance agent running
+behind a leader agent that is executing the main task. You do not lead
+work, you do not block the leader, and you never modify anything: you
+answer narrow probes by scanning the codebase intensively and feeding
+findings back asynchronously ("this file is here, that component works
+like this").
+
+Scope:
+- Answer probes scoped to the leader's current in-progress work
+- Locate files, entry points, symbols, and their callers/dependents
+- Explain how a component works across the files that implement it
+- Stay inside the probe scope; if the probe is ambiguous, state your
+  interpretation and answer anyway
+
+Input format you accept (a probe task):
+{ "probe": "<what to find>", "hint": { "file": "...", "symbol": "..." }, "context": "<what the leader is doing>" }
+
+Output: findings, not prose. Markdown block with:
+- ## Findings — table or bullets: `file:line` — what it is, how it works
+- Confidence: 0.0–1.0 for the overall answer
+- Next read: one `file:line` suggestion the leader should read next
+
+Working rules:
+- Read-only, always — never edit, write, or run shell commands
+- Always cite file:line; never describe code you have not read
+- Index-first discovery: `codebase-repo-map`, `codebase-search`,
+  `codebase-skeleton`, `codebase-incoming-calls`, `codebase-outgoing-calls`
+  before `read`/`grep`/`glob`/`tree`
+- Keep the mailbox message compact: findings + confidence + one next-read
+  suggestion. The leader reads it inside its own context window.
+- Report findings to the leader via the mailbox (`type=result` for a direct
+  probe answer, `type=btw` for ambient/low-urgency context, subject
+  prefixed `[explore]`), then always finish with `submit_result`
+  (`SubagentStructuredReport`): summary, findings[], files_examined[],
+  confidence, suggested_next_steps[].

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/core",
-  "version": "0.308.6",
+  "version": "0.309.0",
   "license": "MIT",
   "description": "WrongStack core: kernel, types, defaults, and shared utilities for the WrongStack CLI agent.",
   "repository": {
@@ -182,8 +182,8 @@
   "wrongstackApiVersion": "0.1.10",
   "dependencies": {
     "zod": "4.4.3",
-    "@wrongstack/kanban": "0.308.6",
-    "@wrongstack/persistence": "0.308.6"
+    "@wrongstack/kanban": "0.309.0",
+    "@wrongstack/persistence": "0.309.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",