@r1z4x/tezgah 1.3.0 → 1.5.0

package/hooks/tezgah_lessons.py

@@ -7,16 +7,16 @@ The session block, the per-turn block and the per-turn digest
 ledger here, so they agree on what a lesson is and on its key. A module of its
 own because the gate must not import `tezgah_context` (its import cost, and the
 rule `hooks/tezgah_task.py::repo_root` states): this one imports only
-`tezgah_paths` at load, and `tezgah_gate` lazily, only for a line that names a
-gate rule as its enforcer.
+`tezgah_paths` and `tezgah_store` at load, and `tezgah_gate` lazily, only for a
+line that names a gate rule as its enforcer.
 
 Stdlib only."""
 import hashlib
-import json
 import os
 import re
 
-from tezgah_paths import cache_dir, off
+import tezgah_store
+from tezgah_paths import off
 
 # A line carries its metadata after its text, never in it: from the first
 # `|| check:` or `|| enforced_by:` clause outside a code span to the end of the
@@ -114,73 +114,28 @@ def is_ledger(path):
             and os.path.basename(os.path.dirname(path)) == ".tezgah")
 
 
-def taint_path(root):
-    """The `lesson_tainted` index of the repository at `root`: the gate keeps
-    each keyed row here as well as in the session's ledger, so the context of a
-    later session reads one small file for the per-line label instead of every
-    ledger on the machine (3173 files, 30 MB on the measuring machine,
-    2026-10-07)."""
-    name = hashlib.sha1(os.path.realpath(root).encode("utf-8", "replace"))
-    return os.path.join(cache_dir(), "lessons", name.hexdigest()[:16] + ".jsonl")
-
-
-def _index_rows(path):
-    """The parseable keyed rows of an index file, oldest first; [] without one.
-    A damaged line costs only itself."""
-    rows = []
-    try:
-        with open(path, encoding="utf-8", errors="replace") as fh:
-            for ln in fh:
-                try:
-                    row = json.loads(ln)
-                except ValueError:
-                    continue
-                if isinstance(row, dict) and row.get("key"):
-                    rows.append(row)
-    except OSError:
-        pass
-    return rows
+def taint_root(root):
+    """The key of the repository at `root` in the `lesson_taint` store: the gate
+    keeps each keyed row there as well as in the session's ledger, so the
+    context of a later session reads one repository's rows for the per-line
+    label instead of every ledger on the machine (3173 files, 30 MB on the
+    measuring machine, 2026-10-07)."""
+    return hashlib.sha1(os.path.realpath(root).encode("utf-8", "replace")).hexdigest()[:16]
 
 
 def write_taint(root, keep, rows):
     """Rewrite the index of the repository at `root`: the rows it holds whose key
-    is in `keep` (the ledger's lines plus the write's new ones), then `rows`. So
-    the file never outgrows the ledger it labels. Best effort, like a ledger row.
-    ponytail: two sessions rewriting one index in the same instant can lose one
-    row (one label); the session ledger keeps its own copy of every row."""
-    path = taint_path(root)
-    kept = [r for r in _index_rows(path) if r["key"] in keep] + rows
-    tmp = "%s.%d.tmp" % (path, os.getpid())
-    try:
-        os.makedirs(os.path.dirname(path), mode=0o700, exist_ok=True)
-        fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
-        with os.fdopen(fd, "w", encoding="utf-8") as fh:
-            fh.write("".join(json.dumps(r) + "\n" for r in kept))
-        os.replace(tmp, path)
-    except OSError:
-        pass
-
-
-# The index as last read, per (path, mtime, size): the session block, the
-# per-turn block and the digest of one prompt each ask for it, and a hook
-# process serves one prompt.
-_TAINTED = {}
+    is in `keep` (the ledger's lines plus the write's new ones), then `rows`, in
+    one transaction. So the index never outgrows the ledger it labels. Best
+    effort, like a ledger row."""
+    tezgah_store.write_taint(taint_root(root), keep, rows)
 
 
 def tainted(root):
     """{key: source} for the lessons of the repository at `root` that a gate
-    recorded as written in a turn that had read untrusted text (`taint_path`);
-    {} when there is none. Read once while the file is unchanged."""
-    path = taint_path(root)
-    try:
-        st = os.stat(path)
-    except OSError:
-        return {}
-    key = (path, st.st_mtime_ns, st.st_size)
-    if key not in _TAINTED:
-        _TAINTED[key] = {str(r["key"]): str(r.get("source") or "")
-                         for r in _index_rows(path)}
-    return _TAINTED[key]
+    recorded as written in a turn that had read untrusted text (`taint_root`);
+    {} when there is none."""
+    return tezgah_store.taint(taint_root(root))
 
 
 def lines(root, retired=None):

package/hooks/tezgah_paths.py

@@ -499,32 +499,129 @@ def have_typesafe_key():
 def have_judge_key():
     """True when tezgah's own judgement seam can ask anyone: the session's own
     CLI (`session_cli()`), else - when the `fallback` setting lets a third party
