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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: graphban-cli
-Version: 0.8.8
+Version: 0.8.9
 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.8 → graphban_cli-0.8.9}/pyproject.toml

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

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

@@ -11,6 +11,7 @@ the same reason: "we could not tell" must never render as "nothing is wrong".
 """
 from __future__ import annotations
 
+import json
 import os
 import shutil
 import subprocess
@@ -408,10 +409,51 @@ def playbooks_line(result: dict | None) -> dict | None:
     return _line("local", PASS, "playbooks", f"polled just now — {note}")
 
 
+def harness_entries(repo: Path) -> list[dict]:
+    """Does each harness config that exists still declare the graphban MCP entry?
+
+    `gban setup` writes the entry and says so once; nothing re-reads it. Remove it and Claude
+    Code can no longer reach the ledger while every server-side check stays PASS. A harness
+    counts as configured when one of its files exists; a missing file is not checked (never
+    set up here), a file without the entry is a FAIL named after the file.
+    """
+    import tomllib
+    from gban import setup  # lazy: setup imports this module
+
+    server = setup.LEDGER_SERVER
+    key = str(repo.resolve())
+
+    def read(path: Path, toml: bool):
+        try:
+            text = path.read_text(encoding="utf-8")
+            return tomllib.loads(text) if toml else json.loads(text)
+        except (OSError, ValueError):
+            return None  # unreadable counts as lacking the entry
+
+    claude = [(setup.claude_home(), lambda b: (((b.get("projects") or {}).get(key) or {})
+                                                .get("mcpServers") or {})),
+              (repo / ".mcp.json", lambda b: b.get("mcpServers") or {})]
+    grok = [(setup.grok_home(), lambda b: b.get("mcp_servers") or {}),
+            (repo / ".grok" / "config.toml", lambda b: b.get("mcp_servers") or {})]
+    out: list[dict] = []
+    for harness, files, toml in (("claude", claude, False), ("grok", grok, True)):
+        present = [(p, pick) for p, pick in files if p.exists()]
+        if not present:
+            continue
+        if any(server in pick(read(p, toml) or {}) for p, pick in present):
+            out.append(_line("local", PASS, f"{harness} mcp", f"{server} entry present"))
+        else:
+            names = ", ".join(str(p) for p, _ in present)
+            out.append(_line("local", FAIL, f"{harness} mcp",
+                             f"no {server} entry for this project in {names} — "
+                             f"{harness} cannot reach the ledger; run `gban setup`"))
+    return out
+
+
 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)
-             + gitignore.check(repo or Path.cwd()))
+             + gitignore.check(repo or Path.cwd()) + harness_entries(repo or Path.cwd()))
     worst = max((SEVERITY[l["status"]] for l in lines), default=0)
     # FAIL exits 1, UNKNOWN exits 0: "could not check" is not "broken", and a doctor that
     # failed a script because a laptop lacked `gbfleet` would stop being run.

{graphban_cli-0.8.8 → graphban_cli-0.8.9}/src/gban/playbooks.py

@@ -6,6 +6,7 @@ Every `gban` command may poll `/health`; `gban update` always does. The receipt
 """
 from __future__ import annotations
 
+import fnmatch
 import hashlib
 import json
 import os
@@ -24,6 +25,31 @@ INTERVAL = 3600
 SKILL_DIRS = (".claude/skills", ".grok/skills", ".agents/skills")
 
 
+#: What a pack entry may write, per `kind` (GRPH-P65 table). `*` is one path segment. Anything
+#: else (settings, AGENTS.md, MCP config, .git/hooks) is refused and the whole pack is dropped.
+ALLOWED = {
+    "skill": tuple(f"{b}/*/SKILL.md" for b in SKILL_DIRS),
+    "loop": (".cursor/agents/*", ".claude/agents/*", ".codex/agents/*", ".cursor/rules/*.mdc"),
+    "playbook": (".cursor/plugins/graphban/skills/*/SKILL.md",),
+    "hook": (".cursor/hooks.json", ".cursor/hooks/gb_after_file_edit.py",
+             ".cursor/hooks/gb_claim_manifest.py", ".cursor/hooks/gb_session_start.py",
+             ".cursor/hooks/gb_stop.py", ".grok/hooks/graphban-claim-manifest.json"),
+}
+
+
+def allowed(kind: object, rel: object) -> bool:
+    """True when `rel` is a path the pack may write for this `kind`."""
+    if not isinstance(kind, str) or kind not in ALLOWED or not isinstance(rel, str):
+        return False
+    parts = rel.split("/")
+    for pat in ALLOWED[kind]:
+        want = pat.split("/")
+        if len(want) == len(parts) and all(
+                fnmatch.fnmatchcase(g, w) and (w != "*" or g) for g, w in zip(parts, want)):
+            return True
+    return False
+
+
 def targets(entry: dict) -> list[str]:
     """Every checkout path one pack entry is written to."""
     rel = entry.get("path")
