@wrongstack/core 0.308.6 → 0.308.7

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/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.308.7",
   "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/persistence": "0.308.7",
+    "@wrongstack/kanban": "0.308.7"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",