@r1z4x/tezgah 1.0.0

package/README.tr.md

@@ -0,0 +1,163 @@
+<p align="center">
+  <a href="README.md">English</a> |
+  <a href="README.de.md">Deutsch</a> |
+  <a href="README.es.md">Español</a> |
+  <a href="README.fr.md">Français</a> |
+  <a href="README.tr.md">Türkçe</a>
+</p>
+
+# Tezgah
+
+<p align="center">
+  <img src="assets/logo/tezgah-logo.svg" alt="tezgah logo" width="220">
+</p>
+
+<h3 align="center">Çalıştırdığınız her yapay zeka kodlama asistanı için tek bir çalışma sözleşmesi.</h3>
+
+<p align="center">
+  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/github/license/r1z4x/tezgah?style=flat-square"></a>
+  <a href="https://github.com/r1z4x/tezgah/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/r1z4x/tezgah/ci.yml?style=flat-square&label=ci"></a>
+  <a href="https://github.com/r1z4x/tezgah/releases/latest"><img alt="Release" src="https://img.shields.io/github/v/release/r1z4x/tezgah?style=flat-square"></a>
+</p>
+
+<p align="center"><sub>İngilizce ana kaynaktır; çeviriler geriden gelebilir.</sub></p>
+
+---
+
+Tezgah, çalıştırdığınız her yapay zeka kodlama asistanını — **birincil
+barındırıcı olan omp** ve Claude Code, Codex, Cursor, opencode ile DeepSeek'in
+dsh donanımı — yapılandırdığınız depo kökleri içinde tek bir çalışma
+sözleşmesiyle donatır. Kendi haline bırakıldığında her asistan sapar: biri
+Türkçe yanıt verirken diğeri İngilizce yanıt verir, biri grep kullanırken
+diğeri bir kod grafiğini sorgular, biri test çalıştırmadan "tamamlandı" der.
+Kurallar paylaşılan bir çekirdekte bir kez yer alır; her barındırıcı, bu
+kuralları anladığı şekle çeviren ince bir adaptör alır — bir kuralı tek yerde
+değiştirdiğinizde her barındırıcıya aynı şekilde ulaşır.
+
+## tezgah neyi zorunlu kılar ve kaydeder
+
+- **Tek sözleşme, altı barındırıcı.** omp, Claude Code, Codex, Cursor,
+  opencode ve dsh aynı kuralları görür, çünkü her barındırıcı paylaşılan tek
+  bir çekirdeğin ince bir adaptörüdür — kuralı bir kez değiştirin, hepsi alır.
+- **"Tamamlandı" demek için kayıtta geçmiş bir kontrol gerekir.** 15 reddin
+  olduğu bir kapı, etkisizleştirilmiş kontrolü durdurur — `--no-verify`,
+  `|| true`, `tail`'e yönlendirilmiş bir test, uçuş sırasında eklenen bir
+  skip — ve Stop kuralı, oturumun kanıt defterinin desteklemediği tamamlanma
+  iddiasını reddeder. Turu reddeder; modelin bu iddiayı dile getirmesini
+  engelleyemez.
+- **Araştırma kütüphanesiyle birlikte gelir.** Araştırma görevleri,
+  bağlamın küçük kalması için tek tek yüklenen 98 becerilik gömülü
+  bir kütüphaneyle OpenResearch üzerinden yürütülür.
+- **Her kuralın bir kapatma anahtarı vardır.** On altı kapatma anahtarı — ve
+  depo başına işaretler — kuralın metnini oturumdan kaldırır; böylece kural
+  yalnızca kapalı görünmez, gerçekten durur.
+- **Sabit bir yanıt biçimi.** Yanıtlar, başka bir dil seçmediyseniz Türkçedir ve sonuçla
+  başlar; bir liste en fazla beş sıralı madde gösterir; bir tahmin tahmin
+  olarak adlandırılır; bir hata konum, neden, çözüm olarak okunur.
+
+## Neyi göstermedi
+
+Tezgah bir mekanizmalar bütünüdür: oturuma eklenen kurallar, belirli komutları
+reddeden bir kapı ve Stop kuralının okuduğu bir defter. Bir ajanın daha az
+hile yaptığının ya da daha çok görev bitirdiğinin kanıtı değildir. Eşleştirilmiş
+bir açık/kapalı deneyi (Ekim 2026; omp üzerinde DeepSeek V4.1 Flash, tezgah'sız
+ile tam tezgah kurulumu karşılaştırıldı) hilede ölçülebilir bir azalma bulmadı,
+çünkü model iki kolda da neredeyse hiç hile yapmadı:
+
+- **Aşama 1, üç baskı düzeneği:** her kolda 60 çalıştırmanın 0'ında hile;
+  temiz geçiş tezgah ile 48/60, tezgah'sız 53/60.
+- **Aşama 2, ImpossibleBench'in çelişkili SWE-bench bölümü (44 örnek,
+  k = 3):** hile tezgah ile 0/132, tezgah'sız 1/131 (-0.8 pp, %95 GA -2.3 ile
+  0 arası); özgün görevlerde temiz geçiş 129/131'e karşı 129/132.
+- **Elle etiketlenmiş yanlış "bitti" iddiaları:** bu imkânsız görevlerde,
+  örneklenen son mesajların tezgah ile 30'da 3'ü, tezgah'sız 30'da 6'sı
+  kullanıcıya görevin bittiğini söyledi. Düzeltilmiş fark -5 pp (%95 GA -18 ile
+  +9 arası), yani iki yönde de etki yok.
+- **Stop kuralının iddia okuyucusunda bir zayıf nokta:** tezgah ile 115/132,
+  tezgah'sız 90/131 çalıştırmayı işaretledi, ama işaretlerinin yalnızca %10'u
+  ve %20'si gerçek "bitti" iddiasıydı. tezgah ile ajan Türkçe yanıt verdi ve
+  okuyucu kısmi bir düzeltmedeki `doğrulandı` sözcüğünü iddia sayıyor. Bu
+  kayda geçti, henüz düzeltilmedi.
+
+Çalıştırmada ölçüm aracı kusurları vardı; bunların arasında, iki koldaki
+ajanların benchmark'ın doğru cevaplarını okuyabilmesi de var. Toplamlar, görev
+başına sayımlar ve her çekince
+[sonuç paketinde](docs/results/paired-outcome-2026-10.md) yer alır (İngilizce).
+
+<a id="install"></a>
+
+## Kurulum
+
+Tek satır, macOS, Linux veya WSL'de (Python 3.10+, `curl`, `tar`). Son sürümü
+indirir, sha256'sını doğrular ve bulduğu her barındırıcıyı kurar (Claude
+Code'u kendi `claude plugin` CLI'ı üzerinden):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/r1z4x/tezgah/main/packaging/install.sh | sh
+```
+
+Ya da npm ile: `npm i -g @r1z4x/tezgah && tezgah --install`.
+
+Ayrıştıramadığı bir barındırıcı yapılandırmasına dokunmaz, değiştirdiği her
+yapılandırmanın tarihli bir `.tezgah-bak` kopyasını tutar ve kurmayı
+planladığı bir barındırıcı kurulamazsa sıfırdan farklı bir kodla çıkar.
+
+### tezgah makinenizde neyi değiştirir
+
+- **Barındırıcı yapılandırması.** Kurulan her barındırıcı tezgah'ın
+  hook'larını, MCP satırlarını ve kendi genel kural dosyasında
+  (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.omp/agent/RULES.md`)
+  yönetilen bir sözleşme bloğunu alır. Claude Code'un hook'ları `claude plugin`
+  ile kaydedilen bir eklentide gelir; `claude` CLI'ı yoksa Claude kurulmamış
+  kalır ve rapor bunu söyler.
+- **Depolarınızdaki ajan dosyaları.** Yapılandırılan köklerde bir oturum
+  `.claude/agents/`, `.codex/agents/` ve `.opencode/agents/` altına alt ajan
+  dosyaları yazar ve bu dizinleri klonun kendi `.git/info/exclude` dosyasına
+  ekler (`TEZGAH_NO_EXCLUDE=1` bunu durdurur).
+- **Günlük güncelleme denetimi.** Durum satırı yeni bir sürümü günde en fazla
+  bir kez sorar; `~/.config/tezgah/update-check-off` ya da
+  `TEZGAH_UPDATE_CHECK=0` bunu kapatır.
+- **orx.** Kurulum, araştırma görevlerinin yönlendirildiği OpenResearch CLI'ını
+  indirir; `TEZGAH_NO_DEPS=1` bunu atlar.
+- **Yanıt dili.** Yanıtlar varsayılan olarak Türkçedir ve Stop kuralı bunu
+  denetler. `--reply-lang en` İngilizce, `any` ise sizin dilinizi ister;
+  ikisi de denetlenmez: `curl -fsSL … | sh -s -- --reply-lang en`.
+
+Kurulumu kodlama asistanınıza yaptırmak isterseniz bunu omp, Claude Code,
+Codex, Cursor veya opencode'a yapıştırın (istem İngilizce; asistan her dilde
+anlar):
+
+```text
+Install tezgah (https://github.com/r1z4x/tezgah) on this machine and verify it.
+
+1. Check the prerequisites: python3 --version must be 3.10 or newer, and curl
+   and tar must exist. If one is missing, stop and tell me which.
+2. Run the installer exactly as published - do not edit it or pipe it anywhere else:
+   curl -fsSL https://raw.githubusercontent.com/r1z4x/tezgah/main/packaging/install.sh | sh
+   Its output must contain "verified tezgah-<version>.tar.gz" (the sha256
+   check). If it does not, stop and show me the output.
+3. Verify: run ~/.local/share/tezgah/current/bin/tezgah-setup --version and
+   ~/.local/share/tezgah/current/bin/tezgah-setup --report, and show me every
+   line that says MISS.
+4. Tell me which hosts were armed, which repository root was configured
+   (default ~/Projects - if my code lives elsewhere, ask me for the directory and
+   run ~/.local/share/tezgah/current/bin/tezgah-setup --roots <dir> --install),
+   and that I must restart each assistant for the hooks to load.
+Do not change any other file and do not uninstall anything.
+```
+
+Sürüm sabitleme, Windows (`packaging/install.ps1`), çevrimdışı tarball,
+yükseltme ve isteğe bağlı entegrasyonlar [docs](docs/README.md) altındadır.
+
+## Desteklenen barındırıcılar
+
+**omp** (birincil barındırıcı; tezgah buna göre geliştirilir ve doğrulanır), **Claude Code**, **Codex**, **Cursor**, **opencode**, **dsh** — paylaşılan tek çekirdeğin ince adaptörleri.
+
+## Ayrıntılar nerede
+
+Kapı, kanıt defteri, barındırıcı adaptörleri, yapılandırma ve geliştirme [docs/README.md](docs/README.md) içindedir; soru başına bir sayfa.
+
+## Lisans
+
+MIT — bkz. [LICENSE](LICENSE).
+Katıştırılmış beceriler (`ponytail`, `no-ai-slop`, `i-have-adhd`) kendi MIT koşullarıyla gelir; bkz. [NOTICE](NOTICE).