-    answer - the TypeSafe env var or key file, then the OpenRouter fallback's own
-    two channels (`OPENROUTER_API_KEY`, `~/.config/openrouter/key`), which are
-    the channels `hooks/tezgah_judge.py`'s `providers()` picks between. This is
-    what `bin/tezgah-triage`, `bin/tezgah-docs` and the skill picker spend. Never
-    omp's login store: the seam does not open it.
+    answer - a chosen Jev carrier's credential (`jev_carriers()`) or the
+    OpenRouter chat fallback's own two channels (`OPENROUTER_API_KEY`,
+    `~/.config/openrouter/key`), which are the channels `hooks/tezgah_judge.py`'s
+    `providers()` picks between. This is what `bin/tezgah-triage`,
+    `bin/tezgah-docs` and the skill picker spend.
 
     Kept next to `have_typesafe_key()` because the two are asked together and a
     report that showed one answer under both questions was wrong in both
-    directions - a key file alone (seam works, omp does not) and a login-store
-    record alone (omp works, seam does not). A blank file is not a credential
-    here either, so this stays in step with the seam's own `strip() or None`."""
+    directions - a key file alone serves the seam and not omp. A blank file is
+    not a credential here either, so this stays in step with the seam's own
+    `strip() or None`."""
     if session_cli():
         return True
     if fallback_policy() == "none":
         return False
-    for env, home in (("TYPESAFE_API_KEY", ".config/typesafe/key"),
-                      ("OPENROUTER_API_KEY", ".config/openrouter/key")):
-        if os.environ.get(env, "").strip():
-            return True
+    return bool(openrouter_key() or any(s for _, s in jev_carriers()))
+
+
+def key_from(envs, path):
+    """The first non-blank env var of `envs`, else the file at `path` (`~`
+    expanded), else None - stripped either way, because a newline inside an
+    Authorization header is an injection, not a typo. The file is the channel a
+    hook needs: it runs where `~/.zshenv` never exported the variable."""
+    for env in envs:
+        value = os.environ.get(env, "").strip()
+        if value:
+            return value
+    try:
+        with open(os.path.expanduser(path), encoding="utf-8") as fh:
+            return fh.read().strip() or None
+    except OSError:
+        return None
+
+
+def omp_login_key(provider):
+    """The API key omp's login store holds for `provider` (`omp auth login`),
+    stripped, else None: the newest enabled `api_key` row's `data.key`, read
+    read-only. Any error - no store, another schema, a locked file - is None."""
+    import sqlite3  # deferred: see have_typesafe_key()
+    store = os.path.join(os.path.expanduser("~"), ".omp", "agent", "agent.db")
+    try:
+        conn = sqlite3.connect("file:%s?mode=ro" % store, uri=True)
         try:
-            with open(os.path.join(HOME, home), encoding="utf-8") as fh:
-                if fh.read().strip():
-                    return True
-        except OSError:
-            pass
-    return False
+            rows = conn.execute(
+                "select data from auth_credentials where provider = ? and "
+                "disabled_cause is null order by id desc", (provider,)).fetchall()
+        finally:
+            conn.close()
+    except (sqlite3.Error, OSError):
+        return None
+    for (data,) in rows:
+        try:
+            value = json.loads(data).get("key")
+        except (TypeError, ValueError, AttributeError):
+            continue
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None
+
+
+def typesafe_key():
+    """TypeSafe's credential: TYPESAFE_API_KEY, else `~/.config/typesafe/key`,
+    else the active omp login (`omp_login_key("typesafe")`), else None."""
+    return (key_from(("TYPESAFE_API_KEY",), "~/.config/typesafe/key")
+            or omp_login_key("typesafe"))
+
+
+def openrouter_key():
+    """OpenRouter's credential: OPENROUTER_API_KEY, else its key file."""
+    return key_from(("OPENROUTER_API_KEY",), "~/.config/openrouter/key")
+
+
+def cloudflare_account():
+    """The Workers AI account id: CLOUDFLARE_ACCOUNT_ID, else its file."""
+    return key_from(("CLOUDFLARE_ACCOUNT_ID",), "~/.config/cloudflare/account_id")
+
+
+def cloudflare_token():
+    """The Workers AI token: JEV_CLOUDFLARE_API_TOKEN, else CLOUDFLARE_API_TOKEN,
+    else `~/.config/cloudflare/token`."""
+    return key_from(("JEV_CLOUDFLARE_API_TOKEN", "CLOUDFLARE_API_TOKEN"),
+                    "~/.config/cloudflare/token")
+
+
+# The Jev carrier a user may choose (`jev_choice()`), and the order `auto`
+# tries them in: TypeSafe direct, OpenRouter's System One endpoint, Cloudflare
+# Workers AI, any System One-compatible URL (JEV_API_BASE_URL + JEV_API_KEY,
+# the names the public jev-mcp server reads), then Cloudflare's own System One
+# models Clef and Clef-flash on Workers AI (the same Cloudflare credential).
+JEV_CHOICES = ("auto", "typesafe", "openrouter", "cloudflare", "compatible",
+               "clef", "clef-flash")
+
+
+def jev_choice():
+    """TEZGAH_JEV_PROVIDER, else JEV_PROVIDER (jev-mcp's name), else config.json
+    `jev`, else `auto` - lowercased. An unknown value is kept, so it resolves to
+    no carrier instead of silently to another one."""
+    for env in ("TEZGAH_JEV_PROVIDER", "JEV_PROVIDER"):
+        value = os.environ.get(env, "").strip().lower()
+        if value:
+            return value
+    cfg = config()
+    value = cfg.get("jev") if isinstance(cfg, dict) else None
+    value = value.strip().lower() if isinstance(value, str) else ""
+    return value or "auto"
+
+
+def jev_carriers():
+    """[(carrier, secret), ...] the chosen Jev carriers in the order the seam
+    asks them. `auto`: every carrier whose credential resolves. A named one: that
+    carrier alone, its secret None when it does not resolve - the seam records
+    why rather than substituting another carrier."""
+    compatible = (os.environ.get("JEV_API_KEY", "").strip() or None
+                  if os.environ.get("JEV_API_BASE_URL", "").strip() else None)
+    workers_ai = cloudflare_token() if cloudflare_account() else None
+    found = [("typesafe", typesafe_key()), ("jev-openrouter", openrouter_key()),
+             ("jev-cloudflare", workers_ai), ("jev-compatible", compatible),
+             ("clef", workers_ai), ("clef-flash", workers_ai)]
+    choice = jev_choice()
+    if choice == "auto":
+        return [(name, secret) for name, secret in found if secret]
+    name = choice if choice in ("typesafe", "clef", "clef-flash") else "jev-" + choice
+    return [(name, dict(found).get(name))]
 
 
 # How far a model call may leave the session's own vendor (config.json
