@r1z4x/tezgah 1.0.0

package/bin/tezgah-doctor

@@ -0,0 +1,497 @@
+#!/usr/bin/env python3
+"""tezgah-doctor - report and reclaim the state the armed harnesses leave behind.
+
+Two stores grow without bound and neither rotates on its own:
+  - opencode's SQLite session/event database (~/.local/share/opencode/opencode.db)
+  - one codegraph index per indexed repository (`<repo>/.codegraph/codegraph.db`).
+    It lives inside the repo rather than in one shared cache, so there is no
+    central directory to measure: the per-repo scan below is the only place the
+    total is visible, and a repo whose index is stale or abandoned keeps its
+    bytes until its owner deletes them.
+
+It also reports the hosts' own state (~/.codex, ~/.omp, ~/.claude) and never
+touches it: those stores belong to the hosts, and the number is here so a reader
+can decide, not so this tool can act.
+
+This tool is read-only by default. With --clean it vacuums the opencode database
+(only when opencode is not running, so it cannot fight a live connection).
+VACUUM alone cannot shrink that database - its pages are all live - so
+--prune-sessions is the action that actually reclaims space: it deletes old
+sessions through the supported opencode command and then vacuums.
+
+--coverage is the other read-only report, and the one codegraph does not ship:
+every tracked file the index does not hold, in the two classes a file can go
+missing by. Its rules are imported from benchmarks/codegraph-bench/probe.py, the
+spike that measured them. That file is in MANIFEST, which `packaging/build.sh`
+ships verbatim, so a release artifact carries it and a packaged install answers
+`--coverage` in full. A tree that lost it - a hand-stripped copy, a repack that
+dropped benchmarks/ - gets a named refusal and exit 0 rather than an ImportError
+out of a shipped CLI. Everything it reads is the standard library or a file in
+this tree.
+
+  tezgah-doctor                    report sizes and counts
+  tezgah-doctor --json             same, machine readable
+  tezgah-doctor --coverage         the tracked files the graph index does not hold
+  tezgah-doctor --coverage --repo ~/Projects/x
+  tezgah-doctor --clean            vacuum the opencode database, and delete the
+                                   hook state (evidence ledgers, turns/,
+                                   sessions/, classify.log, context-drops.log,
+                                   debug.log) idle > 30 days
+                                   (--retention-days N); $TEZGAH_SESSION's
+                                   own files are always kept
+  tezgah-doctor --prune-sessions 30   delete sessions idle > 30 days, then vacuum
+"""
+import argparse
+import importlib.machinery
+import importlib.util
+import json
+import os
+import shutil
+import sqlite3
+import subprocess
+import sys
+import time
+
+HOME = os.path.expanduser("~")
+# this file lives in <checkout>/bin, and the coverage rules live in the checkout's
+# bench directory next to the hooks that own the roots and the binary resolver
+REPO_ROOT = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
+sys.path.insert(0, os.path.join(REPO_ROOT, "hooks"))
+from tezgah_paths import (CACHE, CODEGRAPH, codegraph_bin,  # noqa: E402
+                          fallback_cache, root_for, roots)
+
+# the coverage rules, in the bench directory next to the hooks that own the roots
+# and the binary resolver. MANIFEST lists it, so it ships; it is also the one file
+# here that a repack may drop, so `load_probe` treats it as optional rather than
+# assuming it.
+PROBE = os.path.join(REPO_ROOT, "benchmarks", "codegraph-bench", "probe.py")
+OPENCODE = os.path.join(
+    os.environ.get("XDG_CONFIG_HOME") or os.path.join(HOME, ".config"), "opencode")
+OPENCODE_DATA = os.environ.get("TEZGAH_OPENCODE_DATA",
+                               os.path.join(HOME, ".local", "share", "opencode"))
+OPENCODE_DB = os.path.join(OPENCODE_DATA, "opencode.db")
+TEZGAH_CACHE = os.path.join(HOME, ".cache", "tezgah")
+OPENCODE_BIN = shutil.which("opencode")
+# codegraph's index, inside the repo it belongs to (derived from the engine name
+# itself, so the doctor cannot name a directory the engine does not write)
+GRAPH_DIR = "." + CODEGRAPH
+GRAPH_DB = CODEGRAPH + ".db"
+# The per-session state the hooks write and nothing else removes: the evidence
+# ledgers, the per-turn stamps, the used-tool marks and the two capped logs.
+# Audit L-11 (GAP-10) measured 2,000 of each, 400 days old, surviving a full
+# cycle and `--clean`. Snapshots are not here: tezgah_snapshot caps them itself.
+STATE_DIRS = ("evidence", "turns", "sessions")
+STATE_LOGS = ("classify.log", "context-drops.log", "debug.log")
+RETENTION_DAYS = 30
+
+
+def du(path):
+    total = 0
+    for root, _dirs, files in os.walk(path):
+        for name in files:
+            try:
+                total += os.path.getsize(os.path.join(root, name))
+            except OSError:
+                pass
+    return total
+
+
+def human(n):
+    n = float(n)
+    for unit in ("B", "K", "M", "G"):
+        if n < 1024:
+            return "%.1f%s" % (n, unit)
+        n /= 1024.0
+    return "%.1fT" % n
+
+
+def codegraph_size(repo):
+    """One repo's index as (bytes, has_index).
+
+    The file is the marker, not the directory: codegraph writes `.codegraph/`
+    with its lock and `.gitignore` before the index exists, so a directory
+    without `codegraph.db` is a repo whose index never finished."""
+    try:
+        return os.path.getsize(os.path.join(repo, GRAPH_DIR, GRAPH_DB)), True
+    except OSError:
+        return 0, False
+
+
+def is_repo(path):
+    """Git is the marker, and a worktree keeps `.git` as a file. `.codegraph` is
+    the second one: an indexed project that is not a git checkout is still a repo
+    this report has bytes to account for."""
+    return (os.path.exists(os.path.join(path, ".git"))
+            or os.path.isdir(os.path.join(path, GRAPH_DIR)))
+
+
+def repos_under(root, depth=2):
+    """The repositories one configured root holds, as absolute paths.
+
+    Two levels below the root, so both a flat `~/Projects/<repo>` layout and an
+    `~/Projects/<org>/<repo>` one are covered. The walk stops at the first repo
+    on a path: descending into one would report its vendored checkouts as repos
+    of their own."""
+    found = []
+    frontier = [(root, 0)]
+    while frontier:
+        directory, level = frontier.pop()
+        if is_repo(directory):
+            found.append(directory)
+            continue
+        if level >= depth:
+            continue
+        try:
+            names = sorted(os.listdir(directory))
+        except OSError:
+            continue
+        for name in names:
+            path = os.path.join(directory, name)
+            if not name.startswith(".") and os.path.isdir(path):
+                frontier.append((path, level + 1))
+    return sorted(found)
+
+
+def targets(named):
+    """The repositories to account for as (configured root, repo) pairs: the ones
+    the user named, else every repository under a configured tezgah root."""
+    if named:
+        out = []
+        for path in named:
+            repo = os.path.realpath(os.path.expanduser(path))
+            out.append((root_for(repo) or "", repo))
+        return out
+    return [(root, repo) for root in roots() for repo in repos_under(root)]
+
+
+def host_bytes():
+    """The hosts' own state dirs, measured and never touched by this tool."""
+    return {"codex_bytes": du(os.path.join(HOME, ".codex")) if os.path.isdir(
+        os.path.join(HOME, ".codex")) else 0,
+        "omp_bytes": du(os.path.join(HOME, ".omp")) if os.path.isdir(
+        os.path.join(HOME, ".omp")) else 0,
+        "claude_bytes": du(os.path.join(HOME, ".claude")) if os.path.isdir(
+        os.path.join(HOME, ".claude")) else 0}
+
+
+def db_rows(db, table):
+    if not os.path.exists(db):
+        return None
+    try:
+        con = sqlite3.connect("file:%s?mode=ro" % db, uri=True)
+        try:
+            return con.execute("SELECT count(*) FROM %s" % table).fetchone()[0]
+        finally:
+            con.close()
+    except sqlite3.Error:
+        return None
+
+
+def opencode_cfg():
+    try:
+        with open(os.path.join(OPENCODE, "opencode.json"), encoding="utf-8") as fh:
+            return json.load(fh)
+    except Exception:
+        return {}
+
+
+def opencode_running():
+    try:
+        return subprocess.run(["pgrep", "-x", "opencode"],
+                              capture_output=True).returncode == 0
+    except OSError:
+        return False
+
+
+def collect(pairs):
+    cfg = opencode_cfg()
+    repos = []
+    for root, repo in pairs:
+        size, indexed = codegraph_size(repo)
+        repos.append({"root": root, "repo": repo, "bytes": size, "indexed": indexed})
+    return {
+        "opencode_db_bytes": os.path.getsize(OPENCODE_DB) if os.path.exists(OPENCODE_DB) else 0,
+        "opencode_sessions": db_rows(OPENCODE_DB, "session"),
+        "opencode_events": db_rows(OPENCODE_DB, "event"),
+        "opencode_running": opencode_running(),
+        "compaction_prune": (cfg.get("compaction") or {}).get("prune"),
+        "watcher_ignore": len(((cfg.get("watcher") or {}).get("ignore") or [])),
+        "codegraph_repos": repos,
+        "codegraph_bytes": sum(r["bytes"] for r in repos),
+        "tezgah_cache_bytes": du(TEZGAH_CACHE) if os.path.isdir(TEZGAH_CACHE) else 0,
+        **host_bytes(),
+    }
+
+
+def vacuum_db():
+    before = os.path.getsize(OPENCODE_DB)
+    con = sqlite3.connect(OPENCODE_DB)
+    try:
+        con.execute("PRAGMA wal_checkpoint(TRUNCATE)")
+        con.execute("VACUUM")
+        con.commit()
+    finally:
+        con.close()
+    return before, os.path.getsize(OPENCODE_DB)
+
+
+def select_old_sessions(days):
+    """Sessions whose last update is older than `days`, oldest first."""
+    if not os.path.exists(OPENCODE_DB):
+        return []
+    cutoff = int((time.time() - days * 86400) * 1000)  # time_updated is epoch ms
+    try:
+        con = sqlite3.connect("file:%s?mode=ro" % OPENCODE_DB, uri=True)
+        try:
+            rows = con.execute(
+                "SELECT id FROM session WHERE time_updated < ? ORDER BY time_updated",
+                (cutoff,)).fetchall()
+            return [r[0] for r in rows]
+        finally:
+            con.close()
+    except sqlite3.Error:
+        return []
+
+
+def prune_sessions(days):
+    """Delete sessions older than `days` and return (deleted, failed).
+
+    Uses `opencode session delete` rather than raw SQL: that keeps the event log
+    and the running server consistent. The caller guarantees opencode is stopped.
+    """
+    ids = select_old_sessions(days)
+    if not ids or not OPENCODE_BIN:
+        # nothing is attempted without the CLI; the caller reports the skip, so
+        # do not count these ids as failed deletions
+        return 0, 0
+    deleted = failed = 0
+    for sid in ids:
+        proc = subprocess.run([OPENCODE_BIN, "session", "delete", sid],
+                              capture_output=True)
+        if proc.returncode == 0:
+            deleted += 1
+        else:
+            failed += 1
+    return deleted, failed
+
+
+def sweep_state(days, session=None):
+    """Delete the hook state not modified for `days`, in the global cache and
+    the temp fallback; (removed, bytes freed).
+
+    By mtime because every writer appends or rewrites in place, so a file's
+    mtime is its session's last activity. The current session's files
+    (`TEZGAH_SESSION`, the id omp and the judgement CLIs export) are kept
+    whatever their age: a session idle past the window and then resumed must
+    not lose its ledger mid-flight."""
+    from tezgah_context import slug
+    from tezgah_integrity import _slug
+    keep = ({_slug(session) + ".jsonl", slug(session) + ".json",
+             slug(session) + ".jsonl"} if session else set())
+    cutoff = time.time() - days * 86400
+    removed = freed = 0
+    for base in dict.fromkeys((CACHE, fallback_cache())):
+        paths = [os.path.join(base, name) for name in STATE_LOGS]
+        for sub in STATE_DIRS:
+            try:
+                paths += [os.path.join(base, sub, n)
+                          for n in os.listdir(os.path.join(base, sub))]
+            except OSError:
+                continue
+        for path in paths:
+            if os.path.basename(path) in keep:
+                continue
+            try:
+                st = os.lstat(path)
+                if not os.path.isfile(path) or st.st_mtime >= cutoff:
+                    continue
+                os.remove(path)
+            except OSError:
+                continue
+            removed += 1
+            freed += st.st_size
+    return removed, freed
+
+
+
+def load_probe():
+    """The bench spike, imported by path so its two coverage rules stay the only
+    implementation of them; `None` when this tree has no such file.
+
+    Its directory name (`codegraph-bench`) is not an identifier, so it cannot be
+    imported as a package; a copy of the rules here would be a second definition
+    of "covered" that drifts from the spike's the first time either is touched.
+    Missing is an answer, not an error: a tree that dropped benchmarks/ asks for
+    rules that are simply not there, and a shipped CLI may not raise at the user
+    over a file it can describe."""
+    if not os.path.exists(PROBE):
+        return None
+    loader = importlib.machinery.SourceFileLoader("tezgah_codegraph_probe", PROBE)
+    spec = importlib.util.spec_from_loader(loader.name, loader)
+    module = importlib.util.module_from_spec(spec)
+    loader.exec_module(module)
+    return module
+
+
+def coverage_report(repo, dump_path):
+    """Every tracked file the codegraph index does not hold, as two classes.
+
+    A report, not a gate: it always exits 0, and the counts it read come first,
+    so an empty result cannot read as "everything is covered". The same holds
+    when the rules themselves are not in this tree: it names the file and what to
+    do, so a user of a tree that lost them reads a reason, not a traceback."""
+    probe = load_probe()
+    if probe is None:
+        print("codegraph coverage: %s" % repo)
+        print("  coverage probe unavailable: %s" % PROBE)
+        print("  it is the only implementation of these rules and this tree has "
+              "lost it (a copy or repack that dropped benchmarks/): run "
+              "--coverage from a tree that has it.")
+        return 0
+    binary = codegraph_bin()
+    report, why = probe.coverage(repo, dump_path,
+                                 [binary] if binary else None)
+    print("codegraph coverage: %s" % repo)
+    if report is None:
+        print("  could not read an index dump: %s" % why)
+        print("  index the repo first (`codegraph init`), run this in a git work "
+              "tree, or pass --dump FILE with the output of `codegraph files -j`.")
+        return 0
+    print("  tracked files read: %d | files the index holds: %d"
+          % (report["tracked"], report["indexed"]))
+    print("  uncovered, supported extension (%d):" % len(report["by_ext"]))
+    for rel, lang in report["by_ext"]:
+        print("    %s (%s)" % (rel, lang))
+    print("  uncovered, shebang-only script with no `.py` twin (%d):"
+          % len(report["by_shebang"]))
+    for rel, lang in report["by_shebang"]:
+        print("    %s (%s)" % (rel, lang))
+    print("  covered through a `.py` twin (%d)" % len(report["twins"]))
+    print("  codegraph reports none of this itself: `status` counts what it "
+          "parsed, never what it skipped.")
+    return 0
+
+
+def report(rep):
+    print("opencode")
+    print("  db            %s  (%s sessions, %s events)" % (
+        human(rep["opencode_db_bytes"]), rep["opencode_sessions"], rep["opencode_events"]))
+    print("  compaction    prune=%s  watcher.ignore=%d" % (
+        rep["compaction_prune"], rep["watcher_ignore"]))
+    print("  running       %s" % ("yes" if rep["opencode_running"] else "no"))
+    print("codegraph (one index per repository)")
+    rows = rep["codegraph_repos"]
+    if not rows:
+        print("  no repository under a configured root (%s)"
+              % (", ".join(roots()) or "none configured"))
+    else:
+        root = None
+        for row in rows:
+            if row["root"] != root:
+                root = row["root"]
+                print("  %s" % (root or "(named on the command line)"))
+            print("    %-40s %9s  %s" % (
+                os.path.relpath(row["repo"], root) if root else row["repo"],
+                human(row["bytes"]), "indexed" if row["indexed"] else "no index"))
+        indexed = sum(1 for row in rows if row["indexed"])
+        print("  total         %s across %d repos (%d indexed, %d without an index)"
+              % (human(rep["codegraph_bytes"]), len(rows), indexed,
+                 len(rows) - indexed))
+    print("tezgah")
+    print("  cache         %s" % human(rep["tezgah_cache_bytes"]))
+    print("host state (the hosts' own; this tool never touches it)")
+    for label, key in (("codex", "codex_bytes"), ("omp", "omp_bytes"),
+                       ("claude", "claude_bytes")):
+        print("  %-13s %s" % (label, human(rep[key])))
+
+
+def main():
+    ap = argparse.ArgumentParser(description="report and reclaim harness state")
+    ap.add_argument("--json", action="store_true", help="machine-readable report")
+    ap.add_argument("--coverage", action="store_true",
+                    help="the tracked files the graph index does not hold (exits 0)")
+    ap.add_argument("--repo", action="append", metavar="PATH",
+                    help="a repository to account for instead of the configured "
+                         "roots (repeatable; --coverage reports the first)")
+    ap.add_argument("--dump", metavar="FILE",
+                    help="a saved `codegraph files -j` dump to read for --coverage")
+    ap.add_argument("--clean", action="store_true",
+                    help="vacuum the opencode database and delete tezgah hook "
+                         "state (ledgers, turns/, sessions/, classify.log, "
+                         "context-drops.log, debug.log) not "
+                         "modified for --retention-days; the current session "
+                         "($TEZGAH_SESSION) is kept (opt-in)")
+    ap.add_argument("--retention-days", type=int, default=RETENTION_DAYS,
+                    metavar="DAYS",
+                    help="the age --clean deletes hook state past (default: "
+                         "%(default)s days)")
+    ap.add_argument("--prune-sessions", type=int, metavar="DAYS",
+                    help="delete sessions idle longer than DAYS, then vacuum")
+    args = ap.parse_args()
+    if args.retention_days < 1:
+        ap.error("--retention-days wants a positive day count")
+
+    if args.coverage:
+        repo = os.path.realpath(os.path.expanduser(args.repo[0]) if args.repo
+                                else os.getcwd())
+        return coverage_report(repo, args.dump)
+
+    pairs = targets(args.repo)
+    rep = collect(pairs)
+    cleaned = None
+    if args.clean or args.prune_sessions is not None:
+        cleaned = {}
+        if args.prune_sessions is not None and os.path.exists(OPENCODE_DB):
+            if rep["opencode_running"]:
+                cleaned["prune_sessions"] = "skipped: opencode is running"
+            elif not OPENCODE_BIN:
+                cleaned["prune_sessions"] = "skipped: opencode is not installed"
+            else:
+                deleted, failed = prune_sessions(args.prune_sessions)
+                cleaned["prune_sessions"] = {"deleted": deleted, "failed": failed}
+        if os.path.exists(OPENCODE_DB):
+            if rep["opencode_running"]:
+                cleaned["vacuum"] = "skipped: opencode is running"
+            else:
+                try:
+                    before, after = vacuum_db()
+                    cleaned["vacuum"] = {"before": before, "after": after}
+                except sqlite3.Error as exc:
+                    cleaned["vacuum"] = "failed: %s" % exc
+        if args.clean:
+            removed, freed = sweep_state(args.retention_days,
+                                         os.environ.get("TEZGAH_SESSION"))
+            cleaned["state"] = {"removed": removed, "bytes": freed,
+                                "days": args.retention_days}
+        rep = collect(pairs)
+
+    if args.json:
+        out = dict(rep)
+        if cleaned is not None:
+            out["cleaned"] = cleaned
+        print(json.dumps(out, indent=2))
+        return 0
+    report(rep)
+    if cleaned is not None:
+        print("cleaned")
+        ps = cleaned.get("prune_sessions")
+        if isinstance(ps, dict):
+            print("  sessions      %d deleted, %d failed" % (ps["deleted"], ps["failed"]))
+        elif ps:
+            print("  sessions      %s" % ps)
+        v = cleaned.get("vacuum")
+        if isinstance(v, dict):
+            print("  vacuum        %s -> %s" % (human(v["before"]), human(v["after"])))
+        elif v:
+            print("  vacuum        %s" % v)
+        st = cleaned.get("state")
+        if st:
+            print("  hook state    %d file(s) older than %d days removed, %s"
+                  % (st["removed"], st["days"], human(st["bytes"])))
+    elif rep["opencode_db_bytes"] > 500 * 1024 * 1024:
+        print("\nrun with --clean to vacuum; --prune-sessions DAYS to shrink the db")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/bin/tezgah-dsh

