pi-warden 0.36.0 → 0.40.1

package/CHANGELOG.md

@@ -8,6 +8,84 @@ How to keep this current: add the entry in the same pull request as the change,
 
 <!-- Empty. Next release starts here. -->
 
+## 0.40.1
+
+### Fixed
+
+- An `rm` in a compound command (`rm -rf build && npm test`) no longer makes every word after it a separate target. Target extraction now runs per shell segment, so a compound command stops producing one Jev question per trailing token and no longer trips TypeSafe's 32-question limit on long command lines. A single `rm` naming more targets than the request budget still can; chunking is separate.
+- An `rm` followed by a newline and another command produced no targets at all, so it was never scoped; it now yields the targets of its own line.
+
+## 0.40.0
+
+### Fixed
+
+- `/warden status` and `/warden enable` now describe the key of the configured `typesafeBackend`. With `"openrouter"`, status said "TypeSafe key: missing" on the same line that counted judgments, and enable opened the TypeSafe login prompt, so consent could not be saved. Both call pi-typesafe's backend-aware `authState` and `ensureApiKey`; with no OpenRouter key, enable reports the variable to set instead of prompting (#57).
+- The headless hint and the enable confirmation name the backend's own environment variable.
+
+### Changed
+
+- `src/backend.ts` reads hosts and key variables from pi-typesafe's `DECISIONS_BACKENDS` instead of keeping its own copy; `keyAvailable` is replaced by `authState({ backend }).usable`, which also honours a rejected key. Requires pi-typesafe 0.7.0.
+
+## 0.39.1
+
+### Changed
+- Bump `pi-typesafe` from `^0.6.1` to `^0.6.2`. Programmatic API is unchanged; the 0.6.2 tool schema now documents its own payload fields, and no pi-warden text duplicated it.
+
+## 0.39.0
+
+### Docs
+- README quick start now carries the four setup commands (`/warden enable`, `/warden init`, `/warden index`, `/warden test`) and the beta note; `docs/commands.md` gains rows for `/warden init --force` and `/warden index`.
+- Conscience policy measurement on the per-project corpus with the split disposition gate: beta candidate policy record (89% pooled precision, 74/83; 95% gate not met), comparison against the first measurement and the remeasure, labelled-subset reproduction of the live-run gate numbers.
+- Conscience recommendation remeasurement after index + question changes: before-and-after table, labelled-subset comparison, research-role tool rate, candidate policy update.
+
+### Added
+- `/warden index` command: builds a local capability index with the session model. Entries carry `lead`, `useWhen`, `examples`, and `role` instead of bare names and descriptions. The conscience uses index entries when the source hash matches; bare descriptions are the fallback. Index files live at `~/.pi/agent/pi-warden/index/global.json` and `projects/<hash>.json`. Once-per-session nudge when the index is missing or stale.
+- `conscience.advanceThreshold` config key (default `0.70`): separate gate for the disposition question's P(advance), independent of the usefulness threshold.
+- `CONSCIENCE_BETA_POLICY` in `src/load.ts` (questionHash `fb2d35042f667b3c`, model `jev-1.13.0`, usefulness 0.80, advance 0.70), held in the extension's closure and passed to the activation gate; a test pins the question wording to the policy hash, and `questionHash` is computed over the disposition question plus one canonical candidate question so it no longer moves with batch shape.
+- Capability roles (`research`, `evidence`, `execution`, `delegation`, `review`, `conversation`) in index entries and candidate state; role-based guidance in Score questions.
+
+### Changed
+- Conscience defaults: `recommendThreshold` 1.0 → 0.80 (beta policy thresholds); still off by default — `conscience.enabled: true` is the one switch.
+- The replay script omits prompt excerpts from the selected-candidates table unless `PI_WARDEN_OWNER_REPORTS=1`, so committed reports carry no Linear ids or branch names; scrub greps include `CON-[0-9]+`.
+- Replay script `scripts/conscience-replay.mjs` gates delivery on `advanceThreshold` (default 0.70) and reports pi-warden status rows below the gate.
+- Conscience question wording reverted to baseline after four calibration iterations; the disposition gate, not wording, was the lever.
+
+### Fixed
+- The conscience activation gate now fails closed: with no active policy, or a policy whose hash or model does not match the request, no recommendation is delivered (traced `no_policy`). Previously an absent policy let delivery through, contradicting `docs/configuration.md`. The gate also compares the policy's model against the model that actually answered instead of the literal `"jev-latest"`.
+
+## 0.38.3
+
+### Fixed
+- `/warden config` keeps its panel handle and toggles shut, instead of stacking a second overlay against its own header hint.
+- A bare `/warden` runs `status` again, and `config set <key> <value>` / `get <key>` reach the setting — the argument split dropped the default action and kept only the word after the subcommand.
+
+## 0.38.2
+
+### Docs
+- Conscience recommendation calibration on recorded sessions: first measurement scripts, report, and guard calibration tables.
+
+## 0.38.1
+
+### Changed
+- Verified against Pi 0.87.0; dev dependency updated.
+
+## 0.38.0
+
+### Added
+- Conscience coach: disabled by default pending calibration. Recommends or loads skills and tools before the agent acts via `before_agent_start`. Trace-only until a measured policy ships. Load mode reads skill files from disk with path-rule checks, size bounds, frontmatter validation, and credential canary detection. 48 adversarial tests plus the fixture set.
+
+### Docs
+- Conscience recommendation calibration (2026-09-22): first measurement on 609 turns across 4 projects. Tool recommendation 84% precision, skill recommendation unmeasured pending human labels. No threshold meets the 95% gate; closest is 0.95 at 91%. Candidate policy recorded (not active); `docs/guards.md` updated. `eval/reports/2026-09-22-conscience-recommend/`.
+## 0.37.1
+
+### Docs
+- CONTRIBUTING.md: reflecting the evidence floor for destructive patterns; version bump is optional for outside PRs. docs/guards.md: same stale wording fixed.
+
+## 0.37.0
+
+### Added
+- Compaction evidence appendix (`context.compactAppendix`, default true): after compaction succeeds, the extension sends a deterministic summary of session evidence — saved outputs, last checks, held actions, stuck state, and the active task — as one custom message so the agent can prefer saved paths over re-running commands. All strings are redacted. Does not spend a steer unit.
+
 ## 0.36.0
 
 ### Changed

