pi-pier 0.2.7 → 0.3.1

package/src/jev-client.ts

@@ -0,0 +1,141 @@
+/**
+ * Jev decision layer — direct HTTP client (RFC docs/rfc-jev-integration.md §5). Not the official SDK
+ * (@typesafe-ai/sdk): its retry machinery has no total-latency budget (timeouts retried by default,
+ * Retry-After honored up to 60s), which is incompatible with pier's fail-open budgets.
+ *
+ * Every ask() resolves (never throws): errors, timeouts, 429s and low confidence at the call site
+ * all mean unanswered, and the caller fails open.
+ */
+import { sha256Hex } from './observation-core.ts';
+import { appendEfficiencyLog, efficiencyLogPath } from './efficiency-store.ts';
+import { parseJevAnswers, type JevAnswer, type JevQuestion, type JevUsage } from './jev-core.ts';
+import type { JevConfig } from './efficiency-config-core.ts';
+
+const JEV_DEFAULT_BASE_URL = 'https://api.typesafe.ai';
+
+export interface JevAskMeta {
+  /** Stable question-set id for telemetry rows (e.g. 'epr-diagnostic-gate'). */
+  questionId: string;
+  /** Total-budget override in ms; defaults to the config timeoutMs. */
+  timeoutMs?: number;
+  sessionId?: string;
+  /** Site-specific static fields for telemetry; must never contain request bodies. */
+  extra?: Record<string, unknown>;
+  /**
+   * Post-answer decision fields for telemetry (choices/scores/final verdicts — what threshold tuning
+   * needs; still never request bodies). Called exactly once per ask.
+   */
+  enrich?: (outcome: { ok: boolean; answers: Record<string, JevAnswer> | null }) => Record<string, unknown>;
+}
+
+export type JevAskResult =
+  | { readonly ok: true; readonly answers: Record<string, JevAnswer>; readonly model: string; readonly usage: JevUsage; readonly latencyMs: number }
+  | { readonly ok: false; readonly reason: string; readonly latencyMs: number };
+
+export interface JevRuntimeDeps {
+  fetchImpl?: typeof fetch;
+  now?: () => number;
+  /** Session root for jev.jsonl; telemetry is skipped when absent. */
+  getSessionRoot?: () => string | null;
+  /** Session id fallback for telemetry rows; sites that know it pass meta.sessionId instead. */
+  getSessionId?: () => string | null | undefined;
+}
+
+export interface JevRuntime {
+  readonly available: boolean;
+  ask(request: { state: unknown; questions: Record<string, JevQuestion> }, meta: JevAskMeta): Promise<JevAskResult>;
+}
+
+export function createJevRuntime(getConfig: () => JevConfig, deps: JevRuntimeDeps = {}): JevRuntime {
+  const doFetch = deps.fetchImpl ?? ((input, init) => globalThis.fetch(input, init));
+  const now = deps.now ?? Date.now;
+
+  async function logAsk(
+    config: JevConfig,
+    meta: JevAskMeta,
+    outcome: { ok: true; model: string; usage: JevUsage } | { ok: false; reason: string },
+    latencyMs: number,
+    state: unknown,
+    enriched: Record<string, unknown>,
+  ): Promise<void> {
+    if (!config.logEnabled) return;
+    const sessionRoot = deps.getSessionRoot?.() ?? null;
+    if (!sessionRoot) return;
+    const serialized = JSON.stringify(state) ?? '';
+    const record: Record<string, unknown> = {
+      schema: 'pier-efficiency/1',
+      mechanism: 'jev',
+      sessionId: meta.sessionId ?? deps.getSessionId?.() ?? 'unknown',
+      ts: new Date(now()).toISOString(),
+      questionId: meta.questionId,
+      model: outcome.ok ? outcome.model : config.model,
+      latencyMs,
+      verdict: outcome.ok ? 'answered' : 'fallback',
+      fallback: !outcome.ok,
+      reason: outcome.ok ? null : outcome.reason,
+      stateBytes: Buffer.byteLength(serialized, 'utf8'),
+      stateHash: sha256Hex(serialized),
+      ...(outcome.ok ? { usage: { input_tokens: outcome.usage.inputTokens, output_tokens: outcome.usage.outputTokens } } : {}),
+      ...(meta.extra ?? {}),
+      ...enriched,
+    };
+    try {
+      await appendEfficiencyLog(efficiencyLogPath(sessionRoot, 'jev'), record);
+    } catch {
+      /* Never surfaced to the caller. */
+    }
+  }
+
+  return {
+    // Getter: config reloads (session_start re-resolves from disk) propagate.
+    get available(): boolean {
+      const config = getConfig();
+      return config.enabled && Boolean(config.apiKey);
+    },
+    async ask(request, meta): Promise<JevAskResult> {
+      const startedAt = now();
+      const config = getConfig();
+      const fail = async (reason: string): Promise<JevAskResult> => {
+        const latencyMs = now() - startedAt;
+        const enriched = meta.enrich?.({ ok: false, answers: null }) ?? {};
+        await logAsk(config, meta, { ok: false, reason }, latencyMs, request.state, enriched);
+        return { ok: false, reason, latencyMs };
+      };
+      if (!config.enabled) return fail('disabled');
+      if (!config.apiKey) return fail('no-api-key');
+
+      const timeoutMs = meta.timeoutMs ?? config.timeoutMs;
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const base = (config.baseUrl ?? JEV_DEFAULT_BASE_URL).replace(/\/+$/, '');
+        const response = await doFetch(`${base}/v1/systemone`, {
+          method: 'POST',
+          headers: {
+            Authorization: `Bearer ${config.apiKey}`,
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({ model: config.model, state: request.state, questions: request.questions }),
+          signal: controller.signal,
+        });
+        if (!response.ok) {
+          // 429 (and everything else) fails open immediately: limits are
+          // dynamically adjusted upstream and every pier call is droppable.
+          return fail(response.status === 429 ? 'rate-limited' : `http-${response.status}`);
+        }
+        const raw: unknown = await response.json();
+        const parsed = parseJevAnswers(raw, Object.keys(request.questions));
+        if (!parsed.ok) return fail(parsed.reason);
+        const latencyMs = now() - startedAt;
+        const enriched = meta.enrich?.({ ok: true, answers: parsed.answers }) ?? {};
+        await logAsk(config, meta, { ok: true, model: parsed.model, usage: parsed.usage }, latencyMs, request.state, enriched);
+        return { ok: true, answers: parsed.answers, model: parsed.model, usage: parsed.usage, latencyMs };
+      } catch (error) {
+        const aborted = error instanceof Error && error.name === 'AbortError';
+        return fail(aborted ? 'timeout' : 'network-error');
+      } finally {
+        clearTimeout(timer);
+      }
+    },
+  };
+}

