@ok-ggwp/git-gloss 0.5.0 → 0.7.0

package/README.md

@@ -15,6 +15,8 @@ git gloss hunks [<commit>|wip]        list hunks, numbering changed lines for h3
 git gloss signals [<commit>|<range>|wip] [--json]
                                       what the diff itself says about attention: path classes, pattern
                                       hits, dependency bumps and the computed floor
+git gloss lint [<commit>|wip] [--json]
+                                      advisory checks of a gloss that a reviewer would make by eye
 git gloss adopt [<commit>]            move the gloss of uncommitted work onto the commit made from it
 git gloss add [<commit>] -f a.json    attach an annotation (validated against the diff; --allow-underrate)
 git gloss carry <source>... [--to <c>] gloss a commit from the glosses of the commits its changes came from
@@ -39,6 +41,8 @@ git gloss reviews [<commit>|<range>]  the reviews recorded for commits, with the
       --decide <review-id> --finding <text> --outcome fixed|follow-up|rejected|accepted [--note <text>]
                                       record what was decided about one finding
       --decide <review-id> --complete  the arbiter has finished with that review
+      --decide-template <review-id>   print a JSON skeleton with a row per finding
+      --decide <review-id> --decide-file <file|->  record a filled-in skeleton, all or nothing
 git gloss schema                      print the annotation JSON Schema
 ```
 
@@ -108,7 +112,7 @@ In each repo you use it in:
 
 Put the line in the repo rather than in your user-level `CLAUDE.md`: it only makes sense where `git gloss init` has been run.
 
-`sync` fetches the remote's glosses into `refs/notes/remotes/<remote>/gloss`, merges them into yours, and pushes the glosses of commits the remote has (or, from the hook, is being sent), retrying if someone else pushed in between. Glosses of commits that exist only on your machine, such as a private branch, stay local until those commits are pushed. Glosses on different commits simply combine, and a gloss changed on only one side since you last synced is taken from that side. Only when both sides changed the same commit's gloss since then is it a conflict: the newer gloss (by its `created_at`) wins, because a re-gloss is normally a correction, and if either can't be read, yours is kept. It prints what it fetched, pushed and decided. The hook never blocks a push: if syncing fails it prints a warning and the push goes ahead. It does nothing for `git push --dry-run`. It syncs before the branch is pushed (so glosses arrive even if the branch push is then rejected), and it disables credential prompts so a remote that needs one fails fast instead of stalling the push. If you already have a `pre-push` or `post-commit` hook, `init --hooks` leaves it alone and prints the lines to add. It also won't install into a `core.hooksPath` outside the repository, since other repositories may share that directory.
+`sync` fetches the remote's glosses into `refs/notes/remotes/<remote>/gloss`, merges them into yours, and pushes the glosses of commits the remote has (or, from the hook, is being sent), retrying if someone else pushed in between. Glosses of commits that exist only on your machine, such as a private branch, stay local until those commits are pushed. Glosses on different commits simply combine, and a gloss changed on only one side since you last synced is taken from that side. Only when both sides changed the same commit's gloss since then is it a conflict: the newer gloss (by its `created_at`) wins, because a re-gloss is normally a correction, and if either can't be read, yours is kept. It prints what it fetched, pushed and decided. The hook never blocks a push: if syncing fails it prints a warning and the push goes ahead. It does nothing for `git push --dry-run`. It syncs before the branch is pushed (so glosses arrive even if the branch push is then rejected), and it disables credential prompts so a remote that needs one fails fast instead of stalling the push. If you already have a `pre-push` or `post-commit` hook, `init --hooks` leaves it alone and prints the lines to add. It also won't install into a `core.hooksPath` outside the repository, since other repositories may share that directory. If the remote once published `refs/notes/gloss/<something>`, the stale tracking refs under `refs/notes/remotes/<remote>/gloss/` that would block the fetch are deleted first; if a fetch still fails, `git remote prune <remote>` is the fix.
 
 ## Glossing before you commit
 
@@ -124,6 +128,10 @@ git gloss adopt                # ...or move it by hand
 
 The snapshot is a commit object built from a temporary index, kept by the private ref `refs/worktree/gloss/wip` (one per linked worktree); your branch, index and files are never touched. Taking a new snapshot keeps the gloss of groups whose changes are unchanged, so after committing part of the work or editing one part, only the rest needs glossing again. Its gloss lives in `refs/notes/gloss-wip`, which `sync` doesn't push. Untracked files that look like secrets (`.env`, `*.key`, `*.pem`, `credentials.json`, …) are left out of the snapshot, with a note, because snapshots are shown and sent to reviewers; stage one with `git add` to include it. If a branch or tag is called `wip`, `wip` still means it when there's no snapshot; otherwise use `heads/wip`. Commands warn when you've edited files or committed since the snapshot. `adopt` matches the snapshot's hunks to the commit's by content, so the work can be committed in several commits (each takes the groups whose changes it contains), and changes made after glossing are reported as unexplained rather than silently covered. Once everything is committed, the snapshot is cleared.
 
+## Linting a gloss
+
+`git gloss lint [<commit>|wip]` checks a gloss deterministically for what a reviewer checking its honesty would look for by eye, and prints one line per finding with a stable code: `no-impact`, `impact-below-floor`, `attention-below-floor`, `mechanical-on-floor` (graded mechanical over a floor signal such as CI or sensitive code; a lockfile bump is fine), `unknown-serves`, `test-serves-nothing`, `required-but-nothing-breaks` (`removal_impact` begins "nothing breaks", "no effect" and the like), `missing-risks` (attention `careful` or above and no `risks`), `config-edit` (the diff edits `.gloss/config.json`, which changes what the signals count; the same note `add` prints) and `uncovered-hunks` (a stale gloss). It is advisory: findings never change the exit code (errors such as no gloss still do). `--json` prints `{target, findings: [{code, group?, hunk?, message}]}`. When the diff signals are unavailable (a malformed `.gloss/config.json`), the rating checks are skipped and lint says `incomplete` (`"incomplete": true` in `--json`) instead of `clean`. Run it after `add` and fix what it reports, or be ready to defend it.
+
 ## Glosses that follow your history
 
 A gloss is attached to a commit, so anything that makes new commits from old ones has to bring it along. With `git gloss init --hooks`:
@@ -171,16 +179,31 @@ A review holds a report and a verdict, so by itself it cannot tell "3 fixed, 2 d
 {"decision":1,"review":"<review id>","at":"…","by":"…","complete":true}
 ```
 
