taskops-cli 0.4.2__py3-none-any.whl → 0.5.1__py3-none-any.whl

taskops/_version.py

@@ -1,4 +1,4 @@
 from __future__ import annotations
 
 __title__ = "taskops"
-__version__ = "0.4.2"  # single source of truth; pyproject reads it dynamically
+__version__ = "0.5.1"  # single source of truth; pyproject reads it dynamically

taskops/gitwork/mirror.py

@@ -0,0 +1,132 @@
+"""The board's bare mirror — the forge's history, held so a host can answer.
+
+ARCHITECTURE §16 ("The hosted window") decided this on 2026-08-30: a board
+host MAY hold `<root>/<board>/mirror.git`, a bare `git clone --mirror` of the
+forge the owner declared with `board forge` — and only then does it answer
+`/git` and `/ui/`. The mirror is DERIVED and disposable in exactly the sense
+`cache.sqlite` is: delete it and `ensure` re-clones; nothing in it is truth
+the forge does not hold. Its ONLY source is that forge — it takes no client
+pushes, it is not a second trunk, and nothing here ever writes to it beyond
+what `clone` and `fetch` are.
+
+**The address is derived, never a credential.** The default remote is
+`https://<host>/<repo>.git`, spelled straight out of the declared fact
+(`core/forge.py` owns that shape) — an anonymous clone, which is all a public
+repo needs. A private repo is the owner's business: they point the mirror at
+an ssh remote backed by a deploy key on the host's filesystem (`url=` at
+clone time, or `git remote set-url` in a mirror that already exists), and
+this module neither knows nor stores anything about it. What §11 bans stays
+banned: no stored token, no write credential, no dev credential travelling.
+
+**Failures return None/False, never raise into a request.** These functions
+sit behind HTTP doors serving readers who cannot fix the host's network; a
+mirror that cannot answer is a stale page, not a 500. The same reasoning
+gave `remote.py::push` its 10-second budget, and `fetch` inherits the number:
+a refresh is never a gate, so it may never cost more than a moment. The one
+bounded on-demand fetch lives in `refresh_if_missing` — a requested ref that
+is absent buys exactly one fetch, then the answer is whatever is true, stale
+included. Answering stale beats blocking a page on a forge that is down.
+
+All subprocess goes through `run.py`, the one module allowed to import it —
+and `run.git` RAISES on a timeout (right for workers, wrong for a request),
+so the catch here is part of the contract, not belt-and-braces.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from . import run
+from ..core import forge as forge_facts
+from .._errors import TaskopsError
+
+__all__ = ["ensure", "fetch", "refresh_if_missing"]
+
+MIRROR = "mirror.git"
+"""§16's wording, verbatim: `<root>/<board>/mirror.git`, beside events.jsonl."""
+
+FETCH_TIMEOUT = 10.0
+"""`remote.py::PUSH_TIMEOUT`'s argument, pointing the other way: a refresh is
+never a gate. Worst case a reader waits ten seconds ONCE and gets the truth
+about this disk — which is what `gitdoor` answers anyway."""
+
+CLONE_TIMEOUT = 120.0
+"""A first clone moves the whole history, once, at mount time — not per
+request — so it gets `run.TIMEOUT`'s patience rather than `fetch`'s."""
+
+
+def _url(forge: object) -> str:
+    """The declared fact → the anonymous https remote, or "".
+
+    `forge_facts.understood` already collapses absent, cleared and
+    unintelligible to None, so an https URL is only ever built from a fact a
+    door would also act on. No token, no user@ — the address IS the whole
+    credential story for a public repo.
+    """
+    fact = forge_facts.understood(forge)
+    if fact is None:
+        return ""
+    return f"https://{fact['host']}/{fact['repo']}.git"
+
+
+def ensure(board_dir: Path, forge: object, *, url: str = "") -> Path | None:
+    """The mirror's path — cloning it into existence if this is the first ask.
+
+    An EXISTING `mirror.git` is returned untouched, whatever remote it holds:
+    that is how an owner's ssh remote (a deploy key's address) survives every
+    later call. `url=` overrides the derived address at clone time — the same
+    owner's move, and how tests clone from a local fixture instead of the
+    network. No forge and no url means no mirror, which is the state every
+    board is born in; a clone that fails leaves nothing behind, so the next
+    ask is a clean retry rather than a corpse mistaken for a mirror.
+    """
+    dest = board_dir / MIRROR
+    if dest.is_dir():
+        return dest
+    remote = url or _url(forge)
+    if not remote:
+        return None
+    try:
+        result = run.git("clone", "--mirror", remote, str(dest), timeout=CLONE_TIMEOUT)
+    except TaskopsError:
+        result = None  # timeout, or no git at all — a request never hears it
+    if result is None or not result.ok:
+        return None
+    return dest
+
+
+def fetch(mirror: Path) -> bool:
+    """One bounded fetch from the mirror's own remote. True means it ran clean.
+
+    A `--mirror` clone's fetch refspec already maps every ref one-to-one, so
+    plain `git fetch` IS the whole refresh — no refspec spelled here that
+    could drift from what clone configured. False covers everything a reader
+    cannot fix: a dead remote, a timeout, a directory that stopped being a
+    repo. The caller answers with what it has.
+    """
+    try:
+        return run.git("fetch", cwd=mirror, timeout=FETCH_TIMEOUT).ok
+    except TaskopsError:  # timeout, or no git at all — never the reader's problem
+        return False
+
+
+def _has(mirror: Path, ref: str) -> bool:
+    """`^{commit}` is load-bearing: bare `rev-parse --verify <40-hex>` answers
+    ok for ANY well-formed sha, present or not — a ref arriving as a full sha
+    (which is what a diff door holds) would always read as here."""
+    return run.git("rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}", cwd=mirror).ok
+
+
+def refresh_if_missing(mirror: Path, ref: str) -> bool:
+    """Is `ref` here — after at most ONE fetch if it was not?
+
+    §16's exact promise: a missing ref triggers one bounded on-demand fetch
+    before answering stale. A ref already present costs nothing — no network
+    touched, so a page over known history never waits on a forge. A ref still
+    absent after the fetch is answered False, truthfully: "not here" is the
+    truth about this disk, and the door already knows how to say so.
+    """
+    if _has(mirror, ref):
+        return True
+    fetch(mirror)
+    return _has(mirror, ref)

