ToeStub

Job OS cognitive governor for external systems — pin-sealed multi-source oilfield job coherence, explore-vs-certify firewall, multi-well rotation, partner audit, and optional MCP attachment for agent hosts (Cursor / Claude / Grok).

Pin sealed. Explore never certifies. Never λ=γ.

This is a standalone distribution extracted from the 123abc-grok research monorepo. External teams can clone, configure, and run without the protein dual-gate stack.

License: MIT

---

Quick start (Windows)

git clone https://github.com/RogueGringo/ToeStub.git
cd ToeStub
install.bat
menu.bat

Script	Role
install.bat	Python deps + import check
menu.bat	CMD menu (cfg, smoke, rotation, audit, MCP)
run_mcp.bat	Start stdio MCP server for hosts
cfg\toestub.ini	Paths and job defaults

Menu map

1. Show configuration
2. Edit cfg\toestub.ini (Notepad)
3. Fixture smoke (expects certified)
4. Custom run (LAS/MP/survey from cfg)
5. Multi-well rotation (fixture dual well)
6. Catalog runs
7. Audit latest run
8. MCP connect help
9. Start MCP server (stdio)
   T. Unit tests
   I. Re-install deps
10. Exit

---

Configure

Edit cfg/toestub.ini:

[paths]
default_las = C:\path\to\well.las
default_micropulse = C:\path\to\MicroPulse_dir
default_survey = C:\path\to\SURVEY.csv
out_dir = out\job_os

[job]
channel_pack = surface_min
max_rows = 500
max_depth_mono_violations = 5
with_dynamical_topology = true

Free params are closed-set only (align_mode, window_scale, channel_pack, null_policy, survey_gate, regime_mode).
Pin knobs (depth_mono_eps, mono violations) are pin_config, not free.

---

MCP (agent hosts)

run_mcp.bat

Or host JSON (examples/toestub.mcp.json):

{
  "mcpServers": {
    "toestub": {
      "command": "python",
      "args": ["-m", "toestub.mcp_server"],
      "env": {
        "PYTHONPATH": "C:/PRIMEdEV-1/ToeStub",
        "TOESTUB_REPO_ROOT": "C:/PRIMEdEV-1/ToeStub"
      }
    }
  }
}

Point PYTHONPATH / TOESTUB_REPO_ROOT at your clone path.

Tools

Tool	Purpose
toestub_job_run	Job OS OS-mode loop
toestub_job_catalog	INDEX of runs
toestub_job_rotation	Multi-well same pin
toestub_job_audit	Partner audit (no re-ingest)
toestub_firewall_read	Read FIREWALL.json

---

CLI (operators)

set PYTHONPATH=%CD%
python job_coherence.py --os --las fixtures\mini_edr.las --out-dir out\job_os
python job_coherence.py --catalog --out-dir out\job_os
python job_coherence.py --audit out\job_os\<run_id>
python job_coherence.py --rotation examples\job_rotation_fixture.manifest.json --out-dir out\rotation

---

Law

• CERTIFY = pin hard seal + fixed-point (empty free board × K)
• EXPLORE = science / topology / λ1 trends — not_acceptance
• Near-miss: explore looks good, certify fails → reject for ship
• No shell tool; no soft_T / pin rewrite via free params

Design: docs/design-toestub-mcp.md

---

Requirements

• Windows 10+ (menu.bat) or any OS for Python/MCP
• Python 3.11+
• pip install -r requirements.txt

---

Provenance

Kernel modules: realm/job_os, realm/dynamical_topology, realm/kb_geometry, toestub
Upstream research monorepo: RogueGringo/123abc-grok

---

License

Same as upstream monorepo unless otherwise noted. Contact maintainer for commercial terms.