software-defence-factory 0.15.0 → 0.15.2

package/docs/definition.md

@@ -255,7 +255,7 @@ The binding contract supports at most 16 named, keyless HTTP(S) endpoints. URLs
 with user information, queries, fragments, escapes or malformed syntax are refused.
 Model identifiers cannot contain shell syntax, whitespace or traversal. Context
 must be 1,024–1,048,576 tokens; output must be 1–32,000 and smaller than context.
-The output ceiling follows pinned Pi 0.73.1's simple chat adapter. Range acceptance
+The output ceiling remains 32,000 with the pinned Pi 0.87.1 chat adapter. Range acceptance
 is **not** evidence of server allocation or useful task capacity. Only the three
 shown compatibility fields are supported. Authentication, custom headers, shell
 credential commands, arbitrary request fields, sampling overrides, custom thinking
@@ -271,7 +271,7 @@ The optional binding `reasoningEffort` accepts only these OpenAI-style requests:
 | `low`, `medium`, `high` | `reasoning_effort` set to that exact value |
 
 This is a request choice, not a measured thinking budget or quality claim. The
-pinned Pi 0.73.1 adapter uses a fixed internal `thinkingLevelMap.off="none"` for
+pinned Pi 0.87.1 adapter uses a fixed internal `thinkingLevelMap.off="none"` for
 `none`; `--thinking off` alone does **not** disable a server's default thinking.
 Low/medium/high use the corresponding explicit Pi thinking level. Existing
 bindings with no choice retain their omitted request and private policy shape;
@@ -295,7 +295,12 @@ For the selected local role only, the executor creates a private single-model
 `models.json` and deterministic launcher, mounted read-only at `/factory-local`.
 `PI_CODING_AGENT_DIR` selects that directory; HOME is still ephemeral. The launcher
 checks explicit provider/model argv, removes inherited credential/override inputs
-and propagates Pi JSON provider failures even if Pi exits zero. The registry uses
+and requires a completed JSON turn even if Pi exits zero. Explicit successful
+retry/overflow recovery can clear an assistant error; failed/aborted compaction,
+exhausted retries, malformed/truncated JSONL and missing completion remain failures.
+The original event stream is retained in the bounded private log. The launcher also
+passes the fixed placeholder as Pi's supported runtime `--api-key`, avoiding a
+credential-store refresh against the read-only registry. No credentials are added. The registry uses
 Pi's required fixed non-secret key placeholder (`factory-local-keyless`), which may
 be sent as a bearer value; this is not endpoint authentication. No host home, provider
 catalog or credential store is mounted. Repository files cannot replace this mount.
