@r1z4x/tezgah 1.0.0

package/hooks/tezgah_guard.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""One guard for every entry point: a crashing core degrades one feature.
+
+Each host entry point decodes its payload defensively and then calls into the
+shared core. That call is where a bug stops being a bug and becomes an outage:
+on Claude, Codex and Cursor the session loses one envelope, but on omp the
+bridge turns the same crash into a *session-wide* disable - the gate, the ledger
+and the status line all go off for the rest of the session, with the model told
+not to fix it - and opencode's plugin waits on a core process with no deadline.
+Same fault, blast radii that differ by two orders of magnitude.
+
+`safe` is the single place that fault is caught, and it is applied at every call
+site rather than re-derived per host, for the reason the gate's own refusals are
+recorded: "a deny nobody counts is a rule whose effect can never be argued
+about". A crash swallowed in silence would be worse than the crash - it would
+look like a rule that fired and a core that answered - so the caught class is
+written to the ledger as a `crash` row, best effort, and the row is the only
+thing this module does besides returning None.
+
+It fails open, deliberately, and in the direction the whole layer already
+chooses: the gate passes a call whose record it cannot read, the context builder
+returns None outside a root, and a judgement that cannot be made returns "". A
+core that has crashed has not refused anything, so the call it was guarding
+proceeds - the alternative is a session in which a broken *rule* blocks every
+action, which is the fail-closed trap the design names.
+"""
+import os
+import sys
+import time
+
+# TEZGAH_DEBUG=1 appends one line per hook process to `<cache>/debug.log`: the
+# host, the entry script, every guarded core call with its outcome, and the
+# elapsed time. Audit L-11 (GAP-10) found no debug level at all, so a slow or
+# silently failing hook could only be diagnosed by editing it. Every entry point
+# reaches the core through `safe`, and a hook is one process per event, so the
+# line is written once at exit from what `safe` saw. Off by default, and then
+# the whole cost is this one environment read.
+DEBUG = os.environ.get("TEZGAH_DEBUG", "") not in ("", "0")
+_CALLS = []
+# Plumbing every entry runs before its first decision (the plan 051 switch
+# latch): its success says nothing about the event, so only its crash is logged.
+_PLUMBING = frozenset({"bind_session"})
+_START = time.monotonic()
+
+
+def _host():
+    """`hosts/<name>/...` names its host; the shared `hooks/projects-*.py`
+    scripts run on Claude and dsh alike, so they are named by the script."""
+    parts = os.path.realpath(sys.argv[0] if sys.argv else "").split(os.sep)
+    return parts[parts.index("hosts") + 1] if "hosts" in parts[:-1] else "claude/dsh"
+
+
+def _write_debug():
+    """The line, appended to a file created owner-only (it names the calls a
+    session made). Best effort: a debug log must never cost the hook."""
+    try:
+        from tezgah_paths import cache_dir
+        line = "%d host=%s script=%s calls=%s ms=%d\n" % (
+            int(time.time()), _host(), os.path.basename(sys.argv[0] if sys.argv else ""),
+            ",".join(_CALLS) or "none", (time.monotonic() - _START) * 1000)
+        fd = os.open(os.path.join(cache_dir(), "debug.log"),
+                     os.O_WRONLY | os.O_CREAT | os.O_APPEND, 0o600)
+        with os.fdopen(fd, "a", encoding="utf-8") as fh:
+            fh.write(line)
+    except Exception:
+        pass
+
+
+if DEBUG:
+    import atexit
+    atexit.register(_write_debug)
+
+
+def safe(session_id, fn, *args, **kwargs):
+    """`fn(*args, **kwargs)`, or None when it raises. Never raises itself.
+
+    `session_id` is the guard's own argument, not the callee's: it is what the
+    crash row is filed under, so the first argument of the call is passed after
+    it. A caller with no session id passes None, which `note` treats as the
+    unowned ledger the rest of the module already writes to."""
+    try:
+        out = fn(*args, **kwargs)
+        if DEBUG and getattr(fn, "__name__", "?") not in _PLUMBING:
+            # `answer`: the core returned something (a deny reason, a context
+            # block, a block decision); `none`: it had nothing to say
+            _CALLS.append("%s:%s" % (getattr(fn, "__name__", "?"),
+                                     "none" if out is None else "answer"))
+        return out
+    except Exception as exc:
+        if DEBUG:
+            _CALLS.append("%s:%s" % (getattr(fn, "__name__", "?"),
+                                     type(exc).__name__))
+        try:
+            import tezgah_integrity
+            tezgah_integrity.note(
+                session_id, "crash",
+                "%s: %s" % (getattr(fn, "__name__", str(fn)), str(exc)[:120]))
+        except Exception:
+            # The record is best effort by construction: a guard that raised
+            # while reporting a raise would be the failure it exists to stop.
+            pass
+        return None
+
+
+def _payload_session():
+    """The session id the host handed this process, best effort: the payload on
+    stdin (every hook, the opencode CLIs) or the JSON argument tezgah-capture
+    takes, else TEZGAH_SESSION. The hook never reached its own decode, so this
+    read consumes nothing anyone else will look at."""
+    import json
+    sources = []
+    try:
+        if sys.stdin is not None and not sys.stdin.isatty():
+            sources.append(sys.stdin.read())
+    except Exception:
+        pass
+    sources += sys.argv[1:]
+    for raw in sources:
+        try:
+            data = json.loads(raw)
+        except Exception:
+            continue
+        if isinstance(data, dict):
+            for key in ("session_id", "sessionID", "sessionId", "conversation_id"):
+                if data.get(key):
+                    return str(data[key])
+    return os.environ.get("TEZGAH_SESSION") or "unknown-session"
+
+
+def attest_session(host, session_id, cwd):
+    """The session-start attestation (`tezgah_attest.run`), imported only here
+    and only when called: a broken attestation module then costs the `attest`
+    row inside `safe()`, never the import of a hook that also gates."""
+    import tezgah_attest
+    return tezgah_attest.run(host, session_id, cwd)
+
+
+def import_crash_mark(session_id):
+    """The mark an import failure leaves for the status line, one per session.
+    Built here from stdlib alone (the same `~/.cache/tezgah` as
+    `tezgah_paths.CACHE`), because the module that failed may be tezgah_paths."""
+    import hashlib
+    return os.path.join(os.path.expanduser("~"), ".cache", "tezgah", "import-crash",
+                        hashlib.sha256(str(session_id).encode()).hexdigest()[:16])
+
+
+def import_failed(exc, code=0):
+    """An entry point whose core imports raised: say so and exit `code`.
+
+    `safe` covers the calls, not the `from tezgah_x import ...` lines above
+    them, so a module that failed to import (a rename, a syntax error a release
+    shipped) ended the hook with a traceback - on omp that disables the gate,
+    the ledger and the status line for the session (the lessons ledger records
+    the rename that crashed every omp hook). A hook fails open (`code` 0) like
+    every other caught fault, so the dead core must be visible elsewhere: one
+    stderr line always, a `crash` row when the ledger's own modules still
+    import, and a mark the status line draws (`import_crash_mark`). A CLI a
+    person or a tool asks for a verdict (`tezgah-gate check`) passes a non-zero
+    `code`: an empty answer from it would read as a pass."""
+    detail = "import: %s: %s" % (type(exc).__name__, str(exc)[:120])
+    sys.stderr.write("tezgah: %s could not import its core (%s); this call ran "
+                     "without tezgah\n"
+                     % (os.path.basename(sys.argv[0] if sys.argv else "hook"), detail))
+    session = _payload_session()
+    try:
+        mark = import_crash_mark(session)
+        os.makedirs(os.path.dirname(mark), exist_ok=True)
+        with open(mark, "w", encoding="utf-8") as fh:
+            fh.write(detail + "\n")
+    except Exception:
+        pass
+    try:
+        import tezgah_integrity
+        tezgah_integrity.note(session, "crash", detail)
+    except Exception:
+        pass
+    sys.exit(code)

package/hooks/tezgah_index.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""Detached graph auto-index worker: lock-guarded, bounded retry.
+
+Spawned by tezgah_context.autoindex as
+    [python, tezgah_index.py, binary, root, head, stamp_path, lock_path]
+
+`binary` is the resolved codegraph executable, so the worker never re-resolves
+it. codegraph keeps one live writer per project, so two indexers on one repo is
+the failure the flock below covers; it is also why the retry and the stamp are
+shared with every other caller. HEAD is stamped only after a successful index, so
+a failed run is retried on the next session start rather than being mistaken for
+current. A final failure leaves a `<stamp>.failed` marker that autoindex surfaces
+to the next session, instead of looping invisibly. The flock dies with the
+process, so a crash never leaves a stale lock behind. A host without `fcntl`
+(Windows) still runs this worker: the lock step says it is indexing unlocked and
+carries on, because the index is worth having without one - the same degrading
+import `tezgah_integrity` and `tezgah_research` use. Stdlib only.
+"""
+import os
+import signal
+import subprocess
+import sys
+import time
+
+try:
+    import fcntl
+except ImportError:  # not POSIX: index unlocked, and say so on stderr (below)
+    fcntl = None
+
+RETRIES = int(os.environ.get("TEZGAH_INDEX_RETRIES", "5"))
+DELAY = float(os.environ.get("TEZGAH_INDEX_RETRY_DELAY", "3"))
+# How long one index attempt may run before its process group is killed.
+# Generous on purpose - the worker is detached and retries, so the bound exists
+# to stop an unbounded wait, not to time a slow index. Without it a codegraph
+# that hangs holds this repo's flock forever, and the next session's auto-index
+# then declines to start for the rest of the machine's uptime.
+RUN_TIMEOUT = float(os.environ.get("TEZGAH_INDEX_TIMEOUT", "600"))
+
+
+def run_bounded(argv, timeout=None):
+    """Run one index attempt in its own process group and return its exit status.
+
+    The group is what makes the bound real: `subprocess.run(timeout=)` kills the
+    direct child only, so a codegraph that spawns a helper and then hangs leaves
+    the helper behind and the wait continues one level down. The child is started
+    with `start_new_session=True` - the same shape `tezgah_context.autoindex`
+    already gives this worker - so one `killpg` takes the whole tree. A failed
+    kill is not fatal: the worker exits anyway, and the flock dies with it."""
+    timeout = RUN_TIMEOUT if timeout is None else timeout
+    try:
+        proc = subprocess.Popen(argv, stdout=subprocess.DEVNULL,
+                                stderr=subprocess.DEVNULL,
+                                start_new_session=True)
+    except OSError:
+        return 1
+    try:
+        return proc.wait(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        try:
+            os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+        except OSError:
+            try:
+                proc.kill()
+            except OSError:
+                pass
+        try:
+            proc.wait(timeout=10)
+        except subprocess.TimeoutExpired:
+            pass
+        return 1
+
+
+def command(binary, root):
+    """The argv for one codegraph run over one repository.
+
+    codegraph's own switch is whether the project carries an index already: a
+    project it has never seen takes `init` (non-interactive, so a detached worker
+    cannot hang on a prompt) and one it has takes the incremental `sync`."""
+    if os.path.exists(os.path.join(root, ".codegraph", "codegraph.db")):
+        return [binary, "sync", root]
+    return [binary, "init", root, "-y"]
+
+
+def main():
+    binary, root, head, stamp, lock = sys.argv[1:6]
+    os.makedirs(os.path.dirname(lock), exist_ok=True)
+    handle = open(lock, "w", encoding="utf-8")
+    if fcntl is None:
+        # No advisory lock on this host. Refusing would leave a Windows repo with
+        # no index at all, so run unlocked - but never silently: the parent sends
+        # this to the repo's index log, which is the file a session names when it
+        # reports an index problem.
+        sys.stderr.write(
+            "tezgah: no fcntl on this host; indexing %s unlocked\n" % root)
+    else:
+        try:
+            fcntl.flock(handle, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError:
+            return 0  # another indexer holds this repo; its run will stamp HEAD
+    argv = command(binary, root)
+    failed = stamp + ".failed"
+    for _ in range(RETRIES):
+        if run_bounded(argv) != 0:
+            time.sleep(DELAY)
+            continue
+        with open(stamp, "w", encoding="utf-8") as fh:
+            fh.write(head)
+        try:
+            os.remove(failed)
+        except OSError:
+            pass
+        return 0
+    # leave a marker so the next session reports the failure instead of only
+    # re-spawning the worker silently
+    try:
+        with open(failed, "w", encoding="utf-8") as fh:
+            fh.write("codegraph index failed after %d attempt(s)\n" % RETRIES)
+    except OSError:
+        pass
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())