taskops-cli 0.2.0__py3-none-any.whl

taskops/usecases/_wireclient.py

@@ -0,0 +1,141 @@
+"""Talking to a taskops server over HTTP, with the standard library and nothing else.
+
+`pyproject` declares `dependencies = []` and that is a feature, not an oversight: taskops
+installs into a repository whose owner did not ask for a dependency tree, and a sync client
+is the classic place one gets added for the convenience of two lines. `urllib.request` is
+those two lines.
+
+**No retries.** A push that fails is re-run by the person who ran it, and the second run
+costs nothing because every write here is idempotent — events are content-hashed, a report
+PUT compares fingerprints. An automatic retry would therefore be *safe*, which is exactly
+why it is a bad idea: it would hide a network that is failing behind a command that always
+seems to work. One attempt, a 30-second timeout, and a sentence saying what did not answer.
+
+That argument only got STRONGER when the agent calls arrived. `claim` and `change` are not
+idempotent — a retried claim is a second claim, a retried `done` is a second transition — so a
+retry here could turn a slow network into a card claimed twice. The failure is typed
+(`Unreachable`) precisely so the caller can decide, and for a claim the only safe decision is
+to stop.
+
+**Server errors are relayed verbatim.** The server writes its `error` field for a person;
+translating it into "HTTP 409" here would throw away the only text that says what to do.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, cast
+
+from .._errors import TaskopsError, Unreachable
+
+__all__ = ["Wire", "TIMEOUT", "PAGE"]
+
+TIMEOUT = 30.0
+PAGE = 500
+"""The batch size in both directions — the cap the server's contract declares."""
+
+
+class Wire:
+    """One remote, six calls — four for replication, two for the writes an agent makes.
+    Holds no state beyond where to reach it and how to prove who it is, so a caller may
+    build one per command and throw it away."""
+
+    def __init__(self, url: str, token: str, *, timeout: float = TIMEOUT) -> None:
+        self.base = url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+
+    def post_events(self, events: list[Any]) -> dict[str, Any]:
+        """`{"accepted": n, "max_seq": s}` — `accepted` counts the ones that were NEW there."""
+        return self.call("POST", "/api/sync", body={"events": events})
+
+    def get_events(self, after: int, limit: int = PAGE) -> dict[str, Any]:
+        """One page from the server's log after a SERVER seq. `more` says to ask again."""
+        query = urllib.parse.urlencode({"after": after, "limit": limit})
+        return self.call("GET", f"/api/sync?{query}")
+
+    def get_report(self, label: str) -> dict[str, Any]:
+        """The stored file and its `stamped_seq`. `status` is 404 when the server has none."""
+        query = urllib.parse.urlencode({"label": label})
+        return self.call("GET", f"/api/report/file?{query}", allow=(400, 404))
+
+    def list_reports(self) -> list[str]:
+        """Every label the server holds — the labels-only read, degrading to nothing.
+
+        The contract froze `GET /api/report/file?label=…` before anyone noticed a client
+        cannot ASK for a report whose existence it has no way to learn. A listing was
+        proposed on the server's card as a purely additive shape; until it lands, a server
+        that answers 400/404 here is not an error — it means "reconcile what you know
+        about", which is every label already on this disk.
+        """
+        answer = self.call("GET", "/api/report/file", allow=(400, 404))
+        found: Any = answer.get("labels")
+        if not isinstance(found, list):
+            return []
+        return [str(label) for label in cast("list[Any]", found)]
+
+    def put_report(self, label: str, content: str, *, force: bool = False) -> dict[str, Any]:
+        """Store a report. `{"stored": true}`, or the 409 body with both seqs in it.
+
+        The conflict is RETURNED rather than raised because it is not an error at this
+        layer: reconciling twenty reports must not stop at the first disagreement, and the
+        caller's job is to collect them and tell the person which way each one goes.
+        """
+        body = {"label": label, "content": content, "force": force}
+        return self.call("PUT", "/api/report/file", body=body, allow=(409,))
+
+    def claim(self, body: dict[str, Any]) -> dict[str, Any]:
+        """`POST /api/next` — a claim decided in the SERVER's sqlite, not in ours."""
+        return self.call("POST", "/api/next", body=body)
+
+    def change(self, body: dict[str, Any]) -> dict[str, Any]:
+        """`POST /api/update` — the transition, checked by the server's guards."""
+        return self.call("POST", "/api/update", body=body)
+
+    def call(self, method: str, path: str, *, body: Any = None,
+             allow: tuple[int, ...] = ()) -> dict[str, Any]:
+        """One request. A status in `allow` comes back as data with `status` set."""
+        try:
+            with urllib.request.urlopen(self._request(method, path, body),
+                                        timeout=self.timeout) as answer:
+                return _decode(answer.read())
+        except urllib.error.HTTPError as err:
+            payload = _decode(err.read())
+            if err.code in allow:
+                return {**payload, "status": err.code}
+            raise TaskopsError(_message(payload, self.base + path, err.code)) from err
+        except (urllib.error.URLError, OSError) as err:
+            raise Unreachable(
+                f"could not reach {self.base}: {_cause(err)} — the local board is still "
+                f"yours; run this again when the network is back") from err
+
+    def _request(self, method: str, path: str, body: Any) -> urllib.request.Request:
+        data = None if body is None else json.dumps(body).encode("utf-8")
+        request = urllib.request.Request(self.base + path, data=data, method=method)
+        request.add_header("Authorization", f"Bearer {self.token}")
+        if data is not None:
+            request.add_header("Content-Type", "application/json")
+        return request
+
+
+def _decode(raw: bytes) -> dict[str, Any]:
+    """A JSON object, or an empty one. A body that is not JSON is not a crash: an nginx in
+    front of the server answers 502 in HTML, and the reader wants the status, not a
+    traceback through the parser."""
+    try:
+        parsed: Any = json.loads(raw.decode("utf-8", errors="replace") or "{}")
+    except json.JSONDecodeError:
+        return {}
+    return cast("dict[str, Any]", parsed) if isinstance(parsed, dict) else {}
+
+
+def _message(payload: dict[str, Any], where: str, code: int) -> str:
+    told = str(payload.get("error") or "").strip()
+    return told or f"{where} answered {code} and said nothing a person can act on"
+
+
+def _cause(err: Exception) -> str:
+    return str(getattr(err, "reason", "") or err) or err.__class__.__name__