@@ -544,16 +641,39 @@ def fallback_policy():
     return value if value in FALLBACKS else "vendor"
 
 
+# The session CLIs the judgement seam can ask, in detection order, each with
+# the env vars its host sets in the processes it spawns. omp sets CLAUDECODE
+# too, so it comes first. opencode sets OPENCODE=1 in its own process at start
+# (`process.env.OPENCODE="1"` in the 1.18.31 binary), so its plugin's children
+# and its shell tool inherit it. cursor-agent gives its shell tool CURSOR_AGENT=1
+# and its hooks CURSOR_VERSION (`buildHookEnvironment` in the 2026.10.01
+# bundle). codex gives its shell tool CODEX_THREAD_ID (codex-rs
+# protocol/src/shell_environment.rs `populate_env`); its hooks get only codex's
+# own process env (codex-rs hooks/src/registry.rs), so a codex hook names no
+# session - `judge_cli` picks it there.
+SESSION_CLIS = (("omp", ("OMPCODE",)), ("claude", ("CLAUDECODE",)),
+                ("opencode", ("OPENCODE",)), ("cursor", ("CURSOR_AGENT", "CURSOR_VERSION")),
+                ("codex", ("CODEX_THREAD_ID",)))
+
+
 def session_cli():
-    """`omp` or `claude` - the CLI of the host this process runs under, when it
-    is installed - else None. omp sets CLAUDECODE too, so OMPCODE is read first,
-    and an omp session whose binary is missing is None rather than Claude: the
-    session's credential is omp's, not whatever `claude` is logged in as."""
-    if os.environ.get("OMPCODE"):
-        return "omp" if omp_bin() else None
-    if os.environ.get("CLAUDECODE"):
-        return "claude" if claude_bin() else None
-    return None
+    """The session CLI the judgement seam asks - `omp`, `claude`, `opencode`,
+    `cursor` or `codex` - else None.
+
+    TEZGAH_JUDGE_CLI, else config.json `judge_cli`, picks one by name; `auto`
+    (the default, and any other value) reads the host this process runs under:
+    the first CLI in SESSION_CLIS whose marker is set. Either way the answer is
+    None when that CLI's binary is missing - an omp session is not handed to
+    whatever `claude` is logged in as, and a picked CLI has no stand-in."""
+    bins = {"omp": omp_bin, "claude": claude_bin, "opencode": opencode_bin,
+            "cursor": cursor_bin, "codex": codex_bin}
+    cfg = config()
+    pick = (os.environ.get("TEZGAH_JUDGE_CLI", "").strip()
+            or (cfg.get("judge_cli") if isinstance(cfg, dict) else None))
+    if not isinstance(pick, str) or pick not in bins:
+        pick = next((name for name, markers in SESSION_CLIS
+                     if any(os.environ.get(m) for m in markers)), None)
+    return pick if pick and bins[pick]() else None
 
 
 def orx_bin():
