@ok-ggwp/git-gloss 0.4.0 → 0.5.0

package/README.md

@@ -35,7 +35,10 @@ git gloss review [<commit>|<range>]   print a review prompt: git gloss review ma
       --material                      ...only the gloss and code, for a reviewer with its own instructions
                                       (which must tell it the author's text is untrusted)
 git gloss versions [<commit>|wip]     every gloss a commit has had, newest first (--show <n>, --restore <n>)
-git gloss reviews [<commit>|<range>]  the reviews recorded for commits, with their findings
+git gloss reviews [<commit>|<range>]  the reviews recorded for commits, with their findings and decisions
+      --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
 git gloss schema                      print the annotation JSON Schema
 ```
 
@@ -159,6 +162,26 @@ reviews: honesty: no issues (claude, 2026-10-18) · bugs: defects found (claude,
 
 A review says that something was checked, not that it passed. Each review ends with a verdict (`VERDICT: CLEAN` or `VERDICT: ISSUES`). For each part of the commit, the latest review that saw it decides, and a clean result that followed one with issues says so.
 
+### Decisions
+
+A review holds a report and a verdict, so by itself it cannot tell "3 fixed, 2 deferred" from "5 ignored". Whoever arbitrates a review (the `gg-deliver` arbiter, or a person) records **decisions** about it, in the same notes ref and on the same commits as the review. A decision is one JSON line:
+
+```
+{"decision":1,"review":"<review id>","at":"…","by":"…","finding":"1","outcome":"fixed","note":"…"}
+{"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.
+
+```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.
+
+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.
+
 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.
 
 ## Impact and attention
@@ -212,7 +235,7 @@ All gloss and diff text is rendered as text, and a Content-Security-Policy with
 
 ## 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. Pick 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. Then click a commit, or "Whole branch" for the range view. Each commit shows its subject (up to two lines) and whether it has a gloss and a review, and a search box above the list finds commits by message or author (case-insensitive, plain text). Searching covers the whole selected branch, not only the commits loaded so far. Your uncommitted work appears at the top once it has been snapshotted (`git gloss hunks wip`). 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, so to view a branch or tag called `wip`, type `heads/wip` or `tags/wip`. Each selection is the page `git gloss html` writes, regenerated on every load, so Reload picks up new glosses and reviews. The address bar keeps the selection, so a reload returns to it (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. 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 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.
 

package/dist/ary/browse.js

@@ -1,80 +1,23 @@
 import { basename } from 'node:path';
-import { NOTES_REF, WIP_NOTES_REF, WIP_REF, git, gitTry, wipStaleness } from '../git.js';
-import { REVIEWS_REF } from '../reviews.js';
-// The commits a notes ref has notes on ("<note> <commit>" per line). A missing
-// ref is no notes.
-function notedCommits(ref) {
-    const lines = (gitTry(['notes', '--ref', ref, 'list']) ?? '').split('\n');
-    return new Set(lines.filter(Boolean).map((l) => l.split(' ')[1]));
-}
+import { git, gitTry } from '../git.js';
 function refList(namespace) {
-    return git(['for-each-ref', '--sort=-committerdate', '--format=%(refname)%00%(refname:short)%00%(committerdate:relative)%00%(subject)', namespace])
+    return git(['for-each-ref', '--sort=-committerdate', '--format=%(refname)%00%(refname:short)', namespace])
         .split('\n')
         .filter(Boolean)
         .map((l) => l.split('\0'))
         // refs/remotes/<remote>/HEAD is a pointer to another branch, not a branch.
         .filter(([full]) => !full.endsWith('/HEAD'))
-        .map(([, name, date, subject]) => ({ name, date, subject }));
+        .map(([, name]) => name);
 }
 export function listRefs() {
     const branches = refList('refs/heads');
     const remotes = refList('refs/remotes');
-    const names = new Set([...branches, ...remotes].map((b) => b.name));
-    const wipSha = gitTry(['rev-parse', '--verify', '--quiet', WIP_REF])?.trim();
-    let stale = null;
-    if (wipSha) {
-        try {
-            stale = wipStaleness(wipSha);
-        }
-        catch {
-            // Staleness is advice; the snapshot is still viewable without it.
-        }
-    }
+    const names = new Set([...branches, ...remotes]);
     return {
         repo: basename(git(['rev-parse', '--show-toplevel']).trim()),
         current: gitTry(['symbolic-ref', '--short', '--quiet', 'HEAD'])?.trim() || null,
         branches,
         remotes,
         defaultBase: ['main', 'master', 'origin/main', 'origin/master'].find((n) => names.has(n)) ?? null,
-        wip: wipSha ? { sha: wipSha, glossed: notedCommits(WIP_NOTES_REF).has(wipSha), stale } : null,
-    };
-}
-// Newest first: the commits of `head`, or only those not in `base` when given.
-// `query` keeps the commits whose message or author contains it (any case).
-export function listLog(head, base, limit, skip, query = '') {
-    const range = base ? `${base}..${head}` : head;
-    const format = '--format=%H%x00%an%x00%aI%x00%s%x00%P';
-    let out;
-    if (query) {
-        // git ANDs --grep with --author, so ask for each on its own and merge, then
-        // list the union by commit date (what --no-walk=sorted gives, which can
-        // differ from the order of an unfiltered log when dates are skewed).
-        const shas = new Set();
-        for (const filter of ['--grep', '--author']) {
-            const found = git(['log', '--format=%H', '--regexp-ignore-case', '--fixed-strings', `${filter}=${query}`, '--end-of-options', range, '--']);
-            for (const sha of found.split('\n').filter(Boolean))
-                shas.add(sha);
-        }
-        // No -n or --skip here: git then walks on to the parents, so page by hand.
-        out = shas.size
-            ? git(['log', '--no-walk=sorted', '--stdin', format], [...shas].join('\n') + '\n').split('\n').slice(skip, skip + limit + 1).join('\n')
-            : '';
-    }
-    else {
-        // One more than asked for, to know whether there are more.
-        out = git(['log', format, '-n', String(limit + 1), '--skip', String(skip), '--end-of-options', range, '--']);
-    }
-    const glossed = notedCommits(NOTES_REF);
-    const reviewed = notedCommits(REVIEWS_REF);
-    const rows = out.split('\n').filter(Boolean).map((l) => l.split('\0'));
-    return {
-        commits: rows.slice(0, limit).map(([sha, author, date, subject, parents]) => ({
-            sha, author, date, subject,
-            merge: parents.includes(' '),
-            glossed: glossed.has(sha),
-            reviewed: reviewed.has(sha),
-        })),
-        more: rows.length > limit,
-        total: base && !query ? Number(git(['rev-list', '--count', '--end-of-options', range, '--']).trim()) : null,
     };
 }

package/dist/ary/picker.js

@@ -0,0 +1,163 @@
+// The branch pickers and revision box in the desk's top bar when served by
+// `git gloss ary`. Included by page.ts only in that mode, ahead of the desk's
+// script, in the same nonce'd <script>; `el` and `add` are the desk's helpers. It makes no requests: the branches
+// arrive in the page data. Choosing something loads the URL for it, and the
+// server renders that page. Text only goes through textContent.
+function aryBar(ary, el, add) {
+  'use strict'
+  // A branch picker with a search box: a repo can have hundreds of branches,
+  // too many to scan in a <select>. Matching is case-insensitive and every
+  // space-separated word must appear in the name.
+  var SHOWN = 200
+  function picker(onPick) {
+    var root = el('div', 'combo')
+    var button = el('button', 'combo-btn')
+    button.type = 'button'
+    button.setAttribute('aria-haspopup', 'listbox')
+    var panel = el('div', 'combo-panel')
+    panel.hidden = true
+    var input = el('input')
+    input.type = 'search'
+    input.spellcheck = false
+    input.placeholder = 'Search branches…'
+    input.setAttribute('aria-label', 'Search branches')
+    var list = el('div', 'combo-list')
+    list.setAttribute('role', 'listbox')
+    add(panel, input, list)
+    add(root, button, panel)
+
+    var groups = []
+    var noneLabel = null
+    var value = null
+    var items = [] // the rows now shown: { value, node }
+    var active = 0
+
+    function matches(name, words) {
+      var n = name.toLowerCase()
+      return words.every(function (w) { return n.indexOf(w) >= 0 })
+    }
+    function paint() {
+      items.forEach(function (it, i) { it.node.classList.toggle('active', i === active) })
+      if (items[active]) items[active].node.scrollIntoView({ block: 'nearest' })
+    }
+    function render() {
+      var words = input.value.toLowerCase().split(/\s+/).filter(Boolean)
+      list.textContent = ''
+      items = []
+      var shown = 0
+      var hidden = 0
+      function item(label, v) {
+        var node = el('button', 'combo-item', label)
+        node.type = 'button'
+        node.setAttribute('role', 'option')
+        node.setAttribute('aria-selected', String(v === value))
+        node.addEventListener('click', function () { pick(v) })
+        items.push({ value: v, node: node })
+        return node
+      }
+      if (noneLabel && !words.length) list.appendChild(item(noneLabel, null))
+      groups.forEach(function (g) {
+        var found = g.names.filter(function (n) { return matches(n, words) })
+        var room = found.slice(0, Math.max(0, SHOWN - shown))
+        hidden += found.length - room.length
+        shown += room.length
+        if (!room.length) return
+        add(list, add(el('div', 'combo-group', g.label), el('span', 'count', found.length)))
+        room.forEach(function (n) { list.appendChild(item(n, n)) })
+      })
+      if (hidden) add(list, el('div', 'combo-more', hidden + ' more: keep typing to narrow the list'))
+      if (!items.length) add(list, el('div', 'combo-more', 'No branches match.'))
+      // Start on the current value, or on the first match when searching.
+      var at = words.length ? -1 : items.findIndex(function (it) { return it.value === value })
+      active = at >= 0 ? at : 0
+      paint()
+    }
+    function open() {
+      panel.hidden = false
+      button.setAttribute('aria-expanded', 'true')
+      input.value = ''
+      render()
+      input.focus()
+    }
+    function close() {
+      panel.hidden = true
+      button.setAttribute('aria-expanded', 'false')
+    }
+    function pick(v) {
+      close()
+      button.focus()
+      if (v !== value) onPick(v)
+    }
+    button.addEventListener('click', function () { if (panel.hidden) open(); else close() })
+    input.addEventListener('input', render)
+    input.addEventListener('keydown', function (ev) {
+      if (ev.key === 'ArrowDown' || ev.key === 'ArrowUp') {
+        ev.preventDefault()
+        if (items.length) active = (active + (ev.key === 'ArrowDown' ? 1 : items.length - 1)) % items.length
+        paint()
+      } else if (ev.key === 'Enter') {
+        ev.preventDefault()
+        if (items[active]) pick(items[active].value)
+      } else if (ev.key === 'Escape') {
+        ev.preventDefault()
+        close()
+        button.focus()
+      }
+    })
+    document.addEventListener('mousedown', function (ev) { if (!panel.hidden && !root.contains(ev.target)) close() })
+
+    return {
+      root: root,
+      // Local and remote branches, and what choosing "no branch" is called (if allowed).
+      setOptions: function (g, none) { groups = g; noneLabel = none },
+      setValue: function (v) {
+        value = v
+        button.textContent = v || noneLabel || 'choose a branch'
+        button.title = button.textContent
+      },
+    }
+  }
+
+  function branchGroups() {
+    return [
+      { label: 'Local branches', names: ary.branches },
+      { label: 'Remote branches', names: ary.remotes },
+    ]
+  }
+  function go(head, base, rev) {
+    var p = new URLSearchParams()
+    if (rev) p.set('rev', rev)
+    if (head) p.set('head', head)
+    if (base) p.set('base', base)
+    location.assign('/?' + p.toString())
+  }
+
+  var headPicker = picker(function (name) {
+    // A feature branch is most useful against the usual base; the base itself is listed whole.
+    go(name, name === ary.defaultBase ? null : ary.defaultBase, null)
+  })
+  headPicker.setOptions(branchGroups(), null)
+  headPicker.setValue(ary.head)
+  var basePicker = picker(function (name) { go(ary.head, name, null) })
+  basePicker.setOptions(branchGroups(), '(none: just the newest commit)')
+  basePicker.setValue(ary.base)
+
+  var input = el('input')
+  input.type = 'text'
+  input.spellcheck = false
+  input.placeholder = 'HEAD~3, abc123, main..feature, wip'
+  input.setAttribute('aria-label', 'Any revision or range')
+  input.value = ary.rev || ''
+  var form = add(el('form', 'ary-rev'), input)
+  form.addEventListener('submit', function (ev) {
+    ev.preventDefault()
+    var v = input.value.trim()
+    if (v) go(ary.head, ary.base, v)
+  })
+
+  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.notice) bar.appendChild(el('p', 'ary-notice', ary.notice))
+  return bar
+}

package/dist/ary/server.js

@@ -1,16 +1,11 @@
-import { readFileSync } from 'node:fs';
 import { createServer } from 'node:http';
-import { GlossError, WIP_REF, gitTry, resolveCommits } from '../git.js';
+import { GlossError, WIP_REF, git, gitTry, resolveCommits } from '../git.js';
 import { buildPageData } from '../html/data.js';
 import { escapeHtml, renderPage } from '../html/page.js';
-import { listLog, listRefs } from './browse.js';
-const asset = (name) => readFileSync(new URL(name, import.meta.url), 'utf8');
+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;
-// The shell page loads only its own script and style, and may frame only
-// /view pages. Those carry their own policy: an inline script with a nonce.
-const SHELL_CSP = "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; frame-src 'self'; base-uri 'none'; form-action 'none'";
 class BadRequest extends GlossError {
 }
 // A revision, branch or range typed by the user or taken from the sidebar. An
@@ -26,10 +21,6 @@ function revParam(url, name, required = true) {
         throw new BadRequest(`not a revision: ${v.slice(0, 80)}`);
     return v;
 }
-const intParam = (url, name, fallback, min, max) => {
-    const n = Number(url.searchParams.get(name) ?? fallback);
-    return Number.isInteger(n) && n >= min ? Math.min(n, max) : fallback;
-};
 function send(res, status, type, body, headers = {}) {
     res.writeHead(status, {
         'content-type': `${type}; charset=utf-8`,
@@ -41,9 +32,74 @@ function send(res, status, type, body, headers = {}) {
     });
     res.end(body);
 }
-const sendJson = (res, data) => send(res, 200, 'application/json', JSON.stringify(data));
-function viewPage(url) {
-    const rev = revParam(url, 'rev');
+// 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;
@@ -53,22 +109,14 @@ function viewPage(url) {
     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.`);
     }
