@r1z4x/tezgah 1.0.0 → 1.1.0

package/hooks/tezgah_judge.py

@@ -29,15 +29,19 @@ non-interactive shell where `.zshenv` never runs - the export is absent there,
 and the key file is the channel that survives. That is why the file is read
 rather than the environment trusted.
 
-Behind the credential there are two providers. TypeSafe answers in its own
-schema; when no TypeSafe key resolves, the same questions go to an
-OpenAI-compatible chat endpoint - OpenRouter, whose key rides the same two
-channels (`OPENROUTER_API_KEY`, then `~/.config/openrouter/key`) - and its JSON
-reply is mapped back into the shapes the callers already read. That path is a
-fallback, never a peer: it is chosen only when `key()` is empty, it sends the
-same state to a different host, and a reply that does not carry a question's
-answer leaves that question absent, which every caller already reads as no
-judgement.
+Behind the credential there are three providers, asked in this order. First the
+session's own CLI - `omp` or `claude`, the host this process runs under
+(`tp.session_cli()`) - run headless with no tools, so the judgement is paid
+with the session's own credential, OAuth subscription included, and answered by
+the session's own vendor. TypeSafe and OpenRouter are third parties: they are
+asked only as the `fallback` setting allows (`tp.fallback_policy()`): by
+default (`vendor`) only when there is no session CLI at all, with `any` also
+after the session CLI failed, with `none` never. A third party that answers,
+and a fallback that was refused, is never silent: one stderr line, the
+`fallback` field on the result, and the last-use record `tezgah-status
+--judge` prints (`_record`, `last_use`). A reply that does not carry a
+question's answer leaves that question absent, which every caller already reads
+as no judgement.
 
 Kill switch: `judge-off`, honoured by `available()`, so a caller can fall back to
 its own deterministic path without knowing why the judgement is gone. It is the
@@ -148,58 +152,113 @@ def fallback_model():
     return os.environ.get("TEZGAH_JUDGE_MODEL", "").strip() or cheap_default()
 
 
-def credential():
-    """`(provider, secret)` for the first channel that resolves, else `(None, None)`.
+# The session CLIs the seam can ask, as the argv between the binary and the
+# prompt: no tools, no session file, no project rules, skills, extensions, MCP
+# servers or settings, and the chat fallback's own contract as the system
+# prompt. Measured 2026-10-07 on a one-word answer: claude went from 37,038
+# prompt tokens ($0.30) to 725 ($0.007); omp from 43,735 written to cache
+# ($0.35) to about 37,500, 36,700 of them read from cache ($0.015) - omp has
+# no flag here that drops the rest.
+SESSION_ARGV = {
+    "omp": ["-p", "--no-tools", "--no-lsp", "--no-session", "--no-rules",
+            "--no-skills", "--no-extensions", "--no-title", "--thinking", "off",
+            "--mode", "json", "--system-prompt", CHAT_SYSTEM],
+    "claude": ["-p", "--tools", "", "--no-session-persistence",
+               "--strict-mcp-config", "--disable-slash-commands",
+               "--setting-sources", "", "--output-format", "json",
+               "--system-prompt", CHAT_SYSTEM],
+}
+NO_SESSION = "no session CLI to ask (OMPCODE/CLAUDECODE unset or the CLI missing)"
+
+
+def providers():
+    """[(provider, secret), ...] in the order `ask()` tries them, or [].
+
+    The session's own CLI first (its `secret` is the binary's path); then the
+    third parties - TypeSafe, then OpenRouter - only as `tp.fallback_policy()`
+    allows: `vendor` (the default) asks them only when no session CLI exists,
+    `any` after the session CLI too, `none` never. TypeSafe still wins over
+    OpenRouter whenever both resolve."""
+    session = tp.session_cli()
+    policy = tp.fallback_policy()
+    out = [(session, getattr(tp, session + "_bin")())] if session else []
+    if policy == "none" or (session and policy == "vendor"):
+        return out
+    return out + [(name, secret) for name, secret in
+                  (("typesafe", key()), ("openrouter", openrouter_key())) if secret]
+
 
-    TypeSafe wins whenever it resolves, so adding a fallback cannot move a
-    machine that already judges with Jev. The pair is returned rather than the
-    secret alone so that `available()` and `ask()` cannot disagree about which
-    provider a call will use."""
-    secret = key()
-    if secret:
-        return "typesafe", secret
-    secret = openrouter_key()
-    return ("openrouter", secret) if secret else (None, None)
+def credential():
+    """`(provider, secret)` for the first provider `ask()` will try, else
+    `(None, None)` - so `available()` and `ask()` cannot disagree."""
+    found = providers()
+    return found[0] if found else (None, None)
 
 
 def available():
