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

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

@@ -214,7 +214,8 @@ flowchart TB
         wire["_wire — one POST, one envelope: the decoder both clients share"]
     end
     subgraph L1["1 · core (PURE — no I/O)"]
-        types["types — Card/Milestone/Event/Lease, KINDS registry"]
+        types["types — Card/Milestone/Event/Lease (re-exports KINDS and the actor grammar)"]
+        kindsm["kinds — the event-kind registry: replayed? required body keys"]
         actors["actors — presence, folded from events"]
         event["event — construct + hash"]
         replay["replay — fold(events) → State"]
@@ -228,7 +229,8 @@ flowchart TB
         reportsm["reports — is this a report PATH, and the chapter's list as a fold"]
         holdingm["holding — 'is this history held here?', by event id: board pull + board rm"]
         forgem["forge — the forge vocabulary: which host can be asked, what access counts, owner/name"]
-        hours["hours — working-time math"]
+        seamsm["seams — which ready cards name the same CONCEPT, from the specs alone"]
+        hours["hours — working-time math, and the calendar windows to report it over"]
     end
     subgraph L2["2 · store (the ONLY SQL)"]
         log["log.jsonl — append + fsync"]
@@ -246,14 +248,14 @@ flowchart TB
         mentionsv["_mentions — the ✉ read"]; waitingv["_waiting — the ◆ read"]; eventsv["events — the log, paged"]
         reviewv["review — claim a submitted card, or record the verdict"]
         projectv["project — board-level facts: op=remote, op=visibility, op=forge"]
-        helpersv["_args _cards _context _facts _rows — the helpers; the _ says 'not a verb'"]
+        helpersv["_args _cards _chapter _context _facts _rows _stories _windows — the helpers; the _ says 'not a verb'; _windows owns what a window= spelling MEANS"]
         registry["__init__ — Verb(fn, kind, roles, refusal)"]
     end
     subgraph L4["4 · board.py + gitwork (the ONLY git, client-side)"]
         board["board.py — LocalBoard | RemoteBoard, routing decided ONCE"]
         run["gitwork/run"]; trees["gitwork/trees — worktrees: the GEOMETRY"]
         landing["gitwork/landing — the MERGES: card→chapter, chapter→trunk"]
-        catchup["gitwork/catchup — one worktree, up to date with a branch"]
+        catchup["gitwork/catchup — one worktree, up to date with a branch; the chapter's declared union_files fold, everything else still aborts"]
         trailer["gitwork/trailer"]; bind["gitwork/bind"]
         install["gitwork/install — what GIT needs: hooks, gitignore, the address"]
         claudef["gitwork/claudefiles — what CLAUDE reads: .mcp.json, settings.json"]
@@ -265,11 +267,11 @@ flowchart TB
         identitym["identity.py — WHO signs in, with WHICH key: discover, establish"]
     end
     subgraph L5["5 · transports"]
-        mcpsrv["mcp/server, hello, tools, gitmoves, integrate, dossier, before, render, brief, schema, thread, boards, fields"]
-        httpsrv["http/server (lifecycle), handler (one method per door), mounts, watcher, rpc, admin, scoped, grants, ingest, removal, auth, login, github (membership enrols a key — it mints nothing), feed, static, gitdoor, upstream"]
+        mcpsrv["mcp/server, hello, tools, gitmoves (assign + merge dispatch), integrate (a CARD lands), chapter (a MILESTONE lands: gate, catch-up, record), dossier, before, render, brief, activity, boardview, schema, orders, thread, boards, fields"]
+        httpsrv["http/server (lifecycle), handler (one method per door), mounts, watcher, rpc, admin, scoped, grants, ingest, removal, auth, login, members (the owner's enrol BATCH), feed, static, gitdoor, upstream"]
     end
     subgraph L6["6 · cli"]
-        cli["commands: init · join --key/--invite/--github   ·   enrol: the two introductions, and WHERE a GitHub token may come from   ·   hooks: what the two git hooks call   ·   watch: join with nothing   ·   serving: serve · ui   ·   remote: remote add — which host, which board   ·   operate: board · board visibility · board forge   ·   grants: invite · revoke   ·   push: board push   ·   pull: board pull — the same five steps backwards, over paging: the whole log through the `events` verb   ·   rm: board rm — the guardrail   ·   admin: server init + break-glass"]
+        cli["commands: init · join --key/--invite   ·   enrol: the invite introduction   ·   github + team: the OWNER's forge sync, and WHERE a GitHub token may come from   ·   hooks: what the two git hooks call   ·   watch: join with nothing   ·   serving: serve · ui   ·   remote: remote add — which host, which board   ·   operate: board · board visibility · board forge   ·   grants: invite · revoke   ·   push: board push   ·   pull: board pull — the same five steps backwards, over paging: the whole log through the `events` verb   ·   rm: board rm — the guardrail   ·   admin: server init + break-glass"]
     end
 
     L1 --> L0
@@ -290,8 +292,8 @@ instead of an arbitrary one.
 **A leading `_` marks plumbing for the layer above, and it is a three-zone
 convention**: the package root (`_errors _ids _clock _json _locate _version
 _wire` are level 0; `board.py`, `session.py` and `identity.py` are that layer's
-doors), and `verbs/` (`_args _cards _context _facts _mentions _rows _waiting`
-are helpers — the un-prefixed files are the registry's entries, one per verb).
+doors), and `verbs/` (`_args _cards _chapter _context _facts _mentions _rows
+_stories _waiting _windows` are helpers — the un-prefixed files are the registry's entries, one per verb).
 Nowhere else carries it, because every module under `core/ store/ gitwork/
 http/ mcp/ cli/` is internal to its layer and there is nothing to distinguish;
 `import taskops` exposes five errors and a version, so module names are a
@@ -590,21 +592,19 @@ ever looked at it again or said so. It is now a STOP naming both ways out —
 delete) and join anyway. It counts EVENTS, not the directory, so the ordinary
 `init` → `join` sequence is untouched.
 
-**`taskops join <board> --github` is the whole introduction in one command**
-(`cli/commands.py::join`, `cli/enrol.py::by_github` — the client half of the
-door in §10). It is the `--invite` path with a different proof: the pubkey
-travels with something that vouches for it, the host enrols it, and the key
-signs in ON THE SPOT through the same `session.sign_in`, so what lands in
-`remote.json` is a SESSION with an expiry and a `login` block and never a
-standing credential. **The GitHub token is never a flag value.** `--github` is
-a `store_true` and must stay one: a secret passed as an argument is written to
-the shell's history file before the process starts and is visible in `ps` to
-every user on the box while it runs. It comes from `gh auth token` (the CLI is
-already installed and already authenticated on the machine of anybody who has
-push on the repo, so the common case asks nothing), else `$GITHUB_TOKEN` (CI, and
-a shell with no `gh`), else a HIDDEN `getpass` prompt — three sources, one
-order, in `enrol.py::github_token`. A bare `taskops join` is untouched by all of
-this: an enrolled key still signs in with no flags and never speaks to GitHub.
+**A dev's join carries nothing about GitHub, and did for one day** (deleted
+2026-08-11, §19.1). `taskops join --github` posted the joiner's own GitHub token
+for the host to verify against the declared repo; it was the `--invite` path with
+a different proof, and it was the right shape for the wrong side. The owner's
+`board forge` already knows the team, so the fact is established once, on their
+laptop, and a dev whose key that sync published joins BARE: `taskops join`, the
+address carried by the clone, the key discovered the way ssh discovers one, the
+challenge signed on the spot. Nothing of theirs travels — which is stronger than
+never storing what did. **A GitHub token is never a flag value** survives the
+flag it was written for and now lives beside the only caller left
+(`cli/github.py::token`, §19.1): `gh auth token`, else `$GITHUB_TOKEN`, else a
+HIDDEN `getpass` prompt, because a secret passed as an argument is in the shell's
+history file before the process starts and in `ps` while it runs.
 
 **The on-box commands survive as break-glass**: `taskops invite/revoke --root
 <dir>` still work against the files, on the machine that holds them, for the day
@@ -698,7 +698,7 @@ flowchart LR
     dispatch_t -->|"assign + cut worktree"| verbA["verb: assign"] --> gitA["gitwork/trees.ensure_card"]
     take_t -->|"acquire lease"| verbT["verb: take"] --> liveT["live.sqlite INSERT OR IGNORE"]
     update_t -->|"close / release / drop / rewrite"| verbU["verb: update"]
-    comment_t -->|"say something on ANY open card (+mentions)"| verbU
+    comment_t -->|"say something on ANY card, closed included (+mentions)"| verbU
     review_t -->|"task= claims · verdict= judges"| verbR["verb: review"] --> liveR["live.sqlite — the REVIEW lease"]
     merge_t -->|"--no-ff in integration worktree"| gitM["gitwork/landing.merge_card"] --> verbM["verb: merged"]
     activity_t -->|"a chapter's story, capped, no diffs"| verbAc["verb: activity — a READ"]
