@wyattjoh/demur 0.6.0 → 0.7.0

package/README.md

@@ -48,11 +48,13 @@ or sensitive names. Review TypeSafe's service terms and data-handling policy
 before enabling demur in a sensitive repository. Do not run secrets directly in
 shell arguments when the guard is active.
 
-Pi training capture stores the complete command, working directory, operating
-mode, full verdict and judgments, and resulting host action locally. These
-records can therefore contain secrets or sensitive names from shell arguments
-and paths. Training capture is off by default and is unavailable while the Pi
-integration is disabled.
+Pi training capture stores the complete command, exact TypeSafe state, local
+static-analysis result, model/question/policy versions, exact policy thresholds,
+operating mode, full verdict and judgments, and resulting host action locally.
+These records can therefore contain secrets or sensitive names from shell
+arguments, paths, Git
+context, and deterministic command analysis. Training capture is off by default
+and is unavailable while the Pi integration is disabled.
 
 ## Requirements
 
@@ -98,7 +100,7 @@ Pin a specific release when reproducibility matters:
 
 <!-- x-release-please-start-version -->
 ```sh
-pi install npm:@wyattjoh/demur@0.6.0
+pi install npm:@wyattjoh/demur@0.7.0
 ```
 <!-- x-release-please-end -->
 
@@ -111,7 +113,9 @@ pi
 The extension intercepts `bash` tool calls. Because Pi runs extensions under
 Node.js while demur uses `Bun.secrets`, the extension launches a package-local
 Bun worker for each judgment. The API key remains inside that worker; only the
-command request and resulting verdict cross its local stdio pipes. `ask` opens
+command request and resulting verdict cross its local stdio pipes. When training
+capture is enabled, the exact model state and local policy evidence return with
+the verdict for private local persistence. `ask` opens
 an interactive confirmation dialog; without an interactive UI, demur blocks the
 command.
 
@@ -166,8 +170,11 @@ Set `DEMUR_STATE_HOME` to place `usage.json`, `training.jsonl`, and
 demur-specific override takes precedence over the XDG and home-directory
 locations. Training records are retained until the user removes them. Human
 reviews are appended separately; accepted and corrected records are linked by a
-stable record ID, leaving the original evidence unchanged. A training-write
-failure is reported but never changes whether the command runs.
+stable record ID, leaving the original evidence unchanged. Corrected reviews
+also carry a machine-readable reason so recurring question, context, policy, and
+service failures can be measured without mining free-form notes. Version-one
+records and reviews remain readable. A training-write failure is reported but
+never changes whether the command runs.
 
 Pi packages execute with the user's full system permissions. Review this
 repository before installing it.
@@ -220,7 +227,8 @@ demur auth logout
 demur training review
 demur training list --status=unreviewed --cwd=/workspace
 demur training list --status=deny --json
