taskops-cli 0.4.1__tar.gz → 0.5.0__tar.gz

{taskops_cli-0.4.1 → taskops_cli-0.5.0}/ARCHITECTURE.md

@@ -1012,7 +1012,8 @@ Both remaining items are done. The migration ran against all four v1 boards
 directory of board logs, so it is `pip install` into a venv and one pm2 entry
 (README, "Deployed"). **The box runs this tree** since 2026-08-09 (tk-df8e64,
 §17), so `https://taskops.bernardocastro.dev/<board>/ui/` answers `410` and one
-sentence, exactly as the trunk does (§16, §17). Re-derivable:
+sentence, exactly as the trunk does (§16, §17) — until a board with a declared
+forge gets its hosted window (§16, "The hosted window"). Re-derivable:
 `curl -s https://taskops.bernardocastro.dev/healthz` and
 `curl -w '%{http_code}' https://taskops.bernardocastro.dev/axion/ui/`
 — measured `{"boards": 4}` (after all four boards had been addressed through
@@ -1361,7 +1362,17 @@ files that answer it:
 * **the card dossier drawer**, opening over Monitor and Board through `App`'s
   `openCard` — it renders the acceptance criteria no v1 screen ever drew, and
   carries the UI's ONE write, the comment box with its mention picker
-  . The header's milestone picker scopes every tab at once.
+  . The header's milestone picker scopes every tab at once, and **"all
+  chapters" is an ARGUMENT** — `milestone=*` (`core/types.py::EVERYTHING`), not
+  the absence of one. It sent nothing for a wave, which the server reads as
+  "resolve the scope yourself" and resolves to the single open chapter: the page
+  arrived narrowed to that chapter with the ✓ sitting on "all chapters" the whole
+  time, and clicking the option changed no argument (2026-08-18). Absence still
+  means exactly that — it is the dashboard's OPENING state, and `App::scopeOf`
+  resolves it against the chapter the answer came back scoped to, so the ✓ marks
+  the scope the page is actually drawn at. `verbs/activity.py` refuses `*` in the
+  words of its own doors: a story is one chapter's cards by definition.
+  `ui/smoke/sections/all-chapters-scope.tsx`.
 
 * **the comment toasts**, a stack bottom-right over every tab
   (`ui/src/components/toasts/`), because the UI's one write was invisible to
@@ -1495,15 +1506,18 @@ construction and never sniffed per request** (`Mounts(repo=…)`,
 | `taskops serve` | a directory of boards, no checkout | **404 with the reason spelled out**, and nothing faked | **410 and one sentence** |
 
 The `/ui/` column arrived later, and it is the same `repo` deciding both — see
-"API ONLY is now literal" below.
+"API ONLY is now literal" below. Both cells of the `serve` row are narrowed a
+second time by "The hosted window" below: a board that DECLARED a forge may be
+answered from a bare read-only mirror of it, and only then.
 
 A viewer meets that gap whenever this clone cannot answer — a ref not fetched
 yet, a shallow checkout, a commit from before this repo had the branch — and
 there the UI's declared cascade takes over: numstat from the event → patch from
 /git → the forge link if a slug exists → one honest sentence. No dead anchor, no
 empty pane pretending. (The gap used to have a second, worse shape: a browser
-with no clone at all, pointed at the hosted page. There is no hosted page any
-more — see below.)
+with no clone at all, pointed at the hosted page. That page was withdrawn — see
+below — and comes back only standing on a real history: the forge mirror, in
+"The hosted window".)
 
 That cascade is ONE function — `ui/src/links.tsx::cascade`, beside the slug and
 the link templates it already owned — and `ui/src/components/card/Patch.tsx`
@@ -1585,9 +1599,11 @@ doubled separator and the directory itself, and never repairs one: a traversal
 normalised into something acceptable is the bug. Anything outside
 `.taskops/reports/` is a 400 that names the directory, and `tests/test_topology.py`
 walks every shape (a real secret one directory up included, asserting its
-contents appear nowhere in the answer). `taskops serve` still mounts no `/git`
-at all: the switch is `Mounts.repo`, decided once at construction, and a new
-question underneath it opens no door.
+contents appear nowhere in the answer). `taskops serve` mounts no `/git`
+from a checkout it does not have: the switch is `Mounts.repo`, decided once at
+construction, and a new question underneath it opens no door. The hosted-window
+amendment below changes what `repo` may point AT — a bare mirror of the
+declared forge — never the switch itself.
 
 ### The window: `taskops ui` serves locally even for a REMOTE board (2026-08-08)
 