@@ -584,6 +704,24 @@ def claude_bin():
     return which_user(os.environ.get("TEZGAH_CLAUDE_BIN") or "claude")
 
 
+def opencode_bin():
+    """The opencode CLI (TEZGAH_OPENCODE_BIN, else `opencode`), or None - the
+    lookup `omp_bin()` makes."""
+    return which_user(os.environ.get("TEZGAH_OPENCODE_BIN") or "opencode")
+
+
+def cursor_bin():
+    """Cursor's agent CLI (TEZGAH_CURSOR_BIN, else `cursor-agent`), or None -
+    the lookup `omp_bin()` makes."""
+    return which_user(os.environ.get("TEZGAH_CURSOR_BIN") or "cursor-agent")
+
+
+def codex_bin():
+    """The Codex CLI (TEZGAH_CODEX_BIN, else `codex`), or None - the lookup
+    `omp_bin()` makes."""
+    return which_user(os.environ.get("TEZGAH_CODEX_BIN") or "codex")
+
+
 # The values `reply_lang` (config.json) takes. The value itself is the switch:
 # `tr` (the default, and what an install without the key reads) asks for Turkish
 # replies, `en` for English ones, and `any` drops the Stop language check.
@@ -612,50 +750,40 @@ def reply_lang():
 # `authorized` row, the stand-down text) - the control rule refuses the routes
 # the gate sees, and an interpreter writing them is SECURITY.md's residual.
 STAND_DOWN = "tezgah-setup --uninstall --full\n"
