dsh-context-pruner 0.0.0-stage → 0.1.1

package/lib/index.js

@@ -0,0 +1,795 @@
+/**
+ * dsh-context-pruner host plugin.
+ *
+ * Registers `/prune`, which can both READ the context surface and COMPACT a
+ * chosen span of it.
+ *
+ * ## Command grammar
+ *
+ *   /prune                       Every round ranked BIGGEST FIRST, so you can
+ *                                see which rounds cost the most. Not time order.
+ *   /prune list [n|all|a-b]      Read rounds in time order, with previews.
+ *   /prune drop <a>-<b>          COMPACT rounds a through b into one checkpoint.
+ *                                Everything outside that range is untouched.
+ *   /prune drop <a>-<b> --yes    Skip the confirmation echo.
+ *
+ * ## Why a confirmation step
+ *
+ * `drop` irreversibly changes what the model will see: the chosen rounds stop
+ * being sent and are replaced by one summary. The retired content stays in the
+ * session log for replay, but the model never sees it again. So `drop` first
+ * reports exactly which rounds would be replaced and what would remain, and
+ * requires `--yes` to proceed. That makes the destructive step deliberate
+ * rather than an accidental keystroke.
+ *
+ * ## Why the span is resolved to node seqs here
+ *
+ * Rounds are a presentation concept this plugin owns; the compaction seam
+ * speaks in surface node seqs. `drop` resolves the round range into the exact
+ * inclusive node span, sends that span, and lets the transaction reject an
+ * unbalanced edge rather than silently splitting a tool call from its result.
+ *
+ * @module dsh-context-pruner
+ */
+
+import { CommandDefinitionId } from "@deepseek-ai/dsh-commands/brand";
+import { ManualCompactionError, toolPairingBalancedAfter, toolPairingBalancedBefore } from "@deepseek-ai/dsh-compaction";
+import { describeNodes, formatTokens, groupRounds, renderRounds } from "./inspect.js";
+import { compactExplicitRegion, checkBalance } from "./compact.js";
+import { CorrectiveCompactionEngine, DEFAULT_CORRECTIVE_INSTRUCTION } from "./backend.js";
+
+export { CorrectiveCompactionEngine, DEFAULT_CORRECTIVE_INSTRUCTION } from "./backend.js";
+
+const name = "context-pruner";
+
+/**
+ * Hard requirements: the command registry and the token meter, both on the
+ * host plane.
+ *
+ * `compaction`, `llm` and `sessions` are deliberately NOT listed. In a Web
+ * profile the compaction backend is mounted INSIDE each agent preset (the
+ * host rows `compaction-basic` and `command-compact` are `disabled: true`),
+ * so requiring `compaction` here would leave this plugin permanently
+ * `pending` — the listing half would die along with the destructive half.
+ *
+ * Instead the read path never touches compaction, and `drop` resolves
+ * `ctx.get('compaction')` at call time (see {@link summarizeForDrop}), which
+ * is a host-plane service lookup that works because `ctx.llm` is what the
+ * summarizer actually needs.
+ */
+const inject = ["commands", "tokenMeter"];
+
+/** Rounds shown when the user does not ask for a specific count. */
+const DEFAULT_ROUNDS = 15;
+
+const USAGE = [
+	"Usage:",
+	"  /prune                     rounds ranked biggest-first (what costs the most)",
+	"  /prune list                read the newest 15 rounds in time order",
+	"  /prune list <n>            read the newest n rounds (NOT round number n)",
+	"  /prune list <a>-<b>        read rounds a through b",
+	"  /prune list seq <a>-<b>    read the rounds overlapping a surface seq span",
+	"  /prune list all            read every round",
+	"",
+	"  /prune drop <a>-<b>        compact rounds a-b into one checkpoint (asks first)",
+	"  /prune drop seq <a>-<b>    compact a surface seq span (what the panel sends)",
+	"  /prune drop <a>-<b> --yes  compact without asking"
+].join("\n");
+
+/**
+ * Gather the inspected surface once, so every branch shares one measurement.
+ *
+ * @param ctx - context carrying the token meter.
+ * @param agent - agent whose session is inspected.
+ * @returns `{ measurement, descriptors, rounds }`.
+ */
+function inspect(ctx, agent) {
+	const session = agent.session;
+	const measurement = ctx.tokenMeter.measure(session);
+	const descriptors = describeNodes(session, measurement.nodes);
+	return { measurement, descriptors, rounds: groupRounds(descriptors) };
+}
+
+/**
+ * Parse the argument to `/prune list`.
+ *
+ * @param raw - text after `list`.
+ * @returns a selection, or `{ error }` describing a malformed argument.
+ */
+function parseSelection(raw) {
+	const text = raw.trim();
+	if (text.length === 0) return { kind: "newest", count: DEFAULT_ROUNDS };
+	if (text === "all") return { kind: "all" };
+	if (/^\d+$/.test(text)) {
+		// `list 0` would silently become `list 1`. Say so instead: "the newest
+		// zero rounds" is not a meaningful request, and quietly showing one
+		// round hides the fact that the argument was not understood.
+		const count = Number.parseInt(text, 10);
+		if (count === 0) return { error: "`list 0` would show no rounds; give a count of 1 or more." };
+		return { kind: "newest", count };
+	}
+
+	// The `seq` form mirrors `drop seq <a>-<b>`, so the exact line the panel
+	// seeds into the composer can also be READ back before it is run.
+	const seqRange = /^seq\s+(\d+)\s*-\s*(\d+)$/i.exec(text);
+	if (seqRange !== null) {
+		return {
+			kind: "seq",
+			from: Number.parseInt(seqRange[1], 10),
+			to: Number.parseInt(seqRange[2], 10)
+		};
+	}
+
+	const range = /^(\d+)\s*-\s*(\d+)$/.exec(text);
+	if (range !== null) {
+		const from = Number.parseInt(range[1], 10);
+		const to = Number.parseInt(range[2], 10);
+		if (from > to) return { error: `Range ${from}-${to} is reversed.` };
+		return { kind: "range", from, to };
+	}
+
+	return { error: `Unrecognised argument: ${text}` };
+}
+
+/**
+ * Render the plain `/prune` summary.
+ *
+ * @param inspection - result of {@link inspect}.
+ * @returns human-facing text.
+ */
+function renderSummary(inspection) {
+	const { measurement, descriptors, rounds } = inspection;
+
+	if (rounds.length === 0) return "Nothing on the context surface yet.";
+
+	const lines = [];
+	lines.push("Context at a glance");
+	lines.push(
+		`  ${descriptors.length} nodes in ${rounds.length} round${rounds.length === 1 ? "" : "s"}, ~${measurement.surfaceTokens} tokens (request pressure ~${measurement.totalTokens})`
+	);
+	lines.push("");
+
+	// A raw per-node share rounds to 0% across hundreds of nodes and hides the
+	// real story. Ranking whole rounds is what actually surfaces the weight.
+	//
+	// The heading states the sort order explicitly: "heaviest rounds" alone
+	// left a reader unsure whether the list was chronological or ranked.
+	const heaviest = [...rounds].sort((a, b) => b.tokens - a.tokens).slice(0, 8);
+	const shownTokens = heaviest.reduce((sum, round) => sum + round.tokens, 0);
+	const share = measurement.surfaceTokens === 0
+		? 0
+		: Math.round((shownTokens / measurement.surfaceTokens) * 100);
+
+	// Quote a share only when the list is a real subset; "100% of the total"
+	// is noise when the session is short enough that every round is shown.
+	const scope =
+		heaviest.length < rounds.length
+			? ` — these ${heaviest.length} of ${rounds.length} rounds hold ~${formatTokens(shownTokens)} tok (${share}% of the total)`
+			: ` — all ${rounds.length} shown`;
+
+	lines.push(`Biggest rounds (largest first, not in time order)${scope}:`);
+	for (const round of heaviest) {
+		// The seq span is printed so this listing is actionable on its own: a
+		// reader who identifies the heaviest round can copy the span straight
+		// into `drop seq <a>-<b>` without a second `/prune list` round trip.
+		lines.push(
+			`  round ${String(round.index).padStart(3)}  ${formatTokens(round.tokens).padStart(6)} tok  seq ${String(round.startSeq).padEnd(5)} ${(round.title ?? round.opener).preview}`
+		);
+	}
+	lines.push("");
+
+	lines.push("Reading this: the rounds at the top use the most context, so removing");
+	lines.push("them frees the most. Rounds near the bottom barely matter.");
+	lines.push("");
+	lines.push("Next: to see WHAT a round contains, read it in time order:");
+	lines.push("  `/prune list`      the newest 15 rounds");
+	lines.push("  `/prune list 0-3`  rounds 0 through 3");
+	lines.push("  `/prune list all`  everything");
+	lines.push("Read-only: this command changes nothing in the session.");
+	return lines.join("\n");
+}
+
+/**
+ * Render `/prune list`.
+ *
+ * @param inspection - result of {@link inspect}.
+ * @param selection - parsed selection.
+ * @returns human-facing text.
+ */
+function renderList(inspection, selection) {
+	const { rounds } = inspection;
+
+	if (rounds.length === 0) return "Nothing on the context surface yet.";
+
+	let chosen;
+	let caption;
+
+	if (selection.kind === "all") {
+		chosen = rounds;
+		caption = `All ${rounds.length} rounds`;
+	} else if (selection.kind === "seq") {
+		// A seq selection names surface nodes, not round numbers, so it is
+		// matched by POSITION RANGE: every round whose span overlaps the
+		// requested node window. That makes it the readable counterpart of the
+		// exact line the panel seeds into the composer.
+		const nodes = inspection.measurement.nodes.map((node) => node.seq);
+		const fromIdx = nodes.indexOf(selection.from);
+		const toIdx = nodes.indexOf(selection.to);
+		if (fromIdx === -1 || toIdx === -1) {
+			return `Surface seq ${fromIdx === -1 ? selection.from : selection.to} is not on the surface.`;
+		}
+		chosen = rounds.filter((round) => {
+			const startIdx = nodes.indexOf(round.startSeq);
+			const endIdx = nodes.indexOf(round.endSeq);
+			return startIdx <= toIdx && endIdx >= Math.min(fromIdx, toIdx);
+		});
+		if (chosen.length === 0) {
+			return `No rounds overlap the span seq ${selection.from}-${selection.to}.`;
+		}
+		caption = `Seq ${selection.from}-${selection.to}`;
+	} else if (selection.kind === "range") {
+		chosen = rounds.filter((round) => round.index >= selection.from && round.index <= selection.to);
+		if (chosen.length === 0) {
+			return `No rounds in ${selection.from}-${selection.to}. This session has rounds 0-${rounds.length - 1}.`;
+		}
+		caption = `Rounds ${selection.from}-${selection.to}`;
+	} else {
+		const count = Math.max(1, selection.count);
+		chosen = rounds.slice(-count);
+		caption = `Newest ${chosen.length} of ${rounds.length} rounds`;
+	}
+
+	const shown = new Set(chosen);
+	const shownTokens = chosen.reduce((sum, round) => sum + round.tokens, 0);
+	const lines = [];
+
+	lines.push(`${caption}  (~${formatTokens(shownTokens)} tokens shown)`);
+	lines.push("  round     size  spans        what was said");
+	lines.push(...renderRounds(rounds, (round) => shown.has(round)));
+
+	if (chosen.length < rounds.length) {
+		lines.push("");
+		lines.push(
+			`  ... ${rounds.length - chosen.length} other rounds not shown; use \`/prune list all\` to include them`
+		);
+	}
+
+	return lines.join("\n");
+}
+
+/**
+ * Parse a `drop` argument into the surface spans to compact.
+ *
+ * Three forms exist, and the differences matter:
+ *
+ *   `drop seq 6050-6947, 9000-9100`  — explicit SURFACE SEQ spans. Unambiguous:
+ *                                      seqs are durable identifiers, and this is
+ *                                      the form the UI sends. Commas allow a
+ *                                      SCATTERED selection to be compacted in
+ *                                      one command: rounds 6, 9, 10 and 11
+ *                                      become `seq a-b, c-d` rather than two
+ *                                      commands the user must run in turn.
+ *   `drop 3-7, 12-14`               — ROUND spans, resolved against this
+ *                                      command's own round numbering.
+ *
+ * A round span is only safe because both sides use THIS command's numbering. A
+ * client that numbers rounds by its own rule and sends those indices compacts
+ * the wrong span — which is exactly what happened when the panel sent
+ * `drop 9-11` for a span the host numbered differently. Hence the explicit seq
+ * form for programmatic callers.
+ *
+ * Every span must be non-overlapping and strictly ascending, so the resulting
+ * replacement is unambiguous and the transaction can validate one contiguous
+ * region at a time.
+ *
+ * @param session - session supplying the surface.
+ * @param rounds - rounds from {@link inspect}, for the round form.
+ * @param spec - the argument without `--yes`.
+ * @returns `{ spans, label }` or `{ error }`. `spans` are `{start, end}` pairs.
+ */
+function resolveDropSpans(session, rounds, spec) {
+	const parts = spec.split(",").map((part) => part.trim()).filter((part) => part.length > 0);
+	// Distinguish "no range was given at all" from "a range could not be
+	// parsed". Both used to return `{ error: null }`, so `/prune drop garbage`
+	// was reported as "you gave me no range" rather than "I could not parse
+	// `garbage`" — a misleading diagnosis of a mistake the user can fix.
+	if (parts.length === 0) return { empty: true };
+
+	const nodes = session.surface.nodes;
+	const spans = [];
+
+	for (const part of parts) {
+		const seqForm = /^seq\s+(\d+)\s*-\s*(\d+)$/i.exec(part);
+		if (seqForm !== null) {
+			const start = Number.parseInt(seqForm[1], 10);
+			const end = Number.parseInt(seqForm[2], 10);
+			if (!nodes.includes(start)) return { error: `Surface seq ${start} is not on the surface.` };
+			if (!nodes.includes(end)) return { error: `Surface seq ${end} is not on the surface.` };
+			if (nodes.indexOf(start) > nodes.indexOf(end)) {
+				return { error: `Surface seq ${start} comes after ${end} on the surface.` };
+			}
+			// The label travels ON the span: keeping it in a parallel array
+			// meant the sort below reordered the spans while leaving the labels
+			// behind, so an overlap error named two spans that do not overlap.
+			spans.push({ start, end, label: `seq ${start}-${end}` });
+			continue;
+		}
+
+		const roundForm = /^(\d+)\s*-\s*(\d+)$/.exec(part);
+		if (roundForm === null) return { error: `Unrecognised range: ${part}` };
+
+		const from = Number.parseInt(roundForm[1], 10);
+		const to = Number.parseInt(roundForm[2], 10);
+		const span = resolveRoundSpan(rounds, from, to);
+		if (span.error !== undefined) return { error: span.error };
+		spans.push({ start: span.startSeq, end: span.endSeq, label: `rounds ${from}-${to}` });
+	}
+
+	// Order the spans by surface position, and reject an overlap: two spans
+	// sharing nodes would make the intended replacement ambiguous.
+	spans.sort((a, b) => nodes.indexOf(a.start) - nodes.indexOf(b.start));
+	for (let i = 1; i < spans.length; i += 1) {
+		const previousEnd = nodes.indexOf(spans[i - 1].end);
+		const currentStart = nodes.indexOf(spans[i].start);
+		if (currentStart <= previousEnd) {
+			// Name the pair by INPUT order where possible, because that is the
+			// order the user typed and can compare against.
+			return {
+				error: `Spans ${spans[i - 1].label} and ${spans[i].label} overlap on the surface; select non-overlapping rounds.`
+			};
+		}
+	}
+
+	return { spans, label: spans.map((span) => span.label).join(" + ") };
+}
+
+/**
+ * Resolve a round range into the inclusive surface-node span it covers.
+ *
+ * @param rounds - rounds from {@link inspect}.
+ * @param from - first round index, inclusive.
+ * @param to - last round index, inclusive.
+ * @returns `{ startSeq, endSeq, rounds }` or `{ error }`.
+ */
+function resolveRoundSpan(rounds, from, to) {
+	if (from > to) return { error: `Range ${from}-${to} is reversed.` };
+	if (rounds.length === 0) return { error: "There is nothing on the context surface to compact." };
+
+	const last = rounds.length - 1;
+	if (from < 0 || to > last) {
+		return { error: `Rounds ${from}-${to} are out of range. This session has rounds 0-${last}.` };
+	}
+
+	const chosen = rounds.filter((round) => round.index >= from && round.index <= to);
+	return {
+		startSeq: chosen[0].startSeq,
+		endSeq: chosen[chosen.length - 1].endSeq,
+		rounds: chosen
+	};
+}
+
+/**
+ * Execute `/prune drop <a>-<b> [--yes]`.
+ *
+ * Two phases: without `--yes` it reports exactly what would happen and stops;
+ * with `--yes` it runs the transaction. The confirmation exists because the
+ * model stops seeing the chosen rounds — the log keeps them for replay, but
+ * the conversation itself cannot get them back.
+ *
+ * @param ctx - context carrying the meter, compaction seam and summarizer deps.
+ * @param invocation - command invocation.
+ * @param args - text after `drop`.
+ * @returns the command result.
+ */
+async function handleDrop(ctx, invocation, args) {
+	// `--yes` is a FLAG, not a positional token: it is recognised wherever it
+	// appears and every occurrence is removed. A regex that replaced only the
+	// first match also consumed an adjacent character, so
+	// `/prune drop 2-3 --yes, 6-7` — the natural way to confirm a multi-span
+	// line the panel itself generates — was rejected as "no range given".
+	//
+	// The split is per comma-separated part as well as per whitespace, because
+	// the flag can sit against a neighbour (`1-1 --yes, 3-3`).
+	// Detection and removal must agree: both work on the same token split, so a
+	// form that has its flag stripped is always also treated as confirmed.
+	// Deriving `confirmed` from a separate regex let `1-1,--yes,3-3` strip the
+	// flag from the spec while reporting it was not confirmed — the preview
+	// would print a command the user had already confirmed.
+	const parts = args
+		.split(",")
+		.map((part) => part.split(/\s+/).filter((token) => token.length > 0));
+	const confirmed = parts.some((tokens) => tokens.includes("--yes"));
+	const spec = parts
+		.map((tokens) => tokens.filter((token) => token !== "--yes").join(" "))
+		.filter((part) => part.length > 0)
+		.join(", ");
+
+	const inspection = inspect(ctx, invocation.agent);
+	const resolved = resolveDropSpans(invocation.agent.session, inspection.rounds, spec);
+	if (resolved.empty === true) {
+		return {
+			kind: "error",
+			text: [
+				"`drop` needs at least one range:",
+				"  /prune drop 3-7              (rounds)",
+				"  /prune drop seq 6050-6947    (surface seqs)",
+				"  /prune drop 6-6, 9-11        (several ranges, comma-separated)",
+				"",
+				USAGE
+			].join("\n")
+		};
+	}
+	if (resolved.error !== undefined) return { kind: "error", text: resolved.error };
+
+	const nodes = invocation.agent.session.surface.nodes;
+	const { spans, label } = resolved;
+
+	// The canonical, always-re-parseable rendering of what was selected. Echoing
+	// the raw argument instead would print any empty parts the user typed
+	// (`seq 5-5 , ,`), which re-parses only because empty parts are filtered —
+	// so the "To proceed:" line could hand back a command that does not work.
+	const canonical = spans.map((span) => `seq ${span.start}-${span.end}`).join(", ");
+
+	// Every span must be a balanced boundary before anything is written, so a
+	// bad selection is refused once rather than midway through a partial run.
+	for (let i = 0; i < spans.length; i += 1) {
+		const balanceError = checkBalance(
+			invocation.agent.session,
+			{ start: spans[i].start, end: spans[i].end },
+			toolPairingBalancedBefore,
+			toolPairingBalancedAfter
+		);
+		if (balanceError !== undefined) {
+			// Name the boundary and the remedy concretely. "Try shifting that
+			// range by one round" was guesswork: the usual fix is to EXTEND the
+			// span so the assistant's tool call and its result stay together,
+			// and the user needs the seq to act on.
+			return {
+				kind: "error",
+				text: [
+					`Cannot compact span ${i + 1} of ${spans.length} (seq ${spans[i].start}..${spans[i].end}): ${balanceError}.`,
+					"That boundary separates a tool call from its result, which would corrupt the remaining conversation.",
+					`Extend the span by one round at that end, or use the round form (\`/prune drop <a>-<b>\`), which never splits a step.`
+				].join("\n")
+			};
+		}
+	}
+
+	// Everything about to leave the model's view, described well enough to make
+	// an irreversible decision from. This is the only place that can catch a
+	// mis-aimed span before it commits, so it reports composition and the single
+	// largest node rather than repeating the same opener previews the listing
+	// already showed.
+	const spanDetails = spans.map((span) => {
+		const startIdx = nodes.indexOf(span.start);
+		const endIdx = nodes.indexOf(span.end);
+		const seqs = nodes.slice(startIdx, endIdx + 1);
+		const priced = inspection.measurement.nodes.slice(startIdx, endIdx + 1);
+		// Rounds whose START seq falls inside the span. A round that merely
+		// reaches into the span from before it is not "touched" — nothing of it
+		// is dropped — and counting it overstated the estimate.
+		const contained = inspection.rounds.filter((round) => {
+			const roundIdx = nodes.indexOf(round.startSeq);
+			return roundIdx >= startIdx && roundIdx <= endIdx;
+		});
+		const largest = priced.reduce(
+			(best, node) => (best === undefined || node.tokens > best.tokens ? node : best),
+			undefined
+		);
+		return { span, seqs, priced, contained, largest };
+	});
+
+	const droppedSeqs = new Set(spanDetails.flatMap((detail) => detail.seqs));
+	const droppedTokens = inspection.measurement.nodes
+		.filter((node) => droppedSeqs.has(node.seq))
+		.reduce((sum, node) => sum + node.tokens, 0);
+	const keptTokens = inspection.measurement.surfaceTokens - droppedTokens;
+
+	// A span that does not begin at a round boundary and end at one cuts a
+	// conversation turn in half: the round's remaining nodes stay on the surface
+	// with their human question or its answer missing. The round form can never
+	// produce this, but the seq form — which is what the panel sends — can, so a
+	// user editing a seeded line can create it by accident.
+	//
+	// Alignment is judged against the rounds the span CONTAINS: a span is clean
+	// when it starts no LATER than its first contained round's first node and
+	// ends exactly at its last contained round's end. It may start EARLIER —
+	// pulling in the leading system prompt or runtime snapshot is legitimate and
+	// is what the panel does when a user selects only the first visible round.
+	//
+	// An earlier version required the span's endpoints to be members of the
+	// GLOBAL sets of round starts/ends, which false-positived on a legitimate
+	// "system head plus whole rounds" span and also suppressed the round-count
+	// sentence for a correct command.
+	const midRound = spans
+		.map((span, i) => {
+			const startIdx = nodes.indexOf(span.start);
+			const endIdx = nodes.indexOf(span.end);
+			const contained = inspection.rounds.filter((round) => {
+				const roundIdx = nodes.indexOf(round.startSeq);
+				return roundIdx >= startIdx && roundIdx <= endIdx;
+			});
+			// Nothing contained means the span addresses no whole round at all.
+			if (contained.length === 0) return i + 1;
+			const first = contained[0];
+			const last = contained[contained.length - 1];
+			const startsCleanly = nodes.indexOf(first.startSeq) >= startIdx;
+			const endsCleanly = last.endSeq === span.end;
+			return startsCleanly && endsCleanly ? null : i + 1;
+		})
+		.filter((index) => index !== null);
+
+	if (!confirmed) {
+		const lines = [];
+		const droppedRounds = spanDetails.flatMap((detail) => detail.contained);
+		const notices = droppedRounds.reduce((sum, round) => sum + round.injected, 0);
+
+		lines.push(
+			`Would compact ${label} — ${spans.length} span${spans.length === 1 ? "" : "s"}, ` +
+				`${droppedRounds.length} round${droppedRounds.length === 1 ? "" : "s"}, ` +
+				`${droppedSeqs.size} nodes, ~${formatTokens(droppedTokens)} tok:`
+		);
+		lines.push("");
+
+		if (midRound.length > 0) {
+			lines.push(
+				`  WARNING: span ${midRound.join(", ")} cuts through a conversation round rather than covering whole rounds.`
+			);
+			lines.push(
+				"  Part of a round would be replaced while the rest stays, so the model would see"
+			);
+			lines.push("  an answer with its question missing (or the reverse). Prefer whole rounds.");
+			lines.push("");
+		}
+
+		for (let i = 0; i < spanDetails.length; i += 1) {
+			const detail = spanDetails[i];
+			lines.push(`  span ${i + 1}  seq ${detail.span.start}..${detail.span.end}  ~${formatTokens(detail.priced.reduce((sum, n) => sum + n.tokens, 0))} tok`);
+			for (const round of detail.contained) {
+				const notice =
+					round.injected > 0 ? `  (+${round.injected} notice${round.injected === 1 ? "" : "s"})` : "";
+				lines.push(
+					`          round ${String(round.index).padStart(3)}  ${formatTokens(round.tokens).padStart(6)} tok  ${(round.title ?? round.opener).preview}${notice}`
+				);
+			}
+		}
+
+		// Composition, so a round whose opener hides a long tool chain is not
+		// mistaken for a short question.
+		const droppedNodes = inspection.measurement.nodes.filter((node) => droppedSeqs.has(node.seq));
+		const byRole = new Map();
+		for (const descriptor of inspection.descriptors) {
+			if (!droppedSeqs.has(descriptor.seq)) continue;
+			byRole.set(descriptor.role, (byRole.get(descriptor.role) ?? 0) + 1);
+		}
+		const composition = [...byRole.entries()]
+			.map(([role, count]) => `${count} ${role}`)
+			.join(", ");
+		lines.push("");
+		lines.push(`  inside: ${composition || "(nothing)"}`);
+		if (notices > 0) {
+			lines.push(`  ${notices} of these nodes are harness notices, not conversation.`);
+		}
+		const biggest = spanDetails
+			.map((detail) => detail.largest)
+			.filter((node) => node !== undefined)
+			.sort((a, b) => b.tokens - a.tokens)[0];
+		if (biggest !== undefined) {
+			const descriptor = inspection.descriptors.find((d) => d.seq === biggest.seq);
+			lines.push(
+				`  largest single node: seq ${biggest.seq} (~${formatTokens(biggest.tokens)} tok) — ${descriptor?.preview ?? ""}`
+			);
+		}
+
+		lines.push("");
+		lines.push(
+			`BECOMES: ${spans.length} checkpoint${spans.length === 1 ? "" : "s"} replacing those ${droppedSeqs.size} nodes.`
+		);
+		// Only quote a round count when every span covers whole rounds; a
+		// round-cutting span drops nodes without retiring a round, so the naive
+		// arithmetic could report the round count INCREASING — pruning can never
+		// add a round, and a sentence that says it can destroys trust in the
+		// whole preview.
+		if (midRound.length === 0) {
+			const after = inspection.rounds.length - droppedRounds.length + spans.length;
+			lines.push(
+				`The surface goes from ${inspection.rounds.length} rounds to ${after}, and ~${formatTokens(keptTokens)} tok stay as they are.`
+			);
+		} else {
+			lines.push(
+				`The surface keeps roughly ${formatTokens(keptTokens)} tok of its ${formatTokens(inspection.measurement.surfaceTokens)} tok; ` +
+					"the round count is not quoted because the spans are not round-aligned."
+			);
+		}
+		lines.push("");
+		// What the model will actually be told. This is the real risk of the
+		// operation: the checkpoint ASSERTS a conclusion, so a span the user has
+		// not re-read lets the summarizer decide what counts as true.
+		lines.push("The checkpoints are CORRECTIVE: each marks the dropped reasoning as");
+		lines.push('"Retired Exploration — DO NOT TRUST" and asserts an Authoritative Conclusion.');
+		lines.push("Whatever the summarizer concludes is what the model believes afterwards.");
+		lines.push("This cannot be undone: the session log keeps the originals for replay, but the");
+		lines.push("conversation itself cannot get them back.");
+		lines.push("");
+		lines.push(`To proceed:  /prune drop ${canonical} --yes`);
+		return { kind: "success", text: lines.join("\n") };
+	}
+
+	try {
+		// One transaction per span. They are independent regions, and the
+		// transaction's own lock serializes them, so a failure part-way leaves
+		// the already-committed spans in place and reports how far it got.
+		const results = [];
+		for (let i = 0; i < spans.length; i += 1) {
+			const span = spans[i];
+			try {
+				const result = await compactExplicitRegion({
+					session: invocation.agent.session,
+					agent: invocation.agent,
+					start: span.start,
+					end: span.end,
+					summarize: (input, agent, signal) => summarizeForDrop(ctx, input, agent, signal),
+					meter: ctx.tokenMeter,
+					signal: invocation.signal,
+					sourceCommandId: invocation.commandId,
+					balancedBefore: toolPairingBalancedBefore,
+					balancedAfter: toolPairingBalancedAfter,
+					flush: async () => {
+						// Durability is best-effort here: the `sessions` service may be
+						// absent depending on the composition, and a missing flush
+						// must not turn a committed compaction into a failure.
+						const sessions = ctx.get("sessions");
+						if (sessions !== undefined && sessions !== null && typeof sessions.flush === "function") {
+							await sessions.flush(invocation.agent.session);
+						}
+					}
+				});
+				results.push({ span, result });
+			} catch (error) {
+				if (results.length === 0) throw error;
+				return {
+					kind: "error",
+					text: `Compacted ${results.length} of ${spans.length} spans; span ${i + 1} (seq ${span.start}..${span.end}) failed:\n${String(error?.message ?? error)}`
+				};
+			}
+		}
+
+		const totalNodes = results.reduce((sum, r) => sum + r.result.shadowedSeqs.length, 0);
+		const totalTokens = results.reduce((sum, r) => sum + r.result.shadowedTokenCount, 0);
+		return {
+			kind: "success",
+			text: [
+				`Compacted ${label} (${results.length} checkpoint${results.length === 1 ? "" : "s"}, ${totalNodes} nodes, ~${totalTokens} tokens).`,
+				"Everything outside those spans is unchanged."
+			].join(" "),
+			sourceEventSeq: results[results.length - 1].result.summarySeq
+		};
+	} catch (error) {
+		if (invocation.signal.aborted) {
+			// State the outcome, not just the event. The transaction closes its
+			// lock and rethrows before any span commits, so nothing changed —
+			// but a user who cancelled mid-way cannot know that unaided.
+			return {
+				kind: "error",
+				text: "Prune cancelled. Nothing was changed; no spans were committed."
+			};
+		}
+		if (error instanceof ManualCompactionError) {
+			// Surface the underlying reason when it is more specific than the
+			// classification: "no provider/model available" must not be
+			// reported as a shrink failure, which would send the user hunting
+			// for a range problem that does not exist.
+			const cause = error.cause?.message ?? "";
+			const detail = cause.length > 0 ? ` — ${cause}` : "";
+			const message =
+				error.code === "busy"
+					? "Prune needs an idle agent: a turn is running, or another compaction holds the lock. Retry when idle."
+					: error.code === "changed"
+						? "The history changed while the summary was being written, so nothing was replaced. Retry."
+						: error.code === "summary"
+							? `Prune could not write a checkpoint for those rounds${detail}`
+							: error.code === "persistence"
+								? "Prune succeeded but the session could not be saved. Inspect the session before continuing."
+								: "Prune did not finish cleanly; some history may have changed. Inspect before retrying.";
+			return { kind: "error", text: message };
+		}
+		throw error;
+	}
+}
+
+/**
+ * Produce the correction checkpoint for a drop, reusing the plugin's backend.
+ *
+ * The corrective instruction is the whole point of this plugin: the replaced
+ * span is summarised as a RETIRED direction plus an authoritative conclusion,
+ * not as a neutral transcript, so the model stops treating the dropped rounds
+ * as live reasoning.
+ *
+ * `summarize()` is a prototype method that reads only `this.ctx` and
+ * `this.config`, so it can be applied to a plain object without constructing a
+ * Cordis service. That keeps this call independent of how (or whether) the
+ * corrective backend is mounted as `ctx.compaction`.
+ *
+ * @param ctx - context carrying the LLM service.
+ * @param input - replayed conversation prefix to condense.
+ * @param agent - supplies routed-model history and fallback model.
+ * @param signal - optional cancellation.
+ * @returns `{ summary, provider, model, ... }`.
+ */
+async function summarizeForDrop(ctx, input, agent, signal) {
+	// Resolved at call time rather than injected, because `compaction` lives
+	// inside the agent preset in a Web profile while this plugin is mounted on
+	// the host plane.
+	const llm = ctx.get("llm");
+	if (llm === undefined || llm === null) {
+		throw new Error(
+			"the llm service is unavailable, so no summary can be written; `drop` needs a booted agent with a model route"
+		);
+	}
+
+	const mounted = ctx.get("compaction");
+	const receiver = {
+		ctx: { llm },
+		config: {
+			summarizationProvider: "",
+			summarizationModel: "",
+			maxTokens: 8192,
+			...(mounted?.config === undefined ? {} : mounted.config)
+		}
+	};
+	return CorrectiveCompactionEngine.prototype.summarize.call(receiver, input, agent, signal);
+}
+
+/**
+ * Register `/prune`.
+ *
+ * @param ctx - context carrying the command registry, meter and compaction seam.
+ */
+function apply(ctx) {
+	const handler = (invocation) => {
+		const raw = invocation.rawInput.trim();
+
+		if (raw.length === 0) {
+			return { kind: "success", text: renderSummary(inspect(ctx, invocation.agent)) };
+		}
+
+		// `list` opens the listing branch; anything else is a usage error. A
+		// separator is required after `list` so `listx` is rejected rather than
+		// silently treated as a count.
+		if (raw === "list") {
+			return {
+				kind: "success",
+				text: renderList(inspect(ctx, invocation.agent), { kind: "newest", count: DEFAULT_ROUNDS })
+			};
+		}
+
+		if (raw.startsWith("list") && /^list\s/.test(raw)) {
+			const selection = parseSelection(raw.slice(4));
+			if (selection.error !== undefined) {
+				return { kind: "error", text: `${selection.error}\n\n${USAGE}` };
+			}
+			return { kind: "success", text: renderList(inspect(ctx, invocation.agent), selection) };
+		}
+
+		if (raw === "drop" || (raw.startsWith("drop") && /^drop\s/.test(raw))) {
+			return handleDrop(ctx, invocation, raw === "drop" ? "" : raw.slice(4).trim());
+		}
+
+		// A bare USAGE dump leaves the user unsure whether their input was even
+		// seen. Name the offending token, then show the grammar.
+		const first = raw.split(/\s+/)[0];
+		return { kind: "error", text: `Unknown argument: ${first}\n\n${USAGE}` };
+	};
+
+	ctx.effect(function* () {
+		yield ctx.commands.register({
+			definitionId: CommandDefinitionId("dsh-context-pruner"),
+			name: "prune",
+			description: "Inspect the context, or compact chosen rounds into one checkpoint",
+			input: { hint: "list [n|all|a-b|seq a-b] | drop <a>-<b> [seq a-b] [--yes]" },
+			handler
+		});
+	}, "context-pruner lifecycle");
+}
+
+export { apply, inject, name };