-    """True when a judgement can be asked for: a key resolves and no kill switch."""
+    """True when a judgement can be asked for: a provider resolves and no kill switch."""
     return bool(credential()[1]) and not tp.off("judge-off")
 
 
 def ask(state, questions, *, model=MODEL, timeout=30, attempts=2, deadline=None):
     """One batched call over `questions`; `{"answers", "usage", "latency_ms",
-    "model", "provider"}`.
+    "model", "provider", "fallback"}`.
 
     `questions` is the API's own map - id -> `{type, instructions, criteria}` -
     so a caller that needs a per-line or per-state pass sends every question in
     one request and pays for the state once. The reply's usage is carried back
     because a caller quotes what the judgement cost, and the model and provider
-    beside it because the fallback answers with a different one than the caller
-    named. The model is the one the reply names, else the one asked for: an alias
-    such as `jev-latest` hides a silent upgrade the reply's own field shows.
-
-    One request per call in the normal case, to whichever provider the credential
-    resolves - TypeSafe first, the chat fallback only when `key()` is empty. A
-    transient failure - a timeout, a connection error, a 5xx - gets one more
-    attempt, because a live measurement saw 2 of 50 calls lost that way while the
-    same cells answered on retry; a 4xx (a refused credential, a rejected body)
-    and a reply that parsed malformed are never retried, since the second request
-    would fail identically and only a call that already worked must not be billed
-    twice. The ceiling is one, so the worst case is one duplicated request on a
-    call that answered nothing anyway. A caller on a hook's budget passes
-    `attempts=1` and a `deadline` in seconds: urllib's `timeout` bounds one
-    socket operation, not the call, so only the deadline bounds its wall time.
-
-    A call that ends on a 401, 402 or 5xx marks the provider down for
-    `DOWN_FOR` seconds, and until then every call returns None without a
-    request (`_down`), so a dead credential is not re-paid on every prompt.
-
-    Total by design: no key, an unreadable state, a refused request, a timeout,
-    a reply that is not the documented shape - all `None`, never an exception."""
-    provider, secret = credential()
-    if not secret:
+    beside it because the provider that answers is not the caller's choice. The
+    model is the one the reply names, else the one asked for: an alias such as
+    `jev-latest` hides a silent upgrade the reply's own field shows. `model` is
+    TypeSafe's alone; the session CLI and the chat fallback ignore it.
+
+    The providers are tried in `providers()` order - the session's own CLI
+    first - and the next one is asked only when the previous failed. `fallback`
+    is None when the session answered, else why someone else did; that answer,
+    and a refusal, is recorded (`_record`) and said on stderr. A transient
+    failure - a timeout, a connection error, a 5xx - gets one more attempt on
+    the same provider, because a live measurement saw 2 of 50 calls lost that
+    way while the same cells answered on retry; a 4xx, a CLI that exited
+    non-zero and a reply that parsed malformed are never retried, since the
+    second request would fail identically and only a call that already worked
+    must not be billed twice. A caller on a hook's budget passes `attempts=1`
+    and a `deadline` in seconds: urllib's `timeout` bounds one socket operation,
+    not the call, so only the deadline bounds its wall time.
+
+    A call that ends on a 401, 402, 5xx or a session CLI's non-zero exit marks
+    that provider down for `DOWN_FOR` seconds, and until then it is skipped
+    without a request (`_down`), so a dead credential is not re-paid on every
+    prompt.
+
+    Total by design: no provider, an unreadable state, a refused request, a
+    timeout, a reply that is not the documented shape - all `None`, never an
+    exception."""
+    if not credential()[1]:
         return None
+    stop = None if deadline is None else time.monotonic() + deadline
+    failed = []
+    for provider, secret in providers():
+        result, why = _ask_one(provider, secret, state, questions, model,
+                               timeout, attempts, stop)
+        if result is None:
+            failed.append("%s: %s" % (provider, why))
+            continue
+        note = "; ".join(failed) or (None if provider in SESSION_ARGV else NO_SESSION)
+        result["fallback"] = note
+        _record(result["provider"], result["model"], fallback=note)
+        return result
+    refused = None
+    session = tp.session_cli()
+    if session and (key() or openrouter_key()):
+        refused = ("fallback=%s refuses a third-party judge after %s failed"
+                   % (tp.fallback_policy(), session))
+    _record(None, None, failed="; ".join(failed), refused=refused)
+    return None
+
+
+def _ask_one(provider, secret, state, questions, model, timeout, attempts, stop):
+    """One provider's attempts: `(result, None)`, or `(None, why)`."""
     try:
         if provider == "typesafe":
             used, url = model, endpoint()