taskops/http/auth.py

@@ -52,8 +52,26 @@ def token_in(header: str, path: str) -> str:
     agent's client sends a header, a browser follows a link (`?token=`), and a
     newcomer redeems an invite (`?invite=`). One extractor, so a door added
     later — /feed, /git — cannot accidentally invent a second way in.
+
+    POST-MORTEM (shipped broken in 0.5.0, reported 2026-08-31): this used to be
+    `header.removeprefix("Bearer ").strip()`, and that one line made every
+    PUBLIC board unreadable from its own hosted page. The page's client sends
+    `Authorization: "Bearer " + token()` — with no token, the header reaches
+    the server as `Bearer` (the trailing space stripped in transit), the prefix
+    `"Bearer "` does not match, and the LITERAL STRING "Bearer" came back as
+    the token. `creds.check` then answered "unknown credential — run: taskops
+    join" to a reader who presented nothing at all. Anonymous reads worked only
+    when NO Authorization header was sent — which no browser client does. So:
+    scheme and value are parsed as separate whitespace-delimited fields, the
+    scheme case-insensitive per RFC 7235, and a bearer scheme with NO value is
+    NO credential presented — the query-string fallback and, behind it, the
+    anonymous gate still run. This is deliberately narrow: a header that
+    carries any actual value — wrong, expired, or under a scheme this server
+    never spoke — is a credential that WAS presented, and it refuses exactly as
+    it always has. "Unparseable" is not "anonymous".
     """
-    token = header.removeprefix("Bearer ").strip()
+    scheme, _, value = header.strip().partition(" ")
+    token = value.strip() if scheme.lower() == "bearer" else header.strip()
     if token:
         return token
     for part in path.partition("?")[2].split("&"):

taskops/http/gitdoor.py

@@ -11,12 +11,14 @@ there is no second credential system, and `server.py` checks the credential
 before this module is reached.
 
 **Whether the door exists at all is decided ONCE, at construction**, never
-re-derived per request: `Mounts` carries `repo: Path | None`. `taskops ui` sits
+re-derived per request (`http/repos.py` resolves it per board). `taskops ui` sits
 inside a repo (its root is `<repo>/.taskops`) and passes it; `taskops serve`
-sits in a boards directory and passes nothing, so every /git request there is a
-404 whose message SAYS which case it is — the UI reads those words and falls
-through its cascade (numstat → /git → the forge link → an honest sentence)
-rather than showing a dead pane. ARCHITECTURE.md §16.
+sits in a boards directory and passes nothing FOR A BOARD WITH NO DECLARED
+FORGE, so /git there is a 404 whose message says which case it is — the UI falls
+through its cascade rather than a dead pane. A declared forge may instead mount
+a bare read-only mirror (`<root>/<board>/mirror.git` — §16, "The hosted
+window"): `NO_REPO` means "no checkout here and no mirror for this board",
+never "this host can never read git".
 
 This module only routes and refuses. Everything about git is `gitwork/diff.py`,
 which is where the ref validation lives.
@@ -39,6 +41,7 @@ from typing import Any
 from pathlib import Path
 from urllib.parse import unquote
 
+from . import stale
 from ..core import reports
 from .._errors import NotFound, BadRequest
 from ..gitwork import diff, patch
@@ -46,26 +49,12 @@ from ..gitwork import diff, patch
 NO_REPO = (
     "this host serves boards, not a repository — it was started outside a "
     "checkout (taskops serve), so there is no clone here to read a diff from. "
-    "A host that sits in a repo (taskops ui) answers /git."
+    "A host that sits in a repo (taskops ui) answers /git; a board with a "
+    "declared forge answers from its mirror when the host can hold one."
 )
 
 SEPARATOR = "..."
 
-STALE = (
-    "{refs} not in your clone yet — `{fetch}` brings {them}. The board is shared and "
-    "the code is not: a card's branch reaches origin when it closes, and this "
-    "window reads only the checkout it stands in. Nothing is fetched for you."
-)
-"""The MISSING-REF case, in its own words. It is not an error and must not read
-like one: on a shared board most refs belong to somebody else's card, and until
-you fetch, "not here yet" is simply the truth about your disk. Naming the exact
-command is this codebase's habit — every refusal names the call that works —
-and it is also the reason nothing fetches on the reader's behalf: a background
-`git fetch` inside a read-only door would move a branch under a worktree
-somebody is sitting in."""
-
-SHA = "0123456789abcdef"
-
 NOT_A_REPORT = (
     "{path} is not a report. This door serves committed files under "
     f"{reports.DIR} and nothing else — it is not a file server, and a read "
@@ -97,24 +86,34 @@ TEXT = "text/plain"
 MARKDOWN = "text/markdown"
 
 
-def answer(repo: Path | None, tail: str, query: str) -> dict[str, Any]:
-    """The whole door. `tail` is the path after `<board>/git/`."""
+def answer(
+    repo: Path | None, tail: str, query: str, *, mirrored: bool = False
+) -> dict[str, Any]:
+    """The whole door. `tail` is the path after `<board>/git/`. `mirrored`
+    says the repo is the board's mirror (`http/repos.py`), which is the one
+    case a missing ref buys a bounded fetch (`http/stale.py`)."""
     if repo is None:
         raise NotFound(NO_REPO)
     kind, _, rest = tail.partition("/")
     path = _param(query, "path") or None
     if kind == "file" and rest:
-        return _file(repo, unquote(rest), path or "")
+        return _file(repo, unquote(rest), path or "", mirrored)
     if kind == "commit" and rest:
         ref = unquote(rest)
         found = diff.commit_range(repo, ref)
+        if found is None and stale.refreshed(repo, mirrored, [ref]):
+            found = diff.commit_range(repo, ref)
         if found is None:
-            raise NotFound(_stale(ref))
+            raise NotFound(stale.sentence(ref))
     elif kind == "compare" and SEPARATOR in rest:
         left, _, right = unquote(rest).partition(SEPARATOR)
         found = diff.compare_range(repo, left, right)
         if found is None:
-            raise NotFound(_stale(*(r for r in (left, right) if not diff.resolve(repo, r))))
+            missing = [r for r in (left, right) if not diff.resolve(repo, r)]
+            if stale.refreshed(repo, mirrored, missing):
+                found = diff.compare_range(repo, left, right)
+            if found is None:
+                raise NotFound(stale.sentence(*missing))
     else:
         raise BadRequest(
             "git/commit/<ref>, git/compare/<a>...<b>, or git/file/<rev>?path=<file>"
@@ -122,7 +121,7 @@ def answer(repo: Path | None, tail: str, query: str) -> dict[str, Any]:
     return patch.between(repo, found[0], found[1], path)
 
 
-def _file(repo: Path, rev: str, wanted: str) -> dict[str, Any]:
+def _file(repo: Path, rev: str, wanted: str, mirrored: bool) -> dict[str, Any]:
     """One committed file at a rev — read-only, shape-guarded, capped.
 
     Three walls, in this order: the path is a REPORT path (`under()`, which
@@ -144,8 +143,10 @@ def _file(repo: Path, rev: str, wanted: str) -> dict[str, Any]:
     if not diff.usable(path):
         raise BadRequest(ODD_SHAPE.format(path=path, dir=reports.DIR))
     sha = diff.resolve(repo, rev)
+    if sha is None and stale.refreshed(repo, mirrored, [rev]):
+        sha = diff.resolve(repo, rev)
     if sha is None:
-        raise NotFound(_stale(rev))
+        raise NotFound(stale.sentence(rev))
     got = patch.show(repo, sha, path)
     if got is None:
         raise NotFound(ABSENT.format(path=path, sha=sha[:12]))
@@ -160,26 +161,6 @@ def _file(repo: Path, rev: str, wanted: str) -> dict[str, Any]:
     }
 
 
