@appchy/jarvis 0.1.76 → 0.1.78

package/harness/harness/align.py

@@ -566,7 +566,7 @@ def _align_acceptance(root: Path) -> list:
     # only test never executed, which is the false green the whole join exists to
     # catch. Only statuses the run explicitly reports as not-passed are subtracted,
     # so `align` still works before anyone has produced a run.
-    run, _, _ = _load_run(repo)
+    run = _load_run(repo).proven
     unproven = {cid for cid, status in run.items() if status in ("todo", "failed")}
 
     for name, md in sorted(features.items()):

package/harness/harness/coverage.py

@@ -70,9 +70,10 @@ def cmd_coverage(args) -> int:
     nobody reads. The flip is its own task."""
     root = find_work_root()
     repo = root.parent
-    run, runners, shards = _load_run(repo)
+    read = _load_run(repo)
+    run, runners, shards = read.proven, read.runners, read.shards
 
-    if not shards:
+    if not shards and not read.stale:
         # The commands come from `verify.*` in the repo's config. They used to be
         # one repo's own package-manager invocations, hardcoded — which told every
         # other consumer to run a command it does not have. A name-only literal
@@ -142,7 +143,21 @@ def cmd_coverage(args) -> int:
                      len(built & todo), len(declared - built),
                      sorted(failed), sorted(gap), sorted(ahead)))
 
-    print(f"\n  read {len(shards)} shard(s): {', '.join(shards)}\n")
+    print(f"\n  read {len(shards)} shard(s): {', '.join(shards)}")
+    # WHAT WAS SET ASIDE, on the same screen as what was counted. A result whose
+    # test file is gone and a result that never existed look identical in the
+    # totals, and telling them apart is the difference between "re-run that suite"
+    # and "nobody has ever proved this".
+    if read.stale:
+        folders = sorted({s.rsplit("/", 1)[0] for s in read.stale if "/" in s})
+        print(f"  ignored {len(read.stale)} shard(s) whose test file is gone"
+              f"{' (' + ', '.join(folders) + ')' if folders else ''}"
+              " — re-run those suites to replace them")
+    if read.unattributed:
+        print(f"  {len(read.unattributed)} shard(s) do not say which file they ran"
+              " — counted, but nothing can check them: "
+              + ", ".join(read.unattributed))
+    print()
     print(f"  {'feature':<18} {'built':>6} {'PROVEN':>7} {'eyes-on':>8} {'todo':>5} "
           f"{'gap':>4} {'unbuilt':>8}   status")
     print(f"  {'-' * 18} {'-' * 6} {'-' * 7} {'-' * 8} {'-' * 5} {'-' * 4} "

package/harness/harness/gate.py

@@ -384,12 +384,19 @@ def _results_out(data) -> list:
             for r in (data.get("results") or [])]
 
 
-def _verify_async(root, name) -> int:
-    """Start the gates, or say where the run already in flight has got to.
-
-    One call with three answers, because a verify takes minutes and a relayed tool
-    call cannot. Which answer comes back is never the caller's to choose: it is
-    whatever is true about this checkout right now.
+def _verify_report(root, name) -> int:
+    """Say where the run stands. **Never starts one.**
+
+    ASKING AND STARTING ARE TWO OPERATIONS, and they used to be one call whose
+    meaning depended on timing: it attached when a run was in flight and started
+    one when none was. So a session checking whether the gates had finished set a
+    four-minute build going by asking — which is how a repo with a shared build
+    directory raced itself, and the resulting corruption was read as a flaky gate
+    for three sessions.
+
+    The split is on this side rather than the other because THIS is the call that
+    gets repeated. Polling is the loop; starting happens once and is said out
+    loud. A caller that repeats itself must be unable to cause anything.
     """
     running = live_run(root)
     if running:
@@ -424,6 +431,31 @@ def _verify_async(root, name) -> int:
              "done": done.get("done") or [], "passed": bool(done.get("passed")),
              "commit": done.get("sha") or "", "results": _results_out(done)})
 