@@ -1626,7 +1642,7 @@ The routes do not change, so the committed bundle is untouched by any of this:
 decision). The server used to serve the bundle too, from a `--ui` flag with a
 packaged default — so the box above answered `/ui/` with a real dashboard, and
 that dashboard could not draw a single patch, because the machine it was served
-from deliberately has no clone. It was a degraded window presented as *the*
+from deliberately had no clone. It was a degraded window presented as *the*
 window; the redirect above merely pointed people at it. **The binary serves the
 window; the server serves the truth.**
 
@@ -1634,7 +1650,9 @@ So: `Mounts.ui` is not a parameter, it is `repo`'s shadow — one construction-t
 switch mounts `/git` AND the bundle, and only a process standing in a checkout
 has either. `/ui/` on a board host answers `static.py::NO_UI` as plain text with
 **410 Gone**, not 404: 404 says "no idea, maybe later", and this page was
-withdrawn on purpose and is never coming back to a host with no clone. Plain
+withdrawn on purpose and is never coming back to a host with no clone — and a
+host holding the board's forge MIRROR is no longer that host ("The hosted
+window", below). Plain
 text and not the JSON envelope because the only reader who reaches that door is
 a human with a browser. The `--ui` flag is REMOVED, not deprecated: there is no
 command line that puts the decision back. The bundle still ships inside the
@@ -1659,6 +1677,21 @@ local process**; the browser holds only the token `taskops ui` mints into
 `ui.json`, which is local and revocable. `tests/test_topology.py` searches every
 served byte, and their headers, for the team token.
 
+**A SESSION RUNS OUT AND THE WINDOW DOES NOT** (2026-08-18). A host session is
+twelve hours (`http/login.py::SESSION_TTL`), and a window is a thing you leave
+open: `_upstream` read the token lying in `remote.json` and `Upstream` held it
+for the life of the process, so the morning after, every read answered "that
+credential expired" — and the habit that taught was `taskops join`, a human
+re-pasting a credential the machine can mint itself, which is the exact thing
+the session chapter exists to end. Two halves, both fixed: the command opens
+with `session.fresh`, like every other command has since that chapter landed,
+and the window is handed `session.refresher` so it can sign in AGAIN mid-flight
+— `board.py::RemoteBoard.call`'s retry, narrow for the same reason (the server
+said `EXPIRED`, this process holds a key). A window with no way back in — a
+standing bearer, a public viewer — is unchanged: `refresh` is None and nobody
+replaces a token behind its owner's back (`session.py`). `Upstream` still knows
+nothing about keys or files: it is handed a callable.
+
 **A refusal from the remote arrives in the SERVER's own words**, status and all:
 `upstream.py` returns `(status, bytes)` and re-wraps only a body that is not an
 envelope. A board that says "held by agent:berna/w1" with a 409 must not reach
@@ -1684,6 +1717,66 @@ move a branch under a worktree somebody is sitting in.
 
 A repo joined to nothing behaves exactly as it did.
 