@@ -61,6 +87,17 @@ def _sha(data: bytes) -> str:
     return hashlib.sha256(data).hexdigest()
 
 
+def record(repo: Path, written: dict[str, bytes]) -> None:
+    """Note files this tool wrote outside a poll (setup's skills), so a later pack replaces them
+    like any file we wrote. Keeps every other receipt field."""
+    receipt = _read(repo)
+    files = dict(receipt.get("files") or {})
+    for rel, data in written.items():
+        files[rel] = _sha(data)
+    receipt["files"] = files
+    _save(repo, receipt)
+
+
 def when(ts: float) -> str:
     return time.strftime("%Y-%m-%d %H:%M:%SZ", time.gmtime(ts))
 
@@ -128,14 +165,17 @@ def poll(url: str, repo: Path, *, force: bool = False, client: Client | None = N
     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", {})}
+    # A different server never inherits the old server's stamp or applied sha. File hashes
+    # describe what this tool wrote to disk, whichever server sent it, so they stay owned.
+    same = receipt.get("server") in (url, None)
+    base = {"git_sha": receipt.get("git_sha", "") if same else "",
+            "files": receipt.get("files", {})}
+    new = {"server": url, "polled_at": now, "git_sha": base["git_sha"],
+           "files": base["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"):
+    if sha == base.get("git_sha") and not force:
         _save(repo, new)
         return {"polled": True, "polled_at": now, "git_sha": sha, "note": f"current at {sha[:12]}"}
     try:
@@ -170,6 +210,10 @@ def poll(url: str, repo: Path, *, force: bool = False, client: Client | None = N
                     or ".." in Path(rel).parts or Path(rel).is_absolute():
                 return {"polled": False, "failed": True,
                         "note": "unreadable pack; wrote nothing"}
+            if not allowed(entry.get("kind"), rel):
+                return {"polled": False, "failed": True,
+                        "note": f"pack names a path outside its allowed directories: {rel}; "
+                                "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"]

{graphban_cli-0.8.8 → graphban_cli-0.8.9}/src/gban/setup.py

@@ -651,13 +651,29 @@ def install_skill(repo: Path, slug: str = SKILL_SLUG) -> list[tuple[str, Path]]:
     saying so. A dest that differs does not block the other directories."""
     body = skill_source(slug).read_text(encoding="utf-8")
     out = []
+    from . import playbooks
+    owned = playbooks._read(repo).get("files") or {}
     for dest in skill_dests(repo, slug):
         if dest.exists():
-            out.append(("same" if dest.read_text(encoding="utf-8") == body else "differs", dest))
+            if dest.read_text(encoding="utf-8") == body:
+                status = "same"
+            elif dest.is_file() and owned.get(dest.relative_to(repo).as_posix()) == \
+                    playbooks._sha(dest.read_bytes()):
+                # The server pack wrote this exact body (the receipt says so): it is newer
+                # than the wheel's copy, not a local edit, and the pack keeps it fresh.
+                status = "same"
+            else:
+                status = "differs"
+            out.append((status, dest))
             continue
         dest.parent.mkdir(parents=True, exist_ok=True)
         dest.write_text(body, encoding="utf-8")
         out.append(("written", dest))
+    # Receipt the files we planted, so the pack refreshes them instead of freezing them as edits.
+    planted = {d.relative_to(repo).as_posix(): d.read_bytes() for st, d in out if st == "written"}
+    if planted:
+        from . import playbooks
+        playbooks.record(repo, planted)
     return out
 
 

{graphban_cli-0.8.8 → graphban_cli-0.8.9}/src/gban/skills/graphban-answer/SKILL.md

@@ -41,10 +41,10 @@ Sources, in order. A later source does not override an earlier one. Quote the se
 
 Leave wait:secret, wait:access, wait:deploy, and wait:merge blocked. Name them.
 
-A quote: evidence on the wait, kind note, the sentence and where it came from. update_item status=done on the wait only.
+A quote: answer_wait(wait, answer, source={kind: session|prd|memory|decision, ref, quote}). ref is the PRD key, shard id or decision key; it must resolve. It stores the answer and releases the original. Never update_item the wait to done: that is refused without a stored answer.
 Do not update_prd. Do not answer_grill. Do not move the original item. Do not publish_memory.
 
-No quote: print the question, your recommendation, and one line on why the sources do not decide. Leave the wait blocked.
+No quote: answer_wait(wait, needs_person=true), then print the question, your recommendation, and one line on why the sources do not decide. The wait stays blocked.
 
 Do not spawn, merge, sign_off, bounce, or claim.
 ```
@@ -82,11 +82,11 @@ Silence is ask. A conflict is ask. Two reasonable readings are ask. A new contra
 
 A `--prd` drain answers a wait whose `prd_id` matches, or whose dependency link has `b` this wait and `a` an item on that PRD. Leave every other wait.
 
-The original is `a` on that dependency link. You are not its builder. Leave it blocked. Marking the wait `done` returns it to `next` when no other unmet dependency remains.
+The original is `a` on that dependency link. You are not its builder. Leave it blocked. `answer_wait` returns it to `next` when no other unmet dependency remains. You cannot answer a wait your own agent filed.
 
 ## Quote
 
-The answer is the quoted sentence and where it came from. When the quote is a related decision, the note also names the one step. `update_item` on the wait: evidence `kind` `note` with that sentence, then `status=done`.
+The answer is the quoted sentence and where it came from. When the quote is a related decision, the note also names the one step. `answer_wait` with `answer` (or `option`) and `source` `{kind, ref, quote}`: `kind` is `session`, `prd`, `memory` or `decision`; `ref` must resolve for the last three; `quote` is the sentence. Never move a wait to done with `update_item`.
 
 A decision that should outlive the item: `add_memory`, scope `global`. Read the returned `status`. Leave a `candidate`. Do not `publish_memory`.
 
@@ -94,7 +94,7 @@ A decision that should outlive the item: `add_memory`, scope `global`. Read the
 
 One question. The question, your recommendation, and one line on why the sources do not decide it.
 
-Record nothing until the user answers. Their words are the evidence, then the wait is `done`. The recommendation alone is not the answer.
+Call `answer_wait` with `needs_person=true`; it records no answer. When the user answers, call `answer_wait` with their words and `source` kind `session`. The recommendation alone is not the answer.
 
 A scheduler fire that must ask prints that question and leaves the wait blocked. The parent session puts it to the user.
 

{graphban_cli-0.8.8 → graphban_cli-0.8.9}/tests/test_doctor.py

@@ -724,7 +724,7 @@ def test_doctor_passes_when_the_paths_are_ignored(home, monkeypatch, tmp_path):
     repo = tmp_path / "repo"
     _git_init(repo)
     gitignore.ensure(repo)
-    (repo / ".mcp.json").write_text("{}\n", encoding="utf-8")
+    (repo / ".mcp.json").write_text('{"mcpServers": {"graphban": {}}}\n', encoding="utf-8")
     monkeypatch.setattr(doctor, "authenticated", lambda url: _Server())
     monkeypatch.setattr(doctor, "find_supervisor", lambda: "")
 
@@ -815,3 +815,21 @@ def test_can_supervise_posts_a_validating_probe_and_reads_only_403_and_404(monke
         answer["code"] = code
         assert doctor.can_supervise("http://gb.invalid", "gb_sk_X") is want, code
     assert doctor.can_supervise("file:///etc/passwd", "gb_sk_X") is None
+
+
+def test_doctor_fails_when_the_graphban_entry_is_gone_from_claude_json(home, monkeypatch):
+    """gban setup wrote the entry; removing it must not leave doctor all-PASS."""
+    monkeypatch.setattr(doctor, "authenticated", lambda url: _Server())
+    monkeypatch.setattr(doctor, "find_supervisor", lambda: "")
+    cfg = home / "claude.json"
+    cfg.write_text(json.dumps({"projects": {str(home.resolve()): {
+        "mcpServers": {"graphban": {"command": "x"}}}}}), encoding="utf-8")
+    lines, code = doctor.run("http://gb.invalid", "core", "", repo=home)
+    assert [l["status"] for l in lines if l["name"] == "claude mcp"] == ["PASS"]
+
+    cfg.write_text(json.dumps({"projects": {str(home.resolve()): {"mcpServers": {}}}}),
+                   encoding="utf-8")
+    lines, code = doctor.run("http://gb.invalid", "core", "", repo=home)
+    found = [l for l in lines if l["name"] == "claude mcp"]
+    assert code == 1 and found[0]["status"] == "FAIL"
+    assert str(cfg) in found[0]["detail"]

{graphban_cli-0.8.8 → graphban_cli-0.8.9}/tests/test_playbooks.py

@@ -82,21 +82,21 @@ def test_same_sha_does_not_download(tmp_path):
 
 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"}]}
+        return {"git_sha": sha_, "files": [{"path": ".claude/agents/a.md", "kind": "loop", "body": body},
+                                           {"path": ".claude/agents/b.md", "kind": "loop", "body": "B"}]}
     poll(URL, tmp_path, client=Fake({"git_sha": "1"}, pack("1", "A1")), now=0)
-    (tmp_path / "s/b.md").write_text("edited")
+    (tmp_path / ".claude/agents/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"]
+    assert (tmp_path / ".claude/agents/a.md").read_text() == "A2"
+    assert (tmp_path / ".claude/agents/b.md").read_text() == "edited" and ".claude/agents/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"}]})
+    authed = Fake(None, {"git_sha": "a", "files": [{"path": ".claude/agents/a.md", "kind": "loop", "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 (tmp_path / ".claude/agents/a.md").read_text() == "A"
     assert r["polled"] and receipt(tmp_path)["git_sha"] == "a"
 
 
@@ -248,6 +248,22 @@ def test_restoring_an_edit_is_delete_and_update(tmp_path):
     assert (tmp_path / LOOP).read_text() == "L1" and LOOP in r["written"]
 
 
+def test_update_restores_a_deleted_edit_when_the_sha_is_unchanged(tmp_path):
+    _apply(tmp_path, "1", 0)
+    (tmp_path / LOOP).write_text("mine")
+    r = _apply(tmp_path, "2", 5000, loop="L2")
+    assert r["kept"] == [LOOP] and (tmp_path / LOOP).read_text() == "mine"
+    (tmp_path / LOOP).unlink()
+    # An ordinary poll past the hour at the same sha downloads nothing.
+    fake = Fake({"git_sha": "2"}, _pack("2", loop="L2"))
+    poll(URL, tmp_path, client=fake, now=10000)
+    assert not (tmp_path / LOOP).exists()
+    # `gban update` (force) applies even though the sha is unchanged.
+    r = poll(URL, tmp_path, client=fake, now=10001, force=True)
+    assert (tmp_path / LOOP).read_text() == "L2" and LOOP in r["written"]
+    assert receipt(tmp_path)["files"][LOOP] == sha("L2")
+
+
 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)
@@ -323,3 +339,79 @@ def test_a_foreign_hooks_json_is_left_and_named_while_the_scripts_are_written(tm
     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"
+
+
+def _planted(tmp_path, monkeypatch):
+    from gban import setup as setup_mod
+    src = tmp_path / "wheel" / "SKILL.md"
+    src.parent.mkdir()
+    src.write_text("wheel v1")
+    monkeypatch.setattr(setup_mod, "skill_source", lambda slug="graphban-work": src)
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    setup_mod.install_skill(repo, "graphban-work")
+    return repo
+
+
+def test_a_skill_setup_planted_is_refreshed_by_the_pack(tmp_path, monkeypatch):
+    repo = _planted(tmp_path, monkeypatch)
+    assert receipt(repo)["files"][SKILL] == sha("wheel v1")
+    r = _apply(repo, "2", 5000, skill="S2")
+    assert r["kept"] == []
+    for rel in COPIES:
+        assert (repo / rel).read_text() == "S2"
+        assert receipt(repo)["files"][rel] == sha("S2")
+
+
+def test_a_skill_setup_planted_then_edited_is_left_and_named(tmp_path, monkeypatch):
+    repo = _planted(tmp_path, monkeypatch)
+    (repo / SKILL).write_text("mine")
+    r = _apply(repo, "2", 5000, skill="S2")
+    assert r["kept"] == [SKILL]
+    assert (repo / SKILL).read_text() == "mine"
+    assert (repo / COPIES[2]).read_text() == "S2"
+
+
+def test_switching_server_keeps_file_ownership(tmp_path):
+    other = "http://other.example"
+    poll(URL, tmp_path, client=Fake({"git_sha": "1"}, _pack("1")), now=0)
+    poll(other, tmp_path, client=Fake({"git_sha": "1"}, _pack("1")), now=10)
+    r = poll(URL, tmp_path, client=Fake({"git_sha": "2"}, _pack("2", skill="S2")), now=20)
+    assert r["polled"] is True and not r.get("kept")
+    for rel in COPIES:
+        assert (tmp_path / rel).read_text() == "S2"
+
+
+def test_switching_server_still_leaves_a_local_edit(tmp_path):
+    other = "http://other.example"
+    poll(URL, tmp_path, client=Fake({"git_sha": "1"}, _pack("1")), now=0)
+    (tmp_path / LOOP).write_text("mine")
+    poll(other, tmp_path, client=Fake({"git_sha": "1"}, _pack("1")), now=10)
+    r = poll(URL, tmp_path, client=Fake({"git_sha": "2"}, _pack("2", loop="L2")), now=20)
+    assert (tmp_path / LOOP).read_text() == "mine" and r["kept"] == [LOOP]
+
+
+# --- GRPH-1534: the client only writes the pack's allowed directories ----------------------
+
+@pytest.mark.parametrize("kind,path", [
+    ("loop", ".claude/settings.json"), ("loop", "AGENTS.md"), ("loop", "CLAUDE.md"),
+    ("loop", ".git/hooks/pre-commit"), ("loop", ".mcp.json"),
+    ("skill", ".claude/skills/x/other.md"), ("loop", ".claude/agents/a/b.md"),
+    ("hook", ".git/hooks/pre-commit"), ("bogus", ".claude/agents/ok.md"), (None, LOOP),
+])
+def test_a_path_outside_the_allowlist_writes_nothing(tmp_path, kind, path):
+    pack = _pack("1")
+    pack["files"].append({"path": path, "kind": kind, "body": "x"})
+    r = poll(URL, tmp_path, client=Fake({"git_sha": "1"}, pack), now=0)
+    assert r.get("failed")
+    if kind in ("loop", "hook"):
+        assert path in r["note"]
+    assert not any(p.is_file() for p in tmp_path.rglob("*"))
+
+
+def test_the_real_pack_passes_the_allowlist():
+    from pathlib import Path
+    real = Path(__file__).resolve().parents[2] / "backend/scripts/gban_playbooks.json"
+    for e in json.loads(real.read_text())["files"]:
+        for rel in playbooks.targets(e):
+            assert playbooks.allowed(e["kind"], rel), (e["kind"], rel)

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

@@ -571,6 +571,27 @@ def test_an_edited_skill_is_left_alone(tmp_path, wired):
     assert other.read_text() == setup_mod.skill_source("watch-wave").read_text()
 
 
+def test_a_pack_written_skill_that_differs_from_the_bundled_one_is_not_unknown(tmp_path, wired):
+    """GRPH-1543: the pack just wrote a newer skill than the wheel carries. Setup must not
+    flag a file the same command wrote."""
+    from gban import playbooks
+    repo, home = tmp_path / "repo", tmp_path / ".claude.json"
+    repo.mkdir()
+    planted = {}
+    for rel in setup_mod.SKILL_DEST_DIRS:
+        dest = repo / rel / "graphban-delegation" / "SKILL.md"
+        dest.parent.mkdir(parents=True)
+        dest.write_bytes(b"newer pack copy\n")
+        planted[dest.relative_to(repo).as_posix()] = b"newer pack copy\n"
+    playbooks.record(repo, planted)
+
+    lines, _, _ = _run(Server(), repo, home, wired=wired)
+
+    assert not any("left alone" in l["detail"] for l in lines)
+    assert not any(l.get("name") == "skill" and l.get("status") == "UNKNOWN" for l in lines)
+    assert dest.read_bytes() == b"newer pack copy\n"
+
+
 def test_the_skill_tells_the_agent_the_two_things_it_cannot_work_out(tmp_path):
     """Both are failures that read as something else. A missing tier reads as the tool not
     existing; a missing session reads as something to retry, when the remedy is a person at a

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

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