@appchy/jarvis 0.1.120 → 0.1.121

package/harness/harness/gate.py

@@ -74,9 +74,22 @@ def _alive(pid) -> bool:
     verify takes, and this repo's own set spans 174 seconds warm and far more cold —
     a guess short enough to be useful would strand a real run, and one long enough to
     be safe would not guard anything.
+
+    A pid somebody else owns answers `PermissionError`, and that is ALIVE — the kernel
+    refused to signal a process it confirmed exists. Reading it as dead let a second
+    run start over a live one, and it was also a second answer to the one question
+    `peers._live()` already answers this way: two readings of one pid is exactly the
+    kind of disagreement this file exists to remove.
     """
     try:
+        # Strictly positive: signal 0 to pid 0 asks about the whole process group and
+        # to a negative pid about another one, so either would answer "alive" about
+        # something that is not this run at all.
+        if int(pid) <= 0:
+            return False
         os.kill(int(pid), 0)
+    except PermissionError:
+        return True
     except (OSError, TypeError, ValueError):
         return False
     return True
@@ -126,6 +139,90 @@ def _write_run(root, data) -> None:
         pass
 
 
+def _begin(root, name, pid) -> dict:
+    """The record a run declares itself with, written before the first gate.
+
+    `session` and `head` are here so the two doors can answer questions the file
+    could not: who to go and talk to, and whether the ground moved while the gates
+    were running. Neither is load-bearing — a missing session degrades to saying
+    nothing about who, which is what an enrichment is allowed to do.
+    """
+    return {
+        "task": name,
+        "pid": pid,
+        "machine": peers.here(),
+        # The run belongs to a SESSION, not to the pid: the pid is a detached child
+        # that exits, and the session waiting for the answer is what outlives it.
+        "session": peers.me(),
+        "started": _now().isoformat(),
+        # The commit the gates STARTED on. `sha` below is where they ended, which is
+        # what the evidence records — and the two differ exactly when somebody
+        # committed mid-run, which is the thing nobody could see.
+        "head": _head(root.parent),
+        "gates": sorted(VERIFY),
+        "current": "",
+        "done": [],
+        "finished": None,
+        "passed": False,
+        "sha": "",
+        "results": [],
+        # Whether a finished result has already been handed to a caller. Reading one
+        # is what retires it: an agent that fixed something and asked again wants a
+        # fresh run, not the answer to the question it asked before the fix.
+        "read": False,
+        # The run this one replaced, when that run stopped without recording
+        # anything. Carried forward exactly one deep on purpose: the session whose
+        # run vanished needs to be told once, and keeping a chain of them would make
+        # this file a log of a thing that is over.
+        "lost": _lost(read_run(root)),
+    }
+
+
+def _lost(prior):
+    """A prior run that stopped without ever recording, as the little a reader needs.
+
+    A run whose process is gone and which never finished is the one case the file
+    itself cannot report afterwards, because starting the next run overwrites it —
+    and that is precisely how a session learns its gates vanished by noticing the
+    slot naming somebody else's item.
+    """
+    if not prior or prior.get("finished") or _alive(prior.get("pid")):
+        return None
+    return {k: prior.get(k) for k in
+            ("task", "session", "machine", "started", "current", "done", "gates")}
+
+
+def _claim(root, name, pid) -> bool:
+    """Take the checkout's one verify slot, or report that somebody holds it.
+
+    **Created exclusively, so two starts in the same instant cannot both win.** The
+    check-then-spawn this replaces left the slot unheld for the whole of a Python
+    interpreter's startup — hundreds of milliseconds, not an instant — and two
+    sessions polling the same board is exactly the traffic that finds a window that
+    wide.
+
+    A slot held by a run that is over is taken over rather than waited for, which is
+    the same fail-open `read_run` takes: a lock that outlives its process would
+    strand every future verify in the checkout. Two callers racing to take over one
+    DEAD slot can still both proceed, because breaking a stale lock needs an
+    authority a file cannot be; that residue is stated rather than pretended away.
+    """
+    p = _run_file(root)
+    data = _begin(root, name, pid)
+    try:
+        fd = os.open(p, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
+    except FileExistsError:
+        if live_run(root):
+            return False
+        _write_run(root, data)
+        return True
+    except OSError:
+        return False
+    with os.fdopen(fd, "w") as f:
+        f.write(json.dumps(data, indent=2) + "\n")
+    return True
+
+
 def _elapsed(data) -> int:
     try:
         return max(0, int((_now() - datetime.fromisoformat(str(data["started"]))).total_seconds()))
@@ -238,30 +335,24 @@ def _record(root, name, results, ok, sha) -> bool:
     return True
 
 
-def _execute(root, name) -> tuple:
+def _execute(root, name, adopt: bool = False) -> tuple:
     """Run the gates, tracking them in the run file, and record the outcome.
 
     **Both doors go through here**, which is what makes the guard mean anything: a
     blocking run that wrote no run file would be invisible to the next caller, and
     the overlap this exists to prevent is exactly the one nobody declared.