-demur training review <record-id> --decision=deny --note="would destroy work" --json
+demur training evaluate --json
+demur training review <record-id> --decision=deny --reason=recoverability --note="would destroy work" --json
 demur judge "git reset --hard HEAD~3"
 ```
 
@@ -249,18 +257,22 @@ and Page Down page within the focused pane, and queue navigation stops at its
 first and last entries. Mouse clicks select tabs, records, the filter, or either
 pane; the wheel scrolls the queue and detail pane. Enter selects the original
 decision, `1`/`2`/`3` choose `allow`/`ask`/`deny`, `s`
-leaves a record for a later pass, and `q` or Escape stops. Previously reviewed
-records remain available, and changing an answer appends a review revision while
-preserving its visible history. The TUI remains open when a view is empty and
+leaves a record for a later pass, and `q` or Escape stops. A correction first
+asks for one structured reason, then accepts an optional note. Previously
+reviewed records remain available, and changing an answer appends a review
+revision while preserving its visible history. The TUI remains open when a view is empty and
 polls training state for newly captured or externally reviewed evaluations.
 
 Flag-based training commands provide the same review operations without the
 TUI. `demur training list` accepts `--status` and fuzzy `--cwd` filters. Status
 is derived from the latest human review, so `allow`, `ask`, and `deny` select
 reviewed records while `unreviewed` selects records without a review. Record a
-new append-only review revision by passing a record ID, a required
-`--decision=<allow|ask|deny>`, and an optional `--note`. Add `--json` to either
-operation to emit one versioned JSON document; JSON failures are written to
+new append-only review revision by passing a record ID and a required
+`--decision=<allow|ask|deny>`. Corrections also require `--reason` with one of
+`inert-or-read-only`, `sensitive-data`, `security-boundary`, `recoverability`,
+`shared-infrastructure`, `blast-radius`, `static-uncertainty`, `missing-context`,
+or `service-failure`; `--note` remains optional. Add `--json` to list, evaluate,
+or review to emit one versioned JSON document; JSON failures are written to
 stdout with a nonzero exit code. Interactive `demur training review` still opens
 the TUI, but without a terminal it requires an explicit list or record-ID review
 operation. Reviews remain separate from the original evidence so they can later
@@ -325,11 +337,36 @@ and deterministic policy controls alongside demur.
 - `src/guard.internal.ts` — Effect-native orchestration and fail-closed recovery
 - `src/guard.ts` — managed runtime and Promise boundary
 - `src/training-review-model.ts` — historical review status and cwd filtering
+- `src/training-evaluation.ts` — offline correction metrics and threshold comparisons
 - `src/training-review-tui.tsx` — interactive OpenTUI training-review queue
 - `extensions/demur/` — Pi `tool_call` integration and training-state storage
 - `src/adapters/claude-code.ts` — Claude Code `PreToolUse` integration
 - `eval/` — safe synthetic contrast cases and the live evaluation runner
 
+## Training feedback evaluation
+
+`demur training evaluate` joins each record with its latest review and replays
+stored raw judgments through the shared `decide()` policy. By default it makes
+no TypeSafe requests. The report includes a decision matrix, an asymmetric weighted loss
+that penalizes unsafe false allows most heavily, correction counts grouped by
+structured reason, replay fidelity, and up to five single-threshold candidates
+that improve the observed records.
+
+Candidates are exploratory and are never applied automatically. The command
+scores them on the same private records used to discover them, so validate a
+candidate on an independent holdout and the synthetic corpus before changing
+`THRESHOLDS`. Newly captured version-two records include the exact model state
+and static-gate analysis required for complete replay; legacy records support
+policy-only replay.
+
+Pass `--replay` explicitly to send reviewed version-two records' previously
+captured model state to TypeSafe again using the current question set. This is a
+cost-bearing operation and re-discloses the stored command and context described
+above. It is capped at 20 requests by default; use `--limit=<1-100>` to choose a
+different bound. Commands remain data and are never executed. The replay report shows
+improvements, regressions, failures, token usage, and per-record raw judgments;
+use it when changing one question at a time.
+
 ## Synthetic evaluation
 
 The synthetic evaluation measures whether the two policy-qualification questions

package/extensions/demur/index.ts

@@ -7,7 +7,11 @@ import {
   type ToolCallEvent,
   type ToolCallEventResult,
 } from "@earendil-works/pi-coding-agent";
-import type { Verdict } from "../../src/types.ts";
+import type {
+  GuardEvaluation,
+  GuardEvidence,
+  Verdict,
+} from "../../src/types.ts";
 import {
   estimateInputCostUsd,
   formatUsd,
@@ -54,9 +58,15 @@ export async function handleToolCall(
   if (command.trim() === "") return undefined;
 
   const evaluationStartedAt = performance.now();
-  let verdict: Verdict;
+  let evaluation: GuardEvaluation;
   try {
-    verdict = await runGuardWorker(command, ctx.cwd, ctx.signal);
+    evaluation = await runGuardWorkerRequest(
+      command,
+      ctx.cwd,
+      ctx.signal,
+      process.env,
+      settings.training,
+    );
   } catch (error: unknown) {
     const evaluationMs = performance.now() - evaluationStartedAt;
     if (ctx.signal?.aborted) {
@@ -74,16 +84,20 @@ export async function handleToolCall(
       };
     }
 
-    verdict = {
-      decision: "deny",
-      reason: `demur: guard worker crashed — ${errorDetail(error)}`,
-      judgments: undefined,
-      failure: "unexpected",
-      latencyMs: evaluationMs,
-      usage: undefined,
+    evaluation = {
+      verdict: {
+        decision: "deny",
+        reason: `demur: guard worker crashed — ${errorDetail(error)}`,
+        judgments: undefined,
+        failure: "unexpected",
+        latencyMs: evaluationMs,
+        usage: undefined,
+      },
+      evidence: undefined,
     };
   }
 
+  const verdict = evaluation.verdict;
   const evaluationMs = performance.now() - evaluationStartedAt;
   const inputTokens = verdict.usage?.inputTokens;
   const accumulatedCostUsd = await recordAccumulatedCost(inputTokens);
@@ -109,6 +123,7 @@ export async function handleToolCall(
       ctx,
       settings.mode,
       verdict,
+      evaluation.evidence,
       result,
     );
   }
@@ -302,6 +317,18 @@ export function runGuardWorker(
   signal: AbortSignal | undefined,
   environment: NodeJS.ProcessEnv = process.env,
 ): Promise<Verdict> {
+  return runGuardWorkerRequest(command, cwd, signal, environment, false).then(
+    (evaluation) => evaluation.verdict,
+  );
+}
+
+function runGuardWorkerRequest(
+  command: string,
+  cwd: string,
+  signal: AbortSignal | undefined,
+  environment: NodeJS.ProcessEnv,
+  includeEvidence: boolean,
+): Promise<GuardEvaluation> {
   return new Promise((resolve, reject) => {
     if (signal?.aborted) {
       reject(new Error("guard request cancelled"));
@@ -333,7 +360,6 @@ export function runGuardWorker(
     signal?.addEventListener("abort", abort, { once: true });
     child.stdout.on("data", (chunk: Buffer) => {
       stdout = appendBounded(stdout, chunk);
-      if (stdout.length >= MAX_WORKER_OUTPUT_BYTES) child.kill();
     });
     child.stderr.on("data", (chunk: Buffer) => {
       stderr = appendBounded(stderr, chunk);
@@ -349,7 +375,7 @@ export function runGuardWorker(
         }
 
         try {
-          resolve(parseVerdict(stdout));
+          resolve(parseGuardWorkerResponse(stdout, includeEvidence));
         } catch (error: unknown) {
           reject(new Error(`invalid guard worker response: ${errorDetail(error)}`));
         }
@@ -357,7 +383,7 @@ export function runGuardWorker(
     });
 
     child.stdin.on("error", (error) => finish(() => reject(error)));
-    child.stdin.end(JSON.stringify({ command, cwd }));
+    child.stdin.end(JSON.stringify({ command, cwd, includeEvidence }));
   });
 }
 
@@ -496,14 +522,22 @@ async function recordTrainingResult(
   ctx: ExtensionContext,
   mode: "enforce" | "passive",
   verdict: Verdict,
+  evidence: GuardEvidence | undefined,
   result: ToolCallEventResult | undefined,
 ): Promise<void> {
   try {
+    if (verdict.judgments !== undefined && evidence === undefined) {
+      ctx.ui.notify(
+        "demur: recording training evaluation without replay evidence",
+        "warning",
+      );
+    }
     await recordTrainingEvaluation({
       command,
       cwd: ctx.cwd,
       mode,
       verdict,
+      evidence,
       hostAction: result?.block === true ? "block" : "allow",
     });
   } catch (error: unknown) {
@@ -630,8 +664,36 @@ function formatDecimal(value: number, fractionDigits: number): string {
     .replace(/\.0+$/, "");
 }
 
-function parseVerdict(output: string): Verdict {
-  const value: unknown = JSON.parse(output);
+function parseGuardWorkerResponse(
+  output: string,
+  includeEvidence: boolean,
+): GuardEvaluation {
+  if (!includeEvidence) {
+    return {
+      verdict: parseVerdictValue(JSON.parse(output)),
+      evidence: undefined,
+    };
+  }
+
+  const separator = output.indexOf("\n");
+  if (separator < 0) {
+    throw new Error("training guard response did not contain a verdict line");
+  }
+
+  const verdict = parseVerdictValue(JSON.parse(output.slice(0, separator)));
+  const encodedEvidence = output.slice(separator + 1);
+  try {
+    return {
+      verdict,
+      evidence: parseGuardEvidence(JSON.parse(encodedEvidence)),
+    };
+  } catch {
+    // Training evidence is best-effort and must never change the guard verdict.
+    return { verdict, evidence: undefined };
+  }
+}
+
+function parseVerdictValue(value: unknown): Verdict {
   if (value === null || typeof value !== "object") {
     throw new Error("verdict must be an object");
   }
@@ -657,6 +719,28 @@ function parseVerdict(output: string): Verdict {
   };
 }
 
+function parseGuardEvidence(value: unknown): GuardEvidence | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "object") {
+    throw new Error("guard evidence must be an object");
+  }
+
+  const evidence = value as Record<string, unknown>;
+  if (
+    evidence.modelState === null ||
+    typeof evidence.modelState !== "object" ||
+    typeof evidence.model !== "string" ||
+    !Number.isInteger(evidence.questionSetVersion) ||
+    !Number.isInteger(evidence.policyVersion) ||
+    evidence.policyThresholds === null ||
+    typeof evidence.policyThresholds !== "object"
+  ) {
+    throw new Error("guard evidence is incomplete");
+  }
+
+  return evidence as GuardEvidence;
+}
+
 function errorDetail(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }

package/extensions/demur/training-store.ts

@@ -2,7 +2,11 @@ import { randomUUID } from "node:crypto";
 import { appendFile, mkdir, readFile, rmdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import type { Decision, Verdict } from "../../src/types.ts";
+import type {
+  Decision,
+  GuardEvidence,
+  Verdict,
+} from "../../src/types.ts";
 import { getDemurStateDirectory } from "./paths.ts";
 
 const LOCK_RETRY_MS = 10;
@@ -19,9 +23,9 @@ export type TrainingMode = "enforce" | "passive";
 export type TrainingHostAction = "allow" | "block";
 
 /**
- * Complete evidence captured for one training-mode command evaluation.
+ * Legacy training record captured before replayable invocation evidence existed.
  */
-export type TrainingRecord = {
+export type TrainingRecordV1 = {
   version: 1;
   id: string;
   recordedAt: string;
@@ -33,9 +37,60 @@ export type TrainingRecord = {
 };
 
 /**
- * Human review of one captured training evaluation.
+ * Training record with exact model state and policy provenance.
  */
-export type TrainingReview = {
+export type TrainingRecordV2 = {
+  version: 2;
+  id: string;
+  recordedAt: string;
+  command: string;
+  cwd: string;
+  mode: TrainingMode;
+  verdict: Verdict;
+  evidence: GuardEvidence | undefined;
+  hostAction: TrainingHostAction;
+};
+
+/**
+ * Complete evidence captured for one training-mode command evaluation.
+ */
+export type TrainingRecord = TrainingRecordV1 | TrainingRecordV2;
+
+/**
+ * Machine-readable explanation for why a human corrected a verdict.
+ */
+export type TrainingCorrectionReason =
+  | "inert-or-read-only"
+  | "sensitive-data"
+  | "security-boundary"
+  | "recoverability"
+  | "shared-infrastructure"
+  | "blast-radius"
+  | "static-uncertainty"
+  | "missing-context"
+  | "service-failure";
+
+/**
+ * Stable correction-reason values accepted by storage and CLI boundaries.
+ */
+export const TRAINING_CORRECTION_REASONS: ReadonlyArray<
+  TrainingCorrectionReason
+> = [
+  "inert-or-read-only",
+  "sensitive-data",
+  "security-boundary",
+  "recoverability",
+  "shared-infrastructure",
+  "blast-radius",
+  "static-uncertainty",
+  "missing-context",
+  "service-failure",
+];
+
+/**
+ * Legacy human review recorded before structured correction reasons existed.
+ */
+export type TrainingReviewV1 = {
   version: 1;
   recordId: string;
   reviewedAt: string;
@@ -44,6 +99,24 @@ export type TrainingReview = {
   note: string | undefined;
 };
 
+/**
+ * Human review with a structured reason for corrected model decisions.
+ */
+export type TrainingReviewV2 = {
+  version: 2;
+  recordId: string;
+  reviewedAt: string;
+  originalDecision: Decision;
+  expectedDecision: Decision;
+  correctionReason: TrainingCorrectionReason | undefined;
+  note: string | undefined;
+};
+
+/**
+ * Human review of one captured training evaluation.
+ */
+export type TrainingReview = TrainingReviewV1 | TrainingReviewV2;
+
 /**
  * Input required to append a human review.
  */
@@ -51,9 +124,18 @@ export type TrainingReviewInput = {
   recordId: string;
   originalDecision: Decision;
   expectedDecision: Decision;
+  correctionReason: TrainingCorrectionReason | undefined;
   note: string | undefined;
 };
 
+/**
+ * Input required to append a replayable training evaluation.
+ */
+export type TrainingRecordInput = Omit<
+  TrainingRecordV2,
+  "version" | "id" | "recordedAt"
+>;
+
 /**
  * Resolve the global training-record file according to demur and XDG overrides.
  *
@@ -96,11 +178,11 @@ export function getTrainingReviewPath(
  * @returns The persisted record with generated identity and timestamp
  */
 export async function recordTrainingEvaluation(
-  input: Omit<TrainingRecord, "version" | "id" | "recordedAt">,
+  input: TrainingRecordInput,
   logPath: string = getTrainingLogPath(),
-): Promise<TrainingRecord> {
-  const record: TrainingRecord = {
-    version: 1,
+): Promise<TrainingRecordV2> {
+  const record: TrainingRecordV2 = {
+    version: 2,
     id: randomUUID(),
     recordedAt: new Date().toISOString(),
     ...input,
@@ -131,9 +213,22 @@ export async function loadTrainingRecords(
 export async function recordTrainingReview(
   input: TrainingReviewInput,
   reviewPath: string = getTrainingReviewPath(),
-): Promise<TrainingReview> {
-  const review: TrainingReview = {
-    version: 1,
+): Promise<TrainingReviewV2> {
+  if (
+    input.originalDecision !== input.expectedDecision &&
+    input.correctionReason === undefined
+  ) {
+    throw new Error("corrected training reviews require a correction reason");
+  }
+  if (
+    input.originalDecision === input.expectedDecision &&
+    input.correctionReason !== undefined
+  ) {
+    throw new Error("accepted training reviews cannot have a correction reason");
+  }
+
+  const review: TrainingReviewV2 = {
+    version: 2,
     reviewedAt: new Date().toISOString(),
     ...input,
   };
@@ -213,41 +308,37 @@ function parseTrainingRecord(
 
   const record = value as Record<string, unknown>;
   if (
-    record.version !== 1 ||
+    (record.version !== 1 && record.version !== 2) ||
     typeof record.id !== "string" ||
     typeof record.recordedAt !== "string" ||
     typeof record.command !== "string" ||
     typeof record.cwd !== "string" ||
     (record.mode !== "enforce" && record.mode !== "passive") ||
     (record.hostAction !== "allow" && record.hostAction !== "block") ||
-    !isVerdict(record.verdict)
+    !isVerdict(record.verdict) ||
+    (record.version === 2 && !isGuardEvidence(record.evidence))
   ) {
     throw invalidRecord(path, line);
   }
 
-  const verdict = record.verdict as Record<string, unknown>;
-  return {
-    version: 1,
+  const verdict = normalizeVerdict(record.verdict);
+  const common = {
     id: record.id,
     recordedAt: record.recordedAt,
     command: record.command,
     cwd: record.cwd,
     mode: record.mode,
-    verdict: {
-      decision: verdict.decision as Decision,
-      reason: verdict.reason as string,
-      judgments: verdict.judgments === null
-        ? undefined
-        : verdict.judgments as Verdict["judgments"],
-      failure: verdict.failure === null
-        ? undefined
-        : verdict.failure as Verdict["failure"],
-      latencyMs: verdict.latencyMs as number,
-      usage: verdict.usage === null
-        ? undefined
-        : verdict.usage as Verdict["usage"],
-    },
+    verdict,
     hostAction: record.hostAction,
+  } as const;
+
+  if (record.version === 1) return { version: 1, ...common };
+  return {
+    version: 2,
+    ...common,
+    evidence: record.evidence === null
+      ? undefined
+      : normalizeGuardEvidence(record.evidence),
   };
 }
 
@@ -262,25 +353,55 @@ function parseTrainingReview(
 
   const review = value as Record<string, unknown>;
   if (
-    review.version !== 1 ||
+    (review.version !== 1 && review.version !== 2) ||
     typeof review.recordId !== "string" ||
     typeof review.reviewedAt !== "string" ||
     !isDecision(review.originalDecision) ||
     !isDecision(review.expectedDecision) ||
     (review.note !== undefined &&
       review.note !== null &&
-      typeof review.note !== "string")
+      typeof review.note !== "string") ||
+    (review.version === 2 &&
+      (!isReviewCorrectionReasonValid(review) ||
+        (review.correctionReason !== undefined &&
+          review.correctionReason !== null &&
+          !isTrainingCorrectionReason(review.correctionReason))))
   ) {
     throw invalidRecord(path, line);
   }
 
-  return {
-    version: 1,
+  const common = {
     recordId: review.recordId,
     reviewedAt: review.reviewedAt,
     originalDecision: review.originalDecision,
     expectedDecision: review.expectedDecision,
     note: review.note === null ? undefined : review.note,
+  } as const;
+  if (review.version === 1) return { version: 1, ...common };
+  return {
+    version: 2,
+    ...common,
+    correctionReason: review.correctionReason === null
+      ? undefined
+      : review.correctionReason as TrainingCorrectionReason | undefined,
+  };
+}
+
+function normalizeVerdict(value: unknown): Verdict {
+  const verdict = value as Record<string, unknown>;
+  return {
+    decision: verdict.decision as Decision,
+    reason: verdict.reason as string,
+    judgments: verdict.judgments === null
+      ? undefined
+      : verdict.judgments as Verdict["judgments"],
+    failure: verdict.failure === null
+      ? undefined
+      : verdict.failure as Verdict["failure"],
+    latencyMs: verdict.latencyMs as number,
+    usage: verdict.usage === null
+      ? undefined
+      : verdict.usage as Verdict["usage"],
   };
 }
 
@@ -296,6 +417,63 @@ function isDecision(value: unknown): value is Decision {
   return value === "allow" || value === "ask" || value === "deny";
 }
 
+function isReviewCorrectionReasonValid(
+  review: Record<string, unknown>,
+): boolean {
+  const corrected = review.originalDecision !== review.expectedDecision;
+  const hasReason = review.correctionReason !== undefined &&
+    review.correctionReason !== null;
+  return corrected === hasReason;
+}
+
+/**
+ * Check whether a value is a supported structured correction reason.
+ *
+ * @param value - Candidate correction-reason value
+ * @returns Whether the value belongs to the stable correction taxonomy
+ */
+export function isTrainingCorrectionReason(
+  value: unknown,
+): value is TrainingCorrectionReason {
+  return typeof value === "string" &&
+    TRAINING_CORRECTION_REASONS.includes(value as TrainingCorrectionReason);
+}
+
+function isGuardEvidence(value: unknown): boolean {
+  if (value === null || value === undefined) return true;
+  if (typeof value !== "object") return false;
+  const evidence = value as Record<string, unknown>;
+  return evidence.modelState !== null &&
+    typeof evidence.modelState === "object" &&
+    (evidence.analysis === null || evidence.analysis === undefined ||
+      typeof evidence.analysis === "object") &&
+    typeof evidence.model === "string" &&
+    Number.isInteger(evidence.questionSetVersion) &&
+    Number.isInteger(evidence.policyVersion) &&
+    isNumberRecord(evidence.policyThresholds);
+}
+
+function normalizeGuardEvidence(value: unknown): GuardEvidence {
+  const evidence = value as Record<string, unknown>;
+  return {
+    modelState: evidence.modelState as GuardEvidence["modelState"],
+    analysis: evidence.analysis === null
+      ? undefined
+      : evidence.analysis as GuardEvidence["analysis"],
+    model: evidence.model as string,
+    questionSetVersion: evidence.questionSetVersion as number,
+    policyVersion: evidence.policyVersion as number,
+    policyThresholds: evidence.policyThresholds as GuardEvidence["policyThresholds"],
+  };
+}
+
+function isNumberRecord(value: unknown): boolean {
+  if (value === null || typeof value !== "object") return false;
+  return Object.values(value).every((entry) =>
+    typeof entry === "number" && Number.isFinite(entry)
+  );
+}
+
 function invalidRecord(path: string, line: number): Error {
   return new Error(`invalid training record in ${path} at line ${line}`);
 }