@@ -208,34 +267,43 @@ def ask(state, questions, *, model=MODEL, timeout=30, attempts=2, deadline=None)
 
             def send():
                 return _request(secret, body, timeout)
-        else:
+        elif provider == "openrouter":
             used, url = fallback_model(), openrouter_url()
             body = json.dumps(_chat_body(state, questions, used)).encode()
 
             def send():
                 return _chat_request(secret, body, timeout, questions)
+        else:
+            used, url = None, secret
+            prompt = json.dumps({"state": state, "questions": questions})
+
+            def send():
+                left = timeout if stop is None else max(0.1, min(timeout, stop - time.monotonic()))
+                return _session_request(provider, secret, prompt, left, questions)
         marker = _down_marker(provider, url, secret)
         if _down(marker):
-            return None
-    except Exception:
-        return None
-    stop = None if deadline is None else time.monotonic() + deadline
+            return None, "marked down for %ds after a refusal" % DOWN_FOR
+    except Exception as exc:
+        return None, _why(exc)
     for attempt in range(attempts):
+        if stop is not None and time.monotonic() >= stop:
+            return None, "deadline passed"
         try:
             result = _bounded(send, stop)
         except Exception as exc:
             late = stop is not None and time.monotonic() >= stop
             if attempt + 1 >= attempts or late or not _transient(exc):
                 code = getattr(exc, "code", None)
-                if code in (401, 402) or (isinstance(code, int) and code >= 500):
+                if code in (401, 402) or (isinstance(code, int) and code >= 500) \
+                        or isinstance(exc, SessionFailed):
                     _mark_down(marker)
-                return None
+                return None, _why(exc)
             continue
         named = result.get("model")
-        result["model"] = named if isinstance(named, str) and named else used
+        result["model"] = named if isinstance(named, str) and named else used or "-"
         result["provider"] = provider
-        return result
-    return None
+        return result, None
+    return None, "no attempt"
 
 
 def _answer(result, id):
@@ -485,3 +553,118 @@ def _bounded(send, stop):
     if "err" in box:
         raise box["err"]
     return box["ok"]
