Ship native Codex plugin with Earned Enforcement

.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "marginal",
+  "interface": {
+    "displayName": "Marginal"
+  },
+  "plugins": [
+    {
+      "name": "marginal",
+      "source": {
+        "source": "local",
+        "path": "./plugins/marginal"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -10,7 +10,7 @@ body:
     id: version
     attributes:
       label: MARGINAL version
-      placeholder: "0.2.0"
+      placeholder: "0.3.0"
     validations:
       required: true
   - type: input

.github/workflows/ci.yml

@@ -27,5 +27,6 @@ jobs:
       - run: ruff check .
       - run: mypy src/marginal
       - run: pytest -q
+      - run: python scripts/build_codex_plugin.py --check
       - run: python -m build
       - run: python -m twine check dist/*

.gitignore

@@ -7,6 +7,7 @@ htmlcov/
 dist/
 build/
 .venv/
+.worktrees/
 .env
 *.jsonl
 .DS_Store

CHANGELOG.md

@@ -4,6 +4,8 @@ All notable changes to MARGINAL are documented here. The project follows Semanti
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-08-13
+
 ### Added
 
 - opt-in, provider-neutral `DiminishingReturnDetector` with same-state/evidence-aware gain decay;
@@ -13,6 +15,13 @@ All notable changes to MARGINAL are documented here. The project follows Semanti
 - gross-versus-net savings and intervention status including Graceful Irrelevance through `pass_through`;
 - governance evidence standard, Codex benchmark-readiness guide and Community Feedback Log;
 - structured documentation information architecture by user intent.
+- native Codex plugin marketplace `marginal@marginal` with reproducible dependency-free runtime;
+- one-command native install/remove plus `status`, `doctor`, `review`, `promote`, and `demote`;
+- strict Codex lifecycle contracts, privacy-safe normalization, Git state hashing, and conservative structured outcome classification;
+- authenticated per-session loopback service with bounded messages and fail-open demotion;
+- provider-neutral No Progress evidence control and versioned Earned Enforcement promotion receipts;
+- isolated Codex 0.147.0 marketplace/lifecycle/privacy/removal smoke and universal directory review packet;
+- public privacy, terms, support, Codex integration, and submission documentation.
 
 ### Changed
 
@@ -22,13 +31,16 @@ All notable changes to MARGINAL are documented here. The project follows Semanti
 - website and README now lead with a concrete illustrative trace and proof standard before architecture theory;
 - roadmap now treats governance tax, false-stop rate, matched OFF/ON evaluation and pass-through as first-class success criteria;
 - the 10-task Codex canary is explicitly classified as integration validation rather than public performance evidence.
+- website and README now lead with native Codex install/remove and the measured n=3 `pass_through` result.
 
 ### Scientific limitations
 
 - diminishing-return thresholds are transparent heuristics until calibrated on representative engine telemetry;
 - false stops require external review/counterfactual labels and are not automatically causal estimates;
 - Graceful Irrelevance classifies the measured configuration, not the universal usefulness of MARGINAL;
-- vendor-specific Codex integration and measured public savings remain future v0.3 evidence.
+- the Codex plugin supports local Tool Enforcement paths, not Full Compute Enforcement;
+- the n=3 result remains integration telemetry and does not establish general token savings;
+- universal directory availability depends on external review and release.
 
 ## [0.2.0] - 2026-08-06
 

CITATION.cff

@@ -4,7 +4,7 @@ title: "MARGINAL: Economically Disciplined Compute Allocation for AI Agents"
 type: software
 authors:
   - name: SignalLayer Labs
-version: 0.2.0
+version: 0.3.0
 date-released: 2026-08-06
 license: Apache-2.0
 repository-code: "https://github.com/SignalLayerLabs/Marginal"

PRIVACY.md

@@ -0,0 +1,35 @@
+# MARGINAL Privacy Notice
+
+**Effective date:** 2026-08-13
+
+MARGINAL is local-first open-source software. The Codex plugin makes no network request and does
+not operate a SignalLayer Labs telemetry service.
+
+## Data processed locally
+
+Codex supplies lifecycle identifiers, tool names, tool inputs, tool responses, workspace paths,
+and session metadata to local hooks. MARGINAL uses that input in memory to make a decision and to
+derive hashes. By default it does not persist prompts, source code, raw commands, raw tool output,
+transcripts, authentication files, or credential environment values.
+
+The plugin may store redacted decisions, opaque hashes, aggregate coverage counts, outcome status,
+reason codes, latency, review labels, promotion receipts, and user-private connection files under
+Codex `PLUGIN_DATA`. Connection credentials are removed at session end. Local evidence remains
+until the user deletes it or runs an explicit purge.
+
+## Sharing and remote processing
+
+MARGINAL does not transmit plugin evidence to SignalLayer Labs. GitHub, Codex, package registries,
+and any model provider remain governed by their own policies. Exporting a ledger or attaching files
+to an issue is an explicit user action; inspect exports before sharing them.
+
+## User controls
+
+- `marginal codex status` shows the local mode.
+- `marginal codex demote` returns enforcement to Shadow Mode.
+- `marginal uninstall codex` removes the plugin and preserves evidence.
+- `marginal uninstall codex --purge-data --yes` removes plugin data explicitly.
+
+Security issues must follow [SECURITY.md](SECURITY.md). Privacy questions can be filed through the
+private contact route described in [SUPPORT.md](SUPPORT.md).
+

README.md

@@ -31,6 +31,26 @@ Open source · Local first · Provider neutral · Zero mandatory runtime depende
 
 > **Exploratory 3-task smoke, one paired run per task.** This validates the integration; it is not a general performance claim.
 
+### Install the native Codex plugin
+
+MARGINAL installs through Codex's native plugin marketplace and starts globally in **Shadow Mode**:
+
+```bash
+codex plugin marketplace add SignalLayerLabs/Marginal --ref main && codex plugin add marginal@marginal
+```
+
+Remove it cleanly with:
+
+```bash
+codex plugin remove marginal@marginal
+```
+
+The plugin provides **Tool Enforcement**, not Full Compute Enforcement. Repository blocking is
+disabled until local **Earned Enforcement** evidence proves at least 99% hook coverage, reviewed
+stop candidates, zero false stops, no pending failures, and bounded governance latency. Any drift
+demotes the repository to Shadow Mode and requires a fresh clean evidence window. The public directory submission packet is ready, but the
+directory listing remains subject to OpenAI review; the Git marketplace command above works now.
+
 | Metric | Codex OFF | Codex + MARGINAL | Observed change |
 |---|---:|---:|---:|
 | SWE-bench resolved | 0/3 | 0/3 | **0/3 → 0/3** |
@@ -185,10 +205,37 @@ Read the [benchmark protocol](docs/evaluation/public-benchmarks.md) and [governa
 
 ## Install
 
-Current v0.2 install target:
+### Codex — recommended
+
+```bash
+codex plugin marketplace add SignalLayerLabs/Marginal --ref main && codex plugin add marginal@marginal
+```
+
+Then open `/hooks` in Codex, review the exact commands, and grant trust only after inspection.
+MARGINAL never bypasses the hook trust boundary. Useful management commands:
+
+```bash
+marginal codex status
+marginal codex doctor
+marginal codex review
+marginal codex review --candidate ACTION_HASH --verdict waste
+marginal codex promote
+marginal codex demote
+marginal uninstall codex
+```
+
+The Python package can perform the same native installation transaction:
+
+```bash
+marginal install codex
+```
+
+### Python library
+
+Current tagged library install target:
 
 ```bash
-pip install "marginal-ai @ git+https://github.com/SignalLayerLabs/Marginal.git@v0.2.0"
+pip install "marginal-ai @ git+https://github.com/SignalLayerLabs/Marginal.git@v0.3.0"
 ```
 
 Development checkout:
@@ -199,7 +246,9 @@ cd Marginal
 python -m pip install -e ".[dev]"
 ```
 
-The auditable Codex reference adapter and its first matched smoke are now available in `benchmark/codex_adapter/`. Start from the frozen protocol and treat the current n=3 result as integration evidence, not a performance claim.
+The production Codex adapter lives under `src/marginal/integrations/codex/`; the independent
+benchmark harness remains under `benchmark/codex_adapter/`. Treat the current n=3 result as
+integration evidence, not a performance claim.
 
 ## Quickstart
 
@@ -255,7 +304,10 @@ The engine-specific adapter owns native interception and telemetry. The core own
 
 ## Project status
 
-`v0.2.0` provides the Learning Loop Foundation, privacy profiles, Universal Agent Protocol, versioned evidence and replay. The community-hardening work prepares the core evidence model for **v0.3 — Codex Reference Integration**.
+The v0.3 candidate adds the native Codex plugin, privacy-safe hook contracts, an authenticated
+local service, reversible install/uninstall, and Earned Enforcement receipts to the v0.2 Learning
+Loop Foundation. The universal directory submission is an external review step and is not described
+as live until OpenAI accepts and releases it.
 
 The next milestone must answer a falsifiable question:
 
@@ -271,7 +323,7 @@ If the answer is no, the result should be published as no demonstrated benefit f
 |---|---|
 | Getting started | [Quickstart](docs/getting-started/quickstart.md) |
 | Product model | [Concepts](docs/product/concepts.md) · [Architecture](docs/product/architecture.md) |
-| Integrations | [Integration overview](docs/integrations/overview.md) · [Codex benchmark readiness](docs/integrations/codex-benchmark-readiness.md) |
+| Integrations | [Codex plugin](docs/integrations/codex.md) · [Integration overview](docs/integrations/overview.md) · [Codex benchmark readiness](docs/integrations/codex-benchmark-readiness.md) |
 | Evaluation | [Benchmarking](docs/evaluation/benchmarking.md) · [Public benchmarks](docs/evaluation/public-benchmarks.md) · [Governance evidence](docs/evaluation/governance-evidence.md) |
 | Reference | [API](docs/reference/api.md) |
 | Operations | [Privacy](docs/operations/privacy.md) · [Website](docs/operations/website.md) |

ROADMAP.md

@@ -38,9 +38,9 @@ This roadmap is milestone-driven rather than date-driven. GitHub Issues and pull
 | Milestone | Status | Primary outcome |
 |---|---|---|
 | **v0.1 — Reference Allocator Foundation** | Complete | Provider-neutral allocation, accounting, tracing and first release |
-| **v0.2 — Learning Loop Foundation** | Validation | Universal protocol, non-blocking observation, versioned evidence, privacy and replay |
+| **v0.2 — Learning Loop Foundation** | Complete | Universal protocol, non-blocking observation, versioned evidence, privacy and replay |
 | **Community hardening** | In progress | Governance tax, false-stop accounting, diminishing-return control and clearer evidence UX |
-| **v0.3 — Codex Reference Integration** | Planned | One-command target, real telemetry and first matched public benchmark |
+| **v0.3 — Codex Reference Integration** | Validation | Native plugin, one-command install, Earned Enforcement, and measured smoke |
 | **v0.4 — Multi-Engine Developer Preview** | Planned | Shared core across materially different coding agents |
 | **v0.5 — One-Command Universal Installation** | Planned | Detection, installation, diagnostics and rollback across engines |
 | **v0.6 — Adaptive and Causal Allocation** | Planned | Calibrated learning, exploration and stronger identification strategies |
@@ -60,7 +60,7 @@ Delivered provider-neutral `Action`, `Cost`, `Decision` and `Allocation` primiti
 
 ## v0.2 — Learning Loop Foundation
 
-**Status:** Validation
+**Status:** Complete
 
 The v0.2 release candidate adds:
 
@@ -77,10 +77,10 @@ The v0.2 release candidate adds:
 - task outcomes separated from action-level realized gain;
 - non-causal replay and ledger/reporting CLI support.
 
-### Remaining exit criteria
+### Exit criteria
 
-- [ ] Ruff, mypy strict, full tests, package build and Twine validation pass in canonical CI.
-- [ ] `v0.2.0` is tagged/released from the canonical repository.
+- [x] Ruff, mypy strict, full tests, package build and Twine validation pass in canonical CI.
+- [x] `v0.2.0` is tagged/released from the canonical repository.
 
 Vendor-specific adapters and measured production savings are intentionally outside v0.2.
 
@@ -120,28 +120,30 @@ Vendor-specific adapters and measured production savings are intentionally outsi
 
 ## v0.3 — Codex Reference Integration
 
-**Status:** Planned
+**Status:** Validation
 
 **Objective:** integrate MARGINAL into Codex and produce the first real matched benchmark with measured telemetry and net-value accounting.
 
 ### Integration deliverables
 
-- [ ] Build a thin Codex adapter against the Universal Agent Protocol.
-- [ ] Target `marginal install codex` with safe backup, Shadow Mode default and clean uninstall.
-- [ ] Detect Codex version/capability level and refuse unsupported enforcement claims.
-- [ ] Capture measured input, cached input, output, reasoning and total tokens.
-- [ ] Correlate model/tool/retry/verification actions with session, task and workspace state.
-- [ ] Record evidence hashes where deterministic evidence boundaries exist.
-- [ ] Capture governance tokens, USD and latency separately from workload usage.
-- [ ] Define and record repeated-call metrics consistently in OFF and ON arms.
-- [ ] Export raw paired JSONL sufficient to reproduce the public report.
+- [x] Build a thin Codex adapter against the Universal Agent Protocol.
+- [x] Ship native `marginal@marginal` installation plus `marginal install codex`, Shadow Mode default and clean uninstall.
+- [x] Detect Codex version/capability level and refuse unsupported enforcement claims.
+- [x] Capture measured input, cached input, output, reasoning and total tokens in the benchmark adapter.
+- [x] Correlate tool and verification actions with session, turn, call, task and workspace state.
+- [x] Record evidence hashes where deterministic evidence boundaries exist without persisting raw payloads.
+- [x] Capture governance tokens, USD and latency separately from workload usage.
+- [x] Define and record repeated-call metrics consistently in OFF and ON arms.
+- [x] Export raw paired JSONL sufficient to reproduce the public report.
+- [x] Add Earned Enforcement receipts with explicit promotion and automatic fail-open demotion.
+- [x] Validate add/install/four-hook lifecycle/privacy/remove in an isolated Codex home.
 
 ### Canary: engineering validation only
 
 - [ ] Run a 10-task matched canary with identical model, prompt, tools, limits and verifier.
-- [ ] Confirm event/session/state correlation and no orphaned reservations.
-- [ ] Confirm telemetry is measured rather than declared.
-- [ ] Confirm governance overhead is separately accounted.
+- [x] Confirm event/session/state correlation and no orphaned reservations in focused lifecycle tests.
+- [x] Confirm telemetry is measured rather than declared in the exploratory paired smoke.
+- [x] Confirm governance overhead is separately accounted.
 - [ ] Review deny recommendations for false-stop candidates.
 - [ ] Preserve pass-through and negative results instead of filtering them out.
 
@@ -179,12 +181,14 @@ Report:
 
 ### v0.3 exit criteria
 
-- Codex baseline and Codex + MARGINAL run under matched conditions.
-- Telemetry comes from the runtime/provider integration rather than declared demo estimates.
-- The canary completes without integration failures.
-- Public results are reproducible from raw paired artifacts.
-- Headline claims use **net** metrics after governance tax.
-- If the preregistered gate is not met, the published conclusion says so.
+- [x] Codex baseline and Codex + MARGINAL run under matched conditions for the n=3 integration smoke.
+- [x] Telemetry comes from the runtime/provider integration rather than declared demo estimates.
+- [x] The authoritative Docker verifier completes without infrastructure errors.
+- [x] Public results are reproducible from raw paired artifacts.
+- [x] Headline claims use **net** metrics after governance tax.
+- [x] The published conclusion says `pass_through` because the support gate was not met.
+- [ ] A preregistered repeated run large enough for a general efficiency claim is complete.
+- [ ] The external universal directory review is accepted and released.
 
 See [Codex benchmark readiness](docs/integrations/codex-benchmark-readiness.md).
 

SUPPORT.md

@@ -8,3 +8,12 @@ a public issue.
 
 MARGINAL is an early open-source reference implementation. Community support is best effort;
 no service-level agreement is provided.
+
+For Codex integration reports, include the redacted output of `marginal codex doctor`, the Codex
+version, operating system, plugin version, and whether `/hooks` shows the expected lifecycle hooks.
+Never attach `auth.json`, prompts, source code, raw commands, raw tool output, transcripts, access
+tokens, or the contents of `PLUGIN_DATA` connection files.
+
+Installation and removal guidance is maintained in [docs/integrations/codex.md](docs/integrations/codex.md).
+Privacy questions that cannot be discussed publicly may use GitHub's private vulnerability
+reporting channel; choose the privacy category and do not include unrelated credentials.

TERMS.md

@@ -0,0 +1,24 @@
+# MARGINAL Terms of Use
+
+**Effective date:** 2026-08-13
+
+MARGINAL is provided under the [Apache License 2.0](LICENSE). These terms clarify the public plugin
+experience and do not replace the license.
+
+MARGINAL is experimental developer infrastructure. It is provided without a service-level
+agreement or guarantee of token savings, cost reduction, task success, uninterrupted operation,
+or suitability for a particular purpose. Shadow Mode is the default. Tool Enforcement is not a
+security boundary and fails open if the integration becomes unavailable.
+
+Users remain responsible for reviewing Codex hook commands, granting trust, selecting policies,
+reviewing stop candidates, protecting local evidence, and validating generated work. Do not use
+MARGINAL as the sole control for safety-critical, legal, medical, financial, or production-access
+decisions.
+
+Performance numbers must be interpreted with their published scope. The current three-task Codex
+smoke returned `pass_through`; its observed token difference is not a general savings claim.
+
+Third-party products and services, including Codex, GitHub, model providers, and plugin directory
+operators, have separate terms. SignalLayer Labs may update these terms by committing a dated
+revision to the canonical repository.
+

codemeta.json

@@ -6,7 +6,7 @@
   "codeRepository": "https://github.com/SignalLayerLabs/Marginal",
   "issueTracker": "https://github.com/SignalLayerLabs/Marginal/issues",
   "license": "https://spdx.org/licenses/Apache-2.0",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "datePublished": "2026-08-06",
   "programmingLanguage": "Python",
   "runtimePlatform": "Python 3.10-3.13",

docs/index.md

@@ -15,6 +15,7 @@ MARGINAL documentation is organized by user intent instead of keeping every guid
 ## Integrations
 
 - [Integration overview](integrations/overview.md)
+- [Codex plugin](integrations/codex.md)
 - [Codex benchmark readiness](integrations/codex-benchmark-readiness.md)
 
 ## Evaluation and research
@@ -32,6 +33,10 @@ MARGINAL documentation is organized by user intent instead of keeping every guid
 
 - [Privacy](operations/privacy.md)
 - [Website operations](operations/website.md)
+- [Codex plugin submission](operations/codex-plugin-submission.md)
+- [Privacy notice](../PRIVACY.md)
+- [Terms](../TERMS.md)
+- [Support](../SUPPORT.md)
 
 ## Project