pi-pier 0.4.1 → 0.4.2

package/src/efficiency-config-core.ts

@@ -14,6 +14,10 @@ import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
+/** pi's thinking levels in ascending order, plus `inherit` (summarize at the session's own level). */
+export const SUMMARY_THINKING_LEVELS = ['inherit', 'off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'] as const;
+export type SummaryThinkingLevel = (typeof SUMMARY_THINKING_LEVELS)[number];
+
 export interface OnlineContextCompactConfig {
   enabled: boolean;
   logEnabled: boolean;
@@ -21,6 +25,8 @@ export interface OnlineContextCompactConfig {
   keepRecentTokens?: number;
   firstCompactionRequestScale: number;
   subsequentCompactionMargin: number;
+  /** Cap on the summary request's thinking level (never raised above the session's). */
+  summaryThinkingLevel: SummaryThinkingLevel;
 }
 
 export interface ObservationPackConfig {
@@ -74,7 +80,7 @@ export const DEFAULT_EFFICIENCY_CONFIG: EfficiencyConfig = Object.freeze({
   version: 1,
   onlineContextCompact: Object.freeze({
     enabled: false, logEnabled: false, cacheWriteReadRatio: 'auto', keepRecentTokens: 20000,
-    firstCompactionRequestScale: 2.0, subsequentCompactionMargin: 1.5,
+    firstCompactionRequestScale: 2.0, subsequentCompactionMargin: 1.5, summaryThinkingLevel: 'low',
   }),
   observationPack: Object.freeze({
     enabled: false, logEnabled: false, thresholdBytes: 10240, fullSends: 2,
@@ -87,7 +93,7 @@ export const DEFAULT_EFFICIENCY_CONFIG: EfficiencyConfig = Object.freeze({
   jev: Object.freeze({ enabled: false, logEnabled: false, model: 'jev-1.13.0', timeoutMs: 2000, minConfidence: 0.6 }),
 });
 
-type FieldKind = 'bool' | 'int' | 'number' | 'ratio' | 'string' | 'optionalString';
+type FieldKind = 'bool' | 'int' | 'number' | 'ratio' | 'string' | 'optionalString' | 'enum';
 
 interface FieldSpec {
   readonly key: string;
@@ -97,6 +103,8 @@ interface FieldSpec {
   readonly max?: number;
   /** Issue text for a bound that must not be printed as a plain JS number ("1.0"). */
   readonly minText?: string;
+  /** Accepted values for `enum`. */
+  readonly values?: readonly string[];
 }
 
 /** A section is `{enabled, ...fields}`; field order fixes the order of reported issues. */
@@ -113,6 +121,7 @@ const SECTIONS: readonly SectionSpec[] = [
     { key: 'keepRecentTokens', kind: 'int', min: 1000 },
     { key: 'firstCompactionRequestScale', kind: 'number', min: 1, minText: '1.0' },
     { key: 'subsequentCompactionMargin', kind: 'number', min: 1, minText: '1.0' },
+    { key: 'summaryThinkingLevel', kind: 'enum', values: SUMMARY_THINKING_LEVELS },
   ] },
   { name: 'observationPack', fields: [
     { key: 'enabled', kind: 'bool' },
@@ -156,6 +165,8 @@ function issueFor(section: string, field: FieldSpec): string {
         : `${path} 必须是 ${field.min} 到 ${field.max} 之间的数字`;
     case 'ratio':
       return `${path} 必须是 "auto" 或非负有限数`;
+    case 'enum':
+      return `${path} 必须是 ${(field.values ?? []).join(' | ')} 之一`;
     default:
       return `${path} 必须是非空字符串`;
   }
@@ -190,6 +201,9 @@ function applyField(target: Record<string, unknown>, field: FieldSpec, raw: unkn
       if (typeof raw !== 'string' || !raw.trim()) return false;
       target[field.key] = raw.trim();
       return true;
+    case 'enum':
+      if (typeof raw !== 'string' || !(field.values ?? []).includes(raw)) return false;
+      break;
   }
   target[field.key] = raw;
   return true;

package/src/efficiency-store.ts

@@ -5,7 +5,7 @@
  */
 
 import { constants } from 'node:fs';
-import { lstat, mkdir, open, readdir, realpath, rename, rm, stat } from 'node:fs/promises';
+import { lstat, mkdir, open, readdir, realpath, rename, rm, stat, type FileHandle } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import {
@@ -52,6 +52,21 @@ export function observationObjectPath(root: string, obsId: string): string {
   return join(root, 'observation-pack', 'objects', `${obsId}.txt`);
 }
 
+/** Cross-process idempotence probe: a resumed process has no memo but the content-addressed object
+ *  is still on disk. A wrong-sized file is treated as absent so the writer re-verifies it. */
+export async function observationObjectExists(
+  root: string,
+  obsId: string,
+  expectedBytes?: number,
+): Promise<boolean> {
+  try {
+    const stats = await lstat(observationObjectPath(root, obsId));
+    return stats.isFile() && (expectedBytes === undefined || stats.size === expectedBytes);
+  } catch {
+    return false;
+  }
+}
+
 export function reducerObjectPath(root: string, sha256: string): string {
   return join(root, 'evidence-preserving-reducer', 'objects', `${sha256}.txt`);
 }
@@ -202,6 +217,27 @@ export async function storeContentAddressedObject(
   };
 }
 
+const ALIGN_SCAN_BYTES = 64 * 1024;
+
+/** Advance a mid-line offset to the next line start so a recall page never opens inside a line.
+ *  A single-line tail (no newline left) keeps the requested offset: skipping to EOF would make the
+ *  rest of the object unreadable. */
+async function alignOffsetToLineStart(handle: FileHandle, offset: number, size: number): Promise<number> {
+  if (offset <= 0 || offset >= size) return offset;
+  const prev = Buffer.alloc(1);
+  const { bytesRead: prevRead } = await handle.read(prev, 0, 1, offset - 1);
+  if (prevRead === 0 || prev[0] === 0x0a) return offset;
+
+  const scan = Buffer.alloc(Math.min(ALIGN_SCAN_BYTES, size - offset));
+  for (let pos = offset; pos < size; pos += scan.length) {
+    const { bytesRead } = await handle.read(scan, 0, Math.min(scan.length, size - pos), pos);
+    if (bytesRead === 0) break;
+    const newline = scan.subarray(0, bytesRead).indexOf(0x0a);
+    if (newline !== -1) return pos + newline + 1;
+  }
+  return offset;
+}
+
 export async function readStoredObjectChunk(
   filePath: string,
   offset: number,
@@ -218,14 +254,15 @@ export async function readStoredObjectChunk(
       throw new Error(`Offset ${offset} exceeds object size ${fileStat.size}`);
     }
 
-    const available = Math.max(0, fileStat.size - offset);
+    const start = await alignOffsetToLineStart(handle, offset, fileStat.size);
+    const available = Math.max(0, fileStat.size - start);
     const buffer = Buffer.alloc(Math.min(available, limits.maxBytes + 4));
-    const { bytesRead } = await handle.read(buffer, 0, buffer.length, offset);
+    const { bytesRead } = await handle.read(buffer, 0, buffer.length, start);
     const sliced = sliceBufferChunk(buffer.subarray(0, bytesRead), 0, limits);
     // sliceBufferChunk's nextOffset is relative to the window it was given (offset 0). Callers page
     // with the absolute file offset from the header, so add the seek back.
-    const nextOffset = offset + sliced.nextOffset;
-    return { ...sliced, nextOffset, eof: nextOffset >= fileStat.size };
+    const nextOffset = start + sliced.nextOffset;
+    return { ...sliced, offset: start, nextOffset, eof: nextOffset >= fileStat.size };
   } finally {
     await handle?.close();
   }

package/src/herdr-client.ts

@@ -147,9 +147,20 @@ export function herdrUnavailableHint(err: unknown): string | null {
 /** Wire protocol this client is written against (herdr 0.9.5, contract fixture regenerated 2026-10-20). */
 export const HERDR_PROTOCOL_EXPECTED = 22;
 
+export type WaitFailureReason = 'timeout' | 'unavailable';
+
 export type WaitForOutputResult =
   | { matched: true }
-  | { matched: false; reason: 'timeout' | 'unavailable' };
+  | { matched: false; reason: WaitFailureReason };
+
+/** Classify a failed `pane.wait_for_output`: null means the error is not a wait outcome and should
+ *  surface. herdr may report its own server-side timeout under an `unavailable` code or as
+ *  "timed out"; a wait that consumed its budget is a timeout regardless of the label it chose. */
+export function classifyWaitFailure(message: string, elapsedMs: number, timeoutMs: number): WaitFailureReason | null {
+  if (/timeout|timed out|deadline exceeded/i.test(message) || elapsedMs >= timeoutMs * 0.95) return 'timeout';
+  if (/not supported|not implemented|unknown method|unavailable|method not found/i.test(message)) return 'unavailable';
+  return null;
+}
 
 /** pane.read / agent.read selection: `recent` keeps ANSI so T6 fullscreen detection still sees it. */
 export interface ReadOptions {
@@ -783,6 +794,7 @@ export class HerdrClient implements HerdrClientLike {
   }
 
   async waitForOutput(paneId: string, match: { type: 'substring' | 'regex'; value: string }, timeoutMs: number): Promise<WaitForOutputResult> {
+    const started = Date.now();
     try {
       await this.request('pane.wait_for_output', {
         pane_id: paneId,
@@ -793,10 +805,8 @@ export class HerdrClient implements HerdrClientLike {
       return { matched: true };
     } catch (err) {
       const msg = String((err as Error)?.message ?? err);
-      if (/timeout/i.test(msg)) return { matched: false, reason: 'timeout' };
-      if (/not supported|not implemented|unknown method|unavailable|method not found/i.test(msg)) {
-        return { matched: false, reason: 'unavailable' };
-      }
+      const reason = classifyWaitFailure(msg, Date.now() - started, timeoutMs);
+      if (reason != null) return { matched: false, reason };
       throw err;
     }
   }

package/src/index-pipe.ts

@@ -21,8 +21,6 @@ export interface PipeHandlerSession {
   setPendingMachineRequest: (req: MachineRequest | null) => void;
   /** P0 (RFC §4.4): apply a role switch requested over the pipe (master → worker). */
   applyRoleSwitch: (role: string, switchedBy: string) => Promise<{ ok: boolean; message: string }>;
-  /** Phase 2 (RFC rfc-delegation-identity §3.2): worker → master progress note (display-less custom message). */
-  deliverProgress: (workerPaneId: string, text: string) => Promise<void>;
   /** D113 (RFC rfc-unified-widget): worker → master full todo push; updates the widget cache. */
   applyWorkerTodos: (workerPaneId: string, items: Array<{ content: string; status: string; blocker?: string }>, summary: string) => void;
 }
@@ -58,12 +56,6 @@ export async function handlePipeRequest(
         ? { type: 'ok', id: req.id, detail: res.message }
         : { type: 'error', id: req.id, message: res.message };
     }
-    case 'progress': {
-      // Never triggers a master turn and never floods the visible chat (RFC §3.2); the
-      // display-less custom message rides context only, rendered as a compact card.
-      await s.deliverProgress(req.paneId, req.text);
-      return { type: 'ok', id: req.id };
-    }
     case 'todo_sync': {
       s.applyWorkerTodos(req.paneId, req.items, req.summary);
       return { type: 'ok', id: req.id };

package/src/index.ts

@@ -10,7 +10,6 @@
  * details persist in session JSONL and getBranch() replay implements branch rollback.
  */
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import { Type } from 'typebox';
 import {
   ASK_PARAMETERS,
   ASK_PROMPT_GUIDELINES,
@@ -20,6 +19,7 @@ import {
   hasAskUi,
   noUiResult,
   prepareAsk,
+  prepareAskArguments,
   runAsk,
 } from './ask-user.ts';
 import { pipeNameFor, pipeRequest, startPipeServer } from './pipe-channel.ts';
@@ -42,7 +42,7 @@ import { parseRuntimeManifest } from './tool-gate.ts';
 import { formatPaneTitle } from './pane-title.ts';
 import { registerSlimFrame, updateSlimFrame } from './slim-frame.ts';
 import { applyRestoredWorkerMode, planIndexMode } from './index-runtime.ts';
-import { buildResumeArgv, emptySubagentPortBox, PROGRESS_CUSTOM_TYPE } from './subagent-core.ts';
+import { buildResumeArgv, emptySubagentPortBox, sleepWhileSubsRunningNote } from './subagent-core.ts';
 import { hasWorkerMarker, writeWorkerMarker, readWorkerMarker } from './worker-marker.ts';
 import {
   DELEGATION_CUSTOM_TYPE,
@@ -58,18 +58,16 @@ import { handlePipeRequest, type MachineRequest } from './index-pipe.ts';
 import { installWriteLocks } from './index-locks.ts';
 import { installDashboardCommand } from './dashboard-command.ts';
 import { openPierPanel } from './panel-open.ts';
-import { registerObservationPack, createCompactionBatchPackHook, type PickMiddleExcerpt } from './plugins/observation.ts';
+import { registerObservationPack, createCompactionBatchPackHook, type PickMiddleExcerpts } from './plugins/observation.ts';
 import { createJevRuntime } from './jev-client.ts';
 import {
   NOTICE_RANK_MIN_CONFIDENCE,
-  buildExcerptWindows,
   composeNoticeRanking,
   evaluateExcerptPick,
-  excerptAskIsSafe,
   excerptPickRequest,
   noticeRankRequest,
+  planExcerptAsks,
 } from './jev-core.ts';
-import { completeLineExcerpt } from './observation-core.ts';
 import { installConfigCommand } from './config-command.ts';
 import { CompactCoordinator } from './compact-coordinator.ts';
 import { handleReducerToolResult, type ToolResultEventLike } from './reducer-invoker.ts';
@@ -113,30 +111,37 @@ export default async function (pi: ExtensionAPI) {
   /* ── Jev decision layer (RFC docs/rfc-jev-integration.md): direct HTTP, total-budget
    * abort, fail-open at every site. Disabled or keyless → behavior identical to before. ── */
   const jevRuntime = createJevRuntime(() => effConfig.jev, { getSessionRoot: () => sessionRoot, getSessionId: () => sessionId || null });
-  /** P0-3: candidate windows are generated in code; jev only picks (rerank pattern). */
-  const pickMiddleExcerpt: PickMiddleExcerpt = async (text, excerptBudgetBytes) => {
-    if (!jevRuntime.available) return null;
-    const halfBudget = Math.floor(excerptBudgetBytes / 2);
-    const windows = buildExcerptWindows(text, halfBudget);
-    if (windows.length === 0) return null; // degenerate budget only
-    const headExcerpt = completeLineExcerpt(text, halfBudget, false);
-    const tailExcerpt = completeLineExcerpt(text, excerptBudgetBytes - halfBudget, true);
-    // Credential-shaped text never leaves the process (§8 privacy boundary).
-    if (!excerptAskIsSafe(windows, headExcerpt, tailExcerpt)) return null;
-    const request = excerptPickRequest(windows, headExcerpt, tailExcerpt);
-    if (!request) return null;
+  /** P0-3: candidate windows are generated in code; jev only picks (rerank pattern), one request per batch. */
+  const pickMiddleExcerpts: PickMiddleExcerpts = async (items, excerptBudgetBytes) => {
+    const picks: Array<{ text: string; label: string } | null> = items.map(() => null);
+    if (!jevRuntime.available) return picks;
+    const asked = planExcerptAsks(items, excerptBudgetBytes);
+    const request = excerptPickRequest(asked);
+    if (!request) return picks;
     const result = await jevRuntime.ask(request, {
       questionId: 'obs-excerpt-window',
-      extra: { site: 'obs-excerpt', candidates: windows.map((w) => w.id) },
+      extra: {
+        site: 'obs-excerpt',
+        items: asked.map((a) => ({ obsId: a.obsId, windows: a.windows.map((w) => ({ id: w.id, startLine: w.startLine })) })),
+      },
       enrich: ({ answers }) => {
-        if (!answers || answers.window === undefined || answers.window.type !== 'choice') return {};
-        return { picked: answers.window.choice, confidence: answers.window.confidence };
+        if (!answers) return {};
+        return {
+          picked: asked.map((_, i) => {
+            const answer = answers[`excerpt_${i}_window`];
+            return answer?.type === 'choice' ? { choice: answer.choice, confidence: answer.confidence } : null;
+          }),
+        };
       },
     });
-    if (!result.ok) return null;
-    const picked = evaluateExcerptPick(result.answers, effConfig.jev.minConfidence);
-    const window = picked === null ? undefined : windows.find((w) => w.id === picked);
-    return window ? { text: window.text, label: window.label } : null;
+    if (!result.ok) return picks;
+    for (let i = 0; i < asked.length; i++) {
+      const { index, windows } = asked[i]!;
+      const picked = evaluateExcerptPick(result.answers, i, effConfig.jev.minConfidence);
+      const window = picked === null ? undefined : windows.find((w) => w.id === picked);
+      if (window) picks[index] = { text: window.text, label: window.label };
+    }
+    return picks;
   };
 
   const rendererTypes = installRenderers(pi);
@@ -290,6 +295,8 @@ export default async function (pi: ExtensionAPI) {
         }
         todos.applyEdits(plan.edits, { source: 'reconcile' });
         mirrorTodos();
+        // Reconcile is not a tool call, so nothing else refreshes the resident widget after an edit.
+        todoUi.rerenderWidget?.();
       }
       return plan.noteLines;
     } catch {
@@ -353,6 +360,18 @@ export default async function (pi: ExtensionAPI) {
     });
   });
 
+  /* ── Masters sleep-polled background workers (sleep 120…840) instead of trusting the settlement notice. ── */
+  if (!isSubagent) {
+    pi.on('tool_result', async (event: unknown) => {
+      const rec = (event ?? {}) as { toolName?: unknown; input?: { command?: unknown }; content?: unknown };
+      if (rec.toolName !== 'bash' || typeof rec.input?.command !== 'string') return;
+      const note = sleepWhileSubsRunningNote(rec.input.command, subagentPort.current?.listRunningSubs() ?? []);
+      if (!note) return;
+      const content = Array.isArray(rec.content) ? rec.content as Array<{ type: 'text'; text: string }> : [];
+      return { content: [...content, { type: 'text' as const, text: note }] };
+    });
+  }
+
   let locksHandle = { getHeldLocks: () => [] as readonly string[] };
   if (env) {
     locksHandle = installWriteLocks(pi, { client, env, hard: process.env[WRITE_LOCK_ENV] === '1' });
@@ -365,19 +384,11 @@ export default async function (pi: ExtensionAPI) {
     return Promise.resolve();
   };
 
-  /** Phase 2 (RFC rfc-delegation-identity §3.2): a worker's progress note enters master context as
-   * a display-less custom message — no turn, no visible chat line; renderers.ts gives it a card. */
-  const deliverProgress = (workerPaneId: string, text: string): Promise<void> => {
-    (pi as unknown as {
-      sendMessage?: (msg: { customType: string; content: string; display: boolean; details?: Record<string, unknown> }, opts?: { triggerTurn?: boolean }) => void;
-    }).sendMessage?.(
-      { customType: PROGRESS_CUSTOM_TYPE, content: text.slice(0, 2000), display: false, details: { paneId: workerPaneId } },
-      { triggerTurn: false },
-    );
-    return Promise.resolve();
-  };
   const notices = createNoticeBuffer({
-    isBusy: () => agentActive || lastStopReason === ABORT_STOP_REASON,
+    // pi core rejects prompts while it is compacting (and drops fire-and-forget sends), so a
+    // settlement landing inside the compaction window must stay buffered until the continuation
+    // run settles — otherwise the result is lost with nobody left to retry it.
+    isBusy: () => agentActive || lastStopReason === ABORT_STOP_REASON || coordinator.compactionInFlight,
     send: sendUserMessageAs,
     // P0-2: rank collapsed batches by relevance to the master's in-progress work.
     rank: async (contents) => {
@@ -443,7 +454,6 @@ export default async function (pi: ExtensionAPI) {
         abort: () => { latestCtx?.abort?.(); },
         setPendingMachineRequest: (next) => { pendingMachineRequest = next; },
         applyRoleSwitch: roles.applyRoleSwitch,
-        deliverProgress,
         applyWorkerTodos,
       }));
     } catch {
@@ -589,6 +599,9 @@ export default async function (pi: ExtensionAPI) {
     // Safety fallback: pi core prohibits prompts while compaction is active.
     coordinator.compactionInFlight = false;
     coordinator.intentionalAbort = false;
+    // A selection that never became startable must not latch every later decision (and the
+    // settle-wake hold) until the next human input.
+    coordinator.selectedCompaction = null;
     gates.report('working', currentActivity(todos.items));
   });
 
@@ -612,15 +625,20 @@ export default async function (pi: ExtensionAPI) {
     // flush ran regardless. The merged handler keeps both semantics.
     const msg = event !== null && typeof event === 'object' && 'message' in event ? (event as { message: unknown }).message : null;
     if (msg !== null && typeof msg === 'object') {
-      const { role, stopReason } = msg as { role?: unknown; stopReason?: unknown };
+      const { role, stopReason, usage } = msg as { role?: unknown; stopReason?: unknown; usage?: unknown };
       if (role === 'assistant' && typeof stopReason === 'string') {
         lastStopReason = stopReason;
       }
+      if (role === 'assistant' && usage !== null && typeof usage === 'object') {
+        coordinator.onAssistantUsage(usage as { input?: number; cacheRead?: number; cacheWrite?: number });
+      }
       if (ctx && typeof ctx === 'object') {
         coordinator.onTurnEnd({
           ctx,
           todos: todos.items,
           config: effConfig.onlineContextCompact,
+          pi,
+          lastStopReason: typeof stopReason === 'string' ? stopReason : null,
           cancelReminder: todoUi.cancelReminder,
         });
       }
@@ -654,6 +672,13 @@ export default async function (pi: ExtensionAPI) {
       void sendUserMessageAs(notice, 'followUp');
     }
     if (plan.compact && ctx && typeof ctx === 'object') {
+      // Settlement notices that land inside the compaction window stay buffered (isBusy includes
+      // compactionInFlight). The continuation run flushes them at its own agent_settled; a cancelled
+      // or rejected compaction sends no continuation, so release the buffer once the coordinator is
+      // done and no run has started.
+      const flushAfterCompaction = (): void => {
+        if (!coordinator.compactionInFlight && !agentActive) void notices.flush('followUp');
+      };
       void coordinator.onAgentSettled({
         ctx,
         todos: todos.items,
@@ -664,9 +689,9 @@ export default async function (pi: ExtensionAPI) {
           getObsConfig: () => effConfig.observationPack,
           getManifest: () => roles.state.manifest,
           getSessionId: () => sessionId,
-          pickMiddleExcerpt,
+          pickMiddleExcerpts,
         }),
-      });
+      }).then(flushAfterCompaction, flushAfterCompaction);
     }
     if (lastStopReason !== ABORT_STOP_REASON && !aborted) void notices.flush('followUp');
     void pushSettleReply(aborted);
@@ -677,7 +702,7 @@ export default async function (pi: ExtensionAPI) {
     pi,
     getConfig: () => effConfig,
     getRuntimeManifest: () => roles.state.manifest,
-    pickMiddleExcerpt,
+    pickMiddleExcerpts,
     getRemainingHorizon: () => {
       const usage = (latestCtx as { getContextUsage?: () => { contextWindow?: number } })?.getContextUsage?.();
       return coordinator.getRemainingHorizon(3, usage?.contextWindow ?? null);
@@ -701,6 +726,8 @@ export default async function (pi: ExtensionAPI) {
     description: ASK_TOOL_DESCRIPTION,
     promptGuidelines: ASK_PROMPT_GUIDELINES,
     parameters: ASK_PARAMETERS,
+    // Models sometimes send options/questions as a JSON string; repair them before pi validates.
+    prepareArguments: prepareAskArguments,
     async execute(_tc, params, signal, _upd, ctx) {
       const prepared = prepareAsk(params);
       if (!prepared.ok) return prepared.result;
@@ -717,49 +744,6 @@ export default async function (pi: ExtensionAPI) {
     },
   });
 
-  /* ── report_progress (Phase 2, RFC rfc-delegation-identity §3.2): worker → master checkpoint ── */
-  if (isSubagent) {
-    pi.registerTool({
-      name: 'report_progress',
-      label: 'Report Progress',
-      description:
-        'Send the delegating master a short progress update without finishing the task. Use at meaningful checkpoints (a module done, a test went green, a blocker found) — the master sees it in its context but is not interrupted.',
-      promptSnippet: 'report_progress: mid-task checkpoint to the delegating master (does not end the task).',
-      promptGuidelines: [
-        'Call at meaningful checkpoints only — a milestone reached, a risk discovered, a decision the master should know early — not after every tool call.',
-        'One or two sentences per call; the final answer still goes in your normal closing message when the task finishes.',
-      ],
-      parameters: Type.Object({
-        message: Type.String({ description: 'Short checkpoint update for the delegating master.' }),
-      }),
-      async execute(_tc, params) {
-        const parentPipe = delegation?.parentPipe;
-        const message = typeof (params as { message?: unknown })?.message === 'string'
-          ? (params as { message: string }).message.trim()
-          : '';
-        if (!message) {
-          return { content: [{ type: 'text', text: 'Error: `message` is required (one or two sentences).' }], details: {} };
-        }
-        if (!parentPipe) {
-          return { content: [{ type: 'text', text: 'Error: no delegating master pipe is known to this session; progress cannot be delivered.' }], details: {} };
-        }
-        try {
-          const res = await pipeRequest(parentPipe, {
-            type: 'progress',
-            id: `prog-${Date.now()}`,
-            paneId: env?.paneId ?? '',
-            text: message,
-          }, 5000);
-          return res.type === 'ok'
-            ? { content: [{ type: 'text', text: 'Progress delivered to the master (visible in its context, no interruption).' }], details: {} }
-            : { content: [{ type: 'text', text: `Error: master rejected progress report: ${res.message}` }], details: {} };
-        } catch (err) {
-          return { content: [{ type: 'text', text: `Error: could not reach the master pipe: ${(err as Error)?.message ?? err}` }], details: {} };
-        }
-      },
-    });
-  }
-
   pi.on('session_shutdown', async () => {
     coordinator.compactionInFlight = false;
     coordinator.intentionalAbort = false;

package/src/jev-client.ts

@@ -12,6 +12,10 @@ import { parseJevAnswers, type JevAnswer, type JevQuestion, type JevUsage } from
 import type { JevConfig } from './efficiency-config-core.ts';
 
 const JEV_DEFAULT_BASE_URL = 'https://api.typesafe.ai';
+/** Consecutive transport failures (timeout / network / 5xx) that open the breaker. */
+export const JEV_BREAKER_FAILURES = 2;
+/** While open, asks fail open locally without a request or a telemetry row; the tripping row says so. */
+export const JEV_BREAKER_OPEN_MS = 60_000;
 
 export interface JevAskMeta {
   /** Stable question-set id for telemetry rows (e.g. 'epr-diagnostic-gate'). */
@@ -23,7 +27,7 @@ export interface JevAskMeta {
   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.
+   * needs; still never request bodies). Called exactly once per ask, with null answers on failure.
    */
   enrich?: (outcome: { ok: boolean; answers: Record<string, JevAnswer> | null }) => Record<string, unknown>;
 }
@@ -49,11 +53,14 @@ export interface JevRuntime {
 export function createJevRuntime(getConfig: () => JevConfig, deps: JevRuntimeDeps = {}): JevRuntime {
   const doFetch = deps.fetchImpl ?? ((input, init) => globalThis.fetch(input, init));
   const now = deps.now ?? Date.now;
-
+  // A run of 12 back-to-back network failures and 2.5s timeout stalls showed every site paying
+  // the full budget during an outage; the breaker makes an outage cost one tripping ask.
+  let transportFailures = 0;
+  let breakerOpenUntil = 0;
   async function logAsk(
     config: JevConfig,
     meta: JevAskMeta,
-    outcome: { ok: true; model: string; usage: JevUsage } | { ok: false; reason: string },
+    outcome: { ok: true; model: string; usage: JevUsage } | { ok: false; reason: string; extra?: Record<string, unknown> },
     latencyMs: number,
     state: unknown,
     enriched: Record<string, unknown>,
@@ -77,6 +84,7 @@ export function createJevRuntime(getConfig: () => JevConfig, deps: JevRuntimeDep
       stateHash: sha256Hex(serialized),
       ...(outcome.ok ? { usage: { input_tokens: outcome.usage.inputTokens, output_tokens: outcome.usage.outputTokens } } : {}),
       ...(meta.extra ?? {}),
+      ...(outcome.ok ? {} : outcome.extra ?? {}),
       ...enriched,
     };
     try {
@@ -95,14 +103,25 @@ export function createJevRuntime(getConfig: () => JevConfig, deps: JevRuntimeDep
     async ask(request, meta): Promise<JevAskResult> {
       const startedAt = now();
       const config = getConfig();
-      const fail = async (reason: string): Promise<JevAskResult> => {
+      const fail = async (reason: string, extra?: Record<string, unknown>): 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);
+        await logAsk(config, meta, { ok: false, reason, extra }, latencyMs, request.state, enriched);
         return { ok: false, reason, latencyMs };
       };
+      const transportFail = (reason: string, extra: Record<string, unknown> = {}): Promise<JevAskResult> => {
+        transportFailures += 1;
+        if (transportFailures < JEV_BREAKER_FAILURES) return fail(reason, extra);
+        transportFailures = 0;
+        breakerOpenUntil = now() + JEV_BREAKER_OPEN_MS;
+        return fail(reason, { ...extra, breakerOpenedMs: JEV_BREAKER_OPEN_MS });
+      };
       if (!config.enabled) return fail('disabled');
       if (!config.apiKey) return fail('no-api-key');
+      if (now() < breakerOpenUntil) {
+        meta.enrich?.({ ok: false, answers: null });
+        return { ok: false, reason: 'breaker-open', latencyMs: 0 };
+      }
 
       const timeoutMs = meta.timeoutMs ?? config.timeoutMs;
       const controller = new AbortController();
@@ -121,8 +140,11 @@ export function createJevRuntime(getConfig: () => JevConfig, deps: JevRuntimeDep
         if (!response.ok) {
           // 429 (and everything else) fails open immediately: limits are
           // dynamically adjusted upstream and every pier call is droppable.
+          if (response.status >= 500) return transportFail(`http-${response.status}`);
+          transportFailures = 0;
           return fail(response.status === 429 ? 'rate-limited' : `http-${response.status}`);
         }
+        transportFailures = 0;
         const raw: unknown = await response.json();
         const parsed = parseJevAnswers(raw, Object.keys(request.questions));
         if (!parsed.ok) return fail(parsed.reason);
@@ -131,8 +153,11 @@ export function createJevRuntime(getConfig: () => JevConfig, deps: JevRuntimeDep
         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');
+        if (error instanceof Error && error.name === 'AbortError') return transportFail('timeout');
+        // fetch wraps the socket error in `cause`; its code (ECONNRESET, ENOTFOUND, ...) is the diagnosis.
+        const source = error instanceof Error && error.cause instanceof Error ? error.cause : error;
+        const code = source instanceof Error && 'code' in source && typeof source.code === 'string' ? source.code : undefined;
+        return transportFail('network-error', code ? { errorCode: code } : {});
       } finally {
         clearTimeout(timer);
       }