fix(codex): add native plugin control plane

.github/ISSUE_TEMPLATE/bug_report.yml

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

CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to MARGINAL are documented here. The project follows Semanti
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-08-13
+
+### Added
+
+- a dependency-free native control launcher inside the Codex plugin bundle;
+- repository-scoped hook attestation fields in `status`, including live authenticated services,
+  observed lifecycle evidence, and action coverage.
+
+### Fixed
+
+- the bundled skill no longer requires a separately installed `marginal` executable or Python
+  package to inspect and manage the native plugin;
+- native management commands now read the same Codex plugin data store used by lifecycle hooks,
+  avoiding split-brain Shadow Mode reports.
+
 ## [0.3.1] - 2026-08-13
 
 ### Added

CITATION.cff

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

PRIVACY.md

@@ -25,11 +25,10 @@ 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.
+- `$marginal` in Codex uses the bundled native control plane to show status or demote.
+- `codex plugin remove marginal@marginal` removes the plugin and preserves evidence.
+- the optional Python package command `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

@@ -212,19 +212,21 @@ codex plugin marketplace add SignalLayerLabs/Marginal --ref main && codex plugin
 ```
 
 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:
+MARGINAL never bypasses the hook trust boundary. No Python package or global executable is needed.
+In Codex, ask the bundled skill directly:
+
+```text
+Use $marginal to report whether a live hook service is active, whether hooks were observed, and whether this repository is in Shadow Mode or Tool Enforcement.
+```
+
+The skill resolves the installed plugin with `codex plugin list --json` and runs its bundled
+`scripts/marginal_control.py`, which reads the same private data store as the hooks. Remove it with:
 
 ```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
+codex plugin remove marginal@marginal
 ```
 
-The Python package can perform the same native installation transaction:
+An installed Python package can also perform the native installation transaction:
 
 ```bash
 marginal install codex
@@ -235,7 +237,7 @@ marginal install codex
 Current tagged library install target:
 
 ```bash
-pip install "marginal-ai @ git+https://github.com/SignalLayerLabs/Marginal.git@v0.3.1"
+pip install "marginal-ai @ git+https://github.com/SignalLayerLabs/Marginal.git@v0.3.2"
 ```
 
 Development checkout:

SUPPORT.md

@@ -9,8 +9,8 @@ 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.
+For Codex integration reports, ask `$marginal` for the redacted native `doctor` output and include
+the Codex version, operating system, plugin version, and whether `/hooks` shows the expected hooks.
 Never attach `auth.json`, prompts, source code, raw commands, raw tool output, transcripts, access
 tokens, or the contents of `PLUGIN_DATA` connection files.
 

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.3.1",
+  "version": "0.3.2",
   "datePublished": "2026-08-06",
   "programmingLanguage": "Python",
   "runtimePlatform": "Python 3.10-3.13",

docs/integrations/codex.md

@@ -12,7 +12,7 @@ codex plugin marketplace add SignalLayerLabs/Marginal --ref main && codex plugin
 
 Open `/hooks` in Codex and inspect the four MARGINAL lifecycle commands before granting trust. The
 plugin never uses the bypass-trust flag. Until trust and runtime coverage are observed, MARGINAL is
-inactive or Shadow-only.
+unobserved or Shadow-only; lack of evidence alone does not prove that hooks are disabled.
 
 An installed Python package can perform the same native transaction:
 
@@ -26,17 +26,8 @@ marginal install codex
 codex plugin remove marginal@marginal
 ```
 
-Or:
-
-```bash
-marginal uninstall codex
-```
-
-Removal preserves local evidence. Purge it only through the explicit destructive form:
-
-```bash
-marginal uninstall codex --purge-data --yes
-```
+Removal preserves local evidence. The optional Python package also exposes
+`marginal uninstall codex --purge-data --yes` for an explicit data purge.
 
 ## Earned Enforcement
 
@@ -49,31 +40,41 @@ Global installation never turns blocking on. A repository can enter Tool Enforce
 - p95 decision latency no greater than 75 ms;
 - an unchanged repository, Codex, plugin, adapter, policy, and hook identity;
 - an observable outcome contract for every enforced action family;
-- explicit `marginal codex promote` intent.
+- explicit native `promote` intent.
 
 Any identity drift, lifecycle failure, coverage loss, false stop, or unknown enforced outcome
 invalidates the receipt and demotes to Shadow Mode. Integration failure fails open because MARGINAL
 is an efficiency governor, not a security boundary. Failures and false stops remain in the local
 audit history, then open a fresh evidence window; enforcement can be earned again only with a new
 100-action, five-session clean window.
 