package/README.md

@@ -14,9 +14,12 @@ Instead of interrupting you for every problem, Warden usually feeds the issue ba
 pi install npm:pi-warden
 ```
 
-1. `/warden enable` to activate. Paste a key from [console.typesafe.ai](https://console.typesafe.ai) if you have one (hidden input, saved owner-only), or skip for offline-only mode.
-2. `/warden test` to see one synthetic verdict.
-3. Work as usual. Status line shows verdicts; `ctrl+shift+w` opens the trace sidebar.
+1. `/warden enable` to turn judgments on. Paste a key from [console.typesafe.ai](https://console.typesafe.ai) (hidden input, saved owner-only), or skip for offline-only mode.
+2. `/warden init` to write a starter `pi-warden.md`. The rules guard enforces what you put there.
+3. `/warden index` (recommended) so the conscience knows your skills and tools from their real descriptions.
+4. `/warden test` to see one synthetic verdict, then work as usual. The status line shows verdicts; `ctrl+shift+w` opens the trace sidebar.
+
+The conscience is beta and off by default. Turn it on with `conscience.enabled: true` in the user config.
 
 Works without any key (offline guards: pattern list, runaway stop, sensitive-path notes, credential warnings). Requires Pi 0.85+, Node 22.19+.
 
@@ -32,6 +35,7 @@ Works without any key (offline guards: pattern list, runaway stop, sensitive-pat
 | **Security** | code and output | Hardcoded secrets, injection risks |
 | **Runaway** | reply stream | Stops replies that begin repeating themselves |
 | **Subagent triage** | async child reports | Keeps noisy background work from waking the parent |
+| **Conscience** (beta, off) | each operator prompt | Recommends a skill or tool from the capability index before the agent acts; enable with `conscience.enabled: true` |
 
 ## How intervention works
 

package/dist/backend.d.ts

@@ -1,18 +1,15 @@
 import type { TypeSafeOptions } from "pi-typesafe";
 /** The judgment backend that receives pi-warden's Jev requests. */
 export type JudgmentBackend = "typesafe" | "openrouter";
-/** The host the consent disclosure names as the destination. */
+/** The host the consent disclosure names as the destination, without scheme: `api.typesafe.ai`, `openrouter.ai`. */
 export declare function backendHost(backend: JudgmentBackend): string;
+/** The environment variable that carries the backend's key, for messages that tell the user what to set. */
+export declare function keyEnvFor(backend: JudgmentBackend): string;
 /** Adapt the consent text to the active backend by substituting the destination host. */
 export declare function disclosureFor(backend: JudgmentBackend, disclosure: string): string;
-/**
- * Whether the right credential exists for the chosen backend.
- * TypeSafe uses the pi-typesafe keystore; other backends use an environment variable.
- */
-export declare function keyAvailable(backend: JudgmentBackend, env: Record<string, string | undefined>, keystoreUsable: () => boolean): boolean;
 /**
  * Build the options forwarded to `createTypeSafe`.
- * The caller must gate on `keyAvailable` before calling `createTypeSafe`.
+ * The caller must gate on `authState({ backend }).usable` before calling `createTypeSafe`.
  */
 export declare function judgeOptions(config: {
     maxRequests: number;

package/dist/backend.js

@@ -1,36 +1,28 @@
-import { authState } from "pi-typesafe";
-const BACKENDS = {
-    typesafe: { host: "api.typesafe.ai" },
-    openrouter: { host: "openrouter.ai", keyEnv: "OPENROUTER_API_KEY" },
-};
-/** The host the consent disclosure names as the destination. */
+import { DECISIONS_BACKENDS, DEFAULT_BACKEND } from "pi-typesafe";
+/** The host the consent disclosure names as the destination, without scheme: `api.typesafe.ai`, `openrouter.ai`. */
 export function backendHost(backend) {
-    return BACKENDS[backend].host;
+    return new URL(DECISIONS_BACKENDS[backend].host).host;
+}
+/** The environment variable that carries the backend's key, for messages that tell the user what to set. */
+export function keyEnvFor(backend) {
+    return DECISIONS_BACKENDS[backend].keyEnv ?? DECISIONS_BACKENDS[DEFAULT_BACKEND].keyEnv ?? "TYPESAFE_API_KEY";
 }
 /** Adapt the consent text to the active backend by substituting the destination host. */
 export function disclosureFor(backend, disclosure) {
-    return backend === "typesafe" ? disclosure : disclosure.replace(BACKENDS.typesafe.host, BACKENDS[backend].host);
-}
-/**
- * Whether the right credential exists for the chosen backend.
- * TypeSafe uses the pi-typesafe keystore; other backends use an environment variable.
- */
-export function keyAvailable(backend, env, keystoreUsable) {
-    const keyEnv = BACKENDS[backend].keyEnv;
-    return keyEnv ? (env[keyEnv]?.trim() ?? "") !== "" : keystoreUsable();
+    return backend === DEFAULT_BACKEND ? disclosure : disclosure.replace(backendHost(DEFAULT_BACKEND), backendHost(backend));
 }
 /**
  * Build the options forwarded to `createTypeSafe`.
- * The caller must gate on `keyAvailable` before calling `createTypeSafe`.
+ * The caller must gate on `authState({ backend }).usable` before calling `createTypeSafe`.
  */
 export function judgeOptions(config) {
     return {
         maxRequests: config.maxRequests,
         timeoutMs: config.timeoutMs,
-        ...(config.typesafeBackend === "typesafe" ? {} : { backend: config.typesafeBackend }),
+        ...(config.typesafeBackend === DEFAULT_BACKEND ? {} : { backend: config.typesafeBackend }),
     };
 }
 /** Resolve the effective backend from a raw config value; invalid values fall back to "typesafe". */
 export function resolveBackend(raw) {
-    return raw === "typesafe" || raw === "openrouter" ? raw : "typesafe";
+    return raw === "typesafe" || raw === "openrouter" ? raw : DEFAULT_BACKEND;
 }

package/dist/compact.d.ts

@@ -0,0 +1,63 @@
+export interface SavedOutput {
+    tool: string;
+    path: string;
+    /** Uncompressed size in bytes. */
+    bytes: number;
+}
+export interface CheckEntry {
+    command: string;
+    passed: boolean;
+    /** Short label: "current run", "run 2", or "current run, #3". */
+    when: string;
+}
+export interface HeldEntry {
+    tool: string;
+    /** Redacted preview of the call (command, path, or input); ≤120 chars. */
+    preview: string;
+    outcome: string;
+}
+export interface StuckState {
+    failures: number;
+    sameStrategyScore: number | undefined;
+    currentCallFamily: string | undefined;
+}
+export interface CompactSnapshot {
+    savedOutputs: readonly SavedOutput[];
+    /** Capped at 5 in the hook before this is called. */
+    checks: readonly CheckEntry[];
+    /** Capped at 10 in the hook before this is called. */
+    holds: readonly HeldEntry[];
+    stuck: StuckState | undefined;
+    activeTask: string | undefined;
+}
+/** Returns empty string for an empty snapshot. Capped at 2 000 chars. */
+export declare function compactAppendix(snapshot: CompactSnapshot): string;
+/**
+ * Build a `CompactSnapshot` from the extension's session-scoped state. All string values are redacted; saved-output
+ * paths are local and allowed.
+ */
+export declare function buildCompactSnapshot(options: {
+    savedOutputs: Array<{
+        tool: string;
+        path: string;
+        bytes: number;
+    }>;
+    checks: Array<{
+        command: string;
+        passed: boolean;
+        runIndex: number;
+        indexInRun: number;
+    }>;
+    holds: Array<{
+        tool: string;
+        preview: string;
+        outcome: string;
+    }>;
+    stuck: {
+        failures: number;
+        sameStrategyScore: number | undefined;
+        currentCallFamily: string | undefined;
+    } | undefined;
+    activeTask: string | undefined;
+    runs: number;
+}): CompactSnapshot;

package/dist/compact.js

@@ -0,0 +1,84 @@
+/**
+ * Compaction evidence appendix. Deterministic, pure, no Jev request.
+ *
+ * After Pi fires `session_compact`, the extension builds a snapshot from session memory and passes it to
+ * `compactAppendix`. The returned text is sent as one custom message so the agent can prefer saved paths
+ * over re-running commands.
+ */
+import { redact } from "./redact.js";
+const MAX_CHARS = 2000;
+/** Returns empty string for an empty snapshot. Capped at 2 000 chars. */
+export function compactAppendix(snapshot) {
+    const sections = [];
+    if (snapshot.savedOutputs.length) {
+        const items = snapshot.savedOutputs
+            .map(item => `- ${redact(item.tool)} → ${redact(item.path)} (${item.bytes} bytes)`)
+            .join("\n");
+        sections.push(`### Saved full outputs\n${items}`);
+    }
+    if (snapshot.checks.length) {
+        const items = snapshot.checks
+            .map(c => `- ${c.passed ? "✓" : "✗"} ${c.when}: ${redact(c.command)}`)
+            .join("\n");
+        sections.push(`### Last checks\n${items}`);
+    }
+    if (snapshot.holds.length) {
+        const items = snapshot.holds
+            .map(h => `- ${redact(h.tool)}: ${redact(h.outcome)}${h.preview ? ` (${redact(h.preview)})` : ""}`)
+            .join("\n");
+        sections.push(`### Held actions\n${items}`);
+    }
+    if (snapshot.stuck) {
+        const s = snapshot.stuck;
+        const family = s.currentCallFamily ? `; family: ${redact(s.currentCallFamily)}` : "";
+        const score = s.sameStrategyScore !== undefined ? `; same-strategy: ${s.sameStrategyScore.toFixed(2)}` : "";
+        sections.push(`### Stuck state\n- failures: ${s.failures}${score}${family}`);
+    }
+    if (snapshot.activeTask) {
+        sections.push(`### Active task\n${redact(snapshot.activeTask)}`);
+    }
+    if (sections.length === 0)
+        return "";
+    const body = sections.join("\n\n");
+    const appendix = [
+        "=== PI-WARDEN COMPACT EVIDENCE ===",
+        "Evidence warden kept across compaction. Prefer the saved-output paths below over re-running commands that produced them.",
+        "",
+        body,
+        "=== END PI-WARDEN COMPACT EVIDENCE ===",
+    ].join("\n");
+    const marker = "\n… [truncated]";
+    if (appendix.length <= MAX_CHARS)
+        return appendix;
+    return appendix.slice(0, MAX_CHARS - marker.length) + marker;
+}
+/**
+ * Build a `CompactSnapshot` from the extension's session-scoped state. All string values are redacted; saved-output
+ * paths are local and allowed.
+ */
+export function buildCompactSnapshot(options) {
+    const savedOutputs = options.savedOutputs.map(o => ({
+        tool: o.tool,
+        path: o.path,
+        bytes: o.bytes,
+    }));
+    const maxChecks = 5;
+    const checks = options.checks.slice(-maxChecks).map(c => ({
+        command: c.command,
+        passed: c.passed,
+        when: options.runs <= 1 ? "current run" : `run ${c.runIndex}${c.indexInRun > 0 ? `, #${c.indexInRun + 1}` : ""}`,
+    }));
+    const maxHolds = 10;
+    const holds = options.holds.slice(-maxHolds).map(h => ({
+        tool: h.tool,
+        preview: h.preview,
+        outcome: h.outcome,
+    }));
+    const stuck = options.stuck ? {
+        failures: options.stuck.failures,
+        sameStrategyScore: options.stuck.sameStrategyScore,
+        currentCallFamily: options.stuck.currentCallFamily,
+    } : undefined;
+    const activeTask = options.activeTask ? redact(options.activeTask) : undefined;
+    return { savedOutputs, checks, holds, stuck, activeTask };
+}

