git-oops 1.0.0__py3-none-any.whl

git_oops-1.0.0.dist-info/METADATA

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: git-oops
+Version: 1.0.0
+Summary: The Dual-Mode Terminal Crash Fixer & Autonomous AI Agent Safety Harness (The Final Legend Edition).
+Author: Hao
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: pytest>=7.0.0
+Dynamic: license-file
+Dynamic: requires-python
+
+<div align="center">
+
+# ⚡ git-oops v1.0.0 (The Final Legend Edition)
+
+### *The Zero-Step Autonomous AI Agent Safety Harness & Terminal Crash Interceptor.*
+**Human Mode: Roasted by a Staff Engineer │ Agent Mode: The Headless Shield for Coding Agents**
+
+<p align="center">
+  <img src="assets/readme-hero.jpg" alt="git-oops Hero Banner" width="850" style="border-radius: 10px; margin: 15px 0;" />
+</p>
+
+[![CI Suite](https://github.com/Hao610/git-oops/actions/workflows/ci.yml/badge.svg)](https://github.com/Hao610/git-oops/actions/workflows/ci.yml)
+[![Version](https://img.shields.io/badge/Release-v1.0.0%20Legend-blue.svg)](https://github.com/Hao610/git-oops/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/Python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue?logo=python)](https://www.python.org/)
+[![Zero-Step-Hooks](https://img.shields.io/badge/Git%20Hooks-Zero--Step%20Global-success)]()
+[![L3-Preflight](https://img.shields.io/badge/L3%20CI%2FCD-%3C0.3s%20Local%20Pre--Flight-green)]()
+[![MCP-Ready](https://img.shields.io/badge/MCP-Native%20Server%20Ready-purple)]()
+[![Spend-Protection](https://img.shields.io/badge/Wallet-Circuit%20Breaker%20Protected-orange)]()
+
+</div>
+
+---
+
+## 😤 Why git-oops?
+
+### For Humans:
+Your script crashes with a 50-line traceback. You're exhausted, and ChatGPT gives you a polite 6-paragraph email instead of a 2-line fix.
+`git-oops` roasts your sloppy code with razor-sharp wit and applies a surgical 1-click git patch directly in your terminal.
+
+### For AI Coding Agents (Claude, Cursor, Windsurf, Codex, Devin):
+Modern autonomous coding agents face catastrophic failure modes:
+1. **Context Bloat**: Multi-thousand line terminal dumps overflow agent context windows.
+2. **Infinite Thrashing**: Agents get trapped in loops editing and reverting the same code.
+3. **Ghost Hallucinations**: Agents import non-existent libraries or fall into typosquatted package traps.
+4. **Blast-Radius Disasters**: Agents accidentally execute `rm -rf` or destructive force-pushes.
+
+**`git-oops` provides the missing runtime safety harness that shields your repository, your sanity, and your wallet.**
+
+---
+
+## ⚡ The Dual-Mode Architecture
+
+```text
+                        [ Terminal Crash / Agent Execution ]
+                                          │
+                   ┌──────────────────────┴──────────────────────┐
+                   ▼                                             ▼
+        [ 🧑‍💻 HUMAN MODE ]                                [ 🤖 AGENT MODE ]
+  • High-Fidelity Rounded Cards                   • Clean Machine-Readable JSON
+  • Caustic Critic Roasts (Staff/Chef)            • 90% Context Log Squeezer & Redactor
+  • Interactive [y/N] Patch Confirmation          • Blast-Radius Firewall & AST Linter
+  • Instant `--undo` Reversion                    • Anti-Thrashing Watchdog & Mutex
+                   │                                             │
+                   └──────────────────────┬──────────────────────┘
+                                          ▼
+                         [ 🛡️ SHA-256 Cache & Circuit Breaker ]
+                         [ 🔌 Native Model Context Protocol (MCP) ]
+```
+
+---
+
+## 🌟 The 20 Super-Capabilities
+
+| # | Capability | Module | What It Does | Why It Matters |
+| :-: | :--- | :--- | :--- | :--- |
+| **1** | 🧑‍💻 **Dual-Mode Engine** | `src/cli.py` | Human visual mode or `--agent` / `--json` headless mode. | Works equally well for human engineers and autonomous agents. |
+| **2** | 🔌 **Native MCP Server** | `src/mcp_server.py` | Exposes tools over stdio (`git-oops --mcp`). | Instantly attaches to Claude Desktop, Cursor, and Windsurf. |
+| **3** | 🛑 **Anti-Thrashing Watchdog** | `src/watchdog.py` | Detects repeated edit-revert oscillations (> 3 times). | Halts runaway agent loops before burning through credits. |
+| **4** | 🛡️ **Blast-Radius Firewall** | `src/firewall.py` | Intercepts `rm -rf`, `force-push`, and wildcard deletions. | Prevents rogue agents from wiping out the filesystem. |
+| **5** | 🕵️ **Supply-Chain Shield** | `src/firewall.py` | Blocks hallucinated/typosquatted package installs. | Protects against AI package hallucination attacks. |
+| **6** | 🚨 **Egress Sniffer Probe** | `src/sentinel.py` | Scans patches for unauthorized phone-home connections. | Blocks trojans and telemetry data exfiltration in patches. |
+| **7** | 🔒 **Multi-Agent Mutex** | `src/watchdog.py` | Cooperative file lease locks across multiple agent sub-workers. | Stops concurrent agents from overwriting each other. |
+| **8** | 🪞 **Shadow Workspace** | `src/shadow.py` | Dry-runs patches inside an ephemeral clone directory. | Zero-risk experimentation; commits only after full validation. |
+| **9** | 👻 **Polyglot Ghost Import Linter** | `src/guardian.py` | 0 ms AST/heuristic check across Python, JS/TS, Go, Rust, Java/Kotlin, C/C++, PHP, Ruby, C#, Swift, Dart, Lua, Shell & exotic scripts. | Blocks patches containing non-existent hallucinated packages in any language. |
+| **10**| 🧪 **Regression Guard** | `src/guardian.py` | Runs project tests in sandbox before modifying files. | Prevents agents from breaking existing features. |
+| **11**| ⚖️ **Cross-Model Consensus** | `src/consensus.py` | Requires 2 independent models to agree on the root cause. | Eliminates single-model hallucination single-points-of-failure. |
+| **12**| ✂️ **Anti-Bloat Complexity** | `src/sentinel.py` | Monitors cyclomatic complexity to prevent code bloat. | Stops agents from writing 8-layer nested spaghetti code. |
+| **13**| 📜 **License Taint Shield** | `src/sentinel.py` | Blocks patches containing viral GPL/AGPL copy-paste headers. | Protects commercial projects from open-source license lawsuits. |
+| **14**| 📉 **Context Log Squeezer** | `src/squeezer.py` | Compresses 5,000-line stacks to 20 focused lines. | Saves 90% of token context window costs. |
+| **15**| 🔒 **Secret Redactor** | `src/squeezer.py` | Automatically masks API keys and tokens (`<REDACTED_SECRET>`). | Prevents credential leakage across external LLMs. |
+| **16**| 🧭 **Intent Prefetch Engine** | `src/sentinel.py` | Markov-chain prediction prefetching next-step responses. | Speeds up multi-turn agent tool execution chains to 0 ms. |
+| **17**| ✈️ **Flight Recorder** | `src/blackbox.py` | Logs every action, motivation, and takes file snapshots. | Full auditability of what your agent did overnight. |
+| **18**| ⏪ **Time-Machine Rewind** | `src/blackbox.py` | `--rewind <step_id>` restores snapshot state. | 1-second recovery if an agent takes a wrong path. |
+| **19**| 🧬 **Antibody Immunity DB** | `src/blackbox.py` | Saves verified solutions to a local pathology ledger. | Next time the same error occurs, resolution is instant. |
+| **20**| 🔄 **Anti-Bit-Rot Evolution** | `src/updater.py` | Auto-detects runtime shifts and model deprecations. | Code never rots or breaks across future Python releases. |
+| **21**| 🪝 **Zero-Step Global Hooks** | `src/hooks.py` | Universal machine-wide git interception via `core.hooksPath`. | Zero manual configuration; protects every repository on the machine. |
+| **22**| ⚡ **Sub-Second L3 Pre-Flight** | `src/hooks.py` | Replicates full GitHub CI/CD locally in <0.3s before commit/push. | Blocks secrets, SQLi, command injection, and test failures instantly. |
+| **23**| 📡 **Dynamic OTA Security Feed**| `src/rules.py` | Silent background auto-sync of latest CVEs & malicious package rules. | Rules update automatically whenever connected; zero code changes needed. |
+| **24**| 🎛️ **Obsidian Glassmorphism HUD**| `src/hud.py` | Live web dashboard (`git-oops --hud`) with dark frosted glass design. | Real-time monitoring of spend, locks, hardware telemetry, and panic salvage. |
+| **25**| ⚡ **1ms Deterministic AST Solver**| `src/solver.py` | Zero-AI / Zero-LLM symbolic compiler deductions for fatal errors. | Fixes NoneType, KeyError, and ZeroDivision in 1ms with 0 tokens and $0.00 cost. |
+| **26**| 🦙 **Pure-Offline Local LLM** | `src/local_llm.py` | Sub-second native connector for Ollama & vLLM (`--local`). | 100% private and air-gapped bug fixing without internet or cloud APIs. |
+| **27**| 🔍 **Supply-Chain Phishing Guard**| `src/supply_chain.py`| Levenshtein distance check + Google OSV live database audit. | Intercepts typosquatted dependency decoy attacks like `reqeusts` and `colorma`. |
+| **28**| 🌡️ **Hardware Sentinel & Throttling**| `src/hardware.py`| Monitors battery (<15%) and thermal limits; pins agents to E-Cores. | Prevents rogue AI agent loops from frying your laptop or draining battery. |
+| **29**| 🛡️ **Pre-PR Staff Gatekeeper** | `src/reviewer.py`| Pre-flight audit comparing branch changes against main (`--review-pr`). | Instant staff-level review of security, complexity drift, and test parity. |
+| **30**| 🩹 **Reflog Autopsy & Crash Replay**| `src/salvage.py`| Rescues lost commits (`--salvage`) and replays variable snapshots (`--replay`).| 1-click disaster recovery even after destructive `git reset --hard` or fatal crashes. |
+
+---
+
+## 🚀 Beginner Quickstart (1-Minute Guide)
+
+### 1. Install Globally:
+```bash
+pip install git-oops
+```
+> **Zero Configuration Required**: `git-oops` automatically registers machine-wide hooks in the background. Every `git commit` and `git push` across your repositories is immediately shielded with sub-second L3 security.
+
+### 2. Live Obsidian Web HUD:
+Launch the real-time glassmorphism dashboard in one command:
+```bash
+git-oops --hud
+```
+
+### 3. Connect to Any AI Tool (MCP or Subshell):
+
+#### Option A: For Claude Desktop / Cursor / Windsurf / Antigravity (MCP):
+Add this to your MCP configuration:
+```json
+{
+  "mcpServers": {
+    "git-oops": {
+      "command": "git-oops",
+      "args": ["--mcp"]
+    }
+  }
+}
+```
+
+#### Option B: For OpenAI Codex / Qoder / Copilot / Aider / Devin:
+Simply tell your agent in prompt or rule:
+> *"Always diagnose and apply patches safely via: `git-oops --agent --file <file> --error \"<error>\" --yes`"*
+It outputs clean machine-readable JSON without ANSI codes.
+
+### 4. Interactive Terminal Commands:
+```bash
+# Human mode (roasts you & shows visual diff)
+git-oops --file broken.py --error "KeyError: 'user_id'"
+
+# 1ms Zero-AI Symbolic AST repair ($0.00 cost)
+git-oops --file broken.py --error "AttributeError: 'NoneType' object has no attribute 'x'" --solver --yes
+
+# Run full L3 security pre-flight manually
+git-oops --pre-commit
+
+# Pre-PR Staff Gatekeeper audit
+git-oops --review-pr
+
+# Resurrect lost work after an agent wipeout
+git-oops --salvage
+```
+
+---
+
+## 🧪 Comprehensive Test Suite
+
+All 34 test suites run in under 4.0 seconds with 100% pass rate:
+
+```bash
+pytest tests -v
+```
+
+```text
+============================= 34 passed in 3.97s ==============================
+```
+
+---
+
+## 🔒 100% Local & Privacy-First (Zero Telemetry)
+
+We believe developer tools should never spy on you or your AI agents:
+- **Zero Telemetry**: No tracking pixels, no user analytics, and zero remote logging.
+- **Air-Gapped Safety**: All firewalls, anti-thrashing heuristics, AST parsing, and secret redactors run **100% locally on your machine**.
+- **Data Sovereignty**: The blackbox flight recorder, antibody memory DB, and shadow sandboxes live strictly in `~/.git_oops/` in your local home directory.
+- **Credential Masking**: High-entropy strings, tokens, and keys are automatically sanitized before reaching any AI model.
+
+---
+
+## 🤝 Documentation & Community
+
+- Check out the [Help & Beginner's Manual](HELP.md) for full MCP step-by-step screenshots and command references.
+- Review our [Legal Terms & Disclaimer](LEGAL.md) for licensing, privacy, and autonomous agent safety notices.
+- Read our [Contributing Guidelines](CONTRIBUTING.md) to set up your environment.
+- Review our [Code of Conduct](CODE_OF_CONDUCT.md).
+- To report security vulnerabilities privately, please review [SECURITY.md](SECURITY.md).

git_oops-1.0.0.dist-info/RECORD

@@ -0,0 +1,32 @@
+git_oops-1.0.0.dist-info/licenses/LICENSE,sha256=f-D9ikgd16MW1Y3Q5ZVpUVJ9Q9nlaWBGjYkvb7V1Jpk,1060
+src/__init__.py,sha256=TAqlZmHKWFEThPP4BmzydmzRMUam1Auf6WlqzGXo83M,394
+src/blackbox.py,sha256=GS9yOrf9joXM2wmA58kBVGvb9NHIRgPe1OTG--oUGzk,3954
+src/circuit_breaker.py,sha256=prszziBmFJtY9_NOLrLOKMe1NV8JytWTTz4VwuGT8lc,4139
+src/cli.py,sha256=rSyUBvnasLJSFDif81xvTeSqwAOtgtA-PcAxws9alqQ,27115
+src/consensus.py,sha256=F8JO8YR2peQhEZo1PrD8mNQEC5czlfILwO2krJqLE6Q,2181
+src/engine.py,sha256=BSyHGHQhvsiKALk1USkL1SFHacujbUpF97EfeoMdWnY,9750
+src/firewall.py,sha256=ewJtR5TWOcG5QMw1-89nw_NbE_KTJDcBDZEJbZ-VnLI,2131
+src/guardian.py,sha256=j8KzmxfejHUoSm7tYanZzHAtuxR9bKtJ3weJEZsDx6k,23003
+src/hardware.py,sha256=Cm79griCEOfdYjdsX2OSR3LQ8U_Bg0Dgz-APOMA1bPw,5667
+src/hooks.py,sha256=A48XWgnX13ysM2-_Mkl6Z2rqS9bTUlyVSnIU_mi4OwY,21224
+src/hud.py,sha256=rq8bHQdJMbBl6JxzcLqLoRghFgMIsQ617yThDAaIx10,16930
+src/local_llm.py,sha256=0zqlyKyqvT4j2aevma8oFT-5Dhxep0ViIwg0NgywfRE,4331
+src/mcp_server.py,sha256=abiv12_8BbSwnuyFdxA6QsTWgTIXDdAvn64hbC2xXoI,4450
+src/replay.py,sha256=8ZR4F7IEv6bt4uMvkqcXAD5PsqWhU6boBF6Eh7cfllg,3523
+src/reviewer.py,sha256=6A_LNChOOuX2VwvRIFxMFyDApsFmglEp4D-fB-QuE2I,5743
+src/rules.py,sha256=7rgCvVXtJflAJswCEBmsKVIUOD1xTsaOxNJsaAJl-FQ,11940
+src/salvage.py,sha256=nKQkOFfL2P3B_D0Cm5aKdoSKTEStNjKYNQBAO6apQLY,3455
+src/sentinel.py,sha256=Sra8tDAPBpAZcJfaJTXn6GRXjKbx3GbJ922COeQ1FD8,3189
+src/shadow.py,sha256=X7J-s-cb5wug6yiw_mZcvQsgWI9eEwOnElrc2toxgec,2695
+src/solver.py,sha256=IvjeqA-4MYQ9pWYh-gz247zPYa7IvgukEveTKHQ311M,7131
+src/squeezer.py,sha256=oJlsztbn3wf87bz_flKWKMoz81eCtyF8feemOwAiH2M,2250
+src/supply_chain.py,sha256=elO0vTOjvaQF8W44XARTsBS8douFIk5RHhNkE-dpEMA,5268
+src/tester.py,sha256=ydzKoyRXnCXdhc8DxMNcJEYvglCD3u9C1Kdh3Y10z1k,1779
+src/ui.py,sha256=Ck8LaSE3pOf7gu2HXNJE0jptrMoyAAc6Tdbvq5GnifM,4495
+src/updater.py,sha256=thJgV3DWyYp5aXMx_nxWw_JhfqWkN4N-op9wWL7N-As,1827
+src/watchdog.py,sha256=KpTBeDxOr2kzii-1ajUqEVrHsqBaqxaq7H4UgqYECZI,3363
+git_oops-1.0.0.dist-info/METADATA,sha256=V4WlI7-iBGAm31fDPLxVBhYmTSnOMATfW4GsAXvR-nE,12620
+git_oops-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+git_oops-1.0.0.dist-info/entry_points.txt,sha256=17TgW51XJC0cHS2fpIc4FLUUWDpR1bM-C6uo-ZvLOq0,42
+git_oops-1.0.0.dist-info/top_level.txt,sha256=74rtVfumQlgAPzR5_2CgYN24MB0XARCg0t-gzk6gTrM,4
+git_oops-1.0.0.dist-info/RECORD,,

git_oops-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

git_oops-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+git-oops = src.cli:main

git_oops-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

git_oops-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+src

src/__init__.py

@@ -0,0 +1,16 @@
+"""
+git-oops: The Autonomous Terminal Crash Fixer & AI Agent Safety Harness.
+Version 1.0.0 (The Final Legend Edition)
+"""
+
+__version__ = "1.0.0"
+
+from src.hooks import ensure_auto_hooks
+from src.rules import trigger_ota_update_background
+
+# Auto-bootstrap zero-step hooks & OTA rules on package import
+try:
+    ensure_auto_hooks()
+    trigger_ota_update_background()
+except Exception:
+    pass

src/blackbox.py

@@ -0,0 +1,119 @@
+"""
+Git-Oops Blackbox & Memory: Flight Recorder, Time-Machine Rewind & Antibody DB
+1. Flight Recorder: Logs agent intentions, tools invoked, and patches applied.
+2. Time-Machine: Rewinds codebase state to any previous step.
+3. Antibody DB: Persistent cross-session immunization patterns.
+"""
+
+import os
+import json
+import time
+import shutil
+import hashlib
+from typing import Dict, Any, List, Optional
+
+DB_DIR = os.path.expanduser("~/.git_oops/memory")
+FLIGHT_RECORDER_FILE = os.path.join(DB_DIR, "flight_recorder.jsonl")
+ANTIBODIES_FILE = os.path.join(DB_DIR, "antibodies.json")
+SNAPSHOTS_DIR = os.path.join(DB_DIR, "snapshots")
+
+
+def _ensure_dirs():
+    os.makedirs(DB_DIR, exist_ok=True)
+    os.makedirs(SNAPSHOTS_DIR, exist_ok=True)
+
+
+def record_step(agent_id: str, action: str, target_file: str, motivation: str, diff: str) -> int:
+    """Records an immutable flight recorder event and takes a file snapshot."""
+    _ensure_dirs()
+    step_id = int(time.time() * 1000)
+    
+    # Snapshot file
+    if os.path.exists(target_file):
+        snap_path = os.path.join(SNAPSHOTS_DIR, f"{step_id}_{os.path.basename(target_file)}")
+        shutil.copy2(target_file, snap_path)
+
+    event = {
+        "step_id": step_id,
+        "timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
+        "agent_id": agent_id,
+        "action": action,
+        "target_file": target_file,
+        "motivation": motivation,
+        "diff_snippet": diff[:300]
+    }
+
+    with open(FLIGHT_RECORDER_FILE, "a", encoding="utf-8") as f:
+        f.write(json.dumps(event) + "\n")
+    return step_id
+
+
+def list_flight_events(limit: int = 10) -> List[Dict[str, Any]]:
+    """Retrieves recent flight recorder events."""
+    _ensure_dirs()
+    if not os.path.exists(FLIGHT_RECORDER_FILE):
+        return []
+    events = []
+    with open(FLIGHT_RECORDER_FILE, "r", encoding="utf-8") as f:
+        for line in f:
+            if line.strip():
+                try:
+                    events.append(json.loads(line.strip()))
+                except Exception:
+                    pass
+    return events[-limit:]
+
+
+def rewind_step(step_id: int) -> bool:
+    """Restores the targeted file state to match the snapshot taken at step_id."""
+    _ensure_dirs()
+    events = list_flight_events(limit=100)
+    target_event = next((e for e in events if e.get("step_id") == step_id), None)
+    if not target_event:
+        return False
+
+    orig_file = target_event["target_file"]
+    snap_path = os.path.join(SNAPSHOTS_DIR, f"{step_id}_{os.path.basename(orig_file)}")
+    if os.path.exists(snap_path):
+        shutil.copy2(snap_path, orig_file)
+        return True
+    return False
+
+
+def register_antibody(error_pattern: str, verified_solution: str, explanation: str):
+    """Stores permanent cross-session immunization pattern."""
+    _ensure_dirs()
+    antibodies = {}
+    if os.path.exists(ANTIBODIES_FILE):
+        try:
+            with open(ANTIBODIES_FILE, "r", encoding="utf-8") as f:
+                antibodies = json.load(f)
+        except Exception:
+            antibodies = {}
+
+    pat_hash = hashlib.sha256(error_pattern.strip().lower().encode()).hexdigest()[:16]
+    antibodies[pat_hash] = {
+        "pattern": error_pattern.strip(),
+        "solution": verified_solution,
+        "explanation": explanation,
+        "learned_at": time.strftime("%Y-%m-%d")
+    }
+
+    with open(ANTIBODIES_FILE, "w", encoding="utf-8") as f:
+        json.dump(antibodies, f, indent=2)
+
+
+def match_antibody(error_log: str) -> Optional[Dict[str, Any]]:
+    """Returns verified architecture pattern if previously solved in past sessions."""
+    _ensure_dirs()
+    if not os.path.exists(ANTIBODIES_FILE):
+        return None
+    try:
+        with open(ANTIBODIES_FILE, "r", encoding="utf-8") as f:
+            antibodies = json.load(f)
+        for _, ab in antibodies.items():
+            if ab["pattern"].lower() in error_log.lower():
+                return ab
+    except Exception:
+        pass
+    return None

src/circuit_breaker.py

@@ -0,0 +1,129 @@
+"""
+Git-Oops Circuit Breaker & Local Token/Cost Cache
+Guarantees absolute spend-protection:
+1. Daily USD hard expenditure ceiling (stops runaway recursive calls)
+2. Exact SHA256 deterministic response cache (zero duplicate API costs)
+3. Transparent token-to-dollar real-time accounting
+"""
+
+import os
+import json
+import time
+import hashlib
+from typing import Dict, Any, Optional
+
+CACHE_DIR = os.path.expanduser("~/.git_oops")
+CACHE_FILE = os.path.join(CACHE_DIR, "cache.json")
+LEDGER_FILE = os.path.join(CACHE_DIR, "spend_ledger.json")
+CONFIG_FILE = os.path.join(CACHE_DIR, "config.json")
+
+# Rates per 1M tokens ($0.15 input, $0.60 output approx Gemini 1.5 Flash)
+COST_PER_INPUT_TOKEN = 0.15 / 1_000_000
+COST_PER_OUTPUT_TOKEN = 0.60 / 1_000_000
+
+
+def _ensure_dir():
+    os.makedirs(CACHE_DIR, exist_ok=True)
+
+
+def get_daily_spend() -> float:
+    """Calculates total spend accumulated today."""
+    _ensure_dir()
+    if not os.path.exists(LEDGER_FILE):
+        return 0.0
+    try:
+        with open(LEDGER_FILE, "r", encoding="utf-8") as f:
+            ledger = json.load(f)
+        today = time.strftime("%Y-%m-%d")
+        return float(ledger.get(today, 0.0))
+    except Exception:
+        return 0.0
+
+
+def record_spend(tokens_in: int, tokens_out: int) -> float:
+    """Updates daily spend ledger and returns cost incurred."""
+    _ensure_dir()
+    cost = (tokens_in * COST_PER_INPUT_TOKEN) + (tokens_out * COST_PER_OUTPUT_TOKEN)
+    today = time.strftime("%Y-%m-%d")
+    ledger = {}
+    if os.path.exists(LEDGER_FILE):
+        try:
+            with open(LEDGER_FILE, "r", encoding="utf-8") as f:
+                ledger = json.load(f)
+        except Exception:
+            ledger = {}
+    
+    current = ledger.get(today, 0.0)
+    ledger[today] = round(current + cost, 5)
+    with open(LEDGER_FILE, "w", encoding="utf-8") as f:
+        json.dump(ledger, f, indent=2)
+    return cost
+
+
+def check_circuit_breaker(spend_limit_usd: float = 1.0) -> bool:
+    """
+    Returns True if safe to run; raises PermissionError if budget exceeded.
+    Protects developers from unexpected cloud bills.
+    """
+    spent = get_daily_spend()
+    if spent >= spend_limit_usd:
+        raise PermissionError(
+            f"🚨 [CIRCUIT BREAKER TRIGGERED] Daily budget of ${spend_limit_usd:.2f} exceeded! "
+            f"(Spent today: ${spent:.4f}). Requests blocked to protect your wallet."
+        )
+    return True
+
+
+def get_cached_response(prompt_hash: str) -> Optional[Dict[str, Any]]:
+    """Retrieves deterministic cached patch if previously analyzed."""
+    _ensure_dir()
+    if not os.path.exists(CACHE_FILE):
+        return None
+    try:
+        with open(CACHE_FILE, "r", encoding="utf-8") as f:
+            cache = json.load(f)
+        return cache.get(prompt_hash)
+    except Exception:
+        return None
+
+
+def store_cached_response(prompt_hash: str, response: Dict[str, Any]):
+    """Caches response by content hash to prevent redundant duplicate queries."""
+    _ensure_dir()
+    cache = {}
+    if os.path.exists(CACHE_FILE):
+        try:
+            with open(CACHE_FILE, "r", encoding="utf-8") as f:
+                cache = json.load(f)
+        except Exception:
+            cache = {}
+    cache[prompt_hash] = response
+    with open(CACHE_FILE, "w", encoding="utf-8") as f:
+        json.dump(cache, f, indent=2)
+
+
+def hash_content(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def get_default_config() -> Dict[str, Any]:
+    """Retrieves user persistent configuration."""
+    _ensure_dir()
+    default_cfg = {"personality": "staff", "daily_budget": 1.0}
+    if not os.path.exists(CONFIG_FILE):
+        return default_cfg
+    try:
+        with open(CONFIG_FILE, "r", encoding="utf-8") as f:
+            cfg = json.load(f)
+            return {**default_cfg, **cfg}
+    except Exception:
+        return default_cfg
+
+
+def set_config_value(key: str, value: Any):
+    """Saves a persistent configuration key (e.g. personality or daily budget)."""
+    _ensure_dir()
+    cfg = get_default_config()
+    cfg[key] = value
+    with open(CONFIG_FILE, "w", encoding="utf-8") as f:
+        json.dump(cfg, f, indent=2)