-def _stale(*refs: str) -> str:
-    """Which refs are missing, and the one command that brings them.
-
-    A sha is asked for WITHOUT a refspec — `git fetch origin <40 hex>` is
-    refused by most servers unless they allow it — while a branch is named, so
-    the reader can paste the line and get exactly what the pane wanted."""
-    names = [ref for ref in refs if ref] or ["that ref"]
-    branches = [ref for ref in names if not _looks_like_a_sha(ref)]
-    many = len(names) > 1
-    return STALE.format(
-        refs=f"{' and '.join(names)} {'are' if many else 'is'}",
-        fetch=" ".join(["git fetch origin", *branches]),
-        them="them" if many else "it",
-    )
-
-
-def _looks_like_a_sha(ref: str) -> bool:
-    return len(ref) >= 7 and all(char in SHA for char in ref.lower())
-
-
 def _param(query: str, key: str) -> str:
     for part in query.split("&"):
         name, _, value = part.partition("=")

taskops/http/handler.py

@@ -1,7 +1,7 @@
 """The request handler — one method per door, split out of `server.py` so the
 router (the class) and the server's lifecycle (`BoardServer`, `serve`) each
-have room. What each route MEANS is `server.py`'s docstring; this file is only
-how one request travels through it.
+have room. What each route MEANS is `server.py`'s docstring; this file is
+only how one request travels through it (`routes.py` reads the path).
 """
 
 from __future__ import annotations
