dsh-switchman 1.10.3 → 1.11.0

package/host/context-trim/summarizer.js

@@ -1,16 +1,23 @@
 /** dsh-switchman context-trim summarizer.
  *
- * Produces the summary text for one fold block, two ways:
+ * Produces the summary text for one fold block, three ways:
  *
  * - summarizeWithModel — the L3 path (design §5): a side-model call via
  *   llm.prepareCall + call.stream (receiver-bound on the llm service, the
  *   same waterfall pattern intent classification uses). Guarded by a hard
  *   deadline (AbortController); ANY failure (timeout, error chunk, empty
  *   output) returns null and the caller skips the fold cycle — fail-open.
+ *   A length-finished (output-limit) summary is NOT a failure: it returns
+ *   the text prefixed with TRUNCATED_SUMMARY_MARK so the missing tail
+ *   stays visible (inspection S2).
+ *   Used by BOTH the raw T1 folds (renderMaterial) and the ladder T2/T3
+ *   distillations (renderLadderMaterial, LADDER_SYSTEM_PROMPT).
  * - mechanicalSummary — the deterministic fallback used by the emergency
- *   tier: structural heads of each message, no model round trip.
+ *   tier: structural heads of each message, no model round trip. Never
+ *   used for ladder folds (mechanical summary-of-summaries reclaims little
+ *   and corrupts craft — docs/ladder-fold.md).
  *
- * The summary prompt carries the bili compression rules: message refs and
+ * The summary prompts carry the bili compression rules: message refs and
  * file paths verbatim, decisions WITH rationale, exact values, open
  * objectives carry forward, verbose logs drop.
  */
@@ -25,6 +32,14 @@ export const SUMMARY_TIMEOUT_MS = 120_000;
  * (a 1M-token material would burn the side-model call for no fidelity). */
 export const MAX_MATERIAL_CHARS = 400_000;
 