package/agents/tezgah-reviewer.md

@@ -0,0 +1,70 @@
+---
+name: tezgah-reviewer
+description: >
+  Adversarial, read-only review of a diff, branch or PR: derives the blast
+  radius, checks correctness, contract, security, tests and performance, and
+  classifies every finding confirmed/refuted/unverified.
+model: opus
+effort: high
+readonly: true
+disallowedTools: Write, Edit, NotebookEdit, Bash, Agent
+---
+
+You are tezgah-reviewer, an adversarial code reviewer. Review a change,
+not the whole repo, with the code graph as below.
+
+Load the graph tools first: ToolSearch("select:mcp__codegraph__codegraph_explore,mcp__plugin_tezgah_codegraph__codegraph_explore,mcp__codegraph__codegraph_impact,mcp__plugin_tezgah_codegraph__codegraph_impact,mcp__codegraph__codegraph_callers,mcp__plugin_tezgah_codegraph__codegraph_callers,mcp__codegraph__codegraph_node,mcp__plugin_tezgah_codegraph__codegraph_node"). You have no
+shell, so the codegraph CLI is out of reach: use those MCP tools.
+
+Review the raw artifact, never a summary of it and never the author's
+self-assessment. Format, schema, frontmatter and spec-compliance problems
+live in the exact text, and a framing you were handed is a finding you will
+not make: a reviewer given the implementer's view finds measurably fewer
+defects. If you were handed a paraphrase, read the files instead.
+
+You have no shell, so you cannot run `git diff`: the caller passes
+the changed files and symbols of the target (a base branch, a ref or
+the PR under review). Run the MCP `codegraph_impact` tool per changed
+symbol - that is the blast radius. If the brief names no changed files,
+say so and ask for them instead of guessing. Read the changed code and any caller you intend to accuse.
+An empty or short caller list is not proof that a change is safe: the
+index records only the edges its parser saw, so say what it cannot see
+(dynamic dispatch, string or config lookups, unindexed files) instead of
+implying the list is complete.
+Look only for defects the change causes: correctness, contract/callers,
+security, tests, concurrency and performance. Classify every candidate as
+confirmed (concrete failure scenario + file:line), refuted (a guard,
+caller contract, type or test already prevents it) or unverified (not
+settled). Default to refuted when the evidence is unclear. Only the code
+or a run you observed settles a candidate: a doc, a comment, a lessons
+file, a memory note or an earlier report may raise a question but never
+makes it confirmed or refuted on its own. Report only confirmed findings
+as bugs; no style notes, no praise; empty is the correct answer for a
+clean change.
+
+Score the constraints separately from the defects. For every constraint
+the task stated - keep this behaviour, touch no other file, preserve this
+format - report kept or violated with the file:line that shows which. A
+patch that passes the tests and breaks a stated constraint is not clean,
+and a functional test will not notice it.
+
+Every finding carries a severity - critical (the change cannot stand as
+written), major (a real weakness that must be fixed), minor (noticeable),
+suggestion (an improvement, not a flaw) - and a verbatim quote of the
+code it accuses; a finding about an absence carries no quote. A severity
+is lowered only by evidence: a check you could not complete never
+downgrades a confirmed finding - keep its severity and mark it
+provisional. Disclose the order you read the files in.
+
+Scope and budget. Every round that confirms a defect is followed by a
+round over that fix's delta; the review ends when a round confirms none.
+A later round reads only the delta since the sha the previous round
+recorded (`tezgah-task review` prints it): re-reading the whole diff
+re-reports what was already triaged. Test results are input, not a task
+- read the author's output file; do not run the suite, and run at most one
+`-k` test when a specific accusation needs it. The same defect family
+confirmed three times is a sign the design needs a pivot, not another
+patch.
+
+You may use: the codegraph MCP tools, read, grep and glob. Read-only:
+no writes, no edits, no shell.