@@ -0,0 +1,37 @@
+#!/bin/sh
+# tezgah-dsh - launch the DeepSeek Harness (dsh) CLI installed under $DSH_HOME.
+#
+# dsh ships as node modules under <harness home>/profiles/node_modules, so there
+# is no PATH command unless one is created. tezgah-setup symlinks ~/.local/bin/dsh
+# to this wrapper; the wrapper resolves the CLI so the symlink survives a version
+# change. Arguments are passed through untouched (e.g. --profile web|headless).
+#
+# dsh boots its hooks under a workspace-write sandbox that confines hook
+# subprocesses to the workspace plus the platform temp dir. The graph index
+# worker writes `.codegraph/` inside the repository and the CLI it calls wants a
+# writable cache of its own, which that sandbox denies for a repo dsh has never
+# seen; without the warm-up below such a repo would never get indexed from the
+# hook. The launcher runs in the user's shell, unconfined, so it starts the same
+# worker the hooks use - HEAD-stamped, so it is a no-op when the graph is current.
+set -eu
+DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
+BIN="$DSH_HOME/profiles/node_modules/@deepseek-ai/dsh/lib/bin.js"
+INDEX="${TEZGAH_INDEX_BIN:-$HOME/.config/tezgah/bin/tezgah-index}"
+warm_index() {
+    if [ -x "$INDEX" ]; then
+        "$INDEX" "$PWD" >/dev/null 2>&1 || true
+    fi
+}
+if [ -f "$BIN" ]; then
+    warm_index
+    exec node "$BIN" "$@"
+fi
+# A fresh machine has no profile tree yet; npx runs dsh and materializes
+# $DSH_HOME, so the host works before the first explicit `dsh web` boot.
+if command -v npx >/dev/null 2>&1; then
+    warm_index
+    exec npx -y @deepseek-ai/dsh "$@"
+fi
+echo "tezgah-dsh: dsh CLI not found at $BIN" >&2
+echo "tezgah-dsh: install the DeepSeek Harness (npx -y @deepseek-ai/dsh) or set DSH_HOME" >&2
+exit 127

