software-defence-factory 0.15.3 → 0.15.5

package/docs/npm.md

@@ -282,3 +282,13 @@ reject tampered selections/images/policies and unsupported future writers, and
 verify that readback does not rewrite retained evidence. Image adoption is a
 separate idle operator action; existing attempt images are not migrated by a CLI
 update. See [the migration/rollback recipe](setup.md#local-context-budget-and-worker-image-0152-100).
+
+
+The 0.15.5 compatibility audit adds that exact writer to the explicit v1/v2/v3
+allowlists. The examined change is confined to local Pi projection, proactive
+recovery and completion validation. Evidence schemas, frozen commands, model and
+image selections, policy hashes, candidate reconstruction and acceptance guards
+remain unchanged from 0.15.4. Profile tests exercise all phases and inherited,
+cloud, hybrid and local definitions, reject changed selections and future writers,
+and verify immutable readback. This does not upgrade or qualify historical local
+attempts; installed image adoption and actual inference remain separate gates.

package/docs/recovery.md

@@ -44,6 +44,22 @@ retry around a retained writer or reuse earlier story evidence for a changed
 candidate or policy. Browser traces and screenshots are private evidence and
 are presented through the shared interfaces. See [the web contract](web-verification.md).
 
+## Local Pi history exhaustion
+
+The 0.15.5 candidate adds bounded proactive recovery for short histories, including
+productive writes whose immutable arguments require fewer retained groups;
+see [limits and image adoption](setup.md#local-context-budget-and-worker-image-0152-100).
+A failed/empty summary, exhausted recovery limit, cancellation or irreducible
+request remains a failed attempt even if a tool already wrote a report. Keep its
+checkout, raw events and private diagnostic evidence. Reconcile the stopped
+worker before admitting a smaller task or explicitly selecting another qualified
+profile as a separate attempt. Do not enlarge the allocation, rewrite a failed
+history or label an explicit cloud retry as local success. Successful transport
+recovery still needs semantic checks and independent Review. The reviewed first
+checkpoint failed real local qualification; the revised artifact needs a new
+lead-owned installed and real-task pass before acceptance. See the
+[rejected trial and source regression](proof.md#short-local-pi-history-recovery-0155-candidate-105).
+
 ## Review feedback or phase retry
 
 Use **Request changes** on a failed software review only when its validated

package/docs/setup.md

@@ -509,6 +509,40 @@ guessed or silently rewritten. Do not add project Pi settings to bypass
 the admitted binding or rely on custom tuning that has not been qualified.
 See [pinned compaction behavior](https://github.com/earendil-works/pi/blob/v0.87.1/packages/coding-agent/docs/compaction.md).
 
+Starting with the **0.15.5 candidate (#105)**, the local adapter also checks
+history pressure at Pi's completed-tool-turn boundary. This conservative byte
+signal counts the system/task/tool envelope once, call arguments, non-tool text
+and capped tool excerpts, separately from provider-reported usage. At 65% of the
+input budget it considers Pi's supported summary generator and append-only
+compaction entry. The newest complete tool group is retained; up to three older
+complete groups can remain as additional evidence when the actual summary and
+retained envelope fit. The original task is restored exactly on every generation;
+raw events and existing session entries are not rewritten. Large-result bursts
+still use upstream compaction and the final request projection. Projection gives
+recent short results (up to 2 KiB each, 8 KiB total and at most a quarter of the
+input budget) priority when they fit.
+
+Recovery allows at most 16 proactive summaries per process and two retries per
+summary. It must reduce pressure by at least 4 KiB and leave headroom of 8 KiB
+(or 15% of the input budget when smaller). Its preferred reduction target adapts
+to the immutable latest-group/envelope floor and actual summary size; it cannot
+require that floor to fit an arbitrary fraction of the trigger. The next trigger
+also leaves room for new work. If the latest write/group alone makes recovery
+unproductive, the adapter defers to a later complete turn under the unchanged
+wire guard, when that group can become summary input. This does not permit an
+oversized request through transport. Empty, failed, cancelled or ineffective
+summaries fail the attempt. Oversized instructions, arguments or retained groups
+can still fail closed. These are bounded recovery limits, not automatic
+context/output tuning or a guarantee of useful model work.
+
+The selected context, generation output and model remain unchanged; summary
+output is separately capped (6,553 for proactive summaries with 8,192 selected
+output on pinned Pi). `factory_context_recovery` JSONL events record only
+pressure, envelope/floor sizes, group counts and recovery progress, without
+prompts/content. Pi token accounting stays partial; this summary path is not
+added to ordinary assistant usage totals. See
+[source measurements, rejected real trial and pending qualification](proof.md#short-local-pi-history-recovery-0155-candidate-105).
+
 Before adoption, stop and reconcile all work, retain the old immutable image ID
 and a stopped private-state backup. Build/qualify the exact candidate image, then
 explicitly select it with `factory install --image LOCAL_IMAGE_REF --state PRIVATE_STATE`

package/docs/usage.md

@@ -46,3 +46,60 @@ Historical recovery is optional and budgeted to eight lookups per second and
 512 cached terminal attempts per controller lifetime. Further attempts remain
 unknown; new persisted measurements bypass these legacy read limits. This
 prevents large old queues from rereading all logs on every status poll.
+
+## Pi stdout measurements (0.15.4)
+
+New Pi attempts use `source: "pi_jsonl"`. Factory collects stdout before bounded
+log truncation; stderr, tool results and streaming updates cannot supply usage.
+The audited official `@earendil-works/pi-coding-agent` **0.87.1** OpenAI
+completions adapter reports uncached `input`, `cacheRead`, `cacheWrite`, `output`
+and their sum in `totalTokens`. Factory maps them to the existing contract:
+
+- `input_tokens = input + cacheRead + cacheWrite` (inclusive input).
+- `cached_input_tokens = cacheRead`, and `cache_write_input_tokens = cacheWrite`.
+- `token_usage = input_tokens + output_tokens`; neither cache subset is added again.
+
+Cache-write attribution is optional for historical/Codex records, not assumed
+zero when absent. Pi requires all five counters, validates their sum, and
+preserves exact decimal strings. Unsafe numeric values are rejected. An all-zero
+Pi usage object remains unknown: the installed provider also emits this initial
+placeholder when no usage arrived, including failed requests. Provider cost
+fields and configured zero prices do not establish monetary consumption; local
+hardware/electricity and unpriced provider cost remain unknown.
+
+The pinned agent loop emits completed `message_end` assistant messages and
+repeats them, in order, in that agent turn's `agent_end.messages`. Factory
+reconciles positions within each `agent_start`/`agent_end` interval. Equal token
+counts and equal timestamps are not unique IDs: distinct positions and explicit
+new agent turns count separately. Repeated snapshots do not add tokens; a final
+aggregate alone can supply counts. Contradictory or ambiguous snapshots never
+add unmatched counts. Missing, malformed and oversized evidence cannot turn an
+observation into complete coverage or a measured zero.
+
+All Pi observations currently have **partial** coverage, even after a successful
+run. Pi 0.87.1 performs compaction summary calls outside the visible assistant
+aggregate and can retry provider requests without independent failed-request
+usage accounting. A recovered job can succeed while these totals remain
+incomplete. Absence of a retry/compaction event is not proof of full coverage.
+No scorer, cost estimate, quality claim or acceptance authority follows from
+these measurements.
+
+Parsing is bounded to an 8 MiB line buffer, 262,144 framed lines, 2,048 observed
+assistant messages and at most 1 MiB of retained counter signatures per turn.
+Message content is discarded after each line. Counts and aggregate totals are
+bounded to 128 decimal digits. Beyond a limit, already observed totals remain
+partial; with no usable evidence the result is unknown.
+
+A private, atomic `jobs/JOB/RUN/usage.json` checkpoint contains only usage and
+job/run/phase/frozen execution identity. It is controller-owned, outside the
+worker output mount, and preserves observations when cancellation kills the
+executor before its final result. Normal completion stores the same normalized
+usage in SQLite and measurement artifacts. CLI `status`, the status API and
+existing Analytics/issue detail consume that shared contract after restart.
+Model/provider/role attribution still comes from the frozen execution profile,
+never from usage event fields. Failed/cancelled runs keep their outcome.
+
+There is **no Pi historical log backfill**. Existing records and mixed or
+truncated legacy logs are not rewritten. This bounded measurement slice leaves
+#51's scoring/benchmark engine, #69's model qualification and #70's improvement
+proposal workflow open.

package/factory/execution-profile.mjs

@@ -27,16 +27,20 @@ import { expectedWebStories, webPolicyHash } from './web-verification.mjs';
 // 0.15.3 isolates local Pi mutable state and denies project resource trust.
 // Evidence schemas, candidate reconstruction and frozen profile guards are unchanged;
 // compatibility does not qualify an old local startup or accept a failed attempt.
+// 0.15.4 adds Pi usage metadata only; protected evidence schemas, frozen
+// execution selection, isolation and acceptance policy remain unchanged.
+// 0.15.5 changes only local context recovery/projection; v1/v2/v3 schemas,
+// frozen selection hashes, provenance, checks and acceptance guards are unchanged.
 // Older writers still require exact patch/tree reconstruction before publication.
 // Deliberately independent of VERSION: a release bump is not
 // evidence compatibility. Re-audit this list for every trust-relevant writer,
 // isolation or validation change; remove versions whose guarantees no longer
 // satisfy current policy. See docs/npm.md. This predicate alone grants no trust.
-const SUPPORTED_EXECUTION_RUNTIMES_V1 = new Set(['0.8.0', '0.9.0', '0.9.1', '0.10.0', '0.11.0', '0.11.1', '0.11.2', '0.12.0', '0.13.0', '0.13.1', '0.14.0', '0.15.0', '0.15.1', '0.15.2', '0.15.3']);
+const SUPPORTED_EXECUTION_RUNTIMES_V1 = new Set(['0.8.0', '0.9.0', '0.9.1', '0.10.0', '0.11.0', '0.11.1', '0.11.2', '0.12.0', '0.13.0', '0.13.1', '0.14.0', '0.15.0', '0.15.1', '0.15.2', '0.15.3', '0.15.4', '0.15.5']);
 
 export function isSupportedExecutionProfile(profile) {
-  if ([2, 3].includes(profile?.version)) return (profile.version === 3 ? ['0.15.0', '0.15.1', '0.15.2', '0.15.3'].includes(profile.runtimeVersion) && Object.hasOwn(profile, 'localBinding')
-    : ['0.14.0', '0.15.0', '0.15.1', '0.15.2', '0.15.3'].includes(profile.runtimeVersion) && !Object.hasOwn(profile, 'localBinding') && profile.inferenceProvider !== 'factory-local')
+  if ([2, 3].includes(profile?.version)) return (profile.version === 3 ? ['0.15.0', '0.15.1', '0.15.2', '0.15.3', '0.15.4', '0.15.5'].includes(profile.runtimeVersion) && Object.hasOwn(profile, 'localBinding')
+    : ['0.14.0', '0.15.0', '0.15.1', '0.15.2', '0.15.3', '0.15.4', '0.15.5'].includes(profile.runtimeVersion) && !Object.hasOwn(profile, 'localBinding') && profile.inferenceProvider !== 'factory-local')
     && profile.role === (Object.keys(ROLE_PHASES).find(role => ROLE_PHASES[role] === profile.phase) || null)
     && (profile.reasoningEffort === null || ['low', 'medium', 'high'].includes(profile.reasoningEffort))
     && /^[a-f0-9]{64}$/.test(profile.selectionHash || '');

package/factory/executor.mjs

@@ -9,6 +9,7 @@ import { ROOT, run, save, json, digest, instanceLabel, stopContainers } from './
 import { incidentFor, validateReport } from './incident.mjs';
 import { BoundedLog } from './bounded-log.mjs';
 import { CodexUsageParser, emptyUsage, usageFields } from './usage.mjs';
+import { PiUsageParser } from './pi-usage.mjs';
 import { assertRetainedSource, publicSourceAdmission, publicContinuation, restoreBuildCheckout } from './source-admission.mjs';
 import { runCandidateGit, runCandidateGitRaw } from './git-environment.mjs';
 import { selectedInferenceSecrets, writeSelectedModelEnvironment } from './model-environment.mjs';
@@ -103,7 +104,9 @@ async function container(mode, input, command, options = {}) {
   if (scratch) args.push('--mount',`type=bind,source=${scratch},target=/scratch`);
   if (mode === 'verify') args.push('--env',`FACTORY_BASE_REVISION=${git('rev-parse',`${metadata().base}^{commit}`)}`);
   const logPath = join(folder, attempt, `${mode}.log`);
-  const log = new BoundedLog(), usageParser = execution.executor === 'codex' ? new CodexUsageParser() : null;
+  const log = new BoundedLog(), usageParser = mode === 'verify' ? null
+    : execution.executor === 'codex' ? new CodexUsageParser() : execution.executor === 'pi' ? new PiUsageParser() : null;
+  let savedObservations = 0;
   let exitSignal, selectedModelEnvironment = false, inferenceSecrets = [], code, cleanupError, reportError;
   try {
     if (localDirectory) {
@@ -127,7 +130,17 @@ async function container(mode, input, command, options = {}) {
     console.log(JSON.stringify({ phase: mode, event: 'started', synthetic: harnessOf(config) === 'mock' }));
     code = await new Promise((ok, fail) => {
       const child = spawn('docker', args, { stdio: ['pipe','pipe','pipe'] });
-      child.stdout.on('data', bytes => { log.write('stdout', bytes); usageParser?.write(bytes); });
+      child.stdout.on('data', bytes => {
+        usageParser?.write(bytes);
+        // Controller-owned metadata, outside the worker's /output mount. Atomic
+        // checkpoints survive cancellation without consulting mixed log tails.
+        if (usageParser instanceof PiUsageParser && usageParser.observed !== savedObservations) {
+          observedUsage = usageParser.snapshot();
+          save(join(folder, attempt, 'usage.json'), { version: 1, job, attempt, phase, execution, usage: observedUsage });
+          savedObservations = usageParser.observed;
+        }
+        log.write('stdout', bytes);
+      });
       child.stderr.on('data', bytes => log.write('stderr', bytes));
       child.stdin.on('error',error => { if (error.code !== 'EPIPE') fail(error); });
       child.on('error',fail); child.on('close',(code,signal) => { exitSignal=signal; ok(code); }); child.stdin.end(input);

package/factory/pi-context-budget.mjs

@@ -35,6 +35,16 @@ function excerpt(text, limit) {
   return Buffer.byteLength(shortened) < Buffer.byteLength(text) ? shortened : text;
 }
 
+// A pressure signal, not a token estimate: cap large tool bodies so upstream's
+// existing large-result recovery still owns bursts, but count every call/argument
+// and a useful short excerpt. Provider usage cannot measure this growing floor.
+export function historyPressure(messages, envelope) {
+  const copy = structuredClone(messages);
+  for (const message of copy) if (message.role === 'toolResult')
+    for (const part of message.content || []) if (part.type === 'text') part.text = excerpt(part.text, 1024);
+  return envelope + bytes(copy) + 64 * copy.length;
+}
+
 // Uniform cap shares space among large results without penalizing small ones.
 // Calls, arguments, identities, ordering and all non-tool text are immutable.
 export function fitToolText(value, budget, measure = bytes, native = false) {
@@ -49,8 +59,27 @@ export function fitToolText(value, budget, measure = bytes, native = false) {
       for (const part of message.content) if (part.type === 'text') slots.push([part, 'text', part.text]);
     }
   }
-  const cap = limit => { for (const [object, key, text] of slots) object[key] = excerpt(text, limit); };
+  // Prefer recent short discoveries within a bounded allowance; large batches
+  // still share the remaining space. Prefix stability is measured separately.
+  const recent = new Set();
+  let recentBytes = 0;
+  for (const slot of [...slots].reverse()) {
+    const size = bytes(slot[2]);
+    if (size <= 2048 && recentBytes + size <= Math.min(8192, budget / 4)) {
+      recent.add(slot); recentBytes += size;
+    }
+  }
+  const cap = limit => { for (const slot of slots) {
+    const [object, key, text] = slot;
+    object[key] = recent.has(slot) ? text : excerpt(text, limit);
+  } };
   cap(0);
+  // Release older preferences first if the complete preferred set cannot fit.
+  // Even one useful recent result is better than uniformly shortening them all.
+  for (const slot of [...recent].reverse()) {
+    if (measure(original) <= budget) break;
+    recent.delete(slot); cap(0);
+  }
   if (measure(original) > budget) throw new Error('Local Pi context budget cannot fit required instructions, tool pairs and truncation guidance; use smaller task/input or qualify the configured allocation. No fallback.');
   let low = 0, high = Math.max(0, ...slots.map(([, , text]) => text.length));
   while (low < high) {

package/factory/pi-context-extension.mjs

@@ -1,19 +1,87 @@
 // Explicitly mounted Factory adapter, never discovered from the host/repository.
 import { readFileSync, writeSync } from 'node:fs';
 import { openAICompletionsApi } from '@earendil-works/pi-ai';
-import { bytes, fitToolText, projectedTokens, restoreOutputBudget, validatePairs } from './pi-context-budget.mjs';
+import { generateSummaryWithUsage } from '@earendil-works/pi-coding-agent';
+import { historyPressure, bytes, fitToolText, projectedTokens, restoreOutputBudget, validatePairs } from './pi-context-budget.mjs';
 
 export default function factoryLocalContext(pi) {
   const registry = JSON.parse(readFileSync(new URL('./models.json', import.meta.url), 'utf8'));
   const configured = registry.providers['factory-local'].models[0];
   const window = configured.contextWindow, output = configured.maxTokens;
-  let task;
+  let task, taskEntryId, envelope = 0, recoveries = 0, nextRecovery = 0;
   // Pi catches extension exceptions and can continue. Budget violations must
   // stop before transport, even during summarization, with a durable diagnostic.
   const fatal = error => {
     writeSync(2, `Factory local Pi context protection failed: ${error.message}\n`);
     process.exit(1);
   };
+  // Pi 0.87.1's public manual compact() aborts the active run. Use its
+  // supported completed-turn compaction draft instead: all tools have finished,
+  // and the next request rebuilds the canonical projection from this entry.
+  pi.on('turn_end', async (event, ctx) => {
+    if (event.outcome !== 'completed' || event.message.stopReason !== 'toolUse') return;
+    try {
+      const entries = event.context.contextEntries;
+      taskEntryId ??= entries.find(entry => entry.messages.some(m => m.role === 'user'))?.sourceEntry.id;
+      // Pi includes the system message in its boundary projection. The wire
+      // envelope already counts it and the restored task: count each once and
+      // use the same basis before/after, so removal cannot fake progress.
+      const history = list => list.filter(entry => entry.sourceEntry.id !== taskEntryId)
+        .flatMap(entry => entry.messages).filter(message => message.role !== 'system');
+      const budget = window - output;
+      const threshold = Math.max(Math.floor(budget * 0.65), nextRecovery);
+      const pressure = historyPressure(history(entries), envelope);
+      if (pressure < threshold) return;
+      const starts = entries.flatMap((entry, index) => entry.messages.some(m => m.role === 'assistant'
+        && m.content?.some(p => p.type === 'toolCall')) ? [index] : []);
+      // The newest complete group is the retention floor, including immutable
+      // write arguments. Summarize the older prefix once; after seeing its real
+      // size we can retain up to four groups as additional recent evidence.
+      // Never split a group or summarize only part of a pending tool batch.
+      if (starts.length < 2) return;
+      const newest = starts.at(-1);
+      const floor = historyPressure(history(entries.slice(newest)), envelope);
+      const headroom = Math.min(8192, Math.floor(budget * 0.15));
+      // A large current call may leave no useful recovery yet. Let it reach the
+      // next ordinary turn under the unchanged wire guard, then it can enter
+      // the summarized prefix. Avoid paying for a predictably futile summary.
+      if (floor + 1024 > budget - headroom || pressure - floor < 4096) return;
+      if (++recoveries > 16) throw new Error('Local Pi proactive recovery limit reached; split the task. No fallback.');
+      if (ctx.signal?.aborted) throw new Error('Local Pi proactive recovery cancelled');
+      // Pi's summary serializer ignores system messages. Do not charge their
+      // bytes against the summary input projection; generation still keeps the
+      // exact system envelope. Keep the task and all summarized tool pairs.
+      const older = entries.slice(0, newest).flatMap(entry => entry.messages).filter(m => m.role !== 'system');
+      writeSync(1, `${JSON.stringify({ type: 'factory_context_recovery', phase: 'start', pressure, threshold, floor, envelope, groups: starts.length, recovery: recoveries })}\n`);
+      const input = fitToolText(older, window - output - 8192, bytes, true);
+      const result = await generateSummaryWithUsage(input, ctx.model, Math.min(16384, output),
+        'factory-local-keyless', undefined, ctx.signal,
+        'Preserve the task, verified edits, failed attempts, discoveries and remaining work. Do not claim completion without evidence.',
+        undefined, ctx.thinkingLevel, streamLocal, undefined, { enabled: true, maxRetries: 2, baseDelayMs: 250 });
+      if (ctx.signal?.aborted) throw new Error('Local Pi proactive recovery cancelled');
+      if (!result.text?.trim()) throw new Error('Local Pi proactive recovery returned an empty summary');
+      // Include framing for Pi's summary message. A fixed percentage cannot be
+      // required below the immutable envelope/newest-group floor. Bound both
+      // remaining headroom and actual progress instead, using the real summary.
+      const summaryBytes = bytes(result.text) + 1024;
+      const target = Math.min(budget - headroom, pressure - 4096,
+        Math.max(Math.floor(budget * 0.65 * 0.75), floor + summaryBytes));
+      let cut, after;
+      for (const candidate of starts.slice(-4)) {
+        const candidatePressure = historyPressure(history(entries.slice(candidate)), envelope + summaryBytes);
+        if (candidatePressure <= target) { cut = candidate; after = candidatePressure; break; }
+      }
+      if (cut === undefined) throw new Error('Local Pi proactive recovery did not free enough budget; split the task. No fallback.');
+      // Re-arm above the measured retained floor, so a productive large write
+      // does not cause an immediate repeat summary with nothing new to reclaim.
+      nextRecovery = Math.min(budget - Math.floor(headroom / 2), after + 4096);
+      writeSync(1, `${JSON.stringify({ type: 'factory_context_recovery', phase: 'complete', pressure: after, target,
+        summaryBytes, keptGroups: starts.filter(index => index >= cut).length, recovery: recoveries })}\n`);
+      return { entries: [{ type: 'compaction', summary: result.text,
+        firstKeptEntryId: entries[cut].sourceEntry.id, usage: result.usage,
+        details: { factoryLocalRecovery: 1 } }] };
+    } catch (error) { fatal(error); }
+  });
   pi.on('session_before_compact', event => {
     try {
       // These are request-local copies. Upstream still selects cut points and
@@ -25,39 +93,39 @@ export default function factoryLocalContext(pi) {
         preparation[key] = fitToolText(preparation[key], budget, bytes, true);
     } catch (error) { fatal(error); }
   });
-  pi.registerProvider('factory-local', {
-    api: 'openai-completions',
-    streamSimple(model, context, options) {
-      if (model.id !== configured.id || model.provider !== 'factory-local') fatal(new Error('Selected local model changed'));
-      // Capture before streamSimple/buildBaseOptions clamps against unprojected
-      // history. Generation defaults to the binding; summaries supply their cap.
-      const requestedOutput = options?.maxTokens ?? output;
-      return openAICompletionsApi().streamSimple(model, context, {
-        ...options,
-        onPayload: async (payload, requestModel) => {
-          try {
-            payload = await options?.onPayload?.(payload, requestModel) ?? payload;
-            payload = structuredClone(payload);
-            if (payload.model !== configured.id
-              || !payload.messages?.some(m => m.role === 'system')) throw new Error('Unsupported local request structure or output budget');
-            restoreOutputBudget(payload, configured, requestedOutput, options?.reasoning);
-            if (payload.tools?.length) {
-              task ??= structuredClone(payload.messages.find(m => m.role === 'user'));
-              if (!task) throw new Error('Missing required task');
-              if (!payload.messages.some(m => m.role === 'user' && JSON.stringify(m) === JSON.stringify(task)))
-                payload.messages.splice(1, 0, structuredClone(task));
-              validatePairs(payload.messages);
-            }
-            if (!payload.messages.some(m => m.role === 'user')) throw new Error('Missing required user message');
-            // Restore BEFORE measuring so the final output field is counted.
-            // No request is sent unless projection fits with the full configured
-            // reserve, even when a summary requests a smaller bounded output.
-            return fitToolText(payload, window - output, projectedTokens);
-          } catch (error) { fatal(error); }
-        },
-      });
-    },
-  });
+  function streamLocal(model, context, options) {
+    if (model.id !== configured.id || model.provider !== 'factory-local') fatal(new Error('Selected local model changed'));
+    // Capture before streamSimple/buildBaseOptions clamps against unprojected
+    // history. Generation defaults to the binding; summaries supply their cap.
+    const requestedOutput = options?.maxTokens ?? output;
+    return openAICompletionsApi().streamSimple(model, context, {
+      ...options,
+      onPayload: async (payload, requestModel) => {
+        try {
+          payload = await options?.onPayload?.(payload, requestModel) ?? payload;
+          payload = structuredClone(payload);
+          if (payload.model !== configured.id
+            || !payload.messages?.some(m => m.role === 'system')) throw new Error('Unsupported local request structure or output budget');
+          restoreOutputBudget(payload, configured, requestedOutput, options?.reasoning);
+          if (payload.tools?.length) {
+            task ??= structuredClone(payload.messages.find(m => m.role === 'user'));
+            if (!task) throw new Error('Missing required task');
+            if (!payload.messages.some(m => m.role === 'user' && JSON.stringify(m) === JSON.stringify(task)))
+              payload.messages.splice(1, 0, structuredClone(task));
+            validatePairs(payload.messages);
+            envelope = bytes(payload.tools) + bytes(payload.messages.filter(m => m.role === 'system'))
+              + bytes(task) + 4096;
+          }
+          if (!payload.messages.some(m => m.role === 'user')) throw new Error('Missing required user message');
+          // Restore BEFORE measuring so the final output field is counted.
+          // No request is sent unless projection fits with the full configured
+          // reserve, even when a summary requests a smaller bounded output.
+          return fitToolText(payload, window - output, projectedTokens);
+        } catch (error) { fatal(error); }
+      },
+    });
+  }
+  pi.registerProvider('factory-local', { api: 'openai-completions', streamSimple: streamLocal });
   // Launcher requires this handshake; an extension load failure cannot bypass it.
   writeSync(1, `${JSON.stringify({ type: 'factory_context_ready', version: 1 })}\n`);
 }

package/factory/pi-local-launch.mjs

@@ -24,6 +24,8 @@ export class PiCompletion {
   settled = false;
   lastAssistant = null;
   contextReady = false;
+  proactiveRecovery = false;
+  proactiveCount = 0;
 
   write(chunk) {
     this.pending += chunk;
@@ -42,6 +44,17 @@ export class PiCompletion {
   event(value) {
     if (!value || typeof value.type !== 'string') { this.failed = true; return; }
     if (value.type === 'factory_context_ready' && value.version === 1) this.contextReady = true;
+    if (value.type === 'factory_context_recovery') {
+      if (value.phase === 'start') {
+        if (this.proactiveRecovery || value.recovery !== this.proactiveCount + 1 || value.recovery > 16) this.failed = true;
+        this.proactiveCount = value.recovery;
+        this.proactiveRecovery = true;
+        this.settled = false;
+      } else if (value.phase === 'complete') {
+        if (!this.proactiveRecovery || value.recovery !== this.proactiveCount) this.failed = true;
+        this.proactiveRecovery = false;
+      } else this.failed = true;
+    }
     if (value.type === 'agent_start' || value.type === 'message_start') {
       this.completed = false; this.settled = false;
     }
@@ -95,7 +108,7 @@ export class PiCompletion {
 
   finish() {
     return !this.pending && !this.failed && !this.error && !this.retry && !this.compacting && !this.recovery
-      && this.completed && (!this.modern || this.settled);
+      && !this.proactiveRecovery && this.completed && (!this.modern || this.settled);
   }
 }
 

package/factory/pi-usage.mjs

@@ -0,0 +1,106 @@
+import { UsageLineParser, tokenCount, MAX_USAGE_EVENTS, MAX_USAGE_COUNT_DIGITS } from './usage.mjs';
+
+// Pi's final aggregate includes message content and can be much larger than a
+// Codex usage line. Discard content after parsing; retain only bounded counters.
+export const MAX_PI_USAGE_LINE_BYTES = 8 * 1024 * 1024;
+export const MAX_PI_USAGE_METADATA_BYTES = 1024 * 1024;
+export const MAX_PI_USAGE_EVENTS = 262144;
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function counts(message) {
+  if (!object(message.usage) || !['stop', 'toolUse', 'length', 'error', 'aborted'].includes(message.stopReason)) return null;
+  try {
+    const { input, output, cacheRead, cacheWrite, totalTokens } = message.usage;
+    const uncached = tokenCount(input), out = tokenCount(output), read = tokenCount(cacheRead), write = tokenCount(cacheWrite);
+    const inclusive = uncached + read + write;
+    if (inclusive + out !== tokenCount(totalTokens)) return null;
+    if (Object.hasOwn(message.usage, 'reasoning') && tokenCount(message.usage.reasoning) > out) return null;
+    // The provider initializes missing/failed-request usage to zero. Even a
+    // successful stop with all zeros does not establish a measured zero call.
+    if (inclusive + out === 0n) return null;
+    return [inclusive, out, read, write].map(value => value.toString());
+  } catch { return null; }
+}
+
+export class PiUsageParser extends UsageLineParser {
+  constructor() {
+    super(MAX_PI_USAGE_LINE_BYTES);
+    this.totals = [0n, 0n, 0n, 0n];
+    this.observed = 0;
+    this.events = 0;
+    this.metadataBytes = 0;
+    this.messages = [];
+    this.ended = false;
+    this.ambiguous = false;
+    this.exhausted = false;
+  }
+
+  lineComplete() {
+    if (!this.exhausted && ++this.events > MAX_PI_USAGE_EVENTS) this.exhausted = true;
+    super.lineComplete();
+  }
+
+  parseLine() {
+    if (!this.length || this.exhausted) return;
+    let event;
+    try { event = JSON.parse(this.line.toString('utf8', 0, this.length)); }
+    catch { this.ambiguous = true; return; }
+    if (!object(event)) return;
+    // The pinned agent loop's newMessages starts afresh at each agent_start.
+    // Positions within that turn, not timestamps or equal token counts, match
+    // message_end to the repeated agent_end snapshot. New turns may be identical.
+    if (event.type === 'agent_start') {
+      this.messages = []; this.metadataBytes = 0;
+      this.ended = false; this.ambiguous = false;
+    } else if (event.type === 'message_end') {
+      if (!object(event.message)) { this.ambiguous = true; return; }
+      if (event.message.role !== 'assistant') return;
+      if (this.ended) { this.ambiguous = true; return; }
+      this.append(counts(event.message));
+    } else if (event.type === 'agent_end') {
+      if (!Array.isArray(event.messages) || event.messages.length > MAX_USAGE_EVENTS) { this.ambiguous = true; return; }
+      let index = 0;
+      for (const message of event.messages) {
+        if (!object(message)) { this.ambiguous = true; break; }
+        if (message.role !== 'assistant') continue;
+        const value = counts(message), signature = JSON.stringify(value);
+        if (index < this.messages.length) {
+          if (signature !== this.messages[index]) this.ambiguous = true;
+        } else if (!this.ended && !this.ambiguous && !this.incomplete) this.append(value);
+        else this.ambiguous = true;
+        index++;
+      }
+      if (index !== this.messages.length) this.ambiguous = true;
+      this.ended = true;
+    }
+  }
+
+  append(value) {
+    if (this.exhausted) return;
+    const signature = JSON.stringify(value);
+    if (this.observed >= MAX_USAGE_EVENTS || this.messages.length >= MAX_USAGE_EVENTS || this.metadataBytes + signature.length > MAX_PI_USAGE_METADATA_BYTES) {
+      this.exhausted = true; return;
+    }
+    this.messages.push(signature); this.metadataBytes += signature.length;
+    if (!value) return;
+    const next = this.totals.map((total, index) => total + BigInt(value[index]));
+    // Keep aggregate counts and their shared total representable on readback.
+    if ([...next, next[0] + next[1]].some(total => total.toString().length > MAX_USAGE_COUNT_DIGITS)) {
+      this.exhausted = true; return;
+    }
+    this.totals = next; this.observed++;
+  }
+
+  snapshot() {
+    if (!this.observed) return null;
+    const [input, output, cached, writes] = this.totals.map(String);
+    return { input_tokens: input, output_tokens: output, cached_input_tokens: cached,
+      cache_write_input_tokens: writes, source: 'pi_jsonl', coverage: 'partial' };
+  }
+
+  finish() {
+    // JSONL requires a newline. A trailing fragment is not a completed event.
+    if (this.length || this.overflow) this.incomplete = true;
+    return this.snapshot();
+  }
+}

package/factory/processes.mjs

@@ -84,10 +84,35 @@ export function retainedCodexUsage(state, job, attempt) {
   } catch { return null; }
 }
 
+// New Pi measurements are controller-owned metadata, never historical log
+// backfill. A stopped executor may have checkpointed before producing a result.
+export function retainedPiUsage(state, job, attempt) {
+  try {
+    if (!/^job_[a-z0-9]+$/.test(job?.id || '') || !/^run_[a-z0-9]+$/.test(attempt?.id || '')
+      || !['build', 'review', 'defence'].includes(attempt.command) || attempt.execution?.executor !== 'pi') return null;
+    const folder = join(state, 'jobs', job.id), runFolder = join(folder, attempt.id);
+    for (const path of [join(state, 'jobs'), folder, runFolder]) {
+      const stat = lstatSync(path);
+      if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077)) return null;
+    }
+    const path = join(runFolder, 'usage.json'), stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077) || stat.size > 16384) return null;
+    const saved = JSON.parse(readFileSync(path, 'utf8'));
+    if (saved.version !== 1 || saved.job !== job.id || saved.attempt !== attempt.id || saved.phase !== attempt.command
+      || !isDeepStrictEqual(saved.execution, attempt.execution) || saved.usage?.source !== 'pi_jsonl') return null;
+    const normalized = usageFields(saved.usage, attempt.execution, attempt.command).usage;
+    return normalized.status ? null : normalized;
+  } catch { return null; }
+}
+
+function retainedUsage(state, job, attempt) {
+  return retainedPiUsage(state, job, attempt) || retainedCodexUsage(state, job, attempt);
+}
+
 function usageForAttempt(state, job, attempt) {
   const stored = usageFields(attempt.usage, attempt.execution, attempt.command);
   if (stored.usage.status !== 'unknown') return stored;
-  const recovered = retainedCodexUsage(state, job, attempt);
+  const recovered = retainedUsage(state, job, attempt);
   return recovered ? usageFields(recovered, attempt.execution, attempt.command) : stored;
 }
 
@@ -186,7 +211,7 @@ export function executors(state, recovery = {}) {
     try { exit = await done; }
     finally { clearTimeout(deadline); children.delete(job.id); }
     if (exit.error) throw exit.error;
-    const recovered = retainedCodexUsage(state, job, attempt);
+    const recovered = retainedUsage(state, job, attempt);
     if (!existsSync(resultPath)) return { outcome: 'blocked', ...usageFields(recovered || emptyUsage(attempt.execution, attempt.command), attempt.execution, attempt.command), summary: `Executor exited ${exit.code} without a result` };
     let outcome;
     try { outcome = JSON.parse(readFileSync(resultPath, 'utf8')); }