pi-blackhole 0.2.2 → 0.2.3

package/README.md

@@ -5,8 +5,14 @@ Algorithmic compaction + session-aware observational memory for [Pi](https://git
 Combines [pi-vcc](https://github.com/sting8k/pi-vcc) and [pi-observational-memory](https://github.com/elpapi42/pi-observational-memory) with unified configuration, per-worker model fallback chains, persisted cooldowns, and a manual flush mode.
 
 > This is a frankenmerge. I liked both extensions but they were not compatible - observational memory hooked into Pi's default compaction and prevented pi-vcc from working. So I merged them, made them share the same hook and output, and added the things both were missing: fallback chains, cooldowns, and a toggle between them.
+> Please also see the [`CHANGELOG.md`](CHANGELOG.md)
+
+### Lockstep with upstreams
+
+pi-blackhole tracks both upstream repositories via a [lockstep audit system](https://github.com/k0valik/pi-blackhole/tree/lockstep/2026-05-27/.pi/skills/lockstep) that classifies every new upstream commit as safe-to-port, modified (needs review), rewritten (skip), or orphan (needs mapping). The goal is to lift bugfixes, prompts improvements, and compatible features without breaking existing users or rolling back intentional divergences. Ported changes are reviewed per-commit with human approval — nothing is blindly merged. See [SKILL.md](.pi/skills/lockstep/SKILL.md) for the full workflow. An example execution (including rationale for skipped changes) is documented in [PR #8](https://github.com/k0valik/pi-blackhole/pull/8).
+
+#### For easy setup pass the [`llms.txt`](llms.txt) llms.txt to your agent and it will guide you through the config without needing to read all the docs if you're as lazy as me.
 
-#### For easy setup pass the [`llms.txt`](llms.txt) llms.txt to your agent and it will guide you through the config without needing to read all the docs if you're as lazy as me
 
 # Demo
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-blackhole",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Unified compaction + observational memory extension for Pi — compresses conversation context while preserving durable observations and reflections",
   "license": "MIT",
   "main": "index.ts",

package/src/core/unified-config.ts

@@ -44,6 +44,16 @@ export interface UnifiedConfig {
 	compactAfterTokens: number;
 	/** Observation pool token pressure for full fold. */
 	observationsPoolMaxTokens: number;
+	/** Target token budget for the observation pool (dropper aims here).
+	 *  Optional; defaults to half of observationsPoolMaxTokens when unset.
+	 *  Must be less than observationsPoolMaxTokens.
+	 *
+	 *  NOTE: Ported from upstream as forward-compat (no-op in our pool algorithm).
+	 *  Upstream renamed budgetTokens→targetTokens (52b5844) and uses this
+	 *  for their tokensOverTarget / avgTokensPerObservation drop calculation.
+	 *  We keep our ratio-based urgency algorithm; this knob exists so future
+	 *  lockstep iterations don't diverge on the config shape. */
+	observationsPoolTargetTokens: number;
 	/** Max prompt tokens for reflector model input (rolling window cap). */
 	reflectorInputMaxTokens: number;
 	/** Max prompt tokens for dropper model input (rolling window cap). */
@@ -96,6 +106,7 @@ export const DEFAULTS: UnifiedConfig = {
 	reflectAfterTokens: 25_000,
 	compactAfterTokens: 81_000,
 	observationsPoolMaxTokens: 20_000,
+	observationsPoolTargetTokens: 10_000,
 	reflectorInputMaxTokens: 80_000,
 	dropperInputMaxTokens: 80_000,
 	observerChunkMaxTokens: 40_000,
@@ -160,7 +171,7 @@ function parseConfig(raw: Record<string, unknown>): Partial<UnifiedConfig> {
 	if (typeof raw.debugLog === "boolean") c.debugLog = raw.debugLog;
 
 	// Positive integers
-	const numKeys = ["observeAfterTokens", "reflectAfterTokens", "compactAfterTokens", "observationsPoolMaxTokens", "reflectorInputMaxTokens", "dropperInputMaxTokens", "observerChunkMaxTokens", "observerPreambleMaxTokens", "agentMaxTurns"] as const;
+	const numKeys = ["observeAfterTokens", "reflectAfterTokens", "compactAfterTokens", "observationsPoolMaxTokens", "observationsPoolTargetTokens", "reflectorInputMaxTokens", "dropperInputMaxTokens", "observerChunkMaxTokens", "observerPreambleMaxTokens", "agentMaxTurns"] as const;
 	for (const k of numKeys) {
 		const v = positiveInt(raw[k]);
 		if (v !== undefined) (c as Record<string, unknown>)[k] = v;
@@ -238,7 +249,15 @@ export function loadUnifiedConfig(cwd: string): UnifiedConfig {
 		else if (["0", "false", "no", "off"].includes(v)) parsed.passive = false;
 	}
 
-	return { ...DEFAULTS, ...parsed };
+	// Merge defaults then override
+	const merged = { ...DEFAULTS, ...parsed };
+
+	// Derive observationsPoolTargetTokens if unset or invalid (must be < max)
+	if (merged.observationsPoolTargetTokens >= merged.observationsPoolMaxTokens) {
+		merged.observationsPoolTargetTokens = Math.floor(merged.observationsPoolMaxTokens / 2);
+	}
+
+	return merged;
 }
 
 /**

package/src/om/agents/dropper/agent.ts

@@ -9,9 +9,18 @@ import { agentLoop, type AgentContext, type AgentLoopConfig, type AgentTool } fr
 import type { Message, Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
 import { Type } from "@earendil-works/pi-ai";
 import type { Static } from "typebox";
+import { debugLog } from "../../debug-log.js";
 import { AGENT_LOOP_MAX_TOKENS, boundedMaxTokens } from "../../model-budget.js";
-import { observationToSummaryLine, reflectionToSummaryLine, type Observation, type Reflection } from "../../ledger/index.js";
+import { reflectionToSummaryLine, type Observation, type Reflection } from "../../ledger/index.js";
 import { DROPPER_SYSTEM } from "./prompts.js";
+import {
+	REFLECTION_COVERAGE_DROP_RANK,
+	coverageTierForObservation,
+	observationToDropperLine,
+	reflectionCoverageMap,
+	summarizeCoverageByRelevance,
+	summarizeCoverageByRelevanceForIds,
+} from "./coverage.js";
 
 interface RunDropperArgs {
 	model: Model<any>;
@@ -81,6 +90,13 @@ export function maxDropCountForPool(observations: readonly Observation[], observ
 	return Math.max(1, Math.floor(droppableCount * dropRatio));
 }
 
+function relevanceCounts(observations: readonly Observation[]): Record<Observation["relevance"], number> {
+	return observations.reduce<Record<Observation["relevance"], number>>((counts, observation) => {
+		if (observation.relevance in counts) counts[observation.relevance]++;
+		return counts;
+	}, { low: 0, medium: 0, high: 0, critical: 0 });
+}
+
 export function normalizeDropObservationIds(
 	ids: readonly string[] | undefined,
 	observations: readonly Observation[],
@@ -92,7 +108,6 @@ export function normalizeDropObservationIds(
 	for (const id of ids) {
 		const observation = allowed.get(id);
 		if (!observation) continue;
-		if (observation.relevance === "critical") continue;
 		if (seen.has(id)) continue;
 		seen.add(id);
 		result.push(id);
@@ -100,14 +115,21 @@ export function normalizeDropObservationIds(
 	return result.length > 0 ? result : undefined;
 }
 
+function timestampRank(timestamp: string): number {
+	const parsed = Date.parse(timestamp);
+	return Number.isFinite(parsed) ? parsed : Number.POSITIVE_INFINITY;
+}
+
 export function selectDropCandidates(
 	ids: readonly string[],
 	observations: readonly Observation[],
 	maxDrops: number,
+	reflections: readonly Reflection[] = [],
 ): string[] {
 	if (maxDrops <= 0 || ids.length === 0) return [];
 
 	const byId = new Map(observations.map((observation) => [observation.id, observation]));
+	const coverageById = reflectionCoverageMap(observations, reflections);
 	const firstProposalIndex = new Map<string, number>();
 	for (let i = 0; i < ids.length; i++) {
 		const id = ids[i];
@@ -117,11 +139,16 @@ export function selectDropCandidates(
 	return Array.from(firstProposalIndex.entries())
 		.map(([id, index]) => ({ id, index, observation: byId.get(id) }))
 		.filter((candidate): candidate is { id: string; index: number; observation: Observation } =>
-			candidate.observation !== undefined && candidate.observation.relevance !== "critical"
+			candidate.observation !== undefined
 		)
 		.sort((a, b) => {
+			const coverageDelta = REFLECTION_COVERAGE_DROP_RANK[coverageTierForObservation(a.observation, coverageById)]
+				- REFLECTION_COVERAGE_DROP_RANK[coverageTierForObservation(b.observation, coverageById)];
 			const relevanceDelta = RELEVANCE_DROP_RANK[a.observation.relevance] - RELEVANCE_DROP_RANK[b.observation.relevance];
-			return relevanceDelta || a.index - b.index;
+			const aAge = timestampRank(a.observation.timestamp);
+			const bAge = timestampRank(b.observation.timestamp);
+			const ageDelta = aAge === bAge ? 0 : aAge - bAge;
+			return coverageDelta || relevanceDelta || ageDelta || a.index - b.index;
 		})
 		.slice(0, maxDrops)
 		.map((candidate) => candidate.id);
@@ -135,10 +162,42 @@ export async function runDropper(args: RunDropperArgs): Promise<string[] | undef
 	const fullness = observationPoolFullness(observationTokens, budgetTokens);
 	const urgency = dropUrgencyForFullness(fullness);
 	const maxDropsAllowed = maxDropCountForPool(observations, observationTokens, budgetTokens);
-	if (maxDropsAllowed <= 0) return undefined;
+	const coverageById = reflectionCoverageMap(observations, reflections);
+	const coverageSummaryByRelevance = summarizeCoverageByRelevance(observations, coverageById);
+	debugLog("dropper.agent_start", {
+		activeObservationCount: observations.length,
+		reflectionCount: reflections.length,
+		observationTokens,
+		budgetTokens,
+		fullness,
+		urgency,
+		maxDropsAllowed,
+		relevanceCounts: relevanceCounts(observations),
+		coverageSummaryByRelevance,
+	});
+	if (maxDropsAllowed <= 0) {
+		debugLog("dropper.result", {
+			reason: "not_over_target",
+			toolCallCount: 0,
+			rawRequestedIdsCount: 0,
+			acceptedCandidateCount: 0,
+			selectedDropsCount: 0,
+			selectedDropTokens: 0,
+			selectedCoverageSummaryByRelevance: summarizeCoverageByRelevanceForIds([], observations, coverageById),
+			maxDropsAllowed,
+		});
+		return undefined;
+	}
 
 	const proposedDropIds: string[] = [];
 	const proposed = new Set<string>();
+	const allowed = new Map(observations.map((observation) => [observation.id, observation]));
+	let toolCallCount = 0;
+	let rawRequestedIdsCount = 0;
+	let missingIdsCount = 0;
+	let criticalCandidateIdsCount = 0;
+	let duplicateInRequestCount = 0;
+	let duplicateInRunCount = 0;
 
 	const dropObservations: AgentTool<typeof DropObservationsSchema> = {
 		name: "drop_observations",
@@ -146,14 +205,51 @@ export async function runDropper(args: RunDropperArgs): Promise<string[] | undef
 		description: "Propose active observation ids that are safe to remove from compacted memory.",
 		parameters: DropObservationsSchema,
 		execute: async (_id, params: DropObservationsArgs) => {
-			const normalized = normalizeDropObservationIds(params.ids, observations) ?? [];
+			toolCallCount++;
+			rawRequestedIdsCount += params.ids.length;
+			const seenInRequest = new Set<string>();
 			let added = 0;
-			for (const id of normalized) {
-				if (proposed.has(id)) continue;
+			let requestMissingIds = 0;
+			let requestCriticalCandidateIds = 0;
+			let requestDuplicateIds = 0;
+			let requestDuplicateInRunIds = 0;
+			for (const id of params.ids) {
+				const observation = allowed.get(id);
+				if (!observation) {
+					missingIdsCount++;
+					requestMissingIds++;
+					continue;
+				}
+				if (seenInRequest.has(id)) {
+					duplicateInRequestCount++;
+					requestDuplicateIds++;
+					continue;
+				}
+				seenInRequest.add(id);
+				if (proposed.has(id)) {
+					duplicateInRunCount++;
+					requestDuplicateInRunIds++;
+					continue;
+				}
 				proposed.add(id);
 				proposedDropIds.push(id);
+				if (observation.relevance === "critical") {
+					criticalCandidateIdsCount++;
+					requestCriticalCandidateIds++;
+				}
 				added++;
 			}
+			debugLog("dropper.tool_call", {
+				toolCallCount,
+				rawRequestedIdsCount: params.ids.length,
+				acceptedIdsCount: added,
+				missingIdsCount: requestMissingIds,
+				criticalCandidateIdsCount: requestCriticalCandidateIds,
+				duplicateInRequestCount: requestDuplicateIds,
+				duplicateInRunCount: requestDuplicateInRunIds,
+				totalCandidates: proposedDropIds.length,
+				maxDropsAllowed,
+			});
 			return {
 				content: [{ type: "text", text: `Queued ${added} drop candidate${added === 1 ? "" : "s"}. Candidates this run: ${proposedDropIds.length}. Maximum drops allowed: ${maxDropsAllowed}.` }],
 				details: { added, totalCandidates: proposedDropIds.length, maxDropsAllowed },
@@ -166,7 +262,7 @@ export async function runDropper(args: RunDropperArgs): Promise<string[] | undef
 		? `EXISTING ACTIVE OBSERVATIONS (for context only — these are NOT candidates for dropping):\n${args.existingObservationsSummary}\n\n`
 		: '';
 
-	const userText = `CURRENT REFLECTIONS:\n${joinOrEmpty(reflections.map(reflectionToSummaryLine))}\n\n${existingObservationsContext}NEW OBSERVATIONS TO EVALUATE FOR DROPPING:\n${joinOrEmpty(observations.map(observationToSummaryLine))}\n\nObservation pool pressure: ~${observationTokens.toLocaleString()} tokens; target budget: ~${budgetTokens.toLocaleString()} tokens; fullness: ~${fullnessPercent.toLocaleString()}%.\nDrop urgency: ${urgency}.\nMaximum drops allowed this run: ${maxDropsAllowed.toLocaleString()} observation${maxDropsAllowed === 1 ? "" : "s"}.\nThis maximum is a hard upper bound, not a target. Drop fewer or none if fewer observations are clearly safe.`;
+	const userText = `CURRENT REFLECTIONS:\n${joinOrEmpty(reflections.map(reflectionToSummaryLine))}\n\n${existingObservationsContext}NEW OBSERVATIONS TO EVALUATE FOR DROPPING:\n${joinOrEmpty(observations.map((observation) => observationToDropperLine(observation, coverageTierForObservation(observation, coverageById))))}\n\nObservation pool pressure: ~${observationTokens.toLocaleString()} tokens; target budget: ~${budgetTokens.toLocaleString()} tokens; fullness: ~${fullnessPercent.toLocaleString()}%.\nDrop urgency: ${urgency}.\nMaximum drops allowed this run: ${maxDropsAllowed.toLocaleString()} observation${maxDropsAllowed === 1 ? "" : "s"}.\nThis maximum is a hard upper bound, not a target. Drop fewer or none if fewer observations are clearly safe.`;
 	const prompts: Message[] = [{ role: "user", content: [{ type: "text", text: userText }], timestamp: Date.now() }];
 	const context: AgentContext = { systemPrompt: DROPPER_SYSTEM, messages: [], tools: [dropObservations as AgentTool<any>] };
 	const reasoning = (model as { reasoning?: unknown }).reasoning;
@@ -199,6 +295,28 @@ export async function runDropper(args: RunDropperArgs): Promise<string[] | undef
 	}
 	await stream.result();
 	if (agentError && proposedDropIds.length === 0) throw new Error(`Dropper API error: ${agentError}`);
-	const droppedIds = selectDropCandidates(proposedDropIds, observations, maxDropsAllowed);
+	const droppedIds = selectDropCandidates(proposedDropIds, observations, maxDropsAllowed, reflections);
+	const reason = droppedIds.length > 0
+		? "selected_nonempty"
+		: toolCallCount === 0
+			? "no_tool_call"
+			: proposedDropIds.length === 0
+				? "all_filtered"
+				: "selected_empty";
+	const selectedDropTokens = droppedIds.reduce((sum, id) => sum + (allowed.get(id)?.tokenCount ?? 0), 0);
+	debugLog("dropper.result", {
+		reason,
+		toolCallCount,
+		rawRequestedIdsCount,
+		missingIdsCount,
+		criticalCandidateIdsCount,
+		duplicateInRequestCount,
+		duplicateInRunCount,
+		acceptedCandidateCount: proposedDropIds.length,
+		selectedDropsCount: droppedIds.length,
+		selectedDropTokens,
+		selectedCoverageSummaryByRelevance: summarizeCoverageByRelevanceForIds(droppedIds, observations, coverageById),
+		maxDropsAllowed,
+	});
 	return droppedIds.length > 0 ? droppedIds : undefined;
 }

package/src/om/agents/dropper/coverage.ts

@@ -0,0 +1,128 @@
+import type { Observation, Reflection } from "../../ledger/index.js";
+
+export const REFLECTION_COVERAGE_TIERS = ["none", "partial", "strong"] as const;
+export type ReflectionCoverageTier = typeof REFLECTION_COVERAGE_TIERS[number];
+
+type Relevance = Observation["relevance"];
+
+type CoverageBucket = Record<ReflectionCoverageTier, { count: number; tokens: number }>;
+export type CoverageSummaryByRelevance = Record<Relevance, CoverageBucket>;
+export type CoverageTransitionSummaryByRelevance = Record<Relevance, Record<string, { count: number; tokens: number }>>;
+
+export const REFLECTION_COVERAGE_DROP_RANK: Record<ReflectionCoverageTier, number> = {
+	strong: 0,
+	partial: 1,
+	none: 2,
+};
+
+export function reflectionSupportCounts(reflections: readonly Reflection[]): Map<string, number> {
+	const counts = new Map<string, number>();
+	for (const reflection of reflections) {
+		const uniqueIds = new Set(reflection.supportingObservationIds);
+		for (const id of uniqueIds) counts.set(id, (counts.get(id) ?? 0) + 1);
+	}
+	return counts;
+}
+
+export function reflectionCoverageTierForCount(count: number): ReflectionCoverageTier {
+	if (count <= 0) return "none";
+	if (count === 1) return "partial";
+	return "strong";
+}
+
+export function reflectionCoverageMap(
+	observations: readonly Observation[],
+	reflections: readonly Reflection[],
+): Map<string, ReflectionCoverageTier> {
+	const counts = reflectionSupportCounts(reflections);
+	return new Map(observations.map((observation) => [
+		observation.id,
+		reflectionCoverageTierForCount(counts.get(observation.id) ?? 0),
+	]));
+}
+
+function emptyCoverageBucket(): CoverageBucket {
+	return {
+		none: { count: 0, tokens: 0 },
+		partial: { count: 0, tokens: 0 },
+		strong: { count: 0, tokens: 0 },
+	};
+}
+
+export function emptyCoverageSummaryByRelevance(): CoverageSummaryByRelevance {
+	return {
+		low: emptyCoverageBucket(),
+		medium: emptyCoverageBucket(),
+		high: emptyCoverageBucket(),
+		critical: emptyCoverageBucket(),
+	};
+}
+
+export function summarizeCoverageByRelevance(
+	observations: readonly Observation[],
+	coverageById: ReadonlyMap<string, ReflectionCoverageTier>,
+): CoverageSummaryByRelevance {
+	const summary = emptyCoverageSummaryByRelevance();
+	for (const observation of observations) {
+		const tier = coverageById.get(observation.id) ?? "none";
+		const bucket = summary[observation.relevance][tier];
+		bucket.count++;
+		bucket.tokens += observation.tokenCount;
+	}
+	return summary;
+}
+
+export function summarizeCoverageByRelevanceForIds(
+	ids: readonly string[],
+	observations: readonly Observation[],
+	coverageById: ReadonlyMap<string, ReflectionCoverageTier>,
+): CoverageSummaryByRelevance {
+	const byId = new Map(observations.map((observation) => [observation.id, observation]));
+	const selected = ids.flatMap((id) => {
+		const observation = byId.get(id);
+		return observation ? [observation] : [];
+	});
+	return summarizeCoverageByRelevance(selected, coverageById);
+}
+
+export function emptyCoverageTransitionSummaryByRelevance(): CoverageTransitionSummaryByRelevance {
+	return {
+		low: {},
+		medium: {},
+		high: {},
+		critical: {},
+	};
+}
+
+export function summarizeCoverageTransitionsByRelevance(
+	observations: readonly Observation[],
+	beforeCoverageById: ReadonlyMap<string, ReflectionCoverageTier>,
+	afterCoverageById: ReadonlyMap<string, ReflectionCoverageTier>,
+): CoverageTransitionSummaryByRelevance {
+	const summary = emptyCoverageTransitionSummaryByRelevance();
+	for (const observation of observations) {
+		const before = beforeCoverageById.get(observation.id) ?? "none";
+		const after = afterCoverageById.get(observation.id) ?? "none";
+		if (before === after) continue;
+		const key = `${before}->${after}`;
+		const bucket = summary[observation.relevance][key] ?? { count: 0, tokens: 0 };
+		bucket.count++;
+		bucket.tokens += observation.tokenCount;
+		summary[observation.relevance][key] = bucket;
+	}
+	return summary;
+}
+
+export function observationToDropperLine(
+	observation: Observation,
+	coverage: ReflectionCoverageTier,
+): string {
+	return `[${observation.id}] ${observation.timestamp} [${observation.relevance}] [coverage: ${coverage}] ${observation.content}`;
+}
+
+export function coverageTierForObservation(
+	observation: Observation,
+	coverageById: ReadonlyMap<string, ReflectionCoverageTier>,
+): ReflectionCoverageTier {
+	return coverageById.get(observation.id) ?? "none";
+}

package/src/om/agents/dropper/prompts.ts

@@ -6,30 +6,30 @@ Your job is to identify only the safest active observations to remove from compa
 
 Active-memory framing. Dropping an observation removes it from active compacted memory; it does not erase the ledger history or source evidence. Still, future compressed context will no longer show the observation, so only drop it when its durable meaning is safely captured elsewhere or it is genuinely low-signal and carries no unique future value.
 
-The user message includes drop urgency and "Maximum drops allowed this run". The maximum is a hard upper bound, not a target. Never try to hit it. Drop fewer or none when fewer observations are safely removable.
-
-Urgency guidance:
-- low urgency: only propose trivially safe drops, usually low-signal observations with no unique detail.
-- medium urgency: perform conservative cleanup; prefer low observations and clearly redundant medium observations.
-- high urgency: cleanup is more useful, but preservation rules do not weaken and load-bearing memory must still be kept.
+The user message includes the active observation pool target and "Maximum drops allowed this run". The maximum is a hard upper bound sized to move the pool toward the target if every proposed drop is clearly safe. It is not a target. Do not try to fill it. Drop fewer or none when fewer observations are safely removable. When the active pool is far over target, make a thorough pass over safe candidates rather than stopping after a few obvious examples.
 
 What to drop, in priority order:
 - Redundant observations whose durable meaning is already captured by current reflections with equivalent fidelity.
 - Superseded observations where a later observation clearly replaces the older state.
 - Repeated routine tool acknowledgements or low-signal progress updates that do not carry decisions, constraints, exact errors, or user-specific facts.
-- Older medium observations that no longer carry working context and are covered by a reflection or a newer observation.
+- Older observations that no longer carry working context and are covered by a reflection or a newer observation.
+
+Age-gradient rule. Recent observations carry working context the assistant may still need; older observations have usually been summarized elsewhere or are no longer load-bearing. Prefer older safe drops before newer working context, but age alone is not enough to drop important or uniquely load-bearing observations.
 
-Age-gradient rule. Recent observations carry working context the assistant may still need; older observations have usually been summarized elsewhere or are no longer load-bearing. Prefer older safe drops before newer working context.
+Reflection coverage guidance. Each observation line includes [coverage: none|partial|strong]. Coverage is evidence, not an automatic decision:
+- none: no current reflection cites this observation id. Be cautious, especially for high or critical observations.
+- partial: one current reflection cites this observation id. Compare the observation to the reflection before dropping.
+- strong: two or more current reflections cite this observation id. This is stronger evidence that the durable meaning is preserved, but you must still keep uniquely load-bearing or uncertain observations.
 
-Relevance guidance:
+Relevance guidance. Relevance is importance/resistance, not an absolute keep/drop lock:
 - low: consider first, but drop only when it carries no unique detail, decision, state, error, identifier, or user-specific fact.
 - medium: drop when redundant with reflections or other observations, or when the work state is clearly obsolete.
 - high: drop only when clearly superseded or already captured by a reflection with equivalent fidelity.
-- critical: NEVER drop. Code also rejects critical ids, but you must avoid proposing them.
+- critical: highest importance and strongest resistance. Do not drop fresh or uniquely load-bearing critical observations. Critical observations may be dropped only with strong semantic evidence such as age plus partial/strong reflection coverage, supersession by newer memory, redundancy, or clear obsolescence.
 
-User assertions and concrete completions are never droppable, even at non-critical relevance, unless a current reflection preserves the exact assertion/completion and its important details with equivalent fidelity.
+User assertions and concrete completions must be preserved unless a current reflection or newer observation preserves the exact assertion/completion and its important details with equivalent fidelity.
 
-Preservation floor. Regardless of relevance label, urgency, budget pressure, or age, do not drop observations that uniquely carry any of the following:
+Preservation floor. Regardless of relevance label, budget pressure, coverage, or age, do not drop observations that uniquely carry any of the following:
 - User preferences, constraints, corrections, or identity/role facts.
 - Concrete completions that future runs must not redo.
 - Named identifiers, file paths, function names, package names, tickets, commit SHAs, handles, or exact commands.

package/src/om/agents/observer/prompts.ts

@@ -101,7 +101,7 @@ If a detail is non-obvious from the code or git history, it belongs in the obser
 
 Relevance levels (pick one per observation; this field drives future dropping):
 
-- critical: user assertions about identity, role, or persistent preferences; explicit corrections ("no, don't do X"); concrete completions that future runs MUST NOT redo. These are load-bearing and will NEVER be dropped. Why this matters: if a "critical" item is lost, the assistant may redo finished work, contradict a correction, or misrepresent who the user is.
+- critical: user assertions about identity, role, or persistent preferences; explicit corrections ("no, don't do X"); concrete completions that future runs MUST NOT redo. These are highest-resistance, load-bearing observations and require the strongest evidence before leaving active memory. Why this matters: if a "critical" item is lost, the assistant may redo finished work, contradict a correction, or misrepresent who the user is.
 - high: non-trivial technical decisions, architectural direction, unresolved blockers, key constraints. Worth keeping across many compactions.
 - medium: task-level context that helps within the current work but isn't durable. The default when you are unsure between medium and high.
 - low: routine tool-call acks, repetitive status updates, content trivially re-derivable from recent messages. The dropper will drop these first.

package/src/om/agents/reflector/prompts.ts

@@ -6,7 +6,8 @@ Your task is different from the observer's: you are not recording events, you ar
 
 You receive:
 - Current reflections: durable facts already crystallized.
-- Current observations: active timestamped evidence lines, each shown as "[id] YYYY-MM-DD HH:MM [relevance] content".
+- Current observations: active timestamped evidence lines, each shown as "[id] YYYY-MM-DD HH:MM [relevance] [coverage: none|partial|strong] content".
+- Coverage tiers are review context: none means no current reflection supports the observation id, partial means exactly one current reflection supports it, and strong means two or more current reflections support it. Coverage is not a quota, target, priority score, or instruction to emit reflections.
 
 What to emit:
 - Emit only new durable reflections not already present in current reflections.
@@ -39,13 +40,16 @@ Focus on:
 - Completed outcomes future runs must not redo.
 - Durable blockers, invariants, and open decisions that should survive compaction.
 
-Support ids:
+Support ids and coverage stewardship:
 - Every reflection must include supportingObservationIds from the current observations list.
-- supportingObservationIds are a coverage/provenance set: include current observation ids whose durable meaning is preserved by the reflection and can later be treated as redundant active-memory detail.
-- supportingObservationIds are not a checklist to cover every observation. They are evidence for a reflection that already passed the durable-value bar.
+- First decide whether the reflection content passes the durable-value bar. Then audit support ids for that already-worthy reflection.
+- supportingObservationIds are a coverage/provenance set and downstream dropper coverage evidence: include all current observation ids whose durable meaning is preserved by the reflection with equivalent fidelity and can later be treated as redundant active-memory detail.
+- supportingObservationIds are not a checklist to cover every observation. Do not add ids merely to improve coverage counts, maximize support ids, maximize strong coverage, or unlock the dropper.
+- False or inflated support ids can cause unsafe downstream dropper pruning, including removal of high-resistance active observations whose meaning was not actually preserved.
 - Include additional observation ids only when the reflection preserves their durable meaning with equivalent fidelity.
 - Leave observations unsupported when their details are still active working state, too specific to compress safely, or not yet durable enough.
 - Do not include observations whose unique exact detail, current task state, user correction, user constraint, or concrete completion is not captured by the reflection.
+- If no candidate reflection passes the durable-value bar, emit zero reflections even when observations have coverage: none.
 - Never invent observation ids. Proposals with missing, empty, or invalid supportingObservationIds are rejected.
 
 User assertions are authoritative. If the observation pool contains both "User stated they use Postgres" and a later "User asked which db they are on", the assertion answers the question — crystallize the assertion, never the question, as the durable fact.

package/src/om/consolidation.ts

@@ -49,6 +49,8 @@ import {
 	rawTokensSinceReflectionCoverage,
 	reflectionToSummaryLine,
 	reflectionsCreatedAfterIndex,
+	scoreObservation,
+	selectPriorObservations,
 	type Entry,
 	type Observation,
 	type Reflection,
@@ -125,54 +127,7 @@ function mergeReflections(existing: Reflection[], additional: Reflection[]): Ref
 	return merged;
 }
 
-/** Score an observation for preamble cap selection.
- *  Relevance tier dominates: medium (5+) always outranks low (max 2).
- *  Recency is based on position in the flat-mapped array (0 = oldest, N-1 = newest),
- *  avoiding wall-clock dependency that punishes sessions spanning days or weeks. */
-function scoreObservation(obs: Observation, index: number, total: number): number {
-	const base = obs.relevance === "high" || obs.relevance === "critical" ? 10
-		: obs.relevance === "medium" ? 5 : 1;
-	const recency = total > 1 ? index / (total - 1) : 1;
-	return base + recency;
-}
-
-/** Select observations for the observer preamble, keeping all high-relevance items
- *  unconditionally and filling the remaining token budget with the best-scoring
- *  medium and low observations (relevance-tiered + recency).
- *
- *  Reflections are never trimmed — they are inherently rare and always stay. */
-function selectPriorObservations(observations: Observation[], maxTokens: number): Observation[] {
-	// Track original indices so we can restore chronological order after scoring
-	const indexed = observations.map((obs, i) => ({ obs, originalIndex: i }));
-	const high = indexed.filter(item => item.obs.relevance === "high" || item.obs.relevance === "critical");
-	const rest = indexed.filter(item => item.obs.relevance !== "high" && item.obs.relevance !== "critical");
-
-	// High always kept — consume budget first
-	let budget = maxTokens;
-	const selected = new Set<{ obs: Observation; originalIndex: number }>();
-	for (const item of high) {
-		const lineTokens = Math.ceil(observationToSummaryLine(item.obs).length / 4);
-		selected.add(item);
-		budget -= lineTokens;
-	}
 
-	// Score medium + low and select best within remaining budget
-	if (rest.length > 0 && budget > 0) {
-		const scored = rest.map((item, i) => ({ item, score: scoreObservation(item.obs, i, rest.length) }));
-		scored.sort((a, b) => b.score - a.score); // highest score first
-		for (const { item } of scored) {
-			const lineTokens = Math.ceil(observationToSummaryLine(item.obs).length / 4);
-			if (budget - lineTokens < 0) break;
-			selected.add(item);
-			budget -= lineTokens;
-		}
-	}
-
-	// Restore original chronological order before returning
-	return Array.from(selected)
-		.sort((a, b) => a.originalIndex - b.originalIndex)
-		.map(item => item.obs);
-}
 
 /**
  * Extract all pending observations from accumulated batches that were recorded

package/src/om/ledger/projection.ts

@@ -4,6 +4,7 @@
  * Upstream: https://github.com/elpapi42/pi-observational-memory (src/session-ledger/projection.ts)
  * Unmodified.
  */
+import { selectPriorObservations } from "./render-summary.js";
 import {
 	OM_FOLDED,
 	isMemoryDetails,
@@ -207,10 +208,21 @@ export function buildCompactionProjection(
 		0,
 	);
 	const fullFold = observationTokens >= config.observationsPoolMaxTokens;
-	const projection = fullFold
+	let projection = fullFold
 		? fullProjection(entries, firstKeptEntryId)
 		: normalProjection;
 
+	// Cap observations to budget using relevance-tiered + recency scoring.
+	// Even if the dropper determined some old observations are worth keeping,
+	// this safety valve ensures the compaction output never exceeds the pool
+	// token budget. Observations survive in the branch regardless.
+	if (config.observationsPoolMaxTokens > 0 && observationTokens >= config.observationsPoolMaxTokens) {
+		projection = {
+			observations: selectPriorObservations(projection.observations, config.observationsPoolMaxTokens),
+			reflections: projection.reflections,
+		};
+	}
+
 	const details: MemoryDetails = {
 		type: OM_FOLDED,
 		version: 1,

package/src/om/ledger/render-summary.ts

@@ -25,6 +25,57 @@ export function observationToSummaryLine(observation: Observation): string {
 	return `[${observation.id}] ${observation.timestamp} [${observation.relevance}] ${observation.content}`;
 }
 
+/** Score an observation for cap/trim selection.
+ *  Relevance tier dominates: medium (5+) always outranks low (max 2).
+ *  Recency is based on position in the flat-mapped array (0 = oldest, N-1 = newest),
+ *  avoiding wall-clock dependency that punishes sessions spanning days or weeks. */
+export function scoreObservation(obs: Observation, index: number, total: number): number {
+	const base = obs.relevance === "high" || obs.relevance === "critical" ? 10
+		: obs.relevance === "medium" ? 5 : 1;
+	const recency = total > 1 ? index / (total - 1) : 1;
+	return base + recency;
+}
+
+/** Select observations up to a token budget, keeping all high-relevance items
+ *  unconditionally and filling the remaining budget with the best-scoring
+ *  medium and low observations (relevance-tiered + recency).
+ *
+ *  Reflections are never trimmed — they are inherently rare and always stay.
+ *  Observations stay in the branch either way; this only caps what is rendered
+ *  in the compaction summary output. */
+export function selectPriorObservations(observations: Observation[], maxTokens: number): Observation[] {
+	// Track original indices so we can restore chronological order after scoring
+	const indexed = observations.map((obs, i) => ({ obs, originalIndex: i }));
+	const high = indexed.filter(item => item.obs.relevance === "high" || item.obs.relevance === "critical");
+	const rest = indexed.filter(item => item.obs.relevance !== "high" && item.obs.relevance !== "critical");
+
+	// High always kept — consume budget first
+	let budget = maxTokens;
+	const selected = new Set<{ obs: Observation; originalIndex: number }>();
+	for (const item of high) {
+		const lineTokens = Math.ceil(observationToSummaryLine(item.obs).length / 4);
+		selected.add(item);
+		budget -= lineTokens;
+	}
+
+	// Score medium + low and select best within remaining budget
+	if (rest.length > 0 && budget > 0) {
+		const scored = rest.map((item, i) => ({ item, score: scoreObservation(item.obs, i, rest.length) }));
+		scored.sort((a, b) => b.score - a.score); // highest score first
+		for (const { item } of scored) {
+			const lineTokens = Math.ceil(observationToSummaryLine(item.obs).length / 4);
+			if (budget - lineTokens < 0) break;
+			selected.add(item);
+			budget -= lineTokens;
+		}
+	}
+
+	// Restore original chronological order before returning
+	return Array.from(selected)
+		.sort((a, b) => a.originalIndex - b.originalIndex)
+		.map(item => item.obs);
+}
+
 export function reflectionToSummaryLine(reflection: Reflection): string {
 	return `[${reflection.id}] ${reflection.content}`;
 }