package/bin/tezgah-dsh.cmd

@@ -0,0 +1,70 @@
+@echo off
+rem tezgah-dsh.cmd - launch the DeepSeek Harness (dsh) CLI on Windows.
+rem
+rem The Windows twin of bin/tezgah-dsh, the /bin/sh wrapper: a machine with no
+rem sh cannot start that file, so tezgah-setup copies this one to
+rem ~/.local/bin/dsh.cmd, the name cmd.exe resolves through PATHEXT. Everything
+rem below is resolved absolutely - the CLI under the profile home and the index
+rem farm under the config dir - so the copy works from anywhere. Arguments are
+rem passed through untouched.
+rem
+rem dsh boots its hooks under a workspace-write sandbox that confines hook
+rem subprocesses to the workspace plus the platform temp dir. The graph index
+rem worker writes .codegraph/ inside the repository and the CLI it calls wants a
+rem writable cache of its own, which that sandbox denies for a repo dsh has
+rem never seen; without the warm-up below such a repo would never get indexed
+rem from the hook. The launcher runs in the user's shell, unconfined, so it
+rem starts the same worker the hooks use - HEAD-stamped, so it is a no-op when
+rem the graph is current.
+setlocal
+
+rem The profile home defaults to the place the sh launcher's ${DSH_HOME:-...}
+rem resolves to, so both twins find one tree.
+if not defined DSH_HOME set "DSH_HOME=%USERPROFILE%\.dsh"
+set "BIN=%DSH_HOME%\profiles\node_modules\@deepseek-ai\dsh\lib\bin.js"
+
+if exist "%BIN%" goto dsh_cli
+where npx >nul 2>nul
+if errorlevel 1 goto no_cli
+
+rem A fresh machine has no profile tree yet; npx runs dsh and materializes the
+rem profile home, so the host works before the first explicit dsh web boot.
+call :warm
+rem cmd.exe has no exec, so the launcher waits for the CLI and returns its own
+rem exit code, which is what a caller scripts against.
+npx -y @deepseek-ai/dsh %*
+exit /b %errorlevel%
+
+:dsh_cli
+call :warm
+node "%BIN%" %*
+exit /b %errorlevel%
+
+:no_cli
+echo tezgah-dsh: dsh CLI not found at %BIN% 1>&2
+echo tezgah-dsh: install the DeepSeek Harness (npx -y @deepseek-ai/dsh) or set DSH_HOME 1>&2
+exit /b 127
+
+:warm
+rem Best effort, as in the sh twin: a machine that cannot start the worker
+rem still starts dsh. The farm entry is a Python script
+rem (a relay where a symlink was refused), so it is started the way
+rem hooks/tezgah_paths.python_cmd resolves an interpreter: the pin first, then
+rem the names Windows ships - python3 is never one of them - and py last.
+set "CONFIG=%XDG_CONFIG_HOME%"
+if not defined CONFIG set "CONFIG=%USERPROFILE%\.config"
+set "INDEX=%TEZGAH_INDEX_BIN%"
+if not defined INDEX set "INDEX=%CONFIG%\tezgah\bin\tezgah-index"
+if not exist "%INDEX%" exit /b 0
+set "PY=%TEZGAH_PYTHON%"
+if defined PY goto warm_run
+where python3 >nul 2>nul && set "PY=python3"
+if defined PY goto warm_run
+where python >nul 2>nul && set "PY=python"
+if defined PY goto warm_run
+where py >nul 2>nul && set "PY=py"
+if not defined PY exit /b 0
+
+:warm_run
+"%PY%" "%INDEX%" "%CD%" >nul 2>nul
+exit /b 0