@@ -308,3 +313,9 @@ automatic skills/extensions/templates but explicitly adds `--skill /factory-skil
 preserving the six packaged skills. Recommendations remain guidance, not per-role
 access controls. Build still returns to Factory's independent Review and operator
 handoff; no duplicate review workflow is launched.
+
+
+For long tool-use runs, use the [context-boundary qualification and image migration
+recipe](setup.md#local-context-budget-and-worker-image-0152-100). Declared context
+and output budgets are the same shared binding fields in CLI, API and dashboard;
+there are no Factory compaction knobs or automatic larger-window/model choices.

package/docs/npm.md

@@ -94,6 +94,18 @@ jobs and history are preserved. Existing processes keep their original code.
 Set `SDF_AUTO_UPDATE=0` to skip automatic network checks for a command.
 Source checkouts remain managed by Git and do not update themselves.
 
+The exact selected release is downloaded with npm's `--prefer-online` metadata
+refresh and `--prefer-offline=false`; this does not change account settings.
+An `ETARGET` visibility failure
+gets at most three attempts, separated by one second, within the same total
+120-second download budget (including waits). Offline, authentication and package
+identity errors are not retried by Factory. A successful download must match the
+requested package name, version and CLI entry before immutable adoption. Exhaustion
+cleans only that download's staging directory and retains the selected runtime,
+configuration and job history. Managed updates release their idle reservations on
+download failure; normal reservation/recovery rules in [services](services.md)
+still apply. The retries add no extra download maintenance budget.
+
 CLI updates do not rebuild or update Docker images automatically. Stop the
 installation and run `install --state PATH` when intentionally adopting a new
 runtime image; repeat the relevant qualification before resuming jobs. Install retains the old and new
@@ -104,8 +116,8 @@ installation or retained attempt needs them.
 
 ## Protected evidence compatibility
 
-Factory 0.15.0 recognizes version-1 execution profiles emitted by native
-**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 and 0.15.0**. This is an exact allowlist in
+Factory 0.15.2 recognizes version-1 execution profiles emitted by native
+**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 and 0.15.2**. This is an exact allowlist in
 `factory/execution-profile.mjs`, independent of the installed package version;
 it is not a semver range or an automatic promise for later releases. Unknown
 runtime strings, unknown profile formats and incomplete legacy acceptance
@@ -172,7 +184,7 @@ Verify evidence and cannot authorize acceptance or publication.
 
 Version 0.14.0 preserves the v1 writer only for unchanged inherited installations:
 policy bytes, candidate/check/review/acceptance bindings, mounts and credential
-rules stay compatible. Adopted role overrides use **v2 from 0.14.0 and 0.15.0**, recording
+rules stay compatible. Adopted role overrides use **v2 from 0.14.0, 0.15.0, 0.15.1 and 0.15.2**, recording
 role/provider/effort and an exact selection digest. The executor verifies the
 frozen common configuration before phase selection; continuation and both delivery
 validation paths require matching protected v2 evidence and private frozen config.
@@ -199,6 +211,15 @@ publishes an increased `package.json` version. Existing versions are skipped;
 registry errors fail the release instead of masquerading as a missing version.
 The workflow can also be started manually from `main`.
 
+An accepted npm publication may still be processing. It is not yet a verified,
+downloadable release: exact-version and `latest` metadata can appear at different
+times, and an npm install can briefly report `ETARGET` even after both appear.
+Verify an exact package download and compare its contents with the reviewed
+artifact before reporting release availability. If the bounded updater reports
+that the release is not yet downloadable, retain the prior runtime and retry the
+update later. This does not establish whether a particular delay came from a
+local cache or registry propagation.
+
 For a release, update both manifests with `npm version patch --no-git-tag-version`,
 review the change, and push through the project's normal review flow. A code
 push without a version bump is tested but does not overwrite a published package.
@@ -233,7 +254,7 @@ The 0.15.0 compatibility audit preserves unchanged v1/v2 policy construction,
 protected checks, candidate reconstruction, read-only review and acceptance guards.
 Historical 0.14.0 v2 validation compares its actual writer version rather than
 relabeling it as the installed version. Local registry selection is a new execution
-contract: every phase of a local/hybrid attempt requires **v3 from 0.15.0** and its
+contract: every phase of a local/hybrid attempt requires **v3 from 0.15.0, 0.15.1 or 0.15.2** and its
 exact protected frozen configuration. v1/v2 cannot attest local binding fields,
 providers or a common policy containing a selected local role. A selected endpoint,
 model, limit or compatibility change invalidates the current policy; explicit
@@ -241,3 +262,23 @@ rollback can restore it without editing historical evidence. Controlled regressi
 exercise legacy v2 readback and local v3 rejection/tamper cases. Installed-package
 Docker and independent Review remain delivery qualification, not inferred from this
 compatibility audit.
+
+The 0.15.1 patch changes release downloads and preserves the 0.15.0 v1/v2/v3
+writers, frozen configuration and policy bytes. The explicit allowlists include
+both patch versions; supported v3 readback retains the original writer version
+while still comparing every execution selection, phase and policy field. It does
+not rewrite historical evidence or allow v1/v2 to attest local bindings.
+
+
+The 0.15.2 compatibility audit adds that exact writer to the v1/v2/v3 allowlists.
+It changes the local launcher's interpretation of explicit recovery/completion
+and the standard image recipe, without changing the admitted command, binding
+schema, frozen config/image/selection/policy hashes, protected checks, candidate
+reconstruction or independent review/acceptance guards. Historical 0.15.0 and
+0.15.1 evidence remains readable with its original bytes and writer version;
+readability does not qualify those images for long local tasks. Regression cases
+exercise inherited, cloud-role, hybrid and local profiles through all phases,
+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).

package/docs/setup.md

@@ -430,3 +430,75 @@ leaves Pi usage unknown; controlled protocol fixtures are not token or quality
 benchmarks. Include cloud Review in hybrid totals. No provider token billing for
 local inference does not mean zero electricity, hardware or operator cost. Only
 then qualify a suitable real Factory issue; no customer jobs are part of this slice.
+
+
+## Local context budget and worker image (0.15.2, #100)
+
+The standard worker recipe pins **`@earendil-works/pi-coding-agent@0.87.1`** from
+[earendil-works/pi](https://github.com/earendil-works/pi/tree/v0.87.1), replacing
+`@mariozechner/pi-coding-agent@0.73.1`. Pi requires **Node >=22.19.0**; the image
+installation enforces dependency engines. Factory's controller Node requirement
+is unchanged. The separate Codex pin remains **0.156.1**. A CLI upgrade does not
+rebuild or replace an admitted job image. Source transport proof is documented in
+[proof](proof.md#pi-context-boundary-first-slice-0152-100); installed image and real
+local-model qualification are separate acceptance gates.
+
+Set the selected private binding's `contextWindow` no higher than the server's
+**actually allocated** context for that exact model/request, and set `maxTokens`
+within both endpoint support and available headroom. These existing fields have
+the same CLI/API/dashboard validation and frozen policy. An advertised registry
+window allocates no server memory. For Ollama, configure allocation through its
+supported server/model controls and inspect the running allocation with
+`ollama ps`; see [Ollama context length](https://docs.ollama.com/context-length).
+Factory does not pass an undocumented `num_ctx`, patch a model template or tune
+the host. Unsupported endpoint controls require an explicit capability limit.
+
+Pi 0.87.1's upstream defaults reserve 16,384 tokens and keep approximately 20,000
+recent tokens. At a declared 65,536, its threshold is 49,152, checked **after tool
+results and before the next assistant request in the same run**. This repairs a
+missing check in 0.73.1; increasing its reserve alone cannot add that check. Output
+reservation, tool-result growth, system/tools overhead and summarization must all
+fit the allocation. Prefix compaction alone cannot shrink one large retained
+assistant/tool-result group. The bundled local adapter therefore projects tool
+text into a conservative byte budget before generation and summarization, keeping
+the exact task and tool identities/order. Truncation notices tell the model to
+re-read with offset/limit or narrower queries; raw events/files stay independent
+of this projection. Every request reserves the full configured output, includes
+schemas/arguments and adds template headroom. This is conservative estimation,
+not measured token usage or an allocation/completion guarantee. Unshrinkable
+instructions/arguments fail explicitly rather than being silently removed.
+Pi estimates native history before the wire projection and can reduce output to
+one token. The adapter restores the selected generation allowance only with a
+fitting final payload; explicit upstream summary caps stay bounded separately.
+Both admitted `max_tokens` and `max_completion_tokens` compatibility fields are
+supported. The existing OpenAI `reasoning_effort` selection remains inside that
+total output ceiling; no extra reasoning allowance is added. Numeric/nested
+thinking-budget formats are unsupported and fail explicitly instead of being
+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).
+
+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`
+while idle. The normal install path retains the previously selected image. Plain
+`factory install` builds the standard recipe, now tagged `software-defence-factory-job:0.4.0`;
+updating the CLI alone does neither. Confirm the selected image ID and `pi --version`
+in that image. The protected local launcher requires exactly 0.87.1 and loads only
+its bundled read-only adapter with automatic extension discovery disabled. Missing
+adapter files or an older worker image fail explicitly; old evidence remains
+readable and cloud profiles keep their existing wrapper. Roll back with the retained old image through the same idle install
+path and restore the previously working role definition through revision-guarded
+rollback. Do not change frozen attempts or relabel old failed results.
+
+Lead's bounded actual-inference fixture must include enough tool results to trigger
+summarization, resumed useful tool work, the required report, checks and independent
+Review. Record the exact image/model digest, harness/server versions, allocated
+window, output/reasoning request, tool growth, compaction ordering, elapsed time,
+quality outcome and peak memory; unknown measurements remain null. Set an explicit
+job deadline/resource budget and preserve any unfinished checkout and diagnostic
+artifacts. A short successful prompt is insufficient. A larger actually allocated
+window is a later measured comparison only if this evidence warrants it; do not
+switch model or cloud provider automatically. The failed #83 local attempt is not
+local delivery. An operator-selected fresh cloud retry and unfinished-checkpoint
+recovery remain governed by [recovery](recovery.md) and #42.