package/dist/config.d.ts

@@ -191,6 +191,8 @@ export interface ContextConfig {
     recallTool: RecallTool;
     /** Minimum P(format) before a format-specific parser builds the excerpt instead of the generic head/tail one. */
     formatConfidence: number;
+    /** Append a compact evidence appendix to the summary during compaction. */
+    compactAppendix: boolean;
 }
 export interface RunawayConfig {
     enabled: boolean;
@@ -239,6 +241,43 @@ export interface LearningConfig {
     /** Days to keep hold records in SQLite before pruning. 0 disables pruning. */
     retentionDays: number;
 }
+export type ConscienceSkillMode = "off" | "recommend" | "load";
+export interface ConscienceSkillConfig {
+    /** off: no automatic skill selection; recommend: name a skill and ask the agent to load it; load: supply instructions directly. */
+    mode: ConscienceSkillMode;
+    /** Case-sensitive skill names to exclude; * is the only wildcard. */
+    exclude: string[];
+}
+export interface ConscienceToolConfig {
+    /** Suggest tools including evidence/research tools; never execute or enable them directly. */
+    enabled: boolean;
+    /** Case-sensitive tool names to exclude; * is the only wildcard. */
+    exclude: string[];
+}
+export interface ConscienceConfig {
+    /** Master switch for the conscience module. */
+    enabled: boolean;
+    /** Skill selection settings. */
+    skills: ConscienceSkillConfig;
+    /** Tool suggestion settings. */
+    tools: ConscienceToolConfig;
+    /** Total wall-clock deadline for one assessment (ms). Effective deadline is min(this, shared timeoutMs). */
+    timeoutMs: number;
+    /** Max assessments per admitted operator prompt, including the initial. */
+    maxAssessments: number;
+    /** Max new guidance deliveries per admitted operator prompt. */
+    maxNudges: number;
+    /** Max UTF-8 bytes per skill file for automatic loading. */
+    maxSkillBytes: number;
+    /** Max cumulative automatic loading bytes per admitted prompt. */
+    maxLoadedBytes: number;
+    /** P(useful now) must reach this to select a candidate for recommendation. Default 1.0 (trace-only until calibrated per spec §7). */
+    recommendThreshold: number;
+    /** P(advance) from the disposition question must reach this before a candidate is considered. Default 0.70. */
+    advanceThreshold: number;
+    /** P(useful now) must reach this to auto-load. Must be >= recommendThreshold. Default 1.0 (trace-only until calibrated). */
+    loadThreshold: number;
+}
 export interface WardenConfig {
     /** Master switch. false disables every guard, including offline pattern checks. */
     enabled: boolean;
@@ -279,10 +318,12 @@ export interface WardenConfig {
     steerBudget: number;
     /** Learning and adaptation settings. */
     learning: LearningConfig;
+    /** Broad-consideration coach: recommends or loads skills and tools before the agent acts. */
+    conscience: ConscienceConfig;
 }
 export declare const PACKAGE_NAME = "pi-warden";
 /** Bumped when WardenConfig gains a section; extension.ts checks it so a half-updated module graph is reported, not crashed on. */
-export declare const CONFIG_SCHEMA = 6;
+export declare const CONFIG_SCHEMA = 7;
 export declare const PROJECT_CONFIG_FILE = "pi-warden.json";
 export declare function defaultConfig(): WardenConfig;
 /** Mirrors Pi's agent directory rule so the file sits next to pi-typesafe's auth.json. */

package/dist/config.js

@@ -10,7 +10,7 @@ export function isRecallTool(value) {
 }
 export const PACKAGE_NAME = "pi-warden";
 /** Bumped when WardenConfig gains a section; extension.ts checks it so a half-updated module graph is reported, not crashed on. */
-export const CONFIG_SCHEMA = 6;
+export const CONFIG_SCHEMA = 7;
 export const PROJECT_CONFIG_FILE = `${PACKAGE_NAME}.json`;
 export function defaultConfig() {
     return {
@@ -44,7 +44,7 @@ export function defaultConfig() {
         slop: { enabled: true, threshold: 0.7, prose: { enabled: true, audience: "technical", threshold: 0.7, trend: 2, minChars: 200 } },
         security: { enabled: true, threshold: 0.7 },
         rules: { enabled: true, threshold: 0.7, files: [], fallback: true, maxChars: 8000, exclude: [], skip: [], sensitivePaths: {} },
-        context: { enabled: true, tailMinChars: 12000, confidence: 0.8, duplicateMinChars: 2000, recallTool: "auto", formatConfidence: 0.7 },
+        context: { enabled: true, tailMinChars: 12000, confidence: 0.8, duplicateMinChars: 2000, recallTool: "auto", formatConfidence: 0.7, compactAppendix: true },
         runaway: { enabled: true, repeats: 4, thinkingRepeats: 10, minChars: 400, recover: true },
         notify: { enabled: false, cooldownMs: 10000, command: [] },
         subagent: { enabled: true, wake: true, threshold: 0.8, cooldownMs: 120000 },
@@ -53,6 +53,20 @@ export function defaultConfig() {
         notices: false,
         steerBudget: 3,
         learning: { adaptiveThresholds: true, patternAnalysis: true, minHoldsForAdaptive: 20, adaptationRate: 0.1, retentionDays: 365 },
+        conscience: {
+            enabled: false,
+            skills: { mode: "recommend", exclude: [] },
+            tools: { enabled: true, exclude: [] },
+            timeoutMs: 3000,
+            maxAssessments: 3,
+            maxNudges: 2,
+            maxSkillBytes: 32768,
+            maxLoadedBytes: 65536,
+            // Beta policy thresholds (measured 2026-09-22); disabled by default, conscience.enabled is the switch.
+            recommendThreshold: 0.80,
+            advanceThreshold: 0.70,
+            loadThreshold: 1.0,
+        },
     };
 }
 /** Mirrors Pi's agent directory rule so the file sits next to pi-typesafe's auth.json. */
@@ -408,6 +422,7 @@ function applyGuards(base, raw, timeoutMs, source) {
             duplicateMinChars: positiveInteger(raw.context.duplicateMinChars, base.context.duplicateMinChars),
             recallTool: isRecallTool(raw.context.recallTool) ? raw.context.recallTool : base.context.recallTool,
             formatConfidence: probability(raw.context.formatConfidence, base.context.formatConfidence),
+            compactAppendix: boolean(raw.context.compactAppendix, base.context.compactAppendix),
         } : base.context,
     };
 }
@@ -428,6 +443,7 @@ export function applyUserOverrides(base, raw) {
         notices: boolean(raw.notices, base.notices),
         steerBudget: typeof raw.steerBudget === "number" && Number.isInteger(raw.steerBudget) && raw.steerBudget >= 0 ? raw.steerBudget : base.steerBudget,
         learning: applyLearning(base.learning, raw.learning),
+        conscience: applyConscience(base.conscience, raw.conscience),
     };
 }
 function applyLearning(base, raw) {
@@ -441,6 +457,32 @@ function applyLearning(base, raw) {
         retentionDays: Math.max(0, positiveInteger(raw.retentionDays, base.retentionDays)),
     };
 }
+function applyConscience(base, raw) {
+    if (!isObject(raw))
+        return base;
+    const skillsRaw = isObject(raw.skills) ? raw.skills : undefined;
+    const toolsRaw = isObject(raw.tools) ? raw.tools : undefined;
+    const mode = typeof skillsRaw?.mode === "string" && ["off", "recommend", "load"].includes(skillsRaw.mode) ? skillsRaw.mode : base.skills.mode;
+    return {
+        enabled: boolean(raw.enabled, base.enabled),
+        skills: {
+            mode,
+            exclude: Array.isArray(skillsRaw?.exclude) ? skillsRaw.exclude.filter((x) => typeof x === "string") : base.skills.exclude,
+        },
+        tools: {
+            enabled: boolean(toolsRaw?.enabled, base.tools.enabled),
+            exclude: Array.isArray(toolsRaw?.exclude) ? toolsRaw.exclude.filter((x) => typeof x === "string") : base.tools.exclude,
+        },
+        timeoutMs: Math.max(100, Math.min(10000, typeof raw.timeoutMs === "number" ? raw.timeoutMs : base.timeoutMs)),
+        maxAssessments: Math.max(1, Math.min(10, typeof raw.maxAssessments === "number" ? raw.maxAssessments : base.maxAssessments)),
+        maxNudges: Math.max(1, Math.min(5, typeof raw.maxNudges === "number" ? raw.maxNudges : base.maxNudges)),
+        maxSkillBytes: Math.max(1024, Math.min(131072, typeof raw.maxSkillBytes === "number" ? raw.maxSkillBytes : base.maxSkillBytes)),
+        maxLoadedBytes: Math.max(1024, Math.min(262144, typeof raw.maxLoadedBytes === "number" ? raw.maxLoadedBytes : base.maxLoadedBytes)),
+        recommendThreshold: Math.max(0, Math.min(1, typeof raw.recommendThreshold === "number" ? raw.recommendThreshold : base.recommendThreshold)),
+        advanceThreshold: Math.max(0, Math.min(1, typeof raw.advanceThreshold === "number" ? raw.advanceThreshold : base.advanceThreshold)),
+        loadThreshold: Math.max(0, Math.min(1, typeof raw.loadThreshold === "number" ? raw.loadThreshold : base.loadThreshold)),
+    };
+}
 /** Project files may tune the guards but cannot grant TypeSafe consent, change the mode, or raise budgets. */
 export function applyProjectOverrides(base, raw) {
     if (!isObject(raw))

package/dist/conscience.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Conscience module: broad-consideration coach that recommends or loads
+ * skills and tools before the agent acts.
+ *
+ * Pre-measurement: all selections are trace-only. No steers, no auto-loading.
+ */
+import type { Skill } from "@earendil-works/pi-coding-agent";
+import type { Questions } from "pi-typesafe";
+import type { ConscienceConfig } from "./config.js";
+export type Disposition = "advance" | "awaiting_user" | "no_gap" | "unclear";
+/** Capability roles the session model assigns to index entries. */
+export type CapabilityRole = "research" | "evidence" | "execution" | "delegation" | "review" | "conversation";
+/** Minimal index entry shape used by the conscience; full validation lives in index-cmd. */
+export interface IndexEntry {
+    kind: "skill" | "tool";
+    name: string;
+    scope: "global" | "project";
+    sourceHash: string;
+    role: CapabilityRole;
+    lead: string;
+    useWhen: string[];
+    notWhen: string[];
+    inputs: string;
+    examples: string[];
+    thin: boolean;
+    truncated?: boolean;
+    _location?: string;
+}
+/** One candidate for assessment: a skill or a tool. */
+export interface Candidate {
+    /** "skill" or "tool". */
+    kind: "skill" | "tool";
+    /** Stable id: skill name or tool name. */
+    id: string;
+    /** Human-readable description (sanitized: no absolute paths or URLs). */
+    description: string;
+    /** True when this candidate belongs to a category that was truncated (catalog incomplete). */
+    incomplete?: boolean;
+    /** Full skill metadata, present for kind=skill. */
+    skill?: Skill;
+    /** Capability role, present when the candidate has an index entry. */
+    role?: CapabilityRole;
+    /** Index entry when the candidate has a matching entry; bare description is the fallback. */
+    indexEntry?: IndexEntry;
+}
+/** The result of one assessment. */
+export interface AssessmentResult {
+    /** The disposition chosen by the shared question. */
+    disposition: Disposition;
+    /** The selected candidate, if any. */
+    selected: Candidate | null;
+    /** P(useful now) = P(direct_useful) + P(prerequisite). */
+    usefulness: number;
+    /** P(advance) from the disposition answer. */
+    pAdvance: number;
+    /** Question hash for deduplication. */
+    questionHash: string;
+    /** Time spent on this assessment (ms). */
+    elapsedMs: number;
+    /** Why no selection was made, if applicable. */
+    skipReason?: SkipReason | undefined;
+    /** Error category when skipReason is "error": timeout, network, configuration, auth, or other. */
+    errorCategory?: string | undefined;
+    /** Number of judge requests issued for this assessment. */
+    requestCount: number;
+}
+export type SkipReason = "disabled" | "no_consent" | "no_match" | "already_supplied" | "awaiting_user" | "timeout" | "error" | "stale" | "catalog_unavailable" | "catalog_limit" | "metadata_unsafe" | "budget" | "explicit_skill" | "origin_unknown" | "below_threshold";
+/** Score levels for the usefulness question. Levels are ordered from least to most useful. */
+export declare const SCORE_LEVELS: readonly ["No useful contribution to the current request, or conflicts with the supplied constraints.", "Related to the subject, but already covered, premature, or unable to resolve the current need.", "Addresses a concrete unmet need at the current step without displacing the active workflow.", "Supplies a missing prerequisite or directly applicable documented method needed for the current step."];
+/** Strip absolute paths, URLs, and credentials from a description. */
+export declare function sanitizeDescription(text: string): string;
+/** Opaque IDs: c1, c2, ... in stable order. */
+export declare function opaqueId(index: number): string;
+/** Map candidates to opaque IDs, returning a stable ordered list. */
+export declare function assignOpaqueIds(candidates: Candidate[]): Array<{
+    opaqueId: string;
+    candidate: Candidate;
+}>;
+/**
+ * Build assessment questions for a batch of candidates.
+ * State carries structured data; each question names its candidate field.
+ * Returns questions, the disposition key, and the opaqueId→candidate map.
+ */
+export declare function buildBatchQuestions(batch: Array<{
+    opaqueId: string;
+    candidate: Candidate;
+}>, task: string, recentContext: string, activeSkills: string[], suppliedSkills: string[]): {
+    questions: Questions;
+    dispositionKey: string;
+    idMap: Map<string, Candidate>;
+};
+/**
+ * Build the full state object for the judge request (spec §3 state contract).
+ */
+export declare function buildState(task: string, recentContext: string, activeSkills: string[], suppliedSkills: string[], batch: Array<{
+    opaqueId: string;
+    candidate: Candidate;
+}>): Record<string, unknown>;
+/**
+ * Compute a deterministic hash of the assessment questions for deduplication.
+ * Recursively sorts all object keys for canonical form.
+ *
+ * Opaque candidate ids (c1, c2, …) are positional, not semantic: which batch a prompt happens to
+ * produce must not change the hash the activation gate compares. A conscience question set
+ * (recognised by the `conscience_disposition` key) is therefore hashed as the disposition question
+ * plus one canonical candidate question, keyed `c1` — every candidate question carries the same
+ * wording by design (per-candidate state lives in the request state, not the question text), so any
+ * one of them is the canonical representative.
+ *
+ * Why the hash was constant before this change: each assessment issues several requests (one per
+ * batch), each with its own question keys, and `assess` kept only the hash of whichever batch wrote
+ * `state_.hash` last. Every recorded replay row showed `fb2d35042f667b3c` only because those final
+ * batches happened to serialize identically — an accident of batch order, not a guarantee.
+ */
+export declare function questionHash(questions: Questions): string;
+/** Filter candidates by eligibility rules, capped at MAX_ELIGIBLE per category. Attaches index entries when available. */
+export declare function eligibleCandidates(skills: Skill[], tools: {
+    name: string;
+    description: string;
+}[], config: ConscienceConfig, activeSkills: string[], suppliedSkills: string[], globalIndex?: {
+    entries: IndexEntry[];
+} | undefined, projectIndex?: {
+    entries: IndexEntry[];
+} | undefined): {
+    candidates: Candidate[];
+    skillOverflow: boolean;
+    toolOverflow: boolean;
+};
+export interface Judge {
+    evaluate(request: {
+        state: unknown;
+        questions: Questions;
+    }, options?: {
+        timeoutMs?: number;
+    }): Promise<{
+        answers: Record<string, unknown>;
+    }>;
+}
+export interface ConscienceDeps {
+    judge: Judge | undefined;
+    config: ConscienceConfig;
+    /** Shared timeout from WardenConfig. The effective deadline is min(conscience.timeoutMs, sharedTimeoutMs). */
+    sharedTimeoutMs: number;
+    /** Current wall-clock time (ms). Injected for testability. */
+    now?: () => number;
+    /** Pre-loaded global index, if any. */
+    globalIndex?: {
+        entries: IndexEntry[];
+    } | undefined;
+    /** Pre-loaded project index, if any. */
+    projectIndex?: {
+        entries: IndexEntry[];
+    } | undefined;
+}
+/**
+ * Run assessment for the given prompt revision.
+ * Pre-measurement: returns trace-only results. No steers, no auto-loading.
+ * Issues concurrent requests (up to four in flight), skills first, shared deadline.
+ */
+export declare function assess(prompt: string, recentContext: string, skills: Skill[], tools: {
+    name: string;
+    description: string;
+}[], activeSkills: string[], suppliedSkills: string[], deps: ConscienceDeps): Promise<AssessmentResult>;