-## Commands
+## Native commands
+
+The plugin bundle does not modify `PATH`. Run `codex plugin list --json`, select the exact
+`marginal@marginal` entry, and use its `source.path` as `<plugin-root>`. Then invoke:
 
 | Command | Purpose |
 | --- | --- |
-| `marginal codex status` | Show mode and capability label |
-| `marginal codex doctor` | Inspect Codex version, stable hooks, and plugins |
-| `marginal codex review` | List redacted, unreviewed stop candidates |
-| `marginal codex promote` | Require a ready, hash-valid local receipt |
-| `marginal codex demote` | Immediately return to Shadow Mode |
+| `python3 <plugin-root>/scripts/marginal_control.py status --workspace <repo> --json` | Show live hook service, prior evidence, mode, and coverage |
+| `python3 <plugin-root>/scripts/marginal_control.py doctor --json` | Inspect Codex version, stable hooks, and plugins |
+| `python3 <plugin-root>/scripts/marginal_control.py review --workspace <repo> --json` | List redacted, unreviewed stop candidates |
+| `python3 <plugin-root>/scripts/marginal_control.py promote --workspace <repo> --json` | Require a ready, hash-valid local receipt |
+| `python3 <plugin-root>/scripts/marginal_control.py demote --workspace <repo> --json` | Immediately return to Shadow Mode |
 
 Label a candidate by hash; no raw command or output is displayed or persisted:
 
 ```bash
-marginal codex review --candidate ACTION_HASH --verdict waste
-marginal codex review --candidate ACTION_HASH --verdict helpful
+python3 <plugin-root>/scripts/marginal_control.py review --workspace <repo> --candidate ACTION_HASH --verdict waste
+python3 <plugin-root>/scripts/marginal_control.py review --workspace <repo> --candidate ACTION_HASH --verdict helpful
 ```
 
+On Windows, replace `python3` with `py -3` and use Windows path separators. From a Codex chat,
+`$marginal` performs plugin discovery and these commands automatically.
+
+`hooks_active` attests at least one live authenticated MARGINAL service for the selected repository;
+`hooks_observed` reports persisted lifecycle evidence. Neither field is the enforcement mode, and
+the privacy-preserving control plane does not expose a raw Codex chat identifier.
+
 `waste` means the repeated action added no useful evidence. `helpful` marks the recommendation as a
 false stop and immediately demotes any active receipt.
 

docs/operations/codex-plugin-submission.md