@@ -13,6 +13,8 @@ from http.server import BaseHTTPRequestHandler
 from . import rpc, feed, admin, login, static, gitdoor
 from .. import _clock
 from .auth import Credential, token_in, anonymous
+from .mounts import NAME
+from .routes import split
 from .._errors import BadRequest, TaskopsError
 from .._version import __version__
 
@@ -67,7 +69,10 @@ class Handler(BaseHTTPRequestHandler):
         elif tail.startswith("git/"):
             self._git(board, tail[4:])
         elif tail.startswith("ui"):
-            self._static(tail[2:])
+            self._static(board, tail[2:])  # 0.5.0's address, kept — links were pasted
+        elif self.mounts.ui is None and NAME.match(board) and (not tail or static.asset(tail)):
+            # the page at the board's OWN address; assets are a CLOSED set
+            self._static(board, tail)
         elif (page := static.at_root(self.mounts.ui, self.path)) is not None:
             self._send(200, *page)  # a WINDOW serves its page at the ROOT
         else:
@@ -121,14 +126,37 @@ class Handler(BaseHTTPRequestHandler):
         self._answer(lambda _: self._diff(board, rest))
 
     def _diff(self, board: str, rest: str) -> dict[str, Any]:
-        """Mounted from the LOCAL clone whether the board is local or remote —
-        that is the whole point of serving the window here (§16)."""
+        """A window answers from its own LOCAL clone; a serve-mode host from
+        the board's forge mirror — `repos.py` decides which, per board (§16)."""
         self.mounts.check(board)
         self._credential(board, "read")
