@ok-ggwp/git-gloss 0.6.0 → 0.7.0

package/dist/commands/add.js

@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs';
+import { readFileSync, readSync } from 'node:fs';
 import { parseArgs } from 'node:util';
 import { z } from 'zod';
 import { commitDiff, isWipSnapshot, NOTES_REF, readNote, resolveCommit, WIP_NOTES_REF, writeNote } from '../git.js';
@@ -7,6 +7,32 @@ import { Annotation, noteFormat } from '../schema.js';
 import { validate } from '../validate.js';
 import { loadConfig } from '../config.js';
 import { analyzeGroups, groupInputsFor, ratingProblems } from '../floor.js';
+// readFileSync(0) throws EAGAIN when the pipe is non-blocking and momentarily empty
+// (a big gloss from a slower writer): wait a moment and read on.
+function readStdin() {
+    const chunks = [];
+    const buf = Buffer.alloc(1 << 20);
+    for (;;) {
+        let n;
+        try {
+            n = readSync(0, buf);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === 'EAGAIN') {
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+                continue;
+            }
+            if (code === 'EOF')
+                break;
+            throw err;
+        }
+        if (n === 0)
+            break;
+        chunks.push(Buffer.from(buf.subarray(0, n)));
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
 export const usage = 'add [<commit>] [-f <file>] [--force] [--partial] [--allow-underrate] [--dry-run]   attach an annotation (JSON from file or stdin)';
 export function run(argv) {
     const { values, positionals } = parseArgs({
@@ -25,7 +51,7 @@ export function run(argv) {
         console.error('error: pipe annotation JSON on stdin or pass -f <file> (see `git gloss schema`)');
         return 2;
     }
-    const raw = readFileSync(values.file ?? 0, 'utf8');
+    const raw = values.file ? readFileSync(values.file, 'utf8') : readStdin();
     let json;
     try {
         json = JSON.parse(raw);

package/dist/commands/ary.js

@@ -31,5 +31,8 @@ export function run(argv) {
         if (!values['no-open'])
             openInBrowser(url);
     });
+    // The default action of a signal would skip the cleanup that kills running page builds.
+    for (const [sig, code] of [['SIGINT', 130], ['SIGTERM', 143], ['SIGHUP', 129], ['SIGQUIT', 131]])
+        process.on(sig, () => { server.close(); process.exit(code); });
     return 0;
 }

package/dist/commands/carry.js

@@ -1,6 +1,6 @@
 import { parseArgs } from 'node:util';
 import { existsSync, readFileSync } from 'node:fs';
-import { commitDiff, git, GlossError, readNote, resolveCommit, resolveCommits, writeNote } from '../git.js';
+import { commitDiff, git, GlossError, readNote, rethrowTimeout, resolveCommit, resolveCommits, writeNote } from '../git.js';
 import { matchHunks } from '../loader.js';
 import { findOrigins } from '../origins.js';
 import { location, parseDiff } from '../diff.js';
@@ -20,6 +20,7 @@ export function targetState(sha) {
         return note ? (note.sources || note.carried_from ? 'carried' : 'glossed') : 'none';
     }
     catch (err) {
+        rethrowTimeout(err);
         if (err instanceof GlossError)
             return 'broken';
         throw err;
@@ -41,6 +42,7 @@ export function carry(sourceShas, target) {
             note = readNote(sha);
         }
         catch (err) {
+            rethrowTimeout(err);
             if (!(err instanceof GlossError))
                 throw err;
             unreadable.push(`${sha.slice(0, 7)} (${err.message.replace(/^the gloss on \S+ /, '')})`);

package/dist/commands/lint.js

@@ -1,6 +1,7 @@
 import { parseArgs } from 'node:util';
 import { GlossError, resolveCommits } from '../git.js';
 import { loadGloss } from '../loader.js';
+import { CONFIG_EDIT_NOTE } from '../signals.js';
 import { ratingIssues, tryAnalyze, whyText } from '../floor.js';
 import { attentionRank, impactRank } from '../attention.js';
 import { servesOf } from '../schema.js';
@@ -38,6 +39,8 @@ export function run(argv) {
     const an = tryAnalyze(gloss);
     if (an) {
         const issues = ratingIssues(a, an);
+        if (issues.configEdit)
+            add('config-edit', CONFIG_EDIT_NOTE);
         for (const u of issues.unrated)
             add('no-impact', `no impact rated${u.signal ? ` (floor ${u.floor}: ${whyText(u.why)})` : ''}`, { group: u.id });
         for (const b of issues.belowFloor)

package/dist/commands/review.js

@@ -3,7 +3,7 @@ import { plain } from '../plain.js';
 import { commitDiff, commitSubject, isWipSnapshot, resolveCommits } from '../git.js';
 import { parseDiff } from '../diff.js';
 import { refLabel, sliceText } from '../selection.js';
-import { loadGloss } from '../loader.js';
+import { loadGloss, loadGlossInRange, refusedWarning } from '../loader.js';
 import { NECESSITY_HELP, servesOf } from '../schema.js';
 export const usage = 'review [<commit> | <range>] [--material]   print a review prompt for a commit or a branch (pipe it to an agent, e.g. `| claude -p`); --material prints only the gloss and code, for other review prompts';
 // A fence longer than any backtick run in the content, so a markdown file in
@@ -20,11 +20,12 @@ const hunkLine = (h) => `- ${h.id} ${plain(h.oldFile && h.oldFile !== 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) {
+function commitMaterial(sha, gloss, refused) {
     if (!gloss) {
         return [
             `## Commit ${sha.slice(0, 10)}: ${plain(commitSubject(sha))}`,
-            'This commit has no gloss. Review its changes as unexplained.',
+            refused ? "This commit's gloss was refused (reason below), so it is not shown. Review its changes as unexplained." : 'This commit has no gloss. Review its changes as unexplained.',
+            ...(refused ? [`Reason: ${q(plain(refused).slice(0, 300))}`] : []),
             fenced('diff', parseDiff(commitDiff(sha)).map((h) => `# ${plain(h.file)}\n${h.text}`).join('\n')),
         ];
     }
@@ -69,7 +70,11 @@ function commitMaterial(sha, gloss) {
 export function run(argv) {
     const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { material: { type: 'boolean' } } });
     const { shas, merges, range } = resolveCommits(positionals[0] ?? 'HEAD');
-    const glosses = shas.map((sha) => loadGloss(sha));
+    // In a range a refused gloss is skipped with a warning; a single commit fails with the error.
+    const loaded = shas.map((sha) => (range ? loadGlossInRange(sha) : { gloss: loadGloss(sha), refused: undefined }));
+    loaded.forEach((l, i) => { if (l.refused)
+        console.error(refusedWarning(shas[i], l.refused)); });
+    const glosses = loaded.map((l) => l.gloss);
     if (!range && !glosses[0]) {
         console.error(`${shas[0].slice(0, 10)} has no gloss to review`);
         return 1;
@@ -82,7 +87,7 @@ export function run(argv) {
                 ? `\n\nMerge commits in the range are not included below. A merge can still carry conflict resolutions or edits of its own; check them with \`git show <sha>\`:\n\n${list(merges)}`
                 : ''));
     }
-    shas.forEach((sha, i) => material.push(...commitMaterial(sha, glosses[i])));
+    shas.forEach((sha, i) => material.push(...commitMaterial(sha, glosses[i], loaded[i].refused)));
     // Just the material, for a reviewer that brings its own instructions. Its
     // author text is quoted but not framed as untrusted; the caller must say so.
     if (values.material) {

package/dist/commands/reviews.js

@@ -2,11 +2,11 @@ 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, checkBy, checkDecision, isValidDecision, MAX_FINDINGS, MAX_REVIEW_LINE, decisionSummary, readDecisions, readReviews, reviewStatus, stamp, statusPhrase, verdictOf } from '../reviews.js';
-import { findingRefs, labelFindings, orderDecisions, refOf } from '../findings.js';
+import { addReviews, checkDecision, resolveBy, isValidDecision, MAX_FINDINGS, MAX_REVIEW_LINE, decisionSummary, readDecisions, readReviews, reviewStatus, stamp, statusPhrase, verdictOf } from '../reviews.js';
+import { findingClashes, findingRefs, labelFindings, orderDecisions, refOf } from '../findings.js';
 import { plain } from '../plain.js';
 import { page, style } from '../render.js';
-import { checkLength, parseBatch, readBounded, template } from '../batch.js';
+import { applyBatch, checkLength, prepareBatch, template } from '../batch.js';
 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\n  reviews <target> --decide-template <review-id>   print a JSON skeleton of the findings of a review to fill in\n  reviews <target> --decide <review-id> --decide-file <file|->   record every decision of the filled-in skeleton at once, or none; --stamp, --record and --decide are for tools';
 export function run(argv) {
     const { values, positionals } = parseArgs({
@@ -80,39 +80,30 @@ export function run(argv) {
     };
     const reportOf = (id, holders) => holders.flatMap(readReviews).find((r) => r.id === id);
     // A finding that starts with a ref names a finding of the report: say so when there is none (never refuse).
+    // The refs of a report are computed once, not once per entry.
+    const refsOfReport = new Map();
     const warnUnknownRef = (id, report, finding, hint = '') => {
         const ref = refOf(finding);
-        if (ref !== null && report && !findingRefs(report.findings).has(ref))
+        if (ref !== null && report && !(refsOfReport.get(report.findings) ?? refsOfReport.set(report.findings, findingRefs(report.findings)).get(report.findings)).has(ref))
             console.error(`git-gloss: review ${plain(id)} has no finding ${ref} (${hint}see the refs in \`git gloss reviews ${target}\`); recording it anyway`);
     };
     if (values['decide-template'] !== undefined) {
         const id = values['decide-template'];
         const report = reportOf(id, holdersOf(id));
+        const clash = findingClashes(report.findings);
+        if (clash.length)
+            console.error(`git-gloss: review ${plain(id)}: these refs are ambiguous, so the template cannot list every finding under its own: ${clash.join(', ')}; the findings are in \`git gloss reviews ${target}\``);
         console.log(JSON.stringify(template(id, report.findings), null, 2));
         return 0;
     }
     if (values['decide-file'] !== undefined) {
         const id = values.decide;
         // Everything is checked before the first write: one bad entry records nothing.
-        const batch = parseBatch(readBounded(values['decide-file']), id);
-        const holders = holdersOf(id);
-        const by = values.by !== undefined ? values.by.trim() : gitTry(['config', 'user.name'])?.trim() || 'unknown';
-        checkBy(by);
-        const at = new Date().toISOString();
-        const records = batch.entries.map((e, i) => {
-            const r = { decision: 1, review: id, at, by, finding: e.finding, outcome: e.outcome, ...(e.note ? { note: e.note } : {}) };
-            checkLength(r, `--decide-file: entry ${i + 1}`);
-            return r;
-        });
-        if (batch.complete)
-            records.push({ decision: 1, review: id, at, by, complete: true });
+        const { batch, holders, records } = prepareBatch(values['decide-file'], id, values.by, holdersOf);
         const report = reportOf(id, holders);
         batch.entries.forEach((e, i) => warnUnknownRef(id, report, e.finding, `entry ${i + 1}; `));
-        // One compare-and-swap write per commit, whatever the number of records.
-        for (const sha of holders)
-            addReviews(sha, records);
-        const n = batch.entries.length;
-        console.log(`recorded ${n} decision${n === 1 ? '' : 's'} on ${holders.length} commit${holders.length === 1 ? '' : 's'}${batch.complete ? ' and marked the review complete' : ''}`);
+        const { decisions: n, marked, written, skipped } = applyBatch(holders, records);
+        console.log(`recorded ${n} decision${n === 1 ? '' : 's'} on ${written} commit${written === 1 ? '' : 's'}${marked ? ' and marked the review complete' : ''}${skipped ? ` (${skipped} already recorded)` : ''}`);
         return 0;
     }
     if (values.decide !== undefined) {
@@ -125,8 +116,7 @@ export function run(argv) {
         else
             checkDecision(values);
         const holders = holdersOf(id);
-        const by = values.by !== undefined ? values.by.trim() : gitTry(['config', 'user.name'])?.trim() || 'unknown';
-        checkBy(by);
+        const by = resolveBy(values.by);
         const record = {
             decision: 1, review: id, at: new Date().toISOString(), by,
             ...(values.complete ? { complete: true } : {

package/dist/commands/show.js

@@ -1,7 +1,7 @@
 import { parseArgs } from 'node:util';
-import { commitSubject, gitTry, readNote, resolveCommits } from '../git.js';
+import { commitSubject, gitTry, readNote, resolveCommits, rethrowTimeout } from '../git.js';
 import { refLabel, sliceStats, sliceText } from '../selection.js';
-import { loadGloss } from '../loader.js';
+import { loadGloss, loadGlossInRange, refusedWarning } from '../loader.js';
 import { impactRank } from '../attention.js';
 import { showsImpact, tryAnalyze } from '../floor.js';
 import { IMPACT, NECESSITY, isImpact, isNecessity } from '../schema.js';
@@ -61,7 +61,8 @@ export function run(argv) {
                     const groups = readNote(c)?.annotation.groups.map((g) => g.id) ?? [];
                     return missing.every((id) => groups.includes(id));
                 }
-                catch {
+                catch (err) {
+                    rethrowTimeout(err);
                     return false;
                 }
             });
@@ -84,7 +85,11 @@ export function run(argv) {
         console.error('error: -g needs a single commit; pick one from the range, e.g. git gloss show <commit> -g <group>');
         return 2;
     }
-    const glosses = shas.map((sha) => loadGloss(sha));
+    const loaded = shas.map((sha) => loadGlossInRange(sha));
+    const glosses = loaded.map((l) => l.gloss);
+    const refused = loaded.filter((l) => l.refused).length;
+    loaded.forEach((l, i) => { if (l.refused)
+        console.error(refusedWarning(shas[i], l.refused)); });
     const glossed = glosses.filter(Boolean).length;
     const stale = glosses.filter((g) => g?.stale).length;
     // How many glossed commits had their gloss checked: an honesty review that
@@ -97,13 +102,14 @@ export function run(argv) {
             (glossed ? style(vetted === glossed ? 'green' : 'yellow', `, ${vetted} honesty-reviewed`) : '') +
             (flagged ? style('yellow', ` (${flagged} with issues)`) : '') +
             (stale ? style('red', ` (${stale} stale)`) : '') +
+            (refused ? style('red', ` (${refused} refused)`) : '') +
             (merges.length ? style('dim', `  (${merges.length} merge${merges.length === 1 ? '' : 's'} not shown)`) : ''),
     ];
     shas.forEach((sha, i) => {
         out.push('', style('dim', '─'.repeat(Math.min(termWidth(), 60))));
         const gloss = glosses[i];
         if (!gloss) {
-            out.push(`${style('yellow', sha.slice(0, 10))} ${style('bold', plain(commitSubject(sha)))}`, style('dim', 'no gloss for this commit'));
+            out.push(`${style('yellow', sha.slice(0, 10))} ${style('bold', plain(commitSubject(sha)))}`, style('dim', loaded[i].refused ? 'gloss refused (see the warning)' : 'no gloss for this commit'));
             return;
         }
         // An --only filter can leave a commit with nothing to show; say so and move on.

package/dist/commands/sync.js

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
-import { git, gitTry, GitError, NOTES_REF } from '../git.js';
+import { git, gitTry, GitError, gitCleanup, NETWORK_TIMEOUT, NOTES_REF, rethrowTimeout } from '../git.js';
 import { carryNew } from '../origins.js';
 import { REVIEWS_REF } from '../reviews.js';
 import { carry } from './carry.js';
@@ -22,7 +22,8 @@ function createdAt(blob) {
         const value = JSON.parse(git(['cat-file', 'blob', blob]))?.created_at;
         return typeof value === 'string' ? value : null;
     }
-    catch {
+    catch (err) {
+        rethrowTimeout(err);
         return null;
     }
 }
@@ -50,12 +51,34 @@ function shareable(remote, pushing) {
 // code (or an update-ref onto our own notes ref) touches it.
 function checkTracking(remote, ref, tracking) {
     if (gitTry(['rev-parse', '-q', '--verify', `${tracking}^{commit}`]) === null) {
-        gitTry(['update-ref', '-d', tracking]);
+        gitCleanup(['update-ref', '-d', tracking]);
         throw new GitError(`${remote}'s ${ref} is not a notes commit; ignoring it (nothing was changed here)`);
     }
 }
+// `init`'s refspec is a glob (refs/notes/gloss*), so a remote that once published
+// refs/notes/gloss/x leaves refs/notes/remotes/<remote>/gloss/x behind, and git
+// then cannot create refs/notes/remotes/<remote>/gloss once the remote has that
+// ref (a ref cannot be both a file and a directory): every fetch fails until
+// `git remote prune`. We are about to fetch the ref into `tracking`, so
+// whatever sits below it is stale and cannot be valid together with it. Only
+// that namespace is touched, in one batched update-ref.
+function clearBlockingTracking(tracking) {
+    const stale = (gitTry(['for-each-ref', '--format=%(refname)', `${tracking}/`]) ?? '').split('\n').filter((r) => r.startsWith(`${tracking}/`));
+    if (stale.length)
+        git(['update-ref', '--stdin'], stale.map((r) => `delete ${r}\n`).join(''));
+}
 function fetchTracking(remote, ref, tracking) {
-    git(['fetch', '-q', remote, `+${ref}:${tracking}`]);
+    try {
+        clearBlockingTracking(tracking);
+        git(['fetch', '-q', remote, `+${ref}:${tracking}`], undefined, {}, NETWORK_TIMEOUT);
+    }
+    catch (err) {
+        rethrowTimeout(err);
+        if (err instanceof GitError && /cannot lock ref|Unable to create .*\.lock|some local refs could not be updated/.test(err.message)) {
+            throw new GitError(`${err.message}\n  a stale remote-tracking ref may be in the way; try: git remote prune ${remote}`);
+        }
+        throw err;
+    }
     checkTracking(remote, ref, tracking);
 }
 const PUSH_REF = 'refs/notes/gloss-sync-tmp';
@@ -63,7 +86,7 @@ const PUSH_REF = 'refs/notes/gloss-sync-tmp';
 // someone else's push and the round should be retried.
 function round(remote, pushing, carried) {
     const tracking = `refs/notes/remotes/${remote}/gloss`;
-    const remoteHas = gitTry(['ls-remote', '--exit-code', remote, NOTES_REF]) !== null;
+    const remoteHas = gitTry(['ls-remote', '--exit-code', remote, NOTES_REF], undefined, NETWORK_TIMEOUT) !== null;
     if (remoteHas)
         fetchTracking(remote, NOTES_REF, tracking);
     const local = noteList(NOTES_REF);
@@ -142,13 +165,13 @@ function round(remote, pushing, carried) {
         if (remoteHas)
             git(['update-ref', PUSH_REF, tracking]);
         else
-            gitTry(['update-ref', '-d', PUSH_REF]);
+            gitCleanup(['update-ref', '-d', PUSH_REF]);
         for (const [object, blob] of toPush)
             git(['notes', '--ref', PUSH_REF, 'add', '-f', '-C', blob, object]);
         try {
             // --no-verify: don't run the pre-push hook for the notes push itself,
             // which would call sync again.
-            git(['push', '-q', '--no-verify', remote, `${PUSH_REF}:${NOTES_REF}`]);
+            git(['push', '-q', '--no-verify', remote, `${PUSH_REF}:${NOTES_REF}`], undefined, {}, NETWORK_TIMEOUT);
         }
         catch (err) {
             if (/\(fetch first\)|non-fast-forward/.test(err.message))
@@ -159,7 +182,7 @@ function round(remote, pushing, carried) {
         git(['notes', '--ref', NOTES_REF, 'merge', '-q', '-s', 'ours', PUSH_REF]);
     }
     finally {
-        gitTry(['update-ref', '-d', PUSH_REF]);
+        gitCleanup(['update-ref', '-d', PUSH_REF]);
     }
     return { fetched, pushed: toPush.length, withheld, conflicts };
 }
@@ -169,7 +192,7 @@ const REVIEWS_PUSH_REF = 'refs/notes/gloss-reviews-sync-tmp';
 // commits the remote may see are sent. Returns null if the push lost a race.
 function syncReviews(remote, pushing) {
     const tracking = `refs/notes/remotes/${remote}/gloss-reviews`;
-    const remoteHas = gitTry(['ls-remote', '--exit-code', remote, REVIEWS_REF]) !== null;
+    const remoteHas = gitTry(['ls-remote', '--exit-code', remote, REVIEWS_REF], undefined, NETWORK_TIMEOUT) !== null;
     if (remoteHas)
         fetchTracking(remote, REVIEWS_REF, tracking);
     const before = noteList(REVIEWS_REF);
@@ -190,11 +213,11 @@ function syncReviews(remote, pushing) {
         if (remoteHas)
             git(['update-ref', REVIEWS_PUSH_REF, tracking]);
         else
-            gitTry(['update-ref', '-d', REVIEWS_PUSH_REF]);
+            gitCleanup(['update-ref', '-d', REVIEWS_PUSH_REF]);
         for (const [object, blob] of toPush)
             git(['notes', '--ref', REVIEWS_PUSH_REF, 'add', '-f', '-C', blob, object]);
         try {
-            git(['push', '-q', '--no-verify', remote, `${REVIEWS_PUSH_REF}:${REVIEWS_REF}`]);
+            git(['push', '-q', '--no-verify', remote, `${REVIEWS_PUSH_REF}:${REVIEWS_REF}`], undefined, {}, NETWORK_TIMEOUT);
         }
         catch (err) {
             if (/\(fetch first\)|non-fast-forward/.test(err.message))
@@ -204,7 +227,7 @@ function syncReviews(remote, pushing) {
         git(['notes', '--ref', REVIEWS_REF, 'merge', '-q', '-s', 'cat_sort_uniq', REVIEWS_PUSH_REF]);
     }
     finally {
-        gitTry(['update-ref', '-d', REVIEWS_PUSH_REF]);
+        gitCleanup(['update-ref', '-d', REVIEWS_PUSH_REF]);
     }
     return { fetched, pushed: toPush.length };
 }

package/dist/commands/versions.js

@@ -1,6 +1,9 @@
 import { parseArgs } from 'node:util';
-import { commitDiff, git, gitTry, GlossError, NOTES_REF, resolveCommit, WIP_NOTES_REF, WIP_REF, writeNote } from '../git.js';
+import { commitDiff, git, GitError, gitTry, GlossError, noteSizeProblem, NOTES_REF, parseNote, resolveCommit, WIP_NOTES_REF, WIP_REF, rethrowTimeout, writeNote } from '../git.js';
+import { plain } from '../plain.js';
 import { location, parseDiff } from '../diff.js';
+import { loadGlossOf } from '../loader.js';
+import { carriedErrors } from '../validate.js';
 import { mergeGlosses } from '../merge.js';
 import { noteFormat } from '../schema.js';
 import { refLabel } from '../selection.js';
@@ -51,18 +54,29 @@ function history(ref, only) {
     flush();
     return out;
 }
+// How many group ids the listing names for one version.
+const MAX_LISTED = 20;
+// Everything a version of the history prints comes from a note that may have been
+// pushed by anyone: it is size-checked before it is read, cleaned, and bounded.
 function summary(blob) {
+    const size = Number(gitTry(['cat-file', '-s', blob]));
+    const big = noteSizeProblem(size);
+    if (big)
+        return `(not read: ${big})`;
     try {
         const note = JSON.parse(git(['cat-file', 'blob', blob]));
         const a = note.annotation;
-        const from = note.sources ? `carried from ${note.sources.map((s) => s.slice(0, 7)).join(', ')}; ` : '';
-        return `${from}${a.groups.length} group${a.groups.length === 1 ? '' : 's'}: ${a.groups.map((g) => g.id).join(', ')}\n       task: ${JSON.stringify(a.task)}`;
+        const from = Array.isArray(note.sources) ? `carried from ${note.sources.slice(0, 5).map((s) => plain(String(s)).slice(0, 7)).join(', ')}; ` : '';
+        const ids = a.groups.slice(0, MAX_LISTED).map((g) => plain(String(g.id)).slice(0, 40));
+        const n = a.groups.length;
+        return `${from}${n} group${n === 1 ? '' : 's'}: ${ids.join(', ')}${n > MAX_LISTED ? `, and ${n - MAX_LISTED} more` : ''}\n       task: ${JSON.stringify(plain(String(a.task)).slice(0, 200))}`;
     }
-    catch {
+    catch (err) {
+        rethrowTimeout(err);
         return '(not a readable gloss: joined notes from a squash, or not JSON)';
     }
 }
-const when = (iso) => iso.slice(0, 16).replace('T', ' ');
+const when = (iso) => plain(iso).slice(0, 16).replace('T', ' ');
 export function run(argv) {
     const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: { show: { type: 'string' }, restore: { type: 'string' } } });
     const wip = positionals[0] === 'wip';
@@ -84,12 +98,37 @@ export function run(argv) {
         return { n, v: v };
     };
     if (values.show !== undefined) {
-        process.stdout.write(git(['cat-file', 'blob', pick(values.show, '--show').v.blob]));
+        // Cleaned like everything else printed (control characters, escape sequences, bidi and
+        // zero-width characters become spaces), so not byte-identical to the stored blob.
+        process.stdout.write(plain(git(['cat-file', 'blob', pick(values.show, '--show').v.blob]), true));
         return 0;
     }
     if (values.restore !== undefined) {
         const { n, v } = pick(values.restore, '--restore');
+        // Only a gloss that readers accept is brought back (a restore must not plant what they refuse).
+        const text = git(['cat-file', 'blob', v.blob]);
+        let note;
+        try {
+            note = parseNote(text, `version ${n}`);
+        }
+        catch (err) {
+            if (!(err instanceof GlossError) || err instanceof GitError)
+                throw err;
+            throw new GlossError(`${err.message.replace(/; (replace it|re-gloss it|upgrade).*$/, '')}, so it is not restored (read it with --show ${n})`);
+        }
+        // What readers refuse for the commit it would go on (too many claimed lines).
+        const checkOn = (target) => {
+            try {
+                loadGlossOf(target, note);
+            }
+            catch (err) {
+                if (!(err instanceof GlossError) || err instanceof GitError)
+                    throw err;
+                throw new GlossError(`version ${n} would be refused on ${target.slice(0, 7)}: ${err.message.replace(/^the gloss on \S+ is refused: /, '')} (not restored; read it with --show ${n})`);
+            }
+        };
         if (!wip) {
+            checkOn(sha);
             git(['notes', '--ref', ref, 'add', '-f', '-C', v.blob, sha]);
             console.log(`restored version ${n} as the gloss of ${label}`);
             return 0;
@@ -100,8 +139,8 @@ export function run(argv) {
         const onto = gitTry(['rev-parse', '-q', '--verify', WIP_REF])?.trim();
         if (!onto)
             throw new GlossError('there is no snapshot of uncommitted work to restore onto; run git gloss hunks wip first');
-        const note = JSON.parse(git(['cat-file', 'blob', v.blob]));
         if (v.object === onto || gitTry(['cat-file', '-e', `${v.object}^{commit}`]) === null) {
+            checkOn(onto);
             git(['notes', '--ref', ref, 'add', '-f', '-C', v.blob, onto]);
             console.log(`restored version ${n} onto the wip snapshot ${onto.slice(0, 7)}` +
                 (v.object === onto ? '' : `; its snapshot ${v.object.slice(0, 7)} is gone, so hunk references may not match: check with git gloss show wip`));
@@ -109,6 +148,11 @@ export function run(argv) {
         }
         const current = parseDiff(commitDiff(onto));
         const merged = mergeGlosses([{ sha: v.object, note, hunks: parseDiff(commitDiff(v.object)) }], current);
+        if (merged.annotation) {
+            const errors = carriedErrors(merged.annotation, current);
+            if (errors.length)
+                throw new GlossError(`version ${n} doesn't fit the uncommitted work: ${errors.join('; ')} (not restored)`);
+        }
         if (!merged.annotation)
             throw new GlossError(`none of version ${n}'s glossed changes are in the uncommitted work any more; read it with --show ${n}`);
         writeNote(onto, {
@@ -122,7 +166,7 @@ export function run(argv) {
     }
     console.log(`glosses of ${label}, newest first:`);
     versions.forEach((v, i) => {
-        const head = `${String(i + 1).padStart(3)}  ${when(v.at)}  ${v.how}${wip ? `  (snapshot ${v.object.slice(0, 7)})` : ''}`;
+        const head = `${String(i + 1).padStart(3)}  ${when(v.at)}  ${plain(v.how)}${wip ? `  (snapshot ${v.object.slice(0, 7)})` : ''}`;
         console.log(`${head}${i === 0 && v.blob && !wip ? '  [current]' : ''}`);
         console.log(`       ${v.blob ? summary(v.blob) : 'removed'}`);
     });

package/dist/commands/why.js

@@ -1,7 +1,7 @@
 import { plain } from '../plain.js';
 import { parseArgs } from 'node:util';
 import { blameRange, commitSubject, lineHistory } from '../git.js';
-import { loadGloss } from '../loader.js';
+import { loadGlossInRange, refusedWarning } from '../loader.js';
 import { servesOf } from '../schema.js';
 import { field, groupHeader, style } from '../render.js';
 import { bodyLines, formatRanges } from '../selection.js';
@@ -10,8 +10,13 @@ export const usage = 'why <file>:<line>[-<end>] [--history] [--rev <commit>] [--
 // refer to it; each load diffs the commit.
 const glossCache = new Map();
 function glossFor(commit) {
-    if (!glossCache.has(commit))
-        glossCache.set(commit, loadGloss(commit));
+    if (!glossCache.has(commit)) {
+        // A refused gloss (hostile or broken) is skipped with a warning, once, not a failed command.
+        const { gloss, refused } = loadGlossInRange(commit);
+        if (refused)
+            console.error(refusedWarning(commit, refused));
+        glossCache.set(commit, gloss);
+    }
     return glossCache.get(commit);
 }
 // Groups in a gloss that own `line` of `file` on the new side of the commit's

package/dist/config.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { git, GitError, GlossError, gitTry } from './git.js';
+import { git, GitError, GlossError, gitTry, rethrowTimeout } from './git.js';
 import { globToRegExp } from './glob.js';
 // Settings for the computed signals, in three layers (later wins for scalars,
 // repo config extends the lists of the one before):
@@ -137,10 +137,12 @@ function gitInt(key) {
 }
 // Git failing (a broken repo, an unreadable object, no permission) is not the
 // same as "no base" or "no file": the repo's own, perhaps stricter, config
-// would silently not apply. It is not fatal either (the built-in defaults
-// still give a floor, and refusing to rate anything would make every command
-// fail in a damaged repo), so it is warned about on stderr, once per message,
-// and the defaults are used.
+// would silently not apply, and a floor computed from the defaults alone could
+// be lower than the real one. So the ratings are unverifiable: loadConfig
+// throws a ConfigError, which `add` and `signals` report as an error, and
+// `show`, `lint`, `html` and `hunks` meet through withSignals (the signals are
+// unavailable, `lint` says "incomplete"). A broken base candidate is only
+// warned about (once per message) while a later one still works.
 const warned = new Set();
 function warnOnce(msg) {
     if (warned.has(msg))
@@ -171,8 +173,14 @@ function gitAnswer(args) {
 // is always a `sensitive` path.
 function trustedRef() {
     // No commits yet: no base, and nothing failed.
-    if (gitAnswer(['rev-parse', '--verify', '-q', 'HEAD']) === null)
-        return noBase();
+    try {
+        if (gitAnswer(['rev-parse', '--verify', '-q', 'HEAD']) === null)
+            return noBase();
+    }
+    catch (err) {
+        rethrowTimeout(err);
+        throw new ConfigError(`git failed finding HEAD (${err.message}), so ${CONFIG_FILE} cannot be read and the ratings cannot be verified`);
+    }
     let failed = false;
     // Full ref names, so a tag called "main" cannot stand in for the branch.
     for (const b of ['refs/remotes/origin/main', 'refs/heads/main', 'refs/remotes/origin/master', 'refs/heads/master']) {
@@ -184,20 +192,23 @@ function trustedRef() {
                 return mb;
         }
         catch (err) {
+            rethrowTimeout(err);
             // A broken candidate does not hide the ones after it.
             failed = true;
             warnOnce(`git failed finding the base branch with ${b} (${err.message}); trying the next candidate`);
         }
     }
     // Some candidate failed: git's warning above is the reason, not an absent branch.
-    return failed ? (console.error(`warning: no working base branch, so ${CONFIG_FILE} is not read; using the built-in defaults`), null) : noBase();
+    if (failed)
+        throw new ConfigError(`git failed on every base branch candidate, so ${CONFIG_FILE} cannot be read and the ratings cannot be verified (the repo's own patterns would not apply); fix the repository, or see the warnings above`);
+    return noBase();
 }
 function noBase() {
     console.error('warning: no base branch (origin/main, main, origin/master, master) found, so .gloss/config.json is not read; using the built-in defaults');
     return null;
 }
 // The config file at `ref`: null when the file is not there (the usual case),
-// a warning and null when git could not tell or could not read it. Presence
+// a ConfigError when git could not tell or could not read it. Presence
 // is asked of ls-tree (empty output: absent), not read off an error message.
 function configAt(ref) {
     try {
@@ -206,8 +217,8 @@ function configAt(ref) {
         return git(['show', `${ref}:${CONFIG_FILE}`]);
     }
     catch (err) {
-        warnOnce(`${CONFIG_FILE} could not be read from the base branch (${err.message}); using the built-in defaults, so the repo's own patterns do not apply`);
-        return null;
+        rethrowTimeout(err);
+        throw new ConfigError(`${CONFIG_FILE} could not be read from the base branch (${err.message}); the repo's own patterns cannot be applied, so the ratings cannot be verified`);
     }
 }
 function readRepoConfig() {