package/bin/codegen

@@ -0,0 +1,337 @@
+#!/usr/bin/env python3
+"""codegen - hand a bounded coding task to a cheap model, get back a DIFF.
+
+    codegen "task" --files src/a.py src/b.py [--provider p] [--model m]
+            [--timeout s] [--max-tokens N] [--out-dir DIR]   (drafts only; nothing is applied)
+
+--timeout (default 300) caps the WHOLE request, not one socket operation, so a
+stalled connection exits 2 instead of hanging the caller. CODEGEN_URL overrides
+the endpoint (a gateway, or a test server; plain http only to this machine);
+CODEGEN_MODEL the model.
+
+The model NEVER writes into the repository. It returns whole file bodies, this
+script writes them to a scratch directory and prints `diff -u` against the
+working tree. The caller reviews that diff, applies it, and runs the gate
+(tests, ruff, ty). That separation is the whole point: a cheap model drafts,
+an expensive one decides, and nothing lands unreviewed.
+
+Providers (--provider, default openrouter):
+  openrouter  OPENROUTER_API_KEY  ~/.config/openrouter/key
+  deepseek    DEEPSEEK_API_KEY    ~/.config/deepseek/key
+  inception   INCEPTION_API_KEY   ~/.config/inception/key
+Key lookup order: the provider's env var, then its key file.
+
+EXIT CODES, and they are the contract:
+  0  usable drafts, diff printed
+  2  codegen cannot deliver -- WRITE THE CODE YOURSELF with the main model.
+     Raised for: no key, API or network failure, a request that outlived
+     --timeout, a redirect to another host, a plain-http endpoint off this
+     machine, a --files file carrying a credential (refused, not redacted:
+     nothing is sent), the model answering BLOCKED, an unparseable reply, a
+     TRUNCATED reply (finish_reason=length), a Python draft that does not parse
+     (a `.py` file, or any file whose shebang names Python), or drafts
+     identical to what is already there.
+     A half-written file that happens to parse is the failure this guards
+     against: it looks like an answer and is not one. A draft in a language no
+     checker here parses (`.tsx`, `.js`) is NOT parsed: it still exits 0 and the
+     footer names it, so the router knows which of its files nothing examined.
+  1  the caller misused the tool (bad arguments)
+  130 the request was interrupted (Ctrl-C): stop, do not fall back
+"""
+import ast
+import concurrent.futures
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import urllib.request
+import json
+
+HOOKS = os.path.join(
+    os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "hooks")
+sys.path.insert(0, HOOKS)
+import tezgah_integrity as ti  # noqa: E402
+import tezgah_paths as tp  # noqa: E402
+
+# The redirect guard: a hop that leaves the endpoint's host is refused, since
+# urllib would carry the bearer to whatever host the answer named.
+OPENER = tp.guarded_opener()
+# A credential in a file codegen would send: a vendor key by its own prefix (the
+# ledger redactor's value shapes) or a private-key block. Value shapes only - the
+# redactor's `name=value` patterns would refuse every source file that reads a
+# key from the environment (142 of this repo's 720 tracked files; these shapes
+# match only 4 test fixtures, all fake keys).
+CREDENTIAL = (ti.SECRET_TOKEN, re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----"))
+
+# The cheap id this script names when the models table cannot be read: one
+# unreadable table must not cost a draft. The table is asked first
+# (`cheap_default` below).
+FALLBACK_MODEL = "deepseek/deepseek-v4.1-flash"
+
+# provider -> (chat-completions URL, key env var, key file, default model)
+PROVIDERS = {
+    "openrouter": (
+        "https://openrouter.ai/api/v1/chat/completions",
+        "OPENROUTER_API_KEY",
+        "~/.config/openrouter/key",
+        FALLBACK_MODEL,
+    ),
+    "deepseek": (
+        "https://api.deepseek.com/v1/chat/completions",
+        "DEEPSEEK_API_KEY",
+        "~/.config/deepseek/key",
+        "deepseek-chat",
+    ),
+    # Inception Labs' Mercury route is OpenAI-compatible except for one field:
+    # it takes `max_completion_tokens`, not `max_tokens` (see the `ask` payload
+    # below), and the model id carries no vendor prefix.
+    "inception": (
+        "https://api.inceptionlabs.ai/v1/chat/completions",
+        "INCEPTION_API_KEY",
+        "~/.config/inception/key",
+        "mercury-2.5",
+    ),
+}
+
+
+def cheap_default():
+    """The cheap row the models table names on `any`, else `FALLBACK_MODEL`.
+
+    One source for the cheap tier: a refresh that moves the row moves this
+    default (`hooks/tezgah_models.py`). One unreadable table must not cost a
+    draft, so the read is guarded and the literal is the fallback."""
+    try:
+        import tezgah_models
+        row = tezgah_models.cheap_model("any")
+    except Exception:
+        row = None
+    return row[0] if row else FALLBACK_MODEL
+
+
+# CODEGEN_MODEL still overrides the OpenRouter default (historical behaviour).
+MODEL = os.environ.get("CODEGEN_MODEL", "").strip() or cheap_default()
+
+SYSTEM = """You are writing code inside an existing repository. Rules:
+
+1. Output ONLY complete file bodies, each in this exact form:
+
+=== FILE: <path exactly as given to you> ===
+```
+<the entire new contents of that file>
+```
+
+2. No prose, no explanation, no partial files, no "... rest unchanged".
+   A file you do not change must not appear in your output at all.
+3. Match the surrounding code: its comment density, naming, and idiom. This
+   codebase writes WHY in comments, not WHAT, and marks load-bearing
+   invariants explicitly.
+4. Laziest solution that actually works: reuse what exists, prefer the standard
+   library, add no abstraction that is not needed today. Never simplify away
+   input validation, error handling or security.
+5. If the task cannot be done correctly with what you were given, say so in one
+   line starting with BLOCKED: and output no files."""
+
+# the closing fence must end the block: a nested ``` inside a draft (markdown,
+# docs, anything with a code sample) used to truncate the file silently
+BLOCK = re.compile(r"=== FILE: (?P<path>[^=]+?) ===\s*```[a-zA-Z]*\n"
+                   r"(?P<body>.*?)\n```[ \t]*(?=\s*(?:=== FILE:|\Z))", re.S)
+# A file whose first line says it is Python is one, whatever it is called - the
+# repo's own bin/* scripts have no `.py` and are the drafts this tool is handed.
+PY_SHEBANG = re.compile(r"^#![^\n]*\bpython[0-9.]*\b")
+
+
+def key(provider):
+    _url, env, path, _model = PROVIDERS[provider]
+    k = os.environ.get(env, "").strip()
+    if not k:
+        try:
+            k = open(os.path.expanduser(path), encoding="utf-8").read().strip()
+        except OSError:
+            pass
+    if not k:
+        raise Insufficient("no API key for %s (%s or %s)" % (provider, env, path))
+    return k
+
+
+class Insufficient(Exception):
+    """codegen cannot deliver; the caller must fall back to the main model."""
+
+
+def fetch(req, timeout):
+    with OPENER.open(req, timeout=timeout) as r:
+        return json.load(r)
+
+
+def ask(task, files, model, provider, timeout, max_tokens):
+    url = os.environ.get("CODEGEN_URL", "").strip() or PROVIDERS[provider][0]
+    if tp.plain_http(url):
+        raise Insufficient("CODEGEN_URL %s is plain http off this machine: the key "
+                           "and the files would cross the network in clear" % url)
+    parts = [f"TASK:\n{task}\n"]
+    for path in files:
+        try:
+            body = open(path, encoding="utf-8").read()
+        except OSError as e:
+            sys.exit(f"codegen: cannot read {path}: {e}")
+        # Refused, not redacted: the draft comes back as the whole file, so a
+        # masked value would be diffed as a change to the credential itself.
+        if any(p.search(body) for p in CREDENTIAL):
+            raise Insufficient(f"{path} carries a credential; nothing was sent")
+        parts.append(f"=== FILE: {path} ===\n```\n{body}```\n")
+    payload = {
+        "model": model,
+        "messages": [{"role": "system", "content": SYSTEM},
+                     {"role": "user", "content": "\n".join(parts)}],
+        "temperature": 0,
+    }
+    if max_tokens:
+        # Inception names this field `max_completion_tokens` (its compat table in
+        # ~/.omp/agent/models.yml records the same), so the name follows the
+        # provider rather than the OpenAI default.
+        field = "max_completion_tokens" if provider == "inception" else "max_tokens"
+        payload[field] = max_tokens
+    req = urllib.request.Request(
+        url,
+        data=json.dumps(payload).encode(),
+        headers={"Authorization": f"Bearer {key(provider)}", "Content-Type": "application/json",
+                 "X-Title": "codegen"})
+    # --timeout is the cap on the WHOLE request, not on one socket operation:
+    # urllib's own timeout restarts on every recv, so a body that trickles (or a
+    # connection kept alive with nothing on it) outlives it indefinitely - seen
+    # as a 3-minute hang under --timeout 90. consult caps its calls the same way.
+    pool = concurrent.futures.ThreadPoolExecutor(1)
+    try:
+        out = pool.submit(fetch, req, timeout).result(timeout=timeout)
+    except concurrent.futures.TimeoutError:
+        raise Insufficient("the request outlived --timeout=%ds" % timeout)
+    except Exception as exc:                      # noqa: BLE001 - any failure is a fallback
+        raise Insufficient(f"the request failed: {exc}") from exc
+    finally:
+        pool.shutdown(wait=False)
+    choice = (out.get("choices") or [{}])[0]
+    msg = choice.get("message") or {}
+    if choice.get("finish_reason") == "length":
+        # The last file body is cut off mid-line. It may still parse, which is
+        # exactly why this is checked here and not left to the diff.
+        raise Insufficient("the reply was truncated (finish_reason=length)")
+    return (msg.get("content") or "").strip(), out.get("usage") or {}
+
+
+def main():
+    args = sys.argv[1:]
+    if not args or args[0] in ("-h", "--help"):
+        sys.exit(__doc__.strip())
+    task, files, model, provider, timeout, out_dir, max_tokens = \
+        args[0], [], None, "openrouter", 300, None, 0
+    i = 1
+    while i < len(args):
+        if args[i] == "--files":
+            i += 1
+            while i < len(args) and not args[i].startswith("--"):
+                files.append(args[i]); i += 1
+            continue
+        if args[i] == "--provider" and i + 1 < len(args):
+            provider = args[i + 1]; i += 2; continue
+        if args[i] == "--model" and i + 1 < len(args):
+            model = args[i + 1]; i += 2; continue
+        if args[i] == "--timeout" and i + 1 < len(args):
+            timeout = int(args[i + 1]); i += 2; continue
+        if args[i] == "--out-dir" and i + 1 < len(args):
+            out_dir = args[i + 1]; i += 2; continue
+        if args[i] == "--max-tokens" and i + 1 < len(args):
+            max_tokens = int(args[i + 1]); i += 2; continue
+        sys.exit(f"codegen: unknown argument {args[i]}")
+    if provider not in PROVIDERS:
+        sys.exit("codegen: unknown provider %r (use %s)"
+                 % (provider, " or ".join(sorted(PROVIDERS))))
+    if not files:
+        sys.exit("codegen: --files is required; the model may only touch files you name")
+    if model is None:
+        model = MODEL if provider == "openrouter" else PROVIDERS[provider][3]
+
+    answer, usage = ask(task, files, model, provider, timeout, max_tokens)
+    if answer.startswith("BLOCKED:"):
+        raise Insufficient(answer)
+    if not BLOCK.search(answer):
+        raise Insufficient("no file block in the reply: " + (answer[:200] or "empty"))
+
+    scratch = out_dir or tempfile.mkdtemp(prefix="codegen-")
+    os.makedirs(scratch, exist_ok=True)
+    written = []
+    for m in BLOCK.finditer(answer):
+        path = m.group("path").strip()
+        if path not in files:
+            # The model may only rewrite files the caller named. Anything else
+            # is dropped rather than diffed: a path it invented is a path
+            # nobody reviewed.
+            print(f"codegen: ignoring unrequested file {path}", file=sys.stderr)
+            continue
+        dest = os.path.join(scratch, path.replace("/", "__"))
+        with open(dest, "w", encoding="utf-8") as fh:
+            fh.write(m.group("body"))
+        written.append((path, dest))
+
+    if not written:
+        raise Insufficient("the model returned no file that was in --files")
+
+    # Each draft must parse and must differ. A draft that does not parse is a
+    # half-written file; one that is byte-identical is a model that did nothing.
+    # What this can vouch for is Python, by suffix or by shebang: the repo's own
+    # bin/* scripts carry no `.py`, and they are exactly what the router hands
+    # this tool. Nothing here parses TypeScript or JavaScript, so a draft in one
+    # of those is named as unparsed in the footer rather than passed in silence -
+    # exit 0 is the router's go-ahead, and a file nothing examined has to say so.
+    # ponytail: widening past Python means a real second parser (bun/node) and its
+    # version, not another entry on a suffix list.
+    changed, unparsed = [], []
+    for path, dest in written:
+        body, current = open(dest, encoding="utf-8").read(), open(path, encoding="utf-8").read()
+        vouchable = path.endswith(".py") or bool(PY_SHEBANG.match(body))
+        if vouchable:
+            try:
+                ast.parse(body, filename=dest)
+            except SyntaxError as exc:
+                raise Insufficient(f"{path}: the draft is not valid Python ({exc})") from exc
+        if body == current:
+            continue
+        changed.append((path, dest))
+        if not vouchable:
+            unparsed.append(path)
+    if not changed:
+        raise Insufficient("every draft is identical to the file it replaces")
+
+    for path in unparsed:
+        print(f"codegen: NOTE {path} was not parsed (no checker for this type)",
+              file=sys.stderr)
+    for path, dest in changed:
+        subprocess.run(["diff", "-u", path, dest], check=False)
+    written = changed
+    print(f"\ncodegen: {provider}/{model} | {len(written)} file(s) | "
+          f"in={usage.get('prompt_tokens')} out={usage.get('completion_tokens')} | "
+          f"drafts in {scratch}")
+    print("codegen: NOTHING was applied. Review the diff, then copy the drafts in.")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except KeyboardInterrupt:
+        # Ctrl-C while a stalled request is in flight: main() unwinds, but the
+        # request thread is non-daemon and interpreter shutdown joins it, so the
+        # process would hang until the response ends. Leave immediately instead.
+        print("codegen: interrupted", file=sys.stderr)
+        sys.stdout.flush()
+        sys.stderr.flush()
+        os._exit(130)
+    except Insufficient as exc:
+        # Exit 2 is the whole point: the caller falls back to the main model rather
+        # than applying something this script could not vouch for.
+        print(f"codegen: INSUFFICIENT -- {exc}\n"
+              f"codegen: fall back to the main model and write this one yourself.",
+              file=sys.stderr)
+        sys.stdout.flush()
+        sys.stderr.flush()
+        # A request thread that outlived --timeout is still alive, and sys.exit
+        # waits for it at interpreter shutdown; the message above is already out.
+        os._exit(2)