@appchy/jarvis 0.1.120 → 0.1.122

package/harness/harness/gate.py

@@ -68,18 +68,15 @@ def _run_file(root) -> Path:
 
 
 def _alive(pid) -> bool:
-    """Whether the process that started a run is still there.
+    """Whether the process that started a run is still there — `peers.alive`, so the
+    lock and the peer scan cannot answer one question two ways.
 
     Liveness is the PID and never a clock. A lease would have to guess how long a
     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.
     """
-    try:
-        os.kill(int(pid), 0)
-    except (OSError, TypeError, ValueError):
-        return False
-    return True
+    return peers.alive(pid)
 
 
 def read_run(root):
@@ -120,12 +117,115 @@ def _write_run(root, data) -> None:
     p = _run_file(root)
     tmp = p.with_suffix(".tmp")
     try:
-        tmp.write_text(json.dumps(data, indent=2) + "\n")
+        tmp.write_text(_encode(data))
         os.replace(tmp, p)
     except OSError:
         pass
 
 
+def _encode(data) -> str:
+    """The run file's bytes. One definition, because the claim writes it straight into
+    an exclusively-created descriptor while every later update goes through the
+    rename above — two writers of one format is one of them drifting later."""
+    return json.dumps(data, indent=2) + "\n"
+
+
+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) -> tuple:
+    """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.
+
+    **Only "the file is already there" means somebody holds it.** Any other failure
+    to write is the harness's own problem — a directory that is not writable, a full
+    disk — and it is raised rather than folded into a refusal, because a caller told
+    *a verify is already running here (pid None)* would go looking for a session that
+    does not exist. A door that cannot tell its own failure from the caller's
+    situation must say which.
+
+    Returns `(claimed, holder)`. The holder comes back with the refusal because this
+    already read it to decide: making the caller read the file a third time to say
+    whose run it is was work done twice for one answer that cannot have changed.
+    """
+    p = _run_file(root)
+    try:
+        fd = os.open(p, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o644)
+    except FileExistsError:
+        # Built only once the slot is known to be takeable. `_begin` shells out for
+        # HEAD and reads the run file, and on a contended claim all of it was thrown
+        # away — wasted on exactly the path that happens when two sessions are busy.
+        held = live_run(root)
+        if held:
+            return False, held
+        _write_run(root, _begin(root, name, pid))
+        return True, None
+    with os.fdopen(fd, "w") as f:
+        f.write(_encode(_begin(root, name, pid)))
+    return True, None
+
+
 def _elapsed(data) -> int:
     try:
         return max(0, int((_now() - datetime.fromisoformat(str(data["started"]))).total_seconds()))
@@ -238,30 +338,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):
@@ -275,6 +369,12 @@ def _execute(root, name) -> tuple:
                 finished=_now().isoformat(), passed=ok, sha=sha,
                 results=[{"name": n, "status": s, "said": d, "log": g}
                          for n, s, d, g in results])
+    # A note about a vanished run for the item THIS run just recorded is spent: the
+    # item has a result now, and a record that says both is self-contradictory at
+    # rest. Cleared where it stops being true rather than stepped around by whoever
+    # reads it next, which is the only place that cannot be forgotten.
+    if (data.get("lost") or {}).get("task") == data.get("task"):
+        data["lost"] = None
     _write_run(root, data)
 
     if name and not _record(root, name, results, ok, sha):
@@ -298,19 +398,68 @@ def _print_report(results, sha) -> None:
                 print(f"  {line}")
 
 
-def _busy(running) -> str:
-    """Why a caller cannot start a verify, in the words the refused caller needs.
+def _where(run) -> str:
+    """Which gate a run had reached, as a fraction. Empty when its gate list is
+    unknown, which is the one case there is no fraction to state.
+
+    Shared by a live run and a dead one because it is one idea: a reader told only how
+    long ago something started cannot answer whether it is nearly over or has just
+    begun, and without that the only strategy left is to ask again on a timer.
+    """
+    done, gates = run.get("done") or [], run.get("gates") or []
+    return f"gate {len(done) + 1} of {len(gates)}" if gates else ""
+
+
+def _progress(running) -> str:
+    """How far through a live run is, with what it is doing and for how long."""
+    gate = running.get("current") or ""
+    return (f"{_where(running) or 'starting'}{f' ({gate})' if gate else ''}, "
+            f"{_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, asked: str = "", started: bool = True) -> str:
+    """The run holding this checkout, in the words the caller needs.
+
+    **One sentence for both doors**, because they state one policy and were drifting
+    apart the moment there were two of them: a caller that tried to START says "this
+    one did not start", and a caller that only ASKED says its own item has nothing —
+    and everything else, whose run it is, how far through, who to reach and the fact
+    that no place is being held, is the same either way.
 
     Never phrased as a failure. Two runs in one checkout corrupt each other's
     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)
+    mine = (running.get("task") or "") == asked
+    head = ("a verify is already running here" if started or mine
+            else "a verify is running in this checkout and it is not yours")
+    outcome = ("Two at once corrupt each other's result, so this one did not start."
+               if started else f"Nothing has run for '{asked or 'no task'}'.")
+    return (f"{head} — '{running.get('task') or 'no task'}', {_progress(running)} "
+            f"(pid {running.get('pid')}) on {running.get('machine') or 'this machine'}"
+            + (f", started by {who}" if who else "")
+            + f". {outcome} Nothing is holding your place — ask again, and start it then.")
 
 
 def _describe(data) -> str:
@@ -326,6 +475,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 +528,45 @@ 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 _idle(message, reason) -> int:
+    """Nothing usable has run for the caller's item, and why. One helper because every
+    such answer carries the same two fields and there are five reasons to give it."""
+    return _answer("idle", message, {"gates": sorted(VERIFY), "reason": reason})
+
+
+def _cannot_claim(error, outcome: str) -> str:
+    """The harness could not write the slot — said once, for both doors.
+
+    It exists to stop a caller reading the harness's own failure as another session's
+    lock, so it is the one message here that must not differ between the door that
+    blocks and the door that does not.
+    """
+    return (f"the verify slot could not be written, so nothing {outcome}: {error}. "
+            f"Nothing is holding it — this is the checkout, not another session.")
+
+
+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 +589,157 @@ 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'}')"
-        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)
-        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)})
-
-    return _answer(
-        "idle",
+        # 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:
+            out = _run_out(running)
+            done, gates = out["done"], out["gates"]
+            return _answer(
+                "running",
+                f"running {out['elapsedSeconds']}s: {out['gate'] or 'starting'}. "
+                f"{len(done)} of {len(gates)} done.",
+                {"gate": out["gate"], "elapsedSeconds": out["elapsedSeconds"],
+                 "gates": gates, "done": done, "results": _results_out(running),
+                 "run": out})
+        # 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, None, name)
+        said = _busy(running, asked=name, started=False)
+        return _answer("busy", said + (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, mine, 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)})
+        said, why = _stale(root.parent, mine)
+        return _answer("idle", said,
+                       {"commit": sha, "gates": sorted(VERIFY), "reason": why})
+
+    if lost:
+        return _idle(_gone(name, lost), "lost")
+
+    if mine and mine.get("read"):
+        return _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.", "read")
+
+    if done and done.get("finished"):
+        return _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.", "other")
+
+    return _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)})
+        f"explicitly — asking never starts a run.", "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.
+    """
+    where = _where(lost)
+    return (f"A verify for '{name or 'no task'}' started and stopped without "
+            f"recording anything"
+            + (f" — it was at {where}" if where else "")
+            + ". Nothing was written, so there is no result to read: start them again.")
+
+
+def _abandoned(done, mine, 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.
+
+    Two facts, not three. `mine` arrives already worked out, because "is this record
+    the caller's" is one question and deriving it again here made it three copies of
+    one comparison with nothing linking them. The note itself is retired by the run
+    that records a result, in `_execute` — so nothing has to be stepped around here.
+    """
+    if mine and not mine.get("finished") and not _alive(mine.get("pid")):
+        return mine
+    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) -> tuple:
+    """Why a finished result cannot be used, as `(sentence, reason)`.
+
+    **Both come out of one predicate**, because the sentence a person reads and the
+    word a program branches on must describe the same thing. Asking `_vanished` twice —
+    once here to pick the wording and once in the caller to pick the reason — cost two
+    git subprocesses and left nothing holding the two answers together if either call
+    ever drifted.
+
+    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."), "gone"
+    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}"), "moved"
 
 
 def _verify_start(root, name) -> int:
@@ -448,20 +751,31 @@ 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.
+    try:
+        claimed, held = _claim(root, name, os.getpid())
+    except OSError as e:
+        return _idle(_cannot_claim(e, "started"), "none")
+    if not claimed:
+        # `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(held, asked=name), {"run": _run_out(held)})
+
+    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 _idle(f"The gates could not be started: {e}", "none")
     return _answer(
         "started",
         f"Gates started ({len(VERIFY)}): {', '.join(sorted(VERIFY))}. They take "
@@ -472,20 +786,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.**
 
-    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
+    | 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.
+
+    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 +826,27 @@ 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.
+    try:
+        claimed, held = _claim(root, name, os.getpid())
+    except OSError as e:
+        print(f"error: {_cannot_claim(e, 'ran')}", file=sys.stderr)
+        return 1
+    if not claimed:
+        print(f"error: {_busy(held, asked=name)}", 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}'")