-        return gitdoor.answer(self.mounts.repo, rest, self.path.partition("?")[2])
-
-    def _static(self, rest: str) -> None:  # `static.py` owns what it answers, and why
-        self._send(*static.answer(self.mounts.ui, rest))
+        repo, mirrored = self.mounts.repos.for_board(board)
+        return gitdoor.answer(repo, rest, self.path.partition("?")[2], mirrored=mirrored)
+
+    def _static(self, board: str, rest: str) -> None:
+        """The page — at the board's own root since tk-32d2ba, and still at
+        /ui/, the 0.5.0 address (kept: links were pasted). A WINDOW serves
+        its bundle to whoever reaches the port, unchanged. A serve-mode HOST
+        serves the SAME packaged bundle for a board
+        whose owner declared a forge (`repos.backed` — the fact, never a clone),
+        behind the credential /rpc asks for: public board, anonymous READ;
+        private board, the join refusal. The 410 comes BEFORE the credential on
+        purpose — it says nothing about the board a login would guard, and the
+        no-forge sentence predates keys on this door. A GET here runs no verb,
+        so an anonymous page load writes nothing — no presence row (§11)."""
+        if self.mounts.ui is not None:
+            self._send(*static.answer(self.mounts.ui, rest))
+            return
+        try:
+            self.mounts.check(board)
+            if not self.mounts.repos.backed(board):
+                self._send(*static.answer(None, rest))
+                return
+            self._credential(board, "read")
+        except TaskopsError as err:
+            self._fail(rpc.status_for(rpc.failure(err)), err)
+            return
+        self._send(*static.answer(static.PACKAGED, rest))
 
     # ── plumbing ────────────────────────────────────────────────────────────
 
@@ -170,9 +198,3 @@ class Handler(BaseHTTPRequestHandler):
 
     def _fail(self, status: int, err: TaskopsError) -> None:
         self._json(status, rpc.failure(err))
-
-
-def split(path: str) -> tuple[str, str]:
-    clean = path.partition("?")[0].strip("/")
-    board, _, tail = clean.partition("/")
-    return board, tail

taskops/http/mounts.py

@@ -11,9 +11,10 @@ import re
 from pathlib import Path
 from threading import Lock
 
-from . import feed, watcher
+from . import feed, static, watcher
 from .. import verbs, _clock
 from .login import Host
+from .repos import Repos
 from ..verbs import project
 from .._errors import NotFound, BadRequest
 from .upstream import Upstream, seq_of
@@ -22,8 +23,6 @@ from ..store.stores import Stores
 
 NAME = re.compile(r"^[a-z0-9][a-z0-9-]{0,39}$")
 