+
+    `adopt` is the detached child taking over the slot its parent claimed on its
+    behalf, rather than writing a second record over it. Recreating it would throw
+    away the claim's own start time and the note of whatever run it displaced — and
+    would reopen the window the claim exists to close, since between the parent's
+    claim and a fresh record there would be a moment holding neither.
     """
-    data = {
-        "task": name,
-        "pid": os.getpid(),
-        "machine": peers.here(),
-        "started": _now().isoformat(),
-        "gates": sorted(VERIFY),
-        "current": "",
-        "done": [],
-        "finished": None,
-        "passed": False,
-        "sha": "",
-        "results": [],
-        # Whether a finished result has already been handed to a caller. Reading one
-        # is what retires it: an agent that fixed something and asked again wants a
-        # fresh run, not the answer to the question it asked before the fix.
-        "read": False,
-    }
+    held = read_run(root) if adopt else None
+    if held and not held.get("finished"):
+        data = dict(held, pid=os.getpid())
+    else:
+        data = _begin(root, name, os.getpid())
     _write_run(root, data)
 
     def progress(gate, so_far):
@@ -298,6 +389,33 @@ def _print_report(results, sha) -> None:
                 print(f"  {line}")
 
 
+def _progress(running) -> str:
+    """How far through a run is, as a fraction a reader can act on.
+
+    A refusal saying only how long ago something started cannot answer the one
+    question the refused caller has — is this nearly over, or did it just begin — and
+    the only strategy left without it is to ask again on a timer.
+    """
+    done, gates = running.get("done") or [], running.get("gates") or []
+    gate = running.get("current") or ""
+    where = f"gate {len(done) + 1} of {len(gates)}" if gates else "starting"
+    return f"{where}{f' ({gate})' if gate else ''}, {_elapsed(running)}s in"
+
+
+def _whose(running) -> str:
+    """Who to go and talk to about the run holding the slot, or nothing at all.
+
+    Nothing at all is a real answer and is left empty rather than filled with a
+    hedge: a run recorded by a build that did not note its session, or a client that
+    publishes no session list, has nobody a reader could reach, and a line saying so
+    is noise on a message that is already refusing something.
+    """
+    who = str(running.get("session") or "")
+    if not who:
+        return ""
+    return peers.describe(who, str(running.get("machine") or ""))
+
+
 def _busy(running) -> str:
     """Why a caller cannot start a verify, in the words the refused caller needs.
 
@@ -305,12 +423,19 @@ def _busy(running) -> str:
     result — one gate's build cleans the directory another's log check is about to
     read — and the message a person meets has to say *that*, because the alternative
     reads as a broken build and teaches them to re-run until it goes green.