+    return _answer(
+        "idle",
+        f"No gates have run for '{name or 'no task'}' at this commit. Start them "
+        f"explicitly — asking never starts a run.",
+        {"gates": sorted(VERIFY)})
+
+
+def _verify_start(root, name) -> int:
+    """Start the gates in the background. **Never reports on somebody else's run.**
+
+    Refuses when a run is in flight rather than quietly attaching to it. Attaching
+    is what let one call report a run started for a DIFFERENT task, whose verdict
+    would then have been read against this one's commit — measured 2026-09-09.
+    A refusal that names the task holding the checkout is the honest answer, and
+    the report door is one call away.
+    """
+    running = live_run(root)
+    if running:
+        return _answer(
+            "running", _busy(running),
+            {"gate": running.get("current") or "starting",
+             "elapsedSeconds": _elapsed(running),
+             "gates": running.get("gates") or [], "done": running.get("done") or [],
+             "results": _results_out(running)})
+
     child = subprocess.Popen(
         [sys.executable, os.path.abspath(sys.argv[0]), "verify", "--task", name,
          "--detached"],
@@ -432,17 +464,24 @@ def _verify_async(root, name) -> int:
     return _answer(
         "started",
         f"Gates started ({len(VERIFY)}): {', '.join(sorted(VERIFY))}. They take "
-        f"minutes, not seconds — ask again for progress, and again for the result.",
+        f"minutes, not seconds — ask for progress, which never starts another.",
         {"gates": sorted(VERIFY)})
 
 
 def cmd_verify(args) -> int:
     """Execute the verify commands and RECORD the result against the task.
 
-    Three doors onto one run. Blocking is the person's and is unchanged. `--async`
-    is the tool surface's, because a call that takes 174 seconds cannot be a relayed
-    round trip. `--detached` is the child the second one starts and is nobody's to
-    type.
+    Four doors, and **asking is not one of the ones that starts anything.**
+    Blocking is the person's: typing the command is the explicit act, so it runs
+    the gates and prints the table. `--async` starts a background run for the tool
+    surface, because a call that takes 174 seconds cannot be a relayed round trip.
+    `--status` only reports, and is what a caller waiting for a result uses.
+    `--detached` is the child `--async` spawns and is nobody's to type.
+
+    The two used to be one call that started or attached depending on timing, and
+    the ambiguity cost more than it saved: a session polling for a result started
+    the run it was waiting for, and one call attached to a run belonging to
+    another task and would have reported that verdict here.
     """
     root = find_work_root()
     name = (args.get("task") or "").strip()
@@ -456,16 +495,17 @@ def cmd_verify(args) -> int:
         _execute(root, name)
         return 0
 
+    if args.get("status"):
+        return _verify_report(root, name)
+
+    if args.get("async"):
+        return _verify_start(root, name)
+
     running = live_run(root)
     if running:
-        if args.get("async"):
-            return _verify_async(root, name)
         print(f"error: {_busy(running)}", file=sys.stderr)
         return 1
 
-    if args.get("async"):
-        return _verify_async(root, name)
-
     results, ok, sha = _execute(root, name)
     _print_report(results, sha)
     if name:
@@ -577,7 +617,7 @@ def gate(root, task, accept: str = "", owner: str = "") -> list:
     # a recorded sentence saying what a human saw. A `covers:` with neither is the
     # exact shape of "done on the model's say-so".
     if task.covers:
-        proven, _, _ = _load_run(root.parent)
+        proven = _load_run(root.parent).proven
         seen = _observed_acs(task)
         feature = (task.owner or "").split("/")[-1]
         for ac in task.covers:

package/harness/harness/shard.py

@@ -1,8 +1,8 @@
-"""Reading the coverage shards — the ONE reader, as `sdk/testing/shard.ts` is the one writer.
+"""Reading the coverage shards — the ONE reader, as the covers package is the one writer.
 
-Every runner (vitest, Playwright, the `examples/*.mjs` smokes) drops a
-`.work/coverage/<runner>-<workspace>.json` carrying what that run actually proved. Three
-checks need to read them — `coverage` reports them, `align` refuses to call a skipped
+Every runner (vitest, Playwright, doctest, a hand-rolled script) drops a
+`.work/coverage/<runner>-<workspace>-<source>.json` carrying what that run actually proved.
+Three checks need to read them — `coverage` reports them, `align` refuses to call a skipped
 binding evidence, and `lint`'s rollup asks whether a shipped feature has any. Each growing
 its own reader is the drift the shard format exists to prevent, and it also produced a real
 import cycle the moment the second one wanted it.
@@ -11,6 +11,7 @@ import cycle the moment the second one wanted it.
 """
 import json
 from pathlib import Path
+from typing import NamedTuple
 
 
 #: Precedence when several sites claim one criterion — the SAME rank both
@@ -20,9 +21,30 @@ from pathlib import Path
 _RANK = {"failed": 3, "todo": 2, "passed": 1}
 
 
-def _load_run(repo: Path) -> tuple[dict, dict, list]:
-    """`{'feature/AC-nn': status}` from every shard, the RUNNERS that claimed each
-    criterion, and the shard names read.
+class Run(NamedTuple):
+    """What the shards on disk add up to, and what had to be set aside to get there.
+
+    `stale` and `unattributed` are as much a part of the answer as `proven`: a
+    reader who cannot see that evidence was discarded cannot tell it from evidence
+    that never existed, and that is the failure this whole module guards.
+    """
+
+    #: `{'feature/AC-nn': 'passed' | 'failed' | 'todo'}`.
+    proven: dict
+    #: `{'feature/AC-nn': {runner, …}}` — what KIND of test claimed each one.
+    runners: dict
+    #: The shard filenames actually read.
+    shards: list
+    #: Source paths named by a shard that is no longer in the tree. Their claims
+    #: are not in `proven`.
+    stale: list
+    #: Shards that never say what they ran. Their claims ARE in `proven` — there
+    #: is nothing to check them against — and they are named so a reader knows it.
+    unattributed: list
+
+
+def _load_run(repo: Path) -> Run:
+    """Every shard's verdict on every criterion, merged.
 
     The merge applies `failed > todo > passed` ACROSS shards, because a promise
     is one behaviour however many runners touch it: proven here and failing
@@ -34,30 +56,45 @@ def _load_run(repo: Path) -> tuple[dict, dict, list]:
     `playwright.json`. A criterion bound at both levels reported whichever
     runner sorted last, which is the one thing this file exists not to do.
 
+    A SHARD OUTLIVES THE TEST THAT WROTE IT, so one whose `source` is no longer
+    in the tree is set aside rather than read. It is a result about code this
+    checkout does not have, and nothing rewrites it: a renamed or deleted spec
+    would otherwise go on claiming `passed` forever, which is the same fault a
+    `// Covers:` comment is banned for. The merge above saves only the
+    contradicted case — a criterion with a stale pass AND a live failure reads
+    as failing — and does nothing at all for one whose only record is stale.
+
     The runners are kept because they say what KIND of test claimed a criterion:
     a browser suite proves what is on screen, a unit runner proves a value. Which
     vitest suite is `unit` and which is `integration` is not derivable here, and is
     not guessed at — see `AC_LEVELS`. `_wrong_level` is the only caller that needs
-    them, and it is why this returns three values rather than two: a second reader
-    that tracked runners separately is exactly the drift this module ended.
+    them, and it is why this returns them at all: a second reader that tracked
+    runners separately is exactly the drift this module ended.
     """
-    out: dict = {}
-    runners: dict = {}
-    shards: list = []
+    read = Run({}, {}, [], [], [])
     d = repo / ".work" / "coverage"
     if not d.is_dir():
-        return out, runners, shards
+        return read
     for p in sorted(d.glob("*.json")):
         try:
             data = json.loads(p.read_text())
         except Exception:
             continue
-        shards.append(p.name)
+        source = data.get("source")
+        if not isinstance(source, str) or source == "":
+            # COUNTED, AND NAMED. A runner that does not write a source cannot be
+            # checked, and dropping it would throw away real evidence to punish a
+            # writer. Saying so is what lets somebody fix the writer.
+            read.unattributed.append(p.name)
+        elif not (repo / source).exists():
+            read.stale.append(source)
+            continue
+        read.shards.append(p.name)
         runner = data.get("runner") or "unknown"
         for cid, rec in (data.get("covered") or {}).items():
             status = rec.get("status") if isinstance(rec, dict) else str(rec)
-            runners.setdefault(cid, set()).add(runner)
-            prior = out.get(cid)
+            read.runners.setdefault(cid, set()).add(runner)
+            prior = read.proven.get(cid)
             if prior is None or _RANK.get(status, 0) > _RANK.get(prior, 0):
-                out[cid] = status
-    return out, runners, shards
+                read.proven[cid] = status
+    return read

package/harness/test_work.py

@@ -1008,7 +1008,10 @@ def test_epic_covers_must_be_feature_qualified():
 
 def _shards(tmp: str, **byname: dict) -> Path:
     """A repo with `.work/coverage/` holding one shard per keyword — the file
-    NAME matters, since the merge used to depend on the order they sort in."""
+    NAME matters, since the merge used to depend on the order they sort in.
+
+    A `source` key is written only where a test asks for one, so the merge tests
+    above stay about the merge."""
     d = Path(tmp) / ".work" / "coverage"
     d.mkdir(parents=True)
     for name, covered in byname.items():
@@ -1016,6 +1019,16 @@ def _shards(tmp: str, **byname: dict) -> Path:
     return Path(tmp)
 
 
+def _ran(repo: Path, name: str, source: str, covered: dict) -> Path:
+    """One shard that names the file it ran. Returns that file's path so a test
+    can create it, or rename it away."""
+    d = repo / ".work" / "coverage"
+    d.mkdir(parents=True, exist_ok=True)
+    (d / f"{name}.json").write_text(
+        json.dumps({"runner": "vitest", "source": source, "covered": covered}))
+    return repo / source
+
+
 def test_a_todo_in_one_shard_beats_a_pass_in_another():
     # The masking bug: a criterion driven at both levels — a passing vitest
     # suite AND a Playwright `test.fixme` — is HALF covered, and half is not
@@ -1029,9 +1042,9 @@ def test_a_todo_in_one_shard_beats_a_pass_in_another():
         # Three values since the level model landed: the merged statuses, the
         # RUNNERS that claimed each id, and the shards read. This call site was
         # left unpacking two and nothing caught it — `scripts/` is in no gate.
-        run, _runners, shards = coverage._load_run(repo)
-        assert run["courses/AC-01"] == "todo", run
-        assert len(shards) == 2
+        read = coverage._load_run(repo)
+        assert read.proven["courses/AC-01"] == "todo", read.proven
+        assert len(read.shards) == 2
 
 
 def test_a_failure_anywhere_outranks_everything():
@@ -1066,6 +1079,59 @@ def test_a_covers_with_no_tests_never_promotes_a_criterion():
         assert coverage._load_run(repo)[0]["x/AC-01"] == "passed"
 
 
+def test_a_shard_whose_test_file_is_gone_proves_nothing():
+    # A RENAME, made deliberately, on a fixture — never on this tree's history.
+    # The shard is untouched by the rename and goes on saying `passed`; nothing
+    # will ever rewrite it, because the run that would is gone with the file.
+    with tempfile.TemporaryDirectory() as tmp:
+        repo = Path(tmp)
+        was = _ran(repo, "vitest-picker", "tests/picker.test.ts",
+                   {"projects/AC-01": {"status": "passed"}})
+        was.parent.mkdir(parents=True, exist_ok=True)
+        was.write_text("")
+        assert coverage._load_run(repo).proven["projects/AC-01"] == "passed"
+
+        was.rename(was.parent / "chooser.test.ts")
+        read = coverage._load_run(repo)
+        assert "projects/AC-01" not in read.proven, read.proven
+        assert read.shards == []
+
+
+def test_what_was_set_aside_is_reported_rather_than_dropped():
+    # A reader who cannot see that evidence was discarded cannot tell it from
+    # evidence that never existed, and would go looking for a test to write
+    # rather than a suite to re-run.
+    with tempfile.TemporaryDirectory() as tmp:
+        repo = _shards(tmp, doctest={"engine/AC-02": {"status": "passed"}})
+        _ran(repo, "vitest-picker", "tests/picker.test.ts",
+             {"projects/AC-01": {"status": "passed"}})
+        read = coverage._load_run(repo)
+
+        assert read.stale == ["tests/picker.test.ts"]
+        # The one with no source at all is COUNTED — there is nothing to check it
+        # against, and dropping it would throw away real evidence to punish a
+        # writer — but it is named, so the writer can be fixed.
+        assert read.unattributed == ["doctest.json"]
+        assert read.proven["engine/AC-02"] == "passed"
+
+
+def test_a_live_failure_is_not_argued_away_by_a_stale_pass():
+    # The merge already handled this one, and it is the ONLY case it handled: a
+    # criterion whose sole record is a stale pass had nothing to contradict it.
+    with tempfile.TemporaryDirectory() as tmp:
+        repo = Path(tmp)
+        live = _ran(repo, "playwright-bar", "e2e/bar.spec.ts",
+                    {"daw/AC-16": {"status": "failed"}})
+        live.parent.mkdir(parents=True, exist_ok=True)
+        live.write_text("")
+        _ran(repo, "playwright-old-bar", "old/bar.spec.ts",
+             {"daw/AC-16": {"status": "passed"}})
+
+        read = coverage._load_run(repo)
+        assert read.proven["daw/AC-16"] == "failed"
+        assert read.stale == ["old/bar.spec.ts"]
+
+
 # ---------------------------------------------------------------------------
 # Ported from the second fork. Everything below covers a capability that fork
 # had and this base did not: domain hosting, judgement tallying, run-aware
@@ -2733,6 +2799,83 @@ def test_a_verify_run_is_visible_to_the_next_caller():
                 gate.VERIFY = old
 
 
+def _said(capsys_free_call) -> dict:
+    """The JSON one of the async doors printed, as a dict."""
+    import io
+    from contextlib import redirect_stdout
+
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        capsys_free_call()
+    for line in reversed(buf.getvalue().splitlines()):
+        if line.strip().startswith("{"):
+            return json.loads(line)
+    raise AssertionError(f"no JSON on stdout: {buf.getvalue()!r}")
+
+
+def test_asking_where_the_gates_stand_never_starts_them():
+    # Asking and starting used to be ONE call whose meaning depended on timing, so a
+    # session polling for a result set off the four-minute run it was waiting for.
+    # Polling is the loop and starting happens once, so the repeatable call is the
+    # one that has to be unable to cause anything.
+    with tempfile.TemporaryDirectory() as tmp:
+        v = _tree(tmp)
+        e = _epic(v, "an-epic")
+        _task(e / "in-progress", "alpha", body="# T\n")
+        with _work_dir(tmp) as root:
+            old, gate.VERIFY = gate.VERIFY, {"tests": "true"}
+            try:
+                out = _said(lambda: gate.cmd_verify({"task": "alpha", "status": True}))
+                assert out["state"] == "idle", out
+                # The real assertion: nothing ran, and nothing is running.
+                assert gate.read_run(root) is None, "asking wrote a run file"
+                assert gate.live_run(root) is None
+            finally:
+                gate.VERIFY = old
+
+
+def test_starting_while_a_run_is_live_names_whose_it_is_rather_than_attaching():
+    # Attaching is what let one call report a run started for a DIFFERENT task,
+    # whose verdict would then have been read against this one's commit.
+    with tempfile.TemporaryDirectory() as tmp:
+        v = _tree(tmp)
+        e = _epic(v, "an-epic")
+        _task(e / "in-progress", "alpha", body="# T\n")
+        _task(e / "in-progress", "beta", body="# T\n")
+        with _work_dir(tmp) as root:
+            old, gate.VERIFY = gate.VERIFY, {"tests": "true"}
+            try:
+                gate._write_run(root, {"task": "alpha", "pid": os.getpid(),
+                                       "machine": "here", "started": gate._now().isoformat(),
+                                       "gates": ["tests"], "current": "tests", "done": [],
+                                       "finished": None, "read": False})
+                out = _said(lambda: gate.cmd_verify({"task": "beta", "async": True}))
+                assert out["state"] == "running", out
+                assert "alpha" in out["message"], out["message"]
+            finally:
+                gate.VERIFY = old
+
+
+def test_a_finished_run_for_another_task_is_not_handed_over_as_this_ones():
+    # The wrong-verdict half. A result proven for one item says nothing about
+    # another, and reporting it would put a green gate on work nobody ran.
+    with tempfile.TemporaryDirectory() as tmp:
+        v = _tree(tmp)
+        e = _epic(v, "an-epic")
+        _task(e / "in-progress", "alpha", body="# T\n")
+        _task(e / "in-progress", "beta", body="# T\n")
+        with _work_dir(tmp) as root:
+            old, gate.VERIFY = gate.VERIFY, {"tests": "true"}
+            try:
+                gate.cmd_verify({"task": "alpha"})
+                assert gate.read_run(root)["passed"] is True
+                out = _said(lambda: gate.cmd_verify({"task": "beta", "status": True}))
+                assert out["state"] == "idle", out
+                assert out["passed"] is False, out
+            finally:
+                gate.VERIFY = old
+
+
 def test_a_second_verify_is_refused_while_one_is_running():
     with tempfile.TemporaryDirectory() as tmp:
         v = _tree(tmp)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appchy/jarvis",
-  "version": "0.1.76",
+  "version": "0.1.78",
   "description": "Jarvis — local AI coding assistant CLI",
   "private": false,
   "type": "module",
@@ -65,8 +65,8 @@
     "@jarvis/rpc": "1.0.0",
     "@jarvis/types": "1.0.0",
     "@jarvis/typescript-config": "1.0.0",
-    "@jarvis/ui": "0.1.0",
-    "@jarvis/vitest-config": "1.0.0"
+    "@jarvis/vitest-config": "1.0.0",
+    "@jarvis/ui": "0.1.0"
   },
   "scripts": {
     "dev": "tsx watch src/bin.ts start --foreground",