pi-pier 0.2.6 → 0.3.0

package/src/reducer-invoker.ts

@@ -0,0 +1,392 @@
+/**
+ * D102 Evidence-Preserving Reducer Invoker & Tool Result Handler.
+ *
+ * Implements:
+ *  - Interception of diagnostic command tool results from `bash`.
+ *  - Full untruncated output retrieval from Pi temporary files.
+ *  - P0 content-addressed archival of original source log before replacement.
+ *  - Secret pattern detection and project trust verification (security boundaries).
+ *  - Fast in-process model invocation with timeout protection (default 5s).
+ *  - Zero-tolerance byte-for-byte quotation validation against original source.
+ *  - Block-level content replacement (preserves write-lock warnings).
+ *  - Fail-open resilience: errors or validation failures transparently fallback to full text.
+ */
+
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { countLines } from './observation-core.ts';
+import {
+  containsLikelySecret,
+  DEFAULT_MAX_CHARS,
+  DEFAULT_MAX_OUTPUT_TOKENS,
+  DEFAULT_MIN_BYTES,
+  DEFAULT_TIMEOUT_MS,
+  extractLikelySecretMatch,
+  formatReceiptText,
+  fullOutputPathFromNotice,
+  isDiagnosticCommand,
+  mergeUsage,
+  reducerInputPrompt,
+  reducerInstructions,
+  sha256Hex,
+  validateReceipt,
+  type UsageLike,
+  type UsageTotals,
+} from './reducer-core.ts';
+import {
+  appendEfficiencyLog,
+  efficiencyLogPath,
+  readBashFullOutput,
+  reducerObjectPath,
+  resolveSessionRoot,
+  storeContentAddressedObject,
+} from './efficiency-store.ts';
+import type { EvidencePreservingReducerConfig } from './efficiency-config-core.ts';
+import { diagnosticGateRequest, evaluateDiagnosticGate } from './jev-core.ts';
+import type { JevRuntime } from './jev-client.ts';
+
+/** P0-1 seam: the runtime plus a live confidence gate (config can reload mid-session). */
+export interface JevEprGateDependency {
+  ask: JevRuntime['ask'];
+  getMinConfidence: () => number;
+}
+
+export interface ToolResultEventLike {
+  toolName: string;
+  toolCallId: string;
+  input?: Record<string, unknown>;
+  content: Array<{ type: string; text?: string; [k: string]: unknown }>;
+  details?: Record<string, unknown>;
+  isError: boolean;
+  usage?: UsageLike;
+}
+
+export interface ReducerInvocationResult {
+  /** pi's ToolResultEventResult.content uses TextContent, so the literal type must stay narrow. */
+  content?: Array<{ type: 'text'; text: string; [k: string]: unknown }>;
+  /** Complete pi `Usage` (see mergeUsage): a partial object crashes pi's footer renderer. */
+  usage?: UsageTotals;
+}
+
+let untrustedWarningEmitted = false;
+
+export async function handleReducerToolResult(
+  event: ToolResultEventLike,
+  ctx: ExtensionContext,
+  config: EvidencePreservingReducerConfig,
+  opts?: { epoch?: number; jev?: JevEprGateDependency },
+): Promise<ReducerInvocationResult | undefined> {
+  if (!config.enabled) return undefined;
+  const epoch = opts?.epoch ?? 0;
+
+  // 1. Candidate command & tool gate: strictly bash only
+  if (event.toolName !== 'bash') return undefined;
+  const command = typeof event.input?.command === 'string' ? event.input.command.trim() : '';
+  if (!command) return undefined;
+  if (!isDiagnosticCommand(command)) {
+    // P0-1 (RFC docs/rfc-jev-integration.md §3): the regex missed — widen the
+    // funnel through jev before giving up. The regex fast path stays
+    // authoritative; any jev failure keeps the "not diagnostic" verdict.
+    const gate = opts?.jev;
+    if (!gate) return undefined;
+    const result = await gate.ask(diagnosticGateRequest(command), {
+      questionId: 'epr-diagnostic-gate',
+      timeoutMs: 1000, // tool-result path; only regex-missed commands reach here
+      sessionId: ctx.sessionManager?.getSessionId?.(),
+      extra: { site: 'epr-gate', commandSha256: sha256Hex(command) },
+      enrich: ({ answers }) => {
+        if (!answers) return {};
+        const verdict = evaluateDiagnosticGate(answers, gate.getMinConfidence());
+        return { verdict: verdict.hit ? 'hit' : verdict.reason, choice: verdict.choice, noul: verdict.noul, confidence: verdict.confidence };
+      },
+    });
+    if (!result.ok) return undefined;
+    if (!evaluateDiagnosticGate(result.answers, gate.getMinConfidence()).hit) return undefined;
+  }
+
+  // 2. Project trust boundary check
+  const isTrusted =
+    typeof (ctx as { isProjectTrusted?: () => boolean }).isProjectTrusted === 'function'
+      ? (ctx as { isProjectTrusted: () => boolean }).isProjectTrusted()
+      : false;
+  if (!isTrusted) {
+    if (!untrustedWarningEmitted) {
+      untrustedWarningEmitted = true;
+      console.warn('[pi-herdr] EPR 提炼已在未受信任项目中被安全禁用');
+    }
+    return undefined;
+  }
+
+  // 3. Find primary log text block
+  const logBlock = event.content.find((b) => b && b.type === 'text' && typeof b.text === 'string');
+  if (!logBlock || typeof logBlock.text !== 'string') return undefined;
+
+  // 4. Retrieve complete untruncated source if available
+  const maxChars = config.maxChars ?? DEFAULT_MAX_CHARS;
+  const detailPath = typeof event.details?.fullOutputPath === 'string' ? event.details.fullOutputPath : undefined;
+  // Pi repeats the path inside the truncation notice that ships with the result text; a replayed
+  // or re-shaped event can keep only that text, and reducing the preview would lose the evidence.
+  const noticePath = fullOutputPathFromNotice(logBlock.text);
+  const fullOutputPath = detailPath ?? noticePath;
+  const fullOutputSource = detailPath ? 'details' : noticePath ? 'notice' : 'none';
+  const isTruncated =
+    (event.details?.truncation as { truncated?: boolean } | undefined)?.truncated === true;
+
+  const sessionDir = ctx.sessionManager?.getSessionDir?.();
+  const sessionId = ctx.sessionManager?.getSessionId?.();
+  const sessionRoot = resolveSessionRoot(sessionDir, sessionId);
+
+  // If truncated and no fullOutputPath or fullOutputPath cannot be read safely, fail-open!
+  if (isTruncated && !fullOutputPath) {
+    if (config.logEnabled && sessionRoot) {
+      await logReducerAttempt(sessionRoot, sessionId ?? 'unknown', epoch, {
+        commandSha256: sha256Hex(command),
+        model: config.model ?? 'default',
+        verificationOk: false,
+        reason: 'truncated-source',
+        action: 'fallback_full_text',
+        fullOutputSource,
+      });
+    }
+    return undefined;
+  }
+
+  let body = logBlock.text;
+  if (fullOutputPath) {
+    const full = await readBashFullOutput(fullOutputPath, maxChars);
+    if (!full) {
+      if (config.logEnabled && sessionRoot) {
+        await logReducerAttempt(sessionRoot, sessionId ?? 'unknown', epoch, {
+          commandSha256: sha256Hex(command),
+          model: config.model ?? 'default',
+          verificationOk: false,
+          reason: 'truncated-source',
+          action: 'fallback_full_text',
+          fullOutputSource,
+        });
+      }
+      // Log was truncated but full file could not be read safely -> fallback to avoid hallucinated receipts
+      return undefined;
+    }
+    body = full.content;
+  }
+
+  const sourceBytes = Buffer.byteLength(body, 'utf8');
+  const minBytes = config.minBytes ?? DEFAULT_MIN_BYTES;
+  if (sourceBytes < minBytes || body.length > maxChars) return undefined;
+
+  // 5. Secret detection check
+  if (containsLikelySecret(body)) {
+    if (config.logEnabled && sessionRoot) {
+      await logReducerAttempt(sessionRoot, sessionId ?? 'unknown', epoch, {
+        commandSha256: sha256Hex(command),
+        sourceBytes,
+        model: config.model ?? 'default',
+        verificationOk: false,
+        reason: 'likely-secret',
+        action: 'fallback_full_text',
+        // Which shape tripped the gate — the 2026-09-17 trial had 10 fallbacks
+        // with zero evidence of what matched (test names vs real credentials).
+        secretSnippet: extractLikelySecretMatch(body),
+      });
+    }
+    return undefined; // Fail-open on sensitive data
+  }
+
+  if (!sessionRoot) return undefined;
+
+  const sourceHash = sha256Hex(body);
+  const sourceLines = countLines(body);
+  const archivePath = reducerObjectPath(sessionRoot, sourceHash);
+
+  // 6. P0: Mandatory source archive before any receipt modification
+  try {
+    await storeContentAddressedObject(archivePath, body);
+  } catch {
+    return undefined; // Fail-open if storage fails
+  }
+
+  // If localOnly mode, archival is complete; leave content unmodified
+  if (config.localOnly) return undefined;
+  // 7. Resolve model: configured cheap reducer first, session model as fallback
+  //    (2026-09-17: user directive — gemini-3.8-flash-high stays the reducer;
+  //    unavailability must degrade to the session model, not skip reduction).
+  let targetModel: any = undefined;
+  let reducerModelSource: 'configured' | 'session-fallback' = 'configured';
+  if (config.model && typeof config.model === 'string' && config.model.includes('/')) {
+    const [provider, ...rest] = config.model.split('/');
+    const modelId = rest.join('/');
+    try {
+      targetModel = ctx.modelRegistry?.find?.(provider, modelId);
+    } catch {
+      targetModel = undefined;
+    }
+  }
+  if (!targetModel) {
+    targetModel = ctx.model;
+    reducerModelSource = 'session-fallback';
+  }
+  if (!targetModel || typeof ctx.modelRegistry?.complete !== 'function') {
+    return undefined;
+  }
+  // Unified provider/id label: the 2026-09-17 logs split one session into
+  // "cliproxy/gemini-3.8-flash-high" (fallback rows) and "gemini-3.8-flash-high"
+  // (applied rows), fragmenting per-model grouping.
+  const reducerModelLabel =
+    typeof targetModel.provider === 'string' && typeof targetModel.id === 'string'
+      ? `${targetModel.provider}/${targetModel.id}`
+      : (config.model ?? 'unknown');
+
+  // 8. Invoke model in-process with timeout
+  const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const timeoutSignal = AbortSignal.timeout(timeoutMs);
+  const signal =
+    ctx.signal && typeof (AbortSignal as any).any === 'function'
+      ? (AbortSignal as any).any([ctx.signal, timeoutSignal])
+      : timeoutSignal;
+
+  const promptInput = reducerInputPrompt({
+    command,
+    isError: event.isError,
+    sourceHash,
+    sourceBytes,
+    sourceLines,
+    body,
+  });
+
+  const startMs = Date.now();
+  let modelResult: any;
+  try {
+    modelResult = await ctx.modelRegistry.complete(
+      targetModel,
+      {
+        systemPrompt: reducerInstructions(),
+        messages: [{ role: 'user', content: [{ type: 'text', text: promptInput }], timestamp: Date.now() }],
+      },
+      {
+        maxTokens: config.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS,
+        cacheRetention: 'none',
+        signal,
+      },
+    );
+  } catch (err) {
+    // Fail-open, but no longer silent: the 2026-09-17 trial lost 3+ attempts
+    // (timeout / provider error) with no jsonl trace at all.
+    if (config.logEnabled) {
+      await logReducerAttempt(sessionRoot, sessionId ?? 'unknown', epoch, {
+        commandSha256: sha256Hex(command),
+        sourceBytes,
+        model: reducerModelLabel,
+        reducerModelSource,
+        verificationOk: false,
+        reason: 'invoke-failed',
+        action: 'fallback_full_text',
+        error: err instanceof Error ? err.message : String(err),
+        durationMs: Date.now() - startMs,
+      });
+    }
+    return undefined; // Fail-open on timeout or provider error
+  }
+
+  const modelOutput = Array.isArray(modelResult?.content)
+    ? modelResult.content.map((b: any) => (typeof b.text === 'string' ? b.text : '')).join('')
+    : typeof modelResult?.text === 'string'
+      ? modelResult.text
+      : '';
+
+  if (!modelOutput.trim()) return undefined;
+
+  // 9. Strict byte-for-byte quotation validation
+  const validated = validateReceipt(modelOutput, sourceHash, body, event.isError);
+  if (!validated.ok) {
+    if (config.logEnabled) {
+      const failReason = validated.reason;
+      await logReducerAttempt(sessionRoot, sessionId ?? 'unknown', epoch, {
+        commandSha256: sha256Hex(command),
+        sourceBytes,
+        model: reducerModelLabel,
+        reducerModelSource,
+        verificationOk: false,
+        reason: failReason,
+        action: 'fallback_full_text',
+        // invalid-json rows carried no evidence of what the model actually
+        // returned (fences? truncation? prose?) — keep a sanitized head.
+        ...(failReason === 'invalid-json' ? { rawOutputHead: JSON.stringify(modelOutput.slice(0, 200)) } : {}),
+        durationMs: Date.now() - startMs,
+      });
+    }
+    return undefined;
+  }
+
+  const modelName = targetModel.id ?? config.model ?? 'default';
+  const providerName = typeof targetModel.provider === 'string' ? targetModel.provider : undefined;
+  const receipt = formatReceiptText({
+    command,
+    sourceHash,
+    sourceBytes,
+    sourceLines,
+    sourceArtifactPath: archivePath,
+    validated: validated.value,
+    model: modelName,
+    provider: providerName,
+    totalTokens: modelResult?.usage?.totalTokens,
+  });
+
+  const receiptBytes = Buffer.byteLength(receipt, 'utf8');
+  if (receiptBytes >= sourceBytes) {
+    return undefined; // Must be smaller
+  }
+
+  // 10. Block-level replacement: only replace the log text block, preserving warnings
+  const nextContent = event.content.map((b): { type: 'text'; text: string } =>
+    (b === logBlock ? { ...b, text: receipt } : b) as { type: 'text'; text: string });
+
+  // Backfill usage tokens: the nested reducer model call plus whatever the tool result already carried.
+  // MUST stay a COMPLETE pi `Usage`: pi persists this onto the tool-result message and its footer
+  // renders it through `addUsageToTotals`, which reads `usage.cost.total` unguarded. Emitting only
+  // { input, output, totalTokens } killed the whole pi process with
+  // "TypeError: Cannot read properties of undefined (reading 'total')" (observed 2026-09-13 in a
+  // subagent pane, stack: FooterComponent.render -> addUsageToTotals). See docs/session-format.md.
+  const nextUsage = mergeUsage(event.usage, modelResult?.usage);
+
+  if (config.logEnabled) {
+    await logReducerAttempt(sessionRoot, sessionId ?? 'unknown', epoch, {
+      commandSha256: sha256Hex(command),
+      sourceBytes,
+      receiptBytes,
+      grossSavedBytes: sourceBytes - receiptBytes,
+      compressionRatio: Number((receiptBytes / sourceBytes).toFixed(3)),
+      model: reducerModelLabel,
+      reducerModelSource,
+      verificationOk: true,
+      action: 'applied',
+      fullOutputSource,
+      durationMs: Date.now() - startMs,
+    });
+  }
+
+  return {
+    content: nextContent,
+    usage: nextUsage,
+  };
+}
+
+async function logReducerAttempt(
+  sessionRoot: string,
+  sessionId: string,
+  epoch: number,
+  record: Record<string, unknown>,
+): Promise<void> {
+  const logPath = efficiencyLogPath(sessionRoot, 'reducer');
+  try {
+    await appendEfficiencyLog(logPath, {
+      schema: 'pier-efficiency/1',
+      mechanism: 'evidencePreservingReducer',
+      ts: new Date().toISOString(),
+      sessionId,
+      epoch,
+      ...record,
+    });
+  } catch {
+    /* ignore logging error */
+  }
+}