+/** Prefix for a summary whose side-model output ended early (finish=length):
+ * the text otherwise reads as settled fact while its tail is missing — and
+ * ladder T2/T3 distillation builds on summaries as established facts, so
+ * the gap must stay visible on the wire. Prefixed, not rejected: the fold
+ * still relieves pressure, and re-running at the same maxTokens would
+ * truncate again. (inspection S2) */
+export const TRUNCATED_SUMMARY_MARK = "[truncated summary: the summarizer's output hit its limit (finish=length) — content after the cut may be missing] ";
+
 /** System prompt for the side-model summarizer. English per repo docs
  * style; the OUTPUT language follows the summarized material. */
 export const SUMMARY_SYSTEM_PROMPT = [
@@ -47,6 +62,33 @@ export const SUMMARY_SYSTEM_PROMPT = [
 	"- Output ONLY the summary text.",
 ].join("\n");
 
+/** Flat text body of one message (content blocks joined, unserializable
+ * values tolerated). Shared by renderMaterial and the zero-material
+ * rescue path. */
+function renderMessageBody(message) {
+	const content = message?.content;
+	if (typeof content === "string") return content;
+	if (Array.isArray(content)) {
+		const chunks = [];
+		for (const block of content) {
+			if (block !== null && typeof block === "object" && typeof block.text === "string") chunks.push(block.text);
+			else {
+				try {
+					chunks.push(JSON.stringify(block ?? null));
+				} catch {
+					chunks.push("[unserializable]");
+				}
+			}
+		}
+		return chunks.join("\n");
+	}
+	try {
+		return JSON.stringify(message ?? null);
+	} catch {
+		return "[unserializable]";
+	}
+}
+
 /** Render the fold material for one message range: labeled, ref-stamped
  * blocks. Deterministic (same slice, same bytes) — refs come from refOf so
  * id-less messages stay stable across re-sends. */
@@ -58,29 +100,7 @@ export function renderMaterial(messages, startIdx, endIdx, refOf) {
 		const message = messages[i];
 		const ref = refOf(message, i);
 		const role = typeof message?.role === "string" ? message.role : "unknown";
-		let text;
-		const content = message?.content;
-		if (typeof content === "string") text = content;
-		else if (Array.isArray(content)) {
-			const chunks = [];
-			for (const block of content) {
-				if (block !== null && typeof block === "object" && typeof block.text === "string") chunks.push(block.text);
-				else {
-					try {
-						chunks.push(JSON.stringify(block ?? null));
-					} catch {
-						chunks.push("[unserializable]");
-					}
-				}
-			}
-			text = chunks.join("\n");
-		} else {
-			try {
-				text = JSON.stringify(message ?? null);
-			} catch {
-				text = "[unserializable]";
-			}
-		}
+		let text = renderMessageBody(message);
 		if (Array.isArray(message?.tool_calls) && message.tool_calls.length > 0) {
 			try {
 				text += `\n[tool_calls] ${JSON.stringify(message.tool_calls)}`;
@@ -97,7 +117,71 @@ export function renderMaterial(messages, startIdx, endIdx, refOf) {
 		parts.push(head + body);
 		chars += head.length + body.length;
 	}
-	if (truncated) parts.push(`--- [...material truncated after ${chars} chars; ${endIdx - startIdx + 1 - parts.length} messages dropped from this render...] ---\n`);
+	if (truncated) {
+		// [2026-11-07]-[a single over-ceiling message used to render ZERO
+		// material]-[parts stayed empty, the side model was asked to compress
+		// nothing, and the giant message got permanently replaced by a
+		// content-free summary. Keep the FIRST message's head plus a capped
+		// prefix so the summary at least carries what the message is.]
+		if (parts.length === 0 && startIdx <= endIdx) {
+			const first = messages[startIdx];
+			const firstRef = refOf(first, startIdx);
+			const role = typeof first?.role === "string" ? first.role : "unknown";
+			parts.push(`--- [m${firstRef}] (${role}) ---\n${renderMessageBody(first).slice(0, 2_000)}\n\n`);
+		}
+		parts.push(`--- [...material truncated after ${chars} chars; ${endIdx - startIdx + 1 - parts.length} messages dropped from this render...] ---\n`);
+	}
+	return parts.join("");
+}
+
+/** Distillation system prompt for the ladder tiers (T2 merges active T1
+ * summaries; T3 merges active T2 summaries). The output replaces its
+ * inputs PERMANENTLY — the craft rules are the same KEEP/DROP priorities,
+ * applied one level up. */
+export const LADDER_SYSTEM_PROMPT = [
+	"You distill several context-fold summaries of one coding-agent session into ONE shorter self-contained plain-text summary that permanently replaces them.",
+	"",
+	"Treat the input summaries as facts already settled: never re-derive, never contradict, merge overlapping points.",
+	"",
+	"KEEP VERBATIM:",
+	"- Full file paths with line numbers (lib/hooks.ts:347) — never bare filenames.",
+	"- Function/class/type signatures and the critical code line that encodes a finding.",
+	"- Error messages and stack-trace key lines (exact text).",
+	"- Exact values: versions, config keys, thresholds, magic numbers.",
+	"- Decisions WITH their rationale (the because is load-bearing).",
+	"- Open objectives, unresolved TODOs, and open questions, each tagged with its original message refs.",
+	"",
+	"DROP (one line of lesson per failure stays): verbose detail once the exact value is captured, repetition between the summaries, settled exploration, process narration.",
+	"",
+	"FORMAT:",
+	"- Dense bullets, short thematic headers; no narrative prose.",
+	"- Keep the [m<ref>] anchors for anything a later step may need to unfold.",
+	"- Write the summary in the same language as the input summaries.",
+	"- Output ONLY the summary text.",
+].join("\n");
+
+/** Render the ladder distillation material for one run of consumed blocks:
+ * labeled, block-stamped sections (deterministic — same blocks, same
+ * bytes). Capped by the same material ceiling as renderMaterial. */
+export function renderLadderMaterial(blocks) {
+	const parts = [];
+	let chars = 0;
+	let truncated = false;
+	for (const block of blocks) {
+		const tier = block?.tier === 3 ? 3 : block?.tier === 2 ? 2 : 1;
+		const tokens = Number.isFinite(block?.approxTokens) ? Math.round(block.approxTokens) : "?";
+		const count = Number.isInteger(block?.count) && block.count > 0 ? block.count : "?";
+		const summary = typeof block?.summary === "string" ? block.summary : "";
+		const head = `--- [block ${block?.id ?? "?"}] (tier ${tier}, ~${tokens} tokens, ${count} msgs) ---\n`;
+		const body = `${summary}\n\n`;
+		if (chars + head.length + body.length > MAX_MATERIAL_CHARS) {
+			truncated = true;
+			break;
+		}
+		parts.push(head + body);
+		chars += head.length + body.length;
+	}
+	if (truncated) parts.push(`--- [...material truncated after ${chars} chars; ${blocks.length - parts.length} blocks dropped from this render...] ---\n`);
 	return parts.join("");
 }
 
@@ -127,16 +211,32 @@ export function mechanicalSummary(messages, startIdx, endIdx, refOf) {
 	return lines.join("\n");
 }
 
+/** One-line suffix carrying the adapter's failure detail: DSH terminal
+ * finishes ride { reason: { kind, failure: { message, code, status? } } } —
+ * without this the decisions.log only ever sees finishKind, and upstream
+ * rejections (quota/concurrency/risk) stay invisible. Single-lined, capped. */
+function describeFailure(chunk) {
+	const failure = chunk?.reason?.failure ?? chunk?.failure ?? null;
+	const raw = typeof failure?.message === "string" && failure.message !== ""
+		? failure.message
+		: (typeof failure?.code === "string" && failure.code !== "" ? failure.code : "");
+	if (raw === "") return "";
+	return ` (${raw.replace(/\s+/gu, " ").trim().slice(0, 300)})`;
+}
+
 /** Side-model summary. llm: the dsh llm service (receiver-bound methods);
  * route: { provider, model } | null (null → caller skips); materialText:
- * renderMaterial output; deadlineMs: hard budget. Returns the summary
- * text, or null on ANY failure (caller skips the fold cycle). */
+ * renderMaterial output; options.systemPrompt overrides the default
+ * compression prompt (the ladder distillation passes its own); deadlineMs:
+ * hard budget. Returns the summary text, or null on ANY failure (caller
+ * skips the fold cycle). */
 export async function summarizeWithModel(llm, route, materialText, options = {}) {
 	const fail = typeof options.onFail === "function" ? options.onFail : null;
 	if (route === null || route === undefined) { fail?.("no-route"); return null; }
 	if (typeof llm?.prepareCall !== "function") { fail?.("no-prepare-call"); return null; }
 	const deadlineMs = Number.isFinite(options.deadlineMs) && options.deadlineMs > 0 ? options.deadlineMs : SUMMARY_TIMEOUT_MS;
 	const maxTokens = Number.isFinite(options.maxTokens) && options.maxTokens > 0 ? options.maxTokens : 8_192;
+	const systemPrompt = typeof options.systemPrompt === "string" && options.systemPrompt !== "" ? options.systemPrompt : SUMMARY_SYSTEM_PROMPT;
 	const controller = new AbortController();
 	const timer = setTimeout(() => controller.abort(new Error("trim summary deadline")), deadlineMs);
 	try {
@@ -146,7 +246,7 @@ export async function summarizeWithModel(llm, route, materialText, options = {})
 			(controls) => controls,
 		);
 		let text = "";
-			let finishKind = null;
+		let finishKind = null;
 		// stream options MUST carry the prepared call config — the adapter
 		// dispatch binds credentials/routing from it (same waterfall shape as
 		// the intent classifier; dropping it fails prepare-time integrity).
@@ -154,7 +254,7 @@ export async function summarizeWithModel(llm, route, materialText, options = {})
 		// source tag, exactly like the intent classifier's proven shape.
 		const streamOptions = {
 			...call.config,
-			system: SUMMARY_SYSTEM_PROMPT,
+			system: systemPrompt,
 			messages: [
 				{ id: randomUUID(), role: "user", content: [{ type: "text", text: materialText }], source: { kind: "dsh-switchman-trim-summary" } },
 			],
@@ -163,12 +263,26 @@ export async function summarizeWithModel(llm, route, materialText, options = {})
 		for await (const chunk of call.stream(streamOptions)) {
 			if (chunk?.type === "text-delta" && typeof chunk.text === "string") text += chunk.text;
 			else if (chunk?.type === "finish") {
-				finishKind = chunk.kind ?? null;
-				if (chunk.kind === "error" || chunk.kind === "aborted") { fail?.(`stream-${chunk.kind}`); return null; }
+				// The translator's clean stop is { type:'finish', reason:{kind:'stop'} } —
+				// no top-level kind. Read the nested reason first so clean EOFs log
+				// finish=stop (not finish=none), and treat abort/error finishes as
+				// explicit failures in either shape.
+				const topKind = chunk.kind ?? null;
+				finishKind = chunk.reason?.kind ?? topKind;
+				if (topKind === "error" || topKind === "aborted" || finishKind === "error" || finishKind === "aborted") {
+					fail?.(`stream-${finishKind}${describeFailure(chunk)}`);
+					return null;
+				}
 			}
 		}
 		const summary = text.trim();
 		if (summary === "") { fail?.(`empty-output finish=${finishKind ?? "none"}`); return null; }
+		// A length/max-tokens finish means the tail of the material never got
+		// summarized, yet the text that DID land reads as settled fact — mark it
+		// so every later consumer (view rendering, ladder distillation) sees the
+		// gap. DSH's FinishReasonMap has no "length" kind: adapters map
+		// finish_reason=length to kind "max-tokens" (llm-deepseek translate).
+		if (finishKind === "length" || finishKind === "max-tokens") return `${TRUNCATED_SUMMARY_MARK}${summary}`;
 		return summary;
 	} catch (error) {
 		fail?.(`error: ${error?.message ?? error}`);

package/host/context-trim/surface.js

@@ -68,6 +68,17 @@
  * - Never append while a durable compaction/start..compaction/end lock pair
  *   is open for the session (design constraint).
  *
+ * LADDER SHIP (docs/ladder-fold.md): tier ≥ 2 blocks ride the same pair,
+ * but their material is the REPLACEMENT NODES their consumed blocks shipped
+ * (each consumed block's surfaceReplaced marker carries atSeq). The span
+ * from the first to the last replacement node must contain EXACTLY the
+ * consumed replacement nodes — engine folds are frontier-ordered, nothing
+ * can legitimately interleave, and any mismatch tombstones
+ * (ladder-span-mismatch / ladder-span-gone / ladder-consumed-skipped)
+ * instead of guessing. A ladder block whose consumed blocks have not
+ * shipped yet stays pending: they sit EARLIER in the same sweep (ledger
+ * order) and ship before it is reached again on a later sweep.
+ *
  * Everything fails open: a missing agents service / session.append / surface
  * support degrades to today's behavior (wire=raw banner + tally watermark),
  * and every no-op with pending work is logged to decisions.log.
@@ -75,6 +86,12 @@
 
 import { refOf, summaryMessageOf } from "./view.js";
 
+/** Ladder-block probe (tier ≥ 2): a distillation whose surface material is
+ * the REPLACEMENT NODES of its consumed blocks, not a raw ref range. */
+function isLadderBlock(block) {
+	return block !== null && typeof block === "object" && (block.tier === 2 || block.tier === 3);
+}
+
 // ---- tool-pair closure ------------------------------------------------------
 
 /** Call ids OPENED by one message, across every wire shape the plugin can
@@ -618,12 +635,25 @@ export function createSurfaceFoldPass(deps = {}) {
 		if (typeof sessionId !== "string" || sessionId === "") return 0;
 		const ledger = store.ledgerOf(sessionId);
 		const blocks = Array.isArray(ledger.blocks) ? ledger.blocks : [];
+		// [2026-11-07]-[hintless sweeps used a null generation, so
+		// generation-keyed tombstones could NEVER re-open]-[the idle sweep
+		// passes no sessionHint: every tombstone (incomplete-seqs,
+		// tool-pair-unclosed, append-rejected, ...) was filtered out forever
+		// even after the surface changed (inspection P1-8). Fall back to the
+		// live session's generation when the hint does not carry one.]
 		const generation = (() => {
 			try {
-				return Number.isFinite(sessionHint?.surface?.contentGeneration) ? sessionHint.surface.contentGeneration : null;
+				if (Number.isFinite(sessionHint?.surface?.contentGeneration)) return sessionHint.surface.contentGeneration;
+			} catch {
+				/* fall through to the live lookup */
+			}
+			try {
+				const live = surfaceCapable(sessionHint) ? sessionHint : sessionOf(sessionId);
+				if (live !== null && typeof live === "object" && Number.isFinite(live.surface?.contentGeneration)) return live.surface.contentGeneration;
 			} catch {
-				return null;
+				/* unreadable session: null, fail-open */
 			}
+			return null;
 		})();
 		const pending = blocks.filter((block) => {
 			if (block?.surfaceReplaced !== null && block?.surfaceReplaced !== undefined) return false;
@@ -667,6 +697,196 @@ export function createSurfaceFoldPass(deps = {}) {
 		let headIsSystem = headNodeIsSystem(session, nodes);
 		let shipped = 0;
 		for (const block of pending) {
+			// ---- LADDER BRANCH (tier ≥ 2, docs/ladder-fold.md) --------------
+			// A distillation's surface material is the REPLACEMENT NODES of its
+			// consumed blocks (each carries a surfaceReplaced marker with the
+			// replacement event seq). The span from the first to the last
+			// replacement node must contain EXACTLY those nodes — engine folds
+			// are frontier-ordered, so nothing can legitimately interleave —
+			// and every mismatch tombstones instead of guessing.
+			if (isLadderBlock(block)) {
+				const consumedIds = Array.isArray(block.consumes) ? block.consumes : [];
+				const byId = new Map(blocks.map((entry) => [entry?.id, entry]));
+				const consumed = consumedIds.map((id) => byId.get(id));
+				if (consumed.some((entry) => entry === undefined || entry === null)) {
+					block.surfaceSkip = { reason: "ladder-consumed-skipped", contentGeneration: liveGeneration, at: Date.now() };
+					try {
+						store.persist(ledger);
+					} catch {
+						/* best effort */
+					}
+					skip(sessionId, "ladder-consumed-skipped", via, `block=${block.id}`);
+					continue;
+				}
+				const waiting = consumed.find((entry) => entry.surfaceReplaced === null || entry.surfaceReplaced === undefined);
+				if (waiting !== undefined) {
+					if (tombstoneOf(waiting) !== null) {
+						// A consumed block is hard-skipped on this generation: its
+						// replacement node can never materialize, so the ladder span
+						// can never be exact. Generation-keyed like every skip — a
+						// surface change re-opens both blocks.
+						block.surfaceSkip = { reason: "ladder-consumed-skipped", contentGeneration: liveGeneration, at: Date.now() };
+						try {
+							store.persist(ledger);
+						} catch {
+							/* best effort */
+						}
+						skip(sessionId, "ladder-consumed-skipped", via, `block=${block.id} consumed=${waiting.id}`);
+					}
+					// Otherwise the consumed block is still pending and sits EARLIER
+					// in this loop (ledger order): it ships — or skips — before this
+					// iteration reaches the ladder block again on a later sweep.
+					continue;
+				}
+				const indexOfSeq = new Map(nodes.map((seq, index) => [seq, index]));
+				// Summary-message id positions on the LIVE surface: the
+				// replacement message (acp_summary_<blockId>, deterministic body)
+				// is content-stable, so a branch/compaction that re-projected the
+				// surface invalidates the stored atSeqs but NOT the identity of
+				// the replacement nodes — the same re-location-not-re-target rule
+				// the T1 stale-capture path follows.
+				// [2026-11-07]-[observed live: a DSH branch rebuilt the surface
+				// projection, orphaning every T1 atSeq and tombstoning the pending
+				// T2 as ladder-span-gone forever]-[id re-location lets the ladder
+				// ship after any surface re-projection; the spanExact id-set check
+				// below keeps it exact.]
+				const idIndexOf = new Map();
+				for (let i = 0; i < nodeMessages.length; i++) {
+					const message = nodeMessages[i];
+					if (message !== null && typeof message === "object" && typeof message.id === "string" && message.id.startsWith("acp_summary_")) {
+						idIndexOf.set(message.id, i);
+					}
+				}
+				const atSeqs = [];
+				let unresolved = null;
+				for (const entry of consumed) {
+					const atSeq = Number.isFinite(entry.surfaceReplaced.atSeq) ? entry.surfaceReplaced.atSeq : null;
+					if (atSeq !== null && indexOfSeq.has(atSeq)) {
+						atSeqs.push(atSeq);
+						continue;
+					}
+					const relocatedIdx = idIndexOf.get(`acp_summary_${entry.id}`);
+					if (relocatedIdx === undefined) {
+						unresolved = entry;
+						break;
+					}
+					atSeqs.push(nodes[relocatedIdx]);
+				}
+				if (unresolved !== null) {
+					// A consumed replacement node left the live surface (host
+					// compaction shadowed it): the span is unreconstructable.
+					block.surfaceSkip = { reason: "ladder-span-gone", contentGeneration: liveGeneration, at: Date.now() };
+					try {
+						store.persist(ledger);
+					} catch {
+						/* best effort */
+					}
+					skip(sessionId, "ladder-span-gone", via, `block=${block.id} consumed=${unresolved.id}`);
+					continue;
+				}
+				const nodeIndexes = atSeqs.map((seq) => indexOfSeq.get(seq));
+				const ladderFirstIdx = Math.min(...nodeIndexes);
+				const ladderLastIdx = Math.max(...nodeIndexes);
+				const spanSeqs = nodes.slice(ladderFirstIdx, ladderLastIdx + 1);
+				const expectedSeqs = new Set(atSeqs);
+				let spanExact = spanSeqs.length === atSeqs.length && spanSeqs.every((seq) => expectedSeqs.has(seq));
+				// Id-set exactness: after id re-location the span must contain
+				// EXACTLY the consumed blocks' summary messages — a span that
+				// picked up a stranger's acp_summary node is not this fold's
+				// material (the length check alone cannot tell them apart).
+				if (spanExact) {
+					const expectedIds = new Set(consumed.map((entry) => `acp_summary_${entry.id}`));
+					for (let i = ladderFirstIdx; i <= ladderLastIdx; i++) {
+						const message = nodeMessages[i];
+						if (message === null || message === undefined || typeof message.id !== "string" || !expectedIds.has(message.id)) {
+							spanExact = false;
+							break;
+						}
+					}
+				}
+				if (spanExact) {
+					for (let i = ladderFirstIdx; i <= ladderLastIdx; i++) {
+						const message = nodeMessages[i];
+						if (message === null || message === undefined || typeof message.id !== "string" || !message.id.startsWith("acp_summary_")) {
+							spanExact = false;
+							break;
+						}
+					}
+				}
+				if (!spanExact) {
+					block.surfaceSkip = { reason: "ladder-span-mismatch", contentGeneration: liveGeneration, at: Date.now() };
+					try {
+						store.persist(ledger);
+					} catch {
+						/* best effort */
+					}
+					skip(sessionId, "ladder-span-mismatch", via, `block=${block.id}`);
+					continue;
+				}
+				// Defensive system-head clamp (a summary node can never be node
+				// 0 — T1 folds start after the head — but a drift-hostile guard
+				// costs one comparison).
+				if (headIsSystem && ladderFirstIdx === 0) {
+					block.surfaceSkip = { reason: "system-head", contentGeneration: liveGeneration, at: Date.now() };
+					try {
+						store.persist(ledger);
+					} catch {
+						/* best effort */
+					}
+					skip(sessionId, "system-head", via, `block=${block.id} ladder`);
+					continue;
+				}
+				const ladderStartSeq = nodes[ladderFirstIdx];
+				const ladderEndSeq = nodes[ladderLastIdx];
+				const ladderKey = replacedKey(sessionId, ladderStartSeq, ladderEndSeq, liveGeneration);
+				if (wasReplaced(ladderKey)) continue; // belt over the durable marker
+				try {
+					session.append("compaction/prune", {
+						shadowedRange: { start: ladderStartSeq, end: ladderEndSeq },
+						shadowedSeqs: spanSeqs,
+						shadowedTokenCount: Number.isFinite(block.approxTokens) && block.approxTokens > 0 ? Math.round(block.approxTokens) : spanSeqs.length,
+					});
+					const event = session.append("user/message", replacementMessageOf(block), {
+						surfaceOp: { op: "replace", startSeq: ladderStartSeq, endSeq: ladderEndSeq },
+						sourceEventSeqs: spanSeqs,
+					});
+					block.surfaceReplaced = {
+						startSeq: ladderStartSeq,
+						endSeq: ladderEndSeq,
+						seqs: spanSeqs.slice(),
+						contentGeneration: liveGeneration,
+						atSeq: Number.isFinite(event?.seq) ? event.seq : null,
+						via,
+						at: Date.now(),
+					};
+					delete block.surfaceSkip;
+					rememberReplaced(ladderKey);
+					shipped += 1;
+					// Same post-ship snapshot refresh as the T1 branch: the
+					// shadowed seqs left surface.nodes.
+					nodes = surface.nodes.slice();
+					pairs = derivingPairsOf(session, nodes);
+					nodeMessages = denseMessagesOf(pairs, nodes.length);
+					headIsSystem = headNodeIsSystem(session, nodes);
+					liveGeneration = Number.isFinite(surface.contentGeneration) ? surface.contentGeneration : 0;
+					decisionLog(`session=${sessionId} surface-replace startSeq=${ladderStartSeq} endSeq=${ladderEndSeq} seqs=${spanSeqs.length} tokens=${Number.isFinite(block.approxTokens) ? Math.round(block.approxTokens) : "?"} generation=${liveGeneration} ladder=${block.tier} via=${via}`);
+					try {
+						store.persist(ledger);
+					} catch {
+						/* the in-memory marker still guards this process */
+					}
+				} catch (error) {
+					const message = String(error?.message ?? error).replace(/\s+/g, " ").slice(0, 160);
+					block.surfaceSkip = { reason: `append-rejected:${message}`, contentGeneration: liveGeneration, at: Date.now() };
+					try {
+						store.persist(ledger);
+					} catch {
+						/* best effort */
+					}
+					skip(sessionId, `append-rejected:${message}`, via, `block=${block.id} ladder=${block.tier}`);
+				}
+				continue;
+			}
 			// Resolve the shadow range: stored capture first (validated dense
 			// against the LIVE surface). A stale/incomplete capture — or a
 			// capture-less legacy block — falls back to live location, but ONLY