-_PACKAGED_UI = Path(__file__).resolve().parent.parent / "ui"
-
 class Mounts:
     """The boards this process serves, opened once and kept.
 
@@ -45,16 +44,16 @@ class Mounts:
     ) -> None:
         self.root = root
         self.upstream = upstream
-        # The ONE place that decides whether this process can read a repo, and
-        # it is decided by the CALLER at construction, never sniffed per
-        # request (`gitdoor.py` carries the rest).
+        # Whether this process can read a repo is decided by the CALLER at
+        # construction — a window's own checkout — or, on a serve-mode host,
+        # per BOARD from its declared forge's mirror (`repos.py` carries it).
         self.repo = repo
-        # ONE switch, not two: the same `repo` that mounts /git mounts the bundle. A
-        # dashboard needs the viewer's CLONE to draw a diff, so a process with no clone
-        # has no business serving one — see `static.py` for the whole post-mortem. The
-        # bundle still ships inside the wheel; what went away is the server-side mount
-        # and the `--ui` flag that configured it.
-        self.ui = _PACKAGED_UI if repo is not None else None
+        self.repos = Repos(root, repo, self.stores)
+        # ONE switch, not two: the same `repo` that mounts /git mounts the bundle at
+        # the WINDOW's root. On a serve-mode host `ui` stays None and the /ui door asks
+        # `repos.backed()` per board instead — the forge fact, the same one that opens
+        # /git — see `static.py` and `repos.py` for the whole argument.
+        self.ui = static.PACKAGED if repo is not None else None
         self.credentials = Credentials(root / "live.sqlite")
         # The HOST's own identity, and it opens NOTHING until a login asks
         # (`login.py::Host` says why lazily is a rule here, not a taste).

taskops/http/repos.py

@@ -0,0 +1,98 @@
+"""Which repo answers /git for a board — the window's checkout, or a mirror.
+
+`Mounts.repo` used to be the WHOLE answer: one `Path | None` decided at
+construction, `taskops ui` passing its checkout and `taskops serve` passing
+nothing. §16's hosted window keeps the spirit — the switch is still a decided
+fact, never a per-request sniff — but on a serve-mode host the fact is per
+BOARD: the forge its owner declared (`core/forge.py`, read through the one
+reader `verbs/project.py::forge`). A board with one gets
+`gitwork/mirror.ensure()` lazily, resolved once and cached the way `Mounts`
+caches stores; a board without one is refused with the door named, because a
+refusal that does not say `taskops board forge` strands the reader in a 404.
+
+The WINDOW case is unchanged and deliberately first: a host constructed with a
+checkout answers from it for every board, and no mirror is ever consulted —
+the local clone is the reader's own truth, mirrors are the host's.
+
+The second half of the answer is `mirrored`: `gitdoor` may buy a missing ref
+ONE bounded fetch on a mirror (`http/stale.py`), and must never do that to a
+window's clone — a background fetch inside a read-only door would move a
+branch under a worktree somebody is sitting in.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+from pathlib import Path
+from threading import Lock
+
+from ..verbs import project
+from .._errors import NotFound
+from ..gitwork import mirror
+from ..store.stores import Stores
+
+NO_FORGE = (
+    "this host serves boards, not a repository — it was started outside a "
+    "checkout (taskops serve), and board {board!r} declares no forge to hold a "
+    "mirror of. `taskops board forge <owner>/<repo>` is the door: the declared "
+    "forge is the one source this host may mirror, read-only."
+)
+"""The serve-mode refusal, naming the move that opens it (§16: the refusal
+names the door). It replaces the old blanket NO_REPO here because on a board
+host "no repo" is a board-level fact with a board-level remedy."""
+
+
+class Repos:
+    """Per-board repo resolution for one server process.
+
+    `checkout` is the construction-time window repo, exactly as `Mounts.repo`
+    was; `stores` is `Mounts.stores`, so the forge fact is read from the same
+    open board every other door reads. The cache holds only RESOLVED mirrors:
+    a refusal is re-derived per ask (the fact may be declared any moment), and
+    a failed clone leaves nothing behind, so the next ask is a clean retry.
+    """
+
+    def __init__(
+        self, root: Path, checkout: Path | None, stores: Callable[[str], Stores]
+    ) -> None:
+        self.root = root
+        self.checkout = checkout
+        self._stores = stores
+        self._lock = Lock()
+        self._mirrors: dict[str, Path] = {}
+
+    def for_board(self, name: str) -> tuple[Path | None, bool]:
+        """`(repo, mirrored)` — the repo /git reads for this board, and whether
+        it is a mirror (which is what licenses the one on-demand fetch)."""
+        if self.checkout is not None:
+            return self.checkout, False
+        with self._lock:
+            found = self._mirrors.get(name)
+        if found is not None:
+            return found, True
+        fact = project.forge(self._stores(name))
+        if fact is None:
+            raise NotFound(NO_FORGE.format(board=name))
+        made = mirror.ensure(self.root / name, fact)
+        if made is None:  # clone failed or impossible — gitdoor says NO_REPO
+            return None, False
+        with self._lock:
+            self._mirrors[name] = made
+        return made, True
+
+    def backed(self, name: str) -> bool:
+        """Does a window open for this board here — the FACT, never the mirror.
+
+        /ui asks this instead of `for_board` on purpose: the page it serves is
+        the package's own bundle (`static.PACKAGED`), so its bytes need no repo
+        at all — resolving one would put a network clone in front of
+        `index.html` for nothing, and a clone that FAILS (forge down, key
+        missing) would take the page down with it. The declared forge alone
+        opens the door; the page's own /git calls go through `for_board` and
+        resolve the mirror lazily the moment a diff is actually read — which is
+        also where a resolution failure belongs: on the diff pane, in
+        gitdoor's words, not on the page load. A window's checkout answers for
+        every board, exactly as `for_board`'s first clause does."""
+        if self.checkout is not None:
+            return True
+        return project.forge(self._stores(name)) is not None

taskops/http/routes.py