package/src/jev-core.ts

@@ -0,0 +1,431 @@
+/**
+ * Jev decision layer — pure core (RFC docs/rfc-jev-integration.md).
+ *
+ * Question/answer shapes mirror the closed set of POST /v1/systemone (https://docs.typesafe.ai/api):
+ * noul / choice / score. No I/O here; the HTTP client and jev.jsonl telemetry live in jev-client.ts.
+ *
+ * RFC design rules: arithmetic, counting and thresholds stay in code; state carries only what each
+ * question needs; instructions are English (CJK is weaker, hence the stricter P0-2 gate); and any
+ * answer below its confidence gate counts as unanswered so callers fail open.
+ */
+import { containsLikelySecret, FAILURE_SIGNAL } from './reducer-core.ts';
+
+/* ── Request/response shapes (closed set) ── */
+
+export type JevQuestion =
+  | { readonly type: 'noul'; readonly instructions: string; readonly criteria?: { readonly true?: string; readonly false?: string } }
+  | { readonly type: 'choice'; readonly instructions: string; readonly criteria: Record<string, string> }
+  | { readonly type: 'score'; readonly instructions: string; readonly criteria: readonly string[] };
+
+export interface JevUsage {
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+}
+
+export type JevAnswer =
+  | { readonly type: 'noul'; readonly noul: number }
+  | { readonly type: 'choice'; readonly choice: string; readonly probabilities: Record<string, number>; readonly confidence: number }
+  | { readonly type: 'score'; readonly score: number; readonly probabilities: Record<string, number>; readonly confidence: number };
+
+export interface JevRequest {
+  readonly state: unknown;
+  readonly questions: Record<string, JevQuestion>;
+}
+
+export type JevParsed =
+  | { readonly ok: true; readonly answers: Record<string, JevAnswer>; readonly model: string; readonly usage: JevUsage }
+  | { readonly ok: false; readonly reason: string };
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function finiteNumber(v: unknown): number | undefined {
+  return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+}
+
+function unitNumber(v: unknown): number | undefined {
+  const n = finiteNumber(v);
+  return n !== undefined && n >= 0 && n <= 1 ? n : undefined;
+}
+
+type AnswerOf<T extends JevAnswer['type']> = Extract<JevAnswer, { type: T }>;
+
+/** A missing or wrongly-shaped answer counts as unanswered, never as a verdict (RFC fail-open). */
+function answerOf<T extends JevAnswer['type']>(
+  answers: Record<string, JevAnswer>,
+  id: string,
+  type: T,
+): AnswerOf<T> | undefined {
+  const answer = answers[id];
+  return answer?.type === type ? answer as AnswerOf<T> : undefined;
+}
+
+function parseProbabilities(v: unknown): Record<string, number> | undefined {
+  if (!isPlainObject(v)) return undefined;
+  const out: Record<string, number> = {};
+  for (const [k, raw] of Object.entries(v)) {
+    const n = finiteNumber(raw);
+    if (n === undefined) return undefined;
+    out[k] = n;
+  }
+  return out;
+}
+
+/** Strict validation of one response against the question ids we sent: extra ids are ignored, and
+ *  every expected id must be present and well-formed or the call counts as unanswered (fail-open). */
+export function parseJevAnswers(raw: unknown, expectedIds: readonly string[]): JevParsed {
+  if (!isPlainObject(raw)) return { ok: false, reason: 'response-not-object' };
+  const model = typeof raw.model === 'string' && raw.model.trim() ? raw.model : undefined;
+  if (model === undefined) return { ok: false, reason: 'missing-model' };
+  const rawUsage = isPlainObject(raw.usage) ? raw.usage : undefined;
+  const inputTokens = finiteNumber(rawUsage?.input_tokens);
+  const outputTokens = finiteNumber(rawUsage?.output_tokens);
+  if (inputTokens === undefined || inputTokens < 0 || outputTokens === undefined || outputTokens < 0) {
+    return { ok: false, reason: 'bad-usage' };
+  }
+  const rawAnswers = isPlainObject(raw.answers) ? raw.answers : undefined;
+  if (rawAnswers === undefined) return { ok: false, reason: 'missing-answers' };
+
+  const answers: Record<string, JevAnswer> = {};
+  for (const id of expectedIds) {
+    const a = isPlainObject(rawAnswers[id]) ? rawAnswers[id] : undefined;
+    if (a === undefined) return { ok: false, reason: `missing-answer:${id}` };
+    if (a.type === 'noul') {
+      const noul = unitNumber(a.noul);
+      if (noul === undefined) return { ok: false, reason: `bad-noul:${id}` };
+      answers[id] = { type: 'noul', noul };
+      continue;
+    }
+    if (a.type === 'choice') {
+      const choice = typeof a.choice === 'string' ? a.choice : undefined;
+      const probabilities = parseProbabilities(a.probabilities);
+      const confidence = unitNumber(a.confidence);
+      if (choice === undefined || probabilities === undefined || confidence === undefined) {
+        return { ok: false, reason: `bad-choice:${id}` };
+      }
+      answers[id] = { type: 'choice', choice, probabilities, confidence };
+      continue;
+    }
+    if (a.type === 'score') {
+      const score = finiteNumber(a.score);
+      const probabilities = parseProbabilities(a.probabilities);
+      const confidence = unitNumber(a.confidence);
+      if (score === undefined || score < 0 || probabilities === undefined || confidence === undefined) {
+        return { ok: false, reason: `bad-score:${id}` };
+      }
+      answers[id] = { type: 'score', score, probabilities, confidence };
+      continue;
+    }
+    return { ok: false, reason: `unknown-answer-type:${id}` };
+  }
+  return { ok: true, answers, model, usage: { inputTokens, outputTokens } };
+}
+
+/* ── P0-1: EPR diagnostic-command gate ── */
+
+export const DIAGNOSTIC_OUTPUT_MIN_NOUL = 0.6;
+
+const DIAGNOSTIC_GATE_QUESTIONS: Record<string, JevQuestion> = {
+  cmd_kind: {
+    type: 'choice',
+    instructions: 'What kind of shell command is this?',
+    criteria: {
+      build_test_run: 'Runs a build, test, lint, or typecheck pipeline whose output is repetitive diagnostic log lines (pass/fail, errors, warnings)',
+      install_deps: 'Installs or updates dependencies (npm/pip/cargo fetch); output is progress bars and version lists',
+      server_watch: 'Starts a long-running server, watcher, or REPL that stays in the foreground',
+      source_inspection: 'Prints or searches source/config (cat, ls, grep, git log, diff)',
+      other: 'None of the above',
+    },
+  },
+  diagnostic_output: {
+    type: 'noul',
+    instructions: 'Will this command produce repetitive test/build diagnostic log output (rather than conversational or interactive output)?',
+  },
+};
+
+export function diagnosticGateRequest(command: string): JevRequest {
+  return { state: { command }, questions: DIAGNOSTIC_GATE_QUESTIONS };
+}
+
+export interface DiagnosticGateVerdict {
+  readonly hit: boolean;
+  readonly reason: string;
+  readonly confidence: number | null;
+  readonly choice: string | null;
+  readonly noul: number | null;
+}
+export function evaluateDiagnosticGate(
+  answers: Record<string, JevAnswer>,
+  minConfidence: number,
+): DiagnosticGateVerdict {
+  const kind = answerOf(answers, 'cmd_kind', 'choice');
+  const output = answerOf(answers, 'diagnostic_output', 'noul');
+  if (kind === undefined || output === undefined) {
+    return { hit: false, reason: 'missing-answer', confidence: null, choice: null, noul: null };
+  }
+  if (kind.choice !== 'build_test_run') {
+    return { hit: false, reason: `not-build-test:${kind.choice}`, confidence: kind.confidence, choice: kind.choice, noul: output.noul };
+  }
+  if (kind.confidence < minConfidence) {
+    return { hit: false, reason: 'low-confidence', confidence: kind.confidence, choice: kind.choice, noul: output.noul };
+  }
+  if (output.noul < DIAGNOSTIC_OUTPUT_MIN_NOUL) {
+    return { hit: false, reason: 'non-diagnostic-output', confidence: kind.confidence, choice: kind.choice, noul: output.noul };
+  }
+  return { hit: true, reason: 'hit', confidence: kind.confidence, choice: kind.choice, noul: output.noul };
+}
+
+/** Flip semantics: jev judges first, the regex list decides only when jev produced no usable answer
+ * (failure, malformed, below gate). A confident rejection outranks a regex match. */
+export function isDiagnosticGateUnanswered(verdict: DiagnosticGateVerdict): boolean {
+  return verdict.reason === 'missing-answer' || verdict.reason === 'low-confidence';
+}
+
+/* ── P0-2: settlement-notice relevance ranking ── */
+
+/** Stricter than the global default: settlement text is mostly Chinese while English is jev's primary
+ * training language, so the initial gate starts at 0.7 and calibrates from jev.jsonl. */
+export const NOTICE_RANK_MIN_CONFIDENCE = 0.7;
+const RANK_SCORE_WEIGHT = 0.6;
+
+const RANK_LEVELS = [
+  'Routine completion; the master agent can check it later',
+  'The master agent should be aware; it affects planning',
+  'Reports a failure, error, or blocked state needing immediate attention',
+] as const;
+
+export function noticeRankRequest(input: {
+  inProgressTodos: readonly string[];
+  notices: readonly string[];
+}): JevRequest {
+  const questions: Record<string, JevQuestion> = {};
+  for (let i = 0; i < input.notices.length; i++) {
+    // Question keys are NOT sent to the model: identical instructions would collapse every notice into one.
+    questions[`notice_${i}_rank`] = {
+      type: 'score',
+      instructions: `How urgently does the master agent need to see settlements[${i}] right now, given in_progress_todos?`,
+      criteria: RANK_LEVELS,
+    };
+    questions[`notice_${i}_fail`] = {
+      type: 'noul',
+      instructions: `Does settlements[${i}] report a failure, error, or blocked state?`,
+    };
+  }
+  return {
+    state: {
+      in_progress_todos: input.inProgressTodos,
+      settlements: input.notices,
+    },
+    questions,
+  };
+}
+
+/** A settlement whose fail-noul clears this is pinned to the front regardless of relevance score:
+ * score noise on CJK reordered the same failure notice beyond the cap of shown notices. */
+const NOTICE_FAIL_PIN_THRESHOLD = 0.7;
+
+/**
+ * Display order: pinned failures first, then descending composed relevance (stable on ties -> arrival
+ * order); the per-item confidence gate sinks an item to the routine bucket instead of voiding the
+ * batch, and all items gated -> null. The fail pin ignores the score gate: noul answers carry no
+ * confidence field and failure visibility is the safety property.
+ */
+export function composeNoticeRanking(
+  noticeCount: number,
+  answers: Record<string, JevAnswer>,
+  minConfidence: number,
+): number[] | null {
+  const entries: Array<{ pin: number; value: number; index: number }> = [];
+  let answered = 0;
+  for (let i = 0; i < noticeCount; i++) {
+    const rank = answerOf(answers, `notice_${i}_rank`, 'score');
+    const fail = answerOf(answers, `notice_${i}_fail`, 'noul');
+    if (rank === undefined || fail === undefined) return null;
+    const gated = rank.confidence < minConfidence;
+    if (!gated) answered++;
+    const normalizedScore = rank.score / Math.max(1, RANK_LEVELS.length - 1);
+    entries.push({
+      pin: fail.noul >= NOTICE_FAIL_PIN_THRESHOLD ? 1 : 0,
+      value: gated ? 0 : RANK_SCORE_WEIGHT * normalizedScore + (1 - RANK_SCORE_WEIGHT) * fail.noul,
+      index: i,
+    });
+  }
+  if (answered === 0) return null;
+  entries.sort((a, b) => (b.pin - a.pin) || (b.value - a.value) || (a.index - b.index));
+  return entries.map((entry) => entry.index);
+}
+
+/* ── P0-3: OBS excerpt window candidates (head/tail halves miss the middle) ── */
+
+export type ExcerptWindowId = 'first_signal' | 'densest' | 'mid';
+
+export interface ExcerptWindow {
+  readonly id: ExcerptWindowId;
+  readonly label: string;
+  readonly text: string;
+}
+
+interface LineWindow {
+  readonly text: string;
+  readonly bytes: number;
+  readonly signalCount: number;
+}
+
+function buildLineWindow(lines: readonly string[], start: number, budgetBytes: number, signalLines: ReadonlySet<number>): LineWindow | null {
+  const selected: string[] = [];
+  let bytes = 0;
+  let signalCount = 0;
+  for (let i = start; i < lines.length; i++) {
+    const line = lines[i]!;
+    const lineBytes = Buffer.byteLength(line, 'utf8') + 1; // +1 newline
+    if (bytes + lineBytes > budgetBytes) {
+      if (selected.length === 0) return null; // anchor line alone exceeds the budget
+      break;
+    }
+    selected.push(line);
+    bytes += lineBytes;
+    if (signalLines.has(i)) signalCount++;
+  }
+  if (selected.length === 0) return null;
+  return { text: selected.join('\n'), bytes, signalCount };
+}
+
+/** Code-owned middle-window candidates for a packed observation: failure-signal windows (first hit,
+ * densest cluster) when present, plus a plain mid-output window ALWAYS offered, so jev judges every
+ * packed output — including logs whose failure lines the English FAILURE_SIGNAL regex cannot see. */
+export function buildExcerptWindows(text: string, halfBudgetBytes: number): ExcerptWindow[] {
+  if (halfBudgetBytes <= 0) return [];
+  const lines = text.split('\n');
+  const signalLines = new Set<number>();
+  for (let i = 0; i < lines.length; i++) {
+    if (FAILURE_SIGNAL.test(lines[i]!)) signalLines.add(i);
+  }
+
+  const out: ExcerptWindow[] = [];
+  const seen = new Set<string>();
+
+  if (signalLines.size > 0) {
+    const first = Math.min(...signalLines);
+    const firstWindow = buildLineWindow(lines, Math.max(0, first - 2), halfBudgetBytes, signalLines);
+    if (firstWindow !== null && !seen.has(firstWindow.text)) {
+      seen.add(firstWindow.text);
+      out.push({ id: 'first_signal', label: 'first failure-signal region', text: firstWindow.text });
+    }
+
+    let best: LineWindow | null = null;
+    for (const anchor of signalLines) {
+      const window = buildLineWindow(lines, anchor, halfBudgetBytes, signalLines);
+      if (window === null) continue;
+      if (best === null || window.signalCount > best.signalCount) best = window;
+    }
+    if (best !== null && !seen.has(best.text)) {
+      seen.add(best.text);
+      out.push({ id: 'densest', label: 'densest failure-signal region', text: best.text });
+    }
+  }
+
+  const midAnchor = Math.min(Math.floor(lines.length / 2), Math.max(0, lines.length - 1));
+  const midWindow = buildLineWindow(lines, midAnchor, halfBudgetBytes, signalLines);
+  if (midWindow !== null && !seen.has(midWindow.text)) {
+    out.push({ id: 'mid', label: 'middle region of the output', text: midWindow.text });
+  }
+  return out;
+}
+
+export function excerptPickRequest(
+  middleWindows: readonly ExcerptWindow[],
+  headExcerpt: string,
+  tailExcerpt: string,
+): JevRequest | null {
+  if (middleWindows.length === 0) return null;
+  const criteria: Record<string, string> = {
+    keep_head_tail: 'The existing head and tail excerpts are already the most informative; keep them',
+  };
+  const excerpts: Record<string, string> = { head_excerpt: headExcerpt, tail_excerpt: tailExcerpt };
+  for (const window of middleWindows) {
+    criteria[window.id] = `${window.label}: excerpt from the middle of the output`;
+    excerpts[window.id] = window.text;
+  }
+  return {
+    state: { excerpts },
+    questions: {
+      window: {
+        type: 'choice',
+        instructions: 'A large tool output was replaced by a placeholder keeping two short excerpts. Which excerpt set would most help a coding agent locate the problem without recalling the full text?',
+        criteria,
+      },
+    },
+  };
+}
+
+export function evaluateExcerptPick(
+  answers: Record<string, JevAnswer>,
+  minConfidence: number,
+): ExcerptWindowId | null {
+  const picked = answerOf(answers, 'window', 'choice');
+  if (picked === undefined) return null;
+  if (picked.confidence < minConfidence) return null;
+  return picked.choice === 'first_signal' || picked.choice === 'densest' || picked.choice === 'mid'
+    ? picked.choice
+    : null;
+}
+
+/** Local privacy gate for the excerpt-pick request: its state is sent for EVERY packed output — a path
+ *  the EPR secret gate never covers — so any credential-shaped text keeps the whole request local. */
+export function excerptAskIsSafe(
+  middleWindows: readonly ExcerptWindow[],
+  headExcerpt: string,
+  tailExcerpt: string,
+): boolean {
+  const parts = [headExcerpt, tailExcerpt, ...middleWindows.map((w) => w.text)];
+  return !parts.some((part) => containsLikelySecret(part));
+}
+
+/* ── P0-4: settlement attribution check ─────────────────────────── */
+
+/** Noul answers carry no confidence field (unlike choice/score), so this use case gates on the noul
+ *  probabilities themselves via dedicated constants, like DIAGNOSTIC_OUTPUT_MIN_NOUL. */
+const SETTLE_MATCH_MIN_NOUL = 0.6;
+const SETTLE_FINAL_MIN_NOUL = 0.6;
+
+export type SettleNullVerdict = 'silent' | 'attribution-suspect' | 'extraction-failed';
+
+export function settleVerdictRequest(input: { description: string; tail: string }): JevRequest {
+  return {
+    state: { task: input.description, transcriptTail: input.tail },
+    questions: {
+      tail_matches_task: {
+        type: 'noul',
+        instructions: 'Is this transcript tail from a session working on the described task? Answer false only when the tail is clearly about a different task or conversation.',
+        criteria: {
+          true: 'The tail discusses, works on, or reports on the described task',
+          false: 'The tail is about an unrelated task or a different conversation',
+        },
+      },
+      tail_has_final_answer: {
+        type: 'noul',
+        instructions: 'Does the transcript tail end with (or contain) a complete final answer or report for the task, rather than only intermediate tool exchanges?',
+        criteria: {
+          true: 'A complete final answer/report is present',
+          false: 'Only intermediate steps, questions, or tool exchanges — no final answer',
+        },
+      },
+    },
+  };
+}
+/** Compose the null-closing verdict. null = unanswered (jev off / failed / wrong shapes): callers
+ *  fall back to deterministic signals and the legacy wording, so jev-off stays byte-identical. */
+export function evaluateSettleVerdict(answers: Record<string, JevAnswer>): SettleNullVerdict | null {
+  const match = answerOf(answers, 'tail_matches_task', 'noul');
+  const fin = answerOf(answers, 'tail_has_final_answer', 'noul');
+  if (match === undefined || fin === undefined) return null;
+  if (match.noul < SETTLE_MATCH_MIN_NOUL) return 'attribution-suspect';
+  if (fin.noul >= SETTLE_FINAL_MIN_NOUL) return 'extraction-failed';
+  return 'silent';
+}
+
+/** Privacy gate shared with EPR: never ship credential-shaped tails off-host. */
+export function settleAskIsSafe(tail: string): boolean {
+  return !containsLikelySecret(tail);
+}