package/src/renderers.ts

@@ -0,0 +1,198 @@
+/**
+ * TUI renderers for pier's own session custom entries and reminder messages.
+ *
+ * Why: pier persists authority in the session JSONL (todo edits, subagent registry,
+ * terminal registry, role manifests, soft-approvals) and injects reminder messages.
+ * Without a renderer those transcript rows are raw JSON, which buries the one line
+ * that matters. The line builders here are pure (unit-tested); the component is a
+ * thin string array plus an ANSI-aware truncator, so this module needs no pi-tui
+ * import and degrades to "no renderer" on older pi builds.
+ */
+import { TODO_EDIT_CUSTOM_TYPE, type TodoEditPayload } from './todo-core.ts';
+import { SUBS_CUSTOM_TYPE, type SubsRegistry } from './subagent-core.ts';
+import { TERMINALS_CUSTOM_TYPE, TERM_REMINDER_CUSTOM_TYPE, type TerminalsRegistry } from './terminal-core.ts';
+import { TODO_REMINDER_CUSTOM_TYPE } from './todo-reminder-core.ts';
+
+// Width handling lives in its own module so the ask_user_question UI can reuse it
+// without pulling the todo/subagent/terminal cores into its import graph.
+import { charWidth, styledWidth, truncateStyled } from './ansi-text.ts';
+export { charWidth, styledWidth, truncateStyled };
+
+/** Role manifest entry is written by index.ts; keep the literal here to avoid an import cycle. */
+export const ROLE_MANIFEST_CUSTOM_TYPE = 'pi-herdr.role-manifest';
+/** Soft-approval trace written by the worker manifest gate in index.ts. */
+export const APPROVAL_NEEDED_CUSTOM_TYPE = 'pi-herdr.approval-needed';
+
+/** Structural subset of pi's Theme that the builders actually use. */
+export interface RenderTheme {
+  fg(color: string, text: string): string;
+  bold(text: string): string;
+}
+
+/** Structural subset of pi's Component; enough for `registerEntryRenderer`. */
+export interface RenderComponent {
+  render(width: number): string[];
+  invalidate(): void;
+}
+
+export interface RendererApi {
+  registerEntryRenderer?(
+    customType: string,
+    renderer: (entry: unknown, options: { expanded: boolean }, theme: RenderTheme) => RenderComponent | undefined,
+  ): void;
+  registerMessageRenderer?(
+    customType: string,
+    renderer: (message: unknown, options: { expanded: boolean }, theme: RenderTheme) => RenderComponent | undefined,
+  ): void;
+}
+
+/* ── Pure line builders ────────────────────────────────────────────── */
+
+/** Component wrapper: render is a no-op transform except for width clipping. */
+export function card(lines: readonly string[]): RenderComponent {
+  return {
+    render: (width: number) => lines.map((line) => truncateStyled(line, width)),
+    invalidate() { /* No cached state. */ },
+  };
+}
+
+export function clip(text: string, max: number): string {
+  const flat = text.replace(/\s+/g, ' ').trim();
+  return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
+}
+
+const EDIT_VERB: Record<string, string> = {
+  done: '✓ done',
+  drop: '■ dropped',
+  unblock: '○ unblocked',
+  rm: '✗ removed',
+};
+
+export function formatEditCounts(edits: ReadonlyArray<{ op: string }>): string {
+  const counts = new Map<string, number>();
+  for (const edit of edits) counts.set(edit.op, (counts.get(edit.op) ?? 0) + 1);
+  return [...counts.entries()]
+    .map(([op, n]) => `${EDIT_VERB[op] ?? op}${n > 1 ? ` ×${n}` : ''}`)
+    .join(' · ');
+}
+
+export function todoEditLines(data: unknown, theme: RenderTheme, expanded: boolean): string[] {
+  const payload = data as TodoEditPayload | undefined;
+  const edits = Array.isArray(payload?.edits) ? payload.edits : [];
+  if (edits.length === 0) return [theme.fg('dim', 'todo · no edits')];
+  const head = `${theme.fg('accent', theme.bold('todo'))} ${theme.fg('dim', `· ${edits.length} edit${edits.length > 1 ? 's' : ''}`)} ${formatEditCounts(edits)}`;
+  if (!expanded) return [head];
+  return [
+    head,
+    ...edits.map((edit) => theme.fg('dim', `  ${EDIT_VERB[edit.op] ?? edit.op} — ${clip(String(edit.content ?? ''), 90)}`)),
+  ];
+}
+
+export function subsLines(data: unknown, theme: RenderTheme, expanded: boolean): string[] {
+  const subs = (data as SubsRegistry | undefined)?.subs;
+  if (!Array.isArray(subs) || subs.length === 0) return [theme.fg('dim', 'subagents · none')];
+  const running = subs.filter((s) => s.status === 'running').length;
+  const head = `${theme.fg('accent', theme.bold('subagents'))} ${theme.fg('dim', `· ${subs.length} tracked`)}${running ? ` ${theme.fg('success', `${running} running`)}` : ''}`;
+  if (!expanded) return [head];
+  return [
+    head,
+    ...subs.map((sub) => theme.fg(
+      'dim',
+      `  ${sub.status === 'running' ? '●' : '○'} ${sub.paneId} · ${sub.status} · ${clip(String(sub.description ?? ''), 70)}`,
+    )),
+  ];
+}
+
+export function terminalsLines(data: unknown, theme: RenderTheme, expanded: boolean): string[] {
+  const terminals = (data as TerminalsRegistry | undefined)?.terminals;
+  if (!Array.isArray(terminals) || terminals.length === 0) return [theme.fg('dim', 'terminals · none')];
+  const head = `${theme.fg('accent', theme.bold('terminals'))} ${theme.fg('dim', `· ${terminals.length} open`)}`;
+  if (!expanded) return [head];
+  return [
+    head,
+    ...terminals.map((t) => theme.fg('dim', `  ${t.paneId} · ${clip(String(t.label ?? t.cwd ?? ''), 70)}`)),
+  ];
+}
+
+export function roleManifestLines(data: unknown, theme: RenderTheme): string[] {
+  const rec = (data ?? {}) as { role?: unknown; manifestVersion?: unknown; tools?: unknown; permissions?: unknown };
+  const role = typeof rec.role === 'string' ? rec.role : '?';
+  const version = typeof rec.manifestVersion === 'string' || typeof rec.manifestVersion === 'number' ? String(rec.manifestVersion) : '?';
+  const tools = Array.isArray(rec.tools) ? rec.tools.length : 0;
+  const gates = Object.values((rec.permissions ?? {}) as Record<string, unknown>)
+    .filter((v) => v === 'deny' || v === 'ask').length;
+  const tail = gates > 0 ? theme.fg('warning', ` · ${gates} gated`) : '';
+  return [`${theme.fg('accent', theme.bold('role'))} ${role} ${theme.fg('dim', `v${version} · ${tools} tools`)}${tail}`];
+}
+
+export function approvalLines(data: unknown, theme: RenderTheme): string[] {
+  const rec = (data ?? {}) as { role?: unknown; tool?: unknown };
+  const role = typeof rec.role === 'string' ? rec.role : '?';
+  const tool = typeof rec.tool === 'string' ? rec.tool : '?';
+  return [`${theme.fg('warning', '⚠ approval needed')} ${theme.fg('dim', `· ${tool} (${role})`)}`];
+}
+
+/** Reminder custom messages carry the full injected text; restyle without altering it. */
+export function reminderLines(message: unknown, theme: RenderTheme, label: string, expanded: boolean): string[] {
+  const content = typeof (message as { content?: unknown } | undefined)?.content === 'string'
+    ? String((message as { content: string }).content)
+    : '';
+  const firstLine = content.split('\n').find((line) => line.trim().length > 0) ?? label;
+  const head = `${theme.fg('warning', `↻ ${label}`)}`;
+  if (!expanded) return [head, theme.fg('dim', `  ${clip(firstLine, 110)}`)];
+  return [head, ...content.split('\n').map((line) => theme.fg('dim', line))];
+}
+
+/* ── Installation ──────────────────────────────────────────────────── */
+
+function entryCard(
+  build: (data: unknown, theme: RenderTheme, expanded: boolean) => string[],
+): (entry: unknown, options: { expanded: boolean }, theme: RenderTheme) => RenderComponent {
+  return (entry, options, theme) => card(build((entry as { data?: unknown } | undefined)?.data, theme, options.expanded));
+}
+
+function messageCard(
+  build: (message: unknown, theme: RenderTheme, expanded: boolean) => string[],
+): (message: unknown, options: { expanded: boolean }, theme: RenderTheme) => RenderComponent {
+  return (message, options, theme) => card(build(message, theme, options.expanded));
+}
+
+/**
+ * Register pier's transcript renderers. Returns the custom types actually registered,
+ * so the caller can log coverage and tests can assert the degrade path.
+ *
+ * Why best-effort: entry/message renderers are display-only. A pi build without the
+ * API (pre-0.80.4) or a throwing renderer must never break tool registration, so each
+ * registration is individually guarded.
+ */
+export function installRenderers(pi: unknown): string[] {
+  const api = pi as RendererApi;
+  const registered: string[] = [];
+  const entry = (type: string, build: (data: unknown, theme: RenderTheme, expanded: boolean) => string[]): void => {
+    if (typeof api.registerEntryRenderer !== 'function') return;
+    try {
+      api.registerEntryRenderer(type, entryCard(build));
+      registered.push(type);
+    } catch {
+      /* Older pi or a conflicting renderer: keep the default rendering. */
+    }
+  };
+  const message = (type: string, build: (msg: unknown, theme: RenderTheme, expanded: boolean) => string[]): void => {
+    if (typeof api.registerMessageRenderer !== 'function') return;
+    try {
+      api.registerMessageRenderer(type, messageCard(build));
+      registered.push(type);
+    } catch {
+      /* Best effort; the message still reaches the model. */
+    }
+  };
+
+  entry(TODO_EDIT_CUSTOM_TYPE, (data, theme, expanded) => todoEditLines(data, theme, expanded));
+  entry(SUBS_CUSTOM_TYPE, (data, theme, expanded) => subsLines(data, theme, expanded));
+  entry(TERMINALS_CUSTOM_TYPE, (data, theme, expanded) => terminalsLines(data, theme, expanded));
+  entry(ROLE_MANIFEST_CUSTOM_TYPE, (data, theme) => roleManifestLines(data, theme));
+  entry(APPROVAL_NEEDED_CUSTOM_TYPE, (data, theme) => approvalLines(data, theme));
+  message(TODO_REMINDER_CUSTOM_TYPE, (msg, theme, expanded) => reminderLines(msg, theme, 'todo reminder', expanded));
+  message(TERM_REMINDER_CUSTOM_TYPE, (msg, theme, expanded) => reminderLines(msg, theme, 'terminal nudge', expanded));
+  return registered;
+}

