graphban-cli 0.8.6__tar.gz → 0.8.8__tar.gz

{graphban_cli-0.8.6 → graphban_cli-0.8.8}/.gitignore

@@ -30,6 +30,7 @@ fleet/.pytest_cache/
 # never committed: a CI push to protected main is refused and turns main red (GRPH-1185).
 backend/app/data/refusal_coverage.json
 backend/app/data/gban_skills.json
+backend/app/data/playbooks.json
 
 # Node
 web/node_modules/

{graphban_cli-0.8.6 → graphban_cli-0.8.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: graphban-cli
-Version: 0.8.6
+Version: 0.8.8
 Summary: gban — a Graphban client for the human at a terminal
 Project-URL: Homepage, https://github.com/asc-me/graphban
 Project-URL: Repository, https://github.com/asc-me/graphban

{graphban_cli-0.8.6 → graphban_cli-0.8.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "graphban-cli"
-version = "0.8.6"
+version = "0.8.8"
 description = "gban — a Graphban client for the human at a terminal"
 readme = "README.md"
 requires-python = ">=3.12"

{graphban_cli-0.8.6 → graphban_cli-0.8.8}/src/gban/cli.py

@@ -16,7 +16,7 @@ import sys
 import time
 from pathlib import Path
 
-from gban import config, doctor as doctor_mod, machine as machine_mod, setup as setup_mod, stackmap, swamp as swamp_mod
+from gban import config, doctor as doctor_mod, machine as machine_mod, playbooks, setup as setup_mod, stackmap, swamp as swamp_mod
 from gban.client import (EXIT_NO_SESSION, EXIT_NO_SUPERVISOR, EXIT_REFUSED, EXIT_UNREACHABLE,
                        Client, NoSession,
                        Refused, Unreachable, authenticated, login, pair_poll,
@@ -51,6 +51,7 @@ def _parser() -> argparse.ArgumentParser:
         help=("sign in without typing a password here: prints a short code that a signed-in "
               "person approves in the web app's quick-start dialog"))
 
+    sub.add_parser("update", help="poll the deployment now and refresh the agent files")
     sub.add_parser("logout", help="end the session, here and on the server")
     doctor_cmd = sub.add_parser(
         "doctor", help="check both halves: the ledger, and the local fleet",
@@ -370,6 +371,9 @@ def cmd_doctor(args) -> int:
     project = config.resolve(args.project, config.PROJECT_ENV, "project")
     api_key = doctor_mod.resolve_supervisor_key(project, url=url)
     lines, code = doctor_mod.run(url, project, api_key)
+    poll_line = doctor_mod.playbooks_line(getattr(args, "poll_result", None))
+    if poll_line:
+        lines.append(poll_line)
     if not getattr(args, "no_report", False):
         lines += machine_mod.send(url, project, lines)  # UNKNOWN when undelivered: exit unchanged
     _out({"lines": lines, "ok": code == 0}, doctor_mod.render(lines), args.as_json)
@@ -704,13 +708,46 @@ def cmd_keys(args) -> int:
     return 0
 
 
-COMMANDS = {"login": cmd_login, "logout": cmd_logout, "whoami": cmd_whoami,
+def cmd_update(args) -> int:
+    return 0  # the poll itself runs in main(), forced for this verb
+
+
+COMMANDS = {"update": cmd_update, "login": cmd_login, "logout": cmd_logout, "whoami": cmd_whoami,
             "doctor": cmd_doctor, "setup": cmd_setup, "fleet": cmd_fleet, "seats": cmd_seats,
             "agents": cmd_agents, "keys": cmd_keys, "swamp": cmd_swamp, "stack": cmd_stack}
 
 
+def _poll(args) -> None:
+    """The hourly poll every command rides. Never fails the command itself."""
+    if args.command == "logout":
+        return
+    url = config.resolve(args.server, config.URL_ENV, "url")
+    if not url:
+        return
+    try:
+        # The checkout root, not the cwd: from `cli/` the receipt and the pack still land at
+        # the top of the repository.
+        repo = playbooks.checkout(Path.cwd())
+        if repo is None:  # not in a checkout: there is nowhere the agent files belong
+            result = {"note": "not inside a git checkout; nothing to refresh"}
+        else:
+            project = config.resolve(args.project, config.PROJECT_ENV, "project")
+            result = playbooks.poll(url, repo, force=args.command == "update", project=project)
+    except Exception as exc:  # a poll must not break the verb the person typed
+        result = {"note": f"poll skipped: {exc}"}
+    args.poll_result = result
+    if args.command == "doctor":
+        return  # doctor reports it as its own line, saying whether it looked just now
+    if "polled" not in result and args.command != "update":
+        return  # nothing was checked; a non-update verb stays quiet about it
+    if args.command == "update" or not args.as_json:
+        print(f"{PROG}: {result['note']}",
+              file=sys.stdout if args.command == "update" else sys.stderr)
+
+
 def main(argv: list[str] | None = None) -> int:
     args = _parser().parse_args(argv)
+    _poll(args)
     try:
         return COMMANDS[args.command](args)
     except NoSession as exc:

{graphban_cli-0.8.6 → graphban_cli-0.8.8}/src/gban/doctor.py

@@ -392,6 +392,22 @@ def child_environment(api_key: str) -> dict:
     return env
 
 
+def playbooks_line(result: dict | None) -> dict | None:
+    """The hourly poll as one finding (GRPH-P65).
+
+    A fresh stamp means nothing was asked of the server: the line gives the stored poll time
+    and sha and is UNKNOWN, never a PASS — a skipped poll reported as a clean check is the bug.
+    """
+    if not result:
+        return None
+    note = result.get("note", "")
+    if result.get("skipped"):
+        return _line("local", UNKNOWN, "playbooks", f"not checked now — {note}")
+    if result.get("failed") or "polled" not in result:
+        return _line("local", UNKNOWN, "playbooks", note)
+    return _line("local", PASS, "playbooks", f"polled just now — {note}")
+
+
 def run(url: str, project: str, api_key: str = "",
         repo: Path | None = None) -> tuple[list[dict], int]:
     lines = (ledger(url, project) + local(url, project, api_key)

{graphban_cli-0.8.6 → graphban_cli-0.8.8}/src/gban/gitignore.py

@@ -36,6 +36,7 @@ PATTERNS = (
     ".gbfleet-*",
     ".swamp/",
     "graphban-swamp/",
+    ".graphban/playbooks.json",
 )
 
 #: What we ASK git about. A glob is not a path; these are the files that would be

graphban_cli-0.8.8/src/gban/playbooks.py

@@ -0,0 +1,217 @@
+"""The hourly poll that refreshes the agent files from the deployment (GRPH-P65).
+
+Every `gban` command may poll `/health`; `gban update` always does. The receipt
+`.graphban/playbooks.json` (gitignored) holds `polled_at` (Unix seconds), the server URL, the
+`git_sha` last applied, and the sha256 of every file this tool wrote.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import subprocess  # nosec B404
+import time
+from collections.abc import Callable
+from pathlib import Path
+
+from gban import config
+from gban.client import Client, NoSession, Refused, Unreachable, authenticated
+
+RECEIPT = Path(".graphban") / "playbooks.json"
+INTERVAL = 3600
+#: A `skill` entry is published once, under `.claude/skills/<slug>/SKILL.md`; every harness
+#: reads its own directory (`gbagent` reads all three), so the client writes it to each.
+SKILL_DIRS = (".claude/skills", ".grok/skills", ".agents/skills")
+
+
+def targets(entry: dict) -> list[str]:
+    """Every checkout path one pack entry is written to."""
+    rel = entry.get("path")
+    if entry.get("kind") == "skill" and isinstance(rel, str):
+        for base in SKILL_DIRS:
+            if rel.startswith(base + "/"):
+                tail = rel[len(base) + 1:]
+                return [f"{b}/{tail}" for b in SKILL_DIRS]
+    return [rel]
+
+
+def _write(dest: Path, data: bytes) -> None:
+    """Whole file or nothing: a `gbagent` child spawned mid-apply never reads half a body."""
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    tmp = dest.with_name(dest.name + ".gban-tmp")
+    tmp.write_bytes(data)
+    os.replace(tmp, dest)
+
+
+def _read(repo: Path) -> dict:
+    try:
+        loaded = json.loads((repo / RECEIPT).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    return loaded if isinstance(loaded, dict) else {}
+
+
+def _save(repo: Path, receipt: dict) -> None:
+    path = repo / RECEIPT
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(receipt, indent=1, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def _sha(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def when(ts: float) -> str:
+    return time.strftime("%Y-%m-%d %H:%M:%SZ", time.gmtime(ts))
+
+
+def checkout(start: Path) -> Path | None:
+    """The git toplevel containing `start`, or None outside a checkout.
+
+    The receipt and every pack path are relative to the checkout root, so running `gban`
+    from `cli/` must not plant `.graphban/` and the skills under `cli/`.
+    """
+    try:
+        proc = subprocess.run(  # nosec B603 B607
+            ["git", "-C", str(start), "rev-parse", "--show-toplevel"],
+            capture_output=True, text=True, timeout=30, check=False)
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    top = (proc.stdout or "").strip()
+    return Path(top) if proc.returncode == 0 and top else None
+
+
+def credentialed(url: str, project: str = "") -> Client:
+    """A client that may read `/api/playbooks`: the `gban login` session, else the API key
+    (`$GRAPHBAN_API_KEY`, then the key `gban setup` stored for this project).
+
+    Raises `NoSession` when there is none. `/health` stays unauthenticated; only the pack,
+    which carries the bodies, needs this.
+    """
+    try:
+        return authenticated(url, act="update")
+    except NoSession:
+        key = (os.environ.get(config.API_KEY_ENV) or "").strip() \
+            or config.stored_supervisor_key(project)
+        if not key:
+            raise
+        return Client(url, api_key=key)
+
+
+def poll(url: str, repo: Path, *, force: bool = False, client: Client | None = None,
+         auth: Callable[[], Client] | None = None, project: str = "",
+         now: float | None = None) -> dict:
+    """One poll decision. Returns `{"polled": bool, "note": str, ...}`; never raises for an
+    unreachable or unreadable `/health` (that leaves `polled_at` alone).
+
+    `client` reads `/health`, which needs no credential. `auth` builds the client for the
+    pack, which does: by default the `gban login` session or the stored API key.
+    """
+    now = time.time() if now is None else now
+    url = url.rstrip("/")
+    receipt = _read(repo)
+    polled_at = receipt.get("polled_at")
+    if (not force and isinstance(polled_at, (int, float)) and receipt.get("server") == url
+            and 0 <= now - polled_at < INTERVAL):
+        stored = receipt.get("git_sha") or ""
+        at = f" at {stored[:12]}" if stored else (" (no pack applied)")
+        return {"polled": False, "skipped": True, "polled_at": polled_at, "git_sha": stored,
+                "note": f"last poll {when(polled_at)}{at}; not checked against the server "
+                        "again within the hour"}
+    if auth is None:
+        auth = lambda: credentialed(url, project)  # noqa: E731
+    client = client or Client(url)
+    try:
+        health = client.call("GET", "/health")
+    except (Unreachable, Refused) as exc:
+        return {"polled": False, "failed": True, "note": f"could not poll /health: {exc}"}
+    if not isinstance(health, dict):
+        return {"polled": False, "failed": True, "note": "unreadable /health"}
+    sha = str(health.get("git_sha") or "").strip()
+    # A different server never inherits the old server's applied sha or file hashes.
+    base = receipt if receipt.get("server") == url else {}
+    new = {"server": url, "polled_at": now, "git_sha": base.get("git_sha", ""),
+           "files": base.get("files", {})}
+    if not sha:
+        _save(repo, new)
+        return {"polled": True, "polled_at": now, "note": "deployment is unstamped (empty git_sha)"}
+    if sha == base.get("git_sha"):
+        _save(repo, new)
+        return {"polled": True, "polled_at": now, "git_sha": sha, "note": f"current at {sha[:12]}"}
+    try:
+        pack = auth().call("GET", "/api/playbooks")
+    except NoSession:
+        return {"polled": False, "failed": True,
+                "note": "no credential to fetch the pack; run `gban login` or `gban setup`"}
+    except Refused as exc:
+        if exc.status == 404:
+            new["no_pack"] = True
+            _save(repo, new)
+            return {"polled": True, "polled_at": now,
+                    "note": "this server publishes no pack; setup keeps the wheel copy"}
+        return {"polled": False, "failed": True, "note": f"could not fetch pack: {exc}"}
+    except Unreachable as exc:
+        return {"polled": False, "failed": True, "note": f"could not fetch pack: {exc}"}
+    files = pack.get("files") if isinstance(pack, dict) else None
+    if not isinstance(files, list) or pack.get("git_sha") != sha:
+        return {"polled": False, "failed": True,
+                "note": "deployment identity is split or the pack is unreadable; wrote nothing"}
+    # Validate the whole pack before touching a file: a partial or unreadable payload
+    # writes nothing.
+    plan: dict[str, bytes] = {}
+    for entry in files:
+        if not isinstance(entry, dict):
+            return {"polled": False, "failed": True, "note": "unreadable pack; wrote nothing"}
+        body = entry.get("body")
+        if not isinstance(body, str):
+            return {"polled": False, "failed": True, "note": "unreadable pack; wrote nothing"}
+        for rel in targets(entry):
+            if not isinstance(rel, str) or not rel or rel.startswith(("/", "\\")) \
+                    or ".." in Path(rel).parts or Path(rel).is_absolute():
+                return {"polled": False, "failed": True,
+                        "note": "unreadable pack; wrote nothing"}
+            plan[rel] = body.encode("utf-8")
+    applied = apply(repo, plan, dict(base.get("files", {})))
+    owned, written, kept = applied["files"], applied["written"], applied["kept"]
+    gone = applied["gone"]
+    new.update(git_sha=sha, files=owned)
+    _save(repo, new)
+    note = f"applied {sha[:12]}: {len(written)} file(s) written"
+    if kept:
+        note += "; local edits left in place: " + ", ".join(kept)
+    if gone:
+        note += "; no longer in the pack: " + ", ".join(gone)
+    return {"polled": True, "polled_at": now, "git_sha": sha, "note": note,
+            "written": written, "kept": kept, "gone": gone}
+
+
+def apply(repo: Path, plan: dict[str, bytes], owned: dict[str, str]) -> dict:
+    """Write `plan` (path -> bytes) into `repo` by the ownership rules of GRPH-P65.
+
+    - receipt says we wrote it and the new body differs: replace it;
+    - bytes already match: leave the file, record the hash (this adopts a committed copy);
+    - missing: write it, record the hash;
+    - matches neither the receipt nor the pack: a local edit, left and named;
+    - in the receipt but no longer in the pack: left on disk and named.
+    """
+    owned = dict(owned)
+    written, kept = [], []
+    for rel, data in plan.items():
+        dest, digest = repo / rel, _sha(data)
+        if dest.is_file():
+            have = _sha(dest.read_bytes())
+            if have != digest:
+                if owned.get(rel) != have:
+                    kept.append(rel)
+                    continue
+                _write(dest, data)
+                written.append(rel)
+        elif dest.exists():  # a directory where a file belongs: not ours to remove
+            kept.append(rel)
+            continue
+        else:
+            _write(dest, data)
+            written.append(rel)
+        owned[rel] = digest
+    gone = sorted(r for r in owned if r not in plan)
+    return {"files": owned, "written": written, "kept": kept, "gone": gone}

graphban_cli-0.8.8/src/gban/skills/graphban-prove/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: graphban-prove
+description: >
+  The finish bar before a builder moves an item to review: both database
+  engines, sabotage of the caller, one read of the live surface. Use before
+  update_item sets status=review, or when the user runs /graphban-prove.
+user-invocable: true
+---
+
+# Prove it before review
+
+A green unit suite is not the bar. Run this before `update_item` moves the item to `review`. `graphban-work` says evidence appends; this is the procedure that fills it.
+
+1. Heartbeat immediately before any suite that can run longer than the lease, and again when that suite returns. A lease that lapses mid-suite requeues the item.
+2. Run the SQLite suite. Then run the Postgres suite. Both database engines, in that order. A pass on one engine is not a pass. Record each as a `test` evidence entry with `passed`, `failed`, and `scope`. If the item's test scope is `agent_targeted`, run the targeted tests on both engines and leave the full suites to CI.
+3. Break the caller on purpose: pass an empty argument, drop a field, or skip a branch. Run the test that should catch it. Record a `sabotage` receipt with `claim`, `mutation`, and `tests_failed`. `tests_failed` above zero means the test can fail. Zero means the test cannot fail, so fix the test and repeat. Revert the break before you commit.
+4. Read the live surface the item names once: the endpoint, the page, the command output. Quote the sentence it returned in a `note` evidence entry. An empty list is a finding, not a pass: say so and do not hand it off as proven.
+5. Commit, declare touchpoints, then set `review`.
+
+The builder does not set `done`. Signing off is `graphban-review`.

graphban_cli-0.8.8/src/gban/skills/graphban-ship/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: graphban-ship
+description: >
+  Open a pull request, rebase, or look at a salvage branch without guessing the
+  base. Use when opening a pull request, rebasing a branch, proposing a
+  change for review, or reading a salvage branch.
+user-invocable: true
+---
+
+# Ship a branch
+
+## Base
+
+Call `get_context` and read `gitops`. Say which base rule applied:
+
+1. the flag you were given,
+2. a measured `base_branch`,
+3. the remote default.
+
+An unmeasured base is not `main`. When `gitops` reports the base as unmeasured, fall through to the remote default and say so. Do not guess.
+
+## Subject
+
+The subject is the item id, for example `GRPH-123: <title>`.
+
+## Whitelist
+
+The touchpoints snapshotted at wave start are the whitelist. A file outside them is why a proposal was withheld. Run `gbfleet check-touchpoints`, then declare the file with `update_item` or take it out of the diff. A branch that is behind the base is also withheld: rebase it first.
+
+## Salvage
+
+A salvage is a pushed branch and a note, with no pull URL. A salvage HEAD stays a branch: do not propose its commit as a pull request. A salvage pull request stays open when it is the only copy of the work. A salvage SHA is not signed off while CI is red.
+
+## Done
+
+Ledger `done` is not merged. Check the pull request state before saying the work landed.

graphban_cli-0.8.8/src/gban/skills/graphban-unstick/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: graphban-unstick
+description: >
+  Name why a gbfleet drain is stuck and say what clears it. Use when `until`
+  exits review-unsigned, expires with nothing claimed, a child goes quiet, a
+  lease drops, or WAVE_IDLE shows while items are still next. Or when the user
+  runs /graphban-unstick.
+user-invocable: true
+---
+
+# Unstick a drain
+
+Name the item first. A stuck drain is one item, one holder, one timer. Run `fleet_status` and `get_item_details` on it before you do anything else.
+
+## Which case
+
+- `review-unsigned` — `until` exits because its review search is not limited to `--prd`. Say which item. A review row outside `--prd` is another PRD's work, not this wave's failure. A review claim has no TTL, so it stays until its reviewer signs off or releases it.
+- Post-bounce pin — the bounced item stays pinned to its builder until the pin lapses. Wait. Do not reassign it.
+- Dropped lease — a lease that lapsed is a timer. The item requeues when it runs out. Do not re-claim it for the child.
+- Salvage note with no pull URL — the branch is the work. Find the branch and leave it. Do not delete or rebuild it.
+- Live child with empty holdings — the child is running and holds nothing. That is not an idle wave, and `WAVE_IDLE` does not mean done while it keeps the drain open. Report it. Do not fix it from `watch-wave`.
+- `WAVE_IDLE` while items are still `next` — a collision or a pin holds them. Name what holds them.
+
+## Do not
+
+Do not start a second `until` on the same repo. It mints another child onto the same cluster. Check `gbfleet service status --name <prd_id>` and leave the running one.
+
+Do not `sign_off` the item. You did not review it.
+
+Tell the user the item, the holder, and what clears it. Then stop.

{graphban_cli-0.8.6 → graphban_cli-0.8.8}/src/gban/skills/graphban-wave/SKILL.md

@@ -64,3 +64,7 @@ Attach `graphban-answer` when the service reports running. It answers a `wait:de
 `review-unsigned` can be a review row outside this PRD. Say which item. Do not start another drain over it, and do not `sign_off` it yourself.
 
 `--merge` lands the pull requests this wave opened. Leave every other open pull request. A salvage branch can be the only copy of the work.
+
+Before opening a pull request for a wave's work, read `graphban-ship`: it names the base rule, the touchpoint whitelist, and what a salvage is.
+
+A drain that exits `review-unsigned`, or sits idle with items still `next`, is `graphban-unstick`.

{graphban_cli-0.8.6 → graphban_cli-0.8.8}/src/gban/skills/watch-wave/SKILL.md

@@ -73,3 +73,5 @@ Post the report. Then:
 wave (attach a new loop, delete the old), or on `WAVE_IDLE`.
 
 Do not leave a loop running on an idle wave.
+
+A quiet child, a dropped lease, or an idle wave with items still `next` is reported here and cleared by `graphban-unstick`.

{graphban_cli-0.8.6 → graphban_cli-0.8.8}/tests/test_acts.py

@@ -168,7 +168,7 @@ INVOCATIONS = {
 #: `setup` writes config files and so needs a repository and a target of its own
 #: (`test_setup.py`, which makes the same route-documentation assertion this file does),
 #: `swamp` is `test_swamp.py`, and `stack` is `test_stackmap.py`.
-NOT_DRIVEN_HERE = {"login", "doctor", "fleet", "setup", "swamp", "stack"}
+NOT_DRIVEN_HERE = {"login", "doctor", "fleet", "setup", "swamp", "stack", "update"}
 
 
 def _documented() -> list[re.Pattern]:

{graphban_cli-0.8.6 → graphban_cli-0.8.8}/tests/test_machine_report.py

@@ -32,6 +32,8 @@ class _Rec:
 def _doctor(monkeypatch, lines, code, extra=()):
     monkeypatch.setattr("gban.cli.doctor_mod.run", lambda *a, **k: (list(lines), code))
     monkeypatch.setattr("gban.cli.doctor_mod.resolve_supervisor_key", lambda *a, **k: "")
+    # The hourly pack poll is its own line (test_playbooks); these tests are about the report.
+    monkeypatch.setattr("gban.cli._poll", lambda args: None)
     return main(["doctor", *extra])
 
 

graphban_cli-0.8.8/tests/test_playbooks.py

@@ -0,0 +1,325 @@
+import hashlib
+import json
+import subprocess
+
+import pytest
+
+from gban import cli, playbooks
+from gban.client import Client, NoSession, Refused, Unreachable
+
+URL = "http://x"
+
+
+class Fake:
+    def __init__(self, health, pack=None):
+        self.health, self.pack, self.calls = health, pack, []
+
+    def call(self, method, path, body=None):
+        self.calls.append(path)
+        res = self.health if path == "/health" else self.pack
+        if isinstance(res, Exception):
+            raise res
+        return res
+
+
+def poll(url, repo, *, client, **kw):
+    """The Fake serves both halves unless a test hands a separate credentialed client."""
+    kw.setdefault("auth", lambda: client)
+    return playbooks.poll(url, repo, client=client, **kw)
+
+
+def sha(s):
+    return hashlib.sha256(s.encode()).hexdigest()
+
+
+def receipt(tmp_path):
+    return json.loads((tmp_path / playbooks.RECEIPT).read_text())
+
+
+def test_second_poll_within_hour_skips(tmp_path):
+    c = Fake({"git_sha": "a"}, {"git_sha": "a", "files": []})
+    poll(URL, tmp_path, client=c, now=1000)
+    r = poll(URL, tmp_path, client=c, now=1500)
+    assert c.calls == ["/health", "/api/playbooks"]
+    assert not r["polled"] and "last poll" in r["note"]
+
+
+def test_after_hour_and_other_server_and_force_poll(tmp_path):
+    c = Fake({"git_sha": "a"}, {"git_sha": "a", "files": []})
+    poll(URL, tmp_path, client=c, now=1000)
+    poll(URL, tmp_path, client=c, now=1000 + 3601)
+    assert c.calls.count("/health") == 2
+    poll("http://y", tmp_path, client=c, now=4700)
+    assert c.calls.count("/health") == 3
+    poll("http://y", tmp_path, client=c, now=4701, force=True)
+    assert c.calls.count("/health") == 4
+
+
+def test_dropped_connection_keeps_polled_at(tmp_path):
+    poll(URL, tmp_path, client=Fake(Unreachable("down")), now=1000)
+    assert not (tmp_path / playbooks.RECEIPT).exists()
+
+
+def test_unstamped_writes_no_file_sets_polled_at(tmp_path):
+    r = poll(URL, tmp_path, client=Fake({"git_sha": ""}), now=1000)
+    assert "unstamped" in r["note"] and receipt(tmp_path)["polled_at"] == 1000
+    assert receipt(tmp_path)["files"] == {}
+
+
+def test_404_pack(tmp_path):
+    r = poll(URL, tmp_path, client=Fake({"git_sha": "a"}, Refused(404, "nf")), now=1000)
+    assert "no pack" in r["note"] and receipt(tmp_path)["polled_at"] == 1000
+    assert [p for p in tmp_path.rglob("*") if p.is_file()] == [tmp_path / playbooks.RECEIPT]
+
+
+def test_same_sha_does_not_download(tmp_path):
+    c = Fake({"git_sha": "a"}, {"git_sha": "a", "files": []})
+    poll(URL, tmp_path, client=c, now=1000)
+    c.calls.clear()
+    poll(URL, tmp_path, client=c, now=1000 + 4000)
+    assert c.calls == ["/health"] and receipt(tmp_path)["polled_at"] == 5000
+
+
+def test_ownership(tmp_path):
+    def pack(sha_, body):
+        return {"git_sha": sha_, "files": [{"path": "s/a.md", "body": body},
+                                           {"path": "s/b.md", "body": "B"}]}
+    poll(URL, tmp_path, client=Fake({"git_sha": "1"}, pack("1", "A1")), now=0)
+    (tmp_path / "s/b.md").write_text("edited")
+    r = poll(URL, tmp_path, client=Fake({"git_sha": "2"}, pack("2", "A2")), now=5000)
+    assert (tmp_path / "s/a.md").read_text() == "A2"
+    assert (tmp_path / "s/b.md").read_text() == "edited" and "s/b.md" in r["note"]
+
+
+def test_pack_is_fetched_with_the_credential_not_the_bare_client(tmp_path):
+    bare = Fake({"git_sha": "a"}, Refused(401, "authentication required"))
+    authed = Fake(None, {"git_sha": "a", "files": [{"path": "s/a.md", "body": "A"}]})
+    r = playbooks.poll(URL, tmp_path, client=bare, auth=lambda: authed, now=1000)
+    assert bare.calls == ["/health"] and authed.calls == ["/api/playbooks"]
+    assert (tmp_path / "s/a.md").read_text() == "A"
+    assert r["polled"] and receipt(tmp_path)["git_sha"] == "a"
+
+
+def test_a_401_on_the_pack_leaves_polled_at_alone(tmp_path):
+    bare = Fake({"git_sha": "a"}, Refused(401, "authentication required"))
+    r = playbooks.poll(URL, tmp_path, client=bare, auth=lambda: bare, now=1000)
+    assert r.get("failed") and not (tmp_path / playbooks.RECEIPT).exists()
+
+
+def _no_session(*a, **k):
+    raise NoSession("no stored session")
+
+
+def test_credentialed_falls_back_to_the_api_key(monkeypatch):
+    monkeypatch.setattr(playbooks, "authenticated", _no_session)
+    monkeypatch.setenv(playbooks.config.API_KEY_ENV, "gbk_env")
+    made = playbooks.credentialed(URL, "proj")
+    assert isinstance(made, Client) and made.api_key == "gbk_env" and not made.token
+
+
+def test_credentialed_uses_the_stored_project_key(monkeypatch):
+    monkeypatch.setattr(playbooks, "authenticated", _no_session)
+    monkeypatch.delenv(playbooks.config.API_KEY_ENV, raising=False)
+    monkeypatch.setattr(playbooks.config, "stored_supervisor_key",
+                        lambda p: "gbk_stored" if p == "proj" else "")
+    assert playbooks.credentialed(URL, "proj").api_key == "gbk_stored"
+
+
+def test_no_credential_is_a_failed_poll_not_a_crash(tmp_path, monkeypatch):
+    monkeypatch.setattr(playbooks, "authenticated", _no_session)
+    monkeypatch.delenv(playbooks.config.API_KEY_ENV, raising=False)
+    monkeypatch.setattr(playbooks.config, "stored_supervisor_key", lambda p: "")
+    r = playbooks.poll(URL, tmp_path, client=Fake({"git_sha": "a"}), now=1000)
+    assert r.get("failed") and "credential" in r["note"]
+    assert not (tmp_path / playbooks.RECEIPT).exists()
+
+
+def _git_repo(path):
+    subprocess.run(["git", "init", "-q", str(path)], check=True)
+    return path.resolve()
+
+
+def test_checkout_is_the_git_toplevel(tmp_path):
+    root = _git_repo(tmp_path)
+    (root / "cli" / "src").mkdir(parents=True)
+    assert playbooks.checkout(root / "cli" / "src").resolve() == root
+    outside = tmp_path.parent / (tmp_path.name + "-bare")
+    outside.mkdir()
+    assert playbooks.checkout(outside) is None
+
+
+def test_command_from_a_subdirectory_polls_the_checkout_root(tmp_path, monkeypatch):
+    root = _git_repo(tmp_path)
+    (root / "cli").mkdir()
+    monkeypatch.chdir(root / "cli")
+    seen = {}
+
+    def fake_poll(url, repo, **kw):
+        seen.update(url=url, repo=repo, **kw)
+        return {"note": "ok"}
+    monkeypatch.setattr(playbooks, "poll", fake_poll)
+    assert cli.main(["--server", URL, "update"]) == 0
+    assert seen["repo"].resolve() == root and seen["force"] is True
+
+
+# --- GRPH-1493: applying the pack to the checkout -------------------------------------------
+
+SKILL = ".claude/skills/graphban-work/SKILL.md"
+COPIES = [SKILL, ".grok/skills/graphban-work/SKILL.md", ".agents/skills/graphban-work/SKILL.md"]
+LOOP = ".claude/agents/gb-worker.md"
+PLAYBOOK = ".cursor/plugins/graphban/skills/why-graphban/SKILL.md"
+
+
+def _pack(sha_, skill="S1", loop="L1", playbook="P1", extra=()):
+    files = [{"path": SKILL, "kind": "skill", "body": skill},
+             {"path": LOOP, "kind": "loop", "body": loop},
+             {"path": PLAYBOOK, "kind": "playbook", "body": playbook}, *extra]
+    return {"git_sha": sha_, "files": files}
+
+
+def _apply(tmp_path, sha_, now, **kw):
+    return poll(URL, tmp_path, client=Fake({"git_sha": sha_}, _pack(sha_, **kw)), now=now)
+
+
+def test_a_skill_is_written_to_all_three_skill_directories(tmp_path):
+    _apply(tmp_path, "1", 0)
+    for rel in COPIES:
+        assert (tmp_path / rel).read_text() == "S1"
+        assert receipt(tmp_path)["files"][rel] == sha("S1")
+
+
+def test_changed_skill_loop_and_playbook_are_replaced(tmp_path):
+    _apply(tmp_path, "1", 0)
+    r = _apply(tmp_path, "2", 5000, skill="S2", loop="L2", playbook="P2")
+    for rel in COPIES:
+        assert (tmp_path / rel).read_text() == "S2"
+    assert (tmp_path / LOOP).read_text() == "L2"
+    assert (tmp_path / PLAYBOOK).read_text() == "P2"
+    assert sorted(r["written"]) == sorted([*COPIES, LOOP, PLAYBOOK])
+    assert receipt(tmp_path)["git_sha"] == "2"
+
+
+def test_matching_bytes_are_not_rewritten(tmp_path):
+    _apply(tmp_path, "1", 0)
+    before = {rel: (tmp_path / rel).stat().st_mtime_ns for rel in COPIES}
+    r = _apply(tmp_path, "2", 5000, loop="L2")
+    assert r["written"] == [LOOP]
+    assert {rel: (tmp_path / rel).stat().st_mtime_ns for rel in COPIES} == before
+
+
+def test_a_committed_matching_copy_is_adopted_not_rewritten(tmp_path):
+    (tmp_path / SKILL).parent.mkdir(parents=True)
+    (tmp_path / SKILL).write_text("S1")
+    mtime = (tmp_path / SKILL).stat().st_mtime_ns
+    r = _apply(tmp_path, "1", 0)
+    assert SKILL not in r["written"] and (tmp_path / SKILL).stat().st_mtime_ns == mtime
+    assert receipt(tmp_path)["files"][SKILL] == sha("S1")
+    # Adopted, so the next pack replaces it.
+    _apply(tmp_path, "2", 5000, skill="S2")
+    assert (tmp_path / SKILL).read_text() == "S2"
+
+
+def test_a_local_edit_is_left_and_named_while_the_rest_update(tmp_path):
+    _apply(tmp_path, "1", 0)
+    (tmp_path / LOOP).write_text("mine")
+    r = _apply(tmp_path, "2", 5000, skill="S2", loop="L2")
+    assert (tmp_path / LOOP).read_text() == "mine"
+    assert r["kept"] == [LOOP] and LOOP in r["note"]
+    assert (tmp_path / SKILL).read_text() == "S2"
+    # The edit stays the person's: the receipt still holds what we wrote, not their bytes.
+    assert receipt(tmp_path)["files"][LOOP] == sha("L1")
+    r = _apply(tmp_path, "3", 10000, skill="S3", loop="L3")
+    assert (tmp_path / LOOP).read_text() == "mine" and r["kept"] == [LOOP]
+
+
+def test_an_uncommitted_differing_file_without_receipt_is_a_local_edit(tmp_path):
+    (tmp_path / LOOP).parent.mkdir(parents=True)
+    (tmp_path / LOOP).write_text("theirs")
+    r = _apply(tmp_path, "1", 0)
+    assert (tmp_path / LOOP).read_text() == "theirs" and LOOP in r["kept"]
+    assert LOOP not in receipt(tmp_path)["files"]
+
+
+def test_restoring_an_edit_is_delete_and_update(tmp_path):
+    _apply(tmp_path, "1", 0)
+    (tmp_path / LOOP).write_text("mine")
+    (tmp_path / LOOP).unlink()
+    r = _apply(tmp_path, "2", 5000)
+    assert (tmp_path / LOOP).read_text() == "L1" and LOOP in r["written"]
+
+
+def test_a_path_the_pack_dropped_is_left_on_disk_and_named(tmp_path):
+    extra = [{"path": ".claude/agents/gb-old.md", "kind": "loop", "body": "old"}]
+    _apply(tmp_path, "1", 0, extra=extra)
+    r = _apply(tmp_path, "2", 5000)
+    assert (tmp_path / ".claude/agents/gb-old.md").read_text() == "old"
+    assert r["gone"] == [".claude/agents/gb-old.md"] and "gb-old.md" in r["note"]
+
+
+def test_an_unreadable_entry_writes_nothing(tmp_path):
+    pack = _pack("1")
+    pack["files"].append({"path": "../escape.md", "kind": "loop", "body": "x"})
+    r = poll(URL, tmp_path, client=Fake({"git_sha": "1"}, pack), now=0)
+    assert r.get("failed")
+    assert not any(p.is_file() for p in tmp_path.rglob("*"))
+
+
+def test_doctor_with_a_fresh_stamp_reports_the_stored_poll_not_a_check(tmp_path):
+    from gban import doctor
+    _apply(tmp_path, "abcdef1234567890", 1000)
+    c = Fake({"git_sha": "other"})
+    r = poll(URL, tmp_path, client=c, now=1500)
+    assert c.calls == []
+    line = doctor.playbooks_line(r)
+    assert line["status"] == doctor.UNKNOWN
+    assert playbooks.when(1000) in line["detail"] and "abcdef123456" in line["detail"]
+    assert "not checked" in line["detail"] and "just now" not in line["detail"]
+    fresh = doctor.playbooks_line(_apply(tmp_path, "b", 9000))
+    assert fresh["status"] == doctor.PASS and "just now" in fresh["detail"]
+
+
+def test_gban_doctor_prints_the_playbooks_line(tmp_path, monkeypatch, capsys):
+    root = _git_repo(tmp_path)
+    monkeypatch.chdir(root)
+    monkeypatch.setattr(playbooks, "poll", lambda url, repo, **kw: {
+        "polled": False, "skipped": True, "polled_at": 1000, "git_sha": "abc",
+        "note": "last poll 1970-01-01 00:16:40Z at abc; not checked against the server"})
+    monkeypatch.setattr(cli.doctor_mod, "resolve_supervisor_key", lambda *a, **k: "")
+    monkeypatch.setattr(cli.doctor_mod, "run", lambda *a, **k: ([], 0))
+    assert cli.main(["--server", URL, "doctor", "--no-report"]) == 0
+    out = capsys.readouterr()
+    assert "playbooks" in out.out and "at abc" in out.out and "just now" not in out.out
+    assert "last poll" not in out.err
+
+
+# --- GRPH-1506: hook files ride the pack, each to its own path -------------------------------
+
+HOOK = ".cursor/hooks/gb_stop.py"
+HOOKS_JSON = ".cursor/hooks.json"
+
+
+def _hook_pack(sha_, *extra):
+    files = [{"path": SKILL, "kind": "skill", "body": "S1"},
+             {"path": HOOK, "kind": "hook", "body": "H1"}, *extra]
+    return {"git_sha": sha_, "files": files}
+
+
+def test_a_hook_is_written_once_at_its_own_path_and_a_skill_still_fans_out(tmp_path):
+    poll(URL, tmp_path, client=Fake({"git_sha": "1"}, _hook_pack("1")), now=0)
+    assert (tmp_path / HOOK).read_text() == "H1"
+    assert playbooks.targets({"path": HOOK, "kind": "hook"}) == [HOOK]
+    assert sorted(receipt(tmp_path)["files"]) == sorted([*COPIES, HOOK])
+    for rel in COPIES:
+        assert (tmp_path / rel).read_text() == "S1"
+    assert not (tmp_path / ".claude/hooks").exists()
+
+
+def test_a_foreign_hooks_json_is_left_and_named_while_the_scripts_are_written(tmp_path):
+    (tmp_path / ".cursor").mkdir()
+    (tmp_path / HOOKS_JSON).write_text("theirs")
+    pack = _hook_pack("1", {"path": HOOKS_JSON, "kind": "hook", "body": "{}"})
+    r = poll(URL, tmp_path, client=Fake({"git_sha": "1"}, pack), now=0)
+    assert (tmp_path / HOOKS_JSON).read_text() == "theirs"
+    assert HOOKS_JSON in r["kept"] and HOOKS_JSON in r["note"]
+    assert HOOKS_JSON not in receipt(tmp_path)["files"]
+    assert (tmp_path / HOOK).read_text() == "H1"

{graphban_cli-0.8.6 → graphban_cli-0.8.8}/tests/test_setup.py

@@ -613,9 +613,8 @@ def test_the_skill_hands_the_person_a_runnable_line_and_carries_the_rest(tmp_pat
     assert "do not retry" in body.lower()
 
 
-def test_the_skill_ships_in_the_wheel(tmp_path):
-    """Package DATA, not a .py file — the one class of file a packaging config silently drops.
-    A skill that exists in the repo and not in the wheel installs nothing for anyone."""
+def _built_wheel_names(tmp_path):
+    """Build the CLI wheel and return its member names; skip when no builder exists."""
     import subprocess
     import sys
     import zipfile
@@ -634,12 +633,19 @@ def test_the_skill_ships_in_the_wheel(tmp_path):
     if done is None or done.returncode != 0:
         pytest.skip("no wheel builder available")
     wheel = next(out.glob("*.whl"))
-    names = zipfile.ZipFile(wheel).namelist()
+    return zipfile.ZipFile(wheel).namelist()
+
+
+def test_the_skill_ships_in_the_wheel(tmp_path):
+    """Package DATA, not a .py file — the one class of file a packaging config silently drops.
+    A skill that exists in the repo and not in the wheel installs nothing for anyone."""
+    names = _built_wheel_names(tmp_path)
     assert any(n.endswith("skills/graphban-delegation/SKILL.md") for n in names), names[:20]
     assert any(n.endswith("skills/watch-wave/SKILL.md") for n in names), names[:20]
     assert any(n.endswith("skills/graphban-grill/SKILL.md") for n in names), names[:20]
     assert any(n.endswith("skills/graphban-wave/SKILL.md") for n in names), names[:20]
     assert any(n.endswith("skills/graphban-answer/SKILL.md") for n in names), names[:20]
+    assert any(n.endswith("skills/graphban-prove/SKILL.md") for n in names), names[:20]
 
 
 def test_graphban_wave_drains_one_prd_and_does_not_file_tasks():
@@ -656,6 +662,19 @@ def test_graphban_wave_drains_one_prd_and_does_not_file_tasks():
     assert "Do not attach a spawn watcher" in body
 
 
+def test_graphban_ship_names_base_salvage_and_done(tmp_path):
+    body = " ".join(setup_mod.skill_source("graphban-ship").read_text(encoding="utf-8").split())
+    assert "get_context" in body
+    assert "unmeasured" in body
+    assert "whitelist" in body
+    assert "no pull URL" in body
+    assert "is not merged" in body
+    wave = setup_mod.skill_source("graphban-wave").read_text(encoding="utf-8")
+    assert "graphban-ship" in wave
+    names = _built_wheel_names(tmp_path)
+    assert any(n.endswith("skills/graphban-ship/SKILL.md") for n in names), names[:20]
+
+
 def test_watch_wave_names_the_scheduler_and_cancels_on_idle():
     """The Grok procedure has to live in the shipped skill, not only in a laptop
     copy under ~/.grok. A skill that never says WAVE_IDLE leaves the loop running
@@ -1363,6 +1382,41 @@ def test_the_old_subcommand_flag_order_is_still_rejected():
             _parser().parse_args(argv)
 
 
+def test_graphban_prove_states_the_finish_bar(tmp_path):
+    """The finish bar lives in the shipped skill: heartbeat around the long suite, both
+    engines, a sabotage receipt that failed a test, a quoted live read, no builder `done`."""
+    body = " ".join(setup_mod.skill_source("graphban-prove").read_text(encoding="utf-8").split())
+    assert "Heartbeat immediately before" in body
+    assert "and again when that suite returns" in body
+    assert "SQLite suite" in body
+    assert "Postgres suite" in body
+    assert "`sabotage` receipt" in body
+    assert "`tests_failed`" in body
+    assert "above zero" in body
+    assert "Quote the sentence" in body
+    assert "An empty list is a finding" in body
+    assert "The builder does not set `done`" in body
+    names = _built_wheel_names(tmp_path)
+    assert any(n.endswith("skills/graphban-prove/SKILL.md") for n in names), names[:20]
+
+
+def test_graphban_unstick_names_the_stuck_drain(tmp_path):
+    """The unstick skill names the item, the review row outside --prd, the lease
+    timer and the empty-holdings child, and never starts a second until or signs off."""
+    body = " ".join(setup_mod.skill_source("graphban-unstick").read_text(encoding="utf-8").split())
+    assert "review-unsigned" in body
+    assert "review row outside `--prd`" in body
+    assert "Dropped lease" in body
+    assert "empty holdings" in body
+    assert "Do not start a second `until` on the same repo" in body
+    assert "Do not `sign_off` the item" in body
+    for slug in ("graphban-wave", "watch-wave"):
+        other = " ".join(setup_mod.skill_source(slug).read_text(encoding="utf-8").split())
+        assert "graphban-unstick" in other, slug
+    names = _built_wheel_names(tmp_path)
+    assert any(n.endswith("skills/graphban-unstick/SKILL.md") for n in names), names[:20]
+
+
 def test_graphban_work_names_the_lease_the_graph_and_prove():
     """The work skill must warn that a silent long command drops the lease, send
     changed paths to describe_code, call a receipt a test line, and hand

{graphban_cli-0.8.6 → graphban_cli-0.8.8}/uv.lock

@@ -124,7 +124,7 @@ wheels = [
 
 [[package]]
 name = "graphban-cli"
-version = "0.8.6"
+version = "0.8.8"
 source = { editable = "." }
 
 [package.optional-dependencies]