pi-pier 0.2.7 → 0.3.1

package/src/compact-economics-core.ts

@@ -0,0 +1,328 @@
+/**
+ * D100 Online Context Compact economics & feasibility core: pure decision-making, request horizon
+ * estimation, cache debt tracking and native compaction feasibility preflights — no dependencies
+ * except pi's public cut-point helper.
+ */
+
+import { findCutPoint, sessionEntryToContextMessages, type SessionEntry } from '@earendil-works/pi-coding-agent';
+
+interface CompactionEconomics {
+  readonly remainingRequestScale: number;
+  readonly remainingRequestStddevK: number;
+  readonly windowReserveTokens: number;
+  readonly firstCompactionRequestScale: number;
+  readonly subsequentCompactionMargin: number;
+}
+
+export const DEFAULT_COMPACTION_ECONOMICS: CompactionEconomics = Object.freeze({
+  remainingRequestScale: 1.0,
+  remainingRequestStddevK: 0.0,
+  windowReserveTokens: 16_384,
+  firstCompactionRequestScale: 2.0,
+  subsequentCompactionMargin: 1.5,
+});
+
+/**
+ * Token-account cache ratio: a compaction request re-reads the whole context once (writeTokens), so
+ * breakeven = writeTokens / savingTokens ⇔ ratio 2. This is the `auto` fallback when no usable cache
+ * pricing exists, and a floor: ratio ≤ 1 would zero the incremental cost and compact even on the last
+ * boundary with nothing left to amortize.
+ */
+export const TOKEN_ACCOUNT_CACHE_RATIO = 2.0;
+
+/** Provider-family `auto` fallbacks (implicit-cache families without a write SKU). */
+const PROVIDER_FAMILY_CACHE_RATIOS: Readonly<Record<string, number>> = Object.freeze({
+  gemini: 4,
+  grok: 10,
+  deepseek: 10,
+});
+
+type CompactionReason =
+  | 'economic'
+  | 'window_protection'
+  | 'deferred_economic'
+  | 'deferred_subsequent_margin'
+  | 'deferred_carried_debt'
+  | 'horizon_unavailable'
+  | 'cache_ratio_unavailable'
+  | 'native_not_compactable'
+  | 'failure_backoff'
+  | 'non_positive_saving';
+
+interface RequestHorizonEstimate {
+  readonly requestsPerBoundaryMean: number;
+  readonly requestsPerBoundaryLowerBound: number;
+  readonly unboundedExpectedRemainingRequests: number;
+  readonly windowRequestUpperBound: number | null;
+  readonly expectedRemainingRequests: number;
+}
+
+export interface CompactionDecision {
+  readonly writeTokens: number;
+  readonly archiveTokens: number;
+  readonly memoTokens: number;
+  readonly contextTokens: number;
+  readonly expectedRemainingRequests: number | null;
+  readonly breakevenRequests: number | null;
+  readonly effectiveHorizonRequests: number | null;
+  readonly remainingBoundaries: number;
+  readonly cacheWriteReadRatio: number | null;
+  readonly incrementalCacheCostRatio: number | null;
+  readonly priorCompactionCount: number;
+  readonly carriedDebtTokens: number;
+  readonly cacheDebtRepaymentTokens: number;
+  readonly compact: boolean;
+  readonly reason: CompactionReason;
+}
+
+const MINIMUM_VARIANCE_SAMPLES = 3;
+const SMALL_SAMPLE_SCALE = 0.5;
+/** Retained boundary-request sample cap so the mean tracks recent pacing. */
+export const MAX_BOUNDARY_SAMPLES = 16;
+
+export function estimateRemainingRequests(input: {
+  readonly completedBoundaryRequestCounts: readonly number[];
+  readonly remainingBoundaries: number;
+  readonly scale: number;
+  readonly standardDeviationK: number;
+  readonly contextTokens: number;
+  readonly contextWindowTokens: number | null;
+  readonly averageContextTokenIncrement: number | null;
+}): RequestHorizonEstimate {
+  const counts = input.completedBoundaryRequestCounts;
+  const mean = counts.reduce((total, count) => total + count, 0) / Math.max(1, counts.length);
+  let lowerBound = mean;
+  if (input.standardDeviationK !== 0) {
+    if (counts.length < MINIMUM_VARIANCE_SAMPLES) {
+      lowerBound *= SMALL_SAMPLE_SCALE;
+    } else {
+      const variance = counts.reduce((total, count) => total + (count - mean) ** 2, 0);
+      const deviation = Math.sqrt(variance / (counts.length - 1));
+      lowerBound = Math.max(0, mean - input.standardDeviationK * deviation);
+    }
+  }
+
+  const unboundedExpectedRemainingRequests =
+    1 + Math.floor(lowerBound * Math.max(0, input.remainingBoundaries) * input.scale);
+  const windowRequestUpperBound =
+    input.contextWindowTokens === null ||
+    input.averageContextTokenIncrement === null ||
+    input.averageContextTokenIncrement <= 0
+      ? null
+      : Math.max(
+          0,
+          Math.floor((input.contextWindowTokens - input.contextTokens) / input.averageContextTokenIncrement),
+        );
+
+  return {
+    requestsPerBoundaryMean: mean,
+    requestsPerBoundaryLowerBound: lowerBound,
+    unboundedExpectedRemainingRequests,
+    windowRequestUpperBound,
+    expectedRemainingRequests:
+      windowRequestUpperBound === null
+        ? unboundedExpectedRemainingRequests
+        : Math.min(unboundedExpectedRemainingRequests, windowRequestUpperBound),
+  };
+}
+
+export function decideCompaction(input: {
+  readonly writeTokens: number;
+  readonly archiveTokens: number;
+  readonly memoTokens: number;
+  readonly contextTokens: number;
+  readonly completedBoundaryRequestCounts: readonly number[] | null;
+  readonly remainingBoundaries: number;
+  readonly averageContextTokenIncrement: number | null;
+  readonly contextWindowTokens: number | null;
+  readonly priorCompactionCount: number;
+  readonly carriedDebtTokens: number;
+  readonly cacheDebtRepaymentTokens: number;
+  readonly cacheWriteReadRatio: number | null;
+  readonly economics?: CompactionEconomics;
+}): CompactionDecision {
+  const economics = input.economics ?? DEFAULT_COMPACTION_ECONOMICS;
+  const horizon = input.completedBoundaryRequestCounts === null ? null : estimateRemainingRequests({
+    completedBoundaryRequestCounts: input.completedBoundaryRequestCounts,
+    remainingBoundaries: input.remainingBoundaries,
+    scale: economics.remainingRequestScale,
+    standardDeviationK: economics.remainingRequestStddevK,
+    contextTokens: input.contextTokens,
+    contextWindowTokens: input.contextWindowTokens,
+    averageContextTokenIncrement: input.averageContextTokenIncrement,
+  });
+
+  const savingTokens = input.archiveTokens - input.memoTokens;
+  const compressible = savingTokens > 0;
+  const incrementalCacheCostRatio =
+    input.cacheWriteReadRatio === null ? null : Math.max(0, input.cacheWriteReadRatio - 1);
+  const incrementalWriteCost = incrementalCacheCostRatio === null
+    ? null
+    : input.writeTokens * incrementalCacheCostRatio;
+
+  const breakevenRequests = compressible && incrementalWriteCost !== null
+    ? incrementalWriteCost / savingTokens
+    : null;
+  const combinedBreakevenRequests = compressible && incrementalWriteCost !== null
+    ? (input.carriedDebtTokens + incrementalWriteCost) / savingTokens
+    : null;
+
+  const firstCompaction = input.priorCompactionCount === 0;
+  const horizonRequests = horizon?.expectedRemainingRequests ?? null;
+  // The first-compaction relaxation absorbs cold-start sample noise, but only when work remains: with
+  // zero remaining boundaries the horizon is 1, and scaling it to 2 would burn a full-context summary.
+  const relaxFirstCompaction = firstCompaction && input.remainingBoundaries > 0;
+  const effectiveHorizonRequests = horizon === null
+    ? null
+    : relaxFirstCompaction
+      ? Math.min(
+          horizon.expectedRemainingRequests * economics.firstCompactionRequestScale,
+          horizon.windowRequestUpperBound ?? Number.POSITIVE_INFINITY,
+        )
+      : horizon.expectedRemainingRequests;
+
+  const windowProtection =
+    input.contextWindowTokens !== null &&
+    input.contextTokens >= input.contextWindowTokens - economics.windowReserveTokens;
+  const baseEconomic =
+    horizonRequests !== null &&
+    horizonRequests > 0 &&
+    breakevenRequests !== null &&
+    breakevenRequests <= horizonRequests;
+  const firstEconomic =
+    firstCompaction &&
+    effectiveHorizonRequests !== null &&
+    effectiveHorizonRequests > 0 &&
+    breakevenRequests !== null &&
+    breakevenRequests <= effectiveHorizonRequests;
+  const subsequentMarginOpen =
+    !firstCompaction &&
+    horizonRequests !== null &&
+    breakevenRequests !== null &&
+    breakevenRequests * economics.subsequentCompactionMargin <= horizonRequests;
+  const carriedDebtGateOpen =
+    !firstCompaction &&
+    horizonRequests !== null &&
+    combinedBreakevenRequests !== null &&
+    combinedBreakevenRequests <= horizonRequests;
+
+  const economic = firstCompaction ? firstEconomic : baseEconomic && subsequentMarginOpen && carriedDebtGateOpen;
+  const compact = compressible && (windowProtection || economic);
+
+  // Ordered guards: first hit wins, so the tail entry is the fallback.
+  const reason = ([
+    ['non_positive_saving', !compressible],
+    ['window_protection', windowProtection],
+    ['economic', economic],
+    ['horizon_unavailable', horizon === null],
+    ['cache_ratio_unavailable', breakevenRequests === null],
+    ['deferred_subsequent_margin', !firstCompaction && baseEconomic && !subsequentMarginOpen],
+    ['deferred_carried_debt', !firstCompaction && baseEconomic && !carriedDebtGateOpen],
+    ['deferred_economic', true],
+  ] as Array<[CompactionReason, boolean]>).find(([, hit]) => hit)![0];
+
+  return {
+    writeTokens: input.writeTokens,
+    archiveTokens: input.archiveTokens,
+    memoTokens: input.memoTokens,
+    contextTokens: input.contextTokens,
+    expectedRemainingRequests: horizonRequests,
+    breakevenRequests,
+    effectiveHorizonRequests,
+    remainingBoundaries: input.remainingBoundaries,
+    cacheWriteReadRatio: input.cacheWriteReadRatio,
+    incrementalCacheCostRatio,
+    priorCompactionCount: input.priorCompactionCount,
+    carriedDebtTokens: input.carriedDebtTokens,
+    cacheDebtRepaymentTokens: input.cacheDebtRepaymentTokens,
+    compact,
+    reason,
+  };
+}
+
+/**
+ * Resolve the cache write/read cost ratio for compaction decisions, in order: explicit numeric config
+ * (as-is, e.g. 12.5 for Anthropic-style pricing), model cost metadata (write/read, or input/cacheRead
+ * when cache writes are billed at the input price), provider-family fallback (gemini ≈ 4, grok/deepseek
+ * ≈ 10), then TOKEN_ACCOUNT_CACHE_RATIO. Returns null only for an explicitly invalid numeric config:
+ * `auto` must never resolve to null, since a zero-price table means "no local cacheWrite SKU", not
+ * "no cache", and null would disable OCC for every model in actual use.
+ */
+export function resolveCacheRatioFromCost(
+  ratioConfig: number | 'auto',
+  cost?: { input?: number; cacheRead?: number; cacheWrite?: number } | null,
+  identity?: { provider?: string; modelId?: string } | null,
+): number | null {
+  if (typeof ratioConfig === 'number') {
+    return Number.isFinite(ratioConfig) && ratioConfig >= 0 ? ratioConfig : null;
+  }
+
+  if (cost) {
+    const read = cost.cacheRead ?? 0;
+    const write = cost.cacheWrite ?? 0;
+    const input = cost.input ?? 0;
+    if (read > 0 && write > 0) return write / read;
+    if (read > 0 && write === 0 && input > 0) return input / read;
+  }
+
+  const familyKey = `${identity?.provider ?? ''}/${identity?.modelId ?? ''}`.toLowerCase();
+  for (const [family, ratio] of Object.entries(PROVIDER_FAMILY_CACHE_RATIOS)) {
+    if (familyKey.includes(family)) return ratio;
+  }
+  return TOKEN_ACCOUNT_CACHE_RATIO;
+}
+
+function compactionMessageCount(entries: readonly SessionEntry[], startIndex: number, endIndex: number): number {
+  let count = 0;
+  for (let index = startIndex; index < endIndex; index++) {
+    const entry = entries[index];
+    if (entry && entry.type !== 'compaction' && sessionEntryToContextMessages(entry).length > 0) count++;
+  }
+  return count;
+}
+
+/** Appends the abort marker pi's cut-point search expects after our intentional abort. */
+function branchAfterAbort(entries: readonly SessionEntry[]): SessionEntry[] {
+  return [
+    ...entries,
+    {
+      type: 'message',
+      id: 'pi-herdr-online-context-compact-abort-marker',
+      parentId: entries.at(-1)?.id ?? null,
+      timestamp: new Date(0).toISOString(),
+      message: {
+        role: 'assistant',
+        content: [],
+        api: 'pi-herdr',
+        provider: 'pi-herdr',
+        model: 'aborted',
+        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+        stopReason: 'aborted',
+        timestamp: 0,
+      },
+    } as SessionEntry,
+  ];
+}
+
+/** Would pi's own compaction find history to summarize on this branch? OCC must not abort otherwise. */
+export function nativeCompactionFeasible(entries: readonly SessionEntry[], keepRecentTokens: number): boolean {
+  if (!Array.isArray(entries) || entries.length === 0) return false;
+  const path = branchAfterAbort(entries);
+  let startIndex = 0;
+  for (let index = path.length - 1; index >= 0; index--) {
+    const entry = path[index];
+    if (entry?.type !== 'compaction') continue;
+    const keptIndex = path.findIndex((item) => item.id === (entry as { firstKeptEntryId?: string }).firstKeptEntryId);
+    startIndex = keptIndex >= 0 ? keptIndex : index + 1;
+    break;
+  }
+
+  const cut = findCutPoint(path, startIndex, path.length, keepRecentTokens);
+  const historyEnd = cut.isSplitTurn ? cut.turnStartIndex : cut.firstKeptEntryIndex;
+  const historyMessages = historyEnd > startIndex ? compactionMessageCount(path, startIndex, historyEnd) : 0;
+  const prefixMessages =
+    cut.isSplitTurn && cut.turnStartIndex >= 0
+      ? compactionMessageCount(path, cut.turnStartIndex, cut.firstKeptEntryIndex)
+      : 0;
+  return historyMessages > 0 || prefixMessages > 0;
+}

