one-code-extension 0.5.0 → 0.6.0

package/extensions/ledger/index.ts

@@ -0,0 +1,46 @@
+/**
+ * ledger extension, the request side of the record-once design
+ * (working-docs/features/lifecycle-grid-hunt/design.md sections 2 and 5): the
+ * request is a pure function of the branch. Every request is recorded on the
+ * branch as it went on the wire (`ledger/wire.ts`, the payload side), and the
+ * next request inside the same epoch takes every byte above its append point
+ * from that record instead of from a rebuild.
+ *
+ * Its `context` hook runs right after kept-thinking, before anything injects:
+ *
+ * - it folds the branch (lib/ledger/fold.ts, through the shared memo in
+ *   lib/ledger/fold-memo.ts) and decides whether this request
+ *   opens an epoch (lib/ledger/plan.ts planRequest);
+ * - inside an epoch it cuts the messages the last request covered, so pi and
+ *   every later `context` hook see only the tail, and the payload side puts
+ *   the recorded list in front of what pi renders for it;
+ * - it publishes the plan on LEDGER_PLAN_CHANNEL for the renderer
+ *   (system-reminder) and the payload side.
+ *
+ * Resume, `/reload`, `/fork` and `/tree` need no restore code: each folds a
+ * different branch. pi keeps a `/tree` move only in memory, so `session_tree`
+ * appends a `one-code:branch` record, which makes the selected leaf the one a
+ * reopened file resumes on.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { sessionIdentity } from "../lib/anthropic-auth.ts";
+import { foldSession } from "../lib/ledger/fold-memo.ts";
+import { LEDGER_PLAN_CHANNEL, planRequest } from "../lib/ledger/plan.ts";
+import { makeRecord, RECORD } from "../lib/ledger/records.ts";
+import { extensionVersion } from "../lib/package-version.ts";
+
+export default function ledgerExtension(pi: ExtensionAPI) {
+	const by = extensionVersion();
+
+	pi.on("session_tree", (event) => {
+		pi.appendEntry(RECORD.branch, makeRecord("branch", by, { fromLeafId: event.oldLeafId ?? "" }));
+	});
+
+	pi.on("context", (event, ctx) => {
+		const fold = foldSession(ctx.sessionManager, sessionIdentity(pi, ctx.model));
+		const { plan, tailStart } = planRequest(fold, event.messages as Array<{ role: string; timestamp?: number }>);
+		pi.events.emit(LEDGER_PLAN_CHANNEL, plan);
+		return tailStart > 0 ? { messages: event.messages.slice(tailStart) } : undefined;
+	});
+}

package/extensions/ledger/wire.ts

@@ -0,0 +1,154 @@
+/**
+ * ledger-wire extension, the payload side of the ledger (extensions/ledger/index.ts
+ * has the request side and the design). Its `before_provider_request` hook
+ * runs after every hook that shapes the tail (system-reminder's layout,
+ * tool-search, context-management) and before cache-marks:
+ *
+ * 1. Inside an epoch it splices: the base request's recorded list, then pi's
+ *    rendering of the tail, under the recorded system prompt and tools, with
+ *    tools added mid-epoch appended (lib/ledger/wire.ts spliceRequest).
+ * 2. It settles the layout (lib/ledger/layout.ts: no system message stranded
+ *    before a user message) and validates the request (lib/ledger/validate.ts): no reference to an
+ *    undeclared tool, no system message stranded before a user message. A
+ *    problem is a bug; it is dropped and reported, so it costs one block,
+ *    never a 400. ONE_CODE_LEDGER_STRICT=1 sends it unrepaired instead, for
+ *    the live probes to see.
+ * 3. It records the request as a delta against the fold's base (the request
+ *    the fold rebuilds it on), with the pending items it carried and what its
+ *    new blocks told the model, and publishes it (LEDGER_SENT_CHANNEL) for
+ *    the side calls that replay it (compaction's summarizer, btw, recap,
+ *    forks).
+ *
+ * A pi cache warm never records or publishes: it is not a request the model
+ * answers. pi sends it through the same hooks with the warm cap, under the
+ * plan of the request it warms, in a provider call of its own, so it resends
+ * that request as it went out (with the warm's cap), or after a `/reload` (no
+ * plan here: pi's context is the tail the old instance cut) the branch's last
+ * request. Every other payload follows a context pass: pi's retry runs one
+ * too, and a second payload in the call a request went out in is pi-ai's
+ * strict-tools fallback, a real re-send. The cap alone cannot tell them
+ * apart: pi-ai clamps a request's cap to the window's room, down to 1.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { sessionIdentity } from "../lib/anthropic-auth.ts";
+import { notifyOrPrint } from "../lib/headless-output.ts";
+import { foldSession } from "../lib/ledger/fold-memo.ts";
+import { LEDGER_PLAN_CHANNEL, LEDGER_SENT_CHANNEL, type LedgerSent, type RequestPlan } from "../lib/ledger/plan.ts";
+import { makeRecord, RECORD, type ToldFact } from "../lib/ledger/records.ts";
+import { deliveredAfterRepair, repairRequest, validateRequest } from "../lib/ledger/validate.ts";
+import { settlePayload } from "../lib/ledger/layout.ts";
+import { appendPoint, encodeRequest, hasWarmCap, listKey, type RecordedRequest, recordedBody, recordedRequest, samePrefix, spliceRequest, type WirePayload, withBranchToolOrder, withRequestFields } from "../lib/ledger/wire.ts";
+import { type AffinityModel, affinityHeaders } from "../lib/request-replay.ts";
+import { extensionVersion } from "../lib/package-version.ts";
+
+export default function ledgerWireExtension(pi: ExtensionAPI) {
+	const by = extensionVersion();
+	/** The plan of the last `context` pass; a warm re-runs only this hook and reuses it. */
+	let plan: RequestPlan | undefined;
+	/**
+	 * The provider call the hook runs in: pi resolves a call's headers once
+	 * (`prepareRequest`), before its first payload, so `before_provider_headers`
+	 * opens each call, a warm's included.
+	 */
+	let call = 0;
+	/** The call a request under `plan` went out in: a payload with the warm cap in a later call is a warm, in the same call pi-ai's re-send. */
+	let sentIn: number | undefined;
+	/** What this hook recorded under `plan`: the request, and the hashes it stored, so a re-send stores only new bodies. */
+	let recorded: { request: RecordedRequest; hashes: Set<string> } | undefined;
+	/** The last session request this instance sent, as it left this hook: what a warm resends. */
+	let lastSent: WirePayload | undefined;
+	/** Problems already reported this session, so a recurring bug is one notice. */
+	const reported = new Set<string>();
+
+	pi.events.on(LEDGER_PLAN_CHANNEL, (data) => {
+		plan = data as RequestPlan;
+		sentIn = undefined;
+		recorded = undefined;
+	});
+	pi.on("session_start", () => {
+		plan = undefined;
+		sentIn = undefined;
+		recorded = undefined;
+		lastSent = undefined;
+		reported.clear();
+	});
+
+	/** The session the plan's request is routed for: the one that opened the epoch, recorded with its base. */
+	const routingOf = (current: RequestPlan | undefined, own: string) => (current && !current.epoch ? (current.base?.routing ?? own) : own);
+
+	// A /fork's first request extends its parent's record, and the parent's cache
+	// lives on the host the parent's session id routed to: a gateway such as
+	// OpenRouter picks it by the session-affinity headers, which pi-ai builds
+	// from the fork's own id (R3-M22). Not on Codex, where pi-ai sets its
+	// session-id header after every hook (findings §75). With no plan in this
+	// instance (a warm after a /reload) the call resends the branch's last
+	// request, so it goes where that request was routed.
+	pi.on("before_provider_headers", (event, ctx) => {
+		call++;
+		const own = ctx.sessionManager.getSessionId();
+		const identity = plan ? undefined : sessionIdentity(pi, ctx.model);
+		const routing = plan ? routingOf(plan, own) : ((identity && foldSession(ctx.sessionManager, identity).lastRequest?.routing) ?? own);
+		if (routing === own) return;
+		Object.assign(event.headers, affinityHeaders(ctx.model as AffinityModel | undefined, routing));
+	});
+
+	pi.on("before_provider_request", (event, ctx) => {
+		const model = ctx.model;
+		const identity = sessionIdentity(pi, model);
+		if (!model || !identity) return undefined;
+		const api = model.api;
+		const live = event.payload as WirePayload;
+		const current = plan;
+
+		// A cache warm: the request it warms, as sent, under the warm's cap. A
+		// payload in the call the request went out in is pi-ai sending it again.
+		if ((!current || (sentIn !== undefined && sentIn !== call)) && hasWarmCap(live)) {
+			if (lastSent) return withRequestFields(lastSent, live);
+			const base = foldSession(ctx.sessionManager, identity).lastRequest;
+			return base ? recordedBody(base, live, api) : undefined;
+		}
+		// No context pass in this instance and not a warm: leave pi's request alone.
+		if (!current) return undefined;
+
+		let payload = live;
+		const base = current.epoch ? undefined : current.base;
+		const end = base ? appendPoint(base.list, api) : 0;
+		if (base) payload = spliceRequest(base, payload, api);
+		// An epoch renders pi's tools again, in the order the branch first declared them.
+		else payload = withBranchToolOrder(payload, current.fold.toolOrder, api);
+		const spliced = payload;
+		// The final layout pass: no system message stranded before a user message (lib/ledger/layout.ts).
+		payload = settlePayload(payload, api, listKey(api), end);
+		let delivered: { consumed: string[]; facts: ToldFact[] } = { consumed: current.consumed, facts: current.carried.flatMap((block) => block.facts) };
+
+		const problems = validateRequest(payload, api);
+		if (problems.length > 0) {
+			const fresh = problems.map((problem) => JSON.stringify(problem)).filter((key) => !reported.has(key));
+			for (const key of fresh) reported.add(key);
+			if (fresh.length > 0) notifyOrPrint(ctx, `One Code: the request had ${problems.length} problem(s) the ledger ${process.env.ONE_CODE_LEDGER_STRICT === "1" ? "left in place" : "removed"}: ${fresh.join(", ")}`, "warning");
+			if (process.env.ONE_CODE_LEDGER_STRICT !== "1") {
+				payload = repairRequest(payload, api, problems);
+				delivered = deliveredAfterRepair(payload, api, delivered, current.fold.pending, new Set(current.base?.hashes ?? []), current.carried);
+			}
+		}
+
+		// The recorded prefix is known, unless the layout pass or a repair moved its elements.
+		const request = recordedRequest(payload, identity, base && samePrefix(spliced, payload, listKey(api), end) ? { base, end } : undefined);
+		lastSent = payload;
+		sentIn = call;
+		// The same request again under this plan (pi-ai re-sending an identical body) records nothing new.
+		if (recorded && encodeRequest(recorded.request, request, { has: () => true }) === undefined) return payload === live ? undefined : payload;
+		const known = { has: (hash: string) => current.fold.knownHashes.has(hash) || recorded?.hashes.has(hash) === true };
+		const delta = encodeRequest(current.fold.lastRequest, request, known);
+		if (delta) {
+			if (current.epoch) pi.appendEntry(RECORD.epoch, makeRecord("epoch", by, { cause: current.cause ?? "first" }));
+			const routing = routingOf(current, ctx.sessionManager.getSessionId());
+			pi.appendEntry(RECORD.request, makeRecord("request", by, { ...delta, covers: current.covers, consumed: delivered.consumed, routing }));
+			if (delivered.facts.length > 0) pi.appendEntry(RECORD.told, makeRecord("told", by, { facts: delivered.facts }));
+			recorded = { request, hashes: new Set([...(recorded?.hashes ?? []), ...Object.keys(delta.blobs)]) };
+			pi.events.emit(LEDGER_SENT_CHANNEL, { payload, model, sessionId: ctx.sessionManager.getSessionId(), plan: current } satisfies LedgerSent);
+		}
+		return payload === live ? undefined : payload;
+	});
+}