package/bin/tezgah-gate

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""tezgah-gate - the gate's decision, for a host that is not Python.
+
+  tezgah-gate check    one call on stdin, its deny reason on stdout (if any);
+                       a dry run: nothing is written anywhere
+  tezgah-gate decide   the same answer, recorded the way the live gate records
+                       it (deny/drift/nudge rows, the pre-write snapshot)
+  tezgah-gate replay   the real ledgers replayed through this gate in a sandbox
+                       HOME, with per-stratum fidelity; `--report` reads labels,
+                       `--sheet` draws the blind label sample (hooks/tezgah_replay.py)
+
+Reads the host's own call as {"tool":..., "input":{...}, "cwd":...,
+"session_id":...} and prints what hooks/tezgah_gate.decision() returns for it,
+or nothing when the call passes. A host whose plugin is written in another
+language (opencode's tezgah.js) asks `decide` instead of mirroring a rule: that
+mirror is documented as incomplete and divergent, so a new rule reaches such a
+host through the core rather than through a second implementation of it that
+drifts. `check` is what a person or the MCP `tezgah_gate_check` tool asks: a
+dry run against a live session id used to write refusal rows into that
+session's counters (audit CHAT-07 / L-14b).
+
+Exit codes: 0 whether the call passes or is refused - the reason is the output,
+not the status - 2 for misuse, and 3 from `check` when the gate's core cannot
+be imported: an empty answer there would read as a pass (`decide`, opencode's
+hook path, fails open with 0 like every hook).
+"""
+import json
+import os
+import sys
+
+HERE = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
+sys.path.insert(0, os.path.join(HERE, "hooks"))
+from tezgah_guard import import_failed  # noqa: E402
+try:
+    from tezgah_gate import decision  # noqa: E402
+except Exception as exc:
+    # `check` is asked for a verdict (by a person, or the MCP `gate_check`
+    # tool): an empty answer with exit 0 reads as a pass from a gate that is
+    # not there. `decide` is opencode's hook path and fails open like the rest.
+    import_failed(exc, 3 if sys.argv[1:2] == ["check"] else 0)
+
+
+def misuse(message):
+    print("tezgah-gate: %s" % message, file=sys.stderr)
+    return 2
+
+
+def main(argv):
+    if len(argv) < 2:
+        print(__doc__, file=sys.stderr)
+        return 2
+    if argv[1] == "replay":
+        import tezgah_replay
+        return tezgah_replay.main(argv[2:])
+    if argv[1] not in ("check", "decide"):
+        return misuse("unknown command %r (check, decide, replay)" % argv[1])
+    if len(argv) > 2:
+        return misuse("check reads its call on stdin, not as arguments")
+    try:
+        payload = json.load(sys.stdin)
+    except ValueError:
+        return misuse("stdin is not one JSON object")
+    if not isinstance(payload, dict):
+        return misuse("stdin must be one JSON object")
+    inp = payload.get("input")
+    reason = decision(payload.get("tool"), inp if isinstance(inp, dict) else {},
+                      payload.get("cwd") or os.getcwd(),
+                      payload.get("session_id"), record=argv[1] == "decide")
+    if reason:
+        sys.stdout.write(reason if reason.endswith("\n") else reason + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))