@@ -0,0 +1,32 @@
+"""Where a request path splits into `(board, tail)` — ONE function, shared by
+GET and POST so the two methods cannot disagree about what a path names. Split
+out of `handler.py` at the seam that owns no HTTP at all (this module sees
+strings, never sockets), because the handler sits on the ≤200-line budget
+`tests/test_architecture.py` enforces.
+
+`api/` is stripped HERE, once. Since the board's own address became the page
+(tk-32d2ba), the machine doors — rpc, git, feed, invite/redeem — also answer
+under `/<board>/api/…`, which is the spelling the page uses from now on.
+Stripping in the split rather than per door means every door gets both
+spellings and none can drift: `/<board>/api/rpc` IS `/<board>/rpc` — same
+handler, same credential, same words. The 0.5.0 spellings stay, unprefixed,
+because agents, the MCP client, `taskops ui`'s upstream forward and four
+legacy production boards speak them today.
+
+The prefix cannot shadow a page asset: the packaged bundle's filenames are a
+CLOSED SET and none of them is named `api` (`static.asset` argues the same
+fact from the router's other side). And the ROOT is untouched — `/login`,
+`/rpc` and `/healthz` are one segment, so the strip, which lives in the TAIL,
+never sees them; a board named `api` still answers at `/api/…` because the
+strip runs after the board segment is taken.
+"""
+
+from __future__ import annotations
+
+
+def split(path: str) -> tuple[str, str]:
+    clean = path.partition("?")[0].strip("/")
+    board, _, tail = clean.partition("/")
+    if tail.startswith("api/"):
+        tail = tail[4:]
+    return board, tail

taskops/http/stale.py

@@ -0,0 +1,62 @@
+"""The MISSING-REF case, in its own words — and the one fetch a mirror buys.
+
+Split out of `gitdoor.py` when the mirror chapter pushed it past the module
+budget: this is the cohesive seam, because everything here is about one
+question — a ref the repo lacks — and nothing here routes or reads git ranges.
+
+It is not an error and must not read like one: on a shared board most refs
+belong to somebody else's card, and until you fetch, "not here yet" is simply
+the truth about your disk. Naming the exact command is this codebase's habit —
+every refusal names the call that works — and it is also the reason nothing
+fetches on a WINDOW's behalf: a background `git fetch` inside a read-only door
+would move a branch under a worktree somebody is sitting in. A MIRROR is the
+host's own derived copy with nobody sitting in it, so there — and only there —
+a missing ref buys exactly one bounded fetch before the stale sentence
+(`gitwork/mirror.py::refresh_if_missing`, §16's promise).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..gitwork import mirror
+
+STALE = (
+    "{refs} not in your clone yet — `{fetch}` brings {them}. The board is shared and "
+    "the code is not: a card's branch reaches origin when it closes, and this "
+    "window reads only the checkout it stands in. Nothing is fetched for you."
+)
+
+SHA = "0123456789abcdef"
+
+
+def refreshed(repo: Path, mirrored: bool, refs: list[str]) -> bool:
+    """True when a fetch may have brought the missing refs — retry the read.
+
+    Only the FIRST missing ref pays: `refresh_if_missing` runs at most one
+    fetch, and a mirror's fetch brings every ref at once, so the caller's
+    retry covers the rest. `mirrored` False is the window's clone and answers
+    False without touching the network, which is the §16 sentence above."""
+    if not mirrored or not refs:
+        return False
+    return mirror.refresh_if_missing(repo, refs[0])
+
+
+def sentence(*refs: str) -> str:
+    """Which refs are missing, and the one command that brings them.
+
+    A sha is asked for WITHOUT a refspec — `git fetch origin <40 hex>` is
+    refused by most servers unless they allow it — while a branch is named, so
+    the reader can paste the line and get exactly what the pane wanted."""
+    names = [ref for ref in refs if ref] or ["that ref"]
+    branches = [ref for ref in names if not _looks_like_a_sha(ref)]
+    many = len(names) > 1
+    return STALE.format(
+        refs=f"{' and '.join(names)} {'are' if many else 'is'}",
+        fetch=" ".join(["git fetch origin", *branches]),
+        them="them" if many else "it",
+    )
+
+
+def _looks_like_a_sha(ref: str) -> bool:
+    return len(ref) >= 7 and all(char in SHA for char in ref.lower())