-`finding` is free text naming the finding (reports are free text, so git-gloss doesn't parse findings out of them); `outcome` is `fixed`, `follow-up`, `rejected` or `accepted`; `note` is optional. The second line says the arbiter has finished and no more decisions are coming, which is what separates "all arbitrated" from "5 ignored". The marker is advisory: decisions added after it are still accepted and counted. A review whose verdict is clean needs none.
+`finding` is free text naming the finding. Reports are free markdown, so git-gloss does not parse findings out of the stored text, but for display (in `reviews` and the html page; the stored report stays raw) it labels every top-level list item `**[S.N]**`, S the section (a `#` heading, a bold-only line such as `**2. Removal**`, or a short plain `3. Title` line with a blank line on each side, followed by a bullet list; its own number if it has one, else the previous section plus one; unnumbered headings before the first item are titles and take none) and N the item's place in it, replacing the source's own bullet or number. Items before the first heading are labelled `[N]` and must be named `N:` or `N)` in `--decide` (`1 wording nit` is free text); a numbered heading (`3. Removal`) counts as the ref `3` for `--decide` although no label is printed for it.
+
+Name a decision's finding by that ref, e.g. `--finding "1.2 wording nit"`: `--decide` warns on stderr (and records anyway) when the report has no such ref.
+
+Decisions whose finding starts with a ref (`1.2 `, `1.2: `, or a bare `3:`, `3)`, `3.`; numbers over 3 digits are text) are listed in ref order (1.2 before 1.10), the others after them in time order.
+
+A finding must have visible text: one that is empty, whitespace or only invisible characters is refused by `--decide` and skipped by the reader. `outcome` is `fixed`, `follow-up`, `rejected` or `accepted`; `note` is optional. The second line says the arbiter has finished and no more decisions are coming, which is what separates "all arbitrated" from "5 ignored". The marker carries no `finding`, `outcome` or `note` (`--complete` refuses them, and the reader skips a marker that has one, or `"complete": false`, which only a hand-written line has). The reader takes the keys in any order. The marker is advisory: decisions added after it are still accepted and counted. A review whose verdict is clean needs none.
 
 ```bash
 git gloss reviews wip --decide <review-id> --finding "Rework: wip rule claim" --outcome follow-up --note "next release"
 git gloss reviews wip --decide <review-id> --complete
 ```
 
-The target (`wip`, a commit, a range) is as for `reviews`; the decision is added to every commit there that holds that review, and an unknown review id is an error. `by` is `--by <name>`, else `git config user.name`, else "unknown". `reviews` prints each review's id in its header line (the id `--decide` takes) and lists its decisions under it with a summary ("3 fixed, 2 follow-up · complete", or "4 decided · not marked complete"), and `show` carries the same summary on its reviews line. The HTML view does not show decisions yet. Decisions follow their reviews through `adopt` (so decisions made on `wip` survive committing), `carry`, rebases and `sync`. Text from notes (decisions and review records) and commit subjects is shown with control characters and escape sequences removed, since it can arrive from a remote; decision lines over 16 KB are skipped silently, and review lines over 8 MiB or with findings text over 256 KiB are skipped with a warning; unknown outcomes and decisions for a review that is not on the commit are ignored.
+To decide many findings at once, print a skeleton, fill in each `outcome` (and `note`), and record the file:
 
-Known cost: decisions share the review note, and a git-gloss without this feature ignores decision lines when reading but does not know to keep them: when it copies review records onto another commit (`adopt` and `carry`), it writes only the review records, so the decisions are lost on that copy (git's own note rewriting on an amend or rebase copies whole notes, so that path keeps them). Keep everyone who arbitrates on the same version.
+```bash
+git gloss reviews wip --decide-template <review-id> > d.json    # one row per finding, outcome ""
+git gloss reviews wip --decide <review-id> --decide-file d.json  # or - for stdin
+```
+
+The template has a row for each finding, but none for a numbered heading that has items under it (those items are its findings); a hand-written row naming such a heading's bare number (`2`) is still accepted. A report that would give two findings the same ref (two `1.` headings with items, both `1.1`) gets `1/2`, `1/3`, ... (items `1/2.1`) on the later sections; the first keeps `1`. Only an actual clash relabels: a heading ref (`1`) and an item ref (`1.1`) never clash, so an empty numbered heading, an unnumbered heading or a bold line changes nothing, and every report whose refs were all distinct keeps exactly the refs it had. Decisions already recorded under an old, ambiguous ref (only reports with a clash) no longer match after the relabel and are listed as free text. Past `1/999` the label stays `1/999` and its items keep counting on, so no item row is lost. The file is either an array of `{"finding", "outcome", "note"?}` or the template's object `{"review", "complete", "decisions": [...]}` (`review` and unknown keys are ignored, though a `review` that isn't the `--decide` id is refused; `"complete": true` also records the complete marker). Keys may come in any order. Each finding is the ref and the start of its text (`1.2 wording nit`), checked as for the single call, with the same warning for a ref the report lacks. Validation is all or nothing: everything is checked before anything is written (a repeated finding is refused too), and the records go in one write per commit, with a range written commit by commit (so a git failure midway can leave earlier commits written), so a bad row (naming its entry number), an empty `outcome` (an unfilled row), or a file over 500 entries or 1 MiB, or one whose records come to over 512 KiB once written, records nothing. It prints `recorded N decisions on M commits`. Running the same file again is safe for its own author: a record equal to the latest decision for its finding on that commit (same review, finding, outcome, note and `by`) is skipped, so after a partly failed range write the re-run adds only what is missing, and says `recorded N decisions on W commits (S already recorded)`; S counts records, summed over the commits, and includes the complete marker. It is not a merge of arbiters: if someone else decided the same finding differently since, re-running an old file writes its decision again, as the latest. `--decide-template` warns on stderr when refs are ambiguous (a heading row that shares its ref with another finding). It cannot be combined with `--finding`, `--outcome`, `--note`, `--stamp` or `--record`.
+
+The target (`wip`, a commit, a range) is as for `reviews`; the decision is added to every commit there that holds that review, and an unknown review id is an error. `by` is `--by <name>`, else `git config user.name`, else "unknown". `reviews` prints each review's id in its header line (the id `--decide` takes) and lists its decisions under it with a summary ("3 fixed, 2 follow-up · complete", or "4 decided · not marked complete"), and `show` carries the same summary on its reviews line. The HTML view (`html` and `ary`) shows the same under each review in its Reviews pane, with an outcome chip per decision, and adds how far they got to the stage's rail row (the latest 200 decisions of a review are listed). Decisions follow their reviews through `adopt` (so decisions made on `wip` survive committing), `carry`, rebases and `sync`. In the terminal, text from notes (decisions and review records) and commit subjects is shown with control characters, escape sequences, and bidi and zero-width characters (U+200B, U+200E, U+200F, U+061C, U+2060-U+2064, U+FEFF, tag characters) removed (each becomes a space; ZWNJ and ZWJ stay, so Persian words and emoji sequences render intact, and so does the soft hyphen), since it can arrive from a remote; decision lines over 16 KB are skipped silently, and review lines over 8 MiB or with findings text over 256 KiB are skipped with a warning; unknown outcomes and decisions for a review that is not on the commit are ignored.
+
+Known cost: decisions share the review note, and a git-gloss without this feature ignores decision lines when reading but does not know to keep them: when it copies review records onto another commit (`adopt` and `carry`), it writes only the review records, so the decisions are lost on that copy (git's own note rewriting on an amend or rebase copies whole notes, so that path keeps them). Keep everyone who arbitrates on the same version. Likewise, decisions follow their reviews through `adopt` and `carry` only in versions that know them.
 
 Like glosses, reviews follow rebased commits in repos set up with `git gloss init`. Reviews are shared by `git gloss sync` (and so by every push with the hooks) like glosses, for commits the remote has. They never conflict: everyone's reviews are kept. Other tools can record reviews too: `git gloss reviews --stamp <rev>` before the review, then `git gloss reviews --record` with the stamp and the report as JSON on stdin.
 
@@ -202,11 +225,11 @@ Notes using these fields are format 4; a git-gloss that predates them refuses su
 - **Floor of the change**: skim for `local`, look for `module`, careful for `shared` and `contract`, must-read for `sensitive`, and at least careful when more than `attention.largeChangeFiles` (default 50) files changed.
 - **Derived attention** (when the gloss declares none): start from the highest group impact (declared, else the group's floor) with the same mapping, then raise it one step (capped at must-read, once however many apply) for a behaviour-changing group that no test group serves, for a speculative or defensive group outside tests, or for more than `largeChangeFiles` files; never below the floor. A group is *behaviour-changing* when its necessity is not `mechanical` and not all its hunks are tests, docs, generated files or lockfiles. It is *served by tests* when a group made only of test-file hunks names it in `serves`, directly or through groups it serves; a test group serving `"task"` doesn't count.
 
-`add` checks a gloss against the floor. A group whose declared `impact` is below its floor (above plain `module`) is a warning naming the signal. A declared `attention.level` below the floor is an error unless `attention.override_reason` says why; `--allow-underrate` turns that error into a warning. Leaving `impact` or `attention` out is always allowed. An `override_reason` is shown by `show` and `html` next to the floor, flagged as a mismatch.
+`add` checks a gloss against the floor. A group whose declared `impact` is below its floor (above plain `module`) is a warning naming the signal. A declared `attention.level` below the floor is an error unless `attention.override_reason` says why; `--allow-underrate` turns that error into a warning. `add` also warns, once, naming the groups with no `impact` that should have one: every group except a `mechanical` one on plain source (floor `module` or below); a mechanical lockfile bump, say, still counts. It still accepts the gloss, and leaving `impact` or `attention` out is never an error. An `override_reason` is shown by `show` and `html` next to the floor, flagged as a mismatch.
 
 ### Config
 
-The built-in defaults name no language, framework or tool, only common file names. A repo adds to them with `.gloss/config.json`, committed in that repo. The file is read from the base branch (the merge base of the checked-out `HEAD` and `origin/main`, `main`, `origin/master` or `master`, so a long-lived branch sees the config as of where it forked; a commit on the base branch itself reads its own config, flagged `sensitive` if it edits the file), never from the working tree, so a change cannot reclassify its own paths; a config edit only takes effect once it is on the base branch. With none of those branches the defaults apply, with a warning. Editing the file is itself always a `sensitive` path. A pattern that takes over 250 ms on a hunk is cut off and from then on counts as matching every changed line (with a warning), so a slow or padded line raises the floor and never lowers it:
+The built-in defaults name no language, framework or tool, only common file names. A repo adds to them with `.gloss/config.json`, committed in that repo. The file is read from the base branch (the merge base of the checked-out `HEAD` and `origin/main`, `main`, `origin/master` or `master`, so a long-lived branch sees the config as of where it forked; a commit on the base branch itself reads its own config, flagged `sensitive` if it edits the file), never from the working tree, so a change cannot reclassify its own paths; a config edit only takes effect once it is on the base branch. With none of those branches the defaults apply, with a warning; if git itself fails reading the file or finding the base, the ratings are unverifiable instead: `add` and `signals` stop with an error, `lint` reports `incomplete`, and `show`, `html` and `hunks` go without signals, so the defaults never stand in for the repo's stricter patterns. Editing the file is itself always a `sensitive` path. A pattern that takes over 250 ms on a hunk is cut off and from then on counts as matching every changed line (with a warning), so a slow or padded line raises the floor and never lowers it:
 
 ```json
 {
@@ -231,19 +254,22 @@ A class is a list that extends the default list, or `{ "extends": false, "globs"
 
 Give a range (`git gloss html main..feature --open`) for a branch or PR view: every non-merge commit in order (merges are listed as not reviewed; `A...B` is rejected), a necessity bar across the whole branch, and the sidebar grouped by commit. Commits without a gloss appear with their whole diff marked as unexplained. On range pages a group's link is `#g-<commit>-<group>`. `git gloss review main..feature` likewise covers every commit and adds branch-level questions, such as later commits that undo earlier ones.
 
-All gloss and diff text is rendered as text, and a Content-Security-Policy with a per-page nonce blocks any script the page didn't generate.
+All gloss and diff text is rendered as text. Commit subjects, authors, gloss and review text and decisions are shown with escape sequences and bidi, zero-width and byte-order-mark characters removed, as in the terminal (code lines in a diff are shown as they are). A Content-Security-Policy with a per-page nonce blocks any script the page didn't generate.
 
 ## Browsing
 
-`git gloss ary` starts a small web server and opens it in your browser, so you can explore glosses without working out commits, branches and ranges on the command line. The page is the review desk that `git gloss html` writes, with the pickers in its top bar: choose a branch and a branch to compare it with (the repo's `main` or `master` by default); each picker has a search box, for repos with many branches. With a base, the desk's own sidebar lists the commits of the range; with "none" (or when there is nothing beyond the base, or more than 200 commits) the page shows just the branch's newest commit and its groups. To look at anything else, such as `HEAD~3` or `release..main`, type it into the revision box. As everywhere in git-gloss, `wip` there means the snapshot of uncommitted work, which is what opens first once it has been snapshotted (`git gloss hunks wip`); to view a branch or tag called `wip`, type `heads/wip` or `tags/wip`. Every choice loads a new page (`/?rev=…&head=…&base=…`), regenerated from the repo each time, so reloading picks up new glosses and reviews, and the address keeps the selection (with a random port, a bookmark lasts only until you stop the server; pass `--port` for a stable address).
+`git gloss ary` starts a small web server and opens it in your browser, so you can explore glosses without working out commits, branches and ranges on the command line. The page is the review desk that `git gloss html` writes, with the pickers in its top bar: choose a branch and a branch to compare it with (the repo's `main` or `master` by default); each picker has a search box, for repos with many branches. With a base, the desk's own sidebar lists the commits of the range; with "none" (or when there is nothing beyond the base, or more than 200 commits) the page shows just the branch's newest commit and its groups. A typed range of more than 200 commits shows its newest 200 non-merge commits (and the merges since the oldest of them), with a notice that counts the non-merge commits. On a range, a box above the commit list filters the loaded commits by subject, author or short sha (plain text, not a pattern). When a snapshot of uncommitted work exists, an "Uncommitted work (wip)" link opens it, and the wip view says when the working tree has changed since the snapshot (the server never takes one). With no local branches and a detached HEAD, the page shows HEAD (the notice says whether remote branches exist). To look at anything else, such as `HEAD~3` or `release..main`, type it into the revision box. As everywhere in git-gloss, `wip` there means the snapshot of uncommitted work, which is what opens first once it has been snapshotted (`git gloss hunks wip`); to view a branch or tag called `wip`, type `heads/wip` or `tags/wip`. Every choice loads a new page (`/?rev=…&head=…&base=…`), regenerated from the repo each time, so reloading picks up new glosses and reviews, and the address keeps the selection (with a random port, a bookmark lasts only until you stop the server; pass `--port` for a stable address).
+
+It serves one repository, the one you run it in, until you press Ctrl-C. It listens on 127.0.0.1 only, on a free port (or `--port`), only answers requests addressed to that host name, and never changes the repository: it doesn't take snapshots, change refs or notes, or add objects to the object store (the wip staleness check builds its tree in a temporary directory, so each wip view costs a full temporary-index `git add -A`, proportional to the working tree; it gives up, saying so, on more than 5000 untracked files or when 10 s in total have passed, or git fails or times out in it). The commit filter and the wip link are part of the page. A page shows at most 200 commits; pick a narrower range for more. `--no-open` doesn't launch a browser.
 
-It serves one repository, the one you run it in, until you press Ctrl-C. It listens on 127.0.0.1 only, on a free port (or `--port`), only answers requests addressed to that host name, and never writes anything: it doesn't take snapshots or change notes. A page shows at most 200 commits; pick a narrower range for more. `--no-open` doesn't launch a browser.
+A page is built in a child process of its own, so a slow or hung git never stops the server answering other requests. A build that outlives `GIT_GLOSS_ARY_TIMEOUT` (ms, default 300000; 0, or more than 2147483647, = no limit) gets a 504 page and its git processes are killed; a single git over `GIT_GLOSS_GIT_TIMEOUT` is a 422 page. At most `GIT_GLOSS_ARY_JOBS` (default 4) pages are built at once, further requests get 503 with `Retry-After` at once; a page over `GIT_GLOSS_ARY_MAX_OUTPUT` bytes (default 32 MiB) is a 502; each running build can hold up to twice that in memory (4 builds: 256 MiB). Closing the browser tab, stopping the server (Ctrl-C, or a closed terminal) or a timeout kills the builds it was running.
 
 ## Caveats
 
 - Carrying a gloss onto a server-side squash needs the original commits in your repository; usually the author has them. If a squash merge resolved conflicts or changed much of the code, it may not reach the 80% match; run `git gloss carry <branch commits> --to <squash>`.
 - A gloss records each hunk's location and a hash of its content. If a commit is amended or rebased so its diff changes, `show`, `review` and `why` flag the gloss as stale instead of showing it against the wrong code.
 - Merge commits are diffed against their first parent.
+- A gloss note over 8 MiB (`MAX_NOTE_BYTES` in `src/schema.ts`) is refused when read, with a message saying so, and `add`, `adopt`, `carry` and `versions --restore` will not write one. In a range, `show`, `html`, `review` and `why` skip a commit whose gloss is refused (too big, not valid, over the caps) with a warning on stderr, as for a commit with no gloss (the html page says the gloss was refused and why); for a single commit it is an error. `versions` prints notes from the history cleaned of control characters, escape sequences and bidi/zero-width characters (`--show` too, so it is not byte-identical to the stored note), and `--restore` only brings back a version readers accept for that commit.
 - `git gloss html` writes to `~/.cache/git-gloss/<commit>.html` by default (or `$XDG_CACHE_HOME`). The page is a snapshot; regenerate it after re-glossing.
 
 ## License

package/dist/ary/desk.js

@@ -0,0 +1,112 @@
+import { GlossError, WIP_REF, git, gitTry, resolveCommits, wipStaleness } from '../git.js';
+import { buildPageData } from '../html/data.js';
+import { renderPage } from '../html/page.js';
+import { listRefs } from './browse.js';
+// A range page loads and lays out every commit in it, so a huge one would hang
+// the browser: a longer range shows its newest MAX_RANGE_COMMITS, with a notice.
+export const MAX_RANGE_COMMITS = 200;
+export class BadRequest extends GlossError {
+}
+// A revision, branch or range typed by the user or taken from the sidebar. An
+// option-looking one is refused so it can never be read by git as a flag.
+function revParam(url, name) {
+    const v = url.searchParams.get(name);
+    if (!v)
+        return null;
+    if (v.startsWith('-') || v.length > 500 || v.includes('\0'))
+        throw new BadRequest(`not a revision: ${v.slice(0, 80)}`);
+    return v;
+}
+// Runs in the server process, before any job starts: no git, only string checks.
+export function parseQuery(url) {
+    return { head: revParam(url, 'head'), base: revParam(url, 'base'), rev: revParam(url, 'rev') };
+}
+// The commits of `head` the page shows when nothing else is chosen: those
+// beyond `base` (when a page can show them all), or else the newest one (as a sha, so a branch called "wip"
+// doesn't mean the snapshot).
+function defaultRev(head, base) {
+    if (!head)
+        return null;
+    if (base) {
+        // A range beyond what a page shows would only be an error page: show the newest commit.
+        const n = Number(git(['rev-list', '--count', '--end-of-options', `${base}..${head}`, '--']).trim());
+        if (n > 0 && n <= MAX_RANGE_COMMITS)
+            return `${base}..${head}`;
+    }
+    return gitTry(['rev-parse', '--verify', '--quiet', `${head}^{commit}`])?.trim() || null;
+}
+const PAGE_HEADERS = { 'content-security-policy': "frame-ancestors 'none'" };
+// The page for ?rev=&head=&base=. head and base only fill the pickers and
+// choose the default rev; the rev alone decides which commits are shown.
+// Runs git synchronously: only ever called in a job's child process (and by tests).
+export function buildDesk(query) {
+    const refs = listRefs();
+    const snapshot = gitTry(['rev-parse', '--verify', '--quiet', WIP_REF])?.trim() || null;
+    const known = new Set([...refs.branches, ...refs.remotes]);
+    const { head: wantHead, base: wantBase } = query;
+    let rev = query.rev;
+    // The default base goes with the default branch.
+    const baseFor = (head) => (head === refs.defaultBase ? null : refs.defaultBase);
+    // A link or bookmark may name a branch that has since been deleted or
+    // renamed: use the usual choice instead, and say so.
+    let head = wantHead && known.has(wantHead) ? wantHead : null;
+    const fallback = refs.current || refs.defaultBase || refs.branches[0] || null;
+    let base;
+    let notice = null;
+    if (wantHead && !head) {
+        head = fallback;
+        base = baseFor(head);
+        notice = `Branch “${wantHead}” no longer exists; showing ${head ?? 'the default'} instead.`;
+    }
+    else if (wantBase && !known.has(wantBase)) {
+        head ??= fallback;
+        base = null;
+        notice = `The branch to compare with, “${wantBase}”, no longer exists; showing the newest commit of ${head ?? 'the default'}.`;
+    }
+    else if (head) {
+        base = wantBase;
+    }
+    else {
+        head = fallback;
+        base = wantBase ?? baseFor(head);
+    }
+    if (!rev) {
+        // Opening with nothing chosen shows the uncommitted work, if snapshotted;
+        // choosing a branch shows that branch.
+        const wip = !wantHead && !wantBase && snapshot;
+        rev = wip ? 'wip' : defaultRev(head, base);
+        if (!rev && head)
+            throw new GlossError(`${head} has no commits to show`);
+        if (!rev) {
+            // No branch to start from (no local branches, a detached HEAD): the checked-out commit.
+            rev = 'HEAD';
+            notice ??= `There are no ${refs.remotes.length ? 'local ' : ''}branches; showing the newest commit (HEAD).`;
+        }
+        if (!notice) {
+            const p = new URLSearchParams({ rev });
+            if (head)
+                p.set('head', head);
+            if (base)
+                p.set('base', base);
+            return { status: 302, type: 'text/plain', headers: { location: `/?${p}` }, body: 'redirecting' };
+        }
+    }
+    // "wip" is the latest snapshot of uncommitted work. The server never takes
+    // one (that is `git gloss hunks wip`): browsing doesn't change anything.
+    const target = rev === 'wip' ? snapshot : rev;
+    if (!target)
+        throw new GlossError('no snapshot of uncommitted work yet; run `git gloss hunks wip` first');
+    const { shas, merges, range, total } = resolveCommits(target, MAX_RANGE_COMMITS);
+    if (shas.length < total)
+        notice = `${notice ? notice + ' ' : ''}Showing the newest ${MAX_RANGE_COMMITS} of ${total} non-merge commits; narrow the range to see the rest.`;
+    // The wip view says when the working tree has moved on from the snapshot. It never takes a new
+    // one and writes nothing to the repository (see wipStaleness).
+    const stale = rev === 'wip' && snapshot ? wipStaleness(snapshot, true) : null;
+    if (stale)
+        notice = `${notice ? notice + ' ' : ''}This snapshot is out of date: ${stale}. Run \`git gloss hunks wip\` for a new one.`;
+    if (stale === undefined)
+        notice = `${notice ? notice + ' ' : ''}Could not check whether the working tree has changed since this snapshot was taken (too large or too slow to compare here).`;
+    const data = buildPageData(shas, range, merges);
+    data.ary = { repo: refs.repo, branches: refs.branches, remotes: refs.remotes, defaultBase: refs.defaultBase, head, base, rev, notice, wip: !!snapshot };
+    return { status: 200, type: 'text/html', headers: PAGE_HEADERS, body: renderPage(data) };
+}

package/dist/ary/jobs.js

@@ -0,0 +1,132 @@
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { parseGitTimeout } from '../git.js';
+// Pages are built in a child process (src/ary/page-job.ts), never in the server
+// process: git is called synchronously there, and a slow or hung git would stop
+// the server answering anything. Each child leads its own process group, so a
+// job that is cancelled, times out or is stopped takes its git with it.
+const JOB = fileURLToPath(new URL(`./page-job${import.meta.url.endsWith('.ts') ? '.ts' : '.js'}`, import.meta.url));
+const posInt = (raw, fallback) => (raw !== undefined && /^[1-9]\d*$/.test(raw.trim()) ? Number(raw) : fallback);
+// GIT_GLOSS_ARY_JOBS (page builds at once, 4), GIT_GLOSS_ARY_TIMEOUT (ms a build may take, 300000, 0 = no
+// limit; each git call has its own GIT_GLOSS_GIT_TIMEOUT inside it), GIT_GLOSS_ARY_MAX_OUTPUT (bytes, 32 MiB; a build holds up to twice that while the output is joined).
+export function poolOptionsFromEnv(env = process.env) {
+    return {
+        max: posInt(env.GIT_GLOSS_ARY_JOBS, 4),
+        // setTimeout fires at once for more than 2^31-1 ms (24.8 days): a limit that large means none
+        timeoutMs: ((t) => (t > 2 ** 31 - 1 ? 0 : t))(parseGitTimeout(env.GIT_GLOSS_ARY_TIMEOUT, 300_000)),
+        maxOutput: posInt(env.GIT_GLOSS_ARY_MAX_OUTPUT, 32 * 1024 * 1024),
+    };
+}
+// The flags of this process the child needs to run the same code (type stripping on a Node that
+// has it behind a flag, warnings, source maps, heap size). Anything else is left out: an `-e`
+// script, `--input-type` or `--import` of the parent would make the child run something else.
+const KEEP = /^--(no-)?experimental-[\w-]+(=.*)?$|^--(no-warnings|enable-source-maps|disable-warning=.+|max-old-space-size=\d+|stack-size=\d+)$/;
+export const childExecArgv = (argv) => argv.filter((a) => KEEP.test(a));
+// After SIGTERM the group gets this long before SIGKILL, but only while its leader (node) is still
+// alive: the leader dies on SIGTERM at once and its exit sends SIGKILL to the rest of the group, so
+// git rarely gets the grace. ary's git calls are read-only (see TODO).
+const GRACE_MS = 2000;
+export class JobPool {
+    live = new Set();
+    opts;
+    constructor(opts) { this.opts = opts; }
+    // null: all slots are taken (the caller answers 503; nothing is queued).
+    start(query) {
+        if (this.live.size >= this.opts.max)
+            return null;
+        const { timeoutMs, maxOutput } = this.opts;
+        let settle;
+        const result = new Promise((resolve) => { settle = resolve; });
+        const entry = { killNow: () => { }, cancel: () => { } };
+        let child;
+        try {
+            child = spawn(this.opts.execPath ?? process.execPath, [...(this.opts.execArgv ?? childExecArgv(process.execArgv)), JOB, JSON.stringify(query)], { detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+        }
+        catch (err) {
+            console.error(err);
+            return { result: Promise.resolve({ kind: 'error', status: 500, message: 'internal error' }), cancel() { } };
+        }
+        this.live.add(entry);
+        const pid = child.pid;
+        const killGroup = (sig) => { if (pid) {
+            try {
+                process.kill(-pid, sig);
+            }
+            catch { /* gone */ }
+        } };
+        let timers = [];
+        let stopping = false;
+        const stop = () => {
+            if (stopping)
+                return;
+            stopping = true;
+            killGroup('SIGTERM');
+            timers.push(setTimeout(() => killGroup('SIGKILL'), GRACE_MS).unref());
+        };
+        entry.killNow = () => killGroup('SIGKILL');
+        entry.cancel = () => { settle({ kind: 'cancelled' }); stop(); };
+        if (timeoutMs > 0) {
+            timers.push(setTimeout(() => {
+                settle({ kind: 'error', status: 504, message: `building this page took longer than ${timeoutMs / 1000} s and was stopped (GIT_GLOSS_ARY_TIMEOUT sets the limit)` });
+                stop();
+            }, timeoutMs).unref());
+        }
+        const chunks = [];
+        let size = 0;
+        let err = '';
+        child.stdout.on('data', (d) => {
+            size += d.length;
+            if (size > maxOutput) {
+                chunks.length = 0;
+                settle({ kind: 'error', status: 502, message: `the page is more than ${maxOutput} bytes; pick a narrower range` });
+                stop();
+                return;
+            }
+            if (!stopping)
+                chunks.push(d);
+        });
+        child.stderr.on('data', (d) => { if (err.length < 8192)
+            err += d; });
+        child.on('error', (e) => {
+            // a spawn failure may not be followed by 'close': free the slot here
+            console.error(e);
+            for (const t of timers)
+                clearTimeout(t);
+            this.live.delete(entry);
+            settle({ kind: 'error', status: 500, message: 'internal error' });
+        });
+        child.on('close', (code) => {
+            for (const t of timers)
+                clearTimeout(t);
+            timers = [];
+            // a straggler of the group (a git the job left behind) goes with it
+            killGroup('SIGKILL');
+            this.live.delete(entry);
+            if (stopping)
+                return settle({ kind: 'cancelled' });
+            const all = Buffer.concat(chunks);
+            const nl = all.indexOf(10);
+            if (code !== 0 || nl < 0) {
+                console.error(err.trim() || `page job ended with code ${code}`);
+                return settle({ kind: 'error', status: 500, message: 'internal error' });
+            }
+            try {
+                const head = JSON.parse(all.subarray(0, nl).toString('utf8'));
+                if (typeof head.error === 'string')
+                    return settle({ kind: 'error', status: head.status, message: head.error });
+                settle({ kind: 'page', status: head.status, type: head.type, headers: head.headers, body: all.subarray(nl + 1) });
+            }
+            catch (e) {
+                console.error(e);
+                settle({ kind: 'error', status: 500, message: 'internal error' });
+            }
+        });
+        return { result, cancel: () => entry.cancel() };
+    }
+    // Stops every running job: SIGTERM now, SIGKILL after the grace period.
+    cancelAll() { for (const j of [...this.live])
+        j.cancel(); }
+    // Synchronous and final, for a process that is exiting.
+    killAllNow() { for (const j of this.live)
+        j.killNow(); }
+}

package/dist/ary/page-job.js

@@ -0,0 +1,23 @@
+// Internal entry, run by the ary server as a child process (see jobs.ts): builds
+// one page so that the server's event loop never waits for git. argv[2] is the
+// checked query as JSON. stdout is one JSON line (the status, or an error
+// message) and then the page's bytes. An unexpected failure is left to node:
+// stack on stderr, exit code 1.
+import { GlossError } from '../git.js';
+import { buildDesk } from './desk.js';
+const query = JSON.parse(process.argv[2]);
+let head;
+let body = '';
+try {
+    const r = buildDesk(query);
+    head = { status: r.status, type: r.type, headers: r.headers };
+    body = r.body;
+}
+catch (err) {
+    if (!(err instanceof GlossError))
+        throw err;
+    head = { status: 422, error: err.message };
+}
+// No process.exit: let the pipe drain, a large page is written in pieces.
+process.stdout.write(JSON.stringify(head) + '\n');
+process.stdout.write(body);

package/dist/ary/picker.js

@@ -158,6 +158,14 @@ function aryBar(ary, el, add) {
   function field(label, node) { return add(el('div', 'ary-field'), el('span', null, label), node) }
   var bar = add(el('div', 'ary-bar'), el('span', 'ary-repo', ary.repo),
     field('Branch', headPicker.root), field('Compare with', basePicker.root), field('Revision', form))
+  if (ary.wip) {
+    var wip = el('a', 'ary-wip', 'Uncommitted work (wip)')
+    var q = new URLSearchParams({ rev: 'wip' })
+    if (ary.head) q.set('head', ary.head)
+    if (ary.base) q.set('base', ary.base)
+    wip.href = '/?' + q.toString()
+    bar.appendChild(wip)
+  }
   if (ary.notice) bar.appendChild(el('p', 'ary-notice', ary.notice))
   return bar
 }

package/dist/ary/server.js

@@ -1,26 +1,9 @@
 import { createServer } from 'node:http';
-import { GlossError, WIP_REF, git, gitTry, resolveCommits } from '../git.js';
-import { buildPageData } from '../html/data.js';
-import { escapeHtml, renderPage } from '../html/page.js';
-import { listRefs } from './browse.js';
-// A range page loads and lays out every commit in it, so a huge one would hang
-// the browser. Narrowing it is a better answer than a spinner.
-export const MAX_RANGE_COMMITS = 200;
-class BadRequest extends GlossError {
-}
-// A revision, branch or range typed by the user or taken from the sidebar. An
-// option-looking one is refused so it can never be read by git as a flag.
-function revParam(url, name, required = true) {
-    const v = url.searchParams.get(name);
-    if (!v) {
-        if (required)
-            throw new BadRequest(`missing ?${name}=`);
-        return null;
-    }
-    if (v.startsWith('-') || v.length > 500 || v.includes('\0'))
-        throw new BadRequest(`not a revision: ${v.slice(0, 80)}`);
-    return v;
-}
+import { GlossError } from '../git.js';
+import { escapeHtml } from '../html/page.js';
+import { BadRequest, parseQuery } from './desk.js';
+import { JobPool, poolOptionsFromEnv } from './jobs.js';
+export { MAX_RANGE_COMMITS } from './desk.js';
 function send(res, status, type, body, headers = {}) {
     res.writeHead(status, {
         'content-type': `${type}; charset=utf-8`,
@@ -32,94 +15,33 @@ function send(res, status, type, body, headers = {}) {
     });
     res.end(body);
 }
-// The page may not be framed by anyone: it shows the code of your commits.
-const PAGE_HEADERS = { 'content-security-policy': "frame-ancestors 'none'" };
 function errorPage(res, status, message) {
     send(res, status, 'text/html', `<!doctype html><meta charset="utf-8"><meta name="color-scheme" content="light dark"><pre style="white-space:pre-wrap;font:14px/1.5 system-ui;padding:16px">${escapeHtml(message)}</pre><p style="font:14px/1.5 system-ui;padding:0 16px"><a href="/">Back to the default view</a></p>`, { 'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'" });
 }
-// The commits of `head` the page shows when nothing else is chosen: those
-// beyond `base` (when a page can show them all), or else the newest one (as a sha, so a branch called "wip"
-// doesn't mean the snapshot).
-function defaultRev(head, base) {
-    if (!head)
-        return null;
-    if (base) {
-        // A range beyond what a page shows would only be an error page: show the newest commit.
-        const n = Number(git(['rev-list', '--count', '--end-of-options', `${base}..${head}`, '--']).trim());
-        if (n > 0 && n <= MAX_RANGE_COMMITS)
-            return `${base}..${head}`;
-    }
-    return gitTry(['rev-parse', '--verify', '--quiet', `${head}^{commit}`])?.trim() || null;
-}
-// The page for ?rev=&head=&base=. head and base only fill the pickers and
-// choose the default rev; the rev alone decides which commits are shown.
-function deskPage(url, res) {
-    const refs = listRefs();
-    const known = new Set([...refs.branches, ...refs.remotes]);
-    const wantHead = revParam(url, 'head', false);
-    const wantBase = revParam(url, 'base', false);
-    let rev = revParam(url, 'rev', false);
-    // The default base goes with the default branch.
-    const baseFor = (head) => (head === refs.defaultBase ? null : refs.defaultBase);
-    // A link or bookmark may name a branch that has since been deleted or
-    // renamed: use the usual choice instead, and say so.
-    let head = wantHead && known.has(wantHead) ? wantHead : null;
-    const fallback = refs.current || refs.defaultBase || refs.branches[0] || null;
-    let base;
-    let notice = null;
-    if (wantHead && !head) {
-        head = fallback;
-        base = baseFor(head);
-        notice = `Branch \u201c${wantHead}\u201d no longer exists; showing ${head ?? 'the default'} instead.`;
-    }
-    else if (wantBase && !known.has(wantBase)) {
-        head ??= fallback;
-        base = null;
-        notice = `The branch to compare with, \u201c${wantBase}\u201d, no longer exists; showing the newest commit of ${head ?? 'the default'}.`;
-    }
-    else if (head) {
-        base = wantBase;
-    }
-    else {
-        head = fallback;
-        base = wantBase ?? baseFor(head);
-    }
-    if (!rev) {
-        // Opening with nothing chosen shows the uncommitted work, if snapshotted;
-        // choosing a branch shows that branch.
-        const wip = !wantHead && !wantBase && gitTry(['rev-parse', '--verify', '--quiet', WIP_REF]);
-        rev = wip ? 'wip' : defaultRev(head, base);
-        if (!rev)
-            throw new GlossError(head ? `${head} has no commits to show` : 'there are no branches to show; pass ?rev= to view a commit');
-        if (!notice) {
-            const p = new URLSearchParams({ rev });
-            if (head)
-                p.set('head', head);
-            if (base)
-                p.set('base', base);
-            return send(res, 302, 'text/plain', 'redirecting', { location: `/?${p}` });
-        }
-    }
-    // "wip" is the latest snapshot of uncommitted work. The server never takes
-    // one (that is `git gloss hunks wip`): browsing doesn't change anything.
-    const target = rev === 'wip' ? gitTry(['rev-parse', '--verify', '--quiet', WIP_REF])?.trim() : rev;
-    if (!target)
-        throw new GlossError('no snapshot of uncommitted work yet; run `git gloss hunks wip` first');
-    const { shas, merges, range } = resolveCommits(target);
-    if (shas.length > MAX_RANGE_COMMITS) {
-        throw new GlossError(`${rev} has ${shas.length} commits; a page shows at most ${MAX_RANGE_COMMITS}. Pick a narrower range.`);
-    }
-    const data = buildPageData(shas, range, merges);
-    data.ary = { repo: refs.repo, branches: refs.branches, remotes: refs.remotes, defaultBase: refs.defaultBase, head, base, rev, notice };
-    send(res, 200, 'text/html', renderPage(data), PAGE_HEADERS);
-}
-function route(res, url) {
-    if (url.pathname === '/')
-        return deskPage(url, res);
-    send(res, 404, 'text/plain', 'not found');
+// The page is built in a child process (jobs.ts), so git never blocks this loop. The query is
+// checked here first: a refused request starts nothing. Answers: 503 + Retry-After when
+// all slots are busy, 504 when the build outlives GIT_GLOSS_ARY_TIMEOUT, 502 when its
+// output passes GIT_GLOSS_ARY_MAX_OUTPUT, 422 for what git or the repo says. A client that
+// leaves cancels its job.
+function route(res, url, pool) {
+    if (url.pathname !== '/')
+        return send(res, 404, 'text/plain', 'not found');
+    const job = pool.start(parseQuery(url));
+    if (!job)
+        return send(res, 503, 'text/plain', 'busy: too many pages are being built; retry in a moment', { 'retry-after': '1' });
+    res.on('close', () => { if (!res.writableFinished)
+        job.cancel(); });
+    job.result.then((r) => {
+        if (r.kind === 'cancelled' || res.destroyed || res.writableEnded)
+            return;
+        if (r.kind === 'error')
+            return r.status === 500 ? send(res, 500, 'text/plain', 'internal error') : errorPage(res, r.status, r.message);
+        send(res, r.status, r.type, r.body, r.headers);
+    });
 }
-export function createAry(port) {
-    return createServer((req, res) => {
+export function createAry(port, overrides = {}) {
+    const pool = new JobPool({ ...poolOptionsFromEnv(), ...overrides });
+    const server = createServer((req, res) => {
         // A web page on another site can make the browser send requests here, and
         // with DNS rebinding even read the answers. Only our own origin's host
         // names get through; the server is read-only besides.
@@ -137,7 +59,7 @@ export function createAry(port) {
             catch {
                 throw new BadRequest('not a valid request target');
             }
-            route(res, url);
+            route(res, url, pool);
         }
         catch (err) {
             if (!(err instanceof GlossError)) {
@@ -148,4 +70,16 @@ export function createAry(port) {
             errorPage(res, status, err.message);
         }
     });
+    // Closing the server stops what it is building, and nothing outlives the process.
+    const exitKill = () => pool.killAllNow();
+    process.on('exit', exitKill);
+    server.on('close', () => process.off('exit', exitKill));
+    const close = server.close.bind(server);
+    server.close = (cb) => {
+        pool.cancelAll();
+        const r = close(cb);
+        server.closeAllConnections();
+        return r;
+    };
+    return server;
 }