-_LATCH = {"ledger": None, "since": None, "auth": None}
+_LATCH = {"ledger": None, "since": None}
 
 
 def latch(ledger):
     """Bind this process's `off()` to one session's ledger path (None unbinds)."""
-    _LATCH.update(ledger=ledger, since=None, auth=None)
+    _LATCH.update(ledger=ledger, since=None)
 
 
 def _first_ts(ledger):
+    import tezgah_store  # deferred: an unbound process never opens the ledger
     try:
-        with open(ledger, "rb") as fh:
-            ts = json.loads(fh.readline()).get("ts")
-    except (OSError, ValueError, AttributeError):
+        ts = json.loads(tezgah_store.evidence_first(ledger) or "null").get("ts")
+    except (*tezgah_store.ERRORS, ValueError, AttributeError):
         return None
     return ts if isinstance(ts, (int, float)) else None
 
 
 def _authorized(ledger):
-    """The switch names this session's `authorized` rows carry, memoized on
-    the ledger's size: read only when a switch is newer than the first row."""
-    try:
-        size = os.path.getsize(ledger)
-    except OSError:
-        return frozenset()
-    memo = _LATCH["auth"]
-    if memo and memo[0] == size:
-        return memo[1]
+    """The switch names this session's `authorized` rows carry: read only when
+    a switch is newer than the first row."""
+    import tezgah_store
     names = set()
     try:
-        with open(ledger, encoding="utf-8", errors="replace") as fh:
-            for line in fh:
-                if '"authorized"' not in line:
-                    continue
-                try:
-                    row = json.loads(line)
-                except ValueError:
-                    continue
-                if row.get("kind") == "authorized" and isinstance(
-                        row.get("authorized"), list):
-                    names.update(n for n in row["authorized"] if isinstance(n, str))
-    except OSError:
+        found = tezgah_store.evidence_rows(ledger, kind="authorized")
+    except tezgah_store.ERRORS:
         return frozenset()
-    _LATCH["auth"] = (size, frozenset(names))
-    return _LATCH["auth"][1]
+    for text in found:
+        try:
+            row = json.loads(text)
+        except ValueError:
+            continue
+        if isinstance(row, dict) and isinstance(row.get("authorized"), list):
+            names.update(n for n in row["authorized"] if isinstance(n, str))
+    return frozenset(names)
 
 
 def _honored(path, name):

package/hooks/tezgah_policy.py

@@ -237,7 +237,15 @@ rewrite it plainly.
 on a merge. Review first with a FRESH reviewer (never my own read of my own
 code), run the full suite, and if the review is clean and every test passes,
 merge, move the plan to `.tezgah/plans/done/`, and report the outcome. Bring it back
-to the user only on a critical or high-severity finding, or a failing test.
+to the user only on a critical or major finding left after round two, or a
+failing test. One review per plan, over its whole diff in the verification
+phase; at most two rounds - only a confirmed critical or major finding opens
+round two, a minor or suggestion one is recorded fix-later, and after round two
+what is left goes to the user or is recorded fix-later, never a third round.
+A round spawns its reviewers in ONE message, one per dimension (correctness
+and contract, security, tests and performance) or file group; a diff under 300
+changed lines gets one reviewer. Per-task work gets tests, not a reviewer, and
+`tezgah-task review` refuses a third round.
 
 **Attribution: none, anywhere, ever.** Nothing you persist or publish may name
 the assistant, model, vendor or "AI" as author, co-author, generator or helper -
@@ -283,9 +291,11 @@ independent work remains. Fan out only when
 the subtasks share no mutable file and no interface: if two of them would edit
 the same file, or one's answer decides the other's, keep them in one context or
 sequence them. The shared artifact is the coordination channel, not chatter -
