software-defence-factory 0.14.0 → 0.15.0

package/README.md

@@ -48,7 +48,7 @@ The runtime supplies policy and six focused skills to its isolated jobs. `init`
 
 Each result belongs to a specific candidate commit and policy. A failed check blocks delivery. Changing the candidate or check policy invalidates earlier evidence. Approval records a handoff; publishing, merging and deployment follow the application's separate authority.
 
-The project dashboard has an **Inbox**, measured **Analytics**, **Agents**, **Skills**, **Automations**, **Definition** and **Infrastructure**. Inbox opens on a shared list/board of loaded repository issues and local work, with status, search and checkbox filters, readiness and linked execution attempts. New issue offers repository templates or a blank creation form. Create an issue on the supported repository provider, then choose Start work separately; local brief execution remains available. CLI `issue` exposes the same intake. Definition lives with settings above the theme control. The CLI reads the same definition and controller state. Agent roles use a selected harness such as Codex or Pi; a worker executes their isolated jobs on a host. See [concepts](docs/concepts.md) and [supported interfaces](docs/interfaces.md). Optional automations belong to the selected harness, which calls Factory CLI/API. Factory runs no cron scheduler. See [provider boundaries](docs/integrations.md).
+The project dashboard has an **Inbox**, measured **Analytics**, **Agents**, **Skills**, **Automations**, **Definition** and **Infrastructure**. Inbox opens on a shared list/board of loaded repository issues and local work, with status, search and checkbox filters, readiness and linked execution attempts. New issue offers repository templates or a blank creation form. Create an issue on the supported repository provider, then choose Start work separately; local brief execution remains available. CLI `issue` exposes the same intake. Definition lives with settings above the theme control. The CLI reads the same definition and controller state. Agent roles use a selected harness such as Codex or Pi, with opt-in private keyless local bindings for local/hybrid setups; a worker executes their isolated jobs on a host. See [concepts](docs/concepts.md) and [supported interfaces](docs/interfaces.md). Optional automations belong to the selected harness, which calls Factory CLI/API. Factory runs no cron scheduler. See [provider boundaries](docs/integrations.md).
 
 The optional **defence** workflow accepts scoped incident evidence and produces a private, read-only draft. It does not monitor production or claim verified recovery. See [defence integration](docs/defence-integration.md).
 

package/bin/software-defence-factory.mjs

