@vibelord/lanes 1.2.0 → 1.3.0

package/payload/lanes/libexec/docsd.py

@@ -0,0 +1,2010 @@
+#!/usr/bin/env python3
+"""lanes-docsd — the docs cockpit's web service (W10 W3, LNS-104).
+
+What an agent publishes from a lane, and what a person uploads, is opened here from the phone or laptop shell over the
+tailnet, bound to the person's login. `lanes-docsd.service` runs this file on 127.0.0.1:8185 (`LANES_DOCS_PORT`;
+`--port`, `--bind`: a loopback address only — the service trusts the identity headers its proxy chain sets), behind the
+loopback Caddy of `lanes-mobile.service` (`handle_path /lanes-docs/*`, which strips `/lanes-docs`) behind Tailscale
+Serve (`https://<host>.<tailnet>.ts.net:8443/lanes-docs/...`). Standard library only. The documents, their receipts,
+counts and docs.log are docs_store.py's (W1); Markdown is rendered by mdlite.py (W2).
+
+Who is served (plan "Auth and threat model", binding). A request is answered only when ALL hold, checked in this order
+by Service.gate, each refusal a 403 with its word:
+  not-through-serve   enrold.through_serve: the X-Forwarded-For Serve sets and Caddy keeps names a non-loopback
+                      address (a probe of 127.0.0.1:8185, or of Caddy from this host, carries none)
+  no-identity         enrold.caller_of(headers).present: Serve's Tailscale-User-Login and -Name header set (a tagged
+                      device has none)
+  invalid-login       the login validates as members.py stores one
+  not-pinned          enrold.read_mode()[0] == 'request': the operator ran the RUNBOOK's Serve header check and pinned
+                      `lanes enrol mode request`. Unpinned (auto), pinned `invite` or unreadable: refused — docsd never
+                      latches anything from traffic and never reads LANES_ENROL_REQUEST_MODE
+  not-a-member        login.casefold() in enrold.member_logins(): the login owns a valid members/<device>.json
+  domain-not-allowed  enrold's domain rule over LANES_DOCS_DOMAINS (else LANES_ENROL_DOMAINS; default beyondwork.ai;
+                      comma/space separated, `*` = any)
+  cross-site          fetch_site_ok, on EVERY route (security review 2026-10-08, F2): the request's Sec-Fetch-Site
+                      is `same-origin` or `none` (a page, script, stylesheet or image of this site, or a navigation the
+                      person started: the address bar, a bookmark, a link opened from a terminal or another app) — or
+                      it is a top-level navigation, a GET or HEAD with Sec-Fetch-Mode `navigate` and Sec-Fetch-Dest
+                      `document`, whatever its Sec-Fetch-Site (a link tapped in ntfy's web app, a chat or a mail).
+                      Everything else from another site is refused: a sandboxed artifact is an opaque origin, so its
+                      fetch() and subresource loads are `cross-site` (mode cors/no-cors, dest empty/image/script/…),
+                      and *.ts.net is a public suffix, so another tailnet host's page is `same-site`; neither may spend
+                      the viewer's login here. POST /up keeps the stricter rule: `same-origin` or `none` only, a
+                      navigation included (a form posted from another site). An absent Sec-Fetch-Site is refused
+                      unless the request is such a navigation: every browser that reaches Serve sends the headers
+                      (Chrome 76, Firefox 90, Safari 16.4). The artifact's sandbox (`sandbox allow-scripts`, nothing
+                      else: no allow-popups, allow-top-navigation, allow-forms or allow-downloads) cannot open a
+                      window, submit a form or navigate another browsing context; the one navigation its script can
+                      start is of its own page, which replaces it (its script ends) unless the answer is a download the
+                      sandbox then blocks — so what it can request through the navigation exemption is bounded by the
+                      per-login limit below (VIEWS per VIEW_WINDOW; the HTML standard's rules, not measured in a
+                      browser).
+No Zellij cookie is consulted, ever. DEF-1645 (a process that reaches loopback can send the headers itself) stays the
+documented open risk; the pin gate and the Serve-only check are the controls. Never put this behind Tailscale Funnel.
+A refusal is one docs.log `denied` line per source (the tailnet address Serve forwarded, else the peer) and word; the
+same source refused again within DENIED_REPEAT_S adds no line, and one `denied-repeat` line per DENIED_REPEAT_S says how
+many it folded (its `bytes` field is that count); the login is logged at most MAX_DENIED_LOGIN characters (F4).
+
+Limits (security review 2026-10-08, F2/F5/F8; per process): an authenticated login makes at most VIEWS requests other
+than POST /up in VIEW_WINDOW s (more: 429 rate-limited + Retry-After, one docs.log line per window); at most
+RENDER_SLOTS Markdown renders run at once (a view waits RENDER_WAIT_S for one, then 503 busy); a rendered Markdown
+document is kept in memory by its sha256, least recently used out first, at most RENDER_CACHE_BYTES in all and
+RENDER_CACHE_ENTRY each, so viewing it again renders nothing; UPLOAD_SLOTS big buffers at once, shared by uploads and
+decryptions, and at most one upload per login; an upload's body must arrive within BODY_GRACE_S + its length /
+BODY_MIN_RATE seconds, else 408 request-timeout and its slot is free again.
+
+Who sees a document (visible). docs_store's own rule lets a login see what its store holds, what `for` names it in,
+and every document whose `for` is empty; docsd narrows the last case. A document is visible to the caller when
+  * it is in the caller's own store (docs/<stem(caller)>/…: an upload of theirs), or
+  * its `for` is not empty and names the caller (casefolded), or
+  * its `for` is empty and a member record the caller owns grants the document's workspace (member_workspaces): a
+    record's `workspaces` (the board ids an invite recorded with `lanes invite --workspaces`) grants those boards, and
+    a record that lists none (empty or absent: a key added by hand, a request, an invite minted without
+    `--workspaces`) grants every workspace this host serves (the registry's). Nothing else in Lanes narrows by that
+    list — a view shows every board — so an empty list never meant "no board" (DEF-1852). The upload form's lanes
+    (upload_targets) and `POST /up` follow the same grant.
+A document the caller cannot see is answered 404, exactly like one that does not exist.
+
+Publish pick-up (plan W10 W4; Pickup, a daemon thread main() starts, on its own PICKUP_INTERVAL = 5 s cycle — never
+statusd's). `lane publish <file>` and lane-mcp's `lanes_publish` write ~/.lz/state/publish/<lane>/<id>.json in a
+workspace container (DM-LANES-PUBLISH-REQUEST, lane_core.publish). Each cycle, for every container containers.json
+names whose init pid is alive, whose /proc/<pid>/root is not the host's own `/` (a recycled pid), and — when this
+account can see the home volume containers.json records for it — whose /home/coder is that volume (same st_dev and
+st_ino: a pid the kernel gave another container is skipped; F10), the pick-up first surveys the container's publish
+directory and its lane directories (os.scandir, opened without following a link, `L.open_real_dir`): at most
+MAX_ENTRIES entries in all are examined per container per cycle, nothing more is read, and a container that holds more
+is refused for the cycle — nothing is taken from it, and the journal says so once per OVER_CAP_SAY_S (F1: listing
+100,000 planted lane directories took 5.7 s and 116 MiB a cycle; ~650,000 crossed MemoryMax). Then, lane by lane, at
+most MAX_PICKUPS requests per container:
+  1. claim: `<id>.json` is renamed to `.<id>.taking` in the same directory (nothing is read from a directory docsd
+     cannot write: a request it could not remove would be taken again every cycle). A directory planted at the claim's
+     name is removed when empty, else moved aside to a dot name; a request that still cannot be claimed is skipped and
+     the next one is taken (F9: one planted `.taking` directory stalled its lane's queue);
+  2. read it as a regular file of at most MAX_REQUEST bytes (`L.read_regular_at`: never a link or a FIFO) and check
+     it: `v` 1, `path` absolute, `kind` md|html|svg|file, `claimed_sha256` 64 hex, `bytes` <= PUBLISH_LIMIT (the
+     docs limit, 32 MiB), `title`/`for`/`mime` strings or null; the lane must be one the registry places in THIS
+     container; PUBLISHES requests per container per PUBLISH_WINDOW s;
+  3. resolve `path` inside the container (`L.container_realpath`: a link restarts at the container's root, never the
+     host's) to a file under /home/coder, open every directory without following a link (`L.open_real_dir`) and the
+     file O_NOFOLLOW|O_NONBLOCK, a regular file of at most PUBLISH_LIMIT bytes: a link swapped in meanwhile, a FIFO,
+     a device or a larger file is refused, so a container never makes the host read outside its home;
+  4. stream it into docs_store.intake(login, ws, lane, name, …, limit=PUBLISH_LIMIT, source='publish', kind, title,
+     for_logins, by=<lane id>) through a reader that hashes as it goes and, at the end, refuses a sha256 other than
+     the claimed one inside intake (which then removes what it wrote: nothing is stored);
+  5. write `<id>.receipt.json` back beside the request (`L.atomic_write_at`, 0644; the statusd write_container_status
+     pattern: replaced by rename, never written through a link; a directory planted at that name is removed or moved
+     aside first, F9; DM-LANES-PUBLISH-RECEIPT) — {v: 1, id, request, sha256, bytes, url, at, outcome: ok} or {…, id:
+     null, url: null, outcome: refused, reason} — remove the claim, keep the newest MAX_RECEIPTS receipts of the lane,
+     and append one docs.log `publish` line (outcome `ok` or the reason). The counts follow through intake. A busy
+     store leaves the claim's request for the next cycle.
+Refusal reasons (docs.log): unreadable-request, bad-version, bad-request, bad-kind, bad-title, too-large, unknown-lane,
+rate-limited, for-not-a-member, no-recipient, outside-home, not-a-file, sha256-mismatch, invalid (intake refused),
+error (anything else after the claim: the journal has it). The receipt says the same word, except that
+for-not-a-member and no-recipient both say `not-delivered` (F6: the two words told a container whether a login it
+named owns a member record; a `for` naming a member still answers ok). Without a registry.json nothing is taken (a
+request waits).
+
+Who a published document is for (recipient): the request's `for` — a login that owns a member record (else refused
+`for-not-a-member`), stored in that login's store with `for` = [it]; else the member whose profile's `last_opened.lane`
+is this lane, the latest `at` winning (users/<login>.json), the same way; else every member whose record grants the
+lane's workspace (member_workspaces' rule): `for` empty, stored in the store of the first of them by casefolded login
+(none: refused `no-recipient`). Logins are spelled as their member record spells them. A successful pick-up sends one
+`published` push through notify (notify.notify_published: notify.conf, the desk-presence rule, at most one per lane
+per PUBLISHED_PUSH_S), best effort, after the cycle's receipts are written.
+
+Wire contract v1 (DM-LANES-DOCS-WIRE; paths as docsd sees them, after Caddy strips /lanes-docs; every link and asset
+reference a page carries is RELATIVE, so the pages work under that prefix):
+  GET  /                       200 page: the caller's visible documents, workspace -> lane -> newest first, with counts;
+                               the upload form (the lanes of the caller's workspaces); an empty state
+  GET  /?ws=<ws>&lane=<lane>   the same, only that workspace and/or lane (the sidebar's and the shells' deep link for a
+                               lane is exactly `/lanes-docs/?ws=<ws>&lane=<lane>`, W7). Either may be left out. A value
+                               must be known to the caller (index_filter: a workspace a member record of theirs lists,
+                               or one a visible document is in; a lane of the registry in such a workspace, or one a
+                               visible document is in, and in the named workspace when both are given) — anything
+                               else, a repeated or empty value included, is 404 not-found
+  GET  /d/<id>                 200 page by kind: md -> mdlite.render() in the page (503 busy + Retry-After when no
+                               render slot frees within RENDER_WAIT_S; a document rendered before comes from the cache);
+                               html|svg -> title, facts and a link to d/<id>/artifact (never embedded, no iframe);
+                               upload|file -> facts and a download link
+  GET  /d/<id>/raw             200 the stored bytes: Content-Disposition: attachment; filename="<name>", X-Lanes-Sha256
+  GET  /d/<id>/artifact        200 for kind html|svg only (else 404): the bytes as a top-level document with
+                               Content-Security-Policy: sandbox allow-scripts (nothing else) — an opaque origin
+                               An ENCRYPTED document (docs_store's `age` switch, meta `enc`): raw and artifact decrypt
+                               it on the fly when LANES_DOCS_AGE_IDENTITY names an identity file (at most MAX_BODY
+                               bytes, one at a time, checked against the receipt), else 409 encrypted (a page: fetch
+                               the copy in the workspace's uploads/); its view shows the facts, Markdown rendered only
+                               when it can be decrypted
+  GET  /receipt/<id>.json      200 the document's receipt.json bytes (DM-LANES-DOCS-RECEIPT), application/json
+  GET  /docs.css, /docs.js     200 lanes/web/docs.css|docs.js of the tree this process runs (W6 writes them), else 404
+  GET  /upload.css, /upload.js 200 lanes/web/upload.css|upload.js (W5: the index's drop area), else 404
+  POST /up                     multipart/form-data: `lane` (a lane id of the registry), optional `ws` (must be that
+                               lane's workspace), one or more file parts (a part with a filename). The workspace must be
+                               one the caller's member records grant. Each file goes through uploads.receive (W5): it
+                               lands in the workspace's uploads/ folder in its container (`<folder>/uploads/<name>`,
+                               name docs_store.clean_name's, `-1` on a collision, exactly as `lanes upload` lands one)
+                               AND docs_store.intake(login, ws, lane, name, …, source='web', kind by extension (md,
+                               html, svg, else file), for=[caller], by=caller) in one pass, both or neither, and is
+                               answered with a receipt {id, name, sha256, bytes, url, at, landed} (`landed` the
+                               in-container path an agent reads): 200 JSON {receipts} (an
+                               Accept without text/html) or a page. Refused: 429 rate-limited + Retry-After (UPLOADS
+                               per login in UPLOAD_WINDOW s, counted when the attempt starts), 503 busy + Retry-After
+                               (UPLOAD_SLOTS uploads and decryptions at once, one per login, or the store lock), 415
+                               not multipart/form-data, 411 no Content-Length (or a chunked body), 413 over MAX_BODY (32
+                               MiB), 408 request-timeout (the body did not arrive within BODY_GRACE_S + length /
+                               BODY_MIN_RATE s), 400 bad-request (a
+                               malformed form) | no-file | no-lane | unknown-lane | unknown-workspace, 503
+                               registry-unavailable (no registry.json to resolve the lane in), 503 uploads-unavailable
+                               (the workspace's container folder cannot be written: not running, a link on the way),
+                               500 encrypt-failed (the `age` switch is on and age failed). The gate's `cross-site`
+                               (403) applies to an upload with no navigation exemption: same-origin or none only
+  every route but POST /up     429 rate-limited + Retry-After past VIEWS requests per login in VIEW_WINDOW s
+  everything else              404 not-found (an id is matched against docs_store's id rule before any path is formed;
+                               `..`, encoded dots and overlong ids never match); a known path with another method 405
+Errors are JSON {"error": <word>}, or a short page when the Accept header names text/html. A request body left unread
+by a refusal is read away up to its Content-Length (at most DRAIN_LIMIT) BEFORE the answer, and the answer carries
+`Connection: close`; past DRAIN_LIMIT the answer is sent, the write side shut and the rest read away for LINGER_S
+seconds, so the client still reads the refusal instead of a reset (DEF-1854).
+
+Headers. Every response: Cache-Control no-store (static files no-cache), X-Content-Type-Options nosniff,
+X-Frame-Options DENY, Referrer-Policy no-referrer and a Content-Security-Policy: a page PAGE_POLICY, an artifact
+exactly ARTIFACT_POLICY, everything else DATA_POLICY. The site-wide Caddy header block skips /lanes-docs/* (`header
+@notdocs`), so these are the only ones a document gets.
+
+docs.log (DM-LANES-DOCS-LOG, through docs_store.audit; never content, a title or a name): `denied` (a gate refusal,
+the outcome is its word; coalesced per source, with `denied-repeat` lines, see the gate above), `view` `raw` `artifact`
+`receipt` (ok | not-found | encrypted | busy | rate-limited), `upload` (a refusal before any file reaches intake;
+intake writes its own `intake` line per file) and `publish` (one per request the pick-up takes: the store login, the
+document id, the lane, the host's bytes and sha256 when known, `ok` or the refusal reason).
+"""
+import argparse
+import collections
+import email.message
+import email.parser
+import email.policy
+import errno
+import hashlib
+import html
+import ipaddress
+import json
+import os
+import re
+import socket
+import socketserver
+import stat
+import sys
+import threading
+import time
+import traceback
+import urllib.parse
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import lanes_lib as L  # noqa: E402
+import docs_store as D  # noqa: E402
+import enrold as E  # noqa: E402
+import keys as K  # noqa: E402
+import mdlite  # noqa: E402
+import notify as N  # noqa: E402
+import uploads as U  # noqa: E402
+import users  # noqa: E402
+
+WIRE_VERSION = 1
+DEFAULT_PORT = 8185                    # web/Caddyfile `handle_path /lanes-docs/*` forwards here
+DEFAULT_BIND = '127.0.0.1'
+MAX_BODY = 32 * 1024 * 1024            # a POST /up body; also each file's intake limit (uploads.UPLOAD_LIMIT)
+DRAIN_LIMIT = 2 * MAX_BODY             # an unread body is read away up to this BEFORE a refusal is sent (DEF-1854)
+LINGER_S = 5                           # past DRAIN_LIMIT: seconds the rest is read away after the answer
+MAX_PARTS = 64                         # parts of one form (fields and files)
+MAX_PART_HEADER = 8 * 1024             # one part's header block
+MAX_FIELD = 1024                       # one non-file field's value
+MAX_CONTENT_TYPE = 512
+MAX_STATIC = 512 * 1024                # docs.css / docs.js
+UPLOADS = 30                           # POST /up attempts per login in UPLOAD_WINDOW seconds
+UPLOAD_WINDOW = 600
+UPLOAD_SLOTS = 2                       # big buffers at once (<= MAX_BODY each): uploads parsed and documents decrypted
+BUSY_RETRY = 5                         # Retry-After of a 503 busy
+DECRYPT_WAIT_S = BUSY_RETRY            # a decryption waits this long for its turn and a slot, then 503 busy
+MAX_LOGINS = 4096                      # logins a limiter remembers
+BODY_GRACE_S = 30                      # an upload body must arrive within BODY_GRACE_S + its length / BODY_MIN_RATE s
+BODY_MIN_RATE = 64 * 1024              # (bytes per second: 32 MiB in 542 s), else 408 and the slot is free (F5)
+VIEWS = 300                            # requests other than POST /up per login in VIEW_WINDOW seconds (F2)
+VIEW_WINDOW = 60
+RENDER_SLOTS = 2                       # Markdown renders at once: a hostile 1 MiB document renders for seconds (F2)
+RENDER_WAIT_S = 1.0                    # a view waits this long for a render slot, then 503 busy
+RENDER_CACHE_BYTES = 8 * 1024 * 1024   # rendered Markdown kept in memory by the document's sha256, least recent out
+RENDER_CACHE_ENTRY = 2 * 1024 * 1024   # a larger render is not kept
+DENIED_REPEAT_S = 60                   # one docs.log line per refused source and word in this many seconds (F4)
+MAX_DENIED_SOURCES = 1024              # sources the refusal coalescing remembers
+MAX_DENIED_LOGIN = 64                  # characters of an unauthenticated login a `denied` line keeps
+CHUNK = 64 * 1024
+PAGE_POLICY = ("default-src 'none'; style-src 'self' 'unsafe-inline'; script-src 'self'; img-src 'self' data:; "
+               "connect-src 'self'; form-action 'self'; base-uri 'none'")      # connect-src: upload.js's POST /up
+ARTIFACT_POLICY = 'sandbox allow-scripts'
+DATA_POLICY = "default-src 'none'; sandbox"
+SHA_HEADER = 'X-Lanes-Sha256'
+ARTIFACT_TYPES = {'html': 'text/html; charset=utf-8', 'svg': 'image/svg+xml'}
+STATIC = {'docs.css': 'text/css; charset=utf-8', 'docs.js': 'text/javascript; charset=utf-8',
+          'upload.css': 'text/css; charset=utf-8', 'upload.js': 'text/javascript; charset=utf-8'}
+FETCH_SITES = ('same-origin', 'none')  # Sec-Fetch-Site values the gate serves (every route, F2) …
+NAVIGATION_METHODS = ('GET', 'HEAD')    # … and a top-level navigation by these methods, from any site
+_DECRYPTS = threading.BoundedSemaphore(1)   # encrypted documents decrypted at once (each held in memory)
+_ID = r'([a-z0-9]{10,20})'             # docs_store.ID_RE; check_id runs again before any path is formed
+ROUTES = (('index', re.compile(r'/', re.ASCII)),
+          ('view', re.compile(rf'/d/{_ID}', re.ASCII)),
+          ('raw', re.compile(rf'/d/{_ID}/raw', re.ASCII)),
+          ('artifact', re.compile(rf'/d/{_ID}/artifact', re.ASCII)),
+          ('receipt', re.compile(rf'/receipt/{_ID}\.json', re.ASCII)),
+          ('up', re.compile(r'/up', re.ASCII)),
+          ('static', re.compile(r'/(docs\.css|docs\.js|upload\.css|upload\.js)', re.ASCII)))
+METHODS = {'up': ('POST',)}            # every other route: GET
+_MIME = re.compile(r'[a-z0-9][a-z0-9.+-]{0,63}/[a-z0-9][a-z0-9.+-]{0,63}', re.ASCII)
+_FILENAME_UNSAFE = re.compile(r'[^A-Za-z0-9._-]')
+_BOUNDARY = re.compile(r"[0-9A-Za-z'()+_,./:=? -]{0,69}[0-9A-Za-z'()+_,./:=?-]", re.ASCII)   # RFC 2046 bchars
+_CTE_OK = ('7bit', '8bit', 'binary')
+_CONTROL = re.compile(r'[\x00-\x1f\x7f]')
+
+SENTENCES = {
+    'not-through-serve': 'This page answers only requests that come through Tailscale Serve, at the server\'s '
+                         'tailnet HTTPS address.',
+    'no-identity': 'No tailnet identity reached this page: open it from a device signed in to the tailnet as yourself '
+                   '(a tagged device has no login).',
+    'invalid-login': 'The tailnet login this request carries is not one Lanes accepts.',
+    'not-pinned': 'The docs service is off until the operator has run the Serve header check and pinned it '
+                  '(`lanes enrol mode request` on the server).',
+    'not-a-member': 'Your tailnet login owns no member record on this server.',
+    'domain-not-allowed': 'Your tailnet login is not in a domain this server accepts.',
+    'not-found': 'No such document here, or it is not one you can open.',
+    'method-not-allowed': 'That method is not used here.',
+    'cross-site': 'Refused: this request came from another site and was not a link you followed (Sec-Fetch-Site), '
+                  'or your browser does not say where it came from. Open the Docs page from the shell or the sidebar '
+                  'link, or type its address.',
+    'rate-limited': 'Too many requests in a short time; try again in a few minutes.',
+    'busy': 'The docs service is busy; try again in a moment.',
+    'request-timeout': 'The upload arrived too slowly and was stopped; nothing was stored. Try again.',
+    'unsupported-media-type': 'An upload is a multipart/form-data form.',
+    'length-required': 'An upload needs a Content-Length.',
+    'too-large': 'The upload is larger than 32 MiB.',
+    'bad-request': 'That upload form could not be read.',
+    'no-file': 'The form carried no file.',
+    'no-lane': 'Choose the lane the file is for.',
+    'unknown-lane': 'That lane is not one of this server\'s lanes.',
+    'unknown-workspace': 'That workspace is not one your member record lists.',
+    'registry-unavailable': 'The server has no lane registry yet (`lanes sync`).',
+    'uploads-unavailable': 'The workspace\'s uploads/ folder cannot be written now (its container is not running, or '
+                           'the folder is reached through a link); nothing was stored.',
+    'encrypt-failed': 'The docs store encrypts at rest and age failed; the journal says why. Nothing was stored.',
+    'encrypted': 'This document is encrypted at rest and the docs service holds no key to open it: fetch the copy in '
+                 'the workspace\'s uploads/ folder (or the lane\'s own file) instead.',
+    'server-error': 'Something went wrong on the server; the journal says what.',
+}
+
+
+# ------------------------------------------------------------------------------------------------------- basics
+
+def version():
+    return E.version()
+
+
+def web_dir():
+    """lanes/web of the tree this process runs (L.REPO: the unit names the `current` link, so the installed release),
+    where docs.css and docs.js live (W6)."""
+    return L.REPO / 'web'
+
+
+def esc(value):
+    return html.escape('' if value is None else str(value), quote=True)
+
+
+def human_bytes(size):
+    if size < 1024:
+        return f'{size} B'
+    if size < 1024 * 1024:
+        return f'{size / 1024:.1f} KiB'
+    return f'{size / (1024 * 1024):.1f} MiB'
+
+
+def wants_html(headers):
+    return 'text/html' in (headers.get('Accept') or '').lower()
+
+
+def download_name(name):
+    """The filename a Content-Disposition carries: docs_store names are already [A-Za-z0-9._-]; anything else is `_`."""
+    cleaned = _FILENAME_UNSAFE.sub('_', name or '')[:D.MAX_NAME + D.NAME_SLACK]
+    return cleaned or 'file'
+
+
+def content_type_of(meta):
+    mime = meta.get('mime')
+    return mime if isinstance(mime, str) and _MIME.fullmatch(mime) else 'application/octet-stream'
+
+
+# ------------------------------------------------------------------------------------------------------- people
+
+def served_workspaces(reg):
+    """The workspace ids the registry `reg` serves -> a set (empty without a registry)."""
+    return {workspace['id'] for workspace in (reg or {}).get('workspaces') or []
+            if isinstance(workspace, dict) and isinstance(workspace.get('id'), str)}
+
+
+def _listed(member):
+    return {ws for ws in member.get('workspaces') or () if isinstance(ws, str)}
+
+
+def member_workspaces(login, reg=None):
+    """The workspaces the member records `login` owns grant it (owner login compared casefolded) -> a set: each
+    record's `workspaces`, and every workspace the host serves (served_workspaces of `reg`, else registry.json) for a
+    record that lists none — empty or absent (DEF-1852; the module docstring has the rule). The records
+    keys.load_members accepts, as enrold.member_logins reads them."""
+    members, _problems = K.load_members()
+    folded = login.casefold()
+    found, every = set(), False
+    for member in members:
+        owner = member.get('owner')
+        if isinstance(owner, dict) and owner.get('login', '').casefold() == folded:
+            listed = _listed(member)
+            found |= listed
+            every = every or not listed
+    if every:
+        found |= served_workspaces(registry() if reg is None else reg)
+    return found
+
+
+def member_grants(reg):
+    """{login casefolded: (the login as its member record spells it, the workspaces its records grant)} for every
+    member at once (member_workspaces' rule, `reg` the registry): the pick-up's view of who may receive a document."""
+    members, _problems = K.load_members()
+    served = served_workspaces(reg)
+    out = {}
+    for member in members:
+        owner = member.get('owner')
+        login = owner.get('login') if isinstance(owner, dict) else None
+        if not isinstance(login, str):
+            continue
+        spelling, granted = out.get(login.casefold(), (login, set()))
+        out[login.casefold()] = (spelling, granted | (_listed(member) or served))
+    return out
+
+
+def in_own_store(meta, login):
+    """Whether the document `meta` describes sits in `login`'s own store: docs/<stem(login)>/<ws>/<lane>/<id> is a
+    real directory (never through a link)."""
+    try:
+        stem = D.login_stem(login)
+    except L.LanesError:
+        return False
+    try:
+        info = os.lstat(D.root() / stem / meta['ws'] / meta['lane'] / meta['id'])
+    except (OSError, KeyError, TypeError):
+        return False
+    return stat.S_ISDIR(info.st_mode)
+
+
+def visible(meta, owner, login, workspaces):
+    """docsd's visibility rule (see the module docstring): the caller's own store; else `for` names the caller; else
+    (`for` empty) a member record of the caller lists the document's workspace."""
+    if owner:
+        return True
+    fors = meta.get('for') or []
+    if fors:
+        folded = login.casefold()
+        return any(isinstance(entry, str) and entry.casefold() == folded for entry in fors)
+    return meta.get('ws') in workspaces
+
+
+def visible_docs(login, workspaces):
+    """The metas `login` may see, newest first."""
+    return [meta for meta in D.list_for(login) if visible(meta, in_own_store(meta, login), login, workspaces)]
+
+
+def find_doc(doc_id, login, workspaces):
+    """(meta, (stem, ws, lane, id, name)) of a document the caller may see, else None."""
+    D.check_id(doc_id)
+    found = D.load(doc_id, login)
+    if found is None:
+        return None
+    meta, path = found
+    parts = path.relative_to(D.root()).parts
+    if len(parts) != 5:
+        return None
+    try:
+        owner = parts[0] == D.login_stem(login)
+    except L.LanesError:
+        owner = False
+    return (meta, parts) if visible(meta, owner, login, workspaces) else None
+
+
+def open_doc(meta, parts):
+    """A read-only fd of the document file: every directory component a real directory, the file never a link, never a
+    FIFO, a regular file of the recorded size. Raises OSError otherwise. The caller closes it."""
+    directory = L.open_real_dir(D.root(), parts[:4])
+    try:
+        fd = os.open(parts[4], os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK | getattr(os, 'O_CLOEXEC', 0),
+                     dir_fd=directory)
+    finally:
+        os.close(directory)
+    try:
+        info = os.fstat(fd)
+        if not stat.S_ISREG(info.st_mode) or info.st_size != D.stored_file(meta)[1]:
+            raise OSError('not the recorded document')
+    except BaseException:
+        os.close(fd)
+        raise
+    return fd
+
+
+def read_receipt(parts):
+    """receipt.json's bytes beside the document, or None (absent, a link, not a regular file, too large)."""
+    try:
+        directory = L.open_real_dir(D.root(), parts[:4])
+    except (OSError, L.LanesError):
+        return None
+    try:
+        return L.read_regular_at(directory, D.RECEIPT, D.MAX_META)
+    finally:
+        os.close(directory)
+
+
+def read_all(fd, limit):
+    chunks, size = [], 0
+    while size <= limit:
+        chunk = os.read(fd, min(CHUNK, limit + 1 - size))
+        if not chunk:
+            break
+        chunks.append(chunk)
+        size += len(chunk)
+    return b''.join(chunks)
+
+
+def registry():
+    """registry.json, or None when there is none to read."""
+    try:
+        return L.load_registry()
+    except (L.LanesError, OSError, ValueError):
+        return None
+
+
+def upload_targets(workspaces, reg):
+    """[(ws id, ws title, [(lane id, lane name)])] — the registry's lanes of the caller's workspaces, catalog order."""
+    targets = []
+    for workspace in (reg or {}).get('workspaces') or []:
+        if not isinstance(workspace, dict) or workspace.get('id') not in workspaces:
+            continue
+        lanes = [(lane['id'], lane.get('name') or lane['id']) for lane in workspace.get('lanes') or []
+                 if isinstance(lane, dict) and isinstance(lane.get('id'), str)]
+        if lanes:
+            targets.append((workspace['id'], workspace.get('title') or workspace['id'], lanes))
+    return targets
+
+
+def index_filter(query, workspaces, docs, targets):
+    """(ws, lane) a `GET /?ws=…&lane=…` query names (None for one left out). Known to the caller: a workspace its member
+    records list or a visible document is in; a lane of the registry in such a workspace (`targets`) or one a visible
+    document is in — and of the named workspace when both are given. Raises _Reply(404) for anything else (unknown,
+    repeated, empty, or more fields than a filter has); other keys are ignored."""
+    try:
+        params = urllib.parse.parse_qs(query or '', keep_blank_values=True, max_num_fields=8)
+    except ValueError:
+        raise _Reply(404, 'not-found') from None
+    picked = {}
+    for key in ('ws', 'lane'):
+        values = params.get(key)
+        if values is None:
+            picked[key] = None
+        elif len(values) != 1 or not values[0]:
+            raise _Reply(404, 'not-found')
+        else:
+            picked[key] = values[0]
+    known = {ws: set() for ws in workspaces}
+    for ws, _title, lanes in targets:
+        known.setdefault(ws, set()).update(lane for lane, _name in lanes)
+    for meta in docs:
+        known.setdefault(meta['ws'], set()).add(meta['lane'])
+    ws, lane = picked['ws'], picked['lane']
+    if ws is not None and ws not in known:
+        raise _Reply(404, 'not-found')
+    if lane is not None and lane not in (known[ws] if ws is not None else set().union(*known.values())):
+        raise _Reply(404, 'not-found')
+    return ws, lane
+
+
+# ---------------------------------------------------------------------------------------------------- the form
+
+class FormError(Exception):
+    def __init__(self, error):
+        super().__init__(error)
+        self.error = error
+
+
+def form_boundary(content_type):
+    """The boundary of a `multipart/form-data` Content-Type (read with email.message), or None."""
+    if not content_type or len(content_type) > MAX_CONTENT_TYPE or _CONTROL.search(content_type):
+        return None
+    message = email.message.Message()
+    message['Content-Type'] = content_type
+    if message.get_content_type() != 'multipart/form-data':
+        return None
+    boundary = message.get_param('boundary')
+    if not isinstance(boundary, str) or not _BOUNDARY.fullmatch(boundary):
+        return None
+    return boundary
+
+
+def parse_form(body, boundary):
+    """A multipart/form-data body -> (fields {name: str}, files [(filename, start, end)]) with the files as offsets into
+    `body` (no copy). The delimiters are found by a linear bytes scan (RFC 2046: CRLF "--" boundary, the last one
+    followed by "--"); each part's header block is read by email.parser (Content-Disposition form-data, its name and
+    filename — filename* included — and a Content-Transfer-Encoding of 7bit/8bit/binary or none). Parsing the whole
+    body with email.parser instead held about 13 times a 32 MiB body in memory (measured, see RUNBOOK). A part with an
+    empty filename and no bytes (a file input left empty) is skipped. Raises FormError('bad-request')."""
+    delimiter = b'--' + boundary.encode('ascii')
+    if body.startswith(delimiter):
+        at = len(delimiter)
+    else:                                                    # a preamble is allowed; browsers send none
+        found = body.find(b'\r\n' + delimiter)
+        if found < 0:
+            raise FormError('bad-request')
+        at = found + 2 + len(delimiter)
+    fields, files, parts = {}, [], 0
+    parser = email.parser.BytesHeaderParser(policy=email.policy.HTTP)
+    while True:
+        if body[at:at + 2] == b'--':                         # the close delimiter: the epilogue is ignored
+            return fields, files
+        line_end = body.find(b'\r\n', at)
+        if line_end < 0 or body[at:line_end].strip(b' \t'):  # transport padding only, then CRLF
+            raise FormError('bad-request')
+        start = line_end + 2
+        end = body.find(b'\r\n' + delimiter, start)
+        if end < 0:
+            raise FormError('bad-request')
+        parts += 1
+        if parts > MAX_PARTS:
+            raise FormError('bad-request')
+        if body[start:start + 2] == b'\r\n':
+            header, content = b'', start + 2
+        else:
+            header_end = body.find(b'\r\n\r\n', start, end)
+            if header_end < 0 or header_end - start > MAX_PART_HEADER:
+                raise FormError('bad-request')
+            header, content = body[start:header_end + 2], header_end + 4
+        part = parser.parsebytes(header)
+        if part.get_content_disposition() != 'form-data':
+            raise FormError('bad-request')
+        name = part.get_param('name', header='content-disposition')
+        encoding = (part.get('Content-Transfer-Encoding') or '7bit').strip().lower()
+        if not isinstance(name, str) or encoding not in _CTE_OK:
+            raise FormError('bad-request')
+        filename = part.get_filename()
+        if filename is not None or part.get_param('filename', header='content-disposition') is not None:
+            if filename or end > content:
+                files.append((filename or '', content, end))
+        else:
+            if name in fields or end - content > MAX_FIELD:
+                raise FormError('bad-request')
+            try:
+                fields[name] = body[content:end].decode('utf-8')
+            except UnicodeDecodeError:
+                raise FormError('bad-request') from None
+        at = end + 2 + len(delimiter)
+
+
+class _Slice:
+    """A reader over body[start:end] (docs_store.intake reads it in chunks; nothing is copied whole)."""
+
+    def __init__(self, data, start, end):
+        self._view, self._at = memoryview(data)[start:end], 0
+
+    def read(self, size=-1):
+        if size is None or size < 0:
+            size = len(self._view) - self._at
+        chunk = self._view[self._at:self._at + size]
+        self._at += len(chunk)
+        return bytes(chunk)
+
+
+def upload_target(fields, workspaces, reg):
+    """(ws, lane) for a form's `lane` (and optional `ws`), validated against the registry and the caller's workspaces.
+    Raises FormError: no-lane, unknown-lane, unknown-workspace, registry-unavailable."""
+    lane = fields.get('lane')
+    if not lane:
+        raise FormError('no-lane')
+    try:
+        users.check_lane(lane)
+    except L.LanesError:
+        raise FormError('unknown-lane') from None
+    if reg is None:
+        raise FormError('registry-unavailable')
+    home = next((workspace.get('id') for workspace in reg.get('workspaces') or [] if isinstance(workspace, dict)
+                 for entry in workspace.get('lanes') or [] if isinstance(entry, dict) and entry.get('id') == lane),
+                None)
+    if home is None:
+        raise FormError('unknown-lane')
+    named = fields.get('ws')
+    if (named is not None and named != home) or home not in workspaces:
+        raise FormError('unknown-workspace')
+    return home, lane
+
+
+# ------------------------------------------------------------------------------------------------------- pages
+
+def page(title, content, up='', assets=()):
+    """The page shell. `up` is the relative way back to the docs root ('' at /, '../' at /d/<id>): every reference is
+    relative, because Caddy serves this under /lanes-docs/ and strips the prefix. `assets` names extra stylesheet +
+    script pairs of web/ (the index's drop area: 'upload')."""
+    home = up or './'
+    extra = ''.join(f'<link rel="stylesheet" href="{up}{name}.css"><script src="{up}{name}.js" defer></script>'
+                    for name in assets)
+    return ('<!doctype html><html lang="en"><head><meta charset="utf-8">'
+            '<meta name="viewport" content="width=device-width, initial-scale=1">'
+            '<meta name="referrer" content="no-referrer">'
+            f'<title>{esc(title)}</title>'
+            f'<link rel="stylesheet" href="{up}docs.css">'
+            f'<script src="{up}docs.js" defer></script>{extra}</head>'
+            f'<body class="lanes-docs"><header class="docs-top"><a class="docs-home" href="{home}">Docs</a></header>'
+            f'<main>{content}</main></body></html>').encode('utf-8')
+
+
+def message_page(status, word):
+    sentence = SENTENCES.get(word, word)
+    return page('Docs', f'<h1>Docs</h1><p class="docs-note" data-error="{esc(word)}">{esc(sentence)}</p>'
+                        f'<p class="docs-muted">{status} {esc(word)}</p>')
+
+
+def _doc_row(meta):
+    label = meta.get('title') or meta['name']
+    return (f'<li class="docs-doc" data-kind="{esc(meta["kind"])}"><a href="d/{esc(meta["id"])}">{esc(label)}</a> '
+            f'<span class="docs-meta">{esc(meta["kind"])} · {esc(human_bytes(meta["bytes"]))} · '
+            f'<time>{esc(meta["at"])}</time></span></li>')
+
+
+def index_page(login, docs, reg, targets, ws=None, lane=None):
+    """The index: `docs` (visible, newest first) narrowed to the filter `ws`/`lane` (index_filter checked them)."""
+    names = {}
+    titles = {}
+    for workspace in (reg or {}).get('workspaces') or []:
+        if isinstance(workspace, dict) and isinstance(workspace.get('id'), str):
+            titles[workspace['id']] = workspace.get('title') or workspace['id']
+            for entry in workspace.get('lanes') or []:
+                if isinstance(entry, dict) and isinstance(entry.get('id'), str):
+                    names[entry['id']] = entry.get('name') or entry['id']
+    docs = [meta for meta in docs if (ws is None or meta['ws'] == ws) and (lane is None or meta['lane'] == lane)]
+    grouped = {}
+    for meta in docs:                                    # newest first, so groups come newest first too
+        grouped.setdefault(meta['ws'], {}).setdefault(meta['lane'], []).append(meta)
+    parts = [f'<h1>Docs</h1><p class="docs-who">Signed in as {esc(login)} · {len(docs)} '
+             f'document{"" if len(docs) == 1 else "s"}</p>']
+    if ws is not None or lane is not None:
+        shown = ' › '.join(esc(label) for label in (titles.get(ws, ws) if ws else None,
+                                                     names.get(lane, lane) if lane else None) if label)
+        parts.append(f'<p class="docs-filter">Showing {shown} · <a href="./">All docs</a></p>')
+    if targets:
+        options = ''.join(f'<optgroup label="{esc(title)}">' + ''.join(
+            f'<option value="{esc(lane_id)}"{" selected" if lane_id == lane else ""}>{esc(name)}</option>'
+            for lane_id, name in lanes) + '</optgroup>' for _ws, title, lanes in targets)
+        # The drop area (W5): a plain form that works without a script — the label wraps a multi-file input, so a tap
+        # opens the picker and a drop onto the input takes the files —, and better with upload.js (drag and drop
+        # onto the whole area, a size check, progress, one receipt per file in .docs-sent).
+        parts.append(f'<form class="docs-upload" method="post" action="up" enctype="multipart/form-data" '
+                     f'data-max="{MAX_BODY}">'
+                     f'<label>Lane <select name="lane" required>{options}</select></label>'
+                     '<label class="docs-drop">Drop files here, or tap to choose'
+                     '<input type="file" name="file" multiple required></label>'
+                     '<button type="submit">Upload</button>'
+                     f'<p class="docs-muted">Up to {human_bytes(MAX_BODY)} at once. Each file lands in the '
+                     'workspace\'s uploads/ folder, for the lane\'s agent, with a sha256 receipt here.</p>'
+                     '<ol class="docs-sent" aria-live="polite"></ol></form>')
+    else:
+        parts.append('<p class="docs-note">Uploads go to a lane of a workspace your member record lists, and yours '
+                     'lists none here.</p>')
+    if not docs:
+        parts.append('<p class="docs-empty">No documents yet. An agent publishes one from a lane; an upload lands '
+                     'here with its receipt.</p>')
+    for ws_id, lanes in grouped.items():
+        total = sum(len(metas) for metas in lanes.values())
+        parts.append(f'<section class="docs-ws" data-ws="{esc(ws_id)}"><h2>{esc(titles.get(ws_id, ws_id))} '
+                     f'<span class="docs-count">{total}</span></h2>')
+        for lane_id, metas in lanes.items():
+            parts.append(f'<h3 data-lane="{esc(lane_id)}">{esc(names.get(lane_id, lane_id))} '
+                         f'<span class="docs-count">{len(metas)}</span></h3><ul class="docs-list">'
+                         + ''.join(_doc_row(meta) for meta in metas) + '</ul>')
+        parts.append('</section>')
+    return page('Docs', ''.join(parts), assets=('upload',) if targets else ())
+
+
+def _facts(meta):
+    rows = (('kind', meta['kind']), ('name', meta['name']), ('size', human_bytes(meta['bytes'])),
+            ('workspace', meta['ws']), ('lane', meta['lane']), ('at', meta['at']), ('by', meta.get('by') or '-'),
+            ('source', meta['source']), ('sha256', meta['sha256']))
+    return '<dl class="docs-facts">' + ''.join(f'<dt>{esc(key)}</dt><dd>{esc(value)}</dd>' for key, value in rows) \
+        + '</dl>'
+
+
+def view_page(meta, body=None, locked=False):
+    """A document's page. `locked`: an encrypted document this service cannot open (no identity): its facts only."""
+    doc_id = esc(meta['id'])
+    title = meta.get('title') or meta['name']
+    links = (f'<p class="docs-links"><a href="{doc_id}/raw" download>Download</a> · '
+             f'<a href="../receipt/{doc_id}.json">Receipt</a></p>')
+    if locked:
+        content = f'<p class="docs-note" data-error="encrypted">{esc(SENTENCES["encrypted"])}</p>'
+    elif meta['kind'] == 'md':
+        if body is None:
+            content = (f'<p class="docs-note">This Markdown is larger than {human_bytes(mdlite.MAX_BYTES)} and is not '
+                       'rendered here; download it.</p>')
+        else:
+            content = f'<article class="docs-md">{body}</article>'
+    elif meta['kind'] in ARTIFACT_TYPES:
+        content = (f'<p class="docs-artifact"><a href="{doc_id}/artifact" rel="noopener noreferrer">Open the '
+                   f'{esc(meta["kind"].upper())} artifact</a></p><p class="docs-muted">It opens on its own page in a '
+                   'sandbox: its scripts run, but cannot reach this site or your lanes.</p>')
+    else:
+        content = ''
+    return page(title, f'<h1>{esc(title)}</h1>{links}{content}{_facts(meta)}', up='../')
+
+
+def receipts_page(receipts, error=None):
+    rows = ''.join(f'<li><a href="d/{esc(r["id"])}">{esc(r["name"])}</a> <span class="docs-meta">'
+                   f'{esc(human_bytes(r["bytes"]))} · sha256 <code>{esc(r["sha256"])}</code> · in the lane as '
+                   f'<code>{esc(r["landed"])}</code></span></li>' for r in receipts)
+    note = f'<p class="docs-note" data-error="{esc(error)}">{esc(SENTENCES.get(error, error))}</p>' if error else ''
+    return page('Uploaded', f'<h1>Uploaded</h1>{note}<ul class="docs-receipts">{rows}</ul>'
+                            '<p><a href="./">Back to the docs</a></p>')
+
+
+# ----------------------------------------------------------------------------------------------------- service
+
+def fetch_site_ok(headers, method):
+    """The gate's `cross-site` rule (the module docstring): `Sec-Fetch-Site` same-origin or none, or a GET/HEAD
+    top-level navigation (`Sec-Fetch-Mode: navigate`, `Sec-Fetch-Dest: document`) from any site. A POST — an upload —
+    is never a navigation here."""
+    if headers.get('Sec-Fetch-Site') in FETCH_SITES:
+        return True
+    return (method in NAVIGATION_METHODS and headers.get('Sec-Fetch-Mode') == 'navigate'
+            and headers.get('Sec-Fetch-Dest') == 'document')
+
+
+class RenderCache:
+    """Rendered Markdown by the document's sha256 (the same bytes render the same, mdlite is deterministic), least
+    recently used out first: at most RENDER_CACHE_BYTES in all, nothing larger than RENDER_CACHE_ENTRY kept. A value
+    of None is a document too large to render once its bytes are decoded."""
+
+    def __init__(self):
+        self._lock = threading.Lock()
+        self._entries = collections.OrderedDict()
+        self.size = 0
+
+    def get(self, key):
+        """(True, the render) when `key` is kept (it becomes the most recent), else (False, None)."""
+        with self._lock:
+            if key not in self._entries:
+                return False, None
+            self._entries.move_to_end(key)
+            return True, self._entries[key][0]
+
+    def put(self, key, value):
+        size = sys.getsizeof(value)
+        if size > RENDER_CACHE_ENTRY:
+            return
+        with self._lock:
+            if key in self._entries:
+                return
+            self._entries[key] = (value, size)
+            self.size += size
+            while self.size > RENDER_CACHE_BYTES and self._entries:
+                _key, (_value, gone) = self._entries.popitem(last=False)
+                self.size -= gone
+
+    def __len__(self):
+        return len(self._entries)
+
+
+class Service:
+    """Process-wide state: the domain gate, the limiters, the upload/decrypt slots, the render slots and cache, and the
+    coalescing of refusals in docs.log."""
+
+    def __init__(self, domains=None, clock=time.time):
+        self.domains = tuple(domains) if domains else E.DEFAULT_DOMAINS
+        self.clock = clock
+        self._lock = threading.Lock()
+        self._uploads = {}
+        self._views = {}               # login casefolded -> [window start, requests in it]
+        self._holders = set()          # logins casefolded holding an upload slot (one each)
+        self._denied = {}              # (word, source) -> [window start, refusals folded since, last login]
+        self._swept = float('-inf')
+        self.slots = threading.BoundedSemaphore(UPLOAD_SLOTS)
+        self.renders = threading.BoundedSemaphore(RENDER_SLOTS)
+        self.rendered = RenderCache()
+        self._pin_problem = None
+
+    @classmethod
+    def from_environ(cls, environ):
+        return cls(domains=E.parse_domains(environ.get('LANES_DOCS_DOMAINS') or environ.get('LANES_ENROL_DOMAINS')))
+
+    domain_ok = E.Service.domain_ok        # enrold's rule over self.domains, the same function
+
+    def pinned(self):
+        """Whether the operator pinned request mode (enrold.read_mode): the proof the Serve header check ran."""
+        mode, problem = E.read_mode()
+        if problem and problem != self._pin_problem:
+            print(f'lanes-docsd: {problem}: every request is refused until `lanes enrol mode request` writes it again',
+                  file=sys.stderr, flush=True)
+        self._pin_problem = problem
+        return mode == 'request'
+
+    def gate(self, headers, peer, method='GET'):
+        """(caller, None) when the request may be served, else (caller, the refusal's word). See the module docstring
+        for the order."""
+        caller = E.caller_of(headers)
+        if not E.through_serve(headers.get('X-Forwarded-For'), peer):
+            return caller, 'not-through-serve'
+        if not caller.present:
+            return caller, 'no-identity'
+        if not caller.login:
+            return caller, 'invalid-login'
+        if not self.pinned():
+            return caller, 'not-pinned'
+        if caller.login.casefold() not in E.member_logins():
+            return caller, 'not-a-member'
+        if not self.domain_ok(caller.login):
+            return caller, 'domain-not-allowed'
+        if not fetch_site_ok(headers, method):
+            return caller, 'cross-site'
+        return caller, None
+
+    def attempt(self, login):
+        """0 when `login` may upload now (the attempt is counted), else the seconds to wait."""
+        now, key = self.clock(), login.casefold()
+        with self._lock:
+            recent = [at for at in self._uploads.get(key, ()) if now - at < UPLOAD_WINDOW]
+            if len(recent) >= UPLOADS:
+                self._uploads[key] = recent
+                return int(recent[0] + UPLOAD_WINDOW - now) + 1
+            self._uploads[key] = recent + [now]
+            if len(self._uploads) > MAX_LOGINS:
+                for other in list(self._uploads):
+                    kept = [at for at in self._uploads[other] if now - at < UPLOAD_WINDOW]
+                    if kept:
+                        self._uploads[other] = kept
+                    else:
+                        del self._uploads[other]
+                while len(self._uploads) > MAX_LOGINS:
+                    self._uploads.pop(min(self._uploads, key=lambda name: self._uploads[name][-1]))
+            return 0
+
+    def view(self, login):
+        """(0, False) when `login` may make another request now (it is counted: VIEWS per VIEW_WINDOW s, a fixed
+        window), else (the seconds to wait, whether this is the window's first refusal — the one docs.log line)."""
+        now, key = self.clock(), login.casefold()
+        with self._lock:
+            window = self._views.get(key)
+            if window is None or now - window[0] >= VIEW_WINDOW:
+                if window is None and len(self._views) >= MAX_LOGINS:
+                    for other in [name for name, (start, _n) in self._views.items() if now - start >= VIEW_WINDOW]:
+                        del self._views[other]
+                    while len(self._views) >= MAX_LOGINS:
+                        self._views.pop(min(self._views, key=lambda name: self._views[name][0]))
+                window = self._views[key] = [now, 0]
+            window[1] += 1
+            if window[1] <= VIEWS:
+                return 0, False
+            return int(window[0] + VIEW_WINDOW - now) + 1, window[1] == VIEWS + 1
+
+    def take_upload_slot(self, login):
+        """Whether `login` got one of the UPLOAD_SLOTS (never a second one while it holds one: F5)."""
+        key = login.casefold()
+        with self._lock:
+            if key in self._holders or not self.slots.acquire(blocking=False):
+                return False
+            self._holders.add(key)
+            return True
+
+    def give_upload_slot(self, login):
+        with self._lock:
+            self._holders.discard(login.casefold())
+            self.slots.release()
+
+    def denied(self, login, word, source):
+        """Log a gate refusal, coalesced (F4): the first of a (word, source) is a `denied` line; more within
+        DENIED_REPEAT_S are counted, and flush_denied writes one `denied-repeat` line per window with the count."""
+        now = self.clock()
+        shown = login[:MAX_DENIED_LOGIN] if login else None
+        lines = self._sweep(now)
+        with self._lock:
+            entry = self._denied.get((word, source))
+            if entry is not None:
+                entry[1] += 1
+                entry[2] = shown
+            else:
+                while len(self._denied) >= MAX_DENIED_SOURCES:      # forget the oldest; its count is said first
+                    oldest = min(self._denied, key=lambda key: self._denied[key][0])
+                    start, count, last = self._denied.pop(oldest)
+                    if count:
+                        lines.append((last, count, oldest[0]))
+                self._denied[(word, source)] = [now, 0, shown]
+                lines.append((shown, None, word))
+        for logged, count, said in lines:
+            D.audit('denied' if count is None else 'denied-repeat', logged, None, None, count, None, said, now)
+
+    def flush_denied(self, now=None):
+        """Write the `denied-repeat` lines whose window has passed (the pick-up's cycle calls this every few s)."""
+        now = self.clock() if now is None else now
+        for logged, count, said in self._sweep(now, force=True):
+            D.audit('denied-repeat', logged, None, None, count, None, said, now)
+
+    def _sweep(self, now, force=False):
+        """The repeat lines due at `now`, at most once a second unless `force`: a window with refusals folded into it
+        is said and restarted; one without is forgotten (the next refusal is a `denied` line again)."""
+        lines = []
+        with self._lock:
+            if not force and now - self._swept < 1:
+                return lines
+            self._swept = now
+            for key in list(self._denied):
+                start, count, last = self._denied[key]
+                if now - start < DENIED_REPEAT_S:
+                    continue
+                if count:
+                    lines.append((last, count, key[0]))
+                    self._denied[key] = [now, 0, last]
+                else:
+                    del self._denied[key]
+        return lines
+
+
+# -------------------------------------------------------------------------------------------------------- HTTP
+
+class _Reply(Exception):
+    def __init__(self, status, error, headers=()):
+        super().__init__(error)
+        self.status, self.error, self.headers = status, error, tuple(headers)
+
+
+def resolve(path):
+    """(route, the id or file name it names, or None) for a request path, else (None, None)."""
+    for route, pattern in ROUTES:
+        found = pattern.fullmatch(path)
+        if found:
+            return route, (found.group(1) if found.groups() else None)
+    return None, None
+
+
+class Handler(BaseHTTPRequestHandler):
+    server_version = 'lanes-docsd'
+    timeout = 30
+
+    def version_string(self):
+        return self.server_version
+
+    def log_message(self, format, *args):          # no access log: docs.log is the record, the journal the errors
+        pass
+
+    def do_GET(self):
+        self._route('GET')
+
+    def do_POST(self):
+        self._route('POST')
+
+    def do_HEAD(self):
+        self._route('HEAD')
+
+    def do_PUT(self):
+        self._route('PUT')
+
+    def do_DELETE(self):
+        self._route('DELETE')
+
+    def do_PATCH(self):
+        self._route('PATCH')
+
+    def do_OPTIONS(self):
+        self._route('OPTIONS')
+
+    # ------------------------------------------------------------------------------------------- plumbing
+
+    def _headers(self, status, content_type, length, headers, policy, cache):
+        if self.command in ('POST', 'PUT', 'PATCH') and not self._body_read:
+            self._discard()                        # an unread body would reset the client's connection (DEF-1854)
+        self.send_response(status)
+        self.send_header('Content-Type', content_type)
+        self.send_header('Content-Length', str(length))
+        self.send_header('Cache-Control', cache)
+        self.send_header('X-Content-Type-Options', 'nosniff')
+        self.send_header('X-Frame-Options', 'DENY')
+        self.send_header('Referrer-Policy', 'no-referrer')
+        self.send_header('Content-Security-Policy', policy)
+        for name, value in headers:
+            self.send_header(name, value)
+        if self._discarded:
+            self.send_header('Connection', 'close')
+        self.end_headers()
+
+    def _send(self, status, body, content_type, headers=(), policy=DATA_POLICY, cache='no-store'):
+        self._headers(status, content_type, len(body), headers, policy, cache)
+        if self.command != 'HEAD':
+            self.wfile.write(body)
+        self._linger()
+
+    def _send_fd(self, fd, size, content_type, headers=(), policy=DATA_POLICY):
+        self._headers(200, content_type, size, headers, policy, 'no-store')
+        left = size
+        while left > 0:
+            chunk = os.read(fd, min(CHUNK, left))
+            if not chunk:
+                break                              # shrank under us: the connection closes short, never padded
+            self.wfile.write(chunk)
+            left -= len(chunk)
+        if left:
+            self.close_connection = True
+
+    def _page(self, status, body, headers=()):
+        self._send(status, body, 'text/html; charset=utf-8', headers, PAGE_POLICY)
+
+    def _json(self, status, payload, headers=()):
+        self._send(status, json.dumps(payload).encode('utf-8'), 'application/json; charset=utf-8', headers)
+
+    def _error(self, status, word, headers=()):
+        if wants_html(self.headers):
+            return self._page(status, message_page(status, word), headers)
+        return self._json(status, {'error': word}, headers)
+
+    def _discard(self):
+        """Read an unread request body away BEFORE a refusal is sent (DEF-1854): up to its Content-Length, at most
+        DRAIN_LIMIT bytes. A client sends its whole body before it reads an answer; one answered and closed while it
+        is still sending sees a reset or a broken pipe, never the refusal (W3 MEASURED that on the third of three
+        concurrent 32 MiB uploads, when only 1 MiB was read away). What is left past DRAIN_LIMIT — or a chunked body,
+        which is never read — is _linger's. The connection closes after the answer (`Connection: close`)."""
+        self._body_read = self._discarded = True
+        self.close_connection = True
+        if self.headers.get('Transfer-Encoding') is not None:
+            self._unread = DRAIN_LIMIT
+            return
+        try:
+            declared = max(int(self.headers.get('Content-Length') or 0), 0)
+        except ValueError:
+            declared = 0
+        drained, target = 0, min(declared, DRAIN_LIMIT)
+        try:
+            while drained < target:
+                chunk = self.rfile.read(min(target - drained, CHUNK))
+                if not chunk:                      # the client stopped sending: nothing more will come
+                    self._unread = 0
+                    return
+                drained += len(chunk)
+        except OSError:
+            pass                                   # a read timed out: what is left is _linger's
+        self._unread = declared - drained
+
+    def _linger(self):
+        """After a refusal's answer, when the body is still arriving (past DRAIN_LIMIT, chunked, or a read timed out):
+        shut the write side — the client's next read sees the whole answer and then its end — and read the rest away
+        for at most LINGER_S seconds and DRAIN_LIMIT bytes before the socket closes, so the close does not reset the
+        connection under an answer the client has not read yet (DEF-1854)."""
+        if not self._unread:
+            return
+        self._unread = 0
+        try:
+            self.wfile.flush()
+            self.connection.shutdown(socket.SHUT_WR)
+            deadline, left = time.monotonic() + LINGER_S, DRAIN_LIMIT
+            while left > 0:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    break
+                self.connection.settimeout(remaining)
+                chunk = self.connection.recv(min(CHUNK, left))
+                if not chunk:
+                    break
+                left -= len(chunk)
+        except OSError:
+            pass
+
+    def _body(self):
+        if self.headers.get('Transfer-Encoding') is not None:
+            self._discard()                        # chunked bodies are not read: answer, then _linger
+            raise _Reply(411, 'length-required')
+        length = self.headers.get('Content-Length')
+        if length is None:
+            raise _Reply(411, 'length-required')
+        try:
+            size = int(length)
+        except ValueError:
+            size = -1
+        if size < 0:
+            self._discard()
+            raise _Reply(400, 'bad-request')
+        if size > MAX_BODY:
+            self._discard()
+            raise _Reply(413, 'too-large')
+        # The whole body has a deadline, not just each read (F5): a sender that trickles a byte every few seconds held
+        # an upload slot for as long as it liked. Read into one buffer of the declared size (no second copy).
+        data, got = bytearray(size), 0
+        view = memoryview(data)
+        deadline = time.monotonic() + BODY_GRACE_S + size / BODY_MIN_RATE
+        try:
+            while got < size:
+                left = deadline - time.monotonic()
+                if left <= 0:
+                    raise TimeoutError('the body did not arrive in time')
+                self.connection.settimeout(min(left, self.timeout))
+                read = self.rfile.readinto1(view[got:got + CHUNK])
+                if not read:
+                    break
+                got += read
+        except TimeoutError:
+            self._body_read = self._discarded = True   # the rest is not waited for: answer and close
+            self._unread = 0
+            self.close_connection = True
+            raise _Reply(408, 'request-timeout') from None
+        except OSError:
+            self._body_read = self._discarded = True   # the client went away
+            self._unread = 0
+            self.close_connection = True
+            raise _Reply(400, 'bad-request') from None
+        finally:
+            try:
+                self.connection.settimeout(self.timeout)
+            except OSError:
+                pass
+        self._body_read = True
+        if got != size:
+            self.close_connection = True
+            raise _Reply(400, 'bad-request')
+        return data
+
+    # --------------------------------------------------------------------------------------------- routes
+
+    def _route(self, method):
+        self._body_read = self._discarded = False
+        self._unread = 0
+        service = self.server.service
+        try:
+            caller, refusal = service.gate(self.headers, self.client_address[0], method)
+            if refusal:
+                service.denied(caller.login, refusal,
+                               E.source_key(self.headers.get('X-Forwarded-For'), self.client_address[0]))
+                return self._error(403, refusal)
+            route, name = resolve(urllib.parse.urlsplit(self.path).path)
+            if route != 'up':                      # every request but an upload counts against the login (F2)
+                wait, first = service.view(caller.login)
+                if wait:
+                    if first:                      # one line per login per window: `view … rate-limited`
+                        D.audit('view', caller.login, None, None, None, None, 'rate-limited')
+                    raise _Reply(429, 'rate-limited', (('Retry-After', str(wait)),))
+            if route is None:
+                return self._error(404, 'not-found')
+            allowed = METHODS.get(route, ('GET',))
+            if method not in allowed:
+                return self._error(405, 'method-not-allowed', (('Allow', ', '.join(allowed)),))
+            if route == 'static':
+                return self._static(name)
+            if route == 'up':
+                return self._upload(service, caller)
+            workspaces = member_workspaces(caller.login)
+            if route == 'index':
+                reg = registry()
+                docs, targets = visible_docs(caller.login, workspaces), upload_targets(workspaces, reg)
+                ws, lane = index_filter(urllib.parse.urlsplit(self.path).query, workspaces, docs, targets)
+                return self._page(200, index_page(caller.login, docs, reg, targets, ws, lane))
+            return self._document(route, name, caller.login, workspaces)
+        except _Reply as reply:
+            try:
+                return self._error(reply.status, reply.error, reply.headers)
+            except OSError:                        # the client went away before its answer (a stalled upload's)
+                self.close_connection = True
+        except Exception:                          # noqa: BLE001 — one request's bug never stops the service
+            traceback.print_exc(file=sys.stderr)
+            try:
+                self._error(500, 'server-error')
+            except OSError:
+                pass
+
+    def _static(self, name):
+        try:
+            directory = L.open_real_dir(web_dir(), ())
+        except OSError:
+            return self._error(404, 'not-found')
+        try:
+            data = L.read_regular_at(directory, name, MAX_STATIC)
+        finally:
+            os.close(directory)
+        if data is None:
+            return self._error(404, 'not-found')
+        return self._send(200, data, STATIC[name], cache='no-cache')
+
+    def _document(self, route, doc_id, login, workspaces):
+        try:
+            found = find_doc(doc_id, login, workspaces)
+        except D.DocsError:
+            found = None
+        if found is None or (route == 'artifact' and found[0]['kind'] not in ARTIFACT_TYPES):
+            D.audit(route, login, doc_id, found[0]['lane'] if found else None, None, None, 'not-found')
+            return self._error(404, 'not-found')
+        meta, parts = found
+        if route == 'receipt':
+            data = read_receipt(parts)
+            if data is None:
+                D.audit(route, login, doc_id, meta['lane'], None, None, 'not-found')
+                return self._error(404, 'not-found')
+            D.audit(route, login, doc_id, meta['lane'], meta['bytes'], meta['sha256'], 'ok')
+            return self._send(200, data, 'application/json; charset=utf-8')
+        try:
+            fd = open_doc(meta, parts)
+        except (OSError, L.LanesError):
+            D.audit(route, login, doc_id, meta['lane'], None, None, 'not-found')
+            return self._error(404, 'not-found')
+        try:
+            if meta.get('enc'):
+                return self._encrypted(route, meta, fd, login)
+            if route == 'view':
+                body = None
+                if meta['kind'] == 'md' and meta['bytes'] <= mdlite.MAX_BYTES:
+                    body = self._rendered(route, meta, login, lambda: read_all(fd, mdlite.MAX_BYTES))
+                D.audit(route, login, doc_id, meta['lane'], meta['bytes'], meta['sha256'], 'ok')
+                return self._page(200, view_page(meta, body))
+            D.audit(route, login, doc_id, meta['lane'], meta['bytes'], meta['sha256'], 'ok')
+            if route == 'raw':
+                disposition = f'attachment; filename="{download_name(meta["name"])}"'
+                return self._send_fd(fd, meta['bytes'], content_type_of(meta),
+                                     (('Content-Disposition', disposition), (SHA_HEADER, meta['sha256'])))
+            return self._send_fd(fd, meta['bytes'], ARTIFACT_TYPES[meta['kind']], ((SHA_HEADER, meta['sha256']),),
+                                 ARTIFACT_POLICY)
+        finally:
+            os.close(fd)
+
+    def _rendered(self, route, meta, login, source):
+        """The Markdown document `meta` rendered (None: too large once decoded), from the service's cache by its sha256,
+        else rendered from source()'s bytes in one of RENDER_SLOTS (waiting at most RENDER_WAIT_S, else 503 busy) and
+        kept (F2: a hostile 1 MiB document renders for seconds, and a page could ask for it in a loop)."""
+        service = self.server.service
+        hit, body = service.rendered.get(meta['sha256'])
+        if hit:
+            return body
+        if not service.renders.acquire(timeout=RENDER_WAIT_S):
+            D.audit(route, login, meta['id'], meta['lane'], None, None, 'busy')
+            raise _Reply(503, 'busy', (('Retry-After', str(BUSY_RETRY)),))
+        try:
+            try:                                   # invalid UTF-8 becomes U+FFFD, which can push it past the limit
+                body = mdlite.render(bytes(source()).decode('utf-8', 'replace'))
+            except mdlite.TooLarge:
+                body = None
+        finally:
+            service.renders.release()
+        service.rendered.put(meta['sha256'], body)
+        return body
+
+    def _decrypted(self, route, meta, fd, identity, login):
+        """The plaintext of an encrypted document (docs_store.decrypt, checked against the receipt), one at a time
+        (_DECRYPTS) and in one of the UPLOAD_SLOTS big buffers it shares with uploads (F8), each waited for at most
+        DECRYPT_WAIT_S, else 503 busy."""
+        service = self.server.service
+        if not _DECRYPTS.acquire(timeout=DECRYPT_WAIT_S):
+            D.audit(route, login, meta['id'], meta['lane'], None, None, 'busy')
+            raise _Reply(503, 'busy', (('Retry-After', str(BUSY_RETRY)),))
+        try:
+            if not service.slots.acquire(timeout=DECRYPT_WAIT_S):
+                D.audit(route, login, meta['id'], meta['lane'], None, None, 'busy')
+                raise _Reply(503, 'busy', (('Retry-After', str(BUSY_RETRY)),))
+            try:
+                return D.decrypt(meta, fd, identity)
+            except D.EncryptError:
+                D.audit(route, login, meta['id'], meta['lane'], None, None, 'encrypt-failed')
+                raise _Reply(500, 'server-error') from None
+            finally:
+                service.slots.release()
+        finally:
+            _DECRYPTS.release()
+
+    def _encrypted(self, route, meta, fd, login):
+        """An encrypted document (docs_store's `age` switch, meta `enc`; fd its stored `<name>.age`). With an identity
+        (LANES_DOCS_AGE_IDENTITY) and at most MAX_BODY bytes it is decrypted on the fly (_decrypted); raw and artifact
+        then answer as for a plain document, and a view renders it unless the render cache already holds it. Without
+        one, raw and artifact are 409 encrypted (the page names uploads/), and the view shows the facts only."""
+        try:
+            identity = D.age_settings()[1]
+        except D.DocsError:
+            identity = None
+        if route == 'view':
+            body = None
+            if identity and meta['kind'] == 'md' and meta['bytes'] <= mdlite.MAX_BYTES:
+                body = self._rendered(route, meta, login, lambda: self._decrypted(route, meta, fd, identity, login))
+            D.audit(route, login, meta['id'], meta['lane'], meta['bytes'], meta['sha256'], 'ok')
+            return self._page(200, view_page(meta, body, locked=not identity))
+        data = None
+        if identity and meta['bytes'] <= MAX_BODY:
+            data = self._decrypted(route, meta, fd, identity, login)
+        if data is None:
+            D.audit(route, login, meta['id'], meta['lane'], None, None, 'encrypted')
+            raise _Reply(409, 'encrypted')
+        D.audit(route, login, meta['id'], meta['lane'], meta['bytes'], meta['sha256'], 'ok')
+        if route == 'raw':
+            disposition = f'attachment; filename="{download_name(meta["name"])}"'
+            return self._send(200, data, content_type_of(meta),
+                              (('Content-Disposition', disposition), (SHA_HEADER, meta['sha256'])))
+        return self._send(200, data, ARTIFACT_TYPES[meta['kind']], ((SHA_HEADER, meta['sha256']),), ARTIFACT_POLICY)
+
+    def _upload(self, service, caller):
+        login = caller.login                       # the gate refused one from another site already (F2)
+        wait = service.attempt(login)
+        if wait:
+            D.audit('upload', login, None, None, None, None, 'rate-limited')
+            raise _Reply(429, 'rate-limited', (('Retry-After', str(wait)),))
+        if not service.take_upload_slot(login):
+            D.audit('upload', login, None, None, None, None, 'busy')
+            raise _Reply(503, 'busy', (('Retry-After', str(BUSY_RETRY)),))
+        try:
+            return self._upload_in_slot(login)
+        finally:
+            service.give_upload_slot(login)
+
+    def _upload_in_slot(self, login):
+        boundary = form_boundary(self.headers.get('Content-Type'))
+        if boundary is None:
+            D.audit('upload', login, None, None, None, None, 'unsupported-media-type')
+            raise _Reply(415, 'unsupported-media-type')
+        try:
+            data = self._body()
+        except _Reply as reply:
+            D.audit('upload', login, None, None, None, None, reply.error)
+            raise
+        fields = {}
+        reg = registry()
+        try:
+            fields, files = parse_form(data, boundary)
+            if not files:
+                raise FormError('no-file')
+            ws, lane = upload_target(fields, member_workspaces(login), reg)
+        except FormError as error:
+            lane = fields.get('lane')
+            D.audit('upload', login, None, lane if isinstance(lane, str) and L.IDENT.match(lane) else None, None, None,
+                    error.error)
+            raise _Reply(503 if error.error == 'registry-unavailable' else 400, error.error) from None
+        workspace = next(entry for entry in reg['workspaces'] if isinstance(entry, dict) and entry.get('id') == ws)
+        try:                                       # where the files land: uploads/ of the workspace (W5)
+            folder, home, parts = U.landing(reg, workspace)
+            uploads = U.open_uploads(home, parts)
+        except (L.LanesError, OSError):
+            D.audit('upload', login, None, lane, None, None, 'uploads-unavailable')
+            raise _Reply(503, 'uploads-unavailable') from None
+        receipts, failure = [], None
+        try:
+            for name, start, end in files:
+                try:
+                    meta, landed = U.receive(uploads, D.clean_name(name), _Slice(data, start, end), login=login, ws=ws,
+                                             lane=lane, source='web')
+                except U.UploadError as error:     # intake logged it; nothing of this file landed
+                    failure = {'busy': (503, 'busy'), 'encrypt-failed': (500, 'encrypt-failed')}.get(
+                        error.word, (400, 'bad-request'))
+                    break
+                except (OSError, L.LanesError):    # could not land: the store document was removed again
+                    D.audit('upload', login, None, lane, None, None, 'uploads-unavailable')
+                    failure = (503, 'uploads-unavailable')
+                    break
+                receipts.append({'id': meta['id'], 'name': meta['name'], 'sha256': meta['sha256'],
+                                 'bytes': meta['bytes'], 'url': D.URL.format(meta['id']), 'at': meta['at'],
+                                 'landed': f'{folder}/uploads/{landed}'})
+        finally:
+            os.close(uploads)
+        status, error = failure if failure else (200, None)
+        headers = (('Retry-After', str(BUSY_RETRY)),) if status == 503 else ()
+        if wants_html(self.headers):
+            return self._page(status, receipts_page(receipts, error), headers)
+        payload = {'receipts': receipts}
+        if error:
+            payload['error'] = error
+        return self._json(status, payload, headers)
+
+
+class Server(ThreadingHTTPServer):
+    daemon_threads = True
+    request_queue_size = 32
+
+    def __init__(self, address, service):
+        self.service = service
+        super().__init__(address, Handler)
+
+    def server_bind(self):                         # HTTPServer's getfqdn() lookup is not needed on loopback
+        socketserver.TCPServer.server_bind(self)
+        self.server_name, self.server_port = self.server_address[:2]
+
+
+# ------------------------------------------------------------------------------------------------ publish pick-up
+
+PICKUP_INTERVAL = 5                    # seconds between two pick-up cycles (lane_core.PUBLISH_LATENCY_S)
+PUBLISH_LIMIT = MAX_BODY               # a published file, at most: the docs limit (lane_core.PUBLISH_MAX)
+MAX_REQUEST = 16 * 1024                # one request's JSON
+MAX_PATH = 4096                        # a request's `path`
+MAX_PICKUPS = 16                       # requests taken from one container per cycle; the rest wait for the next
+MAX_RECEIPTS = 16                      # receipts kept per lane in a container, the newest
+PUBLISHES = 30                         # requests taken per container in PUBLISH_WINDOW seconds; more are refused
+PUBLISH_WINDOW = 600
+PUBLISHED_PUSH_S = 60                  # one `published` push per lane in this many seconds, at most
+PUBLISH_KINDS = ('md', 'html', 'svg', 'file')                    # lane_core.PUBLISH_KINDS: docs_store.KINDS - upload
+PUBLISH_DIR = tuple(L.CONTAINER_HOME.strip('/').split('/')) + ('.lz', 'state', 'publish')
+HOME_PARTS = tuple(L.CONTAINER_HOME.strip('/').split('/'))
+REQUEST_SUFFIX, RECEIPT_SUFFIX, CLAIM_SUFFIX = '.json', '.receipt.json', '.taking'
+MAX_ENTRIES = 4096                     # directory entries surveyed per container per cycle; more: refused (F1)
+OVER_CAP_SAY_S = 3600                  # an over-cap container is said in the journal once per this many seconds
+REFUSALS = ('unreadable-request', 'bad-version', 'bad-request', 'bad-kind', 'bad-title', 'too-large', 'unknown-lane',
+            'rate-limited', 'for-not-a-member', 'no-recipient', 'outside-home', 'not-a-file', 'sha256-mismatch',
+            'invalid', 'error')        # the words docs.log says; a receipt says receipt_reason()'s
+NOT_DELIVERED = ('for-not-a-member', 'no-recipient')            # their receipt says `not-delivered` (F6)
+_PLANTED = (errno.EISDIR, errno.ENOTEMPTY, errno.EEXIST)        # a rename onto a directory planted at its target
+_UNCLAIMED = object()                  # _take: the request could not be claimed; the next one is tried
+_SHA256 = re.compile(r'[0-9a-f]{64}', re.ASCII)
+_CHILD_DIR = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | getattr(os, 'O_CLOEXEC', 0)
+_LEAF = os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK | getattr(os, 'O_CLOEXEC', 0)
+
+
+class Refused(Exception):
+    """A publish request refused: `reason` (one of REFUSALS) goes into its receipt, with the host's sha256 and size of
+    the file when they are known."""
+
+    def __init__(self, reason, sha256=None, size=None):
+        super().__init__(reason)
+        self.reason, self.sha256, self.size = reason, sha256, size
+
+
+def container_roots():
+    """[(container, root)] for every container containers.json names (`lanes sync`, statusd: L.refresh_containers)
+    whose init pid is alive: root = /proc/<pid>/root. A pid whose root is the host's own `/` is skipped — a container
+    that went away and a host process that got its pid — so the host's home is never read as a container's. And a pid
+    whose /home/coder (opened without following a link) is not the home volume containers.json records for the
+    container (`home`, the host path docker reports; compared by st_dev and st_ino, a mount shows its source's) is
+    skipped too: another container got the pid, and its requests would be taken as this container's lanes' (F10). When
+    this account cannot see the recorded volume, or none is recorded, only the host-root check applies (DEF-1918)."""
+    info = L.read_json(L.STATE / 'containers.json', {}) or {}
+    try:
+        host = os.stat('/')
+    except OSError:
+        host = None
+    found = []
+    for name in sorted(info if isinstance(info, dict) else ()):
+        entry = info[name]
+        pid = entry.get('pid') if isinstance(entry, dict) else None
+        if not L.IDENT.match(name) or not isinstance(pid, int) or isinstance(pid, bool) or pid <= 0:
+            continue
+        root = Path(L.proc_root()) / str(pid) / 'root'
+        try:
+            seen = os.stat(root)
+        except OSError:
+            continue
+        if host is not None and (seen.st_dev, seen.st_ino) == (host.st_dev, host.st_ino):
+            continue
+        if not _home_matches(root, entry.get('home')):
+            continue
+        found.append((name, root))
+    return found
+
+
+def _home_matches(root, home):
+    """False only when both the recorded home volume `home` and the container's /home/coder can be seen and they are
+    not the same directory."""
+    if not isinstance(home, str) or not home.startswith('/'):
+        return True
+    try:
+        volume = os.stat(home)
+        fd = L.open_real_dir(root, HOME_PARTS)
+    except (OSError, L.LanesError):
+        return True
+    try:
+        mounted = os.fstat(fd)
+    except OSError:
+        return True
+    finally:
+        os.close(fd)
+    return (volume.st_dev, volume.st_ino) == (mounted.st_dev, mounted.st_ino)
+
+
+def lane_places(reg):
+    """{lane id: (workspace id, container)} of every registry lane that runs in a container."""
+    places = {}
+    for workspace in (reg or {}).get('workspaces') or []:
+        if not isinstance(workspace, dict) or not isinstance(workspace.get('id'), str):
+            continue
+        for lane in workspace.get('lanes') or []:
+            if isinstance(lane, dict) and isinstance(lane.get('id'), str) and isinstance(lane.get('container'), str):
+                places.setdefault(lane['id'], (workspace['id'], lane['container']))
+    return places
+
+
+def read_request(directory, name):
+    """The checked request in `name` of the open lane directory -> {path, kind, claimed_sha256, bytes, title, for}.
+    Raises Refused (see the module docstring, step 2)."""
+    raw = L.read_regular_at(directory, name, MAX_REQUEST)
+    try:
+        request = json.loads(raw.decode('utf-8')) if raw is not None else None
+    except ValueError:
+        request = None
+    if not isinstance(request, dict):
+        raise Refused('unreadable-request')
+    if request.get('v') != 1:
+        raise Refused('bad-version')
+    path, sha256, size = request.get('path'), request.get('claimed_sha256'), request.get('bytes')
+    title, for_login, mime = request.get('title'), request.get('for'), request.get('mime')
+    if not (isinstance(path, str) and path.startswith('/') and '\x00' not in path and len(path) <= MAX_PATH
+            and isinstance(sha256, str) and _SHA256.fullmatch(sha256)
+            and isinstance(size, int) and not isinstance(size, bool) and size >= 0
+            and all(value is None or isinstance(value, str) for value in (title, for_login, mime))):
+        raise Refused('bad-request')
+    if request.get('kind') not in PUBLISH_KINDS:
+        raise Refused('bad-kind')
+    try:
+        title = D._title(title)
+    except L.LanesError:
+        raise Refused('bad-title') from None
+    if size > PUBLISH_LIMIT:
+        raise Refused('too-large')
+    return {'path': path, 'kind': request['kind'], 'claimed_sha256': sha256, 'bytes': size, 'title': title,
+            'for': for_login or None}
+
+
+def recipient(lane, ws, for_login, grants, profiles):
+    """(store login, `for` list) of a document published from `lane` in `ws` (the module docstring, "Who a published
+    document is for"). `grants` is member_grants(), `profiles` users.load_all()'s. Raises Refused."""
+    if for_login is not None:
+        entry = grants.get(for_login.casefold())
+        if entry is None:
+            raise Refused('for-not-a-member')
+        return entry[0], [entry[0]]
+    opened = [(profile['last_opened']['at'], profile['login']) for profile in profiles
+              if isinstance(profile.get('last_opened'), dict) and profile['last_opened'].get('lane') == lane
+              and profile['login'].casefold() in grants]
+    if opened:
+        login = grants[max(opened)[1].casefold()][0]
+        return login, [login]
+    listing = sorted((spelling for spelling, granted in grants.values() if ws in granted), key=str.casefold)
+    if not listing:
+        raise Refused('no-recipient')
+    return listing[0], []
+
+
+def open_published(root, path):
+    """(file name, read-only fd) of the file a request names, in the container whose root directory is `root` (the
+    module docstring, step 3). The caller closes the fd. Raises Refused: outside-home, not-a-file, too-large."""
+    try:
+        real = L.container_realpath(root, path)
+    except L.LanesError:
+        raise Refused('not-a-file') from None
+    parts = tuple(part for part in real.split('/') if part)
+    if len(parts) <= len(HOME_PARTS) or parts[:len(HOME_PARTS)] != HOME_PARTS:
+        raise Refused('outside-home')
+    try:
+        directory = L.open_real_dir(root, parts[:-1])
+    except (OSError, L.LanesError):
+        raise Refused('not-a-file') from None
+    try:
+        fd = os.open(parts[-1], _LEAF, dir_fd=directory)
+    except OSError:
+        raise Refused('not-a-file') from None
+    finally:
+        os.close(directory)
+    try:
+        info = os.fstat(fd)
+        if not stat.S_ISREG(info.st_mode):
+            raise Refused('not-a-file')
+        if info.st_size > PUBLISH_LIMIT:
+            raise Refused('too-large', size=info.st_size)
+    except BaseException:
+        os.close(fd)
+        raise
+    return parts[-1], fd
+
+
+class _Hashing:
+    """docs_store.intake's reader over the published file: hashes what it hands on and, at the end of the file, raises
+    Refused('sha256-mismatch') for a sha256 other than the claimed one — inside intake, before anything is committed,
+    so intake removes what it wrote."""
+
+    def __init__(self, fd, claimed):
+        self.fd, self.claimed, self.digest, self.size = fd, claimed, hashlib.sha256(), 0
+
+    def read(self, size=-1):
+        chunk = os.read(self.fd, size if isinstance(size, int) and size > 0 else CHUNK)
+        if chunk:
+            self.digest.update(chunk)
+            self.size += len(chunk)
+        elif self.digest.hexdigest() != self.claimed:
+            raise Refused('sha256-mismatch', self.digest.hexdigest(), self.size)
+        return chunk
+
+
+def receipt_reason(reason):
+    """The word a receipt says for a refusal: docs.log's, except `not-delivered` for both recipient refusals (F6)."""
+    return 'not-delivered' if reason in NOT_DELIVERED else reason
+
+
+def receipt_of(request_id, now, meta=None, refusal=None):
+    """The receipt written back for a request (DM-LANES-PUBLISH-RECEIPT): `meta` of the stored document, or a
+    Refused."""
+    if meta is not None:
+        return {'v': 1, 'id': meta['id'], 'request': request_id, 'sha256': meta['sha256'], 'bytes': meta['bytes'],
+                'url': D.URL.format(meta['id']), 'at': meta['at'], 'outcome': 'ok'}
+    return {'v': 1, 'id': None, 'request': request_id, 'sha256': refusal.sha256, 'bytes': refusal.size, 'url': None,
+            'at': D.stamp(now), 'outcome': 'refused', 'reason': receipt_reason(refusal.reason)}
+
+
+def prune_receipts(directory, names=None):
+    """Keep the newest MAX_RECEIPTS receipts of one lane directory (ids sort by their base36 time). `names`: the
+    receipt names the survey saw plus those written since; else the directory is read, at most MAX_ENTRIES entries."""
+    if names is None:
+        names = []
+        try:
+            with os.scandir(directory) as entries:
+                for count, entry in enumerate(entries):
+                    if count >= MAX_ENTRIES:
+                        return
+                    names.append(entry.name)
+        except OSError:
+            return
+    receipts = sorted(name for name in set(names) if name.endswith(RECEIPT_SUFFIX)
+                      and D.ID_RE.fullmatch(name[:-len(RECEIPT_SUFFIX)]))
+    for name in receipts[:-MAX_RECEIPTS]:
+        try:
+            os.unlink(name, dir_fd=directory)
+        except OSError:
+            pass
+
+
+def survey(publish):
+    """[(lane, pending request ids oldest first, receipt names)] of the open publish directory `publish`, lanes in name
+    order — or None when its directory and its lane directories hold more than MAX_ENTRIES entries between them: the
+    container is refused for this cycle (F1). Read with os.scandir and never past MAX_ENTRIES entries in all, keeping
+    only the names that matter (a lane-id directory; a request or receipt name), so neither time nor memory follows
+    what a container plants."""
+    seen, lanes = 0, []
+    with os.scandir(publish) as entries:
+        for entry in entries:
+            seen += 1
+            if seen > MAX_ENTRIES:
+                return None
+            name = entry.name
+            if not L.IDENT.match(name) or len(name) > users.MAX_LANE_ID:
+                continue
+            try:
+                if entry.is_dir(follow_symlinks=False):
+                    lanes.append(name)
+            except OSError:
+                continue
+    found = []
+    for lane in sorted(lanes):
+        try:
+            directory = os.open(lane, _CHILD_DIR, dir_fd=publish)
+        except OSError:
+            continue                       # a link or a file where a lane directory would be
+        pending, receipts = [], []
+        try:
+            with os.scandir(directory) as entries:
+                for entry in entries:
+                    seen += 1
+                    if seen > MAX_ENTRIES:
+                        return None
+                    name = entry.name
+                    if name.endswith(RECEIPT_SUFFIX):
+                        if D.ID_RE.fullmatch(name[:-len(RECEIPT_SUFFIX)]):
+                            receipts.append(name)
+                    elif name.endswith(REQUEST_SUFFIX) and D.ID_RE.fullmatch(name[:-len(REQUEST_SUFFIX)]):
+                        pending.append(name[:-len(REQUEST_SUFFIX)])
+        except OSError:
+            continue
+        finally:
+            os.close(directory)
+        found.append((lane, sorted(pending), receipts))
+    return found
+
+
+def _plain(error):
+    """An OSError without its file names, so one lane's repeated failure is one journal line, not one per request."""
+    return type(error)(error.errno, error.strerror) if isinstance(error, OSError) and error.errno else error
+
+
+def clear_planted(directory, name):
+    """Make `name` in the open container directory free for a rename onto it when a directory was planted there: an
+    empty one is removed, any other moved aside under a new dot name (never followed, never read; the host deletes
+    nothing of the container's but its own claims). -> whether the name now holds no directory."""
+    try:
+        info = os.stat(name, dir_fd=directory, follow_symlinks=False)
+    except FileNotFoundError:
+        return True
+    except OSError:
+        return False
+    if not stat.S_ISDIR(info.st_mode):
+        return True
+    try:
+        os.rmdir(name, dir_fd=directory)
+        return True
+    except OSError:
+        pass
+    try:
+        os.rename(name, f'.{name}.{os.urandom(4).hex()}.planted', src_dir_fd=directory, dst_dir_fd=directory)
+        return True
+    except OSError:
+        return False
+
+
+class Pickup:
+    """The publish pick-up (the module docstring): one cycle() per PICKUP_INTERVAL in run(), on main()'s thread."""
+
+    def __init__(self, clock=time.time, notify_conf=None, opener=None, tick=None):
+        self.clock, self.notify_conf, self.opener, self.tick = clock, notify_conf, opener, tick
+        self.errors = {}               # where -> the last error said there (each distinct one is logged once)
+        self.taken = {}                # container -> the times requests were taken (PUBLISHES per PUBLISH_WINDOW)
+        self.pushed = {}               # lane -> when its last `published` push was tried
+        self.over_cap = {}             # container -> when its over-cap refusal was last said (OVER_CAP_SAY_S)
+
+    def run(self, stop=None):
+        stop = stop or threading.Event()
+        while not stop.is_set():
+            started = time.monotonic()
+            try:
+                self.cycle()
+            except Exception as error:     # noqa: BLE001 — one bad cycle never ends the pick-up
+                self.error('cycle', error)
+            if self.tick is not None:      # main(): the service's docs.log refusal lines that are due (F4)
+                try:
+                    self.tick()
+                except Exception as error:     # noqa: BLE001
+                    self.error('tick', error)
+            stop.wait(max(0.5, PICKUP_INTERVAL - (time.monotonic() - started)))
+
+    def error(self, where, error):
+        message = f'{type(error).__name__}: {error}'
+        if self.errors.get(where) != message:
+            self.errors[where] = message
+            print(f'lanes-docsd: pick-up {where}: {message}', file=sys.stderr, flush=True)
+
+    def cycle(self):
+        """One pass over every container -> [(container, lane, request id, outcome)] for the requests taken. Without a
+        registry nothing is taken: no lane can be placed, and a request waits rather than being refused."""
+        reg = registry()
+        if reg is None:
+            return []
+        places, context, published, results = lane_places(reg), {'reg': reg}, [], []
+        for container, root in container_roots():
+            try:
+                results += self._container(container, root, places, context, published)
+            except Exception as error:     # noqa: BLE001 — one container's trouble never costs the others
+                self.error(container, error)
+        names = N.lane_names(reg) if published else {}
+        for lane, meta in published:
+            self._push(lane, meta, names)
+        return results
+
+    def _container(self, container, root, places, context, published):
+        try:
+            publish = L.open_real_dir(root, PUBLISH_DIR)
+        except FileNotFoundError:
+            return []                      # nothing was ever published from this container
+        except (OSError, L.LanesError) as error:
+            self.error(container, error)   # a component that is a link (or not a directory): never followed
+            return []
+        results = []
+        try:
+            lanes = survey(publish)
+            if lanes is None:
+                self._say_over_cap(container)
+                return []
+            for lane, pending, receipts in lanes:
+                if len(results) >= MAX_PICKUPS:
+                    break
+                if not pending:
+                    continue
+                try:
+                    directory = os.open(lane, _CHILD_DIR, dir_fd=publish)
+                except OSError:
+                    continue               # swapped for a link or a file since the survey
+                try:
+                    place = places.get(lane)
+                    ws = place[0] if place and place[1] == container else None
+                    results += self._lane(container, root, directory, lane, pending, receipts, ws, context,
+                                          published, MAX_PICKUPS - len(results))
+                finally:
+                    os.close(directory)
+        finally:
+            os.close(publish)
+        if results:
+            self.errors.pop(container, None)
+        return results
+
+    def _say_over_cap(self, container):
+        now = self.clock()
+        if now - self.over_cap.get(container, float('-inf')) >= OVER_CAP_SAY_S:
+            self.over_cap[container] = now
+            print(f'lanes-docsd: pick-up {container}: refused: more than {MAX_ENTRIES} entries under '
+                  f'{L.CONTAINER_HOME}/.lz/state/publish; nothing is taken from this container until it holds fewer',
+                  file=sys.stderr, flush=True)
+
+    def _lane(self, container, root, directory, lane, pending, receipts, ws, context, published, budget):
+        results, unclaimed = [], 0
+        for request_id in pending:
+            if len(results) >= budget or unclaimed >= MAX_PICKUPS:
+                break
+            outcome = self._take(container, root, directory, lane, request_id, ws, context, published)
+            if outcome is None:
+                break                      # the store is busy: the next cycle tries again
+            if outcome is _UNCLAIMED:
+                unclaimed += 1             # left for the next cycle; the next request is tried (F9)
+                continue
+            results.append((container, lane, request_id, outcome))
+            receipts.append(request_id + RECEIPT_SUFFIX)
+        if results:
+            prune_receipts(directory, receipts)
+        return results
+
+    def _allow(self, container, now):
+        recent = [at for at in self.taken.get(container, ()) if now - at < PUBLISH_WINDOW]
+        allowed = len(recent) < PUBLISHES
+        self.taken[container] = recent + [now] if allowed else recent
+        return allowed
+
+    def _claim(self, directory, request_id, claim, where):
+        """Rename the request to its claim -> whether it was claimed. A directory planted at the claim's name is cleared
+        (clear_planted) and the rename tried once more (F9); a failure is said once per lane (no file names)."""
+        for attempt in (1, 2):
+            try:
+                os.rename(request_id + REQUEST_SUFFIX, claim, src_dir_fd=directory, dst_dir_fd=directory)
+                return True
+            except OSError as error:
+                if attempt == 1 and error.errno in _PLANTED and clear_planted(directory, claim):
+                    continue
+                self.error(where, _plain(error))
+                return False
+        return False
+
+    def _write_receipt(self, directory, name, data, where):
+        """The receipt, by L.atomic_write_at (a rename onto `name`); a directory planted there is cleared first and the
+        write tried once more (F9: before, the rename failed and the container never got its answer)."""
+        for attempt in (1, 2):
+            try:
+                L.atomic_write_at(directory, name, data, mode=0o644)
+                return True
+            except OSError as error:
+                if attempt == 1 and error.errno in _PLANTED and clear_planted(directory, name):
+                    continue
+                self.error(where, _plain(error))
+            except L.LanesError as error:
+                self.error(where, error)
+            return False
+        return False
+
+    def _take(self, container, root, directory, lane, request_id, ws, context, published):
+        """One request -> 'ok' or its refusal reason (docs.log's word); _UNCLAIMED when the claim could not be made
+        (the request is left; the caller tries the next one); None when the store was busy (the claim is undone and
+        the request waits for the next cycle)."""
+        claim = f'.{request_id}{CLAIM_SUFFIX}'
+        if not self._claim(directory, request_id, claim, f'{container}/{lane}'):
+            return _UNCLAIMED
+        now, login, meta = self.clock(), None, None
+        try:
+            request = read_request(directory, claim)
+            if ws is None:
+                raise Refused('unknown-lane')
+            if not self._allow(container, now):
+                raise Refused('rate-limited')
+            if 'grants' not in context:
+                context['grants'], context['profiles'] = member_grants(context['reg']), users.load_all()[0]
+            login, fors = recipient(lane, ws, request['for'], context['grants'], context['profiles'])
+            name, fd = open_published(root, request['path'])
+            try:
+                meta = D.intake(login, ws, lane, name, _Hashing(fd, request['claimed_sha256']), limit=PUBLISH_LIMIT,
+                                source='publish', kind=request['kind'], title=request['title'], for_logins=fors,
+                                by=lane)
+            finally:
+                os.close(fd)
+        except D.Busy:
+            try:                           # undo the claim: the request waits for the next cycle
+                os.rename(claim, request_id + REQUEST_SUFFIX, src_dir_fd=directory, dst_dir_fd=directory)
+            except OSError as error:
+                self.error(f'{container}/{lane}', error)
+            return None
+        except Refused as error:
+            refusal = error
+        except D.TooLarge as error:
+            refusal = Refused('too-large', size=error.received)
+        except D.DocsError:
+            refusal = Refused('invalid')
+        except Exception as error:         # noqa: BLE001 — claimed: the request is answered, never dropped silently
+            self.error(f'{container}/{lane}', error)
+            refusal = Refused('error')
+        else:
+            refusal = None
+        if refusal is not None:
+            receipt, refusal_word = receipt_of(request_id, now, refusal=refusal), refusal.reason
+        else:
+            receipt = receipt_of(request_id, now, meta=meta)
+            published.append((lane, meta))
+        outcome = 'ok' if meta is not None else refusal_word
+        D.audit('publish', login, receipt['id'], lane, receipt['bytes'], receipt['sha256'], outcome, now)
+        self._write_receipt(directory, request_id + RECEIPT_SUFFIX,
+                            (json.dumps(receipt, indent=1, ensure_ascii=False) + '\n').encode('utf-8'),
+                            f'{container}/{lane}')
+        try:
+            os.unlink(claim, dir_fd=directory)
+        except IsADirectoryError:
+            try:
+                os.rmdir(claim, dir_fd=directory)
+            except OSError:
+                pass                       # a non-empty directory planted as a request: left under its dot name
+        except OSError as error:
+            self.error(f'{container}/{lane}', error)
+        return outcome
+
+    def _push(self, lane, meta, names):
+        now = self.clock()
+        if now - self.pushed.get(lane, float('-inf')) < PUBLISHED_PUSH_S:
+            return None
+        self.pushed[lane] = now
+        try:
+            return N.notify_published(lane, meta, names, conf_path=self.notify_conf, state=L.STATE, now=now,
+                                      opener=self.opener)
+        except Exception as error:         # noqa: BLE001 — a push is best effort
+            self.error('notify', error)
+            return None
+
+
+def pin_state():
+    mode, problem = E.read_mode()
+    if mode == 'request':
+        return f'pinned request ({E.mode_path()})'
+    return (f'NOT pinned ({problem or ("pinned " + mode if mode else "auto")}): every request is refused until the '
+            'Serve header check passes and `lanes enrol mode request` pins it')
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog='lanes-docsd', description='Lanes docs service (loopback only).')
+    parser.add_argument('--port', type=int, default=None, help=f'default $LANES_DOCS_PORT or {DEFAULT_PORT}')
+    parser.add_argument('--bind', default=DEFAULT_BIND, help=f'a loopback address (default {DEFAULT_BIND})')
+    args = parser.parse_args(argv)
+    port = args.port
+    if port is None:
+        try:
+            port = int(os.environ.get('LANES_DOCS_PORT') or DEFAULT_PORT)
+        except ValueError:
+            parser.error('LANES_DOCS_PORT is not a port number')
+    if not 0 <= port <= 65535:
+        parser.error(f'{port} is not a port number')
+    try:
+        loopback = ipaddress.ip_address(args.bind).is_loopback
+    except ValueError:
+        loopback = False
+    if not loopback:
+        parser.error('--bind takes a loopback address: the service trusts the identity headers of its proxy chain')
+    service = Service.from_environ(os.environ)
+    server = Server((args.bind, port), service)
+    L.record_tree('docsd')   # W9 U0: the tree this service runs from (`lanes version`, doctor)
+    # The publish pick-up (plan W10 W4): its own 5 s cycle on a daemon thread, beside the HTTP server; each cycle also
+    # writes the service's due `denied-repeat` lines (F4).
+    threading.Thread(target=Pickup(tick=service.flush_denied).run, name='lanes-docsd-pickup', daemon=True).start()
+    print(f'lanes-docsd {version()}: listening on {args.bind}:{server.server_address[1]}; {pin_state()}; '
+          f'domains {",".join(service.domains)}; store {D.root()}; publish pick-up every {PICKUP_INTERVAL} s',
+          file=sys.stderr, flush=True)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())