+
+    **It says plainly that nothing is holding your place**, because a refusal that
+    only describes the obstacle reads as a queue, and a caller that believes it is
+    queued waits for a call that will never come. Holding a place would be a
+    scheduler; saying honestly that there is none is a sentence (founder, 2026-09-12).
     """
-    return (f"a verify is already running here — '{running.get('task') or 'no task'}' "
-            f"on {running.get('machine') or 'this machine'}, "
-            f"{_elapsed(running)}s ago (pid {running.get('pid')}). "
-            f"Two at once corrupt each other's result, so this one did not start. "
-            f"Wait for it, or ask again.")
+    who = _whose(running)
+    return (f"a verify is already running here — '{running.get('task') or 'no task'}', "
+            f"{_progress(running)} (pid {running.get('pid')}) "
+            f"on {running.get('machine') or 'this machine'}"
+            + (f", started by {who}" if who else "")
+            + f". Two at once corrupt each other's result, so this one did not start. "
+              f"Nothing is holding your place — ask again, and start it then.")
 
 
 def _describe(data) -> str:
@@ -326,6 +451,12 @@ def _describe(data) -> str:
     return "\n".join([head] + [_failure(r) for r in failed])
 
 
+#: Every flag `verify` answers to — its own three doors, plus the ones every command
+#: here takes. Anything else is a typo or a caller built against a flag that has been
+#: renamed, and both are told rather than run.
+_DOORS = {"task", "start", "status", "detached", "project", "branch", "host"}
+
+
 #: How many of a failing gate's kept lines reach a CALLER, as opposed to the run
 #: file. Deliberately smaller: a caller pays for these in context on every failed
 #: verify, and the point here is to say enough that the next step is obvious without
@@ -373,12 +504,28 @@ def _answer(state, message, data=None) -> int:
     structured payload are the same computation rather than two.
     """
     out = {"state": state, "gate": "", "elapsedSeconds": 0, "gates": [], "done": [],
-           "passed": False, "commit": "", "results": [], "message": message}
+           "passed": False, "commit": "", "results": [], "message": message,
+           # WHY there is nothing to report, when there is nothing. One sentence for
+           # five causes is what made a held slot, a moved commit and a vanished run
+           # all read as "no gates have run" — and three of those are not the
+           # caller's doing in any sense.
+           "reason": "",
+           # The run holding this checkout, which is not necessarily the caller's.
+           # Every other field here is about the caller's ITEM; this one is about the
+           # CHECKOUT, and keeping them apart in the shape is what stops a true fact
+           # about the tree being read as a verdict on the work.
+           "run": None}
     out.update(data or {})
     print(json.dumps(out))
     return 0
 
 