-naming a lead coordinates nothing by itself. If the work
-cannot be split - one file, one bounded change, a strictly serial chain - do it
-directly. Never spawn a subagent whose briefing is bigger than the work.
+naming a lead coordinates nothing by itself. Only a single item - one file, one
+bounded change, a strictly serial chain - is done directly; a list of
+independent items is never worked one by one on the main thread, however small
+each item is, and that holds at every phase: a plan's tasks, its acceptance
+commands and the sources of a survey fan out the same way.
 A slice that needs its own checkout: inside Orca (the session-start `Orca:`
 line) create it with `orca worktree create --name <slug> --parent-worktree
 active --json` and track it with `orca worktree ps --json` or `tezgah-status
@@ -330,7 +340,8 @@ guards against.
 
 ### The gate, for anything either tier produces
 Read the diff yourself. Then tests, lint and type check must pass, and anything
-non-trivial gets an independent review before it lands. A delegate's output is
+non-trivial gets an independent review before it lands - once per plan, not
+per task or commit. A delegate's output is
 a draft until the router has evidence; "the agent said it works" is not
 evidence.
 
@@ -897,8 +908,14 @@ project root and never `git add -f` anything under `.tezgah/`. Off:
 **Parallel by default: fan out independent items.** A request with two or
 more independent items - a numbered or bulleted list, several files or areas, a
 todo list whose entries share no file and no interface - is delegated without
-being asked: one subagent per item, all spawned in ONE message, while the main
-thread decomposes, integrates, verifies and reports. Every writing slice gets
+being asked: count the independent items, spawn one subagent per item in ONE
+message, and keep the main thread for decomposing, integrating, verifying and
+reporting. It holds at every phase, not only the first message: a plan's tasks,
+its acceptance commands and the sources of a survey are items too, and checks
+that share no state are tool calls in one message, never a queue (one suite run
+at a time: two runs of one suite storm the CPU and race on its temp state).
+No item is too small to delegate while another runs beside it; only a single
+item is done inline. Every writing slice gets
 its own branch and checkout - inside Orca `orca worktree create --name <slug>
 --parent-worktree active --json`, else `git worktree add -b <branch> <absolute
 path>`; its brief names every read, edit and shell `cwd` as an absolute path
@@ -907,7 +924,8 @@ not grow. Read-only slices need no worktree. Pick each agent by task class from
 the specialists line; `{ROUTE_BIN}` names the tier for code work. Serialize
 only a real dependency - one slice's output is another's input, or two slices
 edit one file - and say which. Never wait idle on a spawned slice while
-independent work remains. Off: `orchestrate-off`.
+independent work remains. A subagent does its own slice and never fans out
+again. Off: `orchestrate-off`.
 
 **Kill switches:** each one removes its own rule from this text, not just the
 status mark. `~/.config/tezgah/`: `exec-mode.off`, `orchestrate-off`,
@@ -928,6 +946,15 @@ The ponytail intensity level is not a switch: `tezgah-pony lite|full|ultra`.
 # CORE_RULES labels in hooks/tezgah_context.py.
 CONDITIONAL_KEYS = ("spec", "consult", "research", "product", "graph", "fanout")
 
+# The fan-out rule's action, which the one-line repeat of an armed paragraph
+# (hooks/tezgah_context.armed_again) carries: a bare "Armed again" named a rule
+# the session had to recall, and the second list of a session was worked one
+# item at a time. It is the paragraph's own clause, cut to one sentence.
+FANOUT_ACTION = ("count the independent items, spawn one subagent per item in "
+                 "ONE message (each writing slice in its own worktree, absolute "
+                 "paths), and keep the main thread for integrating and verifying;"
+                 " a subagent does its own slice and never fans out again.")
+
 # The always-on replacement for the conditional paragraphs: one line each so a
 # host without a per-turn hook still knows the rule exists and where the full
 # text lives.