package/extensions/lib/agent-cron.ts

@@ -38,10 +38,26 @@ export interface AgentCronResult {
 	details?: Record<string, unknown>;
 }
 
+/**
+ * The conversation a fire lands in: its branch to read, and entries to
+ * append to it. A no-prompt `/loop` sentinel records there what it already
+ * sent, so the record follows that conversation (its `/tree`, its resume,
+ * its own compaction), not the session that owns the job store.
+ */
+export interface FireConversation {
+	getBranch(): readonly unknown[];
+	appendEntry(customType: string, data?: unknown): void;
+}
+
 export interface AgentCronFire {
 	agentId: string;
 	jobId: string;
-	prompt: string;
+	/**
+	 * The text to send, resolved against the agent's own conversation (a
+	 * sentinel reads and records its delivery there; undefined resolves as a
+	 * conversation that was sent nothing). Call it once, for the send.
+	 */
+	text(conversation: FireConversation | undefined): string;
 	/** Set by the subagents extension when a live agent received it. */
 	delivered?: boolean;
 }

package/extensions/lib/agent-loader.ts

@@ -114,8 +114,9 @@ export interface AgentLoaderOptions {
  * listener). A cached loader therefore broke the second child of the same
  * agent type, every SendMessage resume, every workflow agent after the first,
  * and any sibling still running when one was disposed