taskops/usecases/ask.py

@@ -0,0 +1,41 @@
+"""`taskops_ask` — reading. One task in full, or a search when there is no id.
+
+Two shapes behind one tool because they are one intent with one missing piece: an
+agent either knows which task it means or it does not, and making that two tools would
+have it choose wrong half the time. With `task` it returns the whole context; with
+`query` it returns candidates, and the agent asks again by id.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .._errors import BadRequest
+from ..contracts import Task, TaskView
+from ._project import caller, heartbeat, project
+from .view import view
+
+__all__ = ["ask", "search"]
+
+
+def ask(start: Path | str, task_id: str, *, actor: str = "") -> TaskView:
+    """One task and everything around it."""
+    if not task_id.strip():
+        raise BadRequest("`task` is required — pass `query` instead to search")
+    with project(start) as store:
+        heartbeat(store, caller(store, actor)["id"])
+        return view(store, task_id.strip())
+
+
+def search(start: Path | str, query: str, *, limit: int = 20) -> list[Task]:
+    """Tasks whose title or spec contains `query`.
+
+    Comments are deliberately NOT searched. They are the largest text in the system
+    and the least specific: a substring match over a conversation returns the task
+    where somebody mentioned a word once, ranked identically to the task the word
+    names. When this needs to be better it needs ranking, not a wider LIKE.
+    """
+    if not query.strip():
+        raise BadRequest("`query` is required — a non-empty string")
+    with project(start) as store:
+        return store.tasks.search(query.strip(), limit=limit)

taskops/usecases/claim.py

@@ -0,0 +1,104 @@
+"""`taskops_next` — the call an agent makes to start working.
+
+The loop matters: `ready_tasks` is ORDERED, and losing a race on the best task means
+trying the next one rather than failing. With twenty agents asking at once, contention
+is the normal case, and an implementation that returned an error on a lost race would
+have every agent retrying the same task in lockstep.
+
+What comes back is not an id. It is the task, its spec, its conversation, its
+collisions, the branch to create and the agent's inbox — everything the next few
+minutes need, assembled in the one call the agent was already making.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .._clock import now
+from ..contracts import Claim, NextResult, Task
+from ..engine import branch_for, counts, ready_tasks, record, unblock
+from ..engine import claim as take_lease
+from ..storage import Store
+from ._project import caller, heartbeat, project
+from ._reasons import why_nothing
+from ._routing import claim_remotely, routed, whoami
+from .view import inbox_for, view
+
+__all__ = ["next_task"]
+
+
+def next_task(start: Path | str, *, actor: str = "", session: str = "",
+              labels: tuple[str, ...] = (), task: str = "",
+              local: bool = False) -> NextResult:
+    """Claim the best available task, or explain why there is none.
+
+    `local` forces the claim into THIS sqlite. It exists for the server, which runs this
+    function to answer `POST /api/next` and would otherwise call itself if the store it
+    serves happened to carry a `remote.json` — see `_routing`.
+    """
+    if (remote := routed(start, local)) is not None:
+        return claim_remotely(start, remote, {"actor": whoami(start, actor),
+                                              "session": session,
+                                              "labels": list(labels), "task": task})
+    with project(start) as store:
+        who = caller(store, actor)["id"]
+        # BEFORE any write. Two reasons, and the first one is a bug this ordering fixed:
+        # sqlite3 auto-opens a transaction on the first write, and `BEGIN IMMEDIATE` inside
+        # one raises. The second is why it belongs first anyway — the sweep, the unblock and
+        # the claim are one decision, so they must be one transaction. An unblock that
+        # committed separately would publish a ready task this call is about to claim.
+        store.claiming()
+        heartbeat(store, who)
+        unblock(store)
+        claimed = _take(store, who, session, labels, task)
+        if claimed is None:
+            return _result(store, None, why_nothing(store, labels, task, who))
+        return _result(store, claimed, "")
+
+
+def _take(store: Store, who: str, session: str, labels: tuple[str, ...],
+          wanted: str) -> Claim | None:
+    """Walk the ordered pool until a claim lands. None if every candidate was taken.
+
+    A task asked for BY ID must still be `ready` AND not assigned to somebody else. Both checks were
+    missing and both were found by RUNNING the thing, not by review:
+
+    - the dependency check, by following the usage guide: `next --task <id>` on a task whose
+      dependency was open handed it over, so the path where a human names the task was the one that
+      skipped the graph.
+    - the assignment check, by watching a dispatched fleet: a worker invented its own actor id and
+      claimed a card assigned to another worker. Filtering `ready_tasks` was not enough, because
+      asking by id never went through it.
+    """
+    if wanted:
+        asked_for = store.tasks.need(wanted)
+        pool = [asked_for] if _claimable(asked_for, who) else []
+    else:
+        pool = ready_tasks(store, labels=labels, actor=who)
+    for candidate in pool:
+        lease = take_lease(store, candidate, actor=who, session=session)
+        if lease is None:
+            continue
+        store.tasks.set_status(candidate["id"], "claimed", when=now())
+        record(store, task=candidate["id"], actor=who, kind="claimed",
+               body={"session": session, "branch": branch_for(candidate)})
+        return Claim(view=view(store, candidate["id"]), lease=lease,
+                     branch=branch_for(candidate),
+                     inbox=inbox_for(store, who))
+    return None
+
+
+def _claimable(task: Task, who: str) -> bool:
+    """Ready, and either unassigned or assigned to this caller."""
+    return task["status"] == "ready" and task["assignee"] in ("", who)
+
+
+def _result(store: Store, claim: Claim | None, reason: str) -> NextResult:
+    """The answer, always carrying the queue's shape.
+
+    The counts ride along on SUCCESS too, not only on failure: an agent that just took
+    the last ready task and can see that knows to plan rather than come straight back.
+    """
+    numbers = counts(store)
+    return NextResult(claim=claim, reason=reason, ready=numbers["ready"],
+                      working=numbers["working"], blocked=numbers["blocked"])