package/factory/execution-profile.mjs

@@ -21,16 +21,19 @@ import { expectedWebStories, webPolicyHash } from './web-verification.mjs';
 // selection digest. V1 can never attest an adopted role override.
 // 0.15.0 keeps unchanged v1/v2 policies and writers; local selections require
 // v3 for every phase. Legacy evidence cannot attest the new registry/launcher.
+// 0.15.1 changes release downloads only; v1/v2/v3 writers and policy are unchanged.
+// 0.15.2 updates the opt-in local launcher and standard image; schemas, frozen
+// command/config/image hashes, protected 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']);
+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']);
 
 export function isSupportedExecutionProfile(profile) {
-  if ([2, 3].includes(profile?.version)) return (profile.version === 3 ? profile.runtimeVersion === '0.15.0' && Object.hasOwn(profile, 'localBinding')
-    : ['0.14.0', '0.15.0'].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'].includes(profile.runtimeVersion) && Object.hasOwn(profile, 'localBinding')
+    : ['0.14.0', '0.15.0', '0.15.1', '0.15.2'].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 || '');
@@ -132,7 +135,7 @@ export function assertFrozenExecution(config, execution, phase) {
   delete expected.hostName;
   // Audited legacy writers retain their real version. Never let v1/v2 attest
   // a local binding, including a deterministic phase of a hybrid attempt.
-  if (expected.version < 3 && isSupportedExecutionProfile(execution) && execution.version === expected.version)
+  if (isSupportedExecutionProfile(execution) && execution.version === expected.version)
     expected.runtimeVersion = execution.runtimeVersion;
   const actual = { ...execution }; delete actual.hostName; delete actual.workerName;
   if (!isDeepStrictEqual(expected, actual)) throw new Error('Admitted execution profile does not match this attempt');

package/factory/executor.mjs

@@ -110,6 +110,8 @@ async function container(mode, input, command, options = {}) {
       mkdirSync(localDirectory, { mode: 0o700 });
       const { reference, ...binding } = config.localBinding;
       writeFileSync(join(localDirectory, 'launch.mjs'), readFileSync(join(ROOT, 'factory/pi-local-launch.mjs')), { mode: 0o600, flag: 'wx' });
+      for (const file of ['pi-context-extension.mjs', 'pi-context-budget.mjs'])
+        writeFileSync(join(localDirectory, file), readFileSync(join(ROOT, 'factory', file)), { mode: 0o600, flag: 'wx' });
       writeFileSync(join(localDirectory, 'models.json'), JSON.stringify(localRegistry(binding)), { mode: 0o600, flag: 'wx' });
       args.push('--mount', `type=bind,source=${localDirectory},target=${LOCAL_AGENT_DIR},readonly`,
         '--env', `PI_CODING_AGENT_DIR=${LOCAL_AGENT_DIR}`);

package/factory/image/Dockerfile

@@ -1,7 +1,7 @@
 FROM node:22-bookworm-slim@sha256:43ac6c60b8f89723f746e8a92ce91abd5017e627ce1ddfe4238355d3a30b772c
 RUN apt-get update && apt-get install -y --no-install-recommends git python3 python3-venv ca-certificates procps \
     && rm -rf /var/lib/apt/lists/* \
-    && npm install --global @openai/codex@0.156.1 @mariozechner/pi-coding-agent@0.73.1 \
+    && npm install --global --engine-strict @openai/codex@0.156.1 @earendil-works/pi-coding-agent@0.87.1 \
     && npm cache clean --force
 COPY mock.mjs /opt/factory/mock.mjs
 USER node

package/factory/pi-context-budget.mjs

@@ -0,0 +1,75 @@
+// Request projection only. Never change raw tool events, files or session entries.
+// UTF-8 bytes (not characters/4) conservatively cover text tokenization; explicit
+// framing headroom also covers chat templates. This is a budget, not usage.
+export const bytes = value => Buffer.byteLength(JSON.stringify(value), 'utf8');
+export const projectedTokens = payload => bytes(payload) + 1024
+  + 64 * ((payload.messages?.length || 0) + (payload.tools?.length || 0));
+
+// Pi 0.87.1 clamps against native history BEFORE onPayload. Recover the caller's
+// allowance, not that obsolete clamp. Explicit summary caps remain explicit.
+// Only the selected adapter's OpenAI effort control is supported: numeric or
+// nested thinking budgets could also have been clamped and must not be guessed.
+export function restoreOutputBudget(payload, configured, requested, reasoning) {
+  const field = configured.compat.maxTokensField;
+  const fields = ['max_tokens', 'max_completion_tokens'].filter(key => Object.hasOwn(payload, key));
+  if (!Number.isSafeInteger(requested) || requested < 1 || requested > configured.maxTokens
+    || fields.length !== 1 || fields[0] !== field
+    || !Number.isSafeInteger(payload[field]) || payload[field] < 1 || payload[field] > requested)
+    throw new Error('Unsupported local output budget; refusing to override selected limits');
+  if ((reasoning !== undefined && !['off', 'low', 'medium', 'high'].includes(reasoning))
+    || ['reasoning', 'thinking', 'thinking_token_budget', 'reasoning_budget', 'chat_template_kwargs', 'chat_template_args', 'enable_thinking']
+      .some(key => Object.hasOwn(payload, key)))
+    throw new Error('Unsupported local reasoning budget; qualify the endpoint controls before use');
+  const effort = configured.reasoning
+    ? (!reasoning || reasoning === 'off' ? configured.thinkingLevelMap?.off : reasoning) : undefined;
+  if (payload.reasoning_effort !== effort)
+    throw new Error('Local reasoning effort does not match the selected request');
+  payload[field] = requested;
+}
+
+function excerpt(text, limit) {
+  if (text.length <= limit) return text;
+  // Do not split a UTF-16 surrogate pair. JSON escaping is counted afterward.
+  const prefix = text.slice(0, limit).replace(/[\uD800-\uDBFF]$/, '');
+  const shortened = `${prefix}\n[Factory context projection: shortened tool result (${Buffer.byteLength(text, 'utf8')} original UTF-8 bytes). Raw tool event is unchanged; source files are unchanged by projection. Do not infer omitted contents. Re-read the original path with read offset/limit (start with limit: 40), or run a narrower query; keep subsequent batches small.]`;
+  return Buffer.byteLength(shortened) < Buffer.byteLength(text) ? shortened : text;
+}
+
+// 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) {
+  const original = structuredClone(value);
+  if (measure(original) <= budget) return original;
+  const messages = Array.isArray(original) ? original : original.messages;
+  const slots = [];
+  for (const message of messages) {
+    if (message.role !== (native ? 'toolResult' : 'tool')) continue;
+    if (typeof message.content === 'string') slots.push([message, 'content', message.content]);
+    else if (Array.isArray(message.content)) {
+      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); };
+  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) {
+    const mid = Math.ceil((low + high) / 2); cap(mid);
+    if (measure(original) <= budget) low = mid; else high = mid - 1;
+  }
+  cap(low);
+  return original;
+}
+
+export function validatePairs(messages) {
+  const pending = new Set(), seen = new Set();
+  for (const message of messages) {
+    if (message.role !== 'tool' && pending.size) throw new Error('Local Pi context has interrupted tool pairs');
+    for (const call of message.tool_calls || []) {
+      if (!call.id || seen.has(call.id)) throw new Error('Local Pi context has duplicate tool identity');
+      pending.add(call.id); seen.add(call.id);
+    }
+    if (message.role === 'tool' && !pending.delete(message.tool_call_id)) throw new Error('Local Pi context has orphan tool result');
+  }
+  if (pending.size) throw new Error('Local Pi context has missing tool results');
+}

package/factory/pi-context-extension.mjs

@@ -0,0 +1,64 @@
+// Explicitly mounted Factory adapter, never discovered from the host/repository.
+import { readFileSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+import { openAICompletionsApi } from '@earendil-works/pi-ai';
+import { bytes, fitToolText, projectedTokens, restoreOutputBudget, validatePairs } from './pi-context-budget.mjs';
+
+export default function factoryLocalContext(pi) {
+  const registry = JSON.parse(readFileSync(join(process.env.PI_CODING_AGENT_DIR, 'models.json'), 'utf8'));
+  const configured = registry.providers['factory-local'].models[0];
+  const window = configured.contextWindow, output = configured.maxTokens;
+  let task;
+  // 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.on('session_before_compact', event => {
+    try {
+      // These are request-local copies. Upstream still selects cut points and
+      // generates the summary. Reserve space for its pinned summary templates;
+      // the provider wrapper checks the exact serialized request as well.
+      const preparation = event.preparation;
+      const budget = window - output - 8192 - bytes(preparation.previousSummary || '');
+      for (const key of ['messagesToSummarize', 'turnPrefixMessages'])
+        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); }
+        },
+      });
+    },
+  });
+  // 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

@@ -1,48 +1,143 @@
-// Mounted read-only beside the single selected registry. Pi 0.73.1 JSON mode
-// may exit zero after a provider error; preserve the stream but fail the job.
+// Mounted read-only beside the single selected registry. Keep all JSON evidence;
+// process exit alone does not establish a successfully completed Pi turn.
 import { readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { spawn } from 'node:child_process';
-const directory = dirname(fileURLToPath(import.meta.url));
-const registry = JSON.parse(readFileSync(join(directory, 'models.json'), 'utf8'));
-const provider = registry.providers?.['factory-local'];
-const args = process.argv.slice(2);
-const selected = flag => args.filter(arg => arg === flag).length === 1 ? args[args.indexOf(flag) + 1] : null;
-const model = provider?.models?.[0];
-const thinking = selected('--thinking');
-const validThinking = model?.reasoning && model?.thinkingLevelMap?.off !== 'none'
-  ? ['low', 'medium', 'high'].includes(thinking) : thinking === 'off';
-if (Object.keys(registry.providers || {}).length !== 1 || provider?.models?.length !== 1
-  || selected('--provider') !== 'factory-local' || selected('--model') !== provider.models[0].id
-  || selected('--mode') !== 'json' || !validThinking)
-  throw new Error('Local Pi registry and explicit selection do not match; refusing fallback');
-// Never inherit credential inputs, provider overrides, NODE_OPTIONS or external
-// Pi directories. The runtime image supplies binaries; the repository supplies data.
-const env = Object.fromEntries(['PATH', 'HOME', 'LANG', 'TMPDIR', 'FACTORY_PHASE'].filter(key => process.env[key] !== undefined).map(key => [key, process.env[key]]));
-env.PI_CODING_AGENT_DIR = directory;
-const child = spawn('pi', args, { env, stdio: ['inherit', 'pipe', 'inherit'] });
-let pending = '', failed = false, completed = false;
-const event = line => {
-  if (!line.trim()) return;
-  try {
-    const value = JSON.parse(line);
-    if (value.type === 'message_end' && value.message?.role === 'assistant'
-      && ['error', 'aborted'].includes(value.message.stopReason)) failed = true;
-    if (value.type === 'agent_end') completed = true;
-  } catch { failed = true; }
-};
-child.stdout.setEncoding('utf8');
-child.stdout.on('data', chunk => {
-  process.stdout.write(chunk);
-  pending += chunk;
-  let end;
-  while ((end = pending.indexOf('\n')) !== -1) { event(pending.slice(0, end)); pending = pending.slice(end + 1); }
-  if (pending.length > 1024 * 1024) { failed = true; pending = ''; }
-});
-child.on('error', error => { console.error(`Local Pi launch failed: ${error.message}`); process.exitCode = 1; });
-child.on('close', code => {
-  if (pending) event(pending);
-  if (failed || !completed) console.error('Local Pi did not complete successfully; inspect the private log. No fallback was selected.');
-  process.exitCode = code === 0 && !failed && completed ? 0 : (Number.isInteger(code) && code > 0 ? code : 1);
-});
+import { spawn, spawnSync } from 'node:child_process';
+
+// A long run can emit a multi-megabyte agent_end aggregate even after compaction.
+// Bound parsing separately from the much smaller retained diagnostic log.
+const MAX_EVENT_CHARACTERS = 8 * 1024 * 1024;
+
+// Pi 0.73.1 and 0.87.1 print JSONL. Errors can precede explicit recovery, but
+// aborted/failed compaction, invalid framing and incomplete recovery stay fatal.
+export class PiCompletion {
+  pending = '';
+  failed = false;
+  error = false;
+  retry = false;
+  compacting = false;
+  compactionReason = null;
+  recovery = false;
+  completed = false;
+  modern = false;
+  settled = false;
+  lastAssistant = null;
+  contextReady = false;
+
+  write(chunk) {
+    this.pending += chunk;
+    let end;
+    while ((end = this.pending.indexOf('\n')) !== -1) {
+      const line = this.pending.slice(0, end);
+      this.pending = this.pending.slice(end + 1);
+      if (line.length > MAX_EVENT_CHARACTERS) this.failed = true;
+      else if (line.trim()) {
+        try { this.event(JSON.parse(line)); } catch { this.failed = true; }
+      }
+    }
+    if (this.pending.length > MAX_EVENT_CHARACTERS) { this.failed = true; this.pending = ''; }
+  }
+
+  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 === 'agent_start' || value.type === 'message_start') {
+      this.completed = false; this.settled = false;
+    }
+    if (value.type === 'message_end' && (!value.message || typeof value.message.role !== 'string')) this.failed = true;
+    if (value.type === 'message_end' && value.message?.role === 'assistant') {
+      this.completed = false;
+      this.settled = false;
+      this.lastAssistant = value.message;
+      if (!['stop', 'toolUse', 'length', 'error', 'aborted'].includes(value.message.stopReason) || !Array.isArray(value.message.content)) this.failed = true;
+      if (value.message.stopReason === 'aborted') this.failed = true;
+      else if (['error', 'length'].includes(value.message.stopReason)) { this.error = true; this.recovery = false; }
+      else if (['stop', 'toolUse'].includes(value.message.stopReason)) {
+        if (this.error && (this.retry || this.recovery)) this.error = false;
+        this.recovery = false;
+      }
+    }
+    if (value.type === 'auto_retry_start') { this.retry = true; this.completed = false; this.settled = false; }
+    if (value.type === 'auto_retry_end') {
+      if (!this.retry || value.success !== true) this.failed = true;
+      this.retry = false;
+    }
+    // Both audited versions use compaction_*; retain the older public alias
+    // defensively so failed compaction never disappears as an ignored event.
+    if (['compaction_start', 'auto_compaction_start'].includes(value.type)) {
+      if (this.compacting || !['manual', 'threshold', 'overflow'].includes(value.reason)) this.failed = true;
+      this.compactionReason = value.reason;
+      this.compacting = true; this.settled = false;
+    }
+    if (['compaction_end', 'auto_compaction_end'].includes(value.type)) {
+      if (!this.compacting || value.reason !== this.compactionReason || typeof value.willRetry !== 'boolean'
+        || value.aborted !== false || value.errorMessage
+        || !value.result || typeof value.result.summary !== 'string' || !value.result.summary.trim()) this.failed = true;
+      this.compacting = false;
+      if (value.reason === 'overflow' && value.willRetry === true && !this.failed) this.recovery = true;
+    }
+    if (value.type === 'agent_end') {
+      this.settled = false;
+      if (Object.hasOwn(value, 'willRetry')) {
+        this.modern = true;
+        if (typeof value.willRetry !== 'boolean') this.failed = true;
+      }
+      const last = value.messages?.at(-1);
+      this.completed = value.willRetry !== true && last?.role === 'assistant' && last.stopReason === 'stop'
+        && this.lastAssistant?.stopReason === 'stop'
+        && JSON.stringify(last) === JSON.stringify(this.lastAssistant)
+        && Array.isArray(last.content) && last.content.some(part => part.type === 'text' && part.text?.trim())
+        && !last.content.some(part => part.type === 'toolCall');
+    }
+    if (value.type === 'agent_settled') this.settled = true;
+  }
+
+  finish() {
+    return !this.pending && !this.failed && !this.error && !this.retry && !this.compacting && !this.recovery
+      && this.completed && (!this.modern || this.settled);
+  }
+}
+
+function launch() {
+  const directory = dirname(fileURLToPath(import.meta.url));
+  const registry = JSON.parse(readFileSync(join(directory, 'models.json'), 'utf8'));
+  const provider = registry.providers?.['factory-local'];
+  const args = process.argv.slice(2);
+  const selected = flag => args.filter(arg => arg === flag).length === 1 ? args[args.indexOf(flag) + 1] : null;
+  const model = provider?.models?.[0];
+  const thinking = selected('--thinking');
+  const validThinking = model?.reasoning && model?.thinkingLevelMap?.off !== 'none'
+    ? ['low', 'medium', 'high'].includes(thinking) : thinking === 'off';
+  if (Object.keys(registry.providers || {}).length !== 1 || provider?.models?.length !== 1
+    || selected('--provider') !== 'factory-local' || selected('--model') !== provider.models[0].id
+    || selected('--mode') !== 'json' || !validThinking)
+    throw new Error('Local Pi registry and explicit selection do not match; refusing fallback');
+  // Never inherit credential inputs, provider overrides, NODE_OPTIONS or external
+  // Pi directories. The runtime image supplies binaries; the repository supplies data.
+  const env = Object.fromEntries(['PATH', 'HOME', 'LANG', 'TMPDIR', 'FACTORY_PHASE'].filter(key => process.env[key] !== undefined).map(key => [key, process.env[key]]));
+  env.PI_CODING_AGENT_DIR = directory;
+  for (const file of ['pi-context-extension.mjs', 'pi-context-budget.mjs']) readFileSync(join(directory, file));
+  const version = spawnSync('pi', ['--version'], { env, encoding: 'utf8', timeout: 10000 });
+  if (version.status !== 0 || version.stdout.trim() !== '0.87.1')
+    throw new Error('Local context protection requires pinned Pi 0.87.1; qualify and select the worker image while idle. No fallback.');
+  // The explicit non-secret runtime key bypasses Pi 0.87.1's credential-store
+  // refresh, which otherwise tries to lock auth.json in this read-only mount.
+  // --no-extensions still disables discovery. Only this read-only bundled path
+  // is explicitly enabled; it cannot load repository or host extensions.
+  const child = spawn('pi', [...args, '--extension', join(directory, 'pi-context-extension.mjs'), '--api-key', 'factory-local-keyless'], { env, stdio: ['inherit', 'pipe', 'inherit'] });
+  const completion = new PiCompletion();
+  child.stdout.setEncoding('utf8');
+  child.stdout.on('data', chunk => {
+    process.stdout.write(chunk);
+    completion.write(chunk);
+  });
+  child.on('error', error => { console.error(`Local Pi launch failed: ${error.message}`); process.exitCode = 1; });
+  child.on('close', code => {
+    const completed = completion.contextReady && completion.finish();
+    if (!completed) console.error('Local Pi did not complete successfully; inspect the private log. No fallback was selected.');
+    process.exitCode = code === 0 && completed ? 0 : (Number.isInteger(code) && code > 0 ? code : 1);
+  });
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) launch();

package/factory/pins.json

@@ -1,3 +1,3 @@
 {
-  "jobImage": "software-defence-factory-job:0.3.0"
+  "jobImage": "software-defence-factory-job:0.4.0"
 }

package/factory/updates.mjs

@@ -65,17 +65,33 @@ function installedEntry(dataHome, version) {
     return pkg.name === PACKAGE && pkg.version === version && existsSync(entry) ? entry : null;
   } catch { return null; }
 }
-export function installRelease(version, dataHome = DATA_HOME, runner = spawnSync) {
+export function installRelease(version, dataHome = DATA_HOME, runner = spawnSync, {
+  now = () => performance.now(),
+  sleep = ms => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms),
+} = {}) {
   if (!/^\d+\.\d+\.\d+$/.test(version)) throw new Error('Invalid release version');
   const existing = installedEntry(dataHome, version);
   if (existing) return existing;
   const releases = join(dataHome, 'releases'); privateDir(releases);
   const staging = mkdtempSync(join(releases, '.download-'));
   try {
-    const result = runner('npm', ['install', '--prefix', staging, '--no-save', '--package-lock=false',
-      '--ignore-scripts', '--omit=dev', '--no-audit', '--no-fund', '--registry', REGISTRY, `${PACKAGE}@${version}`],
-      { encoding: 'utf8', timeout: 120000, maxBuffer: 1024 * 1024 });
-    if (result.error || result.status !== 0) throw new Error(`npm update download failed: ${result.error?.message || result.stderr || result.status}`);
+    // Metadata refresh and visibility retries share the original download budget.
+    // Only ETARGET is retried; offline/auth/identity failures keep their own errors.
+    const deadline = now() + 120000;
+    for (let attempt = 1; attempt <= 3; attempt++) {
+      const remaining = Math.floor(deadline - now());
+      if (remaining <= 0) throw new Error(`npm update download failed for ${PACKAGE}@${version}: 120-second download budget exhausted`);
+      const result = runner('npm', ['install', '--prefix', staging, '--no-save', '--package-lock=false',
+        '--ignore-scripts', '--omit=dev', '--no-audit', '--no-fund', '--prefer-online', '--prefer-offline=false', '--registry', REGISTRY, `${PACKAGE}@${version}`],
+        { encoding: 'utf8', timeout: remaining, killSignal: 'SIGKILL', maxBuffer: 1024 * 1024 });
+      if (!result.error && result.status === 0) break;
+      const detail = result.error?.message || result.stderr || result.status;
+      const visibilityDelay = !result.error && /^npm (?:ERR!|error) code ETARGET\s*$/m.test(result.stderr || '');
+      if (!visibilityDelay) throw new Error(`npm update download failed for ${PACKAGE}@${version}: ${detail}`);
+      if (attempt === 3 || deadline - now() <= 1000)
+        throw new Error(`npm release ${PACKAGE}@${version} is not yet downloadable; publication may still be processing. Retry the update later. ${detail}`);
+      sleep(1000);
+    }
     const pkg = read(join(staging, 'node_modules', PACKAGE, 'package.json'));
     if (pkg.name !== PACKAGE || pkg.version !== version || !existsSync(join(staging, 'node_modules', PACKAGE, 'bin/software-defence-factory.mjs')))
       throw new Error('Downloaded package identity does not match the requested release');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "software-defence-factory",
-  "version": "0.15.0",
+  "version": "0.15.2",
   "description": "Factory: scoped software delivery and defence investigations with isolated jobs, evidence and review",
   "type": "module",
   "license": "MIT",
@@ -57,7 +57,8 @@
     "test": "node --test tests/*.test.mjs",
     "check": "node scripts/check.mjs && node --test tests/*.test.mjs && npm run test:dashboard",
     "build:dashboard": "npm --prefix dashboard ci --ignore-scripts && npm --prefix dashboard run build",
-    "test:dashboard": "npm --prefix dashboard test"
+    "test:dashboard": "npm --prefix dashboard test",
+    "qualify:pi": "FACTORY_REQUIRE_PI=1 node --test tests/pi-local-adapter.test.mjs tests/pi-context.test.mjs tests/pi-context-batch.test.mjs"
   },
   "dependencies": {
     "yaml": "2.9.1"