@@ -770,7 +770,7 @@ sequenceDiagram
     Dev->>Board: taskops_board
     Board-->>Dev: group MERGE: [tk-a1]
     Dev->>Board: taskops_merge task=tk-a1  (or tasks=[tk-a1, tk-b2] / done=true — the same path per card, in order, stopping at the first failure)
-    Board->>Git: trees.behind() — if tk-a1 lacks the ms/* head, catchup.catch_up() merges ms/* IN tk-a1's own worktree (dirty or missing: refused, untouched; conflict: aborted clean, git's files + the count)
+    Board->>Git: trees.behind() — if tk-a1 lacks the ms/* head, catchup.catch_up() merges ms/* IN tk-a1's own worktree, with the chapter's union_files (from the dossier already loaded) applied as merge=union through an EPHEMERAL core.attributesFile outside the repo (dirty or missing: refused, untouched; conflict in anything undeclared: aborted clean, git's files + the count)
     Board->>Git: merge_card() --no-ff into ms/<milestone>, in the integration worktree
     Git-->>Board: sha (or refused, conflict files named, ms/* untouched)
     Board-->>Dev: merged
@@ -824,7 +824,7 @@ nobody has touched yet.
 |---|---|---|
 | **MCP over stdio** | Claude / any MCP host, per-repo | newline-delimited JSON-RPC 2.0. `initialize` returns `instructions`: the whole role protocol AND the board as of that moment (`mcp/hello.py` — the same verb and renderer an agent would call, so it is a delivered answer, not a second version of one). That is what a v1 system prompt was, minus the second place for truth to live, and it needs no hook and no settings file to be trusted. **One server per SESSION, shared by every sub-agent**, which is why identity rides on the call (`actor=`, §5) and not in the process's environment. `tools/call` on a refusal answers `isError: true` with the refusal *as the text content* — never a protocol-level error, because an agent that cannot read the way out will invent one; an unexpected exception answers the same way rather than ending the loop, since that loop is the session's only door to the board. |
 | **HTTP RPC** | a remote board's clients (`RemoteBoard`, the browser) | `POST /<board>/rpc` with `{"verb", "args", "actor"}`, `Authorization: Bearer <token>`. Answer is always an envelope: `{"ok": true, "seq": N, "data": {...}}` or `{"ok": false, "error": {"code", "message"}}` — v1 let three verbs answer with a bare array and the decoder silently turned it into `{}`. |
-| **GitHub introduction** | somebody joining a board that DECLARED a forge | `POST /<board>/join/github` with `{"github_token", "principal", "pubkey"}`. The host asks GitHub once — `GET /repos/{owner}/{name}`, the caller's own token in the header, `permissions[need]` read out of the answer — and on yes enrols the pubkey exactly as `invite/redeem` does. It mints NOTHING: the answer is `{principal, actor, role, fingerprint, repo, need}` and the caller's next call is the ordinary `/login` challenge with the key it just enrolled, so from the second call on this door is invisible. **The token is a header on one outgoing request and nothing else** — not the log, not `server.sqlite`, not `remote.json`, not the answer, not a refusal. A board that declared no forge refuses before anything leaves the host and keeps its invite-only flow; GitHub not answering is `Unreachable`, never a grant. **The opt-in is `taskops board forge <owner>/<repo> [--need push|admin]`**, owner-only and server-scope beside `board.visibility`, and `--clear` takes it back to invite-only — the refusal's own sentence is TYPED as the argv of a test, so the message and the command cannot drift (`http/github.py::FORGE_VERB`, `cli/operate.py::_forge`, and the two blocks in `tests/test_topology.py`). |
+| **GitHub, from the OWNER's laptop** | `taskops board forge <owner>/<repo>`, and nothing else in the system | two GETs, neither of them at a taskops door: `GET /repos/{owner}/{name}/collaborators?permission=<need>` (paginated, the owner's own token in the `Authorization` header — the only authenticated call in the chapter) and `GET https://github.com/<login>.keys` (PUBLIC, `text/plain`, no credential spent). What reaches the host afterwards is `members.enroll` over the ordinary `/rpc`, carrying principals and ssh key lines: **no GitHub token ever crosses to a taskops host, and none is stored on either side** — it is a header on the owner's outgoing requests and dies with the command. A board that declared no forge is not asked about at all, so it stays invite-only exactly as before. There was a door here for one day — a dev POSTing their own token to `/<board>/join/github` — and §19.1 is why it is gone (`cli/github.py`, `cli/team.py`, `http/members.py`, and the tail block in `tests/test_topology.py`). |
 | **WebSocket feed** | the browser UI only | `GET /<board>/feed`, upgraded via the RFC 6455 handshake (`HTTP/1.1` required for the 101 response to be accepted — the one bug class invisible to a library-based test, caught only with a raw-socket test). A message is a *signal* (`{"type": "changed"}`), never a payload — the client refetches, so a dropped or duplicated frame can never show something the board never said. SSE is the automatic fallback for a proxy that eats the Upgrade. Agents never use this: their live channel is the "pulse" line appended to every tool result. The UI carries exactly ONE write — a comment box with a mention picker on the card panel, through the same `/rpc` door and token. |
 | **Delivery hook** | Claude Code sessions in a joined repo | `taskops hook claude`, wired by `init`/`join` into `.claude/settings.json` on `PostToolUse` + `UserPromptSubmit`. Read-only and one-way: resolves the reader (env, else worktree-path → card → holder) and injects context — `✉ …` when a mention is pending, for ANYBODY (throttled per reader per 30s); and `◆ …`, one line per group with the count and the call that clears it, when MERGE / REVIEW / STALLED is non-empty and the reader is a `dev:` (throttled per 180s, its own key). Silence otherwise, exit 0 always, any failure silent. Both reads (`mentions`, `waiting`) renew no lease. The one sanctioned Claude hook: it may deliver, never decide, store, or write. |
 
@@ -834,7 +834,7 @@ nobody has touched yet.
 
 | removed / never built | why | where it's enforced |
 |---|---|---|
-| a `recover` verb | doing is derived from the live lease; nothing is ever wrong to recover | no entry in `verbs/__init__.py::REGISTRY`; `tests/test_verbs.py::test_a_dead_workers_card_comes_back_by_itself` |
+| a `recover` verb | doing is derived from the live lease; nothing is ever wrong to recover. Handing a card on is not that verb and never grew into one — it stayed inside `assign`, needs a named replacement, and is argued in §12 | no entry in `verbs/__init__.py::REGISTRY`; `tests/test_verbs.py::test_a_dead_workers_card_comes_back_by_itself` |
 | a reviewer ROLE, a stored review STATUS, automatic reviewer assignment | v1's review system: `peer` deadlocks, 14 closing rules over 6 modules, reviewers eating the budget of the work | review EXISTS since 2026-08-07 but narrowed: optional per card, derived from history-only events + a second lease, judged by an ordinary agent that may never judge its own work. `CARD_STATUSES` stays three; there is no reviewer role and nothing auto-assigns |
 | AUTOMATIC merges to the trunk | v1's `land` merged as a side effect of closing a card and ran checkout under working agents | a CARD cannot be merged to the trunk — `taskops_merge task=` takes no target. A finished MILESTONE lands via `taskops_merge milestone=` (2026-08-07): explicit, refused while any card is open or unintegrated, refused off-trunk, recorded as a `milestone landed` event. What stays impossible is the trunk moving as a side effect of anything |
 | git replication between clones | split-brain, two machines "owning" the same card | `RemoteBoard` never falls back to a local store on write failure (`Unreachable` instead) |
@@ -846,7 +846,9 @@ nobody has touched yet.
 | a `--force` on `taskops board push`, and a SYNC channel behind `board.ingest` | a non-empty target means two histories, and giving them an order they never had fabricates a timeline the board never observed. The precondition ("no history but its own beginning") is true exactly once in a board's life, which is what keeps the door a promotion and not replication between clones — the thing banned two rows up | `http/ingest.py` refuses and says so; `tests/test_topology.py::test_a_target_that_is_not_empty_is_refused_and_no_force_is_offered`, and the argument is the module's own docstring |
 | a `--force` on `taskops board rm` (and it is not an alias for `--discard-history`) | removing a board deletes the only copy of a history nobody can regenerate, and `--force` is a word every tool spends on something recoverable — it names no consequence, so it cannot warn. The flag that gets past the guardrail names the thing it destroys, and the guardrail itself is on the HOST, comparing the ids the caller says it holds against the ids the board really has: a wall the client enforces is a convention | `http/removal.py` refuses unless `core/holding.py` says the history is held elsewhere, and only a literal `true` opens `discard_history`; `tests/test_topology.py::test_the_flag_is_named_for_what_it_destroys_and_a_force_is_not_a_synonym` and `…::test_board_rm_refuses_a_history_this_checkout_does_not_hold_and_names_both_ways_out` |
 | a SILENT `taskops join` over a local board | the local history stayed on disk byte for byte and nothing ever looked at it again or said so — a command about connecting is what made it invisible | `cli/commands.py::_keep_or_archive` refuses naming `taskops board push` and `--discard-local` (which archives, never deletes); `tests/test_topology.py::test_join_refuses_to_orphan_a_local_board_and_names_both_ways_out` |
-| GitHub as a CREDENTIAL — v1's GitHub login: a stored token, a call to GitHub on every sign-in | three costs, and §18 is the whole argument: a token that travels (worth stealing for reasons unrelated to the board), a network dependency at every login (GitHub down = nobody signs in), and a SECOND identity system beside the keys, with its own enrolment, expiry and revocation to keep in step. The convenience is kept and the costs are not: GitHub is asked ONCE, and what persists is an ssh key | `http/github.py` mints nothing — no token, no session, no `Set-Cookie`: the answer is `{principal, actor, role, fingerprint, repo, need}` and the caller's next call is the ordinary `/login`. The token is a header on one outgoing request and is written to no file (`tests/test_topology.py::test_the_github_token_is_written_to_no_file_and_no_event`, which greps the board log AND the host store, with a positive control), and it cannot be passed as a flag value at all (`…::test_a_token_cannot_be_passed_as_a_flag_value_at_all`). There is no `join.github` row in `core/scope.py` and no second credential type anywhere |
+| GitHub as a CREDENTIAL — v1's GitHub login: a stored token, a call to GitHub on every sign-in | three costs, and §19 is the whole argument: a token that travels (worth stealing for reasons unrelated to the board), a network dependency at every login (GitHub down = nobody signs in), and a SECOND identity system beside the keys, with its own enrolment, expiry and revocation to keep in step. The convenience is kept and the costs are not: GitHub is asked ONCE, by the owner, and what persists is an ssh key | the only module that speaks to GitHub is `cli/github.py`, on the owner's machine; the host takes principals and key lines (`http/members.py`) and no token reaches it. `tests/test_topology.py::test_the_owners_token_is_spent_on_ONE_endpoint_and_written_nowhere` greps the host tree AND the checkout with a positive control, and `…::test_no_flag_on_join_takes_a_token_and_none_ever_will` holds the parser to "never a flag value". There is one `members.enroll` row in `core/scope.py` — a ROLE rule — and no second credential type anywhere |
+| a GitHub door on the DEV's side — `POST /<board>/join/github`, a `--github` flag, a token discovered at join time (2026-08-11) | it made every dev's own credential travel to a host that has no business seeing one, to prove a fact the OWNER already holds; and it asked for an ssh key from people who, having push over ssh, had published one already. Deleted the day after it shipped — §19.1 | there is no route, no flag and no client function: `grep -r 'join/github\|by_github' src tests` is empty, and `test_no_flag_on_join_takes_a_token_and_none_ever_will` asserts the ABSENCE from `join --help`. The replacement is one command on the owner's side and `taskops join`, bare, on the dev's (`…::test_the_dev_whose_key_the_sync_published_joins_with_two_words`) |
+| a COMMITTED `.gitattributes` (or a written `$GIT_DIR/info/attributes`) as the union-merge mechanism | a milestone's `union_files` is one chapter's convenience, and both of those are repo-wide and outlive the merge. Measured in this repo: `git rev-parse --git-path info/attributes` inside a LINKED worktree answers the COMMON dir, so writing there hands one card's declaration to every sibling merging at the same moment, and a crash between write and delete leaves it enabled for the whole repository, invisibly. A committed file is worse still: it makes the chapter's convenience permanent and reviewable as if it were a repo decision | `gitwork/catchup.py::_attributes` writes a temp file OUTSIDE the repository and passes it as `git -c core.attributesFile=…` for that one process, deleted in a `finally` on both paths. The precedence is deliberate: an in-tree `.gitattributes` BEATS `core.attributesFile`, so the dashboard bundle's `-merge` cannot be overridden by a declaration. `tests/test_git.py::test_no_attributes_file_survives_a_merge_that_worked` and `…_that_aborted` assert nothing is left in the temp dir, in the tree, or at `info/attributes` |
 | a slug in a branch name that isn't the milestone's | a renamed milestone orphaned its branch (ghost branches) | `Milestone.branch` computed once at creation, stored, never re-derived |
 | a stored `doing` | a dead worker's card claimed to be worked on forever | `CARD_STATUSES = ("open", "done", "dropped")` — `"doing"` raises `BadRequest` if ever passed to `status=` |
 | a worker-SLOT roster (held / free / lapsed as a pool) | taskops allocates no worker: `workers=[…]` is a label chosen at the call, sub-agents are ephemeral, and an actor is a name bound to the RUN of a card — a roster with capacity would be a fiction the board could never make true | the Actors view draws DEVS with their agents as lines inside them instead (`ui/src/pages/Actors.tsx`, `components/monitor/panels.ts` — both carry the post-mortem); an agent with no card is HISTORY, never "free", and `ui/smoke/sections/actors.tsx` asserts the words `free`, `slot` and `capacity` appear nowhere in that markup ("actors: NO WORKER SLOTS, under that name or any other") |
@@ -865,6 +867,68 @@ not have. A dead function that describes a banned design is worse than no
 function — the next reader takes it as permission. An abandoned lease expires;
 nothing takes a card away from its holder.
 
+**Amended 2026-08-11, and the amendment is narrow.** One thing does take a card
+from its holder, and it is not a recover: `taskops_assign` handing that card to
+a NAMED replacement (`store/handover.py::displace`, its only caller
+`verbs/assign.py`). What made `force_release()` a banned shape was that it freed
+a lease into nobody's hands, on nobody's authority, to fix something the design
+says is never wrong. This frees it into a named worker's, on the orchestrator's,
+in the same call and the same event that names them — and the reason is that the
+clock was answering a question it cannot answer. The lease's only heartbeat is
+`Live.renew`, called by every verb, so *MCP traffic* stands in for *alive*, and
+that proxy is wrong in both directions at once: a worker that DIED holds its card
+for up to `LEASE_TTL` while the orchestrator that watched it die is refused the
+hand-over, and a worker that is WORKING — twenty quiet minutes of reading,
+editing and running tests, not one MCP call — stops renewing and is reported
+`stalled` while alive. No value of `LEASE_TTL` fixes both; raising it worsens the
+first and lowering it worsens the second. They are one bug pulling in opposite
+directions. So the clock stopped being the authority: `stalled` is now a
+*report* ("quiet for N minutes", `quiet_for`), never a mechanism, and what
+changes hands is decided by somebody, on the record. Nothing is taken by the
+passage of time, and a displaced worker still does not lose what it built —
+`core/machine.py::_not_somebody_elses` asks about the ASSIGNEE, never the clock.
+Pinned by `tests/test_verbs.py::test_the_orchestrator_hands_over_a_card_whose_lease_is_still_live`
+and `…::test_handing_a_card_to_the_worker_that_holds_it_leaves_its_lease_alone`.
+
+**So a lapsed lease never blocks the owner's own close** (2026-08-14, asked by an
+operator who watched a resumed worker's `done` land after its lease had expired).
+It is accepted, deliberately: `core/machine.py::_not_somebody_elses` refuses only
+a LIVE holder who is somebody else, so with no new holder the worker that did the
+work still closes it — the same argument as above, read from the other end. A
+close that demanded a live lease would punish exactly the twenty quiet minutes of
+editing that the clock cannot see, and it would do it at the one moment the work
+is finished. Pinned by
+`tests/test_core.py::test_a_lapsed_lease_does_not_cost_you_your_own_card`.
+
+**And a done card can never read `stalled`.** The same operator reported seeing
+both at once. That is not a state the derivation can produce:
+`core/graph.py::derived` answers the STORED status first, above every live fact,
+so the instant the done event is in the log the card reads `done` — owner or no
+owner, holder or no holder, however long the lease has been gone. `stalled`
+belongs to the open branch alone. A stalled row beside a landed done is a read
+that happened before the write (or a different copy of the board), never a
+disagreement between the two. Pinned by
+`tests/test_core.py::test_a_closed_card_derives_done_and_can_never_read_stalled`.
+
+**And a report has to be readable.** `quiet_for` alone was not: a session limit
+took five workers at once and every STALLED row said the same "quiet for 1h", so
+resume-vs-reassign became an investigation per card. A stalled row now also
+carries `last_event = {kind, ago}` — the last thing on the card's thread — and
+`commits`, how many commit events are bound to it (`verbs/_rows.py::forensics`,
+attached by `pulse.py::run` to the stalled group ALONE, exactly as `waiting_on`
+is attached to blocked; every other row is byte-identical to what it was, and no
+other row pays for the thread read). Dispatched-and-never-heard-from
+(`edited`), claimed-then-silent (`claimed`), thinking-out-loud-then-gone
+(`comment`) and work-on-the-branch (`commit`, with a count) are four different
+moves, and they are now four different lines. Still derived per read, still
+nothing stored, and still no cause of death: the lease's only heartbeat is MCP
+traffic, so the board can say WHAT was last said and never WHY it stopped.
+Rendered on the MCP board by `mcp/boardview.py::_group`; pinned by
+`tests/test_verbs.py::test_a_stalled_row_says_what_its_holder_last_did_and_how_long_ago`,
+`…::test_a_stalled_row_counts_the_commits_bound_to_the_card`,
+`…::test_only_a_stalled_row_carries_the_forensics_keys` and
+`tests/test_mcp.py::test_a_stalled_line_says_what_the_holder_last_did_and_what_is_on_the_branch`.
+
 The remaining "recover" mentions (`core/types.py`, `verbs/assign.py`,
 `mcp/tools.py`, `gitwork/run.py`, `core/mentions.py`, `store/live.py`) are
 intentional: each one explains why the
@@ -886,10 +950,39 @@ Milestone, next to `rules`. Both are implemented (tk-097cae, 2026-08-07): the
 ordering rule is one sentence in `mcp/server.py::INSTRUCTIONS`, delivered at
 the handshake inside `hello.py`'s budget; `Milestone.criteria` travels into
 every take like `rules` and is SHOWN at `taskops_merge milestone=`, which
-refuses until the human answers `criteria_met=true` — recorded in the `landed`
-event, never judged by the machine. §10 of that post-mortem was the map from each
+refuses until the human answers — `criteria_met=true`, or `criteria_met=false`
+with a MANDATORY `note=` (2026-08-14, tk-d65ad3: some criteria are structurally
+post-landing — "seven days of live rows" for code that only deploys FROM the
+trunk — and a gate that took only `true` deadlocked the chapter or invited a
+lie). Both answers, and the note, are recorded in the `landed` event and never
+judged by the machine; `false` in silence is the one refused outcome, in the
+gate (`mcp/chapter.py::land`, before any git runs) and again in the write
+(`verbs/record.py::merged`). §10 of that post-mortem was the map from each
 adoption to its test.
 
+**And the seam files a chapter declares are a chapter's field, not a repo's**
+(2026-08-14, tk-6882a1). Three conflicts in one real wave were the same shape —
+sibling cards each APPENDING to a registry, a changelog, a barrel file — and git
+already folds that shape with its built-in `union` driver. So a milestone
+DECLARES the paths: `taskops_plan union_files=[…]` at creation, or
+`taskops_update milestone=… union_files=[…]` afterwards, replaced WHOLE like
+`rules` and `criteria` (`verbs/_chapter.py::LISTS`, `core/chapters.py`) — the
+un-declare is `union_files=[]`, because an append-only log has no un-declare
+event. It is SCOPED twice over. In space: only the declared paths get
+`merge=union`; everything undeclared conflicts, aborts and refuses byte for
+byte as before, and an in-tree `.gitattributes` still WINS over the ephemeral
+file, so the dashboard bundle's `-merge` cannot be overridden by a declaration.
+In time and in place: it is applied on the CARD's catch-up alone
+(`mcp/integrate.py` reads it off the dossier it already loaded and passes it to
+`gitwork/catchup.py::catch_up`); the chapter→trunk catch-up
+(`mcp/chapter.py::_catch_up_to_trunk`) passes nothing, because a chapter meeting
+a moved trunk is the human's merge, not a sibling's append. Why the mechanism is
+an EPHEMERAL `core.attributesFile` outside the repo rather than a committed
+`.gitattributes` or `info/attributes` is argued in §11's table — in one line,
+both of those are repo-wide and outlive the merge, and inside a linked worktree
+`info/attributes` resolves to the COMMON dir, which would hand one card's
+declaration to every sibling merging at that moment.
+
 ---
 
 ## 13. Verified state at time of writing
@@ -985,6 +1078,23 @@ dashboard on a machine with no node. React is bundled, never fetched from a
 CDN, so it also serves offline. It is a *client of the same HTTP contracts*
 described in §10 and imports nothing from the Python tree.
 
+Its live channel (`ui/src/client.ts::subscribe`) is **one reconnect loop with no
+terminal state but `stop()`**. It had two dead ends and neither survives: a
+WebSocket that had opened and dropped retried exactly ONCE after 500ms and then
+fell back to SSE permanently, and the SSE error handler only reported
+`onLive(false)` — so an `EventSource` that died fatally (`readyState` CLOSED, a
+non-200 while the server restarts) was retried by nothing at all, and the header
+sat on "offline" with a stale board until somebody pressed reload. Now WS retries
+with capped exponential backoff (500ms doubling to 8s: a laptop that slept
+through the night must not wait minutes after the lid opens), a fatally-closed
+SSE hands itself back to the same loop, and every failure path ends in `retry()`
+or in a transport that will. Regaining the feed pokes exactly ONE refetch — the
+transports' own `hello` frame, counted by `frame()`, never a second signal on
+`open` — so staleness heals with the connection and one recovery is one fetch.
+`subscribe` takes an injectable `Env` (`WebSocket`, `EventSource`, `setTimeout`,
+`clearTimeout`), which is what lets `ui/smoke/sections/feed-reconnect.tsx` drive
+the whole state machine headlessly, both removed dead ends included.
+
 What it shows, at this commit — the section is written to be re-read against
 `ui/src/App.tsx` and `ui/src/components/chrome/TabNav.tsx`, which are the two
 files that answer it:
@@ -1046,6 +1156,52 @@ files that answer it:
   columns (`ui/src/pages/Board.tsx`): Ready · In flight (`doing` + `stalled`,
   which carries a danger marker) · Review (`review` + `reviewing` + `changes`,
   three chips in one column) · Blocked · To merge · Done.
+  When the focused chapter is COMPLETE — landed, or every group but Done empty
+  with something done — the columns give way to the **chapter story**
+  (`ui/src/components/story/ChapterStory.tsx`): a single landing-timeline, one
+  tile per card in the order they landed, each with its closing line, diff-stat
+  and worked time, under a header of aggregate stats. Completion is DERIVED per
+  read from the board payload (`ui/src/components/story/stats.ts`) — no new
+  verb, no stored status — the data is the existing `activity` verb through
+  `useBoard`, and the view is read-only like the columns it replaces: a tile
+  opens the same card drawer.
+  An open chapter is read **two ways**, chosen by a `columns | flow` segmented
+  control (`components/board/ViewToggle.tsx`) whose state lives on the page and
+  in `localStorage`. Not a route and not a sixth tab: the flow IS the board drawn
+  differently, and a tab would file it beside Monitor and Actors as another page
+  with another payload. **Flow** draws the dependency graph left to right, agents
+  on the nodes; all of its geometry is decided without a DOM in
+  `components/flow/layout.ts`, and `FlowView.tsx` measures and paints and decides
+  nothing. **Every edge it can draw ends on a BLOCKED node**, which is the
+  payload read honestly rather than a shortcut: a `BoardRow` (`verbs/pulse.py::_row`)
+  carries no `after` — the card's whole dependency list is sent only on the CARD
+  read — and the one dependency fact on the board payload is `waiting_on`, which
+  `pulse.py::run` attaches to the blocked group alone from `core/graph.py::blockers`,
+  already filtered to the dependencies that have NOT closed. That is "closing a
+  blocker frees its dependents by definition" reaching the drawing. The bands
+  therefore cannot come from the edges — a done card with no surviving edge would
+  sit beside a running one — so each state has a FLOOR (done 0 · in flight 1 ·
+  waiting 2) that a longest-path over open blockers may raise and never lower.
+  A blocker the payload does not carry as a row yields no edge: a line to a node
+  that is not on screen is a line to nowhere.
+  In BOTH views a tile that changes column **moves** rather than teleporting
+  (`components/board/flip.ts` + `useFlip.ts`): First/Last/Invert/Play, one
+  `requestAnimationFrame`, CSS transitions and no animation library. The old
+  rects are cached at the END of every commit rather than measured on the way in,
+  because the payload arrives through `useBoard` several components up and a
+  refetch is not the only thing that re-lays the page out. Exits are NOT
+  choreographed — a tile the board no longer says exists would be a second source
+  of truth about what is on the board, for a quarter second of decoration — and
+  `prefers-reduced-motion` skips the play, never the layout, which is exactly the
+  behaviour that came before. The holder rides along: `shared/Avatar.tsx` is now
+  the ONE disc, serving both the header presence row and the card tile, which
+  disagreed before (four hash tones in the header, accent-vs-grey by role on the
+  tile — one agent, two colours, which reads as two agents). It has two
+  independent axes: the HUE is derived from the actor string over 24 steps
+  because this board runs eight agents in a wave and four tones is a guaranteed
+  collision, and `live` — the lease actually held — is the emphasis. Neither is a
+  literal colour: saturation, lightness and the wash's alpha are `--disc-*`
+  tokens declared once per theme.
 * **Actors** — the fourth view (`ui/src/pages/Actors.tsx`), and the one that
   answers "who has been on this board, what did they carry, and for how long".
   **It is a page about DEVS, and an agent is a LINE inside one.** It shipped
@@ -1065,6 +1221,14 @@ files that answer it:
   reads no verb and no new payload key: `team`, `doing`, `reviewing`, `stalled`
   and `board.hours` are four slices the board already sends, and
   `closed`/`commits` are counts over the SAME window, said once in the subtitle.
+  **Which window is a CHOICE, and it opens on the calendar month** — 7 days ·
+  This month · Last month · Total, a `Segmented` filter in the header
+  (`ui/src/hoursWindow.ts`), carried into the one board call as `window=` and
+  into the dev overlay unchanged. A sliding default is what read as "hours being
+  discounted when a chapter closes"; §21 has the whole diagnosis. The subtitle
+  says what came BACK, not what was asked: `windowSaid()` prints
+  `report.window.label` — the server's own "August 2026" — and falls back to the
+  day-bucket sentence for a board that sends no `window` at all.
   A figure the payload cannot say draws an em dash and never `0`, and a dev's
   totals are dev + agents — refused WHOLE when one member cannot say its own,
   because a sum over a subset presented as a total is the dishonesty this
@@ -1182,8 +1346,12 @@ files that answer it:
   constant and not a prop, so no caller can ask for a laxer frame. Everything
   else (forms, popups, top navigation, modals, downloads) stays withheld, and
   the frame carries `referrerpolicy="no-referrer"` and an empty `allow`. A
-  `text/plain` report is NOT framed: `srcdoc` parses as HTML, so it goes into a
-  `<pre>` as a React text node — escaped, whitespace intact, and no
+  `.md` report is answered `content_type: text/markdown` and drawn by the
+  shared markdown renderer (`ui/src/markdown.ts` →
+  `components/shared/Markdown.tsx`) with no frame and no sandbox — the renderer
+  builds React elements and emits no HTML. Only unrecognised types fall to the
+  `<pre>`: a `text/plain` report is NOT framed — `srcdoc` parses as HTML, so it
+  goes into a `<pre>` as a React text node — escaped, whitespace intact, and no
   `dangerouslySetInnerHTML` exists anywhere in this dashboard. It is pinned
   headlessly in `ui/smoke/sections/report-sandbox.tsx` against a report the
   fixture commits WITH a hostile `<script>` in it
@@ -1195,13 +1363,43 @@ files that answer it:
   carries the UI's ONE write, the comment box with its mention picker
   . The header's milestone picker scopes every tab at once.
 
+* **the comment toasts**, a stack bottom-right over every tab
+  (`ui/src/components/toasts/`), because the UI's one write was invisible to
+  everyone but its author: a comment landed and no other session's screen said
+  so. Everything is DERIVED client-side from the feed the Event pane already
+  reads — nothing is stored, no verb changed and there is no Python diff behind
+  it. `model.ts` is the whole of the decision-making and it is a plain module
+  with no React, no timers and no clock of its own: which comments are new, what
+  the preview trims to, how deep the stack goes and when a toast leaves are all
+  functions taking their clock and cursor as ARGUMENTS, which is what lets
+  `ui/smoke/sections/comment-toasts-model.tsx` and `…-stack.tsx` pin them under
+  `react-dom/server` with no jsdom and no stopwatch. "New" is a HEAD DELTA plus
+  an id set, not a per-event seq — `verbs/events.py` drops the rowid on the way
+  out, so the client derives the arrival count from `head - lastHead` against a
+  newest-first page one, and the id set catches the one case that arithmetic
+  over-counts (a burst larger than `EVENT_PAGE`). A toast is shown once, by
+  event id, ever, and the first load is SILENT: a page of history toasted on
+  mount would be fifty notifications about yesterday. "Already toasted" is a set
+  in memory and never a read-receipt — there is no mark-as-read verb on this
+  board and there must not be one (§11). A toast carries the author's avatar,
+  the card's title and the trimmed text; clicking it expands in place to the
+  whole message, and a SEPARATE affordance opens the card dossier through the
+  same `openCard`. The commented card's tile answers with a short-lived pulse
+  that returns to rest — the BORDER untouched, `components/board/CardTile.tsx`
+  argues why. No literal colour anywhere in it (`theme/tokens.css` only), and
+  `prefers-reduced-motion` suppresses every animation through the query helper
+  `components/board/flip.ts` already exported.
+
 Removed on purpose and not to be rebuilt: an "Attention" screen, which is in no
 Nova section, and an "Hours" tab, which in Nova is the Throughput panel *inside*
 Monitor.
 
 **The board points at the code** (`ui/src/links.tsx`): given a slug, a sha is an
-anchor to `…/commit/<sha>`, a card offers its PR-style `…/compare/<base>...<head>`
-and a chapter compares against the forge's own default branch — the trunk's name
+anchor to `…/commit/<sha>`, and a chapter compares against the forge's own
+default branch. The card dossier's Worktree block opens the dashboard's own
+worktree diff view (reading the local clone, no forge slug needed); forge
+`…/compare/<base>...<head>` links remain on the Worktrees index rows, the
+WorktreeDiff header and the chapter compare (the `compareUrl` consumers) — the trunk's name
 is not on the board, and a `main` in one of these URLs would be the UI guessing.
 The host is a VALUE (`BY_HOST`), not a second code path: GitLab differs by
 `/-/commit/` and nothing else. And it shows the diff ITSELF when the host it is
@@ -1250,7 +1448,7 @@ Three mechanisms, all client-side, all in the layers that already had git:
 | # | mechanism | where |
 |---|---|---|
 | 1 | a commit event carries `numstat` — `+/-` per file, `null` for a file git could not count (a binary, never a `0`) | `gitwork/bind.py` → `verbs/record.py`; drawn by `ui/src/links.tsx` on the dossier's commit list and on the Event stream |
-| 2 | branches reach `origin` by **best-effort pushes** at the three lifecycle moments that already exist — done, integrate, land | `gitwork/remote.py::push`, called from `gitwork/trees.py` / `mcp/gitmoves.py`. `trees.py`'s `merge_trunk` is the precedent and its comment is the contract: *best effort; local still landed*. Never a gate, never in a commit hook, never a board fact |
+| 2 | branches reach `origin` by **best-effort pushes** at the three lifecycle moments that already exist — done, integrate, land | `gitwork/remote.py::push`, called from `mcp/gitmoves.py` (done) and `gitwork/landing.py` (integrate, land). `landing.py`'s comment is the contract: *best effort; local still landed*. Never a gate, never in a commit hook, never a board fact |
 | 3 | the repo's forge slug is recorded ONCE, by the side that HAS the repo (`init`/`join`), as `{host, slug, url}`, and rides on the board payload | `gitwork/remote.py::remember` → `verbs/project.py`; consumed by `ui/src/links.tsx` |
 
 **The switch for all of it is `git remote get-url origin`, never a
@@ -1372,7 +1570,9 @@ clone, exactly as a patch does: `diff.resolve` for the rev, then `git show
 <sha>:<path>` through `gitwork/patch.py::show`, capped on the same `CAP` and
 flagged the same way (`capped()` is one function so the two answers cannot
 disagree about what `truncated` means). It answers the same JSON envelope, so
-`content_type` (`text/html` only for a literal `.html`) is a FIELD and never
+`content_type` — one of three values decided by extension: `text/html` for a
+literal `.html`, `text/markdown` for `.md`, `text/plain` for everything else
+(`gitdoor.py::_kind`) — is a FIELD and never
 this response's header — the token lives in this origin, so no file can make it
 serve HTML, and deciding what to do with `text/html` is the READER's job. It is
 done in one place, `ui/src/components/reports/ReportFrame.tsx`: an `<iframe
@@ -1715,13 +1915,14 @@ One thing the same incident exposed and this card did NOT fix: `Mounts` caches
 until the process restarts. It is noted in `_configuration`'s docstring so the
 next reader of that module knows it, and nowhere else.
 
-**Not yet running this chapter.** §18's door is in this tree and NOT on the
-domain — proved by asking it, not assumed: `POST /axion/join/github` answers
-*"nothing at /axion/join/github"*, and a `project op=forge` call on the axion
-board is refused with *"op='forge' is not a project fact — this board knows:
-('remote', 'visibility')"*. So the axion board has no forge declared and cannot
-have one until the sixth run of *Upgrading a host*. Everything §18 describes is
-true of the code and of the suite; nothing in it is true of production yet.
+**Not yet running this chapter.** §19 is in this tree and NOT on the domain —
+proved by asking it, not assumed: a `project op=forge` call on the axion board is
+refused with *"op='forge' is not a project fact — this board knows: ('remote',
+'visibility')"*. So the axion board has no forge declared and cannot have one
+until the sixth run of *Upgrading a host*. (The join door that same probe asked
+about — it answered *"nothing at …"* then, from a host running older code — no
+longer exists anywhere: §19.1.) Everything §19 describes is true of the code and
+of the suite; nothing in it is true of production yet.
 ---
 
 ## 18. Reports — the loop, end to end (2026-08-10)
@@ -1811,103 +2012,102 @@ agreed with the goal and paid for it with the mechanism: it had **GitHub login**
 — you handed it a token, it kept the token, and every sign-in was another call
 to GitHub with it. v2 deleted that on purpose, and this chapter brings back the
 convenience without any of the three things it cost. The whole design is one
-sentence: **GitHub proves WHO you are once, the server enrols your ssh key from
-that proof, and from the second call onwards the chapter is invisible.**
+sentence: **GitHub says once who works on the repo, the host enrols their ssh
+keys from that, and from then on the chapter is invisible.**
+
+The chapter shipped in two halves a day apart, and the second deleted the first.
+For one day the DEV carried the introduction (`taskops join --github`: their own
+token posted to `POST /<board>/join/github`, the host asking GitHub whether it
+had `need` on the declared repo). It worked and it was on the wrong side —
+§19.1 is the argument. What runs now:
 
 ```
-taskops join axion --github
+taskops board forge <owner>/<repo>        ← the OWNER, on their laptop
    │  gh auth token  /  $GITHUB_TOKEN  /  a hidden prompt      (never a flag)
+   │  1. record the fact, then re-READ it out of the answer  ← --clear asks nothing
+   │  2. GET /repos/owner/name/collaborators?permission=need  ·  paginated
+   │     the ONLY authenticated call, the token in a header and nowhere else
+   │  3. GET github.com/<login>.keys — PUBLIC, no token, no rate budget
    ▼
-POST /axion/join/github {github_token, principal, pubkey}
-   │  1. read the board's OWN declaration      ← no forge? refuse; nothing leaves the host
-   │  2. GET /repos/owner/name  ·  ONE call  ·  token in the header, nowhere else
-   │  3. permissions[need] is true → login.register(pubkey)   ← what an invite does
-   ▼  answers {principal, actor, role, fingerprint, repo, need} — NO token, NO session
-POST /login  →  the ordinary SSHSIG challenge, with the key just enrolled
+POST /rpc members.enroll {members: [{principal, keys}, …]}    ← ONE batch
+   │  login.register per person   ← what an invite does, exactly
    ▼
-every call after this one is what it would have been with an invite
+the dev, in a fresh clone:  taskops join   →  the ordinary SSHSIG challenge
 ```
 
+**The dev types two words and nothing about GitHub ever reaches them.** Their
+key was published on GitHub before any of this — somebody with push has already
+got one, which is the whole observation the chapter turns on — so asking them
+for a second one, or for a token, was redundant twice over.
+
 ### The three costs, and where each one goes
 
 **1. A token that travels.** A GitHub token is a bearer for everything that
 account can reach; v1 stored one per user, so the board's database became worth
-stealing for reasons that had nothing to do with the board. Here the token is a
-LOCAL and a header: read out of one request body, put in the `Authorization` of
-one outgoing call, and gone with the frame. It is not in `events.jsonl`, not in
-`server.sqlite`, not in `allowed_signers`, not in `remote.json`, not in the
-answer, and not spelled into any refusal — `_why()` names the repo and the
-access level and never the credential. On the client side it is never a flag
-VALUE either: `--github` is a `store_true`, because a secret passed as an
-argument is in `~/.zsh_history` before the process starts and in `ps` for every
-user on the box while it runs.
+stealing for reasons that had nothing to do with the board. Here exactly one
+token is read, on the machine of the person it belongs to, and it goes into the
+`Authorization` header of the collaborator pages and nowhere else: not to the
+taskops host at all (`members.enroll` takes principals and key lines and does not
+know what GitHub is), not in `events.jsonl`, not in `server.sqlite`, not in
+`allowed_signers`, not in `remote.json`, not spelled into a refusal —
+`cli/github.py::_why` names the repo and the access level and never the
+credential. It is never a flag VALUE either: a secret passed as an argument is in
+`~/.zsh_history` before the process starts and in `ps` for every user on the box
+while it runs, so the sources are `gh auth token`, `$GITHUB_TOKEN`, a hidden
+`getpass` prompt, in that order (`cli/github.py::token`).
 
 That is asserted rather than reviewed, in `tests/test_topology.py`:
-`test_the_github_token_is_written_to_no_file_and_no_event` greps every byte the
-host owns — the board log and the server store, not the two files somebody
-remembered — with a positive control proving the grep reads what the flow
-actually wrote; `test_join_github_is_one_command_and_what_lands_is_a_session_never_the_token`
-byte-scans the joined checkout afterwards; and
-`test_a_token_cannot_be_passed_as_a_flag_value_at_all` holds the parser to it in
-both argparse syntaxes.
+`test_the_owners_token_is_spent_on_ONE_endpoint_and_written_nowhere` greps the
+host's whole tree AND the owner's checkout, with a positive control proving the
+scan reads what the flow actually wrote, and checks that `<login>.keys` carried
+no credential; `test_the_dev_whose_key_the_sync_published_joins_with_two_words`
+byte-scans the joined clone afterwards; and
+`test_no_flag_on_join_takes_a_token_and_none_ever_will` holds the parser to it.
 
 **2. A network dependency at every login.** v1 could sign nobody in while GitHub
 was down or rate-limiting, because GitHub was the login. Here GitHub is asked
-exactly ONCE in a principal's life, and by the caller's own token — so the rate
-budget spent is theirs (5000/h authenticated against 60/h anonymous) and not a
-shared one this host could exhaust for everybody. `GET /repos/{owner}/{name}`
-answers `permissions` *for the authenticated user*, which is why one request
-settles the question. After that the credential is an ssh key and the door is
-`/login`; a board whose members are all enrolled never speaks to GitHub again,
-and `test_a_bare_join_still_works_unchanged_for_a_key_the_host_already_knows`
-pins that by counting ZERO further calls at the stub forge. When GitHub *is*
-unreachable the answer is `Unreachable`, loudly — a host that cannot ask does
-not guess (`test_github_unreachable_refuses_LOUDLY_and_never_falls_back_to_granting`).
+when the OWNER runs one command, by the owner's own token — so the rate budget
+spent is theirs (5000/h authenticated against 60/h anonymous) and never a shared
+one this host could exhaust for everybody. After that the credential is an ssh
+key and the door is `/login`; nobody's sign-in touches GitHub, ever, and
+`test_the_dev_whose_key_the_sync_published_joins_with_two_words` pins it by
+counting ZERO calls at the stub while the dev joins. When GitHub *is* unreachable
+the sync refuses loudly and enrols nobody — a host whose team could not be listed
+does not guess at one — and the fix is to run the same command again, because the
+declaration is already recorded when that happens.
 
 **3. A second identity system.** This is the one that actually killed v1's
 version: two kinds of "who", each with its own enrolment, expiry and revocation,
 and every feature afterwards written twice. There is no second kind here because
-the door creates nothing of its own. It calls `login.register` — the *same*
-function `invite/redeem` calls, renamed from `_register` and shared rather than
-copied — so what persists is a pubkey and a line in `allowed_signers`, byte for
-byte what an invite leaves behind. It mints no session and returns no token, so
-there is nothing to expire, nothing extra to revoke (`taskops revoke --key
-SHA256:…` retires a GitHub-enrolled key exactly as it retires an invited one),
-and `permit` has one table.
-
-**And no new row in `core/scope.py`, deliberately.** A server-scope operation is
-a rule about what a ROLE may do, and the caller at this door holds no role yet —
-the same as at `invite/redeem`, whose authorisation is the invite it burns and
-not a principal it does not have. GitHub's yes IS that proof, and the effect is
-the one `key.add` already describes; a `join.github` operation would be a second
-credential type standing where a role belongs. What the caller *becomes* is
-`member`, through the ordinary table, on the ordinary `/login`. Nor is it the
-banned anonymous write: a named account with a named access level on a named
-repo caused it, which is strictly more than an invite proves.
-
-One refusal is not about GitHub at all. `login.register` ADDS a key to a
-principal that already exists — right for an invite, since an owner re-joining
-must not be demoted — so through this door it would let anybody with push on the
-repo hang their own key off the name `berna`. A principal this host already
-knows is therefore refused here: membership of a repo is not permission to BE
-somebody (`test_membership_of_the_repo_is_not_permission_to_BE_somebody`).
+nothing in this chapter creates one. `members.enroll` calls `login.register` —
+the *same* function `invite/redeem` calls — so what persists is a pubkey and a
+line in `allowed_signers`, byte for byte what an invite leaves behind. No session
+is minted and no token returned, so there is nothing to expire, nothing extra to
+revoke (`taskops revoke --key SHA256:…` retires a GitHub-enrolled key exactly as
+it retires an invited one), and `permit` has one table.
+
+**The one row in `core/scope.py` is `members.enroll`, and it is a role rule.**
+The caller is a PRINCIPAL with a session an ssh key minted — the owner — and
+what it decides is who exists on this host, which is `key.add`'s wall and not a
+softer one. There is deliberately no `join.github` operation and no credential
+type beside the key: a role table answers "what may this role do", and "GitHub
+said yes" is not a role.
 
 ### Why the board must OPT IN
 
-`forge()` is `None` for every board ever created, and the door reads it FIRST —
-before the body is parsed and before anything leaves the host. A board that
-never declared a forge has no such door: it refuses with the sentence that says
-it is opened by invite, its stub forge records nothing, and its invite flow is
-byte-identical to the one it had before this chapter existed
-(`test_a_board_that_declared_no_forge_keeps_its_invite_only_door`). That is not
-politeness towards old boards — it is the only way "GitHub can open a board" is
-not also "anybody who can name a repo can open *your* board". The declaration is
-an owner's act, `{host, repo, need}`, refused loudly on every part of it
-(`core/forge.py::declare`): an unknown host, a slug that is not exactly
-`owner/name`, a `need` outside GitHub's own `push`/`admin`. `pull` is absent on
-purpose — read access to a public repo is not a membership. And it is
-REVERSIBLE: `op=forge` with `repo=""` clears the fact and the board is
-invite-only again, because opting in is reversible or it is a trap.
+`forge()` is `None` for every board ever created, and the sync reads it back out
+of the answer before it asks GitHub anything — so a board that never declared a
+forge, and a board whose owner cleared it, talk to GitHub not at all
+(`test_the_forge_is_cleared_back_to_invite_only_by_the_same_verb` counts the
+stub's calls across both). Such a board is invite-only, byte-identically to what
+it was before this chapter existed. That is not politeness towards old boards —
+it is the only way "GitHub can open a board" is not also "anybody who can name a
+repo can open *your* board". The declaration is an owner's act, `{host, repo,
+need}`, refused loudly on every part of it (`core/forge.py::declare`): an unknown
+host, a slug that is not exactly `owner/name`, a `need` outside GitHub's own
+`push`/`admin`. `pull` is absent on purpose — read access to a public repo is not
+a membership. And it is REVERSIBLE: `op=forge` with `repo=""` clears the fact,
+because opting in is reversible or it is a trap.
 
 Reading the same fact back is asymmetric and that asymmetry is the design:
 `declare` refuses loudly because a human is typing and a typo that defaults to
@@ -1918,17 +2118,171 @@ than as a promise the host cannot keep.
 
 ### How a board opts in
 
-`op=forge` is an owner's act and it now has a door a human reaches: `taskops board
+`op=forge` is an owner's act and it has one door a human reaches: `taskops board
 forge <owner>/<name> [--need push|admin]`, with `--clear` to make the board
 invite-only again. It is a server-scope OWNER operation beside `board.visibility`
-in `http/admin.py::REGISTRY` — same table, same role gate, no second door.
-
-`http/github.py::NO_FORGE` names that command, and the naming is a TEST rather
-than a string comparison: `test_the_refusal_names_a_command_the_cli_really_answers`
-splits the refusal's own sentence and feeds it back as argv, then reads the fact
-back. That refusal advertised a command that did not exist once — sending the one
-reader already blocked to an argparse error — and executing it is what makes that
-the last time.
+in `http/admin.py::REGISTRY` — same table, same role gate, no second door — and
+since 2026-08-11 that same command SYNCS the repo's team into the host (§19.1).
+
+### And how anybody else finds out
+
+Declaring it wrote an event on the host and nothing else — correctly, since a
+forge is a fact about the BOARD and a committed file would be a second place the
+truth lives. But for one chapter the READ side had the same hole the write side
+never did: the fact was in the log, `forge()` read it, the door acted on it, and
+it was in no payload. An agent with full board access could not tell that this
+board is one whose repo team the owner can sync in, and the dashboard could not
+draw what it could not read. **Discovery was by bumping into a closed door.**
+
+It now rides on the `board` payload beside `visibility`, which is the same move
+for the same reason (`verbs/pulse.py`, `verbs/project.py`): derived per read
+from `project.forge(stores)`, one log, one fold, one reader — the payload simply
+stopped hiding it. That is also what makes the line above true, that neither
+`board.visibility` nor `board.forge` needs a `get` half.
+
+**A board that declared no forge sends NO KEY** — not `null`, not `{}`. The
+splat in `pulse.py` is what enforces it, and it is not a nicety: `None` would be
+a third state (absent / null / a fact) for every consumer to learn, when
+`core/forge.py` spent a whole module collapsing absent, cleared and
+unintelligible into ONE answer. Proved rather than assumed — a forge-less
+board's whole payload is byte-identical across this change, and
+`tests/test_verbs.py::test_a_cleared_forge_takes_the_key_out_of_the_payload_again`
+pins that clearing a forge returns the payload to exactly the key set it had.
+
+The dashboard draws it as one line under the board's own identity in the header
+— `github.com/cloudacio/Axion · push` — text and not an anchor, because
+`ui/src/links.tsx` owns every forge URL the dashboard emits and keys them off
+`BoardPayload.repo`, a DIFFERENT fact that may name a different repo. The
+command a reader would need is the line's `title`
+(`ui/src/components/chrome/Header.tsx`, `ui/smoke/sections/forge-opens-the-board.tsx`).
+
+### 19.1 The introduction moved to the OWNER (2026-08-11)
+
+The half of the chapter that deleted the other half. Everything below shipped a
+day after the door above, and on the second day the door was removed: `POST
+/<board>/join/github`, the `--github` flag, the client's `by_github`, the token
+discovery inside `join`, and the six tests that pinned them. Deleted, not
+deprecated — there is no route answering 410 and no dead flag.
+
+**Why the dev's door was the wrong side.** It asked each dev to prove a fact the
+owner already holds, and charged them a credential to do it: their GitHub token
+left their machine, on every first join, to be verified by a host that has no
+business seeing one. Berna put it in one sentence — requiring push on the repo
+AND a separate ssh key is redundant, because whoever pushes over ssh has already
+published the key they push with. So the same question is asked once, by the
+person whose token it is, and the dev's side becomes `taskops join`.
+
+**What the deleted tests pinned, and where it went.** The token in no file: now
+`test_the_owners_token_is_spent_on_ONE_endpoint_and_written_nowhere`, over a
+wider surface (host tree *and* checkout). The three refusals by name: now
+`test_github_refusing_the_owners_token_names_the_repo_and_enrols_nobody`. An
+unreachable GitHub never degrading into a yes: the sync enrols nobody and says
+to run it again. A board with no forge never talking to GitHub: counted at the
+stub in the `--clear` test. Membership not being permission to BE somebody: it
+cannot arise — nothing enrols on a stranger's say-so any more. And the whole
+flow, from both ends, in
+`test_the_dev_whose_key_the_sync_published_joins_with_two_words`.
+
+### The host enrols in BATCH — `members.enroll` (2026-08-11)
+
+The seam the owner's side of this chapter stands on, and the one row it takes in
+`core/scope.py`: this is called by a PRINCIPAL with a role — the owner, over
+`/rpc`, with a session an ssh key minted — and what it decides is *who exists on
+this host*. That is `key.add`'s wall and not a softer one because the argument is
+a list (`http/members.py`, `admin.py::REGISTRY`).
+
+```
+{"verb": "members.enroll", "args": {"members": [{"principal": "ana",
+                                                 "keys": ["ssh-ed25519 AAAA…"]}]}}
+-> {"enrolled": […], "added": [{principal, fingerprint}…], "unchanged": […],
+    "skipped": [{principal, fingerprint, why}…], "others": […], "signers": 3}
+```
+
+**It does not know what GitHub is.** It receives principals and key lines; the
+forge, the collaborator list and the owner's token live entirely in the CLI that
+calls it, so there is no token to store here because none ever arrives. And the
+enrolment is `login.register` — the same function the invite door calls, which
+is what keeps "an existing principal only ever GAINS a key" one rule rather than
+two: a batch that names the owner leaves the owner an owner
+(`test_the_owner_re_enrolled_stays_owner_and_the_keys_accumulate`, beside the
+invite door's own `test_a_re_join_never_demotes_the_owner_it_only_adds_a_key`).
+
+**Idempotent by SKIPPING, not by rewriting.** A key already live for its
+principal is not written again, so a re-run touches no row and `allowed_signers`
+comes out byte for byte (`test_one_batch_enrols_a_team_and_re_running_it_leaves_the_same_state`).
+Two keys are refused and REPORTED rather than obeyed: a fingerprint the owner
+revoked — otherwise the next sync undoes every revocation — and one another
+principal already holds, which the fingerprint being the primary key would MOVE,
+silently stopping somebody outside the batch from signing. The whole batch is
+validated (names and key grammar) before a single row is written, so a typo in
+the tenth entry does not leave nine enrolled.
+
+**And it revokes nobody.** A principal enrolled by invite has no reason to be in
+a forge's collaborator list, so a sync that never heard of them would revoke them
+for existing. The answer instead carries `others` — every principal the batch did
+not name, with their live fingerprints, which is what `taskops revoke --key`
+takes — and the decision stays a human's
+(`test_the_answer_names_who_the_batch_did_NOT_name_and_revokes_nobody`).
+
+### The command itself — `taskops board forge` declares AND syncs
+
+Declaring and syncing are ONE command because they are one intention. The owner
+who names the repo means "these people work here"; a second verb to make that
+true is a second thing to forget, and the whole point of the chapter is that the
+dev on the other end types `taskops join` and nothing else. So `taskops board
+forge <owner>/<repo>` records the fact and then, on the fact **re-read out of
+the answer** (never on its own argv, which is why `--clear` asks GitHub nothing):
+
+```
+cli/operate.py::_forge   declares, signs in ONCE, hands the session down
+  └─ cli/team.py::sync   the flow and the report — knows no transport
+       ├─ cli/github.py::token()         gh auth token → $GITHUB_TOKEN → hidden prompt
+       ├─ cli/github.py::collaborators() GET /repos/…/collaborators?permission=push
+       │                                 …paginated. AUTHENTICATED, and the only call that is
+       ├─ cli/github.py::keys_of()       GET github.com/<login>.keys — PUBLIC, no token
+       └─ members.enroll                 ONE batch to the host (§19 above)
+```
+
+**The token's whole life is `collaborators`.** It is read on the owner's laptop,
+put in one `Authorization` header per page, and dropped with the frame — not
+returned, not printed, not written, and *not sent to the taskops host at all*.
+That is the difference from the door this replaced, where a stranger's token
+arrived in a request body: here it never leaves the machine that owns it, and
+`test_the_owners_token_is_spent_on_ONE_endpoint_and_written_nowhere` greps the
+host's whole tree AND the checkout's for it, with a positive control so the scan
+is known to be reading real bytes.
+
+**Pagination is not a detail.** A first page is 30 by default and 100 at most,
+and a team that outgrows one page is exactly the team this command exists for:
+stopping at page one enrols some of them and reports the rest as DRIFT, which
+reads to the owner as a revocation list. `test_the_forge_enrols_every_collaborator_with_push_across_every_page`
+puts five people over three pages against a real socket.
+
+**Nobody is dropped in silence, and that is the whole report.** Three outcomes
+travel back and each names its own way out:
+
+| what happened | printed as |
+|---|---|
+| enrolled / already there | `enrolled`, `unchanged`, `keys N added` — from the host's own answer |
+| a collaborator with no ssh key on GitHub | named, with `taskops invite <login>` |
+| a principal here who is no longer a collaborator | named, with the exact `taskops revoke --key SHA256:…` |
+
+The third one is REPORTED and never acted on, for §19's reason: a principal
+enrolled by an invite is not a GitHub login, so a pruning sync would retire them
+for having been introduced the other way. The owner is excluded from that list
+outright — a `revoke` line beside the account running the command is a way to
+lock yourself out of your own host. A login GitHub capitalises is lower-cased on
+the CLI side, because a principal name is `[a-z0-9._-]` and `Ana` would be
+refused mid-batch; a `Bot` collaborator is dropped by `type`, having neither a
+legal principal name nor a key to publish.
+
+`_wire.text()` exists for this, and is now the only foreign GET in the package:
+it briefly had a sibling decoding into an OBJECT, and neither of the two answers
+here is one — `.keys` is `text/plain` and the collaborator page is a JSON *array*,
+which `as_object` flattens to `{}`. A page of people silently reading as nobody
+is the bug that shape prevents, so the decoding belongs to whoever knows what it
+asked for and only the status and `Unreachable` are shared.
+
 ## 20. A board's whole life — create → push → (live) → pull → rm (2026-08-10)
 
 Until this chapter a board's life ran one way. `board create` made one, `board
@@ -2113,3 +2467,93 @@ reads the committed report back at its sha.
 `taskops` already has, and no chapter can dogfood one it introduced. Registering
 this report belongs to the session after `ms-b9bf00` puts master on the host and
 the tool on the laptop — the milestone that exists for exactly that.
+
+## 21. Hours you can trust — the edge rule, and calendar anchors (2026-08-14)
+
+Berna reported hours being "discounted" when chapters close. Diagnosed against
+the live log, not guessed: **no event is ever lost.** `events.jsonl` only grows
+and the land machinery refuses to touch a dirty board file. The complaint was
+true, and it was windowing arithmetic plus a missing anchor.
+
+### The artifact, exactly
+
+Every figure the dashboard drew was over one sliding window, and
+`core/hours.py::sessions` only counted an interval when BOTH of its stamps were
+inside it — `report.summary` handed it `cache.window(start, end)`, so an
+interval that straddled the leading edge arrived with its opener already
+filtered out and was counted by NOBODY. A chapter close produces a burst of
+events. Days later the window's leading edge crosses that burst and **whole
+intervals vanish at once**, so the total falls by more than the elapsed time.
+That is precisely what reads as "hours deducted when a chapter closes".
+
+### Half one — an interval belongs to the window its CLOSING stamp is in
+
+`sessions(stamps, since=)` keeps an interval when the stamp that CLOSES it is at
+or after the edge, whatever its opener. The caller's one duty is the FETCH:
+`report._fetch` reads from `start - hours.GAP`, because nothing older than the
+longest countable interval can pair into the window anyway. The keeping is
+`sessions()`'s decision, once.
+
+**The rule lives in `core/hours.py` and not in the feeding** because `sessions()`
+is the one definition of what an interval is, and the timesheet blocks and the
+total beside them must stay one pass — a caller that filtered its own events
+would be a second definition, and the blocks would disagree with the total the
+moment the two drifted. The counts beside the hours (`closed`, `commits`,
+`cards`) stay strictly inside the window: they count EVENTS, not intervals, so
+the pre-roll is not theirs to see. `tests/test_core.py` replays one log through
+two adjacent window positions and pins that the sum changes only by real aging.
+
+### Half two — the vocabulary, one place
+
+`verbs/_windows.py::parse` is the ONE decision of what a `window=` spelling
+means, and every form resolves through `core/hours.py` so the DST rule holds for
+all of them (both edges out of the same zoneinfo walk, never an opening stamp
+plus a count of seconds):
+
+```
+7d        the last N calendar days, 1..90 — the sliding figure
+month     this calendar month in the caller's tz, first midnight → today
+2026-07   that calendar month, closed on BOTH edges — a figure that never moves again
+total     the whole log, the figure that only grows
+```
+
+An unrecognised spelling is **REFUSED, and the refusal names all four.** The
+earlier `days()` fell back to 7 for anything it did not understand, which is how
+`7dd` or `august` becomes a plausible number nobody questions.
+
+Two edges are argued in the code and easy to get wrong. An OPEN-ended span
+(`month`, `total`) closes on the next local midnight, never on `now`: every edge
+here is half-open, and the event that closes the current interval is usually the
+one stamped `now` — ending there silently dropped the last block of work from
+the very window a person opens to see it. And `total` carries NO day buckets
+(`days_total: 0`): the whole log grows by a bucket a day forever, most of them
+empty, so a truncated tail would be mistaken for the span.
+
+The resolved `Span` rides on the answer (`window` in the payload: the spelling
+asked, the kind, a printable label, both edges), so a screen titles itself
+"August 2026" instead of inferring a month from two epoch floats.
+
+### Half three — the page anchors on a figure that only grows
+
+The Actors page opens on the CURRENT MONTH (`ui/src/hoursWindow.ts`,
+`DEFAULT_HOURS_CHOICE`) with a visible filter — 7 days · This month · Last month
+· Total — and the per-actor overlay carries the same span. A sliding window as
+the default is what read as hours being discounted.
+
+`hoursWindow.ts` maps four labelled options onto four server spellings and
+repeats none of the arithmetic; everything the screen prints about the span
+comes back on `ReportPayload.window`, because a client re-deriving "August 2026"
+from two epoch floats is a second calendar implementation in a second language
+and a second zone. ONE spelling is computed in the browser and has to be: `last`
+is "the month before the one the READER is in", emitted as a bare `YYYY-MM` —
+the form the server closes on both edges — and `lastMonth(now)` takes `now` as a
+parameter so the January case (`2026-00`) is testable.
+
+The window is an ARGUMENT to the one `board` call, exactly as `milestone` is
+(`ui/src/useBoard.ts`) — still ONE fetcher, one coalesced refetch, one snapshot
+every pane reads. It is not the per-tab fetcher §15 refuses. The cost is stated:
+Throughput draws exactly `THROUGHPUT_DAYS` bars into a viewBox cut into that
+many slots and Actors anchors on a calendar month, so one number cannot be both,
+and moving between those tabs costs one request. A board one version behind
+sends no `window` key at all, and `windowSaid()` falls back to the day-bucket
+sentence — a degradation, never a blank.