@@ -3,7 +3,7 @@
 ```text
 status: not_submitted
 status_date: 2026-08-13
-plugin_version: 0.3.1
+plugin_version: 0.3.2
 marketplace_selector: marginal@marginal
 portal_submission_type: skills_only_zip
 portal_access: authentication_required
@@ -32,9 +32,9 @@ and permits repository Tool Enforcement only after a versioned evidence gate pro
 reviewed false stops, and governance overhead. It never reads prompts, source, raw commands, raw
 outputs, transcripts, or Codex credentials for evidence.
 
-**Release notes:** First universal-directory candidate. Adds MARGINAL's local-first Shadow Mode,
-review workflow, Earned Enforcement gates, fail-open demotion, native Codex lifecycle package,
-production logo, eight reviewer cases, and reproducible v0.3.1 archive.
+**Release notes:** Adds a dependency-free native control plane, repository-scoped hook attestation,
+local Shadow Mode, review workflow, Earned Enforcement gates, fail-open demotion, production logo,
+eight reviewer cases, and a reproducible v0.3.2 archive.
 
 Starter prompts are the three `interface.defaultPrompt` entries in
 `plugins/marginal/.codex-plugin/plugin.json`. The production logo is
@@ -67,10 +67,10 @@ coverage or identity changes.
 - [x] Secret-marker scan returns zero persisted occurrences.
 - [x] Reproducible smoke evidence is committed with runtime SHA-256 provenance.
 - [x] Privacy, terms, support, and eight reviewer cases exist.
-- [x] Canonical main contains v0.3.1 after merge and every public Pages URL resolves.
+- [ ] Canonical main contains v0.3.2 after merge and every public Pages URL resolves.
 - [x] A deterministic single-root ZIP builder covers the manifest, skill, hooks, runtime, and logo.
 - [ ] SignalLayer Labs identity and Apps Management write permission are confirmed in Platform.
-- [ ] The v0.3.1 archive is uploaded in Platform and external review is started.
+- [ ] The v0.3.2 archive is uploaded in Platform and external review is started.
 
 Build the exact upload artifact with:
 
@@ -89,4 +89,4 @@ verified SignalLayer Labs identity; none can be inferred from repository or GitH
 external identifier, credential, or reviewer correspondence belongs in this repository.
 
 Acceptance evidence:
-[`codex-plugin-smoke-2026-08-13-v0.3.1.json`](evidence/codex-plugin-smoke-2026-08-13-v0.3.1.json).
+[`codex-plugin-smoke-2026-08-13-v0.3.2.json`](evidence/codex-plugin-smoke-2026-08-13-v0.3.2.json).

docs/operations/codex-plugin-test-cases.json

@@ -1,11 +1,11 @@
 {
   "schema_version": 1,
-  "plugin_version": "0.3.1",
+  "plugin_version": "0.3.2",
   "positive": [
     {
       "id": "positive-shadow-status",
       "prompt": "Use MARGINAL to inspect the current Codex governance mode.",
-      "expected": "Reports Shadow Mode and Tool Enforcement capability without claiming blocking is active."
+      "expected": "Uses the bundled native launcher, reports hook observation separately from Shadow Mode, and does not require a global marginal executable."
     },
     {
       "id": "positive-doctor",

docs/operations/evidence/codex-plugin-smoke-2026-08-13-v0.3.2.json

@@ -0,0 +1,16 @@
+{
+  "codex_version": "codex-cli 0.147.0",
+  "completed_sessions": 1,
+  "directory_archive_sha256": "c45bb71d78d501e3159939de1db5c205ee380943a97c809499f61fad8a8fae8d",
+  "evidence_records": 4,
+  "hook_coverage": 1.0,
+  "installed": true,
+  "marketplace_selector": "marginal@marginal",
+  "native_control_mode": "shadow",
+  "native_control_observed": true,
+  "plugin_version": "0.3.2",
+  "raw_secret_occurrences": 0,
+  "removed": true,
+  "runtime_sha256": "7ea67b6a17d8f44c03b70e29ec29497a00edd0f9c4262e59cb9082f2015eafe6",
+  "shadow_block_count": 0
+}

plugins/marginal/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "marginal",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Evidence-gated compute governance for Codex, local-first and Shadow Mode by default.",
   "author": {
     "name": "SignalLayer Labs",

plugins/marginal/runtime/provenance.json

@@ -1 +1 @@
-{"builder":"scripts/build_codex_plugin.py","python_requires":">=3.10","schema_version":1,"sha256":"98dc5a49e77864fd529c647cc5e81181b9f5ebda234561135a80d4a05823f06d","source_hash":"c0fd650bfd08f8e8550cb88fb1d5b1649203bd44367dcd450f78c9928b8ce6dd"}
+{"builder":"scripts/build_codex_plugin.py","python_requires":">=3.10","schema_version":1,"sha256":"7ea67b6a17d8f44c03b70e29ec29497a00edd0f9c4262e59cb9082f2015eafe6","source_hash":"ab9dfa18a1ddf72f65a64cc7aba86ca0bd1b4e79e0747c983078e5b8ee87e042"}

plugins/marginal/scripts/marginal_control.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""Run MARGINAL's bundled control plane against Codex plugin data."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+
+def _plugin_data() -> Path:
+    configured = os.environ.get("PLUGIN_DATA")
+    if configured:
+        return Path(configured).expanduser().resolve()
+    codex_home = os.environ.get("CODEX_HOME")
+    home = Path(codex_home).expanduser() if codex_home else Path.home() / ".codex"
+    return (home / "plugins" / "data" / "marginal-marginal").resolve()
+
+
+def main(argv: list[str] | None = None) -> int:
+    arguments = list(sys.argv[1:] if argv is None else argv)
+    if not arguments or arguments[0] not in {
+        "status",
+        "doctor",
+        "review",
+        "promote",
+        "demote",
+    }:
+        print(
+            "usage: marginal_control.py {status|doctor|review|promote|demote} [options]",
+            file=sys.stderr,
+        )
+        return 2
+
+    plugin_root = Path(__file__).resolve().parents[1]
+    runtime = plugin_root / "runtime" / "marginal_runtime.pyz"
+    if not runtime.is_file():
+        print(f"MARGINAL runtime not found: {runtime}", file=sys.stderr)
+        return 1
+
+    data = _plugin_data()
+    data.mkdir(parents=True, exist_ok=True, mode=0o700)
+    environment = {
+        name: value
+        for name in ("PATH", "CODEX_HOME", "LANG", "LC_ALL", "SYSTEMROOT")
+        if (value := os.environ.get(name)) is not None
+    }
+    environment["PLUGIN_DATA"] = str(data)
+    environment["PLUGIN_ROOT"] = str(plugin_root)
+    os.execve(
+        sys.executable,
+        [
+            sys.executable,
+            str(runtime),
+            "codex",
+            arguments[0],
+            "--data-dir",
+            str(data),
+            *arguments[1:],
+        ],
+        environment,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())