package/src/role-loader.ts

@@ -143,7 +143,8 @@ function parseAndValidate(name: string, fileName: string, text: string, layerLab
     throw new RoleLoaderError('INVALID_ROLE_CONFIG', `role "${name}"（${layerLabel}）不是合法 JSON: ${(err as Error).message}`);
   }
   const result = validateRoleManifest(parsed);
-  if (!result.ok) {
+  // `ok === false` (instead of `!ok`) is required to narrow without strictNullChecks.
+  if (result.ok === false) {
     throw new RoleLoaderError(
       'INVALID_ROLE_CONFIG',
       `role "${name}"（${layerLabel}）校验失败:\n${result.issues.map((i) => `  - ${i}`).join('\n')}`,

package/src/role-manifest.ts

@@ -58,10 +58,6 @@ function isPlainObject(v: unknown): v is Record<string, unknown> {
   return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
 
-function isPosInt(v: unknown): boolean {
-  return typeof v === 'number' && Number.isInteger(v) && v > 0;
-}
-
 export function validateRoleManifest(input: unknown): ValidateResult {
   const issues: string[] = [];
   if (!isPlainObject(input)) {

package/src/runtime-policy.ts

@@ -4,6 +4,7 @@
  * Why: Prevents drift between hardcoded literals and environment overrides;
  * makes timing behavior explicit and testable.
  */
+import { pierOption } from './pier-options.ts';
 
 export interface RuntimePolicy {
   /** Subagent overall timeout (ms) */
@@ -12,8 +13,6 @@ export interface RuntimePolicy {
   readonly gcTickMs: number
   /** Poll interval for subagent state observation (ms) */
   readonly pollIntervalMs: number
-  /** Stale check cadence (turns) */
-  readonly staleCadenceTurns: number
   /** Settlement notice window / machine-inject grace / takeover idle (ms) */
   readonly settlementWindowMs: number
   /** Post-settle observation window before auto-consume (ms) */
@@ -22,16 +21,15 @@ export interface RuntimePolicy {
   readonly foregroundPatienceMs: number
   /** Default session TTL (seconds) */
   readonly sessionTtlSeconds: number
-  /** Terminal read maximum bytes */
-  readonly terminalReadMaxBytes: number
   /** Git operation timeout (ms) */
   readonly gitTimeoutMs: number
   /** Subagent pane pipe readiness wait (ms) */
   readonly readinessTimeoutMs: number
 }
 
+/** B10: read through the option catalog so the legacy `PI_HERDR_*` spelling keeps working. */
 function parseEnvInt(key: string, defaultValue: number, min: number = 0): number {
-  const raw = process.env[key]
+  const raw = pierOption(key)
   if (!raw) return defaultValue
   
   const parsed = Number.parseInt(raw, 10)
@@ -48,14 +46,13 @@ export function createRuntimePolicy(overrides?: Partial<RuntimePolicy>): Runtime
     subagentTimeoutMs: overrides?.subagentTimeoutMs ?? parseEnvInt('PIER_SUBAGENT_TIMEOUT_MS', 600_000, 1000),
     gcTickMs: overrides?.gcTickMs ?? parseEnvInt('PIER_GC_TICK_MS', 30_000, 1000),
     pollIntervalMs: overrides?.pollIntervalMs ?? parseEnvInt('PIER_POLL_INTERVAL_MS', 30_000, 1000),
-    staleCadenceTurns: overrides?.staleCadenceTurns ?? parseEnvInt('PIER_STALE_CADENCE_TURNS', 3, 1),
     settlementWindowMs: overrides?.settlementWindowMs ?? parseEnvInt('PIER_SETTLEMENT_WINDOW_MS', 60_000, 0),
     observationWindowMs: overrides?.observationWindowMs ?? parseEnvInt('PIER_OBSERVATION_WINDOW_MS', 30_000, 0),
     foregroundPatienceMs: overrides?.foregroundPatienceMs ?? parseEnvInt('PIER_FOREGROUND_PATIENCE_MS', 300_000, 0),
     sessionTtlSeconds: overrides?.sessionTtlSeconds ?? parseEnvInt('PIER_SESSION_TTL_SECONDS', 600, 0),
-    terminalReadMaxBytes: overrides?.terminalReadMaxBytes ?? parseEnvInt('TERM_READ_MAX', 4096, 1),
     gitTimeoutMs: overrides?.gitTimeoutMs ?? parseEnvInt('PIER_GIT_TIMEOUT_MS', 10_000, 1),
-    readinessTimeoutMs: overrides?.readinessTimeoutMs ?? parseEnvInt('PIER_READY_TIMEOUT_MS', 30_000, 1000),
+    // A14: concurrent heavy workers can take far longer than 30s to boot; PIER_READY_TIMEOUT_MS overrides.
+    readinessTimeoutMs: overrides?.readinessTimeoutMs ?? parseEnvInt('PIER_READY_TIMEOUT_MS', 90_000, 1000),
   }
 }