stallguard 0.1.0__tar.gz

stallguard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stallguard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stallguard-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: stallguard
+Version: 0.1.0
+Summary: Drop-in wrapper that streams agent steps and kills/flags stalls, loops, and fake-GOAL finishes.
+License: MIT
+Project-URL: Homepage, https://github.com/gpt4omni/stallguard
+Keywords: ai-agents,llm,coding-assistant,devtools,cli
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# stallguard
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](pyproject.toml)
+[![No dependencies](https://img.shields.io/badge/deps-zero-brightgreen.svg)](stallguard/)
+[![CI](https://github.com/gpt4omni/stallguard/actions/workflows/test.yml/badge.svg)](https://github.com/gpt4omni/stallguard/actions/workflows/test.yml)
+
+**Your coding agent says "done". Did it do anything?** stallguard is a drop-in
+wrapper that streams agent steps, kills stalls and retry-loops, and flags
+fake-GOAL finishes — with a shareable trace for every run.
+
+![stallguard demo](demo.gif)
+
+```bash
+pipx install stallguard
+stallguard run -- npx claude-code "fix the login bug"
+# [stallguard] status=ok exit=0 duration=42.1s trace=traces/stallguard-....html
+```
+
+No code changes. Just prefix your agent command with `stallguard run --`.
+
+## The problem
+
+AI coding agents fail in three boring, expensive ways:
+
+1. **Stalls** — no output for 20 minutes while your CI minute-burn ticks.
+2. **Loops** — the same tool call retried 500 times (`retrying with same args...`).
+3. **Fake-GOALs** — prints `DONE ✅` while `git diff` is empty.
+
+Logs scroll by, nobody watches, green checkmarks lie. stallguard turns each run
+into a verdict: `ok`, `error`, `stalled`, `looped`, or `fake-goal` — enforced
+by exit code, so CI can act on it.
+
+## 30-second quickstart
+
+```bash
+# any agent, any command — just prefix it
+stallguard run -- python -u your_agent.py
+stallguard run --stall-timeout 90 --require-diff -- ./run.sh
+
+# inspect a run later
+stallguard view traces/stallguard-*.jsonl
+# open traces/stallguard-*.html in a browser for the full step-by-step trace
+```
+
+## What it catches
+
+| flag | default | catches | exit |
+|---|---|---|---|
+| `--stall-timeout N` | 120 | no output for N seconds → `SIGKILL` | 124 |
+| `--repeat-limit K` | 15 | K identical lines in a row → `SIGKILL` | 125 |
+| `--require-diff` | off | exit 0 + "done" text but empty `git diff` | 3 |
+| `--expect-file PATH` | — | required file missing after run (repeatable) | 3 |
+| `--trace-dir DIR` | `traces` | JSONL + summary JSON + self-contained HTML per run | — |
+
+`0` = ok, `1` = agent errored, `3` = fake-goal, `124` = stalled, `125` = looped.
+
+## Why not just `timeout`?
+
+`timeout 300 ./agent` kills a hung run but tells you nothing: was it a stall, a
+loop, or nearly done? And it can't catch the worst case — the agent that
+finishes fast, prints success, and changed zero files. stallguard records
+*timestamped evidence* for every run and verifies the goal actually happened.
+
+## CI: fail on fake success
+
+```yaml
+- name: Run agent under stallguard
+  run: stallguard run --stall-timeout 300 --require-diff -- ./run-agent.sh
+- name: Upload traces
+  uses: actions/upload-artifact@v4
+  with:
+    name: stallguard-traces
+    path: traces/
+```
+
+Or use the bundled composite action (see [action.yml](action.yml)).
+Every failed run links its HTML trace — debugging starts from evidence, not
+from re-running and hoping.
+
+## Works with any agent
+
+`stallguard` sees stdout, not APIs, so it works with everything:
+Claude Code, Codex CLI, OpenHands, AutoGPT, your own Python script — if it
+prints steps, stallguard can supervise it. Zero dependencies, stdlib only.
+
+## Dev
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .
+python -m stallguard run -- python -u examples/ok.py
+python -m stallguard run --stall-timeout 1 -- python -u examples/hang.py; echo $?
+python -m stallguard run --repeat-limit 3 -- python -u examples/loop.py; echo $?
+python -m unittest discover -s tests
+```
+
+## Roadmap
+
+- [ ] Token/step budgets (`--max-lines`, `--max-minutes`)
+- [ ] Semantic loop detection (same tool call, different formatting)
+- [ ] Live web dashboard for parallel agent fleets
+- [ ] PyPI release + Homebrew formula
+
+PRs welcome — especially real traces of agents failing in new and creative ways.
+
+MIT. If stallguard caught your agent slacking, leave a ⭐.

stallguard-0.1.0/README.md

@@ -0,0 +1,107 @@
+# stallguard
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](pyproject.toml)
+[![No dependencies](https://img.shields.io/badge/deps-zero-brightgreen.svg)](stallguard/)
+[![CI](https://github.com/gpt4omni/stallguard/actions/workflows/test.yml/badge.svg)](https://github.com/gpt4omni/stallguard/actions/workflows/test.yml)
+
+**Your coding agent says "done". Did it do anything?** stallguard is a drop-in
+wrapper that streams agent steps, kills stalls and retry-loops, and flags
+fake-GOAL finishes — with a shareable trace for every run.
+
+![stallguard demo](demo.gif)
+
+```bash
+pipx install stallguard
+stallguard run -- npx claude-code "fix the login bug"
+# [stallguard] status=ok exit=0 duration=42.1s trace=traces/stallguard-....html
+```
+
+No code changes. Just prefix your agent command with `stallguard run --`.
+
+## The problem
+
+AI coding agents fail in three boring, expensive ways:
+
+1. **Stalls** — no output for 20 minutes while your CI minute-burn ticks.
+2. **Loops** — the same tool call retried 500 times (`retrying with same args...`).
+3. **Fake-GOALs** — prints `DONE ✅` while `git diff` is empty.
+
+Logs scroll by, nobody watches, green checkmarks lie. stallguard turns each run
+into a verdict: `ok`, `error`, `stalled`, `looped`, or `fake-goal` — enforced
+by exit code, so CI can act on it.
+
+## 30-second quickstart
+
+```bash
+# any agent, any command — just prefix it
+stallguard run -- python -u your_agent.py
+stallguard run --stall-timeout 90 --require-diff -- ./run.sh
+
+# inspect a run later
+stallguard view traces/stallguard-*.jsonl
+# open traces/stallguard-*.html in a browser for the full step-by-step trace
+```
+
+## What it catches
+
+| flag | default | catches | exit |
+|---|---|---|---|
+| `--stall-timeout N` | 120 | no output for N seconds → `SIGKILL` | 124 |
+| `--repeat-limit K` | 15 | K identical lines in a row → `SIGKILL` | 125 |
+| `--require-diff` | off | exit 0 + "done" text but empty `git diff` | 3 |
+| `--expect-file PATH` | — | required file missing after run (repeatable) | 3 |
+| `--trace-dir DIR` | `traces` | JSONL + summary JSON + self-contained HTML per run | — |
+
+`0` = ok, `1` = agent errored, `3` = fake-goal, `124` = stalled, `125` = looped.
+
+## Why not just `timeout`?
+
+`timeout 300 ./agent` kills a hung run but tells you nothing: was it a stall, a
+loop, or nearly done? And it can't catch the worst case — the agent that
+finishes fast, prints success, and changed zero files. stallguard records
+*timestamped evidence* for every run and verifies the goal actually happened.
+
+## CI: fail on fake success
+
+```yaml
+- name: Run agent under stallguard
+  run: stallguard run --stall-timeout 300 --require-diff -- ./run-agent.sh
+- name: Upload traces
+  uses: actions/upload-artifact@v4
+  with:
+    name: stallguard-traces
+    path: traces/
+```
+
+Or use the bundled composite action (see [action.yml](action.yml)).
+Every failed run links its HTML trace — debugging starts from evidence, not
+from re-running and hoping.
+
+## Works with any agent
+
+`stallguard` sees stdout, not APIs, so it works with everything:
+Claude Code, Codex CLI, OpenHands, AutoGPT, your own Python script — if it
+prints steps, stallguard can supervise it. Zero dependencies, stdlib only.
+
+## Dev
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .
+python -m stallguard run -- python -u examples/ok.py
+python -m stallguard run --stall-timeout 1 -- python -u examples/hang.py; echo $?
+python -m stallguard run --repeat-limit 3 -- python -u examples/loop.py; echo $?
+python -m unittest discover -s tests
+```
+
+## Roadmap
+
+- [ ] Token/step budgets (`--max-lines`, `--max-minutes`)
+- [ ] Semantic loop detection (same tool call, different formatting)
+- [ ] Live web dashboard for parallel agent fleets
+- [ ] PyPI release + Homebrew formula
+
+PRs welcome — especially real traces of agents failing in new and creative ways.
+
+MIT. If stallguard caught your agent slacking, leave a ⭐.

stallguard-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stallguard"
+version = "0.1.0"
+description = "Drop-in wrapper that streams agent steps and kills/flags stalls, loops, and fake-GOAL finishes."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["ai-agents", "llm", "coding-assistant", "devtools", "cli"]
+
+[project.urls]
+Homepage = "https://github.com/gpt4omni/stallguard"
+
+[project.scripts]
+stallguard = "stallguard.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["stallguard*"]

stallguard-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stallguard-0.1.0/stallguard/__init__.py

@@ -0,0 +1,5 @@
+"""stallguard: trace agent runs, kill stalls/loops, verify real progress."""
+from .tracer import run_command, RunConfig, RunResult
+
+__all__ = ["run_command", "RunConfig", "RunResult"]
+__version__ = "0.1.0"

stallguard-0.1.0/stallguard/__main__.py

@@ -0,0 +1,4 @@
+from stallguard.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

stallguard-0.1.0/stallguard/cli.py

@@ -0,0 +1,75 @@
+"""CLI: stallguard run -- <cmd>  |  stallguard view <trace.jsonl>"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .tracer import RunConfig, run_command
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="stallguard", description="Trace agent runs; kill stalls/loops; verify real progress.")
+    sub = p.add_subparsers(dest="sub")
+
+    r = sub.add_parser("run", help="run a command under supervision")
+    r.add_argument("--stall-timeout", type=float, default=120, help="kill if no output for N seconds (default 120)")
+    r.add_argument("--repeat-limit", type=int, default=15, help="kill after K identical lines in a row (default 15)")
+    r.add_argument("--require-diff", action="store_true", help="exit!=0-style flag when git diff is empty on success")
+    r.add_argument("--expect-file", action="append", default=[], help="file that must exist after run (repeatable)")
+    r.add_argument("--trace-dir", default="traces", help="where to write traces (default traces/)")
+    r.add_argument("--label", default="", help="label stored in summary")
+    r.add_argument("cmd", nargs=argparse.REMAINDER, help="command after --")
+    # allow `stallguard -- cmd` shorthand: handled in main()
+    v = sub.add_parser("view", help="print summary for a trace")
+    v.add_argument("trace", help="path to .jsonl or .summary.json")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args_in = sys.argv[1:] if argv is None else argv
+    # shorthand: stallguard -- <cmd>  /  stallguard --stall-timeout 5 -- <cmd>
+    if args_in[:1] == ["--"] or (args_in and "run" not in args_in and "view" not in args_in and "-h" not in args_in and "--help" not in args_in):
+        args_in = ["run"] + args_in
+    p = build_parser()
+    args = p.parse_args(args_in)
+    if args.sub == "view":
+        path = args.trace
+        if path.endswith(".summary.json"):
+            print(open(path, encoding="utf-8").read())
+        else:
+            summ = path.replace(".jsonl", ".summary.json")
+            try:
+                print(open(summ, encoding="utf-8").read())
+            except FileNotFoundError:
+                print(json.dumps({"error": f"no summary at {summ}"}, indent=2))
+                return 1
+        return 0
+    if args.sub != "run":
+        p.print_help()
+        return 2
+    cmd = args.cmd
+    if cmd[:1] == ["--"]:
+        cmd = cmd[1:]
+    if not cmd:
+        print("usage: stallguard run [--stall-timeout N] [--require-diff] -- <command...>", file=sys.stderr)
+        return 2
+    cfg = RunConfig(
+        cmd=cmd,
+        stall_timeout=args.stall_timeout,
+        repeat_limit=args.repeat_limit,
+        require_diff=args.require_diff,
+        expect_files=args.expect_file,
+        trace_dir=args.trace_dir,
+        label=args.label,
+    )
+    res = run_command(cfg)
+    exit_disp = "killed" if res.exit_code is not None and res.exit_code < 0 else res.exit_code
+    print(f"\n[stallguard] status={res.status} exit={exit_disp} "
+          f"duration={res.duration_s:.1f}s trace={res.trace_jsonl}", flush=True)
+    code = 0 if res.status == "ok" else {"error": 1, "fake-goal": 3, "stalled": 124, "looped": 125}.get(res.status, 1)
+    return code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

stallguard-0.1.0/stallguard/detectors.py

@@ -0,0 +1,24 @@
+"""Stall/loop detectors (stdlib only)."""
+from __future__ import annotations
+
+
+class LoopDetector:
+    """Flags K consecutive identical lines (agent stuck in a retry loop)."""
+
+    def __init__(self, repeat_limit: int = 15):
+        self.repeat_limit = max(2, repeat_limit)
+        self._last: str | None = None
+        self._count = 0
+
+    def feed(self, line: str) -> str | None:
+        norm = " ".join(line.strip().split())
+        if not norm:
+            return None
+        if norm == self._last:
+            self._count += 1
+        else:
+            self._last = norm
+            self._count = 1
+        if self._count >= self.repeat_limit:
+            return f"line repeated {self._count}x: {norm[:160]}"
+        return None

stallguard-0.1.0/stallguard/goalcheck.py

@@ -0,0 +1,53 @@
+"""GOAL verification: did the agent actually change anything?"""
+from __future__ import annotations
+
+import subprocess
+
+
+def git_changed_files(cwd: str) -> list[str]:
+    """All working-tree changes: staged, unstaged, AND untracked new files."""
+    try:
+        out = subprocess.run(
+            ["git", "status", "--porcelain"],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        if out.returncode != 0:
+            return []
+        files = []
+        for line in out.stdout.splitlines():
+            rest = line[3:] if len(line) > 3 else ""
+            if " -> " in rest:  # renames: "orig -> new"
+                rest = rest.split(" -> ")[-1]
+            rest = rest.strip().strip('"')
+            if rest:
+                files.append(rest)
+        return files
+    except Exception:
+        return []
+
+
+SUCCESS_TOKENS = ("goal", "done", "complete", "success", "finished", "all tests pass")
+
+
+def check_goal(
+    exit_code: int,
+    output_text: str,
+    changed_files: list[str],
+    require_diff: bool,
+    expect_files: list[str],
+    missing: list[str],
+) -> tuple[bool, str]:
+    lowered = output_text.lower()
+    claims_success = any(tok in lowered for tok in SUCCESS_TOKENS)
+    if missing:
+        return False, f"missing expected files: {missing}"
+    if expect_files and not missing:
+        return True, "expected files present"
+    if require_diff and not changed_files and exit_code == 0:
+        if claims_success:
+            return False, "claimed success but git diff is empty"
+        return False, "require-diff: no changed files"
+    return True, "ok"

stallguard-0.1.0/stallguard/render.py

@@ -0,0 +1,36 @@
+"""Render a self-contained HTML trace report (no JS deps)."""
+from __future__ import annotations
+
+import html
+
+
+def write_html(path: str, summary: dict, events: list[dict]) -> None:
+    color = {
+        "ok": "#16a34a",
+        "error": "#dc2626",
+        "stalled": "#d97706",
+        "looped": "#d97706",
+        "fake-goal": "#9333ea",
+    }.get(summary.get("status", ""), "#555")
+    rows = []
+    for e in events[-2000:]:
+        rows.append(
+            f'<div class="ln"><span class="t">{e["t"]:>8.2f}s</span>'
+            f"<span>{html.escape(e['line']) or '&nbsp;'}</span></div>"
+        )
+    files = "".join(f"<li><code>{html.escape(f)}</code></li>" for f in summary.get("changed_files", [])) or "<li><i>none</i></li>"
+    page = f"""<!doctype html><html><head><meta charset="utf-8">
+<title>stallguard — {html.escape(str(summary.get('status')))}</title>
+<style>body{{font-family:ui-monospace,monospace;max-width:900px;margin:24px auto;padding:0 16px}}
+.badge{{display:inline-block;padding:2px 10px;border-radius:999px;color:#fff;background:{color}}}
+.ln{{display:flex;gap:12px;border-bottom:1px solid #eee;padding:2px 0;white-space:pre-wrap}}.t{{color:#888;min-width:70px}}</style>
+</head><body>
+<h1>stallguard trace</h1>
+<p><span class="badge">{html.escape(str(summary.get('status')))}</span>
+exit={html.escape(str(summary.get('exit_code')))} duration={html.escape(str(summary.get('duration_s')))}s</p>
+<p><code>{html.escape(' '.join(summary.get('cmd', [])))}</code></p>
+<h3>Changed files</h3><ul>{files}</ul>
+<h3>Log (last {len(rows)} lines)</h3>{''.join(rows)}
+</body></html>"""
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(page)

stallguard-0.1.0/stallguard/tracer.py

@@ -0,0 +1,199 @@
+"""Run a subprocess, stream output, detect stalls/loops, write trace files."""
+from __future__ import annotations
+
+import json
+import os
+import queue
+import subprocess
+import threading
+import time
+from dataclasses import dataclass, field
+
+from .detectors import LoopDetector
+from .goalcheck import git_changed_files, check_goal
+from .render import write_html
+
+
+@dataclass
+class RunConfig:
+    cmd: list[str]
+    cwd: str = "."
+    stall_timeout: float = 120.0
+    repeat_limit: int = 15
+    require_diff: bool = False
+    expect_files: list[str] = field(default_factory=list)
+    trace_dir: str = "traces"
+    label: str = ""
+
+
+@dataclass
+class RunResult:
+    status: str  # ok | error | stalled | looped | fake-goal
+    exit_code: int | None
+    duration_s: float
+    trace_jsonl: str
+    summary_json: str
+    report_html: str
+    changed_files: list[str] = field(default_factory=list)
+
+
+def _reader_thread(pipe, q: queue.Queue):
+    try:
+        for line in iter(pipe.readline, ""):
+            q.put(line)
+    finally:
+        try:
+            pipe.close()
+        except Exception:
+            pass
+        q.put(None)
+
+
+def run_command(cfg: RunConfig) -> RunResult:
+    os.makedirs(cfg.trace_dir, exist_ok=True)
+    stamp = time.strftime("%Y%m%d-%H%M%S")
+    base = os.path.join(cfg.trace_dir, f"stallguard-{stamp}")
+    trace_jsonl = base + ".jsonl"
+    summary_json = base + ".summary.json"
+    report_html = base + ".html"
+
+    before = git_changed_files(cfg.cwd)
+    start = time.monotonic()
+    wall_start = time.time()
+
+    proc = subprocess.Popen(
+        cfg.cmd,
+        cwd=cfg.cwd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        bufsize=1,
+    )
+    assert proc.stdout is not None
+    q: queue.Queue = queue.Queue()
+    t = threading.Thread(target=_reader_thread, args=(proc.stdout, q), daemon=True)
+    t.start()
+
+    loop = LoopDetector(repeat_limit=cfg.repeat_limit)
+    events = []
+    last_output = time.monotonic()
+    status = "ok"
+    exit_code: int | None = None
+    loop_hit: str | None = None
+
+    with open(trace_jsonl, "w", encoding="utf-8") as f:
+        alive = True
+        while alive:
+            try:
+                line = q.get(timeout=0.2)
+            except queue.Empty:
+                line = None
+            now = time.monotonic()
+            if line is None:
+                if proc.poll() is not None and q.empty():
+                    alive = False
+                elif now - last_output > cfg.stall_timeout:
+                    status = "stalled"
+                    proc.kill()
+                    try:
+                        proc.wait(timeout=5)
+                    except Exception:
+                        pass
+                    alive = False
+                continue
+            if line is None:  # sentinel
+                if proc.poll() is not None:
+                    # drain check done on next loop
+                    continue
+                continue
+            # real output line
+            last_output = now
+            ts = time.time() - wall_start
+            ev = {"t": round(ts, 3), "stream": "stdout", "line": line.rstrip("\n")}
+            events.append(ev)
+            f.write(json.dumps(ev) + "\n")
+            f.flush()
+            print(line, end="", flush=True)
+            hit = loop.feed(ev["line"])
+            if hit is not None:
+                loop_hit = hit
+                status = "looped"
+                proc.kill()
+                try:
+                    proc.wait(timeout=5)
+                except Exception:
+                    pass
+                alive = False
+
+        exit_code = proc.poll()
+        if exit_code is None:
+            try:
+                exit_code = proc.wait(timeout=5)
+            except Exception:
+                exit_code = None
+
+    duration_s = time.monotonic() - start
+    after = git_changed_files(cfg.cwd)
+    changed = sorted(set(after) - set(before))
+    # stallguard's own traces are evidence, not agent progress:
+    # exclude the trace dir prefix AND our exact trace basenames
+    # (covers --trace-dir pointing at the repo root itself)
+    td = os.path.relpath(os.path.abspath(cfg.trace_dir), os.path.abspath(cfg.cwd))
+    own = {
+        os.path.basename(trace_jsonl),
+        os.path.basename(summary_json),
+        os.path.basename(report_html),
+    }
+    changed = [
+        f
+        for f in changed
+        if os.path.basename(f) not in own
+        and f != td
+        and not f.startswith(td + os.sep)
+    ]
+
+    # expect_files are relative to cwd; check existence
+    missing = [p for p in cfg.expect_files if not os.path.exists(os.path.join(cfg.cwd, p))]
+
+    if status == "ok":
+        if exit_code not in (0, None):
+            status = "error"
+        else:
+            goal_ok, reason = check_goal(
+                exit_code=exit_code or 0,
+                output_text="\n".join(e["line"] for e in events[-50:]),
+                changed_files=changed,
+                require_diff=cfg.require_diff,
+                expect_files=cfg.expect_files,
+                missing=missing,
+            )
+            if not goal_ok:
+                status = "fake-goal"
+
+    summary = {
+        "label": cfg.label,
+        "cmd": cfg.cmd,
+        "status": status,
+        "exit_code": exit_code,
+        "duration_s": round(duration_s, 2),
+        "stall_timeout": cfg.stall_timeout,
+        "repeat_limit": cfg.repeat_limit,
+        "changed_files": changed,
+        "loop_detail": loop_hit,
+        "trace": os.path.basename(trace_jsonl),
+        "require_diff": cfg.require_diff,
+        "expect_files": cfg.expect_files,
+    }
+    with open(summary_json, "w", encoding="utf-8") as f:
+        json.dump(summary, f, indent=2)
+    write_html(report_html, summary, events)
+
+    return RunResult(
+        status=status,
+        exit_code=exit_code,
+        duration_s=duration_s,
+        trace_jsonl=trace_jsonl,
+        summary_json=summary_json,
+        report_html=report_html,
+        changed_files=changed,
+    )

stallguard-0.1.0/stallguard.egg-info/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: stallguard
+Version: 0.1.0
+Summary: Drop-in wrapper that streams agent steps and kills/flags stalls, loops, and fake-GOAL finishes.
+License: MIT
+Project-URL: Homepage, https://github.com/gpt4omni/stallguard
+Keywords: ai-agents,llm,coding-assistant,devtools,cli
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# stallguard
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](pyproject.toml)
+[![No dependencies](https://img.shields.io/badge/deps-zero-brightgreen.svg)](stallguard/)
+[![CI](https://github.com/gpt4omni/stallguard/actions/workflows/test.yml/badge.svg)](https://github.com/gpt4omni/stallguard/actions/workflows/test.yml)
+
+**Your coding agent says "done". Did it do anything?** stallguard is a drop-in
+wrapper that streams agent steps, kills stalls and retry-loops, and flags
+fake-GOAL finishes — with a shareable trace for every run.
+
+![stallguard demo](demo.gif)
+
+```bash
+pipx install stallguard
+stallguard run -- npx claude-code "fix the login bug"
+# [stallguard] status=ok exit=0 duration=42.1s trace=traces/stallguard-....html
+```
+
+No code changes. Just prefix your agent command with `stallguard run --`.
+
+## The problem
+
+AI coding agents fail in three boring, expensive ways:
+
+1. **Stalls** — no output for 20 minutes while your CI minute-burn ticks.
+2. **Loops** — the same tool call retried 500 times (`retrying with same args...`).
+3. **Fake-GOALs** — prints `DONE ✅` while `git diff` is empty.
+
+Logs scroll by, nobody watches, green checkmarks lie. stallguard turns each run
+into a verdict: `ok`, `error`, `stalled`, `looped`, or `fake-goal` — enforced
+by exit code, so CI can act on it.
+
+## 30-second quickstart
+
+```bash
+# any agent, any command — just prefix it
+stallguard run -- python -u your_agent.py
+stallguard run --stall-timeout 90 --require-diff -- ./run.sh
+
+# inspect a run later
+stallguard view traces/stallguard-*.jsonl
+# open traces/stallguard-*.html in a browser for the full step-by-step trace
+```
+
+## What it catches
+
+| flag | default | catches | exit |
+|---|---|---|---|
+| `--stall-timeout N` | 120 | no output for N seconds → `SIGKILL` | 124 |
+| `--repeat-limit K` | 15 | K identical lines in a row → `SIGKILL` | 125 |
+| `--require-diff` | off | exit 0 + "done" text but empty `git diff` | 3 |
+| `--expect-file PATH` | — | required file missing after run (repeatable) | 3 |
+| `--trace-dir DIR` | `traces` | JSONL + summary JSON + self-contained HTML per run | — |
+
+`0` = ok, `1` = agent errored, `3` = fake-goal, `124` = stalled, `125` = looped.
+
+## Why not just `timeout`?
+
+`timeout 300 ./agent` kills a hung run but tells you nothing: was it a stall, a
+loop, or nearly done? And it can't catch the worst case — the agent that
+finishes fast, prints success, and changed zero files. stallguard records
+*timestamped evidence* for every run and verifies the goal actually happened.
+
+## CI: fail on fake success
+
+```yaml
+- name: Run agent under stallguard
+  run: stallguard run --stall-timeout 300 --require-diff -- ./run-agent.sh
+- name: Upload traces
+  uses: actions/upload-artifact@v4
+  with:
+    name: stallguard-traces
+    path: traces/
+```
+
+Or use the bundled composite action (see [action.yml](action.yml)).
+Every failed run links its HTML trace — debugging starts from evidence, not
+from re-running and hoping.
+
+## Works with any agent
+
+`stallguard` sees stdout, not APIs, so it works with everything:
+Claude Code, Codex CLI, OpenHands, AutoGPT, your own Python script — if it
+prints steps, stallguard can supervise it. Zero dependencies, stdlib only.
+
+## Dev
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .
+python -m stallguard run -- python -u examples/ok.py
+python -m stallguard run --stall-timeout 1 -- python -u examples/hang.py; echo $?
+python -m stallguard run --repeat-limit 3 -- python -u examples/loop.py; echo $?
+python -m unittest discover -s tests
+```
+
+## Roadmap
+
+- [ ] Token/step budgets (`--max-lines`, `--max-minutes`)
+- [ ] Semantic loop detection (same tool call, different formatting)
+- [ ] Live web dashboard for parallel agent fleets
+- [ ] PyPI release + Homebrew formula
+
+PRs welcome — especially real traces of agents failing in new and creative ways.
+
+MIT. If stallguard caught your agent slacking, leave a ⭐.

stallguard-0.1.0/stallguard.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+stallguard/__init__.py
+stallguard/__main__.py
+stallguard/cli.py
+stallguard/detectors.py
+stallguard/goalcheck.py
+stallguard/render.py
+stallguard/tracer.py
+stallguard.egg-info/PKG-INFO
+stallguard.egg-info/SOURCES.txt
+stallguard.egg-info/dependency_links.txt
+stallguard.egg-info/entry_points.txt
+stallguard.egg-info/top_level.txt
+tests/test_stallguard.py

stallguard-0.1.0/stallguard.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

stallguard-0.1.0/stallguard.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+stallguard = stallguard.cli:main

stallguard-0.1.0/stallguard.egg-info/top_level.txt

@@ -0,0 +1 @@
+stallguard

stallguard-0.1.0/tests/test_stallguard.py

@@ -0,0 +1,79 @@
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+def run_stallguard(args, cwd):
+    env = dict(os.environ, PYTHONPATH=ROOT)
+    return subprocess.run(
+        [sys.executable, "-m", "stallguard"] + args,
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        timeout=60,
+        env=env,
+    )
+
+
+class TestStallguard(unittest.TestCase):
+    def test_ok(self):
+        with tempfile.TemporaryDirectory() as d:
+            p = run_stallguard(["run", "--trace-dir", d, "--", sys.executable, "-u", f"{ROOT}/examples/ok.py"], cwd=d)
+            self.assertEqual(p.returncode, 0, p.stderr + p.stdout)
+            self.assertIn("status=ok", p.stdout)
+
+    def test_loop_kill(self):
+        with tempfile.TemporaryDirectory() as d:
+            p = run_stallguard(["run", "--trace-dir", d, "--repeat-limit", "3", "--", sys.executable, "-u", f"{ROOT}/examples/loop.py"], cwd=d)
+            self.assertEqual(p.returncode, 125, p.stderr + p.stdout)
+            self.assertIn("status=looped", p.stdout)
+
+    def test_stall_kill(self):
+        with tempfile.TemporaryDirectory() as d:
+            p = run_stallguard(["run", "--trace-dir", d, "--stall-timeout", "1", "--", sys.executable, "-u", f"{ROOT}/examples/hang.py"], cwd=d)
+            self.assertEqual(p.returncode, 124, p.stderr + p.stdout)
+            self.assertIn("status=stalled", p.stdout)
+
+    def test_fake_goal_require_diff(self):
+        with tempfile.TemporaryDirectory() as d:
+            subprocess.run(["git", "init", "-q"], cwd=d, check=True)
+            code = "print('GOAL done success', flush=True)"
+            p = run_stallguard(["run", "--trace-dir", d, "--require-diff", "--", sys.executable, "-u", "-c", code], cwd=d)
+            self.assertEqual(p.returncode, 3, p.stderr + p.stdout)
+            self.assertIn("status=fake-goal", p.stdout)
+
+    def test_new_untracked_file_counts_as_progress(self):
+        with tempfile.TemporaryDirectory() as d:
+            subprocess.run(["git", "init", "-q"], cwd=d, check=True)
+            code = "open('out.txt','w').write('x'); print('GOAL done', flush=True)"
+            p = run_stallguard(["run", "--trace-dir", d, "--require-diff", "--", sys.executable, "-u", "-c", code], cwd=d)
+            self.assertEqual(p.returncode, 0, p.stderr + p.stdout)
+            self.assertIn("status=ok", p.stdout)
+
+    def test_own_traces_dont_count_as_progress(self):
+        with tempfile.TemporaryDirectory() as d:
+            subprocess.run(["git", "init", "-q"], cwd=d, check=True)
+            code = "print('GOAL done success', flush=True)"
+            p = run_stallguard(["run", "--trace-dir", d, "--require-diff", "--", sys.executable, "-u", "-c", code], cwd=d)
+            self.assertEqual(p.returncode, 3, p.stderr + p.stdout)
+
+    def test_trace_files_written(self):
+        with tempfile.TemporaryDirectory() as d:
+            run_stallguard(["run", "--trace-dir", d, "--", sys.executable, "-u", f"{ROOT}/examples/ok.py"], cwd=d)
+            names = os.listdir(d)
+            self.assertTrue(any(n.endswith(".jsonl") for n in names))
+            self.assertTrue(any(n.endswith(".summary.json") for n in names))
+            self.assertTrue(any(n.endswith(".html") for n in names))
+            summ = [n for n in names if n.endswith(".summary.json")][0]
+            with open(os.path.join(d, summ), encoding="utf-8") as fh:
+                data = json.load(fh)
+            self.assertEqual(data["status"], "ok")
+
+
+if __name__ == "__main__":
+    unittest.main()