taskops/usecases/dispatch.py

@@ -0,0 +1,160 @@
+"""`taskops_dispatch` — one agent launches others and hands each a card.
+
+The flow this exists for, and the one taskops could not express before:
+
+```
+   planner ──▶ taskops_plan      five cards, wired
+           ──▶ taskops_dispatch  five workers, one card each, running now
+```
+
+Before this, a planner could create work and then nothing happened: cards sat in a pool waiting for a
+human to open a terminal per agent. Assignment alone would not have fixed it either — an assigned card
+with nobody running is still a card nobody is doing.
+
+**It PREPARES; the orchestrator spawns.** By default this assigns the cards, makes their worktrees,
+and hands back a ready-to-use brief per card — and starts no process at all. The caller then passes
+each brief to its OWN sub-agent tool, so the workers run inside the session that is already open.
+
+That default is a correction. The first version spawned `claude -p` per card, which opens a NEW
+billed session each time; a real fleet of six drained an API balance mid-run and left six cards
+claimed by processes that no longer existed. Sub-agents in the current session use the subscription
+that is already paid for, and they die with the session instead of outliving it invisibly.
+`spawn=True` still exists for the case somebody genuinely wants detached workers.
+
+**Assign, then hand over, in that order.** The card is assigned to the worker's actor id BEFORE
+anything can claim it, so the scheduler will only ever offer it to that worker — and no other agent
+sees it at all.
+
+**Concurrency is capped and the cap is low.** Each worker is a model doing unsupervised work in a
+repository, so the default is conservative and the ceiling is explicit rather than "as many as you
+asked for". A planner that wants twenty has to say twenty.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .._clock import now
+from .._errors import BadRequest
+from ..contracts import Task
+from ..engine import branch_for, record, unblock
+from ..engine.worker import Launched, launch, prepare
+from ..storage import Store
+from ._project import caller, heartbeat, project
+
+__all__ = ["dispatch", "DispatchResult", "MAX_WORKERS", "DEFAULT_WORKERS"]
+
+DEFAULT_WORKERS = 3
+"""How many launch when nobody says. Three is enough to see parallelism and few enough that a first
+try on a real repository cannot turn into a stampede."""
+
+MAX_WORKERS = 12
+"""The ceiling, whatever was asked for. Every worker is a Claude Code process with a model behind it,
+so the real limits are rate limits and money — and a planner that miscounts should hit a refusal here
+rather than an invoice."""
+
+
+class DispatchResult:
+    """Who was launched, and who was not.
+
+    `skipped` is not an afterthought: a dispatch that quietly launched three of five would leave a
+    planner believing five agents are working, and the two cards it never started would look claimed
+    and never move.
+    """
+
+    def __init__(self, *, launched: list[Launched], skipped: list[str],
+                 planned: bool = False, spawned: bool = False) -> None:
+        self.launched = launched
+        self.skipped = skipped
+        self.planned = planned
+        """True for a dry run. The renderer says so loudly — a preview that reads like a result is
+        how somebody believes five agents are working when none are."""
+
+        self.spawned = spawned
+        """True when processes were actually started. False in the default mode, where the cards are
+        assigned and briefed and the CALLER is expected to spawn sub-agents — so the renderer has to
+        tell it that the remaining half is its job."""
+
+
+def dispatch(start: Path | str, *, tasks: tuple[str, ...] = (), count: int = 0, actor: str = "",
+             prefix: str = "", model: str = "", dry_run: bool = False, spawn: bool = False,
+             use_api_key: bool = False) -> DispatchResult:
+    """Launch a worker per card. Named cards, or the best `count` ready ones.
+
+    `count` rather than "everything ready" as the default shape, because "all" is the request nobody
+    means literally on a board with forty cards in it.
+
+    `dry_run` shows the plan and changes NOTHING — no assignment, no worktree, no process. It exists
+    because this is the one call in taskops that spends money: every worker is a model, and a planner
+    that miscounted should be able to look before it commits to five of them. It is also the honest
+    answer to "which cards would you pick", which no amount of reading the scheduler gives you.
+
+    `use_api_key` is the opt-in for billing per token: a spawned worker inherits the environment
+    MINUS `worker.DROPPED_ENV`, so it uses the logged-in subscription. Only the CLI passes it.
+    """
+    with project(start) as store:
+        who = caller(store, actor)
+        heartbeat(store, who["id"])
+        unblock(store)
+        chosen, skipped = _choose(store, tasks, count, who["id"])
+        if dry_run:
+            return DispatchResult(launched=[_preview(store, t, who["dev"], prefix or "w", i)
+                                            for i, t in enumerate(chosen, start=1)],
+                                  skipped=skipped, planned=True)
+        prepared = [_assign(store, task, who["dev"], prefix or "w", i, spawn=spawn, model=model,
+                            use_api_key=use_api_key) for i, task in enumerate(chosen, start=1)]
+        if not spawn:
+            return DispatchResult(launched=prepared, skipped=skipped, spawned=False)
+        return DispatchResult(launched=[w for w in prepared if w.pid],
+                              skipped=skipped + [w.task for w in prepared if not w.pid],
+                              spawned=True)
+
+
+def _preview(store: Store, task: Task, dev: str, prefix: str, index: int) -> Launched:
+    """What a worker WOULD be. pid 0 says no process exists, which the renderer reads."""
+    from ..engine.worker import worktree_for
+
+    return Launched(actor=f"agent:{dev}/{prefix}{index}", task=task["id"], pid=0,
+                    tree=worktree_for(store.root, task), log=Path(""),
+                    branch=branch_for(task), brief="")
+
+
+def _choose(store: Store, wanted: tuple[str, ...], count: int,
+            asker: str) -> tuple[list[Task], list[str]]:
+    """The cards to dispatch, and the ids that were refused with a reason attached to none.
+
+    A named card must be `ready` and unassigned — the same rule `next` enforces, for the same reason:
+    dispatching a worker onto a blocked card would start a process that immediately finds nothing to
+    do and exits, which reads as a broken dispatch rather than a wrong request.
+    """
+    from ..engine import ready_tasks
+
+    if wanted:
+        found = [store.tasks.need(task_id) for task_id in wanted]
+        ok = [t for t in found if t["status"] == "ready" and not t["assignee"]]
+        return _capped(ok), [t["id"] for t in found if t not in ok]
+    return _capped(ready_tasks(store, actor=asker)[:count or DEFAULT_WORKERS]), []
+
+
+def _capped(tasks: list[Task]) -> list[Task]:
+    if len(tasks) > MAX_WORKERS:
+        raise BadRequest(f"{len(tasks)} workers asked for; the ceiling is {MAX_WORKERS} — "
+                         f"dispatch in batches, or raise it deliberately")
+    return tasks
+
+
+def _assign(store: Store, task: Task, dev: str, prefix: str, index: int, *,
+            spawn: bool, model: str, use_api_key: bool = False) -> Launched:
+    """Assign the card and prepare its worktree; spawn a process only if asked.
+
+    Assignment FIRST, always — see the module docstring. The actor name is derived
+    (`agent:<dev>/<prefix><n>`) rather than random, so a fleet view reads as `berna/w1 … berna/w3`
+    instead of three hashes and a developer can tell at a glance which workers are theirs.
+    """
+    worker = f"agent:{dev}/{prefix}{index}"
+    store.tasks.set_assignee(task["id"], worker, when=now())
+    record(store, task=task["id"], actor=worker, kind="handoff",
+           body={"assigned_to": worker, "dispatched": True, "mentions": [worker]})
+    if spawn:
+        return launch(store.root, task, actor=worker, model=model, use_api_key=use_api_key)
+    return prepare(store.root, task, actor=worker)

taskops/usecases/dossier.py

@@ -0,0 +1,155 @@
+"""`report … --write` — the dossier persisted where git can keep it.
+
+The only use case here that writes a FILE rather than an event, and deliberately so. Every
+other projection is regenerated on demand because regenerating is always right; this one
+stops being derived the moment a human or `/taskops:digest` writes the narration into it, so
+it is written once, refused a second time, and committed like source.
+
+The window is a `Selector`, not a date: a day, a week and the whole project are the same
+document over different spans, and the file is named by the window's LABEL — `2026-07-28.md`,
+`2026-07-22..2026-07-28.md`, `all.md`.
+
+Which is also why it goes through `render`: the file's shape is a rendering, and the same
+string has to be producible in a test from a literal dict.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .._clock import now
+from .._errors import AlreadyWritten
+from ..contracts import ReportFile
+from ..engine import (
+    OnPass,
+    OnText,
+    label_of,
+    missing_events,
+    narrate,
+    period_report,
+    stamp,
+    stamped_seq,
+)
+from ..render import is_pending, render_day, render_report
+from ..storage import REPORTS_DIR, Store
+from ._narrating import Progressive
+from ._project import project
+from ._range import Selector, is_day, resolve
+
+__all__ = ["write_report", "read_report", "digest", "report_path"]
+
+
+def write_report(start: Path | str, sel: Selector | None = None, *,
+                 force: bool = False) -> Path:
+    """Render the window and write `.taskops/reports/<label>.md`. Returns where it landed.
+
+    Refuses an existing file unless `force`, because the file may already carry a narration
+    nobody can regenerate — and the report someone linked to yesterday changing under them is
+    exactly the thing that makes a written record worthless.
+    """
+    with project(start) as store:
+        span = resolve(store, sel or Selector())
+        path = report_path(store.root, _label(span))
+        if path.exists() and not force:
+            raise AlreadyWritten(f"{path} already exists — read it, or pass --force to "
+                                 f"regenerate it (any narration in it is lost)")
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(_generate(store, span), encoding="utf-8")
+        return path
+
+
+def read_report(start: Path | str, date_text: str = "") -> ReportFile:
+    """What is on disk for a report LABEL — a day, a range, or `all`.
+
+    A day answers staleness (its window is fixed, so "did anything land after this was
+    written" is a fair question). Any other label answers `stale: False` on purpose: `all.md`
+    is out of date the moment anything happens, and a permanent red badge is noise, not
+    information. This was a real 400 in the UI — clicking `all.md` sent its label through the
+    day parser, which refused the very file the index had just listed.
+
+    A day with no file still answers with a dossier — the one that would be written — so a
+    reader never gets an empty screen and a "generate it" button as the only content.
+    """
+    with project(start) as store:
+        label = date_text.strip()
+        path = report_path(store.root, label) if label else None
+        if path is not None and path.is_file() and not is_day(label):
+            written = path.read_text(encoding="utf-8")
+            return ReportFile(date=label, path=str(path), dossier_md=written,
+                              exists=True, stale=False, missing_events=0)
+        span = resolve(store, Selector(date=date_text))
+        date = span[0]
+        path = report_path(store.root, date)
+        written = path.read_text(encoding="utf-8") if path.is_file() else ""
+        behind = missing_events(store, date, date, stamped_seq(written))
+        return ReportFile(date=date, path=str(path),
+                          dossier_md=written or _generate(store, span),
+                          exists=bool(written), stale=behind > 0, missing_events=behind)
+
+
+
+def digest(start: Path | str, sel: Selector | None = None, *, model: str = "",
+           force: bool = False, on_pass: OnPass = None, on_text: OnText = None) -> Path:
+    """Write the window's report if it is missing, then have Claude narrate it.
+
+    The two callbacks are how a caller SEES it happen — which pass is running, and the prose as
+    it is written. Optional, and nothing here prints: a use case that wrote to stdout would be
+    unusable from the HTTP transport, which calls this same function.
+
+    Two failures are kept apart on purpose. The dossier is written FIRST and committed to disk
+    before the model is called, so a narration that fails — no `claude`, not logged in, a
+    timeout — costs the prose and never the facts. Running it again then narrates the file that
+    is already there rather than starting over.
+
+    An existing narration is refused without `force` for the same reason a written report is:
+    somebody may have written it by hand, and this is the one section a machine cannot recover.
+
+    `force` regenerates the DOSSIER too, not only the prose. Narrating the file as it lies is
+    what the first version did, and it produced the worst possible failure: a fresh narration of
+    a stale document. A report written before a card was closed — or before the renderer learned
+    to show open cards at all — reads to the model as a day on which nothing happened, and the
+    prose says so, accurately and uselessly. Anybody passing `--force` is asking for this report
+    to be redone; redoing half of it is the answer nobody wants.
+
+    The prose reaches the file AS IT IS WRITTEN (`_narrating.Progressive`), not at the end. A
+    run of several passes used to leave `_pendiente_` on disk for a quarter of an hour, which
+    is indistinguishable from a report nobody narrated — and a crash at minute fourteen made
+    that permanent.
+    """
+    with project(start) as store:
+        span = resolve(store, sel or Selector())
+        path = report_path(store.root, _label(span))
+        if force or not path.is_file():
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(_generate(store, span), encoding="utf-8")
+        report = path.read_text(encoding="utf-8")
+        if not is_pending(report) and not force:
+            raise AlreadyWritten(f"{path} already carries a narration — read it, or pass "
+                                 f"--force to replace it (the old one is lost)")
+        live = Progressive(path, report, on_pass=on_pass, on_text=on_text)
+        return live.finish(narrate(report, model=model, on_pass=live.passed, on_text=live.text))
+
+
+def report_path(root: Path, label: str) -> Path:
+    return root / REPORTS_DIR / f"{label}.md"
+
+
+def _label(span: tuple[str, str, str]) -> str:
+    """The window's name, asked of the renderer's own source of truth rather than rebuilt
+    here — a path and a heading that disagree is the bug this indirection exists to stop."""
+    return span[2] or label_of(span[0], span[1])
+
+
+def _generate(store: Store, span: tuple[str, str, str]) -> str:
+    """The file's whole text, stamped with the log's max_seq AT THIS MOMENT.
+
+    Read after the dossier would be a race with itself — an event landing mid-render would be
+    in the report and outside its own fingerprint, and the file would claim to be older than
+    it is. Read first, and the worst case is a report that reports itself stale.
+
+    The rendering is `full`: the spec of every card, every comment whole, every file of every
+    commit. The terminal keeps the short form — this is the copy somebody reads INSTEAD of the
+    git log a month later, and a truncation it cannot expand is a fact permanently lost.
+    """
+    return render_report(stamp(_label(span), store.events.max_seq(), now()),
+                         render_day(period_report(store, *span), detail="full"))