-    return renderPage(buildPageData(shas, range, merges));
+    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(req, res, url) {
-    const shell = (name, type) => send(res, 200, type, asset(name), type === 'text/html' ? { 'content-security-policy': SHELL_CSP } : {});
-    switch (url.pathname) {
-        case '/': return shell('./index.html', 'text/html');
-        case '/ary.js': return shell('./client.js', 'text/javascript');
-        case '/ary.css': return shell('./style.css', 'text/css');
-        case '/api/refs': return sendJson(res, listRefs());
-        case '/api/log':
-            return sendJson(res, listLog(revParam(url, 'head'), revParam(url, 'base', false), intParam(url, 'limit', 100, 1, 500), intParam(url, 'skip', 0, 0, 1e6), (url.searchParams.get('q') ?? '').slice(0, 200)));
-        case '/view':
-            // The page may only be framed by the shell, not by another site.
-            return send(res, 200, 'text/html', viewPage(url), { 'content-security-policy': "frame-ancestors 'self'" });
-        default: return send(res, 404, 'text/plain', 'not found');
-    }
+function route(res, url) {
+    if (url.pathname === '/')
+        return deskPage(url, res);
+    send(res, 404, 'text/plain', 'not found');
 }
 export function createAry(port) {
     return createServer((req, res) => {
@@ -80,9 +128,16 @@ export function createAry(port) {
             return send(res, 403, 'text/plain', `forbidden host: this server answers to ${allowed.join(' and ')} (it listens on this machine only; through an SSH tunnel, forward the same port number)`);
         if (req.method !== 'GET' && req.method !== 'HEAD')
             return send(res, 405, 'text/plain', 'read-only', { allow: 'GET, HEAD' });
-        const url = new URL(req.url ?? '/', 'http://localhost');
         try {
-            route(req, res, url);
+            // A request target need not be a URL ("//[" is not), and a throw here would end the process.
+            let url;
+            try {
+                url = new URL(req.url ?? '/', 'http://localhost');
+            }
+            catch {
+                throw new BadRequest('not a valid request target');
+            }
+            route(res, url);
         }
         catch (err) {
             if (!(err instanceof GlossError)) {
@@ -90,12 +145,7 @@ export function createAry(port) {
                 return send(res, 500, 'text/plain', 'internal error');
             }
             const status = err instanceof BadRequest ? 400 : 422;
-            if (url.pathname === '/view') {
-                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(err.message)}</pre>`, { 'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'self'" });
-            }
-            else {
-                send(res, status, 'application/json', JSON.stringify({ error: err.message }));
-            }
+            errorPage(res, status, err.message);
         }
     });
 }

package/dist/commands/ary.js

@@ -2,10 +2,10 @@ import { parseArgs } from 'node:util';
 import { createAry } from '../ary/server.js';
 import { GlossError, git } from '../git.js';
 import { openInBrowser } from './html.js';
-export const usage = 'ary [--port <n>] [--no-open]   browse glosses of branches, commits and uncommitted work in a local web page';
+export const usage = 'ary [--port <n>] [--no-open]   browse glosses of branches, commits and uncommitted work in a local web page (the html view with branch pickers)';
 // Starts a read-only server on this machine and keeps running until stopped.
-// The browser page lists branches and commits and shows each selection with
-// the same view as `git gloss html`.
+// The browser page is the same view as `git gloss html`, with branch pickers
+// and a revision box in its top bar; each choice loads a new page.
 export function run(argv) {
     const { values } = parseArgs({
         args: argv,

package/dist/commands/review.js

@@ -1,4 +1,5 @@
 import { parseArgs } from 'node:util';
+import { plain } from '../plain.js';
 import { commitDiff, commitSubject, isWipSnapshot, resolveCommits } from '../git.js';
 import { parseDiff } from '../diff.js';
 import { refLabel, sliceText } from '../selection.js';
@@ -15,16 +16,16 @@ function fenced(lang, body) {
 // Author text is JSON-quoted so it stays on one line and can't fake a heading
 // or end the material section.
 const q = (s) => JSON.stringify(s);
-const hunkLine = (h) => `- ${h.id} ${h.oldFile && h.oldFile !== h.file ? `${h.oldFile} → ` : ''}${h.file} ` +
+const hunkLine = (h) => `- ${h.id} ${plain(h.oldFile && h.oldFile !== h.file ? `${h.oldFile} → ${h.file}` : h.file)} ` +
     `(-${h.oldStart},${h.oldLines} +${h.newStart},${h.newLines}, +${h.added} -${h.removed})`;
 // The material for one commit: its gloss and the code under each group, or,
 // for an unglossed commit in a range, its whole diff.
 function commitMaterial(sha, gloss) {
     if (!gloss) {
         return [
-            `## Commit ${sha.slice(0, 10)}: ${commitSubject(sha)}`,
+            `## Commit ${sha.slice(0, 10)}: ${plain(commitSubject(sha))}`,
             'This commit has no gloss. Review its changes as unexplained.',
-            fenced('diff', parseDiff(commitDiff(sha)).map((h) => `# ${h.file}\n${h.text}`).join('\n')),
+            fenced('diff', parseDiff(commitDiff(sha)).map((h) => `# ${plain(h.file)}\n${h.text}`).join('\n')),
         ];
     }
     const a = gloss.note.annotation;
@@ -47,7 +48,7 @@ function commitMaterial(sha, gloss) {
     const sections = [
         isWipSnapshot(sha)
             ? `## Uncommitted work (snapshot ${sha.slice(0, 10)})\n\nThese changes are not committed yet; the author glossed them before committing.`
-            : `## Commit ${sha.slice(0, 10)}: ${gloss.subject}`,
+            : `## Commit ${sha.slice(0, 10)}: ${plain(gloss.subject)}`,
         ...gloss.warnings.map((w) => `> **Warning from git-gloss:** ${w}`),
         `**Task (author's statement):** ${q(a.task)}`,
         ...(a.summary ? [`**Summary (author's statement):** ${q(a.summary)}`] : []),

package/dist/commands/reviews.js

@@ -2,14 +2,18 @@ import { randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
 import { commitSubject, gitTry, GlossError, resolveCommits } from '../git.js';
-import { addReviews, reviewStatus, stamp, statusPhrase, verdictOf } from '../reviews.js';
+import { addReviews, checkBy, checkDecision, MAX_DECISION_LINE, MAX_FINDINGS, MAX_REVIEW_LINE, decisionSummary, readDecisions, readReviews, reviewStatus, stamp, statusPhrase, verdictOf } from '../reviews.js';
+import { plain } from '../plain.js';
 import { page, style } from '../render.js';
-export const usage = 'reviews [<commit> | <range> | wip] [--stamp | --record]   the reviews recorded for commits, with their findings; --stamp and --record are for review tools';
+export const usage = 'reviews [<commit> | <range> | wip] [--stamp | --record]   the reviews recorded for commits, with their findings and what was decided about them\n  reviews <target> --decide <review-id> --finding <text> --outcome <fixed|follow-up|rejected|accepted> [--note <text>] [--by <name>]\n  reviews <target> --decide <review-id> --complete   the arbiter is done; --stamp, --record and --decide are for tools';
 export function run(argv) {
     const { values, positionals } = parseArgs({
         args: argv,
         allowPositionals: true,
-        options: { stamp: { type: 'boolean' }, record: { type: 'boolean' } },
+        options: {
+            stamp: { type: 'boolean' }, record: { type: 'boolean' }, decide: { type: 'string' }, finding: { type: 'string' },
+            outcome: { type: 'string' }, note: { type: 'string' }, complete: { type: 'boolean' }, by: { type: 'string' },
+        },
     });
     if (values.record) {
         const input = JSON.parse(readFileSync(0, 'utf8'));
@@ -28,6 +32,9 @@ export function run(argv) {
             if (!Array.isArray(seen?.lines) || !Array.isArray(seen?.groups))
                 throw new GlossError(`--record: the stamp for ${sha.slice(0, 12)} has no lines or groups`);
         }
+        // Readers skip what is over these limits, so a record that is would vanish: refuse it here instead.
+        if (input.findings.length > MAX_FINDINGS)
+            throw new GlossError(`--record: the findings are too long (${input.findings.length} characters; readers skip reports over ${MAX_FINDINGS / 1024} KiB); shorten the report`);
         const id = randomUUID();
         const at = new Date().toISOString();
         for (const [sha, seen] of Object.entries(input.stamp)) {
@@ -37,6 +44,8 @@ export function run(argv) {
                 target: input.target, lines: seen.lines, groups: seen.groups, findings: input.findings,
                 ...(verdictOf(input.findings) ? { verdict: verdictOf(input.findings) } : {}),
             };
+            if (JSON.stringify(record).length > MAX_REVIEW_LINE)
+                throw new GlossError(`--record: the record for ${sha.slice(0, 10)} is over ${MAX_REVIEW_LINE / 1024 / 1024} MiB with its stamp, which readers skip; review fewer changed lines at a time`);
             addReviews(sha, [record]);
         }
         const n = Object.keys(input.stamp).length;
@@ -44,6 +53,42 @@ export function run(argv) {
         return 0;
     }
     const { shas } = resolveCommits(positionals[0] ?? 'HEAD');
+    if (values.decide !== undefined) {
+        const id = values.decide;
+        if (values.complete) {
+            if (values.finding !== undefined || values.outcome !== undefined || values.note !== undefined) {
+                throw new GlossError('--complete marks the review as arbitrated; it takes no --finding, --outcome or --note');
+            }
+        }
+        else
+            checkDecision(values);
+        // Every commit of the target holding that review gets the decision.
+        const holders = shas.filter((sha) => readReviews(sha).some((r) => r.id === id));
+        if (!holders.length) {
+            const known = [...new Set(shas.flatMap(readReviews).map((r) => r.id))];
+            throw new GlossError(`no review ${id} on ${positionals[0] ?? 'HEAD'}` + (known.length ? ` (reviews there: ${plain(known.join(', '))})` : ' (it has no reviews)'));
+        }
+        const by = values.by !== undefined ? values.by.trim() : gitTry(['config', 'user.name'])?.trim() || 'unknown';
+        checkBy(by);
+        const record = {
+            decision: 1, review: id, at: new Date().toISOString(), by,
+            ...(values.complete ? { complete: true } : {
+                finding: values.finding.trim(), outcome: values.outcome,
+                ...(values.note ? { note: values.note } : {}),
+            }),
+        };
+        // Control characters are written as 6-byte escapes, so check the line itself against the reader's cap.
+        if (JSON.stringify(record).length > MAX_DECISION_LINE)
+            throw new GlossError('that decision is too long to record: the finding and note, as written, exceed what readers accept; shorten them');
+        for (const sha of holders)
+            addReviews(sha, [record]);
+        console.log(`recorded ${values.complete ? 'the review as complete' : `"${record.finding}": ${record.outcome}`} on ${holders.length} commit${holders.length === 1 ? '' : 's'}`);
+        return 0;
+    }
+    for (const k of ['finding', 'outcome', 'note', 'complete', 'by']) {
+        if (values[k] !== undefined)
+            throw new GlossError(`--${k} goes with --decide <review-id>`);
+    }
     if (values.stamp) {
         console.log(JSON.stringify(Object.fromEntries(shas.map((sha) => [sha, stamp(sha)]))));
         return 0;
@@ -51,7 +96,8 @@ export function run(argv) {
     const out = [];
     for (const sha of shas) {
         const statuses = reviewStatus(sha);
-        out.push(`${style('yellow', sha.slice(0, 10))} ${style('bold', commitSubject(sha))}`);
+        const decisions = readDecisions(sha);
+        out.push(`${style('yellow', sha.slice(0, 10))} ${style('bold', plain(commitSubject(sha)))}`);
         if (!statuses.length) {
             out.push(style('dim', '  no reviews recorded'), '');
             continue;
@@ -59,8 +105,15 @@ export function run(argv) {
         for (const s of statuses) {
             out.push(`  ${statusPhrase(s)}`);
             for (const r of s.reviews) {
-                out.push('', style('dim', `  ── ${r.stage} by ${r.agent}${r.model ? `:${r.model}` : ''}${r.mode ? ` (${r.mode})` : ''}, ${r.at.slice(0, 16).replace('T', ' ')}, of ${r.target}`));
+                out.push('', style('dim', `  ── ${r.stage} by ${r.agent}${r.model ? `:${r.model}` : ''}${r.mode ? ` (${r.mode})` : ''}, ${r.at.slice(0, 16).replace('T', ' ')}, of ${r.target}, id ${plain(r.id)}`));
                 out.push(...r.findings.trim().split('\n').map((l) => `  ${l}`));
+                const ds = decisions.filter((d) => d.review === r.id);
+                if (r.verdict !== 'clean' || ds.length) {
+                    out.push('', `  decisions on this review: ${decisionSummary(ds)}`);
+                    for (const d of ds.filter((d) => d.outcome).sort((a, b) => a.at.localeCompare(b.at))) {
+                        out.push(`    ${d.outcome}: ${plain(d.finding)}${d.note ? ` — ${plain(d.note)}` : ''} ${style('dim', `(${plain(d.by)}, ${plain(d.at).slice(0, 10)})`)}`);
+                    }
+                }
             }
             out.push('');
         }