- * (LIFECYCLE-REVIEW-2026-09-06 H3, measured). A build costs ~3 ms once the
- * extension modules are in jiti's cache, so there is nothing to save.
+ * (LIFECYCLE-REVIEW-2026-09-06 H3, measured). A build costs ~3 ms once pi's
+ * factory cache holds the extensions for that directory (jiti itself runs
+ * with `moduleCache: false`, findings §8), so there is nothing to save.
  */
 export async function buildAgentLoader(options: AgentLoaderOptions): Promise<DefaultResourceLoader> {
 	const loader = new DefaultResourceLoader({

package/extensions/lib/anthropic-auth.ts

@@ -0,0 +1,98 @@
+/**
+ * The login a request goes out under, and the rest of a request's identity
+ * (lib/ledger): every input that makes pi-ai build a differently shaped
+ * request. An Anthropic OAuth login (a Claude subscription) carries pi's
+ * identity betas and Claude Code's tool names; Sign in with ChatGPT drops
+ * OpenAI's per-message `configuration_update` items and the cache fields
+ * (pi-ai openai-responses.js isChatGPTSignIn); thinking turned off drops
+ * pi-ai's per-message effort markers on a model that takes them. A change
+ * of any of them opens an epoch, so recorded history is never replayed in a
+ * shape pi would not build.
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { RequestIdentity } from "./ledger/records.ts";
+
+/** mtime cache: this runs on every provider request, the hottest path there is. */
+let authCache: { mtimeMs: number; oauth: ReadonlySet<string> } | undefined;
+
+/** The providers pi's auth.json holds an OAuth login for. */
+function oauthProviders(): ReadonlySet<string> {
+	// getAgentDir() honours PI_CODING_AGENT_DIR, so an isolated one-code app
+	// reads its own auth.json rather than ~/.pi's.
+	const path = join(getAgentDir(), "auth.json");
+	try {
+		const mtimeMs = statSync(path).mtimeMs;
+		const cached = authCache;
+		if (cached && cached.mtimeMs === mtimeMs) return cached.oauth;
+		const auth = JSON.parse(readFileSync(path, "utf8")) as Record<string, { type?: unknown; refresh?: unknown } | undefined>;
+		const oauth = new Set(Object.entries(auth ?? {}).flatMap(([provider, entry]) => (entry?.type === "oauth" || typeof entry?.refresh === "string" ? [provider] : [])));
+		authCache = { mtimeMs, oauth };
+		return oauth;
+	} catch {
+		authCache = undefined;
+		return new Set();
+	}
+}
+
+/** True when pi's auth.json holds an OAuth login for Anthropic. */
+export function isAnthropicOAuth(): boolean {
+	return oauthProviders().has("anthropic");
+}
+
+/** OpenAI's own endpoint, where pi-ai treats a login that is not an `sk-` key as Sign in with ChatGPT. */
+const OPENAI_API = "https://api.openai.com/v1";
+
+/**
+ * The auth kind a request to `provider` goes out with: "oauth" for an
+ * Anthropic subscription login, "chatgpt" for Sign in with ChatGPT on
+ * OpenAI's own endpoint, else "key".
+ */
+export function authKind(provider: string | undefined, baseUrl?: string): "oauth" | "chatgpt" | "key" {
+	if (provider === "anthropic") return isAnthropicOAuth() ? "oauth" : "key";
+	if (provider === "openai" && baseUrl === OPENAI_API && oauthProviders().has("openai")) return "chatgpt";
+	return "key";
+}
+
+interface IdentityModel {
+	api?: string;
+	provider?: string;
+	id?: string;
+	baseUrl?: string;
+	reasoning?: boolean;
+	thinkingLevelMap?: Record<string, unknown>;
+	compat?: unknown;
+}
+
+/**
+ * Whether pi-ai puts its per-message effort markers in the request (an
+ * effort directive before each earlier reply, a Responses
+ * `configuration_update`): only on a model that takes them, and not while
+ * thinking is off there (pi-ai anthropic-messages.js effortMessages).
+ * Undefined on a model without them, or when the level is unknown.
+ */
+function effortMarkers(model: IdentityModel, thinkingLevel: string | undefined): boolean | undefined {
+	if ((model.compat as { supportsMidConvoEffort?: boolean } | undefined)?.supportsMidConvoEffort !== true || thinkingLevel === undefined) return undefined;
+	return !(thinkingLevel === "off" && model.reasoning === true && model.thinkingLevelMap?.off !== null);
+}
+
+/**
+ * Who a request to `model` goes to and how pi-ai shapes it, as the ledger
+ * records it; a change opens an epoch. `thinkingLevel` is the session's
+ * (`pi.getThinkingLevel()`). Undefined without a full model.
+ */
+export function requestIdentity(model: IdentityModel | undefined, thinkingLevel?: string): RequestIdentity | undefined {
+	if (!model?.api || !model.provider || !model.id) return undefined;
+	const markers = effortMarkers(model, thinkingLevel);
+	return { api: model.api, provider: model.provider, model: model.id, auth: authKind(model.provider, model.baseUrl), ...(markers !== undefined ? { effortMarkers: markers } : {}) };
+}
+
+/**
+ * The identity of a request this session sends to `model` now, under the
+ * session's thinking level (undefined where the API lacks it: a test double).
+ */
+export function sessionIdentity(pi: { getThinkingLevel?: () => string }, model: IdentityModel | undefined): RequestIdentity | undefined {
+	return requestIdentity(model, typeof pi.getThinkingLevel === "function" ? pi.getThinkingLevel() : undefined);
+}

package/extensions/lib/child-extensions.ts

@@ -14,9 +14,19 @@
  * either: its tools are shared in from the parent as customTools
  * (lib/mcp-share.ts `watchMcpTools`), not reconnected.
  *
- * Order mirrors the package's load order: the reminder and deferral sinks
- * (system-reminder, tool-search) first, before anything emitting on their
- * channels (the bus does not replay). A caller that loads these must set the
+ * Order mirrors the package's load order: kept-thinking first (the first
+ * `context` hook, before anything reads the messages), the ledger's request
+ * side next (it cuts the request to its tail before anything injects), then
+ * the reminder and deferral sinks (system-reminder, tool-search), before
+ * anything emitting on their channels (the bus does not replay), then
+ * context-management and compaction as in the main session (a child's requests
+ * carry the same thinking edit, and a fork that crosses its threshold is
+ * summarized by replaying its own last request, not by pi's uncached default
+ * summarizer), then the ledger's payload side, after every hook that shapes
+ * the tail and before cache-marks. A child has its own event bus (pi's
+ * resource loader makes one per loader), so its captures never reach the
+ * parent's side calls. A fork's file is a copy of the parent's, records included, so
+ * its first request extends the parent's last one and reads its cache. A caller that loads these must set the
  * loader's `noContextFiles`, because claude-context injects `# claudeMd` itself.
  */
 
@@ -34,7 +44,7 @@ const EXTENSIONS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..");
 // (mode "print"), so `run_in_background` runs blocking there and nothing a
 // child starts outlives it (Claude Code kills an agent's shells as it exits).
 export const CHILD_EXTENSIONS = [
-	"system-reminder", "tool-search", "claude-context", "tool-call-corruption/child",
+	"kept-thinking", "ledger", "system-reminder", "tool-search", "context-management", "compaction", "ledger/wire", "cache-marks", "claude-context", "tool-call-corruption/child",
 	"file-tracker", "search-tools", "skill", "bash/child", "powershell/child", "web", "web-fetch", "notebook",
 ];
 

package/extensions/lib/context-facts.ts

@@ -1,51 +1,65 @@
-/** Comparisons for the historical context stack. No pi imports or live-state reads. */
-import { createHash } from "node:crypto";
-import { buildClaudeMdBlock, buildContextBlock, type ContextFile } from "./claude-context.ts";
-import type { ReminderEntry } from "./reminders.ts";
+/**
+ * What claude-context's message-1 blocks tell, as ledger facts, and the notice
+ * for a resumed session whose workspace changed since (pure). The blocks are
+ * live state; an epoch records their fingerprints with its request, so the
+ * first request of a resumed process compares them with the live files and git
+ * status, and says what changed once. The historical blocks stay as sent.
+ */
+import { buildClaudeMdBlock, type ContextFile } from "./claude-context.ts";
+import type { ToldFact } from "./ledger/records.ts";
+import { contentHash } from "./ledger/wire.ts";
+import { toldBlockFact } from "./reminders.ts";
 
-export const CONTEXT_FACT_KEYS = ["claude-context", "one-code-context", "claude-context-context", "claude-context-date"] as const;
-export const RESUME_FACTS_KEY = "context-resume-changes";
-export const DATE_CHANGE_KEY = "claude-context-date-change";
+/** The told keys of the fingerprints (whole-text block facts) and of the compaction flag (a mode). */
+export const FACT_KEYS = {
+	instructions: "context-facts:instructions",
+	memory: "context-facts:memory",
+	git: "context-facts:git",
+	date: "context-facts:date",
+	/** On when the epoch's blocks were taken at a compaction, not at the session's start. */
+	compaction: "context-facts:compaction",
+} as const;
 
-export interface ContextFactsBaseline {
+/** A told block's hash (`toldBlockFact`): for a string or null it is the sha256 of its JSON. */
+const fingerprint = contentHash;
+
+/** Fingerprints of only what the model was shown, not unshown file tails or filesystem mtimes. */
+export interface ContextFingerprints {
 	instructions: string;
 	memory: string;
-	git: string;
-	/** A compaction starts a new snapshot epoch, not a new conversation. */
-	atCompaction: boolean;
-	/**
-	 * The directory the facts were read in: the session's cwd, or the entered
-	 * worktree at a compaction. A resume compares in the same one. Absent in
-	 * older snapshots.
-	 */
-	cwd?: string;
 }
 
-const fingerprint = (value: unknown): string => createHash("sha256").update(JSON.stringify(value)).digest("hex");
-
-/** Hash only what the model was shown, not unshown file tails or filesystem mtimes. */
-export function contextFactsBaseline(input: {
-	contextFiles: ContextFile[];
-	memoryIndex: { path: string; content: string } | null;
-	gitStatus: string | null;
-	atCompaction: boolean;
-	cwd?: string;
-}): ContextFactsBaseline {
+export function contextFingerprints(input: { contextFiles: ContextFile[]; memoryIndex: { path: string; content: string } | null }): ContextFingerprints {
 	return {
 		instructions: fingerprint(buildClaudeMdBlock({ contextFiles: input.contextFiles })),
 		memory: fingerprint(buildClaudeMdBlock({ contextFiles: [], memoryIndex: input.memoryIndex })),
-		git: fingerprint(input.gitStatus),
-		atCompaction: input.atCompaction,
-		...(input.cwd !== undefined ? { cwd: input.cwd } : {}),
 	};
 }
 
-export function storedFactsBaseline(value: unknown): ContextFactsBaseline | undefined {
-	if (!value || typeof value !== "object") return undefined;
-	const v = value as Record<string, unknown>;
-	if (![v.instructions, v.memory, v.git].every((part) => typeof part === "string" && /^[a-f0-9]{64}$/.test(part)) || typeof v.atCompaction !== "boolean") return undefined;
-	const { cwd, ...facts } = v;
-	return { ...facts, ...(typeof cwd === "string" ? { cwd } : {}) } as unknown as ContextFactsBaseline;
+export const gitFingerprint = (gitStatus: string | null): string => fingerprint(gitStatus);
+
+/** The live workspace's fingerprints for the resumed-session check: the instructions, the memory index and, when a git snapshot is taken, the git status. */
+export type LiveFingerprints = ContextFingerprints & { git?: string };
+
+export function liveFingerprints(files: Parameters<typeof contextFingerprints>[0], gitStatus: string | null, withGit: boolean): LiveFingerprints {
+	return { ...contextFingerprints(files), ...(withGit ? { git: gitFingerprint(gitStatus) } : {}) };
+}
+export const dateFingerprint = (date: string): string => fingerprint(date);
+
+/** The facts the instructions block tells. */
+export function instructionFacts(prints: ContextFingerprints): ToldFact[] {
+	return [
+		{ kind: "block", key: FACT_KEYS.instructions, hash: prints.instructions },
+		{ kind: "block", key: FACT_KEYS.memory, hash: prints.memory },
+	];
+}
+
+/** The facts the context block tells: its git snapshot, and whether a compaction took it. */
+export function contextBlockFacts(gitStatus: string | null, atCompaction: boolean): ToldFact[] {
+	return [
+		toldBlockFact(FACT_KEYS.git, gitStatus),
+		{ kind: "mode", key: FACT_KEYS.compaction, on: atCompaction },
+	];
 }
 
 /** A refreshed git snapshot must not describe itself as the conversation's initial status. */
@@ -53,26 +67,31 @@ export function compactionGitStatus(text: string | null): string | null {
 	return text?.replace("This is the git status at the start of the conversation.", "This is the git status at the latest compaction.") ?? null;
 }
 
-/** One short factual notice; the historical blocks themselves remain byte-identical. */
-export function resumeFactsNotice(before: ContextFactsBaseline, current: ContextFactsBaseline): string | undefined {
+/**
+ * One short factual notice when the live workspace differs from what the
+ * epoch's blocks told, and the facts that bring the told state up to date.
+ * Undefined when nothing the epoch told has changed, or the epoch told none
+ * of it (its blocks predate the facts).
+ */
+export function resumeFactsNotice(
+	told: ReadonlyMap<string, string>,
+	atCompaction: boolean,
+	live: ContextFingerprints & { git?: string },
+): { text: string; facts: ToldFact[] } | undefined {
 	const changed: string[] = [];
-	if (before.git !== current.git) changed.push("git status changed");
-	if (before.memory !== current.memory) changed.push("the memory index changed");
-	if (before.instructions !== current.instructions) changed.push("CLAUDE.md-family instructions changed");
+	const facts: ToldFact[] = [];
+	const compare = (key: string, hash: string | undefined, what: string) => {
+		const before = told.get(key);
+		if (hash === undefined || before === undefined || before === hash) return;
+		changed.push(what);
+		facts.push({ kind: "block", key, hash });
+	};
+	compare(FACT_KEYS.git, live.git, "git status changed");
+	compare(FACT_KEYS.memory, live.memory, "the memory index changed");
+	compare(FACT_KEYS.instructions, live.instructions, "CLAUDE.md-family instructions changed");
 	if (changed.length === 0) return undefined;
-	return `Since the saved context snapshot, ${changed.join("; ")}. The earlier context block reflects ${before.atCompaction ? "the latest compaction" : "the session's start"}, not the current workspace. Read the current files or run git status if needed.`;
-}
-
-/** Old snapshots lack separate fingerprints: do not invent which half of # claudeMd changed. */
-export function legacyResumeFactsNotice(stack: readonly ReminderEntry[], live: {
-	instructions: string | null;
-	email: string | null;
-	gitStatus: string | null;
-}): string | undefined {
-	const changed: string[] = [];
-	const previousContext = stack.find((entry) => entry.key === "claude-context-context")?.text ?? null;
-	const gitPart = (text: string | null) => text?.match(/# gitStatus\n[\s\S]*?(?=\n\nOne Code attached this context automatically;|$)/)?.[0] ?? null;
-	if (gitPart(previousContext) !== gitPart(buildContextBlock(live))) changed.push("git status changed");
-	if ((stack.find((entry) => entry.key === "claude-context")?.text ?? null) !== live.instructions) changed.push("CLAUDE.md-family instructions or the memory index changed");
-	return changed.length ? `Since the saved context snapshot, ${changed.join("; ")}. The earlier context block reflects the session's start, not the current workspace. Read the current files or run git status if needed.` : undefined;
+	return {
+		text: `Since the saved context snapshot, ${changed.join("; ")}. The earlier context block reflects ${atCompaction ? "the latest compaction" : "the session's start"}, not the current workspace. Read the current files or run git status if needed.`,
+		facts,
+	};
 }

package/extensions/lib/covered-messages.ts

@@ -0,0 +1,23 @@
+/**
+ * The whole conversation each request covers, as pi built it, for compaction's
+ * summarizer. (btw's and recap's standalone fallbacks read the current branch
+ * at call time instead: lib/side-call.ts `branchMessages`.) Inside an epoch
+ * the ledger (extensions/ledger) cuts a request to its tail before every later
+ * `context` hook, so the full list comes with the request's plan instead.
+ */
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { LEDGER_PLAN_CHANNEL, type RequestPlan } from "./ledger/plan.ts";
+
+/** Call `onRequest` at each request's `context` pass with every message the request covers. */
+export function followCoveredMessages(pi: ExtensionAPI, onRequest: (messages: AgentMessage[], ctx: ExtensionContext) => void): void {
+	let planned: readonly AgentMessage[] | undefined;
+	pi.events.on(LEDGER_PLAN_CHANNEL, (data) => {
+		planned = (data as RequestPlan).messages as readonly AgentMessage[];
+	});
+	pi.on("context", (event, ctx) => {
+		onRequest([...(planned ?? event.messages)], ctx);
+		planned = undefined;
+	});
+}