package/src/config-catalog-core.ts

@@ -0,0 +1,332 @@
+/**
+ * D104 config catalog core (pure).
+ *
+ * Single source of truth for the four pier configuration planes: knob descriptors, effective-value
+ * provenance (env > workspace > user > default) and rendering for `/pier-config show|check|doc`. The
+ * `env` plane derives from the `PIER_OPTIONS` registry, so it cannot disagree with the runtime readers;
+ * no I/O here (config-command.ts does the reading) and test/config-catalog.test.ts guards the mirror.
+ */
+
+import { PIER_OPTIONS } from './pier-options.ts';
+
+export type ConfigPlaneId = 'efficiency' | 'roles' | 'pi' | 'env';
+
+export type ConfigKind = 'boolean' | 'number' | 'string' | 'enum';
+
+export interface ConfigKnob {
+  readonly plane: ConfigPlaneId;
+  /** Dotted path inside the plane's file, or the env var name for the `env` plane. */
+  readonly key: string;
+  readonly kind: ConfigKind;
+  readonly defaultValue?: string | number | boolean;
+  /** Highest-precedence env override for a file-plane knob. */
+  readonly envVar?: string;
+  /** Lower bound for numeric knobs (mirrors the runtime validator). */
+  readonly min?: number;
+  /** Historical spellings still accepted for an env knob (B10: canonical `PIER_*` first). */
+  readonly aliases?: readonly string[];
+  readonly impact: string;
+  readonly docRef?: string;
+  /** True when pier only reads the value (owned by pi / herdr). */
+  readonly readOnly?: boolean;
+}
+
+export interface ConfigPlane {
+  readonly id: ConfigPlaneId;
+  readonly title: string;
+  readonly owner: 'pier' | 'pi';
+  /** Human-facing path templates, in precedence order. */
+  readonly files: readonly string[];
+  readonly editHint: string;
+}
+
+export const CONFIG_PLANES: readonly ConfigPlane[] = Object.freeze([
+  {
+    id: 'efficiency',
+    title: 'Efficiency mechanisms (D100-D103)',
+    owner: 'pier',
+    files: ['<workspace>/.pi-herdr/config.json', '~/.pi/agent/herdr-pi/config.json', 'PI_HERDR_* env'],
+    editHint: 'Edit the workspace or user JSON (env wins); see docs/efficiency-trial.md',
+  },
+  {
+    id: 'roles',
+    title: 'Role profiles (D82/D11)',
+    owner: 'pier',
+    files: ['<workspace>/.pi-herdr/roles/<name>.json', '~/.pi/agent/herdr-pi/roles/<name>.json', 'builtin src/roles/'],
+    editHint: 'Add or edit a role JSON; builtin names (master/worker-default) cannot be overridden',
+  },
+  {
+    id: 'pi',
+    title: "Pi's own settings (read-only here)",
+    owner: 'pi',
+    files: ['~/.pi/agent/settings.json', '<trusted-project>/.pi/settings.json'],
+    editHint: 'Use pi\'s /settings for everything except the OCC-relevant compaction.* keys',
+  },
+  {
+    id: 'env',
+    title: 'Runtime policy env (PIER_* / PI_HERDR_*)',
+    owner: 'pier',
+    files: ['process environment (per-process, no file)'],
+    editHint: 'Export the variable before starting pi; it applies to new processes only',
+  },
+] as const);
+
+/** Efficiency knobs: mirrors schemas/efficiency-config.schema.json (guarded by the catalog test). */
+const EFFICIENCY_KNOBS: readonly ConfigKnob[] = [
+  { plane: 'efficiency', key: 'onlineContextCompact.enabled', kind: 'boolean', defaultValue: false, envVar: 'PI_HERDR_COMPACT_ENABLE', impact: 'Todo-driven online compaction (OCC) master switch', docRef: 'docs/efficiency-trial.md' },
+  { plane: 'efficiency', key: 'onlineContextCompact.logEnabled', kind: 'boolean', defaultValue: false, envVar: 'PI_HERDR_COMPACT_LOG', impact: 'Write compact.jsonl decisions', docRef: 'docs/efficiency-trial.md' },
+  { plane: 'efficiency', key: 'onlineContextCompact.cacheWriteReadRatio', kind: 'string', defaultValue: 'auto', envVar: 'PI_HERDR_CACHE_RATIO', impact: 'KV cache write/read cost ratio; auto = model cost, then input/cacheRead, then provider family (gemini 4 / grok+deepseek 10), then token-account 2.0 — never disables OCC', docRef: 'docs/efficiency-trial.md' },
+  { plane: 'efficiency', key: 'onlineContextCompact.firstCompactionRequestScale', kind: 'number', defaultValue: 2.0, min: 1.0, impact: 'First-compaction horizon relaxation', docRef: 'docs/efficiency-trial.md' },
+  { plane: 'efficiency', key: 'onlineContextCompact.subsequentCompactionMargin', kind: 'number', defaultValue: 1.5, min: 1.0, impact: 'Safety margin required for later compactions', docRef: 'docs/efficiency-trial.md' },
+  { plane: 'efficiency', key: 'onlineContextCompact.keepRecentTokens', kind: 'number', defaultValue: 20000, min: 1000, impact: 'Native compaction tail window; inherited from pi unless set here', docRef: 'docs/configuration.md' },
+  { plane: 'efficiency', key: 'observationPack.enabled', kind: 'boolean', defaultValue: false, envVar: 'PI_HERDR_OBS_PACK_ENABLE', impact: 'Project large tool outputs as placeholders (observationPack)', docRef: 'docs/efficiency-trial.md' },
+  { plane: 'efficiency', key: 'observationPack.logEnabled', kind: 'boolean', defaultValue: false, envVar: 'PI_HERDR_OBS_PACK_LOG', impact: 'Write observation.jsonl packed/recall records', docRef: 'docs/efficiency-trial.md' },
+  { plane: 'efficiency', key: 'observationPack.thresholdBytes', kind: 'number', defaultValue: 10240, min: 1024, impact: 'Minimum output size before packing applies', docRef: 'docs/efficiency-trial.md' },
+  { plane: 'efficiency', key: 'observationPack.fullSends', kind: 'number', defaultValue: 2, min: 1, impact: 'Provider requests that keep the full text before packing', docRef: 'docs/efficiency-trial.md' },
+  { plane: 'efficiency', key: 'observationPack.recallChunkBytes', kind: 'number', defaultValue: 16384, min: 1024, impact: 'obs_recall page size', docRef: 'docs/efficiency-trial.md' },
+  { plane: 'efficiency', key: 'observationPack.excerptBytes', kind: 'number', defaultValue: 1024, min: 128, impact: 'Whole-line head/tail excerpt kept in the placeholder', docRef: 'docs/efficiency-trial.md' },
+  { plane: 'efficiency', key: 'evidencePreservingReducer.enabled', kind: 'boolean', defaultValue: false, envVar: 'PI_HERDR_REDUCER_ENABLE', impact: 'Reduce long bash diagnostic logs to a verified receipt (EPR)', docRef: 'docs/efficiency-trial.md' },
+  { plane: 'efficiency', key: 'evidencePreservingReducer.logEnabled', kind: 'boolean', defaultValue: false, envVar: 'PI_HERDR_REDUCER_LOG', impact: 'Write reducer.jsonl attempts and fallback reasons', docRef: 'docs/efficiency-trial.md' },
+  { plane: 'efficiency', key: 'evidencePreservingReducer.model', kind: 'string', envVar: 'PI_HERDR_REDUCER_MODEL', impact: 'Cheap model used for reduction (provider/model); defaults to the session model', docRef: 'docs/efficiency-trial.md' },
+  { plane: 'efficiency', key: 'evidencePreservingReducer.minBytes', kind: 'number', defaultValue: 4096, min: 512, impact: 'Minimum log size before reduction is attempted', docRef: 'docs/efficiency-trial.md' },
+  { plane: 'efficiency', key: 'evidencePreservingReducer.maxChars', kind: 'number', defaultValue: 600000, min: 1000, impact: 'Skip reduction above this log size', docRef: 'docs/efficiency-trial.md' },
+  { plane: 'efficiency', key: 'evidencePreservingReducer.maxOutputTokens', kind: 'number', defaultValue: 2048, min: 128, impact: 'Reduction output token budget', docRef: 'docs/efficiency-trial.md' },
+  { plane: 'efficiency', key: 'evidencePreservingReducer.timeoutMs', kind: 'number', defaultValue: 5000, min: 500, impact: 'Synchronous reduction budget; timeout falls back to the full log', docRef: 'docs/efficiency-trial.md' },
+  { plane: 'efficiency', key: 'evidencePreservingReducer.localOnly', kind: 'boolean', defaultValue: false, impact: 'Archive the raw log but never call a model', docRef: 'docs/efficiency-trial.md' },
+  { plane: 'efficiency', key: 'jev.enabled', kind: 'boolean', defaultValue: false, envVar: 'PIER_JEV_ENABLE', impact: 'Jev decision layer (System One classification) master switch; every call site fails open', docRef: 'docs/rfc-jev-integration.md' },
+  { plane: 'efficiency', key: 'jev.logEnabled', kind: 'boolean', defaultValue: false, envVar: 'PIER_JEV_LOG', impact: 'Write jev.jsonl question outcomes (no request/response bodies)', docRef: 'docs/rfc-jev-integration.md' },
+  { plane: 'efficiency', key: 'jev.baseUrl', kind: 'string', envVar: 'PIER_JEV_BASE_URL', impact: 'API root override (relay/gateway); default https://api.typesafe.ai', docRef: 'docs/rfc-jev-integration.md' },
+  { plane: 'efficiency', key: 'jev.model', kind: 'string', defaultValue: 'jev-1.13.0', envVar: 'PIER_JEV_MODEL', impact: 'Pinned versioned model id; aliases drift silently and skew tuned thresholds', docRef: 'docs/rfc-jev-integration.md' },
+  { plane: 'efficiency', key: 'jev.timeoutMs', kind: 'number', defaultValue: 2000, min: 500, envVar: 'PIER_JEV_TIMEOUT_MS', impact: 'Total per-call budget via AbortController hard kill', docRef: 'docs/rfc-jev-integration.md' },
+  { plane: 'efficiency', key: 'jev.minConfidence', kind: 'number', defaultValue: 0.6, min: 0, envVar: 'PIER_JEV_MIN_CONFIDENCE', impact: 'Minimum Choice/Score confidence to adopt an answer; below counts as unanswered', docRef: 'docs/rfc-jev-integration.md' },
+  { plane: 'efficiency', key: 'jev.apiKey', kind: 'string', envVar: 'PIER_JEV_API_KEY', impact: 'API key; PIER_JEV_API_KEY env > config value > TYPESAFE_API_KEY env', docRef: 'docs/rfc-jev-integration.md' },
+];
+
+/** Pi-owned keys pier only reads. */
+const PI_KNOBS: readonly ConfigKnob[] = [
+  { plane: 'pi', key: 'compaction.enabled', kind: 'boolean', impact: 'When false, OCC is disabled too (unless PI_HERDR_COMPACT_ENABLE=1)', docRef: 'docs/efficiency-trial.md', readOnly: true },
+  { plane: 'pi', key: 'compaction.keepRecentTokens', kind: 'number', impact: 'Inherited as the OCC retention window when not set in the efficiency config', docRef: 'docs/efficiency-trial.md', readOnly: true },
+];
+
+/** Runtime policy / behaviour env knobs, derived from the `PIER_OPTIONS` registry. */
+const ENV_KNOBS: readonly ConfigKnob[] = PIER_OPTIONS.map((option) => ({
+  plane: 'env' as const,
+  key: option.name,
+  kind: option.min === undefined ? ('string' as const) : ('number' as const),
+  defaultValue: option.min === undefined
+    ? (option.fallback === '' ? undefined : option.fallback)
+    : Number(option.fallback),
+  aliases: option.legacy ? [option.legacy] : undefined,
+  min: option.min,
+  impact: option.description,
+}));
+
+/** Every knob the catalog can resolve (roles is a per-file plane: its schema is the reference). */
+export const CONFIG_KNOBS: readonly ConfigKnob[] = Object.freeze([...EFFICIENCY_KNOBS, ...PI_KNOBS, ...ENV_KNOBS]);
+
+export function readDotted(obj: unknown, dotted: string): unknown {
+  let cursor: unknown = obj;
+  for (const part of dotted.split('.')) {
+    if (!cursor || typeof cursor !== 'object' || Array.isArray(cursor)) return undefined;
+    cursor = (cursor as Record<string, unknown>)[part];
+  }
+  return cursor;
+}
+
+/** Secret-shaped KEY names (not values). Deliberately narrower than a bare `token` match so that
+ *  legitimate keys like `compaction.keepRecentTokens` are still shown verbatim. */
+const SECRET_LIKE = /(api[_-]?key|apikey|authorization|bearer|access[_-]?token|client[_-]?secret|password|credential)/i;
+
+export function formatValue(value: unknown): string {
+  if (value === undefined) return '(unset)';
+  if (typeof value === 'string') return value === '' ? '""' : value;
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  if (value === null) return 'null';
+  return JSON.stringify(value);
+}
+
+export function redactValue(key: string, value: unknown): string {
+  if (SECRET_LIKE.test(key) && value !== undefined && value !== '') return '***';
+  return formatValue(value);
+}
+
+export type ConfigSource = 'env' | 'workspace' | 'user' | 'default' | 'pi';
+
+export interface ResolvedKnob {
+  readonly knob: ConfigKnob;
+  readonly value: string;
+  readonly source: ConfigSource;
+  readonly via?: string;
+  /** Set when a workspace layer exists but was ignored (untrusted project). */
+  readonly note?: string;
+}
+
+export interface RawConfigLayers {
+  readonly env?: Record<string, string | undefined>;
+  /** Parsed workspace efficiency config (untrusted layers are reported, never honored). */
+  readonly workspace?: unknown;
+  readonly user?: unknown;
+  readonly workspaceTrusted?: boolean;
+  /** Result of loadPiNativeCompactionSettings (pi-owned values pier reads). */
+  readonly piSettings?: { enabled?: boolean; keepRecentTokens?: number };
+}
+
+function resolveFileKnob(knob: ConfigKnob, layers: RawConfigLayers): ResolvedKnob {
+  const envRaw = knob.envVar ? (layers.env ?? {})[knob.envVar] : undefined;
+  if (envRaw !== undefined && envRaw !== '') return { knob, value: redactValue(knob.key, envRaw), source: 'env' };
+
+  const workspaceValue = readDotted(layers.workspace, knob.key);
+  const userValue = readDotted(layers.user, knob.key);
+  if (workspaceValue !== undefined) {
+    if (layers.workspaceTrusted) return { knob, value: redactValue(knob.key, workspaceValue), source: 'workspace' };
+    return userValue === undefined
+      ? { knob, value: redactValue(knob.key, knob.defaultValue), source: 'default', note: 'workspace value ignored (untrusted project)' }
+      : { knob, value: redactValue(knob.key, userValue), source: 'user', note: 'workspace layer ignored (untrusted project)' };
+  }
+  if (userValue !== undefined) return { knob, value: redactValue(knob.key, userValue), source: 'user' };
+  return { knob, value: redactValue(knob.key, knob.defaultValue), source: 'default' };
+}
+
+export function resolveConfigKnobs(layers: RawConfigLayers): ResolvedKnob[] {
+  const out = EFFICIENCY_KNOBS.map((knob) => resolveFileKnob(knob, layers));
+
+  // Effective-value rule from loadEfficiencyConfigFromDisk: pi's compaction.enabled=false
+  // disables OCC unless PI_HERDR_COMPACT_ENABLE forces it on.
+  const occ = out.find((e) => e.knob.key === 'onlineContextCompact.enabled');
+  const envForced = (layers.env?.PI_HERDR_COMPACT_ENABLE ?? '') !== '';
+  if (occ && occ.value === 'true' && layers.piSettings?.enabled === false && !envForced) {
+    out[out.indexOf(occ)] = { ...occ, value: 'false', note: 'pi compaction.enabled=false disables OCC (set PI_HERDR_COMPACT_ENABLE=1 to force)' };
+  }
+
+  for (const knob of PI_KNOBS) {
+    const raw = knob.key === 'compaction.enabled' ? layers.piSettings?.enabled : layers.piSettings?.keepRecentTokens;
+    out.push(raw === undefined
+      ? { knob, value: formatValue(undefined), source: 'pi', note: 'not set in pi settings' }
+      : { knob, value: redactValue(knob.key, raw), source: 'pi' });
+  }
+  return out;
+}
+
+/** Resolves the env plane: only catalog keys are ever read. */
+export function resolveEnvKnobs(env: Record<string, string | undefined> = {}): ResolvedKnob[] {
+  return ENV_KNOBS.map((knob) => {
+    // Same precedence as pierOption(): canonical first, then the historical spelling, empty = unset.
+    for (const name of [knob.key, ...(knob.aliases ?? [])]) {
+      const raw = env[name];
+      if (raw === undefined || raw === '') continue;
+      return { knob, value: redactValue(knob.key, raw), source: 'env' as const, ...(name === knob.key ? {} : { via: name }) };
+    }
+    return { knob, value: redactValue(knob.key, knob.defaultValue), source: 'default' as const };
+  });
+}
+
+export interface CheckReport {
+  readonly plane: ConfigPlaneId;
+  readonly ok: boolean;
+  readonly issues: readonly string[];
+}
+
+export function checkEnvKnobs(env: Record<string, string | undefined> = {}): string[] {
+  const issues: string[] = [];
+  for (const knob of ENV_KNOBS) {
+    if (knob.kind !== 'number') continue;
+    for (const name of [knob.key, ...(knob.aliases ?? [])]) {
+      const raw = env[name];
+      if (raw === undefined || raw === '') continue;
+      const parsed = Number.parseInt(raw, 10);
+      const min = knob.min ?? 0;
+      if (!Number.isFinite(parsed) || parsed < min) {
+        issues.push(`${name}="${raw}" is not a valid integer >= ${min} (runtime falls back to ${formatValue(knob.defaultValue)})`);
+      }
+    }
+  }
+  return issues;
+}
+
+function sourceLabel(entry: ResolvedKnob): string {
+  const base = entry.via ? `${entry.source} via ${entry.via}` : entry.source;
+  return entry.note ? `${base} (${entry.note})` : base;
+}
+
+export function summarizePlane(entries: readonly ResolvedKnob[]): string {
+  const changed = entries.filter((e) => e.source !== 'default');
+  if (changed.length === 0) return 'all defaults';
+  const bySource = new Map<ConfigSource, number>();
+  for (const e of changed) bySource.set(e.source, (bySource.get(e.source) ?? 0) + 1);
+  return `${changed.length} set (${[...bySource].map(([s, n]) => `${s} ${n}`).join(', ')})`;
+}
+
+export function renderIndex(lines: {
+  efficiency: readonly ResolvedKnob[];
+  pi: readonly ResolvedKnob[];
+  env: readonly ResolvedKnob[];
+  roleSummary: string;
+}): string[] {
+  const mechanism = (prefix: string): string =>
+    lines.efficiency.some((e) => e.knob.key === `${prefix}.enabled` && e.value === 'true') ? 'on' : 'off';
+  return [
+    'pier config — 4 planes, env > workspace > user > default',
+    `  efficiency  ${summarizePlane(lines.efficiency)} — OCC ${mechanism('onlineContextCompact')} / OBS ${mechanism('observationPack')} / EPR ${mechanism('evidencePreservingReducer')}`,
+    `  roles       ${lines.roleSummary}`,
+    `  pi          ${summarizePlane(lines.pi)} — OCC reads compaction.* only`,
+    `  env         ${summarizePlane(lines.env)}`,
+    '  show: /pier-config show <efficiency|roles|pi|env|all>   check: /pier-config check   report: /pier-config doc',
+  ];
+}
+
+export function renderPlane(entries: readonly ResolvedKnob[]): string[] {
+  const out: string[] = [];
+  for (const entry of entries) {
+    const { knob } = entry;
+    const from = knob.envVar && entry.source === 'env' ? ` (from ${knob.envVar})` : '';
+    const flags = [knob.readOnly ? 'read-only' : '', knob.docRef ?? ''].filter(Boolean).join('; ');
+    out.push(`  ${knob.key}${from} = ${entry.value}  [${sourceLabel(entry)}]${flags ? `  (${flags})` : ''}`);
+    out.push(`      ${knob.impact}`);
+  }
+  return out;
+}
+
+export function renderCheck(reports: readonly CheckReport[]): string[] {
+  const out: string[] = [];
+  for (const report of reports) {
+    out.push(`  ${report.ok ? 'ok  ' : 'FAIL'} ${report.plane}`);
+    for (const issue of report.issues) out.push(`      - ${issue}`);
+  }
+  return out;
+}
+
+export interface ReportMeta {
+  readonly generatedAt: string;
+  readonly cwd: string;
+  readonly workspaceTrusted: boolean;
+  readonly piVersion?: string;
+}
+
+export function renderReport(entries: readonly ResolvedKnob[], meta: ReportMeta): string {
+  const lines = [
+    '# pier config report',
+    '',
+    `- generated: ${meta.generatedAt}`,
+    `- cwd: ${meta.cwd}`,
+    `- workspace trusted: ${meta.workspaceTrusted}`,
+    ...(meta.piVersion ? [`- pi: ${meta.piVersion}`] : []),
+    '',
+    'Precedence: env > workspace (trusted) > user > default.',
+    '',
+  ];
+  const escape = (text: string): string => text.replace(/\|/g, '\\|');
+  for (const plane of CONFIG_PLANES) {
+    const planeEntries = entries.filter((e) => e.knob.plane === plane.id);
+    lines.push(`## ${plane.id} — ${plane.title}`, '', `Files: ${plane.files.map((f) => `\`${f}\``).join(' , ')}`, '', `> ${plane.editHint}`, '');
+    if (planeEntries.length === 0) {
+      lines.push('(no value-carrying knobs; per-file plane)', '');
+      continue;
+    }
+    lines.push('| key | value | source | impact |', '|---|---|---|---|');
+    for (const entry of planeEntries) {
+      lines.push(`| \`${entry.knob.key}\` | ${escape(entry.value)} | ${sourceLabel(entry)} | ${escape(entry.knob.impact)} |`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
+}