+
+
+class SessionFailed(RuntimeError):
+    """The session CLI exited non-zero or printed no answer: a logged-out CLI or
+    an exhausted plan fails the same way on the next call, so it is never
+    retried and it marks the provider down like a 401."""
+
+
+def _session_request(name, exe, prompt, timeout, questions):
+    """One headless run of the session's own CLI, mapped into the documented
+    return. It starts in an empty temp dir with stdin closed - the answer rests
+    on the prompt alone, and a CLI that wants a login exits instead of waiting -
+    with TEZGAH_NESTED set so tezgah's own hooks stand down in the child. The
+    answer is read from the CLI's JSON output: the model and the usage it names
+    are what the call really used."""
+    import shutil
+    import subprocess
+    import tempfile
+    cwd = tempfile.mkdtemp(prefix="tezgah-judge-")
+    started = time.monotonic()
+    try:
+        proc = subprocess.run([exe] + SESSION_ARGV[name] + [prompt], cwd=cwd,
+                              stdin=subprocess.DEVNULL, capture_output=True,
+                              text=True, timeout=timeout,
+                              env=dict(os.environ, TEZGAH_NESTED="1"))
+    finally:
+        shutil.rmtree(cwd, ignore_errors=True)
+    if proc.returncode:
+        raise SessionFailed("%s exit %d: %s" % (name, proc.returncode,
+                                                 (proc.stderr or proc.stdout).strip()[-200:]))
+    if name == "claude":
+        data = json.loads(proc.stdout)
+        if data.get("is_error"):
+            raise SessionFailed("claude: %s" % str(data.get("result"))[:200])
+        text = data.get("result") or ""
+        model = next(iter(data.get("modelUsage") or {}), None)
+        usage = data.get("usage") or {}
+        tokens_in = sum(int(usage.get(k) or 0) for k in (
+            "input_tokens", "cache_creation_input_tokens", "cache_read_input_tokens"))
+        tokens_out = int(usage.get("output_tokens") or 0)
+    else:
+        message = None
+        for line in proc.stdout.splitlines():
+            try:
+                event = json.loads(line)
+            except ValueError:
+                continue
+            if isinstance(event, dict) and event.get("type") == "message_end" \
+                    and (event.get("message") or {}).get("role") == "assistant":
+                message = event["message"]
+        if message is None:
+            raise SessionFailed("omp printed no answer")
+        text = "".join(part.get("text") or "" for part in message.get("content") or []
+                       if isinstance(part, dict) and part.get("type") == "text")
+        model = "/".join(str(message[k]) for k in ("provider", "model") if message.get(k))
+        usage = message.get("usage") or {}
+        tokens_in = sum(int(usage.get(k) or 0) for k in ("input", "cacheRead", "cacheWrite"))
+        tokens_out = int(usage.get("output") or 0)
+    # A chat model may fence its object; the outermost braces are the object.
+    answers = _chat_answers(json.loads(text[text.find("{"):text.rfind("}") + 1]), questions)
+    return {"answers": answers,
+            "usage": {"input_tokens": tokens_in, "output_tokens": tokens_out},
+            "latency_ms": int((time.monotonic() - started) * 1000),
+            "model": model}
+
+
+def _why(exc):
+    """A failure as one short reason: the HTTP code, else the exception's text."""
+    code = getattr(exc, "code", None)
+    if isinstance(code, int):
+        return "http %d" % code
+    return ("%s: %s" % (type(exc).__name__, exc))[:200]
+
+
+# The last judgement's record, one file: what answered, and why it was not the
+# session's own CLI when it was not. `tezgah-status --judge` prints it.
+LAST = "judge-last.json"
+
+
+def _say(line):
+    try:
+        import sys
+        sys.stderr.write("tezgah-judge: %s\n" % line)
+    except Exception:
+        pass
+
+
+def _record(provider, model, fallback=None, failed=None, refused=None):
+    """Write the last-use record and say any fallback or refusal on stderr.
+    Best effort like every hook write: a cache that cannot be written loses
+    the record, never the answer."""
+    if fallback and provider:
+        _say("answered by %s/%s - %s" % (provider, model, fallback))
+    elif refused:
+        _say("no judgement: %s (%s)" % (refused, failed))
+    row = {"at": time.strftime("%Y-%m-%dT%H:%M:%S%z"), "provider": provider,
+           "model": model, "fallback": fallback, "failed": failed or None,
+           "refused": refused, "policy": tp.fallback_policy()}
+    try:
+        path = os.path.join(tp.cache_dir(), LAST)
+        with open(path + ".tmp", "w", encoding="utf-8") as fh:
+            json.dump(row, fh)
+        os.replace(path + ".tmp", path)
+    except (OSError, TypeError, ValueError):
+        pass
+
+
+def last_use():
+    """The last judgement's record (see `_record`), or None when none was kept."""
+    try:
+        with open(os.path.join(tp.cache_dir(), LAST), encoding="utf-8") as fh:
+            row = json.load(fh)
+    except (OSError, ValueError):
+        return None
+    return row if isinstance(row, dict) else None