package/src/ledger.ts

@@ -1,24 +1,20 @@
 /**
  * Disposal ledger shared by HMR and session shutdown (D80⑤ + D79).
  *
- * HMR partial reload can skip old fiber effect disposers, so process-level resources
- * such as intervals, pipe servers, and watchers would leak without compensation.
- * Core modules register those resources by module key; reload disposes matching keys,
- * while session_shutdown disposes everything.
- *
- * D79 reuses this mechanism for pi-surface registration cleanup; logical keys need not
- * be file paths. The ledger stays dependency-free and connects through bootstrap/index.
+ * HMR partial reload can skip old fiber effect disposers, so process-level resources (intervals, pipe
+ * servers, watchers) would leak without compensation. Modules register those resources by module key;
+ * reload disposes matching keys, session_shutdown disposes everything. D79 reuses the same mechanism
+ * for pi-surface registration cleanup, where keys need not be file paths.
  */
 
 import { fileURLToPath } from 'node:url';
 
-/** Normalize file URLs and paths to comparable absolute keys for HMR matching. */
-export function normalizeModuleKey(spec: string): string {
+function normalizeModuleKey(spec: string): string {
   let s = String(spec);
   try {
     if (s.startsWith('file://')) s = fileURLToPath(s);
   } catch {
-    /* Keep malformed URLs unchanged so disposal can still use the caller's key. */
+    // Malformed URL: keep the caller's key so disposal still matches.
   }
   return s.replace(/\\/g, '/');
 }
@@ -27,7 +23,7 @@ export class DisposeLedger {
   /** LIFO order matches Cordis effect disposal semantics. */
   private order: Array<{ key: string; dispose: () => void }> = [];
 
-  /** Register a resource and return cancellation so self-disposal cannot run twice. */
+  /** Register a resource; the returned cancellation makes self-disposal a no-op. */
   add(spec: string, dispose: () => void): () => void {
     const entry = { key: normalizeModuleKey(spec), dispose };
     this.order.push(entry);
@@ -37,27 +33,23 @@ export class DisposeLedger {
     };
   }
 
-  /** HMR compensation disposes only matching keys in LIFO order. */
   disposeKey(spec: string | string[]): number {
-    const keys = new Set((Array.isArray(spec) ? spec : [spec]).map(normalizeModuleKey));
+    const keys = (Array.isArray(spec) ? spec : [spec]).map(normalizeModuleKey);
     let n = 0;
     for (let i = this.order.length - 1; i >= 0; i--) {
-      if (keys.has(this.order[i].key)) {
-        const { dispose } = this.order[i];
-        this.order.splice(i, 1);
-        try { dispose(); } catch { /* Compensation failures are non-fatal. */ }
-        n++;
-      }
+      if (!keys.includes(this.order[i]!.key)) continue;
+      const { dispose } = this.order.splice(i, 1)[0]!;
+      try { dispose(); } catch { /* Compensation must never abort the reload. */ }
+      n++;
     }
     return n;
   }
 
-  /** Dispose every entry in LIFO order during session_shutdown. */
   disposeAll(): number {
     let n = 0;
     while (this.order.length > 0) {
       const { dispose } = this.order.pop()!;
-      try { dispose(); } catch { /* Compensation failures are non-fatal. */ }
+      try { dispose(); } catch { /* Reload/shutdown must survive a broken disposer. */ }
       n++;
     }
     return n;