caracms 0.8.0 → 0.8.2

package/src/live/git.ts

@@ -30,6 +30,40 @@
  * new, deleted or changed (`changeOf`), and a file made and removed again since the
  * last Publish isn't waiting at all.
  *
+ * **Losing `drafts`** (caracms-cloud adversarial review, finding 5). Every head of
+ * `drafts` this server makes or finds at start is recorded in Redis (`drafts:head`, no
+ * expiry). A start that finds `drafts` gone (a branch tidy-up, a stale-branch bot) makes
+ * it again from that commit while GitHub still has it; only when it can't does it fall
+ * back to `main`, with a loud log line and a note every editor sees for a week
+ * (`drafts:lost`, `draftsLost()`), cleared by the next Publish.
+ *
+ * **`main` rolled back by a force-push** (caracms-cloud adversarial review, force-push
+ * note). A developer resetting `main` to an older commit and force-pushing leaves `drafts`
+ * holding what was rolled away, so it all reads as waiting and the next Publish puts it
+ * back. Each check asks whether `main` still has the last Publish's commit (one compare per
+ * pair of commits): a push on top, a merge or a `git revert` all keep it, so only history
+ * being rewritten finds it gone. Then a log line, and a note every editor sees
+ * (`main:rolled-back`, `mainRolledBack()`). Nothing works out which waiting changes were
+ * rolled back. The note goes with the next Publish, once nothing is waiting (everything
+ * discarded: it stays gone for that rollback), or when `main` has the commit again.
+ *
+ * **Commits that keep failing** (finding 4): `commitTrouble()` says so once
+ * `COMMIT_TROUBLE_AFTER` draft commits in a row have failed, until one succeeds; the
+ * status poll turns it into the save bar's warning. In-process: the sweep's ticks on this
+ * server are what fail, and a restart learns it again within a few ticks.
+ *
+ * **Holding a document back** (caracms-cloud adversarial review, finding 15). Publish
+ * checks every waiting document as the reader will (document-problems.ts): one the reader
+ * would refuse (no title) isn't published. `main` gets `drafts`' tree with those files as
+ * `main` has them (a new one left out), and `drafts` gets one more commit on top, headed
+ * `Held back:`, putting them back as they were, so they're still waiting, with who changed
+ * them. A moved document's old file is held with its new one. Nothing publishable: nothing
+ * moves (`held-back`).
+ *
+ * **Discarding a document's changes** (`restoreDrafts`): its files are committed to
+ * `drafts` as `main` has them now (a file `main` lacks is removed), headed `Discarded:`,
+ * so what's waiting no longer lists them. One commit, compare-and-swap like any other.
+ *
  * In-process state here is caches of git and GitHub, and throttles; none of it is
  * the only record of anything.
  */