+### The hosted window: the host may hold a MIRROR of the declared forge (decided 2026-08-30)
+
+The first amendment narrowed "no server reads a repo" to "a host that sits in a
+repo may read it". This one narrows the other clause — *the server deliberately
+has no clone* — and, as before, the change is recorded here rather than quietly
+made:
+
+> **A board host MAY hold a bare, READ-ONLY mirror of the board's DECLARED
+> forge — and only then does it answer `/git` and `/ui/`.** A board with no
+> declared forge is exactly what it was: 404 on `/git`, 410 on `/ui/`, each
+> refusal naming `taskops board forge <owner>/<repo>` as the door.
+
+Why this is not the degraded window "API ONLY" withdrew. That window's flaw was
+never that a server drew a dashboard — it was that the machine drawing it had
+NO git at all, so every diff fell through the whole cascade to a forge link or
+a sentence, a blank presented as *the* window. The mirror removes the flaw, not
+the caution: it is **the same history the forge already holds** — `git clone
+--mirror` of the repo the owner declared with `board forge`, refreshed by ONE
+bounded on-demand fetch when a requested ref is missing, then answered stale
+rather than blocking — so a diff served from it is the diff GitHub would show,
+read by the same `gitwork/diff.py` doors, behind the same visibility rules as
+`/rpc`. And the dev-side story does not move an inch: `taskops ui` still serves
+the window from the checkout it stands in, reading the dev's OWN clone,
+including refs the forge has never seen. The hosted window is for the reader
+who has no clone — the case the local window, by construction, cannot serve.
+
+**Where it lives**: `<root>/<board>/mirror.git`, a bare repo beside the board's
+`events.jsonl` — later cards follow this wording. It is DERIVED and disposable
+in exactly the sense `cache.sqlite` is: delete it and it re-clones from the
+declared forge; nothing in it is truth the forge does not hold. Its ONLY source
+is that forge. It takes no client pushes — the host still exposes no receive
+door of any kind — and it is not a second trunk: nothing lands there, nothing
+is read back into the log from it, and `taskops_merge` still happens in the
+dev's shared checkout.
+
+**The credential story** is §19's, unchanged in kind. A public repo needs no
+credential at all. A private repo is fetched with an **ssh deploy key on the
+host's filesystem** — read-only, minted and installed by the OWNER, revocable
+on the forge like any deploy key — which is the ONE new credential this chapter
+adds, and it is the owner's business exactly as `board forge` itself is. What
+remains banned is what §11 and §19 already ban: a stored GitHub token (the
+mirror's remote is an address, never a token), a write credential in any form,
+GitHub as a second identity system, and any dev credential travelling to the
+host — nobody's `gh auth token` is involved, because the owner already declared
+the repo and the mirror pulls from the outside like any anonymous (or
+deploy-keyed) clone.
+
+**Still banned, spelled out**: client pushes to the host and git replication
+between clones (the mirror replicates FROM the forge, one direction, and no
+clone ever pushes to it); a write credential on the host; a second trunk; a
+`--ui` flag or any per-request sniffing (whether the mirror exists is decided
+at mount time, the same `Mounts.repo` switch, now pointable at `mirror.git`);
+and anonymous writes — a public board's hosted window is a READ, and it leaves
+no `presence` row.
+
+So `static.py::NO_UI` and `gitdoor.py::NO_REPO` change meaning, not words of
+intent: each stops saying "this host never has a repo" and starts saying "this
+BOARD declared no forge, so this host holds no mirror to read from" — a state
+the owner ends with one `taskops board forge`. The refusal still names the door.
+
 ### A concept named by two cards is a seam — the fan-out rule, third notch
 
 `gitwork/remote.py` was born TWICE in one wave: two workers, each over the
@@ -1778,7 +1871,9 @@ request (`http/mounts.py::stores`), so a just-restarted process says `1`, not
 
 **That md5-of-the-served-bundle check is history, not the procedure any more.**
 Since §16's "API ONLY" amendment the host serves no bundle: `/<board>/ui/`
-answers `410` and one sentence, so there is nothing at the domain to md5. The
+answers `410` and one sentence (until the hosted-window chapter deploys a board
+whose forge is declared — §16, "The hosted window"), so there is nothing at the
+domain to md5. The
 wheel is still checked for its markers *before* it ships — it is the same wheel
 teammates install to get `taskops ui` — and the domain is verified by DATA,
 through `/rpc`.

{taskops_cli-0.4.1 → taskops_cli-0.5.0}/CHANGELOG.md

@@ -3,6 +3,83 @@
 The source of truth for release notes — GitHub Releases are extracted from
 here, never written twice.
 
+## 0.5.0 — the hosted window
+
+- **A board can be READ without a clone.** Until now the dashboard was only ever
+  served by `taskops ui`, a binary standing in a checkout: a host running
+  `taskops serve` answered `/git` with a 404 and `/ui/` with a 410, because a
+  dashboard draws DIFFS and the host deliberately had no repository to read them
+  from. Serving a page that could not draw a single patch was a degraded window
+  presented as *the* window, so it was withdrawn. That reasoning had one
+  unexamined premise — that the host can never have git — and this release
+  removes it, argued in ARCHITECTURE §16 ("The hosted window") before a line of
+  code moved.
+- **The host may hold a bare, READ-ONLY mirror of the board's DECLARED forge**,
+  at `<root>/<board>/mirror.git`, 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 it re-clones; nothing in it is truth the
+  forge does not already hold. Its ONLY source is the repo the owner declared
+  with `taskops board forge` — it takes no client pushes, it is not a second
+  trunk, and nothing is ever read back into the log from it.
+- **A board that declared no forge is exactly what it was**: 404 on `/git`,
+  410 on `/ui/`, and each refusal now names the door — `taskops board forge
+  <owner>/<repo>` — instead of stranding the reader in a sentence about a host
+  they cannot change.
+- **No new credential type.** A public repo is mirrored anonymously; a private
+  one is fetched with an ssh deploy key on the host's filesystem, installed by
+  the OWNER, revocable on the forge — the one new credential this chapter adds,
+  and it is the owner's business exactly as `board forge` itself is. No stored
+  GitHub token, no dev credential travelling, no second identity system.
+- **The page opens on the FACT, never on a clone.** `/ui/` is granted by the
+  declared forge alone: the bundle's bytes come from the installed package, so
+  putting a network clone in front of `index.html` would take a static page down
+  whenever the forge is unreachable. The mirror resolves lazily the moment a
+  diff is actually read — which is where a failure belongs, in the diff pane, in
+  the door's own words.
+- **A missing ref buys exactly ONE bounded fetch**, then answers stale rather
+  than blocking a page on a forge that is down — and only on a mirror. A
+  window's own clone still fetches nothing on the reader's behalf: a background
+  fetch inside a read-only door would move a branch under a worktree somebody is
+  sitting in.
+- **Reads stay reads.** `/ui/` sits behind the credential `/rpc` asks for —
+  a `public` board serves the page to an anonymous reader, a private one refuses
+  with the same join sentence — and an anonymous page load writes nothing at
+  all, not even the invisible write: no presence row.
+
+## 0.4.2 — the filter that filtered nothing, and the window that stopped signing in
+
+- **"All chapters" is an ARGUMENT now, and it really shows every chapter.** The
+  option sent no `milestone=` at all — and an absent milestone never meant "the
+  whole board": it means "server, resolve the scope yourself", which resolves to
+  the single open chapter when there is exactly one. So on a board with one
+  chapter open and seven landed (Berna's, reported 2026-08-18) the page came back
+  narrowed to that chapter, the menu drew its ✓ beside a scope that had never
+  been in effect, and clicking the option changed no argument at all — the only
+  way to see other work was to name every chapter in turn. Board-wide is now
+  asked for by name (`milestone=*`, `core/types.py::EVERYTHING`). Absence still
+  means exactly what it meant, so no agent and no existing caller sees any
+  change: it is the dashboard's OPENING state, and the ✓ now falls on the chapter
+  the server actually resolved, so the pill can no longer claim a scope the page
+  is not drawn at. `taskops_activity` refuses `*` in the words of its own doors —
+  a story is one chapter's cards by definition — where it used to answer
+  `milestone * does not exist`, a lookup's answer to a question that was never a
+  lookup.
+- **A window whose session ran out signs in again instead of teaching `taskops
+  join`.** A host session is twelve hours and a window is a thing you leave open.
+  Two halves of one hole, both on the `taskops ui` path and nowhere else: the
+  command read the token lying in `remote.json` instead of `session.fresh` —
+  which every other command has taken since sessions landed — so a window opened
+  on yesterday's session was dead on arrival; and the forwarder held the token it
+  was built with for the life of the process, so a window that was open when the
+  session expired answered "that credential expired" to every read. Neither path
+  could come back, so the habit it taught was re-joining: a human pasting a
+  credential the machine can mint itself from the key it already has. The retry
+  is `RemoteBoard.call`'s and just as narrow — the SERVER said EXPIRED, and this
+  process holds a key — and it is a callable passed in, so the forwarder still
+  knows nothing about keys, files or logins. A window with no way back in (a
+  standing bearer token, a public viewer) is unchanged: nobody replaces a token
+  behind its owner's back.
+
 ## 0.4.1 — the board comes alive: the forge enrols the team, hours stop lying, comments become visible
 
 - **A comment now SAYS so, on every open dashboard.** The UI's one write was

{taskops_cli-0.4.1 → taskops_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: taskops-cli
-Version: 0.4.1
+Version: 0.5.0
 Summary: A shared work board for teams of coding agents, with a human who decides.
 Project-URL: Repository, https://github.com/bernatch22/taskops
 License-Expression: MIT
@@ -70,7 +70,7 @@ importable leaves commits un-stamped, silently.
 taskops init                              a local board in this repo
 taskops join [<name>] [--invite <id>]     join a board, install the hooks
 taskops remote add <url>                  the host this checkout operates, like git's origin
-taskops serve                             host boards — an events API, no dashboard
+taskops serve                             host boards — /ui and /git open per declared forge
 taskops server init                       bootstrap THIS host: its owner and their ssh key
 taskops board create|ls|push|pull|rm      the boards on a host
 taskops board visibility|forge            who may read one · which repo's team is enrolled
@@ -383,9 +383,11 @@ to bytes that are not in history yet is a pointer to nothing.
 ```
 
 Then `taskops ui` lists it under the chapter's **Reports** tab and renders it
-full width, read out of **your own clone** at that sha — the dashboard never
-asks the server for the bytes, and there is nothing to serve: a host running
-`taskops serve` answers `/git` with a 404, whole.
+full width, read out of **your own clone** at that sha — the local dashboard
+never asks the server for the bytes. A host running `taskops serve` answers
+`/git` too, from a bare read-only mirror of the board's DECLARED forge — the
+hosted window, for the reader with no clone. A board that never declared one
+refuses with a sentence naming `taskops board forge <owner>/<repo>`.
 
 **Reading one, from the other side.** Everything above is the author's half; a
 reader needs no ceremony at all. Three doors onto the same bytes:

{taskops_cli-0.4.1 → taskops_cli-0.5.0}/README.md

@@ -58,7 +58,7 @@ importable leaves commits un-stamped, silently.
 taskops init                              a local board in this repo
 taskops join [<name>] [--invite <id>]     join a board, install the hooks
 taskops remote add <url>                  the host this checkout operates, like git's origin
-taskops serve                             host boards — an events API, no dashboard
+taskops serve                             host boards — /ui and /git open per declared forge
 taskops server init                       bootstrap THIS host: its owner and their ssh key
 taskops board create|ls|push|pull|rm      the boards on a host
 taskops board visibility|forge            who may read one · which repo's team is enrolled
@@ -371,9 +371,11 @@ to bytes that are not in history yet is a pointer to nothing.
 ```
 
 Then `taskops ui` lists it under the chapter's **Reports** tab and renders it
-full width, read out of **your own clone** at that sha — the dashboard never
-asks the server for the bytes, and there is nothing to serve: a host running
-`taskops serve` answers `/git` with a 404, whole.
+full width, read out of **your own clone** at that sha — the local dashboard
+never asks the server for the bytes. A host running `taskops serve` answers
+`/git` too, from a bare read-only mirror of the board's DECLARED forge — the
+hosted window, for the reader with no clone. A board that never declared one
+refuses with a sentence naming `taskops board forge <owner>/<repo>`.
 
 **Reading one, from the other side.** Everything above is the author's half; a
 reader needs no ceremony at all. Three doors onto the same bytes:

{taskops_cli-0.4.1 → taskops_cli-0.5.0}/src/taskops/_version.py

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

{taskops_cli-0.4.1 → taskops_cli-0.5.0}/src/taskops/cli/serving.py

@@ -25,7 +25,7 @@ if TYPE_CHECKING:  # a NAME for the annotation, never an import at start-up
     from ..http.upstream import Upstream
 
 from . import window
-from .. import _clock
+from .. import _clock, session
 from .._json import as_object
 from ..board import DIR, find_root, is_project, read_config
 from .._errors import TaskopsError
@@ -133,7 +133,13 @@ def _upstream(root: Path) -> Upstream | None:
     url = str(config.get("url", ""))
     if not url:
         return None
-    token = str(config.get("token", ""))
+    # The SESSION, refreshed here if it has run out and refreshable again from
+    # inside the window if it runs out while somebody is reading (2026-08-18,
+    # `http/upstream.py`): a host session is twelve hours and this window is
+    # meant to be left open. `fresh` falls back to the cached token whenever it
+    # cannot sign in, and `refresher` is None for a standing bearer — neither
+    # replaces a token nobody may replace, which is `session.py`'s own rule.
+    token = str(session.fresh(root, config, _clock.now()))
     if not token and config.get("readonly"):
         # A viewer's window (`commands.py::_watch`): an Upstream with no bearer.
         # `Mounts.public` reads exactly this — no token means this window is
@@ -145,7 +151,7 @@ def _upstream(root: Path) -> Upstream | None:
             f"{root / DIR}/board.json points at {url} but there is no credential in "
             "remote.json — run: taskops join <url with ?token= or ?invite=>"
         )
-    return Remote(url, token)
+    return Remote(url, token, refresh=session.refresher(root, config))
 
 
 def _open(url: str) -> int:

{taskops_cli-0.4.1 → taskops_cli-0.5.0}/src/taskops/core/types.py

@@ -161,6 +161,18 @@ MILESTONE_STATUSES = ("open", "done", "dropped")
 CLOSED = ("done", "dropped")
 LEASE_TTL = 900.0  # 15 min; every MCP call renews it
 PROJECT = "project"  # the `task` of board-level events
+EVERYTHING = "*"
+"""`milestone=*`: the WHOLE board, said out loud — no chapter in scope.
+
+An ABSENT milestone means "resolve it yourself" (`verbs/_facts.py::in_scope`),
+which with exactly one open chapter IS that chapter. Right for an agent, and it
+left the dashboard's "all chapters" unreachable: it sent no `milestone=`, the
+board came back narrowed anyway, and the picker drew a ✓ beside a scope that had
+never been in effect and that clicking could not change (2026-08-18). Absent and
+"all" are two questions; they now have two arguments, and nothing that omitted
+it sees any change. `verbs/activity.py` is where the two genuinely part — it
+REQUIRES a chapter, and answered `milestone * does not exist`, a lookup's answer
+to a question that was never a lookup."""
 
 
 # Fields of a Card that `edited` may target. Anything else is a BadRequest, so

taskops_cli-0.5.0/src/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)