package/hooks/tezgah_models.py

@@ -105,7 +105,10 @@ SLOTS = {
                  "any": ("anthropic/claude-opus-5.5", "high")},
 }
 AGENT_SLOT = {"tezgah-cheap": "cheap", "tezgah-standard": "standard",
-              "tezgah-frontier": "frontier", "tezgah-reviewer": "frontier"}
+              "tezgah-frontier": "frontier", "tezgah-reviewer": "frontier",
+              "tezgah-tester": "cheap", "tezgah-docs": "standard",
+              "tezgah-security": "frontier", "tezgah-ui": "standard",
+              "tezgah-researcher": "frontier"}
 # The OpenRouter id of every model the table names, with its list price per 1M
 # tokens (input, output) on READ_ON, so `refresh` can say what moved.
 SNAPSHOT = {"anthropic/claude-opus-5.5": (4.0, 20.0),
@@ -280,17 +283,50 @@ def _selector(family, slot):
     return FAMILY_PREFIX[family] + model + (":" + effort if effort else "")
 
 
+# The OpenRouter id of a host-column model: the route the default `vendor`
+# fallback keeps - the same model through another provider and account - when
+# the `any` column names another vendor's model on that slot.
+OPENROUTER_ID = {"claude-opus-5-5": "anthropic/claude-opus-5.5",
+                 "zai/glm-5.3-flash": "z-ai/glm-5.3-flash"}
+VENDOR_STEMS = (("claude", "anthropic"), ("glm", "zai"), ("gpt", "openai"),
+                ("deepseek", "deepseek"))
+
+
+def _vendor(model):
+    """The vendor a table id's model comes from, or the id itself."""
+    name = model.split("/")[-1].lower()
+    return next((v for stem, v in VENDOR_STEMS if name.startswith(stem)), name)
+
+
 def _chain(mode, slot, funded, agent=""):
     """[selector, ...] for one slot: the mode's family first - the user picked it,
-    so it leads even when its credential is not visible from here - then every
-    other funded family, each on that slot's own row.
-
-    The fallbacks are rotated by the agent's own name (`agent`): identical chains
+    so it leads even when its credential is not visible from here - then the
+    fallbacks the `fallback` setting allows (`tp.fallback_policy()`).
+
+    `vendor`, the default: only the mode's own model vendor - the same model
+    through OpenRouter, or another funded column whose model is that vendor's -
+    because a session on Opus that ran its subagents on GPT and GLM after one
+    Anthropic 429 is the failure the owner reported (2026-10-07). `none`: the
+    mode's selector alone. `any`: every other funded family, each on that
+    slot's own row, rotated by the agent's own name (`agent`): identical chains
     for every agent meant one family's 429 moved all of them onto the same next
     family in the same moment, which is the cascade the chain exists to break
     (independent review, 2026-10-01). The rotation is deterministic - the same
     agent resolves the same order on every machine - so nothing here is random."""
+    policy = tp.fallback_policy()
     families = [mode] + [f for f in OMP_FAMILIES if f != mode and f in funded]
+    if policy == "none":
+        return [_selector(mode, slot)]
+    if policy == "vendor":
+        model, effort = SLOTS[slot][mode]
+        out = [_selector(mode, slot)]
+        for family in families[1:]:
+            if _vendor(SLOTS[slot][family][0]) == _vendor(model):
+                out.append(_selector(family, slot))
+            elif family == "any" and model in OPENROUTER_ID:
+                out.append("openrouter/" + OPENROUTER_ID[model]
+                           + (":" + effort if effort else ""))
+        return list(dict.fromkeys(out))
     tail = families[1:]
     if agent and len(tail) > 1:
         shift = sum(ord(c) for c in agent) % len(tail)

package/hooks/tezgah_orca.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""Orca: is this session inside it, which CLI drives it, and what it tracks.
+
+Orca (an IDE for agent sessions) owns worktrees, terminals, its embedded browser
+and artifacts, and it exports its own markers into every terminal it starts.
+tezgah reads those markers - never writes them - so a session in Orca is told to
+create a checkout with `orca worktree create` rather than a raw `git worktree
+add` Orca does not list, and `tezgah-status --orca` shows which of a repo's
+checkouts Orca tracks. Stdlib only; detection forks nothing, so the session-start
+line costs no process. docs/orca.md is the page.
+"""
+import json
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+
+# The markers an Orca terminal exports (observed in Orca 1.4.221's env). Any one
+# is enough; TERM_PROGRAM=Orca covers a shell that dropped the ORCA_* set.
+MARKERS = ("ORCA_WORKTREE_ID", "ORCA_TERMINAL_HANDLE", "ORCA_PANE_KEY")
+MAC_APP_CLI = "/Applications/Orca.app/Contents/Resources/bin/orca"
+# The file Orca leaves in each per-account codex home it hands out as CODEX_HOME.
+MANAGED_HOME = ".orca-managed-home"
+
+
+def session(env=None):
+    """{worktree, terminal, version} when this process runs in an Orca terminal,
+    else None. `worktree` is the path half of ORCA_WORKTREE_ID
+    (`<repoId>::<path>`)."""
+    env = os.environ if env is None else env
+    if not any(env.get(k) for k in MARKERS) and env.get("TERM_PROGRAM") != "Orca":
+        return None
+    return {"worktree": env.get("ORCA_WORKTREE_ID", "").partition("::")[2],
+            "terminal": env.get("ORCA_TERMINAL_HANDLE", ""),
+            "version": env.get("ORCA_APP_VERSION", "")}
+
+
+def cli(env=None, platform=None):
+    """The argv prefix that runs Orca's CLI, or None. The order is the orca-cli
+    skill's: Orca's own ORCA_CLI_COMMAND (WSL), then its exported bin dir, then
+    PATH. On Linux outside an Orca terminal a bare `orca` is the GNOME screen
+    reader, so only `orca-ide` counts there. TEZGAH_ORCA_BIN pins one binary
+    (tests): a missing one is None, never a fallback to the real app."""
+    env = os.environ if env is None else env
+    platform = platform or sys.platform
+    pinned = env.get("TEZGAH_ORCA_BIN")
+    if pinned:
+        return [pinned] if os.access(pinned, os.X_OK) else None
+    if env.get("ORCA_CLI_COMMAND"):
+        return shlex.split(env["ORCA_CLI_COMMAND"])
+    bindir = env.get("ORCA_CLI_BIN_DIR")
+    if bindir and os.access(os.path.join(bindir, "orca"), os.X_OK):
+        return [os.path.join(bindir, "orca")]
+    path = env.get("PATH", os.defpath)
+    name = ("orca-ide" if platform.startswith("linux") and not session(env)
+            else "orca")
+    found = shutil.which(name, path=path)
+    if found:
+        return [found]
+    if platform == "darwin" and os.access(MAC_APP_CLI, os.X_OK):
+        return [MAC_APP_CLI]
+    return None
+
+
+def run(args, timeout=10):
+    """`orca <args> --json`'s `result`, or None when there is no CLI, the
+    runtime is down or the answer is not `ok`."""
+    argv = cli()
+    if not argv:
+        return None
+    try:
+        proc = subprocess.run(argv + list(args) + ["--json"], capture_output=True,
+                              text=True, timeout=timeout)
+        data = json.loads(proc.stdout)
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return None
+    return data.get("result") if isinstance(data, dict) and data.get("ok") else None
+
+
+def checkouts(paths):
+    """Orca's view of a repository's git checkouts (`paths`, real paths):
+    {"tracked": [row per checkout Orca lists], "untracked": [path Orca does not
+    list]}, or None when the runtime cannot answer. Read from `orca worktree ps`,
+    the one call that carries terminals and agent states together."""
+    ps = run(["worktree", "ps", "--limit", "1000"])
+    if ps is None:
+        return None
+    wanted = set(paths)
+    tracked = {}
+    for row in ps.get("worktrees") or []:
+        path = os.path.realpath(row.get("path") or "")
+        if path in wanted:
+            tracked[path] = {
+                "path": path, "name": row.get("displayName") or "",
+                "card": row.get("workspaceStatus") or "",
+                "status": row.get("status") or "",
+                "terminals": row.get("liveTerminalCount") or 0,
+                "agents": ["%s:%s" % (a.get("agentType"), a.get("state"))
+                           for a in row.get("agents") or []]}
+    return {"tracked": [tracked[p] for p in paths if p in tracked],
+            "untracked": [p for p in paths if p not in tracked]}
+
+
+def context_line(env=None):
+    """The session-start line for a session inside Orca, or "" outside it."""
+    here = session(env)
+    if not here:
+        return ""
+    where = here["worktree"] or "unknown"
+    return ("Orca: this session runs in an Orca terminal (worktree `%s`); Orca "
+            "owns worktrees, terminals, its embedded browser and artifacts here. "
+            "A parallel slice that needs its own checkout gets one from `orca "
+            "worktree create --name <slug> --parent-worktree active --json` (add "
+            "`--agent <cli> --prompt <brief>` to start its worker there), not "
+            "`git worktree add`, which Orca does not list. A long job runs in "
+            "`orca terminal create --worktree <selector> --command <cmd> --json`, "
+            "not a background shell. Track with `orca worktree ps --json` and "
+            "`tezgah-status --orca`; mark checkpoints with `orca worktree set "
+            "--worktree active --comment <text>`. Full guide: `orca skills get "
+            "orca-cli`." % where)
+
+
+def summary(codex_home):
+    """One `orca:` line for `tezgah-setup --status`: app/runtime, whether this
+    shell is in an Orca terminal, and whose codex home CODEX_HOME names; ""
+    when Orca is neither installed nor around this shell."""
+    argv, here = cli(), session()
+    if not argv and not here:
+        return ""
+    runtime = ((run(["status"]) or {}).get("runtime") or {}) if argv else {}
+    parts = ["orca: %s" % (
+        "runtime %s reachable" % runtime.get("appVersion", "")
+        if runtime.get("reachable") else
+        "CLI %s, runtime not reachable (`orca open`)" % argv[-1] if argv else
+        "no orca CLI found")]
+    parts.append("this shell runs in an Orca terminal (worktree %s)"
+                 % (here["worktree"] or "unknown") if here
+                 else "this shell is not an Orca terminal")
+    if os.path.isfile(os.path.join(codex_home, MANAGED_HOME)):
+        parts.append("CODEX_HOME %s is an Orca-managed codex home: tezgah adds "
+                     "its hook groups beside Orca's and leaves Orca's entries "
+                     "and env alone" % codex_home)
+    return "; ".join(parts)

package/hooks/tezgah_paths.py

@@ -497,18 +497,23 @@ def have_typesafe_key():
 
 
 def have_judge_key():
-    """True when tezgah's own judgement seam resolves a credential: the env var
-    it reads, else its key file - and, when neither resolves, the OpenRouter
-    fallback's own two channels (`OPENROUTER_API_KEY`, `~/.config/openrouter/key`),
-    which are the channels `hooks/tezgah_judge.py`'s `credential()` 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.
+    """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.
 
     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`."""
+    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():
@@ -522,6 +527,35 @@ def have_judge_key():
     return False
 
 
+# How far a model call may leave the session's own vendor (config.json
+# `fallback`). `vendor`, the default: the session's own model first, and a
+# fallback only to the same vendor's model (a subagent chain may reach Opus
+# through OpenRouter; the judge has no such route, so it falls back to nobody
+# while the session CLI exists, and to a third party only when there is no
+# session CLI at all). `any`: a cross-vendor fallback is allowed after the
+# session's own model fails. `none`: no provider but the session's, ever.
+FALLBACKS = ("vendor", "any", "none")
+
+
+def fallback_policy():
+    """The configured `fallback` value, `vendor` when unset or unknown."""
+    cfg = config()
+    value = cfg.get("fallback") if isinstance(cfg, dict) else None
+    return value if value in FALLBACKS else "vendor"
+
+
+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
+
+
 def orx_bin():
     """The OpenResearch `orx` executable, or None when it is not installed.