@@ -202,19 +202,21 @@ try {
     if (command === 'definition' && positional.length) {
       const action = positional[0];
       if (!['export', 'validate', 'diff', 'apply', 'rollback'].includes(action) || positional.length !== 1) throw new Error('Choose definition export|validate|diff|apply|rollback');
-      let value;
+      let value, bindings;
       if (['validate', 'diff', 'apply'].includes(action)) {
         if (!flags.file) throw new Error('--file is required');
         value = JSON.parse(readFileSync(resolve(flags.file), 'utf8'));
+        if (flags['bindings-file']) bindings = JSON.parse(readFileSync(resolve(flags['bindings-file']), 'utf8'));
       }
       let result;
       if (action === 'export') result = inspectDefinition(state).definition;
       else if (action === 'rollback' && !flags['expected-revision']) result = previewRollback(state);
+      else if (action === 'validate' && bindings !== undefined && !existsSync(join(state, 'factory.json'))) throw new Error('Local binding validation requires an installation');
       else if (action === 'validate' && !existsSync(join(state, 'factory.json'))) result = { valid: true, definition: parseRoleDefinition(value), capabilities: ROLE_CAPABILITIES, resolution: 'Requires an installation for inherited settings' };
-      else if (['validate', 'diff'].includes(action)) result = previewDefinition(state, value);
+      else if (['validate', 'diff'].includes(action)) result = previewDefinition(state, value, bindings);
       else {
         if (!flags['expected-revision']) throw new Error('--expected-revision from the current preview is required');
-        result = await api(state, `/api/v1/definition/${action}`, { expected_revision: flags['expected-revision'], ...(action === 'apply' ? { definition: value } : {}) });
+        result = await api(state, `/api/v1/definition/${action}`, { expected_revision: flags['expected-revision'], ...(action === 'apply' ? { definition: value, ...(bindings === undefined ? {} : { local_bindings: bindings }) } : {}) });
       }
       console.log(JSON.stringify(result, null, 2));
       process.exit(0);
@@ -343,7 +345,7 @@ Compatibility executable: software-defence-factory (same runtime and state)
   web probe --state PATH                    Execute the pinned local Chromium readiness probe
   foundation                              Read the operator setup skill; no installation required
   definition | agents | skills            Inspect roles, instructions and installation settings
-  definition export|validate|diff          Portable roles; validate/diff require --file PATH
+  definition export|validate|diff          Portable roles; validate/diff require --file PATH; optional --bindings-file PRIVATE_PATH
   definition apply --file PATH --expected-revision HASH
   definition rollback --expected-revision HASH   Idle controller only
   inbox [--page N] [--issue-state open|closed|all] [--source inbox|factory]

package/docs/definition.md

@@ -1,4 +1,4 @@
-# Role definitions (0.14.0)
+# Role definitions (0.15.0)
 
 The portable definition selects harness/model profiles for **Implement**, **Review**
 and **Investigate**. CLI, local API and the existing Agents/Definition pages use
@@ -18,8 +18,8 @@ does not make skills, resources, access, workflow gates or schedules editable.
 
 The root accepts exactly `version` and `roles`. Version must be numeric `1`;
 role names are exactly `implement`, `review`, `investigate`. Missing roles and
-missing `harness` mean `inherit`. Each role accepts only `harness`, `model` and
-`reasoningEffort`; unknown fields, roles, versions and incompatible combinations
+missing `harness` mean `inherit`. Each role accepts only `harness`, `model`, `reasoningEffort` and
+`localBinding`; unknown fields, roles, versions and incompatible combinations
 fail explicitly. The authoritative implementation and capability matrix are in
 [role-definition.mjs](../factory/role-definition.mjs), not a second schema copy.
 
@@ -41,14 +41,16 @@ fail explicitly. The authoritative implementation and capability matrix are in
   positional prompt and duplicate model flags left by an effort-only selection
   are refused before adoption. Use the Codex preset or correct the private
   command while stopped. All-inherit commands remain byte-for-byte unchanged.
-- Explicit `codex` or `pi` uses the same maintained preset as `init`, even when
+- Explicit `codex` or hosted `pi` uses the same maintained preset as `init`, even when
   the installed harness has the same name. No command, path, privilege, network,
   credential or provider-authorization argument can enter the portable payload.
 - `model` is a user-selected identifier (1–128 identifier characters, no paths,
   URLs, whitespace or command switches). Omit it for the explicit harness default;
-  `null` also requests that default. Explicit Pi requires a supported
+  `null` also requests that default. Explicit hosted Pi requires a supported
   `provider/model` prefix so credential selection is unambiguous. For inherited Pi,
   a model must agree with any installed private `inferenceProvider`.
+- `localBinding` selects an explicitly adopted private keyless Pi binding instead
+  of a hosted model; see the opt-in contract below.
 - This slice exposes Codex `reasoningEffort` values `low`, `medium`, `high`, passed
   as `-c model_reasoning_effort="VALUE"`. Omission preserves private/default
   behavior; it does not attest a detected effort. Pi effort control is unavailable.
@@ -124,7 +126,7 @@ the complete new record and history are present. Incomplete temporary files are
 not loaded. The adopted record must be a regular private file; repository symlinks
 are refused. Revisions include a monotonic sequence and the private base settings,
 so an old revision is stale even after rollback. Back up the entire private state
-while stopped; rollback restores portable roles only, not separately edited base
+while stopped; rollback restores roles and adopted local bindings, not separately edited base
 settings, credentials or historical attempts. New reads do not use a startup cache.
 
 Before each attempt, trusted configuration resolves and freezes **all roles** in
@@ -135,7 +137,7 @@ phase settings. Protected v2 execution evidence records role, requested model,
 provider, explicit effort and a digest binding the exact private command selection.
 The executor checks that binding before launching. Role overrides require v2;
 old v1 evidence cannot attest them. Unchanged legacy configurations still emit
-v1 with the actual 0.14.0 runtime version. See [compatibility](npm.md#protected-evidence-compatibility).
+v1 with the actual installed runtime version. See [compatibility](npm.md#protected-evidence-compatibility).
 
 Changing a role invalidates prior acceptance/checkpoint evidence under that
 policy. Rollback can restore the exact prior policy; it never edits evidence or
@@ -149,8 +151,8 @@ existing task-model behavior.
 Only the selected provider's inference settings reach each agent phase. Codex
 account-auth data never reaches Pi, including Pi using OpenAI. Check and Handoff
 receive no inference credentials. Git/issue-provider identity remains on the
-controller. No new credentials, endpoint binding, model download or provider is
-created by a definition.
+controller. Portable roles create no credentials or model downloads. The opt-in local binding
+contract below explicitly adopts private endpoint details separately.
 
 ## Role and output boundaries
 
@@ -186,3 +188,123 @@ inspection in both themes remain separate gates. #53 stays open for per-role
 skills/resources/access, broader project/flow/automation definitions and readiness
 attestation. #69 owns local/hybrid model benchmarks, #51 measurement and #70
 improvement proposals.
+
+## Opt-in local bindings (0.15.0, #69)
+
+A portable role can select `{"harness":"pi","localBinding":"local-worker"}`
+instead of a hosted `model`. The same reference can serve Implement, Review and
+Investigate, or any role can retain Codex/a hosted Pi model for a hybrid setup.
+Binding references cannot be combined with a role model or reasoning effort.
+They require the maintained Pi preset; private wrappers are not binding adapters.
+
+Connection details belong to explicitly adopted **private installation state**,
+not the portable definition. No repository filename, issue or model response is
+an active configuration source. Save a private JSON binding map, for example:
+
+```json
+{
+  "local-worker": {
+    "endpoint": "http://operator-selected-host:8080/v1",
+    "model": "exact-installed-model-id",
+    "contextWindow": 32768,
+    "maxTokens": 4096,
+    "reasoningEffort": "default",
+    "compat": {
+      "maxTokensField": "max_tokens",
+      "supportsUsageInStreaming": true,
+      "requiresToolResultName": false
+    }
+  }
+}
+```
+
+These illustrative values are not defaults or measured recommendations. Select
+the endpoint, exact model and limits for your installation. `endpoint` is a base
+URL for OpenAI **chat completions**, not a full `/chat/completions` URL. The job's
+isolated network must reach it; its loopback address is not the host's loopback.
+Factory neither opens ports nor adjusts networking or inference services.
+
+```sh
+factory definition diff --state PRIVATE_STATE --file roles.json --bindings-file PRIVATE_BINDINGS.json
+factory definition apply --state PRIVATE_STATE --file roles.json --bindings-file PRIVATE_BINDINGS.json --expected-revision HASH_FROM_DIFF
+factory definition rollback --state PRIVATE_STATE --expected-revision CURRENT_HASH
+```
+
+`validate`, `diff` and `apply` accept `--bindings-file`. Without it they retain the
+installed binding map. Providing a map replaces it in full, so removing a referenced
+binding fails until its roles are changed in the same request. `export` includes
+only portable roles/references. CLI `definition` inspects private bindings locally.
+The authenticated API adds optional `local_bindings` beside `definition` to
+validate/diff/apply; `GET /api/v1/definition` returns both. Diff returns
+`binding_changes`. Unauthenticated `/api/v1/definitions` omits endpoint maps;
+authenticated readback includes them. The existing Agents/Definition editor uses
+this same contract and shows a binding diff before Apply, including connection-only
+changes. Configuration makes no inference/model-list requests and never starts work.
+
+Bindings and roles share one revision, idle check, atomic record and at most ten
+rollback snapshots. Rollback restores both together; stale/busy/invalid writes
+preserve the prior state. Endpoint normalization is idempotent; URLs whose normalized
+form contains forbidden escapes (including Unicode path characters) are rejected.
+The complete serialized record and history are validated before replacement.
+The version-2 private record reads old version-1 role
+records without rewriting them. An old runtime cannot read a newly adopted v2
+record: roll back profiles first and restore a stopped pre-upgrade private-state
+backup before downgrading binaries. Do not hand-edit histories or frozen attempts.
+
+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
+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
+maps and provider plugins are unsupported. Factory does not spoof local inference
+as the hosted OpenAI provider.
+
+The optional binding `reasoningEffort` accepts only these OpenAI-style requests:
+
+| Binding choice | Chat-completions request |
+| --- | --- |
+| Omitted or `default` | No `reasoning_effort` override; server default applies |
+| `none` | `reasoning_effort: "none"` |
+| `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
+`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;
+no default is inserted into their saved configuration. The binding editor,
+CLI/API diff, private readback, frozen selection and rollback share this choice.
+Separate role bindings can request different efforts. Endpoint support and actual
+behavior remain unqualified until tested on that installation. A server rejection
+fails the job without fallback or retrying with a different choice; a server that
+silently ignores the field cannot be detected from successful transport alone.
+
+Before admission, all selected references must resolve. Each attempt freezes the
+chosen endpoint, exact model, declared limits, reasoning request, compatibility settings and maintained
+command along with the common resource/timeout/skill policy. Unselected bindings
+are not included. Local/hybrid attempts emit protected **v3** evidence across all
+phases, binding the selection digest and common policy. Public facts show configured
+context/output, unknown actual allocation and unqualified quality. Old v1/v2 writers
+cannot attest local bindings; unchanged legacy profiles keep their policy bytes and
+compatible evidence. See [the compatibility audit](npm.md#protected-evidence-compatibility).
+
+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
+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.
+Files are removed after confirmed container shutdown; uncertain shutdown retains
+them behind the existing recovery fence until normal recovery confirms absence.
+
+Local roles receive no cloud model environment; cloud roles receive no local
+registry/override. Verify and Handoff receive neither. The local preset disables
+automatic skills/extensions/templates but explicitly adds `--skill /factory-skills`,
+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.

package/docs/interfaces.md

@@ -21,7 +21,7 @@ shell endpoint or a second scheduler.
 | Remove a stopped task | No command | `DELETE /api/v1/jobs/:id` | Remove action | Add CLI; keep existing recoverability/history semantics |
 | Evidence list/read/download | No command | Authenticated artifact routes | Files/preview/download | Add CLI with matching access and size/path rules |
 | Roles, workflows and packaged skills | `definition`, `agents`, `skills` JSON (also while stopped) | `GET /api/v1/definitions` | Agents, Skills and Definition | Shared catalog plus bounded role harness/model editing; deterministic checks, gates, skills and resources stay shared |
-| Portable role definitions | `definition export/validate/diff/apply/rollback` | Authenticated `/api/v1/definition` and typed operations | Agents/Definition role editor, diff, explicit idle Apply and rollback | One schema/capability matrix; revision CAS and bounded atomic history; [request shapes](definition.md) |
+| Portable roles and private local bindings | `definition export/validate/diff/apply/rollback`, optional `--bindings-file` for validate/diff/apply | Authenticated `/api/v1/definition` and typed operations | Agents/Definition role editor, diff, explicit idle Apply and rollback | One schema/capability matrix; revision CAS and bounded atomic role/binding history; configured context distinct from unknown allocation and unqualified quality; [request shapes](definition.md) |
 | Project repository links | Validated links in `status` | `project_links` from configured Git origin | View repo / optional GitHub issue link | Provider creates/issues reads are separate from Git source links |
 | Recorded token usage | Per-attempt `usage` and `token_usage` in `status` | Same status records | Analytics, task rows, metadata/history | No billing estimate; partial/unknown coverage stays explicit |
 | Analytics/filtering | Raw status available | Source queue records | Derived views | Expose equivalent queries/summaries without inventing usage data |

package/docs/npm.md

@@ -104,8 +104,8 @@ installation or retained attempt needs them.
 
 ## Protected evidence compatibility
 
-Factory 0.14.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 and 0.14.0**. This is an exact allowlist in
+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/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 +172,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 only**, recording
+rules stay compatible. Adopted role overrides use **v2 from 0.14.0 and 0.15.0**, 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.
@@ -227,3 +227,17 @@ delivery under [#61](https://github.com/arcitai/software-and-defence-factory/iss
 
 References: [npm/npx](https://docs.npmjs.com/cli/v11/commands/npx/),
 [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/).
+
+
+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
+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
+rollback can restore it without editing historical evidence. Controlled regressions
+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.

package/docs/setup.md

@@ -389,3 +389,44 @@ To add operator scope at admission, use `issue start --url URL --workflow softwa
 --brief-file operator.md --state PATH` with an optional UTF-8 brief of at most
 16000 characters. This keeps the remote identity and current-content check;
 local requests still use `issue start --file` or `--draft` without `--brief-file`.
+
+
+## Optional keyless local or hybrid inference
+
+Use the [local binding recipe](definition.md#opt-in-local-bindings-0150-69) to adopt
+an explicit private endpoint/model map and portable Pi role references. Keep the
+working default and a stopped private-state backup; preview, apply while idle and
+use revision-guarded rollback. A local Implement role can be paired with an existing
+cloud Review role. No downloads, service restarts, port changes or jobs occur during
+configuration. Authenticated endpoints, sampling overrides and custom thinking
+maps are unsupported. Local bindings may request OpenAI-style `reasoningEffort`:
+`default` (or omitted), `none`, `low`, `medium` or `high`. Default omits the request;
+it does not disable server thinking. Qualify the endpoint's actual semantics before
+using a request as a thinking-budget control. Unsupported requests fail without
+fallback when the endpoint rejects them; transport success alone cannot prove a
+server honored the request. Existing omitted choices remain unchanged.
+
+Qualify the actual installed image and endpoint from an isolated job before using
+it for application work. Record server/harness versions, exact model ID and digest,
+quantization, GPU/backend and actual offload, available and peak memory, endpoint
+reachability, tool-call/result compatibility and report/check/review outcomes.
+Keep host inference access separate from controller/forge credentials. Unknown
+values stay unknown; registry discovery only proves client capability.
+
+Reconcile the client's configured context with the server's actual allocation and
+per-request/model overrides. Do not infer a 65k allocation from a remembered agent
+setting or a server default. A bounded 64k/128k allocation experiment, where
+supported, must record KV-cache and Flash Attention settings, memory and allocation
+success separately from long-context task quality. This worker supplies no such
+measurements or driver/kernel advice. Do not recommend larger windows from the
+schema's upper limit.
+
+The operator still owns #69's matched two-fixture comparison: pinned bases,
+comparable prompts/contexts/trials, a measured existing local baseline and one
+selected alternative, decisive independent checks and separate Review contexts.
+Retain failures, repairs and human time. Record wall time, observable prefill/decode,
+input/cached/output tokens, memory/offload and all reviewer usage. Factory currently
+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.

package/factory/definition-store.mjs

@@ -1,36 +1,43 @@
+import { isDeepStrictEqual } from 'node:util';
+import { parseLocalBindings } from './local-inference.mjs';
 import { closeSync, existsSync, fsyncSync, openSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { configAt, digest, harnessOf } from './lib.mjs';
-import { DefinitionError, installedRoleRecord, parseRoleDefinition, publicRoleProfiles, resolveRoleProfiles, ROLE_CAPABILITIES } from './role-definition.mjs';
+import { DefinitionError, installedRoleRecord, parseRoleRecord, parseRoleDefinition, publicRoleProfiles, resolveRoleProfiles, ROLE_CAPABILITIES } from './role-definition.mjs';
 
+const revisionOf = (config, record) => digest(JSON.stringify({ config, sequence: record.sequence, definition: record.definition, localBindings: record.localBindings }));
 function context(state) {
   const config = configAt(state), record = installedRoleRecord(state);
-  delete config.roleDefinition;
-  return { config, record, revision: digest(JSON.stringify({ config, sequence: record.sequence, definition: record.definition })) };
+  delete config.roleDefinition; delete config.localBindings;
+  record.localBindings ||= {};
+  return { config, record, revision: revisionOf(config, record) };
 }
 function view({ config, record, revision }) {
-  return { revision, inherited_harness: harnessOf(config), definition: record.definition, rollback_available: record.history.length > 0,
-    effective: publicRoleProfiles(resolveRoleProfiles(config, record.definition)), capabilities: ROLE_CAPABILITIES };
+  return { revision, inherited_harness: harnessOf(config), definition: record.definition, local_bindings: record.localBindings, rollback_available: record.history.length > 0,
+    effective: publicRoleProfiles(resolveRoleProfiles({ ...config, localBindings: record.localBindings }, record.definition)), capabilities: ROLE_CAPABILITIES };
 }
 export function inspectDefinition(state) { return view(context(state)); }
-export function previewDefinition(state, value) {
+export function previewDefinition(state, value, bindings) {
   const current = context(state), definition = parseRoleDefinition(value);
   const before = view(current);
-  const effective = publicRoleProfiles(resolveRoleProfiles(current.config, definition));
+  const localBindings = parseLocalBindings(bindings === undefined ? current.record.localBindings : bindings);
+  const effective = publicRoleProfiles(resolveRoleProfiles({ ...current.config, localBindings }, definition));
   const changes = [];
   for (const role of ROLE_CAPABILITIES.roles) {
     if (JSON.stringify(before.definition.roles[role]) !== JSON.stringify(definition.roles[role])
       || JSON.stringify(before.effective[role]) !== JSON.stringify(effective[role]))
       changes.push({ role, before: before.effective[role], after: effective[role], selection: definition.roles[role] });
   }
-  return { revision: current.revision, definition, effective, changes, valid: true,
+  return { revision: current.revision, definition, local_bindings: localBindings, effective, changes,
+    binding_changes: Object.keys({ ...current.record.localBindings, ...localBindings }).filter(name => JSON.stringify(current.record.localBindings[name]) !== JSON.stringify(localBindings[name]))
+      .map(name => ({ reference: name, before: current.record.localBindings[name] || null, after: localBindings[name] || null })), valid: true,
     qualification: 'Configuration only; harness, model availability and quality are not qualified' };
 }
 export function previewRollback(state) {
   const previous = context(state).record.history.at(-1);
   if (!previous) throw new DefinitionError('No previous definition is available', 409);
-  return { ...previewDefinition(state, previous), rollback: true };
+  return { ...previewDefinition(state, previous.definition, previous.localBindings), rollback: true };
 }
 function assertIdle(queue, state) {
   if (queue.closing || queue.maintenance || queue.active || queue.actions.size || queue.issueActions.size
@@ -40,12 +47,12 @@ function assertIdle(queue, state) {
   if (existsSync(jobs) && readdirSync(jobs).some(id => /^job_[a-z0-9]+$/.test(id) && existsSync(join(jobs, id, 'active.json'))))
     throw new DefinitionError('Executor recovery is required before applying a definition', 409);
 }
-function persist(state, record) {
+function persist(state, serialized) {
   const destination = join(state, 'role-definition.json'), temp = `${destination}.${randomUUID()}.tmp`;
   let fd;
   try {
     fd = openSync(temp, 'wx', 0o600);
-    writeFileSync(fd, JSON.stringify(record, null, 2) + '\n'); fsyncSync(fd); closeSync(fd); fd = undefined;
+    writeFileSync(fd, serialized); fsyncSync(fd); closeSync(fd); fd = undefined;
     // Definition and rollback history share one atomic replacement. A crash before
     // rename retains the old record; after rename it retains the complete new one.
     renameSync(temp, destination);
@@ -54,19 +61,24 @@ function persist(state, record) {
 // Called synchronously only by the single controller, after request body parsing.
 // No await between CAS, idle check and atomic replacement; admission cannot interleave.
 export function changeDefinition(state, queue, input, rollback = false) {
-  const allowed = rollback ? ['expected_revision'] : ['expected_revision', 'definition'];
+  const allowed = rollback ? ['expected_revision'] : ['expected_revision', 'definition', 'local_bindings'];
   if (!input || Object.keys(input).some(key => !allowed.includes(key)) || typeof input.expected_revision !== 'string')
     throw new DefinitionError('Expected definition and expected_revision (rollback accepts expected_revision only)');
   const current = context(state);
   if (input.expected_revision !== current.revision) throw new DefinitionError('Definition revision changed; refresh and preview again', 409);
   assertIdle(queue, state);
-  const value = rollback ? current.record.history.at(-1) : input.definition;
+  const value = rollback ? current.record.history.at(-1) : { definition: input.definition, localBindings: input.local_bindings };
   if (!value) throw new DefinitionError('No previous definition is available', 409);
-  const preview = previewDefinition(state, value);
-  if (!rollback && JSON.stringify(preview.definition) === JSON.stringify(current.record.definition)) return view(current);
-  const history = rollback ? current.record.history.slice(0, -1) : [...current.record.history, current.record.definition].slice(-10);
-  const record = { version: 1, sequence: current.record.sequence + 1, definition: preview.definition, history };
-  persist(state, record);
-  return { revision: digest(JSON.stringify({ config: current.config, sequence: record.sequence, definition: record.definition })),
-    inherited_harness: harnessOf(current.config), definition: record.definition, effective: preview.effective, rollback_available: history.length > 0, capabilities: ROLE_CAPABILITIES };
+  const preview = previewDefinition(state, value.definition, value.localBindings);
+  if (!rollback && JSON.stringify(preview.definition) === JSON.stringify(current.record.definition)
+    && JSON.stringify(preview.local_bindings) === JSON.stringify(current.record.localBindings)) return view(current);
+  const history = rollback ? current.record.history.slice(0, -1) : [...current.record.history, { definition: current.record.definition, localBindings: current.record.localBindings }].slice(-10);
+  const record = { version: 2, sequence: current.record.sequence + 1, definition: preview.definition, localBindings: preview.local_bindings, history };
+  const serialized = JSON.stringify(record, null, 2) + '\n';
+  if (Buffer.byteLength(serialized) > 256000) throw new DefinitionError('Private definition history exceeds 256 KB; shorten binding endpoints before applying');
+  const roundtrip = parseRoleRecord(JSON.parse(serialized));
+  if (!isDeepStrictEqual(record, roundtrip)) throw new DefinitionError('Private definition record must round-trip without normalization');
+  const next = view({ config: current.config, record: roundtrip, revision: revisionOf(current.config, roundtrip) });
+  persist(state, serialized);
+  return next;
 }

package/factory/execution-evidence.mjs

@@ -37,7 +37,7 @@ export function trustedExecutionProfile(state, job, run, phase, expectedPolicy)
       assertPrivateDirectory(path);
     const profile = readPrivateJson(join(folder, 'artifacts', run.id, 'execution.json'));
     if (profile.version === 1 && hasRoleOverrides(installedRoleRecord(state).definition)) return false;
-    if (profile.version === 2) {
+    if ([2, 3].includes(profile.version)) {
       const frozen = readPrivateJson(join(folder, run.id, 'execution-config.json'));
       if (!frozen.roleDefinition || !frozen.resolvedRoleProfiles || digest(JSON.stringify(frozen)) !== expectedPolicy) return false;
       assertFrozenExecution(frozen, profile, phase);

package/factory/execution-profile.mjs

@@ -1,3 +1,4 @@
+import { publicLocalBinding } from './local-inference.mjs';
 import { isDeepStrictEqual } from 'node:util';
 import { resolveRoleProfiles, ROLE_PHASES } from './role-definition.mjs';
 import { harnessOf } from './lib.mjs';
@@ -18,19 +19,22 @@ import { expectedWebStories, webPolicyHash } from './web-verification.mjs';
 // deterministic phases, protected checks, isolation and acceptance remain compatible.
 // Role overrides require v2, with role/provider/reasoning and a private-command
 // 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.
 // 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']);
+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']);
 
 export function isSupportedExecutionProfile(profile) {
-  if (profile?.version === 2) return profile.runtimeVersion === '0.14.0'
+  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')
     && 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 || '');
-  return profile?.version === 1 && !Object.hasOwn(profile, 'role') && !Object.hasOwn(profile, 'selectionHash')
+  return profile?.version === 1 && !Object.hasOwn(profile, 'localBinding') && profile.inferenceProvider !== 'factory-local' && !Object.hasOwn(profile, 'role') && !Object.hasOwn(profile, 'selectionHash')
     && SUPPORTED_EXECUTION_RUNTIMES_V1.has(profile.runtimeVersion);
 }
 
@@ -54,6 +58,7 @@ export function effectiveExecutionConfig(configuration, requestedModel, modelEnv
   if (configuration.roleDefinition) {
     const config = withRequestedModel(configuration, requestedModel);
     config.resolvedRoleProfiles = resolveRoleProfiles(config, config.roleDefinition, modelEnvironmentPath);
+    delete config.localBindings; // Freeze only the bindings selected by admitted roles, never the catalog.
     return config;
   }
   const inferenceProvider = effectiveInferenceProvider(configuration, modelEnvironmentPath);
@@ -77,7 +82,9 @@ export function executionProfile(commonConfig, phase) {
     policyHash: digest(JSON.stringify(commonConfig)), hostName: hostname(),
   };
   if (commonConfig.resolvedRoleProfiles) {
-    profile.version = 2;
+    const local = Object.values(commonConfig.resolvedRoleProfiles).some(p => p.localBinding);
+    profile.version = local ? 3 : 2;
+    if (local) profile.localBinding = deterministic ? null : publicLocalBinding(config.localBinding);
     profile.role = Object.keys(ROLE_PHASES).find(role => ROLE_PHASES[role] === phase) || null;
     profile.reasoningEffort = deterministic ? null : config.reasoningEffort || null;
     profile.inferenceProvider = deterministic ? null : config.inferenceProvider || null;
@@ -123,6 +130,10 @@ export function assertFrozenExecution(config, execution, phase) {
   const expected = executionProfile(config, phase);
   // Host identity is presentation; all execution and policy selections must match.
   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)
+    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

@@ -1,3 +1,4 @@
+import { localRegistry, LOCAL_AGENT_DIR } from './local-inference.mjs';
 import { assertFrozenExecution, phaseExecutionConfig } from './execution-profile.mjs';
 import { withReconstructedCandidate } from './candidate-patch.mjs';
 import { harnessOf } from './lib.mjs';
@@ -32,7 +33,7 @@ let sourceAdmission, continuation;
 try { sourceAdmission = JSON.parse(process.env.SDF_SOURCE_ADMISSION || 'null'); continuation = JSON.parse(process.env.SDF_CONTINUATION || 'null'); }
 catch { throw new Error('Protected source admission metadata is malformed'); }
 const policyHash = digest(JSON.stringify(commonConfig));
-if (commonConfig.roleDefinition || execution.version === 2) assertFrozenExecution(commonConfig, execution, phase);
+if (commonConfig.roleDefinition || [2, 3].includes(execution.version)) assertFrozenExecution(commonConfig, execution, phase);
 else if (execution.policyHash !== policyHash || execution.phase !== phase) throw new Error('Admitted execution profile does not match this attempt');
 const output = process.env.SDF_OUTPUT_DIR, result = process.env.SDF_STEP_RESULT_PATH;
 if (!output || !result) throw new Error('Missing workflow result paths');
@@ -78,6 +79,7 @@ async function container(mode, input, command, options = {}) {
   const reportDir = join(folder, attempt, mode);
   mkdirSync(reportDir, { recursive: true, mode: 0o700 });
   const modelEnvironmentPath = join(folder, attempt, `.model-${mode}.env`);
+  const localDirectory = mode !== 'verify' && config.localBinding ? join(folder, attempt, `.local-${mode}`) : null;
   // Native builds need disk-backed scratch space, not the small temporary RAM disk.
   // Only this attempt can write here; the candidate and its Git metadata stay read-only.
   const scratch = mode === 'verify' ? join(folder, attempt, 'check-workspace') : null;
@@ -104,6 +106,14 @@ async function container(mode, input, command, options = {}) {
   const log = new BoundedLog(), usageParser = execution.executor === 'codex' ? new CodexUsageParser() : null;
   let exitSignal, selectedModelEnvironment = false, inferenceSecrets = [], code, cleanupError, reportError;
   try {
+    if (localDirectory) {
+      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' });
+      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}`);
+    }
     selectedModelEnvironment = writeSelectedModelEnvironment(join(state, 'model.env'), modelEnvironmentPath, {
       phase: mode, executor: execution.executor, inferenceProvider: config.inferenceProvider,
     });
@@ -129,6 +139,7 @@ async function container(mode, input, command, options = {}) {
     // selected inference file and mounted scratch until a host-side listing
     // proves the container is absent. A client exit alone is not that proof.
     removeContainerAndConfirmAbsence(name, mode === 'verify');
+    if (localDirectory) rmSync(localDirectory, { recursive: true, force: true });
     try { redactRetainedPhaseOutputs(join(folder, attempt), mode, inferenceSecrets); }
     catch (error) { reportError = error; }
     try { if (scratch && mode === 'verify' && !keepScratch) removeScratch(scratch); } catch (error) { cleanupError = error; }
@@ -402,6 +413,8 @@ try {
   }
   // Failed filtering is recoverable state: keep its exact secret source and
   // active fence until a later stopped-process recovery completes it.
+  if (['build', 'review', 'defence'].includes(phase))
+    rmSync(join(folder, attempt, `.local-${phase}`), { recursive: true, force: true });
   if (outputRetentionComplete && ['build', 'review', 'defence'].includes(phase))
     rmSync(join(folder, attempt, `.model-${phase}.env`), { force: true });
   if (outputRetentionComplete) rmSync(lock);

package/factory/lib.mjs

@@ -80,9 +80,12 @@ export function configAt(state) {
   if (typeof config.check !== 'string' || !config.scope || !['project','service','environment','owner'].every(k=>typeof config.scope[k]==='string'&&config.scope[k].trim())) throw new Error('Missing check or installation scope');
   readinessMapping(config.issueReadinessLabels);
   validateWebVerification(config.webVerification);
-  if (config.roleDefinition !== undefined || config.resolvedRoleProfiles !== undefined) throw new Error('Role profiles belong in the controller-managed definition; use definition apply');
-  const definition = installedRoleRecord(state).definition;
-  if (hasRoleOverrides(definition)) config.roleDefinition = definition;
+  if (config.roleDefinition !== undefined || config.resolvedRoleProfiles !== undefined || config.localBindings !== undefined) throw new Error('Role profiles belong in the controller-managed definition; use definition apply');
+  const { definition, localBindings } = installedRoleRecord(state);
+  if (hasRoleOverrides(definition)) {
+    config.roleDefinition = definition;
+    if (Object.keys(localBindings || {}).length) config.localBindings = localBindings;
+  }
   return config;
 }
 export async function api(state, path, body, method, { timeoutMs = API_TIMEOUT_MS } = {}) {