@@ -45,7 +79,8 @@ import { MissingBranchError, StaleHeadError, type Branch, type CommitSummary, ty
 import { HttpError } from './github.ts';
 import { runningCommitFrom } from './mode.ts';
 import { mergeFile } from './merge.ts';
-import { draftMessage, mergeMessage, parseMessage, publishMessage, type Person } from './messages.ts';
+import { discardMessage, draftMessage, heldMessage, mergeMessage, parseMessage, publishMessage, type Person } from './messages.ts';
+import { textProblems } from '../document-problems.ts';
 import type { RedisClient } from './redis.ts';
 import { landed, StatusCache } from './status-cache.ts';
 import { DEFAULT_TIMINGS, type LiveTimings } from './timings.ts';
@@ -79,10 +114,22 @@ export type CheckResult =
 	| { kind: 'fast-forward'; to: string; fromMain: string[] }
 	| { kind: 'merged'; commit: string; fromMain: string[]; keptDraft: string[] };
 
+/** A waiting document Publish left waiting (finding 15): its file, its title and why ("its title is empty"). */
+export interface HeldBack {
+	file: string;
+	title: string;
+	reason: string;
+}
+
 export type PublishResult =
 	| { kind: 'nothing-waiting' }
-	/** `fileTitles`: each of `record.files`' own title, in that order (`record.titles` is the headline's items). */
-	| { kind: 'published'; record: PublishRecord; attempts: number; fileTitles: string[] }
+	/**
+	 * `fileTitles`: each of `record.files`' own title, in that order (`record.titles` is the headline's items).
+	 * `held`: the documents left waiting (finding 15), none of them in `record.files`.
+	 */
+	| { kind: 'published'; record: PublishRecord; attempts: number; fileTitles: string[]; held: HeldBack[] }
+	/** Finding 15: everything waiting would break the reader, so nothing moved. */
+	| { kind: 'held-back'; held: HeldBack[] }
 	/** A Publish was already running; this press joined it. */
 	| { kind: 'joined'; record: PublishRecord | null };
 
@@ -140,6 +187,35 @@ export interface LiveGitOptions {
 	statusCache?: StatusCache;
 }
 
+/**
+ * Draft commits failing in a row before the editor is told (finding 4): three of the
+ * sweep's 30-second ticks, about a minute of failing, so one GitHub blip never shows.
+ */
+export const COMMIT_TROUBLE_AFTER = 3;
+
+/** Draft commits failing in a row (finding 4): since when, and how many. */
+export interface CommitTrouble {
+	since: number;
+	failures: number;
+}
+
+/** `drafts` was made again from `main` and what it held is gone (finding 5): its last recorded head (null: none was), and when. */
+export interface DraftsLost {
+	commit: string | null;
+	at: string;
+}
+
+/**
+ * `main` no longer has the last Publish's commit (force-push note): that commit, `main`'s head
+ * when it was found, and when. `cleared`: nothing was waiting since, so the note is done with.
+ */
+export interface MainRolledBack {
+	publish: string;
+	main: string;
+	at: string;
+	cleared?: boolean;
+}
+
 /** The site file that holds Site Settings, relative to the site (Decision 15). Defined in config.ts (M5a: the reserved `settings` collection). */
 export { SITE_SETTINGS_FILE };
 
@@ -150,6 +226,17 @@ const RAILWAY_API = 'https://backboard.railway.com/graphql/v2';
 
 const posix = (p: string) => p.split(sep).join('/');
 
+/** The rollback note as kept in Redis; null when there's none or it doesn't read. */
+function parseRolledBack(raw: string | null): MainRolledBack | null {
+	if (!raw) return null;
+	try {
+		const v = JSON.parse(raw) as MainRolledBack;
+		return typeof v.publish === 'string' && typeof v.main === 'string' ? v : null;
+	} catch {
+		return null;
+	}
+}
+
 /** What `drafts` holds beyond `main`: from one compare, extended by this server's own commits. */
 interface SinceMain {
 	main: string;
@@ -204,6 +291,21 @@ export class LiveGit {
 	private deploymentsDenied = false;
 	/** A deleted file's title (M5a): the waiting list's name for it once `drafts` has no copy. Learned when this process deleted it, else from `main`'s copy at a check (`learnDeletedTitles`), so a restart keeps it. */
 	private deletedTitles = new Map<string, string>();
+	/** Finding 5: the `drafts` head last written to Redis from here, so the same one isn't written twice. */
+	private recordedHead: string | null = null;
+	/** Finding 5: `drafts` was made again from `main` (read at start; a Publish clears it). */
+	private lost: DraftsLost | null = null;
+	/** Force-push note: `main` lost the last Publish's commit (read at each check; a Publish clears it). */
+	private rolledBack: MainRolledBack | null = null;
+	/** Force-push note: the last (publish commit, `main`) pair checked, and an unknown commit already logged. */
+	private rollbackPair: string | null = null;
+	private rollbackUnknown: string | null = null;
+	/** Its own cache, not `includesCache`: that one reads a commit GitHub lacks as "not included". */
+	private onMainCache = new Map<string, boolean>();
+	/** Finding 4: draft commits failing in a row; null after a success. */
+	private failing: CommitTrouble | null = null;
+	/** Finding 6: a publish whose refs moved but whose record couldn't be written to Redis. */
+	private unkeptRecord: PublishRecord | null = null;
 
 	constructor(options: LiveGitOptions) {
 		this.backend = options.backend;
@@ -270,10 +372,62 @@ export class LiveGit {
 		return this.key('publish:last');
 	}
 
+	/** Finding 5: the newest head of `drafts` this server made or found, and the note left when it was lost. */
+	get draftsHeadKey(): string {
+		return this.key('drafts:head');
+	}
+	get draftsLostKey(): string {
+		return this.key('drafts:lost');
+	}
+
+	/** Force-push note: `main` was found without the last Publish's commit. */
+	get mainRolledBackKey(): string {
+		return this.key('main:rolled-back');
+	}
+
 	private async setPublishRecord(record: PublishRecord): Promise<void> {
 		const raw = JSON.stringify(record);
 		await landed(this.statusCache, this.publishRecordKey, () => this.redis.set(this.publishRecordKey, raw));
 		this.statusCache.string(this.publishRecordKey, raw);
+		this.unkeptRecord = null;
+	}
+
+	/**
+	 * Finding 6: the newest publish as the status poll read it, unless this server made a
+	 * newer one whose record Redis didn't take: that one.
+	 */
+	publishRecordOr(record: PublishRecord | null): PublishRecord | null {
+		const unkept = this.unkeptRecord;
+		return unkept && (!record || record.at < unkept.at) ? unkept : record;
+	}
+
+	/**
+	 * Finding 5: record `drafts`' head in Redis (no expiry), so a start that finds the
+	 * branch deleted can make it again from here. Never fails what it follows.
+	 */
+	private async recordDraftsHead(commit: string): Promise<void> {
+		if (this.recordedHead === commit) return;
+		try {
+			await this.redis.set(this.draftsHeadKey, commit);
+			this.recordedHead = commit;
+		} catch (error) {
+			this.log(`recording drafts' head (${commit.slice(0, 7)}): ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+
+	/** Finding 5: `drafts` was made again from `main` at a start, losing what it held (for a week, or until the next Publish). */
+	draftsLost(): DraftsLost | null {
+		return this.lost;
+	}
+
+	/** Force-push note: `main` was rolled back past the last Publish, and something is still waiting. */
+	mainRolledBack(): MainRolledBack | null {
+		return this.rolledBack && !this.rolledBack.cleared ? this.rolledBack : null;
+	}
+
+	/** Finding 4: draft commits have failed `COMMIT_TROUBLE_AFTER` times in a row or more, and none has succeeded since. */
+	commitTrouble(): CommitTrouble | null {
+		return this.failing && this.failing.failures >= COMMIT_TROUBLE_AFTER ? this.failing : null;
 	}
 
 	/** Run `fn` alone among this server's git operations, so the copy is never changed by two at once. */
@@ -291,6 +445,13 @@ export class LiveGit {
 	 * can run it once `commitPending` is in place, Decision 8).
 	 */
 	async start(options: { check?: boolean } = {}): Promise<void> {
+		// Finding 5: a note left by an earlier start that lost `drafts` (it expires after a week).
+		try {
+			const raw = await this.redis.get(this.draftsLostKey);
+			this.lost = raw ? (JSON.parse(raw) as DraftsLost) : null;
+		} catch (error) {
+			this.log(`reading the lost-drafts note: ${error instanceof Error ? error.message : String(error)}`);
+		}
 		await this.backend.tracker.within('start', () =>
 			this.exclusive(async () => {
 				let heads: Heads;
@@ -298,19 +459,69 @@ export class LiveGit {
 					heads = await this.backend.readHeads();
 				} catch (error) {
 					if (!(error instanceof MissingBranchError) || error.branch !== 'drafts') throw error;
-					const main = await this.mainOnly();
-					this.log(`no drafts branch yet: creating it from main (${main.slice(0, 7)})`);
-					await this.backend.createBranch('drafts', main).catch((e: unknown) => {
-						if (!(e instanceof HttpError && e.status === 422)) throw e; // another server made it first
-					});
-					heads = await this.backend.readHeads();
+					heads = await this.remakeDrafts();
 				}
 				await this.download(heads.drafts);
+				await this.recordDraftsHead(heads.drafts.commit);
 			}),
 		);
 		if (options.check !== false) await this.check({ force: true });
 	}
 
+	/**
+	 * `drafts` is missing (finding 5): made again from its last recorded head when GitHub
+	 * still has that commit, so nothing unpublished is lost. Otherwise from `main`, as on a
+	 * site's first start; with a recorded head, or a publish on record (so it isn't a first
+	 * start), that loses every change saved since the last Publish: a loud log line, and the
+	 * editor's note (`drafts:lost`). Redis out: this start fails rather than make `drafts`
+	 * from `main` and lose what the next start could put back.
+	 */
+	private async remakeDrafts(): Promise<Heads> {
+		const main = await this.mainOnly();
+		const recorded = await this.redis.get(this.draftsHeadKey);
+		if (recorded) {
+			const heads = await this.createDrafts(recorded);
+			if (heads) {
+				this.log(`the drafts branch was missing: made it again from its last recorded head (${recorded}), so nothing unpublished was lost`);
+				return heads;
+			}
+		}
+		const published = recorded === null ? (await this.lastPublish()) !== null : true;
+		const heads = await this.createDrafts(main);
+		if (!heads) throw new Error(`caracms: couldn't make the drafts branch from main (${main.slice(0, 7)}).`);
+		if (!published) {
+			this.log(`no drafts branch yet: created it from main (${main.slice(0, 7)})`);
+			return heads;
+		}
+		this.log(
+			recorded
+				? `UNPUBLISHED CHANGES LOST: the drafts branch was missing on GitHub and its last recorded head (${recorded}) isn't there any more, so drafts was made again from main (${main.slice(0, 7)}). Every change saved since the last Publish, up to that commit, is gone from the editor.`
+				: `UNPUBLISHED CHANGES LOST: the drafts branch was missing on GitHub and no head of it was recorded, so drafts was made again from main (${main.slice(0, 7)}). Any change saved since the last Publish is gone from the editor.`,
+		);
+		this.lost = { commit: recorded, at: new Date(this.now()).toISOString() };
+		await this.redis.set(this.draftsLostKey, JSON.stringify(this.lost), { px: this.timings.autosaveTtlMs }).catch((error: unknown) => {
+			this.log(`keeping the lost-drafts note: ${error instanceof Error ? error.message : String(error)}`);
+		});
+		return heads;
+	}
+
+	/** Make `drafts` at `commit`; null when GitHub doesn't have that commit. Another server making it first is a success. */
+	private async createDrafts(commit: string): Promise<Heads | null> {
+		try {
+			await this.backend.createBranch('drafts', commit);
+		} catch (error) {
+			const heads = await this.backend.readHeads().catch((e: unknown) => {
+				if (e instanceof MissingBranchError && e.branch === 'drafts') return null;
+				throw e;
+			});
+			if (heads) return heads; // another server made it first
+			// GitHub answers 422 for a sha it doesn't have (the memory backend, 404). Anything else fails the start.
+			if (error instanceof HttpError && (error.status === 422 || error.status === 404)) return null;
+			throw error;
+		}
+		return this.backend.readHeads();
+	}
+
 	/** `main`'s head when `drafts` is missing (readHeads throws then). */
 	private async mainOnly(): Promise<string> {
 		// listCommits reads main alone; its first entry is the head.
@@ -379,6 +590,20 @@ export class LiveGit {
 	 * and merges again.
 	 */
 	async commitDrafts(entries: DraftEntry[]): Promise<DraftCommitResult> {
+		// Finding 4: count the failures in a row (the save bar's warning), and record the new head.
+		try {
+			const r = await this.commitDraftsOnce(entries);
+			this.failing = null;
+			if (r.commit) await this.recordDraftsHead(r.commit);
+			return r;
+		} catch (error) {
+			this.failing = { since: this.failing?.since ?? this.now(), failures: (this.failing?.failures ?? 0) + 1 };
+			if (this.failing.failures === COMMIT_TROUBLE_AFTER) this.log(`draft commits have failed ${COMMIT_TROUBLE_AFTER} times in a row: the editor now says they aren't reaching GitHub`);
+			throw error;
+		}
+	}
+
+	private async commitDraftsOnce(entries: DraftEntry[]): Promise<DraftCommitResult> {
 		return this.backend.tracker.within('draft', () =>
 			this.exclusive(async () => {
 				for (let attempt = 1; ; attempt++) {
@@ -448,6 +673,80 @@ export class LiveGit {
 		);
 	}
 
+	// ── Discard changes ─────────────────────────────────────────────────────────
+
+	/** These files as `main` has them now (null: it hasn't), in one read of the heads and one of the files. */
+	async readMain(files: readonly string[]): Promise<Map<string, string | null>> {
+		if (files.length === 0) return new Map();
+		const heads = await this.backend.readHeads();
+		const read = await this.backend.readFiles(files.map((f) => ({ commit: heads.main.commit, path: this.toRepo(f) })));
+		return new Map(files.map((f, i) => [f, read[i] ?? null]));
+	}
+
+	/**
+	 * Put these files on `drafts` back to what `main` has now (removed where `main` has
+	 * none), in one commit headed `Discarded: <titles> — by <person>`. Nothing to change:
+	 * no commit. The files leave what's waiting (`since`). A lost race refreshes the copy and
+	 * goes again. Returns the commit (null when `drafts` already matched) and each file's
+	 * text as it now reads (null: gone).
+	 */
+	async restoreDrafts(files: readonly string[], titles: readonly string[], by: Person): Promise<{ commit: string | null; texts: Map<string, string | null> }> {
+		const result = await this.backend.tracker.within('draft', () =>
+			this.exclusive(async () => {
+				for (let attempt = 1; ; attempt++) {
+					const heads = await this.reread();
+					const head = this.head();
+					const read = await this.backend.readFiles(files.map((f) => ({ commit: heads.main.commit, path: this.toRepo(f) })));
+					const texts = new Map(files.map((f, i) => [f, read[i] ?? null] as [string, string | null]));
+					const changed = [...texts].filter(([file, text]) => this.read(file) !== text);
+					const settle = (commit: string) => {
+						// Every one of them matches main now: none is waiting. Only while the compare is of this main.
+						if (this.since && this.since.main === heads.main.commit && this.since.drafts === commit) {
+							for (const file of files) {
+								this.since.files.delete(this.toRepo(file));
+								this.since.absent.delete(this.toRepo(file));
+							}
+						} else this.since = null;
+					};
+					if (changed.length === 0) {
+						settle(head.commit);
+						return { commit: null, texts };
+					}
+					try {
+						const removed = changed.filter(([, text]) => text === null).map(([f]) => this.toRepo(f));
+						const writes = changed.filter(([, text]) => text !== null).map(([file, contents]) => ({ path: this.toRepo(file), contents: contents! }));
+						const message = discardMessage([...titles], [...files], by);
+						const [headline, ...body] = message.split('\n');
+						const next = await this.backend.commitOnBranch('drafts', head.commit, writes, removed, headline!, body.join('\n').replace(/^\n/, ''));
+						for (const [file, text] of changed) {
+							if (text === null) this.copyFiles.delete(file);
+							else this.copyFiles.set(file, text);
+						}
+						this.copyHead = next;
+						if (this.since?.drafts === head.commit) {
+							this.since.drafts = next.commit;
+							this.since.commits.push({ sha: next.commit, parents: [head.commit], message, date: new Date(this.now()).toISOString() });
+						}
+						settle(next.commit);
+						this.historyCache = null;
+						this.log(`discarded ${next.commit.slice(0, 7)}: ${files.join(', ')}`);
+						return { commit: next.commit, texts };
+					} catch (error) {
+						const now = await this.backend.readHeads().catch(() => null);
+						const moved = now !== null && now.drafts.commit !== head.commit;
+						if (!(error instanceof StaleHeadError) && !moved) throw error;
+						if (attempt >= MAX_ATTEMPTS) throw new Error(`caracms: drafts kept moving; gave up discarding after ${attempt} tries.`);
+						this.log('discard: drafts moved under us; refreshing the copy and trying again');
+					}
+				}
+			}),
+		);
+		if (result.commit) await this.recordDraftsHead(result.commit);
+		// Force-push note: everything rolled back may have just been discarded.
+		await this.exclusive(() => this.rollbackSettled());
+		return result;
+	}
+
 	// ── Keeping drafts up to date with main (Decision 8) ────────────────────────
 
 	/**
@@ -467,6 +766,7 @@ export class LiveGit {
 					const r = await this.exclusive(() => this.checkOnce(pendingCommitted));
 					if (r !== 'needs-pending') {
 						await this.exclusive(() => this.learnDeletedTitles());
+						await this.exclusive(() => this.checkRollback());
 						return r;
 					}
 					await this.commitPending();
@@ -533,6 +833,7 @@ export class LiveGit {
 		this.since = { main: heads.main.commit, drafts: heads.main.commit, commits: [], files: new Set(), absent: new Set() };
 		const fromMain = (cmp.files ?? []).filter((f) => this.inScope(f.path)).map((f) => this.toSite(f.path));
 		this.log(`drafts fast-forwarded to main (${heads.main.commit.slice(0, 7)})`);
+		await this.recordDraftsHead(heads.main.commit);
 		await this.told(fromMain);
 		return { kind: 'fast-forward', to: heads.main.commit, fromMain };
 	}
@@ -616,6 +917,7 @@ export class LiveGit {
 			absent: new Set(absent),
 		};
 		this.log(`merged main into drafts (${commit.slice(0, 7)}): from main [${fromMain.join(', ')}], draft kept [${keptDraft.join(', ')}]`);
+		await this.recordDraftsHead(commit);
 		await this.told([...copyAfter.keys()]);
 		return { kind: 'merged', commit, fromMain, keptDraft };
 	}
@@ -718,11 +1020,18 @@ export class LiveGit {
 			return null;
 		}
 		const repoFiles = (cmp.files ?? this.diffCopyFallback().map((path) => ({ path }))).map((f) => f.path);
-		const files = repoFiles.filter((p) => p.startsWith(this.prefix)).map(this.toSite);
+		const waiting = repoFiles.filter((p) => p.startsWith(this.prefix)).map(this.toSite);
+		const { records, addresses } = splitMoves(Object.entries(await this.redis.hgetall(movesKey(this.keyPrefix))));
+		// Finding 15: a document the reader would refuse stays waiting; the rest go.
+		const held = this.heldBack(waiting, records);
+		const files = waiting.filter((f) => !held.has(f));
+		if (!files.length) {
+			this.log(`publish: nothing publishable; held back ${[...held.keys()].join(', ')}`);
+			return { kind: 'held-back', held: [...held.values()] };
+		}
 		// A file drafts no longer has is deleted: "Contact (deleted)", its title from main's copy first (M5a Decision 12).
 		const gone = files.filter((f) => this.read(f) === null);
 		const goneTitles = await this.titlesBeforeRemoval(gone, heads.main.commit);
-		const { records, addresses } = splitMoves(Object.entries(await this.redis.hgetall(movesKey(this.keyPrefix))));
 		// Collections under pages: a held document's addresses come from its holder's (only `holds` is read, so no blocks are needed).
 		const bases = await heldBasesOf({ ...this.site, blocks: {} }, this.contentSource());
 		const moves = this.movesIn(files, records, bases, addresses);
@@ -744,18 +1053,104 @@ export class LiveGit {
 			...readdressed.map((f) => `${titleOf(f, this.read(f))} (moved from ${moves.from.get(f)})`),
 			...items.filter((_, i) => !moves.from.has(files[i]!) && !moves.to.has(files[i]!)),
 		];
-		const commit = await this.backend.createCommit(heads.drafts.tree, [heads.main.commit], publishMessage(titles, files, by));
+		// Finding 15: main's tree is drafts' with the held files as main has them, and drafts
+		// gets them back in a commit of its own on top, so they stay waiting.
+		const heldFiles = [...held.keys()];
+		const onMain = heldFiles.length ? await this.backend.readFiles(heldFiles.map((f) => ({ commit: heads.main.commit, path: this.toRepo(f) }))) : [];
+		const tree = heldFiles.length
+			? await this.backend.createTree(
+					heads.drafts.tree,
+					heldFiles.flatMap((f, i) => (onMain[i] === null ? [{ path: this.toRepo(f), mode: '100644', sha: null }] : [])),
+					heldFiles.flatMap((f, i) => (onMain[i] === null ? [] : [{ path: this.toRepo(f), contents: onMain[i]! }])),
+				)
+			: heads.drafts.tree;
+		const commit = await this.backend.createCommit(tree, [heads.main.commit], publishMessage(titles, files, by));
+		const heldBackMessage = heldFiles.length ? heldMessage([...held.values()].map((h) => h.title), heldFiles, waitingFromCommits(heldFiles, cmp.commits)) : null;
+		const draftsHead = heldBackMessage ? await this.backend.createCommit(heads.drafts.tree, [commit], heldBackMessage) : commit;
 		const moved = await this.moveRefs([
 			// main: a fast-forward onto the squash commit. drafts: not a fast-forward, so
 			// `force`, but still compare-and-swap on `before` (M1 → G2).
 			{ branch: 'main', before: heads.main.commit, after: commit, force: false },
-			{ branch: 'drafts', before: heads.drafts.commit, after: commit, force: true },
+			{ branch: 'drafts', before: heads.drafts.commit, after: draftsHead, force: true },
 		]);
 		if (!moved) return null; // the squash commit is left orphaned; nothing points at it
-		this.copyHead = { commit, tree: heads.drafts.tree };
-		this.since = { main: commit, drafts: commit, commits: [], files: new Set(), absent: new Set() };
+		this.copyHead = { commit: draftsHead, tree: heads.drafts.tree };
+		this.since = heldBackMessage
+			? {
+					main: commit,
+					drafts: draftsHead,
+					commits: [{ sha: draftsHead, parents: [commit], message: heldBackMessage, date: new Date(this.now()).toISOString() }],
+					files: new Set(heldFiles.map(this.toRepo)),
+					absent: new Set(heldFiles.filter((_, i) => onMain[i] === null).map(this.toRepo)),
+				}
+			: { main: commit, drafts: commit, commits: [], files: new Set(), absent: new Set() };
 		this.deletedTitles.clear();
 		this.historyCache = null;
+		const record: PublishRecord = { commit, by, at: new Date(this.now()).toISOString(), files, titles, tryAgainAt: null };
+		// The refs moved: the Publish has happened, and it's deploying. Nothing after this may
+		// fail it (caracms-cloud adversarial review, finding 6): Redis dropping out now is logged,
+		// and the answer is `published` with the record made here.
+		try {
+			await this.afterPublish(record, draftsHead, records, addresses, bases, held);
+		} catch (error) {
+			this.unkeptRecord = record;
+			this.log(`published ${commit.slice(0, 7)}, but what follows a publish in Redis didn't all happen (${error instanceof Error ? error.message : String(error)}): the status shows this publish from this server's memory until the next one`);
+		}
+		this.log(`published ${commit.slice(0, 7)} (attempt ${attempt}): ${titles.join(', ')}${heldFiles.length ? `; held back ${heldFiles.join(', ')}` : ''}`);
+		return { kind: 'published', record, attempts: attempt, fileTitles, held: [...held.values()] };
+	}
+
+	/**
+	 * Finding 15: the waiting files Publish leaves waiting, by file: each document the reader
+	 * would refuse (document-problems.ts), and a moved one's old file with it (its record, old
+	 * file → new), so its live page stays where it is. A deletion is never held back.
+	 */
+	private heldBack(files: readonly string[], records: ReadonlyMap<string, string>): Map<string, HeldBack> {
+		const held = new Map<string, HeldBack>();
+		for (const file of files) {
+			const text = this.read(file);
+			if (text === null || !this.isDocument(file)) continue;
+			const [problem] = textProblems(text);
+			if (problem) held.set(file, { file, title: titleOf(file, text), reason: problem.reason });
+		}
+		for (const [old, now] of records) {
+			const why = held.get(now);
+			if (why && files.includes(old) && !held.has(old)) held.set(old, { ...why, file: old });
+		}
+		return held;
+	}
+
+	/** Is this site file a document of a declared collection (Site Settings and shared blocks included)? */
+	private isDocument(file: string): boolean {
+		try {
+			confinePath(this.site as ResolvedSite, file);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	/** Publish's Redis work once its refs have moved (finding 6: its caller catches what fails). `draftsHead`: where it left `drafts` (finding 5). */
+	private async afterPublish(
+		record: PublishRecord,
+		draftsHead: string,
+		records: ReadonlyMap<string, string>,
+		addresses: ReadonlyMap<string, string>,
+		bases: Readonly<Record<string, HeldBase>>,
+		held: ReadonlyMap<string, HeldBack>,
+	): Promise<void> {
+		const { files } = record;
+		await this.recordDraftsHead(draftsHead);
+		if (this.lost) {
+			// Finding 5: a Publish since `drafts` was lost is the team carrying on; the note goes.
+			this.lost = null;
+			await this.redis.del(this.draftsLostKey).catch(() => 0);
+		}
+		if (this.rolledBack) {
+			// Force-push note: what was waiting has been published, rolled-back content and all, by choice.
+			this.rolledBack = null;
+			await this.redis.del(this.mainRolledBackKey).catch(() => 0);
+		}
 		// The moves this publish took live are done with (a move made since stays waiting).
 		const published = [...records].filter(([old]) => files.includes(old)).map(([old]) => old);
 		if (published.length) {
@@ -771,7 +1166,8 @@ export class LiveGit {
 		// changed since (still its live address in what was published) stays waiting.
 		const live = withHeldBases(this.site, bases);
 		const done = [...addresses].filter(([file, was]) => {
-			if (this.read(file) === null) return false;
+			// Finding 15: a held-back document's live address is still the one recorded.
+			if (this.read(file) === null || held.has(file)) return false;
 			const url = this.urlOf(live, file);
 			return url !== null && url !== was;
 		}).map(([file]) => `${ADDRESS_FIELD}${file}`);
@@ -784,15 +1180,12 @@ export class LiveGit {
 			if (cleared) this.statusCache.hash(key, {}, done);
 			else this.statusCache.drop(key);
 		}
-		const record: PublishRecord = { commit, by, at: new Date(this.now()).toISOString(), files, titles, tryAgainAt: null };
 		await this.setPublishRecord(record);
-		this.log(`published ${commit.slice(0, 7)} (attempt ${attempt}): ${titles.join(', ')}`);
-		return { kind: 'published', record, attempts: attempt, fileTitles };
 	}
 
-	/** The newest publish, from Redis. */
+	/** The newest publish, from Redis (or this server's own newer one Redis didn't take, finding 6). */
 	async lastPublish(): Promise<PublishRecord | null> {
-		return LiveGit.publishRecordFrom(await this.redis.get(this.publishRecordKey));
+		return this.publishRecordOr(LiveGit.publishRecordFrom(await this.redis.get(this.publishRecordKey)));
 	}
 
 	/** A publish record from its text as read (the status cache's, on a poll). */
@@ -917,7 +1310,11 @@ export class LiveGit {
 		if (!this.since) return [];
 		const waiting = new Set([...this.since.files].filter((p) => this.inScope(p)).map(this.toSite));
 		const out = new Map<string, string>();
-		for (const c of this.since.commits) for (const file of parseMessage(c.message).keptDraft) if (waiting.has(file)) out.set(file, c.sha);
+		for (const c of this.since.commits) {
+			const parsed = parseMessage(c.message);
+			for (const file of parsed.discardedFiles) out.delete(file); // a discard ends the notice's reason
+			for (const file of parsed.keptDraft) if (waiting.has(file)) out.set(file, c.sha);
+		}
 		return [...out].map(([file, commit]) => ({ file, commit }));
 	}
 
@@ -946,6 +1343,79 @@ export class LiveGit {
 		});
 	}
 
+	// ── `main` rolled back (force-push note) ─────────────────────────────────────
+
+	/**
+	 * After a check: does `main` still have the last Publish's commit? Only rewritten history
+	 * loses it (a push on top, a merge or a revert keeps it). One compare per pair; never
+	 * fails the check.
+	 */
+	private async checkRollback(): Promise<void> {
+		try {
+			const record = await this.lastPublish();
+			if (!record) {
+				this.rolledBack = null;
+				return;
+			}
+			const main = this.since?.main ?? (await this.backend.readHeads()).main.commit;
+			const pair = `${record.commit}:${main}`;
+			if (pair !== this.rollbackPair) {
+				const has = await this.mainHasPublish(record.commit, main);
+				if (has === null) {
+					// GitHub doesn't know the commit (another repo's record, or long gone): can't tell, so no note.
+					if (this.rollbackUnknown !== record.commit) this.log(`the last Publish's commit (${record.commit.slice(0, 7)}) isn't on GitHub: can't tell whether main was rolled back`);
+					this.rollbackUnknown = record.commit;
+					this.rolledBack = null;
+				} else if (has) {
+					if (this.rolledBack || this.rollbackPair === null) await this.redis.del(this.mainRolledBackKey);
+					this.rolledBack = null;
+				} else {
+					const kept = this.rolledBack?.publish === record.commit ? this.rolledBack : parseRolledBack(await this.redis.get(this.mainRolledBackKey));
+					if (kept && kept.publish === record.commit) this.rolledBack = kept;
+					else {
+						this.rolledBack = { publish: record.commit, main, at: new Date(this.now()).toISOString() };
+						await this.redis.set(this.mainRolledBackKey, JSON.stringify(this.rolledBack));
+						this.log(
+							`MAIN WAS ROLLED BACK: main (${main.slice(0, 7)}) no longer has the last Publish's commit (${record.commit.slice(0, 7)}), so its history was rewritten (a force-push). What was rolled back is waiting in the editor again, and the next Publish puts it back; editors are told to discard what they don't want first.`,
+						);
+					}
+				}
+				this.rollbackPair = pair;
+			}
+			await this.rollbackSettled();
+		} catch (error) {
+			this.log(`checking whether main was rolled back: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+
+	/** Force-push note: with nothing waiting (all of it discarded), the note is done with for this rollback, on every server. */
+	private async rollbackSettled(): Promise<void> {
+		const note = this.rolledBack;
+		if (!note || note.cleared || !this.since || this.waiting().length > 0) return;
+		this.rolledBack = { ...note, cleared: true };
+		this.log(`main's rollback: nothing is waiting any more, so the note is done with`);
+		await this.redis.set(this.mainRolledBackKey, JSON.stringify(this.rolledBack)).catch((error: unknown) => {
+			this.log(`keeping the rollback note's end: ${error instanceof Error ? error.message : String(error)}`);
+		});
+	}
+
+	/** Is the Publish's `commit` in `main`? Null when GitHub doesn't have it. One compare per pair, per server. */
+	private async mainHasPublish(commit: string, main: string): Promise<boolean | null> {
+		if (commit === main) return true;
+		const key = `${commit}:${main}`;
+		const known = this.onMainCache.get(key);
+		if (known !== undefined) return known;
+		try {
+			const cmp = await this.backend.compare(commit, main);
+			const yes = cmp.status === 'ahead' || cmp.status === 'identical';
+			this.onMainCache.set(key, yes); // ancestry never changes
+			return yes;
+		} catch (error) {
+			if (error instanceof HttpError && (error.status === 404 || error.status === 422)) return null;
+			throw error;
+		}
+	}
+
 	/** Is `commit` in `running` (the same, or an ancestor)? One compare per pair, per server. */
 	private async includes(commit: string, running: string): Promise<boolean> {
 		const key = `${commit}:${running}`;