+def _run_out(running) -> dict:
+    return {"task": running.get("task") or "", "gate": running.get("current") or "",
+            "done": running.get("done") or [], "gates": running.get("gates") or [],
+            "elapsedSeconds": _elapsed(running), "by": _whose(running)}
+
+
 def _results_out(data) -> list:
     return [{"name": r.get("name", ""), "passed": r.get("status") == "PASS",
              "skipped": r.get("status") == "SKIP", "said": r.get("said") or ""}
@@ -401,42 +548,158 @@ def _verify_report(root, name) -> int:
     """
     running = live_run(root)
     if running:
-        gate = running.get("current") or "starting"
-        done, gates = running.get("done") or [], running.get("gates") or []
-        for_task = running.get("task") or ""
-        whose = "" if for_task == name else f" (started for '{for_task or 'no task'}')"
+        # WHOSE run it is changes the answer, not merely its wording. A run proving
+        # somebody else's item leaves this caller with no evidence and no slot, which
+        # is a different situation from watching its own gates go — and reporting
+        # both as `running` is how a session read a held checkout as its own progress.
+        if (running.get("task") or "") == name:
+            gate = running.get("current") or "starting"
+            done, gates = running.get("done") or [], running.get("gates") or []
+            return _answer(
+                "running",
+                f"running {_elapsed(running)}s: {gate}. {len(done)} of {len(gates)} done.",
+                {"gate": gate, "elapsedSeconds": _elapsed(running), "gates": gates,
+                 "done": done, "results": _results_out(running),
+                 "run": _run_out(running)})
+        # Every gate-shaped field stays EMPTY. The caller has no run, and filling
+        # them with another item's progress is the misreading this state exists to
+        # make impossible.
+        #
+        # A run of the caller's OWN that vanished is told here too, and this is the
+        # branch that matters most: the session whose gates stopped without recording
+        # asks, finds the slot naming somebody else's item, and that is the whole of
+        # what it had to go on. Being behind a stranger's run and having lost your own
+        # are two facts, and it needs both.
+        lost = _abandoned(running, name)
         return _answer(
-            "running",
-            f"running {_elapsed(running)}s: {gate}. {len(done)} of {len(gates)} done.{whose}",
-            {"gate": gate, "elapsedSeconds": _elapsed(running), "gates": gates,
-             "done": done, "results": _results_out(running)})
-
-    done = read_run(root)
-    # A finished run answers for the commit it ran at and no other. Once the CODE
-    # moves, or once its answer has been read, it is history — and the next ask is a
-    # new run rather than yesterday's verdict handed over again.
-    #
-    # "Moved" is the completion gate's own definition, not string equality, and the
-    # difference is not academic: recording a result is itself a board commit, so a
-    # run in a repo with `git.commit` on always ends at a different HEAD than it
-    # started. Comparing shas directly meant every finished run looked stale to the
-    # very caller waiting for it, and `--async` answered "started" forever.
-    if (done and done.get("finished") and not done.get("read")
-            and done.get("task") == name
-            and _still_current(root.parent, done.get("sha") or "")):
-        done["read"] = True
-        _write_run(root, done)
+            "busy",
+            f"A verify is running in this checkout and it is not yours — "
+            f"'{running.get('task') or 'no task'}', {_progress(running)}"
+            + (f", started by {_whose(running)}" if _whose(running) else "")
+            + f". Nothing has run for '{name or 'no task'}', and nothing is holding "
+              f"your place — ask again once the slot is free."
+            + (f" {_gone(name, lost)}" if lost else ""),
+            {"run": _run_out(running), "reason": "lost" if lost else ""})
+
+    return _verify_verdict(root, name, read_run(root))
+
+
+def _verify_verdict(root, name, done) -> int:
+    """Where the caller's own item stands, once nothing is running.
+
+    A finished run answers for the commit it ran at and no other. Once the CODE
+    moves, or once its answer has been read, it is history — and the next ask is a
+    new run rather than yesterday's verdict handed over again.
+
+    "Moved" is the completion gate's own definition, not string equality, and the
+    difference is not academic: recording a result is itself a board commit, so a run
+    in a repo with `git.commit` on always ends at a different HEAD than it started.
+    Comparing shas directly meant every finished run looked stale to the very caller
+    waiting for it, and the starting door answered "started" forever.
+
+    **Every way of having no usable result says WHICH, and they are not variations of
+    one sentence.** Measured across three sessions in one checkout: a held slot, a
+    commit landing mid-run, a run whose process vanished and a result already handed
+    over all reported as *no gates have run for this item*. Three of the four are
+    nobody's mistake, and a caller told the same thing in all four cases can only
+    guess which it is looking at — which is what turned roughly three wasted
+    nine-gate runs a day into something nothing caught.
+    """
+    mine = done if done and (done.get("task") or "") == name else None
+    lost = _abandoned(done, name)
+
+    if mine and mine.get("finished") and not mine.get("read"):
+        sha = mine.get("sha") or ""
+        if _still_current(root.parent, sha):
+            mine["read"] = True
+            _write_run(root, mine)
+            return _answer(
+                "finished", _describe(mine),
+                {"elapsedSeconds": _elapsed(mine), "gates": mine.get("gates") or [],
+                 "done": mine.get("done") or [], "passed": bool(mine.get("passed")),
+                 "commit": sha, "results": _results_out(mine)})
+        return _answer("idle", _stale(root.parent, mine),
+                       {"commit": sha, "gates": sorted(VERIFY),
+                        "reason": "gone" if _vanished(root.parent, sha) else "moved"})
+
+    if lost:
+        return _answer("idle", _gone(name, lost),
+                       {"gates": sorted(VERIFY), "reason": "lost"})
+
+    if mine and mine.get("read"):
         return _answer(
-            "finished", _describe(done),
-            {"elapsedSeconds": _elapsed(done), "gates": done.get("gates") or [],
-             "done": done.get("done") or [], "passed": bool(done.get("passed")),
-             "commit": done.get("sha") or "", "results": _results_out(done)})
+            "idle",
+            f"The gates for '{name}' finished and that result has already been "
+            f"reported once — asking again does not re-run them. Start them again to "
+            f"prove the code as it stands now.",
+            {"gates": sorted(VERIFY), "reason": "read"})
+
+    if done and done.get("finished"):
+        return _answer(
+            "idle",
+            f"No gates have run for '{name or 'no task'}'. The last run in this "
+            f"checkout proved '{done.get('task') or 'no task'}', which says nothing "
+            f"about yours. Start them explicitly — asking never starts a run.",
+            {"gates": sorted(VERIFY), "reason": "other"})
 
     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)})
+        {"gates": sorted(VERIFY), "reason": "none"})
+
+
+def _gone(name, lost) -> str:
+    """A run of the caller's that stopped without recording, in its own words.
+
+    Said from two places — on its own when nothing is running, and appended to a held
+    slot — because the session it is addressed to reaches it either way and the fact
+    does not change with the company it keeps.
+    """
+    gates, at = lost.get("gates") or [], len(lost.get("done") or []) + 1
+    return (f"A verify for '{name or 'no task'}' started and stopped without "
+            f"recording anything"
+            + (f" — it was at gate {at} of {len(gates)}" if gates else "")
+            + ". Nothing was written, so there is no result to read: start them again.")
+
+
+def _abandoned(done, name):
+    """A run for `name` that stopped without recording — whether it is still the run
+    on disk, or was carried onto the one that replaced it."""
+    if done and (done.get("task") or "") == name and not done.get("finished") \
+            and not _alive(done.get("pid")):
+        return done
+    lost = (done or {}).get("lost")
+    return lost if isinstance(lost, dict) and (lost.get("task") or "") == name else None
+
+
+def _vanished(repo, sha: str) -> bool:
+    """Whether the commit a result named is no longer in this repo at all."""
+    return bool(sha) and sha != "no-git" and not git.has_commit(repo, sha)
+
+
+def _stale(repo, done) -> str:
+    """Why a finished result cannot be used, naming both commits.
+
+    A hash the reader cannot open is worse than no hash, so a commit that a push
+    rebased out of the history is said to be GONE rather than reported as the code
+    having moved: the code may well be identical, and the two call for different
+    next steps.
+    """
+    sha, head = (done.get("sha") or "")[:12], _head(repo)[:12]
+    ran = done.get("head") or ""
+    task = done.get("task") or "no task"
+    if _vanished(repo, done.get("sha") or ""):
+        return (f"The gates for '{task}' passed at {sha}, and that commit is no "
+                f"longer in this branch's history — a push rebased it away. The code "
+                f"it measured may be untouched, but nothing can be proven against a "
+                f"commit that is gone: start them again.")
+    drifted = (f" Those gates began at {ran[:12]} and ended at {sha}, so something "
+               f"was committed while they were running." if ran and not sha.startswith(ran[:12])
+               else "")
+    return (f"The gates for '{task}' ran at {sha} and the code has moved since — "
+            f"HEAD is {head}. That result does not describe what is in the tree now, "
+            f"so it cannot be used: start them again.{drifted}")
 
 
 def _verify_start(root, name) -> int:
@@ -448,20 +711,29 @@ def _verify_start(root, name) -> int:
     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"],
-        cwd=root.parent, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
-        stderr=subprocess.DEVNULL, start_new_session=True)
+    # The slot is taken BEFORE the child is spawned, and by this process, because a
+    # child cannot claim anything until a Python interpreter has finished starting —
+    # and a slot left open for those few hundred milliseconds is a slot two polling
+    # sessions will both walk through. The child adopts it and stamps its own pid.
+    if not _claim(root, name, os.getpid()):
+        running = live_run(root) or {}
+        # `busy` and never `running`: this caller has no run, and the fields that
+        # would describe one stay empty so the slot's state cannot be read as its own.
+        return _answer("busy", _busy(running), {"run": _run_out(running)})
+
+    try:
+        subprocess.Popen(
+            [sys.executable, os.path.abspath(sys.argv[0]), "verify", "--task", name,
+             "--detached"],
+            cwd=root.parent, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL, start_new_session=True)
+    except (OSError, subprocess.SubprocessError) as e:
+        # Nothing is going to run, so the slot is given back rather than left to
+        # expire with this process — a checkout that reads as busy for no reason is
+        # the failure this whole item is about.
+        _run_file(root).unlink(missing_ok=True)
+        return _answer("idle", f"The gates could not be started: {e}",
+                       {"gates": sorted(VERIFY), "reason": "none"})
     return _answer(
         "started",
         f"Gates started ({len(VERIFY)}): {', '.join(sorted(VERIFY))}. They take "
@@ -472,20 +744,39 @@ def _verify_start(root, name) -> int:
 def cmd_verify(args) -> int:
     """Execute the verify commands and RECORD the result against the task.
 
-    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.
+    Four doors, and **each is named for whether it starts anything.**
+
+    | door | starts a run |
+    |---|---|
+    | no flag | yes, here, printing the table when it is done |
+    | `--start` | yes, in the background, answering at once |
+    | `--status` | no — it only says where the run stands |
+    | `--detached` | the child `--start` spawns, and nobody else's to type |
+
+    The flag that starts in the background was called `--async` and is renamed
+    rather than aliased. It only ever started a run, but it READ like "ask me in the
+    background" — and a session polling with it set a fresh nine-gate run going every
+    time the previous one ended. `--start` cannot be misread, and matches what the
+    tool surface has always called the same thing.
 
-    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
+    Starting and asking 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()
+    # A flag this door does not know is REFUSED rather than ignored. The parser turns
+    # any `--word` into a flag, so an unread one fell through to the blocking door —
+    # meaning a caller that typed the wrong thing silently waited minutes for a run
+    # it never asked to start, which is the surprise every door here is being made to
+    # stop having. A typo and a renamed flag both land here and both say so.
+    unknown = sorted(set(args) - _DOORS)
+    if unknown:
+        die(f"jarvis work verify: unknown flag(s) {', '.join('--' + f for f in unknown)} "
+            f"— it takes a name, and one of --start (start them in the background), "
+            f"--status (only say where a run stands) or no flag at all (start them "
+            f"here and wait).")
     if not VERIFY:
         print("no `verify` commands configured — set them in "
               ".claude/work.config.json so completion has something to prove "
@@ -493,21 +784,22 @@ def cmd_verify(args) -> int:
         return 1
 
     if args.get("detached"):
-        _execute(root, name)
+        _execute(root, name, adopt=True)
         return 0
 
     if args.get("status"):
         return _verify_report(root, name)
 
-    if args.get("async"):
+    if args.get("start"):
         return _verify_start(root, name)
 
-    running = live_run(root)
-    if running:
-        print(f"error: {_busy(running)}", file=sys.stderr)
+    # The person's door claims the slot the same way the background one does, so
+    # neither can be the hole in a guard the other honours.
+    if not _claim(root, name, os.getpid()):
+        print(f"error: {_busy(live_run(root) or {})}", file=sys.stderr)
         return 1
 
-    results, ok, sha = _execute(root, name)
+    results, ok, sha = _execute(root, name, adopt=True)
     _print_report(results, sha)
     if name:
         print(f"  recorded on '{name}'")

package/harness/harness/git.py

@@ -590,6 +590,21 @@ def _left_alone(theirs) -> str:
             "to land.")
 
 
+def has_commit(repo, sha: str) -> bool:
+    """Is `sha` still a commit this repo holds?
+
+    A push that rebases rewrites the commits it moves, so a sha a gate run recorded
+    can stop existing while the code it measured is untouched. Everything that reads
+    a recorded sha needs to tell that apart from the code having changed: they are
+    opposite situations and the first one cannot be diagnosed from a hash a reader
+    cannot open.
+    """
+    if not sha or sha == "no-git":
+        return False
+    code, _, _ = _git(repo, "cat-file", "-e", f"{sha}^{{commit}}")
+    return code == 0
+
+
 def only_board_moved(repo, sha: str) -> bool:
     """Is everything between `sha` and HEAD a board file?
 

package/harness/presets/appchy/PRESET.md

@@ -441,7 +441,7 @@ the only way forward has hit a real gap: **park a question, do not shell out.**
 | Create a task | `jarvis work new <name> --epic <e> [--priority] [--depends] [--owner] [--code] [--covers]` | either — `work_create` is the tool |
 | List | `jarvis work list` | either — `work_list` is the tool |
 | Pick up / complete | `jarvis work move <name> in-progress\|complete --delivered "…" --not-included "…"` | either — `work_take` / `work_complete` |
-| Prove it | `jarvis work verify --task <name>` (blocks) · `--async` (what the tool uses) | either — `work_verify` |
+| Prove it | `jarvis work verify <name>` (blocks) · `--start` (what the tool uses) · `--status` (asks, starts nothing) | either — `work_verify` |
 | Record an approved plan | `jarvis work plan <name> [--file <path>]` | either |
 | Hand off | `jarvis work handoff <name>`, then fill it | either — **no tool yet**; the prose is judgement |
 | Open the NEXT session | `jarvis work kickoff <name>` — never hand-write the prompt | either — `work_wrap` embeds it |