one-code-extension 0.4.1 → 0.6.0

package/extensions/lib/reminders.ts

@@ -1,92 +1,91 @@
 /**
- * System-reminder queue — the steering mechanism shared by all One Code
- * extensions. Reminders are injected transiently into the outgoing request via
- * pi's `context` event; they are never written to the session file.
+ * System reminders: the steering blocks One Code adds to a request, rendered
+ * once and then kept as sent (working-docs/features/lifecycle-grid-hunt/design.md
+ * section 5). The ledger (extensions/ledger) sends through pi only the
+ * messages after the last request's coverage, the tail, and takes everything
+ * above it from that request's record. So a reminder is rendered only onto the
+ * tail, rides the request that first carried it, and stays in the record
+ * byte for byte; nothing here is restored or re-rendered later.
  *
  * Cross-extension contract: emit on the event bus channel
- * `one-code:system-reminder` with `{ text, scope?, placement? }` to enqueue from
- * any extension (including third-party ones). The queue instance itself lives
- * in the system-reminder extension; do not import one from here (jiti gives
- * every extension its own module instance, so a shared export steers nothing).
+ * `one-code:system-reminder` with `{ text, placement? }`. The live
+ * state lives in the system-reminder extension; do not import one from here
+ * (jiti gives every extension its own module instance, so a shared export
+ * steers nothing).
  *
- * Three placements, chosen by what kind of fact the reminder is:
+ * Four placements, chosen by what kind of fact the reminder is:
  *
- * - `first-prepend` — SESSION CONTEXT that never changes mid-session (deferred
- *   tools, agent catalog, MCP instructions, skills, `# claudeMd`). Front of the
- *   FIRST user message, before the user's text, ordered by `order`, exactly
- *   Claude Code's first-message stack. Byte-stable, so the cached prefix holds.
- * - `sticky-append` — SESSION STATE that switches on and off (auto mode, plan
- *   mode, a worktree session, ultracode). Appended to the user message that
- *   opened the turn during which the state switched on (`since`) and to EVERY
- *   user message after it, so message N carries the block on every later
- *   request too: the prefix stays byte-stable while the state holds, and the
- *   model still sees the reminder on its latest turn. Switching off drops the
- *   blocks (one cache miss, once). The old `last-append` + every-turn
- *   combination re-cached the previous turn on every turn — permanently, in
- *   auto mode.
- * - `last-append` — ONE-SHOT STEERING about what just happened (a deferred tool
- *   miss, a file changed under the model, a mode change). Delivered where the
- *   model reads next, and then KEPT there so the message never changes again:
- *   a one-shot pending when a tool result is stored is written INTO that result
- *   (`takeOneShots` from the `tool_result` hook — Claude Code persists its
- *   mid-turn reminders the same way, so the transcript carries them and no
- *   request ever re-caches the result); a one-shot still pending when a request
- *   goes out is `pin`ned to the request's tail (the trailing tool result by call
- *   id, else the last user message by timestamp) and re-attached to that same
- *   message on every later request, byte-identical. Pins are process memory
- *   (a `--resume` drops them: one miss, once).
- * - `user-prepend` — LOCAL-COMMAND BREADCRUMBS (`/clear`, `/model`, a panel
- *   command): what Claude Code shows the model when the user ran a slash
- *   command. Bare text blocks placed BEFORE the user's text on the next user
- *   message that opens a request (after the `first-prepend` stack on message
- *   one), then pinned there like a delivered one-shot. They never ride a tool
- *   result — a command run mid-turn waits for the next prompt. The caveat
- *   block is queued `once` per pending run (a second command joins the first
- *   caveat); the command and stdout blocks are never collapsed.
- *   `lib/local-command.ts` builds the blocks.
+ * - `first-prepend`: SESSION CONTEXT (environment, deferred tools, agent
+ *   catalog, MCP instructions, skills, `# claudeMd`). Live state, kept current
+ *   by its owner; rendered only on a request that opens an epoch, in front of
+ *   the first user message and ordered by `order`: Claude Code's first-message
+ *   stack. Inside an epoch message 1 is the record, so a change is not
+ *   rendered; its owner announces the difference at render time
+ *   (RENDER_CHANNEL: live minus what the epoch told).
+ * - `sticky-append`: SESSION STATE that switches on and off (auto mode, plan
+ *   mode, a worktree session, ultracode). Appended to every user message of
+ *   the tail stamped at or after the state switched on (`since`). Switched on
+ *   mid-turn, it first rides the switching call's result (`toolCallId`), or
+ *   the first result after the switch, never the already-sent turn opener.
+ *   Removing it closes it: later messages stop carrying it, and the ones
+ *   already sent keep it in the record.
+ * - `last-append`: ONE-SHOT steering about what just happened (a deferred
+ *   tool miss, a file changed under the model, a mode change). Persisted when
+ *   emitted as a `one-code:pending` entry, so it survives `/reload` and quit
+ *   and is gone with an abandoned `/tree` branch; delivered on the tail of the
+ *   next request (the call's own result when `toolCallId` names one in the
+ *   tail, the prompt's own message when `promptTimestamp` names one, else
+ *   the trailing tool result, else the last user message), and
+ *   recorded as consumed by that request.
+ * - `user-prepend`: LOCAL-COMMAND BREADCRUMBS (`/clear`, `/model`, a panel
+ *   command): pending like a one-shot, but placed only before the text of a
+ *   prompt that opens a request; mid-turn it waits. The caveat block is
+ *   queued `once` per run (a second command joins the first caveat); the
+ *   command and stdout blocks are never collapsed. `lib/local-command.ts`
+ *   builds them.
  *
- * Persisted or pinned is decided by WHEN the one-shot is emitted, which is a
- * load-order rule: system-reminder's `tool_result` hook takes the one-shots
- * pending at that moment, so only an extension whose own `tool_result` handler
- * runs BEFORE it (listed before `system-reminder` in `package.json`
- * `pi.extensions`, like `context-budget`) or that emits from `tool_call` gets
- * its block written into the result. Emitting from a later `tool_result`
- * handler, or from `tool_execution_end` (pi runs it AFTER the `tool_result`
- * hooks, findings §3), lands the block on the same result but as a pin. Same
- * wording on the wire, so this only matters for `--resume` and for ordering
- * after the `<total_tokens>` line.
- *
- * A compaction summary counts as a user message for anchoring (pi renders it as
- * one), so the context stack survives a compaction that left no user turn. So
- * does a `custom` harness message (task notification, wakeup, hook context):
- * pi sends it as a user message, and a turn it opens has no other user turn.
- *
- * Retry safety falls out of this: pi re-runs the `context` transform per LLM
- * attempt, and both a persisted and a pinned one-shot are present on every
- * attempt by construction.
+ * A compaction summary counts as a user message for the stack (pi renders it
+ * as one), and so does a `custom` harness message (task notification, wakeup,
+ * hook context): pi sends it as a user message, and a turn it opens has no
+ * other user turn.
  */
 
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
+import type { BlockFact, FileVersion, ToldFact } from "./ledger/records.ts";
+import { contentHash } from "./ledger/wire.ts";
+import type { MovedBlock } from "./system-role.ts";
 
 export const REMINDER_CHANNEL = "one-code:system-reminder";
 
-/** "next-turn" fires once on the next LLM call; "every-turn" fires on every call until removed. */
-export type ReminderScope = "next-turn" | "every-turn";
+/**
+ * Emitted by the system-reminder extension once per request, while it renders
+ * the tail (a `RenderRequest`). An owner of a capability block subscribes and
+ * adds the blocks this request needs from live state and what the epoch has
+ * told: on a request inside an epoch, the names live now that the epoch has
+ * not told yet. Computed when the request goes out, never when a change is
+ * queued, so a capability that came and went before the request is never
+ * announced.
+ */
+export const RENDER_CHANNEL = "one-code:render";
 
 /** See the module header for which placement fits which kind of reminder. */
 export type ReminderPlacement = "first-prepend" | "sticky-append" | "last-append" | "user-prepend";
 
-/** Where a delivered one-shot stays: a tool result (by call id) or a user turn (by timestamp). */
-export type PinAnchor = { kind: "toolResult"; toolCallId: string } | { kind: "user"; timestamp: number };
-
 /**
  * `order` values for the `first-prepend` context stack, matching Claude Code's
- * fixed sequence on the first user message: deferred tools → agent catalog → MCP
- * instructions → skills → the `# claudeMd` block (last, just before the user's
- * text). Gaps leave room for One Code-specific reminders (e.g. subagent models).
+ * fixed sequence on the first user message: environment → model line → deferred
+ * tools → agent catalog → MCP instructions → skills → the instructions block →
+ * the context block → the date (just before the user's text). Gaps leave room
+ * for One Code-specific reminders (e.g. subagent models). On a model that takes
+ * a mid-conversation system message, everything below `claudeMd`, and the date,
+ * moves into that message instead (`movesToSystemRole`, lib/system-role.ts).
  */
 export const CONTEXT_ORDER = {
+	environment: 1,
+	modelLine: 2,
+	/** One Code's note that a `-p`/json run ends with its turn (`lib/notifications.ts oneShotSessionNote`); not Claude Code's. */
+	oneShot: 3,
 	deferredTools: 10,
 	subagentModels: 20,
 	agents: 21,
@@ -94,263 +93,364 @@ export const CONTEXT_ORDER = {
 	delegation: 22,
 	mcp: 30,
 	skills: 40,
+	/** Claude Code's auto-mode note; only in the system message (`systemRoleOnly`). */
+	autoModeNote: 45,
+	/** The `<total_tokens>` line the first prompt carries (later prompts: lib/turn-budget-layout.ts). */
+	totalTokens: 46,
 	// CLAUDE.md-family (with AGENTS.md as a per-directory fallback when a directory
 	// has no CLAUDE.md) — CLAUDE.md > AGENTS.md.
 	claudeMd: 50,
-	// One Code's own instructions ride in their own block AFTER the # claudeMd
+	// One Code's own instructions ride in their own block AFTER the instructions
 	// block (higher `order` = closer to the user text = higher precedence), so
 	// ONECODE.md takes precedence over CLAUDE.md/AGENTS.md. Not part of CC.
-	oneCodeMd: 60,
+	oneCodeMd: 52,
+	/** The user's email and the git snapshot. */
+	context: 54,
+	date: 56,
 } as const;
 
-/** A drained reminder with everything the injector needs to place it. */
-export interface ReminderEntry {
-	text: string;
-	placement: ReminderPlacement;
-	order: number;
-	/**
-	 * Literal text appended AFTER the closing `</system-reminder>` tag. Claude
-	 * Code's `# claudeMd` block ends `</system-reminder>\n\n` on the wire; this
-	 * reproduces that byte-for-byte. Defaults to "".
-	 */
-	suffix?: string;
-	/**
-	 * `sticky-append` only: when the state switched on. The user message that
-	 * opened the turn in progress at that moment, and every user message after
-	 * it, carry the block.
-	 */
-	since?: number;
-	/** Set on a pinned one-shot: the exact message it rides on every request. */
-	pin?: PinAnchor;
-	/**
-	 * Emit `text` as-is instead of inside a `<system-reminder>` frame — for the
-	 * few Claude Code blocks that ride bare, like `<total_tokens>` after a tool
-	 * result. Defaults to false.
-	 */
-	raw?: boolean;
+/**
+ * Whether a `first-prepend` block of this order leaves the first user message
+ * for the mid-conversation system message on a model that takes one: the
+ * session facts below the instructions block, and the date, which Claude Code
+ * puts last in that message. The instructions, One Code's own block and the
+ * context block stay in the user message.
+ */
+export function movesToSystemRole(order: number): boolean {
+	return order < CONTEXT_ORDER.claudeMd || order === CONTEXT_ORDER.date;
 }
 
 export interface ReminderPayload {
 	text?: string;
-	scope?: ReminderScope;
-	/** Key so a reminder can be replaced (next-turn) or replaced/removed (every-turn). */
+	/** Key so a reminder can be replaced (a pending one-shot, a live block) or removed (a live block). */
 	key?: string;
-	/** Remove the every-turn reminder registered under `key` instead of enqueueing. */
+	/** Remove the live block or close the sticky state under `key`. */
 	remove?: boolean;
 	/** Where in the message stack this reminder lands. Defaults to `last-append`. */
 	placement?: ReminderPlacement;
 	/** Sort key among `first-prepend` reminders (Claude Code order). Defaults to 0. */
 	order?: number;
-	/** Literal text appended after the closing `</system-reminder>` tag. Defaults to "". */
-	suffix?: string;
 	/** Emit the text bare, with no `<system-reminder>` frame. */
 	raw?: boolean;
-	/** `user-prepend` only: skip when the same text is already pending (the shared caveat). */
+	/** `first-prepend` only: sent only inside the mid-conversation system message, never on a user message. */
+	systemRoleOnly?: boolean;
+	/** `sticky-append` only: never on the message that carries the context stack, which already says the same. */
+	skipStackCarrier?: boolean;
+	/** `user-prepend` only: placed once per request, however many are pending (the shared caveat). */
 	once?: boolean;
+	/** `user-prepend` only: on a request that does not open with a prompt (mid-turn, an overflow retry), the tail carries it instead. */
+	orTail?: boolean;
+	/** A one-shot dropped, undelivered, at a later compaction (a post-compaction restore). */
+	untilCompaction?: boolean;
+	/** A one-shot only: the files whose whole content it shows, recorded on its pending entry (`PendingRecordData.observations`). */
+	observations?: FileVersion[];
+	/** A one-shot only: the changed file versions it names, recorded on its pending entry (`PendingRecordData.notified`). */
+	notified?: FileVersion[];
 	/**
-	 * `sticky-append` only: anchor the block from this timestamp instead of now —
-	 * `0` puts it on every user message in the session, including ones a resume
-	 * brought back (the `<total_tokens>` line rides every user message in CC).
+	 * `sticky-append` only: the state is on from this timestamp instead of now.
+	 * `0` puts it on every user message (the `<total_tokens>` line rides every
+	 * user message in Claude Code).
 	 */
 	since?: number;
+	/**
+	 * The tool call whose result this reminder belongs to. A one-shot rides that
+	 * result when the request carries it; a sticky state rides it first. Both
+	 * avoid attaching a switch or countdown to another call in a parallel batch.
+	 */
+	toolCallId?: string;
+	/**
+	 * A one-shot only: the timestamp of the user message it belongs to (a
+	 * prompt's hook context). It rides that message when the request carries
+	 * it, so a prompt whose request failed keeps its own context when the
+	 * next prompt resends it.
+	 */
+	promptTimestamp?: number;
+	/** `first-prepend` only: what the block tells the model, recorded when an epoch sends it. */
+	facts?: ToldFact[];
 }
 
-interface StoredReminder extends ReminderEntry {
-	key?: string;
+/** The fact that the whole-text block `key` told `value` (a text, or a snapshot such as a git status). */
+export function toldBlockFact(key: string, value: unknown): BlockFact {
+	return { kind: "block", key, hash: contentHash(value) };
 }
 
-type EnqueueOptions = {
-	scope?: ReminderScope;
-	key?: string;
-	placement?: ReminderPlacement;
-	order?: number;
-	suffix?: string;
+/** A live `first-prepend` block. */
+export interface StackEntry {
+	key: string;
+	text: string;
+	order: number;
 	raw?: boolean;
-	/** Test seam / explicit anchor for `sticky-append`; defaults to now. */
-	since?: number;
-	/** `user-prepend` only: skip when the same text is already pending. */
-	once?: boolean;
-};
+	systemRoleOnly?: boolean;
+	facts?: ToldFact[];
+}
 
-export class ReminderQueue {
-	private nextTurn: StoredReminder[] = [];
-	/** Delivered one-shots, each fixed to the message it first rode (see `pin`). */
-	private pinned: StoredReminder[] = [];
-	private everyTurn = new Map<string, StoredReminder>();
-	private readonly now: () => number;
+/** A live `sticky-append` state. */
+export interface StickyEntry {
+	key: string;
+	text: string;
+	raw?: boolean;
+	/** When it switched on: user messages stamped at or after it carry it. */
+	since: number;
+	toolCallId?: string;
+	skipStackCarrier?: boolean;
+}
 
-	constructor(now: () => number = Date.now) {
-		this.now = now;
-	}
+/** A sticky state as a render places it: `delivered` once an answered request in the epoch carried it (its `stickyFact` is told), so a tool-result pin is only for its first delivery. */
+export type StickyToPlace = StickyEntry & { delivered: boolean };
 
-	enqueue(text: string, opts?: EnqueueOptions): void {
-		if (!text.trim()) return;
-		const placement = opts?.placement ?? "last-append";
-		const entry: StoredReminder = {
-			text,
-			placement,
-			order: opts?.order ?? 0,
-			suffix: opts?.suffix,
-			key: opts?.key,
-			raw: opts?.raw,
-		};
-		if (placement === "sticky-append") {
-			// A standing reminder re-emitted with the SAME text (plan mode re-emits
-			// every turn) keeps its anchor, so the blocks on earlier messages do not
-			// move. Different text under the same key is a new fact (plan → auto
-			// under the shared "permission-mode" key) and anchors from now.
-			const previous = opts?.key !== undefined ? this.everyTurn.get(opts.key) : undefined;
-			entry.since =
-				opts?.since ??
-				(previous?.placement === "sticky-append" && previous.text === text ? previous.since : undefined) ??
-				this.now();
-		}
-		if (opts?.scope === "every-turn") {
-			this.everyTurn.set(opts.key ?? text, entry);
-			return;
-		}
-		// A breadcrumb run shares one caveat block (`once`): the same text pending
-		// twice would show the model two identical blocks in a row. Only the
-		// announcer's caveat asks for this — two commands with the same (empty)
-		// stdout are two commands, and both stay.
-		if (placement === "user-prepend" && opts?.once && this.nextTurn.some((r) => r.placement === placement && r.text === text)) return;
-		// A keyed next-turn reminder replaces its predecessor, so a rapidly
-		// re-emitted state change (cycling permission modes) announces only
-		// where it settled.
-		if (opts?.key) this.nextTurn = this.nextTurn.filter((r) => r.key !== opts.key);
-		this.nextTurn.push(entry);
-	}
+/** A one-shot to place on this request: a pending entry, or a block an owner rendered for it. */
+export interface OneShot {
+	/** The pending entry's id; absent on a render-time block. */
+	id?: string;
+	text: string;
+	raw?: boolean;
+	placement: "last-append" | "user-prepend";
+	toolCallId?: string;
+	promptTimestamp?: number;
+	once?: boolean;
+	orTail?: boolean;
+	facts?: ToldFact[];
+}
 
-	remove(key: string): void {
-		this.everyTurn.delete(key);
-	}
+/** What a capability owner adds on RENDER_CHANNEL. */
+export interface RenderedBlock {
+	text: string;
+	/** What the block tells the model, recorded with the request that carries it. */
+	facts?: ToldFact[];
+}
 
-	/**
-	 * Take the pending `last-append` one-shots out of the queue — for the
-	 * `tool_result` hook, which writes them into the stored result. Other
-	 * placements stay queued for the next request.
-	 */
-	takeOneShots(): ReminderEntry[] {
-		const { matching, rest } = partition(this.nextTurn, (r) => r.placement === "last-append");
-		this.nextTurn = rest;
-		return matching.map(strip);
-	}
+/** The RENDER_CHANNEL payload. */
+export interface RenderRequest {
+	/** True when the request opens an epoch: the live stack is rendered, so owners add nothing. */
+	epoch: boolean;
+	/** What the epoch has told the model so far, by fact kind. */
+	told: ReadonlyMap<string, ReadonlySet<string>>;
+	/** Modes the epoch has told, by key: on or off as last told. */
+	modes: ReadonlyMap<string, boolean>;
+	/** Whole-text blocks the epoch has told, by key: the content hash of the text last told (`toldBlockFact`). */
+	toldBlocks: ReadonlyMap<string, string>;
+	/** The request's model. */
+	model: { provider?: string; api?: string; id?: string; compat?: unknown } | undefined;
+	/** Blocks for the tail of this request. */
+	blocks: RenderedBlock[];
+}
 
-	/**
-	 * Fix the pending one-shots of `placement` to `anchor` — the message they
-	 * ride on this request — so every later request re-attaches them there
-	 * unchanged. Called by the owner at `context` time, after it has decided the
-	 * tail: `last-append` goes on the tail (`tailAnchor`), `user-prepend` only
-	 * on a request that ends in a user-like message (`openingUserAnchor`) —
-	 * mid-turn, breadcrumbs stay queued.
-	 */
-	pin(anchor: PinAnchor, placement: "last-append" | "user-prepend" = "last-append"): void {
-		const { matching, rest } = partition(this.nextTurn, (r) => r.placement === placement);
-		for (const entry of matching) this.pinned.push({ ...entry, pin: anchor });
-		this.nextTurn = rest;
+/**
+ * The live reminder state: the `first-prepend` stack and the open sticky
+ * states, as their owners last emitted them. One-shots are not held here:
+ * they are persisted as pending entries when emitted.
+ */
+export class LiveReminders {
+	private stack = new Map<string, StackEntry>();
+	/** Open states in the order they switched on. */
+	private sticky = new Map<string, StickyEntry>();
+	private readonly now: () => number;
+
+	constructor(now: () => number = Date.now) {
+		this.now = now;
 	}
 
 	/**
-	 * Everything to inject on this request: every-turn state, pinned one-shots,
-	 * then whatever is still pending. A `user-prepend` breadcrumb leaves the
-	 * queue only through `pin(anchor, "user-prepend")` (it must land on a user
-	 * message, not a tool result), so an unpinned one stays for the next request. `messages` is the request being built:
-	 * pins whose anchor is no longer in it (compacted away, or left behind on
-	 * another branch) are dropped here, as part of draining, so no caller can
-	 * forget the step. Nothing else is ever evicted: a pin is one small object,
-	 * and removing a pin whose message is still in context would change that
-	 * message and re-cache everything after it — the old "oldest past 400" cap
-	 * did exactly that (CACHE-REVIEW-2026-09-04 M3).
+	 * Apply one reminder payload. Returns "one-shot" for a `last-append` or
+	 * `user-prepend` reminder, which the caller persists as a pending entry.
 	 */
-	drain(messages: AgentMessage[]): ReminderEntry[] {
-		if (this.pinned.length > 0) {
-			const locate = pinLocator(messages);
-			this.pinned = this.pinned.filter((entry) => locate(entry.pin as PinAnchor) !== -1);
+	apply(payload: ReminderPayload): "live" | "one-shot" | "ignored" {
+		const placement = payload.placement ?? "last-append";
+		if (payload.remove) {
+			if (!payload.key) return "ignored";
+			this.stack.delete(payload.key);
+			this.sticky.delete(payload.key);
+			return "live";
 		}
-		const { matching: held, rest: pending } = partition(this.nextTurn, (r) => r.placement === "user-prepend");
-		this.nextTurn = held;
-		return [...[...this.everyTurn.values()].map(strip), ...this.pinned.map(strip), ...pending.map(strip)];
+		const text = payload.text;
+		if (typeof text !== "string" || !text.trim()) return "ignored";
+		if (placement === "last-append" || placement === "user-prepend") return "one-shot";
+		const key = payload.key ?? text;
+		if (placement === "first-prepend") {
+			const entry: StackEntry = { key, text, order: payload.order ?? 0 };
+			if (payload.raw) entry.raw = true;
+			if (payload.systemRoleOnly) entry.systemRoleOnly = true;
+			if (payload.facts) entry.facts = payload.facts;
+			this.stack.set(key, entry);
+			return "live";
+		}
+		const previous = this.sticky.get(key);
+		const same = previous && previous.text === text && !!previous.raw === !!payload.raw && !!previous.skipStackCarrier === !!payload.skipStackCarrier;
+		// Re-emitting an unchanged standing state keeps its start and delivery; a
+		// changed one is a new state from now.
+		if (same && (payload.since === undefined || payload.since === previous.since)) return "live";
+		const entry: StickyEntry = { key, text, since: payload.since ?? this.now() };
+		if (payload.raw) entry.raw = true;
+		if (payload.skipStackCarrier) entry.skipStackCarrier = true;
+		if (payload.toolCallId) entry.toolCallId = payload.toolCallId;
+		this.sticky.delete(key);
+		this.sticky.set(key, entry);
+		return "live";
 	}
 
-	get size(): number {
-		return this.everyTurn.size + this.nextTurn.length + this.pinned.length;
+	/** The stack in Claude Code's order (`order`, then emission order). */
+	stackEntries(): StackEntry[] {
+		return [...this.stack.values()].map((entry, i) => ({ entry, i })).sort((a, b) => a.entry.order - b.entry.order || a.i - b.i).map((x) => x.entry);
 	}
 
-	/** True when a one-shot of `placement` is waiting to be delivered (the owner decides where). */
-	hasPending(placement: "last-append" | "user-prepend"): boolean {
-		return this.nextTurn.some((r) => r.placement === placement);
+	stickyEntries(): StickyEntry[] {
+		return [...this.sticky.values()];
 	}
+}
 
-	/** `hasPending("last-append")` — kept for the existing callers and tests. */
-	get hasPendingOneShots(): boolean {
-		return this.hasPending("last-append");
-	}
+/** The told fact of a sticky state's first delivery: it follows the branch, and a failed request's is revoked. */
+export function stickyFact(entry: Pick<StickyEntry, "key" | "text" | "since">): BlockFact {
+	return toldBlockFact(`sticky:${entry.key}`, { since: entry.since, text: entry.text });
 }
 
-/** One pass: the entries `test` accepts and the rest, in order. */
-function partition<T>(items: T[], test: (item: T) => boolean): { matching: T[]; rest: T[] } {
-	const matching: T[] = [];
-	const rest: T[] = [];
-	for (const item of items) (test(item) ? matching : rest).push(item);
-	return { matching, rest };
+export interface RenderInput {
+	/** The request opens an epoch: the stack goes on the first user message. */
+	epoch: boolean;
+	/** The model takes a mid-conversation system message (`systemRoleOnly` blocks render, `moved` is filled). */
+	layout: boolean;
+	stack: readonly StackEntry[];
+	sticky: readonly StickyToPlace[];
+	oneShots: readonly OneShot[];
 }
 
-function strip(r: StoredReminder): ReminderEntry {
-	const entry: ReminderEntry = { text: r.text, placement: r.placement, order: r.order, suffix: r.suffix };
-	if (r.raw) entry.raw = true;
-	if (r.since !== undefined) entry.since = r.since;
-	if (r.pin !== undefined) entry.pin = r.pin;
-	return entry;
+export interface RenderResult {
+	messages: AgentMessage[];
+	/** The stack blocks that move to the mid-conversation system message (epoch and layout only). */
+	moved: MovedBlock[];
+	/** True when the stack was placed. */
+	stackPlaced: boolean;
+	/** The sticky states this request carried. */
+	stickyPlaced: string[];
+	/** The one-shots this request carried. */
+	placed: OneShot[];
 }
 
+type ContentBlock = TextContent | ImageContent;
+
 /**
- * One pass over `messages` → a lookup from a pin to the index of the message it
- * rides (-1 when that message left the context). Built once per request by the
- * queue's drain and once by injectReminders, so pin count never multiplies the
- * message count on the per-request path.
+ * The request's messages (its tail, or all of them on an epoch) with the
+ * reminders placed, and what was placed. The input is not mutated. A one-shot
+ * that finds no anchor is not placed and stays pending.
  */
-function pinLocator(messages: AgentMessage[]): (pin: PinAnchor) => number {
-	const byToolCall = new Map<string, number>();
-	const byTimestamp = new Map<number, number>();
-	messages.forEach((m, index) => {
-		if (m.role === "toolResult") {
-			const id = (m as { toolCallId?: string }).toolCallId;
-			if (typeof id === "string" && !byToolCall.has(id)) byToolCall.set(id, index);
-		} else if (isUserLike(m)) {
-			const stamp = (m as { timestamp?: number }).timestamp;
-			if (typeof stamp === "number" && !byTimestamp.has(stamp)) byTimestamp.set(stamp, index);
+export function renderReminders(messages: readonly AgentMessage[], input: RenderInput): RenderResult {
+	const before = new Map<number, TextContent[]>();
+	const after = new Map<number, TextContent[]>();
+	const push = (map: Map<number, TextContent[]>, index: number, blocks: TextContent[]) => {
+		if (index < 0 || blocks.length === 0) return;
+		map.set(index, [...(map.get(index) ?? []), ...blocks]);
+	};
+	const firstUser = messages.findIndex(isUserLike);
+	const lastUser = messages.findLastIndex(isUserLike);
+	const last = messages.length - 1;
+	// Mid-turn, the request ends in the tool results the model is about to read:
+	// a one-shot belongs there. Otherwise on the last user turn.
+	const tail = last >= 0 && messages[last].role === "toolResult" ? last : lastUser;
+	const stackAt = firstUser === -1 ? tail : firstUser;
+
+	let stackPlaced = false;
+	let moved: MovedBlock[] = [];
+	if (input.epoch && stackAt !== -1) {
+		const stack = input.stack.filter((entry) => input.layout || !entry.systemRoleOnly);
+		push(before, stackAt, stack.map(block));
+		stackPlaced = stack.length > 0;
+		if (input.layout) {
+			moved = stack.filter((entry) => movesToSystemRole(entry.order)).map((entry) => ({ framed: framedReminderText(entry), inner: entry.text }));
 		}
-	});
-	return (pin) => (pin.kind === "toolResult" ? byToolCall.get(pin.toolCallId) : byTimestamp.get(pin.timestamp)) ?? -1;
-}
+	}
 
-/** The anchor a one-shot lands on for this request: the trailing tool result, else the last user-like message. */
-export function tailAnchor(messages: AgentMessage[]): PinAnchor | undefined {
-	const last = messages[messages.length - 1] as (AgentMessage & { toolCallId?: string }) | undefined;
-	if (last?.role === "toolResult" && typeof last.toolCallId === "string") return { kind: "toolResult", toolCallId: last.toolCallId };
-	for (let i = messages.length - 1; i >= 0; i--) {
-		const m = messages[i] as AgentMessage & { timestamp?: number };
-		if (isUserLike(m) && typeof m.timestamp === "number") {
-			return { kind: "user", timestamp: m.timestamp };
+	const stickyPlaced: string[] = [];
+	for (const state of input.sticky) {
+		const carriers: number[] = [];
+		messages.forEach((message, index) => {
+			if (!isStickyCarrier(message) || stamp(message) < state.since) return;
+			if (state.skipStackCarrier && input.epoch && index === firstUser) return;
+			carriers.push(index);
+		});
+		// The pin is for a state switched on mid-turn; one on from the start
+		// (`since: 0`, the constant budget line) rides user messages only.
+		if (!state.delivered && state.since > 0) {
+			const first = firstResultAfter(messages, state);
+			if (first !== -1 && !carriers.includes(first)) carriers.unshift(first);
+		}
+		if (carriers.length === 0) continue;
+		stickyPlaced.push(state.key);
+		for (const index of carriers.sort((a, b) => a - b)) push(after, index, [block(state)]);
+	}
+
+	const placed: OneShot[] = [];
+	const opening = last >= 0 && isUserLike(messages[last]) ? last : -1;
+	const placedOnce = new Set<string>();
+	for (const shot of input.oneShots) {
+		if (shot.placement === "user-prepend" && (opening !== -1 || !shot.orTail)) {
+			if (opening === -1) continue;
+			placed.push(shot);
+			if (shot.once && placedOnce.has(shot.text)) continue;
+			if (shot.once) placedOnce.add(shot.text);
+			push(before, opening, [block(shot)]);
+			continue;
 		}
+		const own = shot.toolCallId
+			? messages.findIndex((m) => m.role === "toolResult" && (m as { toolCallId?: string }).toolCallId === shot.toolCallId)
+			: shot.promptTimestamp !== undefined
+				? promptAt(messages, shot.promptTimestamp)
+				: -1;
+		const at = own !== -1 ? own : tail;
+		if (at === -1) continue;
+		placed.push(shot);
+		push(after, at, [block(shot)]);
 	}
-	return undefined;
+
+	const changed = before.size > 0 || after.size > 0;
+	return {
+		messages: changed ? messages.map((m, index) => withBlocks(m, before.get(index) ?? [], after.get(index) ?? [])) : [...messages],
+		moved,
+		stackPlaced,
+		stickyPlaced,
+		placed,
+	};
+}
+
+function stamp(message: AgentMessage): number {
+	return (message as { timestamp?: number }).timestamp ?? 0;
 }
 
+/** How much later pi may stamp a custom message it rebuilt from the session than the one it delivered. */
+const RESTAMP_WINDOW_MS = 1000;
+
 /**
- * The anchor for a `user-prepend` breadcrumb on this request: the trailing
- * message when it is a user-like turn (the prompt that opens the request), else
- * undefined — mid-turn (a trailing tool result) the breadcrumbs keep waiting.
+ * The prompt a one-shot's `promptTimestamp` names, or -1 when the request does
+ * not carry it. pi stores a custom message (a `/skill:` invocation) with the
+ * time it persisted it, at `message_end`, so after `/reload` or resume the
+ * rebuilt message is stamped a little after the delivered one the pin took;
+ * a user message keeps its own stamp.
  */
-export function openingUserAnchor(messages: AgentMessage[]): PinAnchor | undefined {
-	const last = messages[messages.length - 1] as (AgentMessage & { timestamp?: number }) | undefined;
-	if (last && isUserLike(last) && typeof last.timestamp === "number") return { kind: "user", timestamp: last.timestamp };
-	return undefined;
+function promptAt(messages: readonly AgentMessage[], timestamp: number): number {
+	const exact = messages.findIndex((m) => isStickyCarrier(m) && stamp(m) === timestamp);
+	if (exact !== -1) return exact;
+	return messages.findIndex((m) => m.role === "custom" && stamp(m) > timestamp && stamp(m) - timestamp < RESTAMP_WINDOW_MS);
 }
 
-/** A tool result's content with reminder blocks appended (for the `tool_result` hook). */
-export function appendReminderBlocks(content: ContentBlock[], entries: ReminderEntry[]): ContentBlock[] {
-	return [...content, ...entries.map(reminderBlock)];
+/**
+ * Where a state switched on mid-turn first shows: its switching call's result
+ * when the request carries it, else (that result compacted away, or no call
+ * named) the first tool result stamped after the switch, but never one after a
+ * user message that already carries it. With no carrier at all (an overflow
+ * compaction kept only a reply and its results), the request's tail.
+ */
+function firstResultAfter(messages: readonly AgentMessage[], state: StickyEntry): number {
+	if (state.toolCallId !== undefined) {
+		const own = messages.findIndex((m) => m.role === "toolResult" && (m as { toolCallId?: string }).toolCallId === state.toolCallId);
+		if (own !== -1) return own;
+	}
+	for (let i = 0; i < messages.length; i++) {
+		const message = messages[i];
+		if (stamp(message) < state.since) continue;
+		if (isStickyCarrier(message)) return -1;
+		if (message.role === "toolResult") return i;
+	}
+	if (messages.some(isStickyCarrier)) return -1;
+	const last = messages.length - 1;
+	return last >= 0 && messages[last].role === "toolResult" ? last : -1;
 }
 
 /**
@@ -381,14 +481,17 @@ export const COMPACTION_SUMMARY_PREFIX =
 	"The conversation history before this point was compacted into the following summary:\n\n<summary>\n";
 export const COMPACTION_SUMMARY_SUFFIX = "\n</summary>";
 
-type ContentBlock = TextContent | ImageContent;
-
 function toBlocks(content: string | ContentBlock[]): ContentBlock[] {
 	return typeof content === "string" ? [{ type: "text", text: content }] : [...content];
 }
 
-function reminderBlock(entry: ReminderEntry): TextContent {
-	return { type: "text", text: (entry.raw ? entry.text : wrapReminder(entry.text)) + (entry.suffix ?? "") };
+/** A reminder's text exactly as it rides a message: framed, unless raw. */
+export function framedReminderText(entry: { text: string; raw?: boolean }): string {
+	return entry.raw ? entry.text : wrapReminder(entry.text);
+}
+
+function block(entry: { text: string; raw?: boolean }): TextContent {
+	return { type: "text", text: framedReminderText(entry) };
 }
 
 /**
@@ -396,9 +499,7 @@ function reminderBlock(entry: ReminderEntry): TextContent {
  * (task notification, wakeup, hook context, `<new-diagnostics>`); pi's
  * `convertToLlm` sends it to the model as `role: "user"`, so on the wire it IS
  * a user turn — and a turn opened by one (a `/loop` tick, an agent report
- * arriving while idle) has no `user` message of its own. Before 2026-09-05 such
- * a request got no context stack at all, and its pending one-shots pinned to
- * the previous user message (STEERING-REVIEW-2026-09-05 H1).
+ * arriving while idle) has no `user` message of its own (STEERING-REVIEW-2026-09-05 H1).
  */
 function isUserLike(m: AgentMessage): boolean {
 	return isStickyCarrier(m) || m.role === "compactionSummary";
@@ -427,92 +528,3 @@ function withBlocks(message: AgentMessage, before: TextContent[], after: TextCon
 	const target = message as AgentMessage & { content: string | ContentBlock[] };
 	return { ...target, content: [...before, ...toBlocks(target.content), ...after] } as AgentMessage;
 }
-
-/**
- * Returns a copy of `messages` with reminder blocks injected (Claude Code
- * convention: reminders ride inside message content blocks, never as messages
- * of their own). See the module header for the three placements. A bare string
- * is `last-append` (back-compat). The input array and its messages are not
- * mutated. With nothing to anchor to (no user, tool-result, or compaction
- * summary message), messages are returned unchanged and the caller keeps the
- * reminders queued.
- */
-export function injectReminders(messages: AgentMessage[], reminders: Array<string | ReminderEntry>): AgentMessage[] {
-	if (reminders.length === 0) return messages;
-
-	const entries: ReminderEntry[] = reminders.map((r) =>
-		typeof r === "string" ? { text: r, placement: "last-append", order: 0 } : r,
-	);
-	const firstPrepend = entries
-		.filter((e) => e.placement === "first-prepend")
-		.map((e, i) => ({ e, i }))
-		.sort((a, b) => a.e.order - b.e.order || a.i - b.i)
-		.map((x) => x.e);
-	const sticky = entries.filter((e) => e.placement === "sticky-append");
-	const pinnedEntries = entries.filter((e) => e.pin !== undefined);
-	const lastAppend = entries.filter((e) => e.placement === "last-append" && e.pin === undefined);
-	// An unpinned `user-prepend` never reaches here through the queue (drain
-	// holds it back); a caller passing one directly gets it on the opening user
-	// message, before the text, like a pinned one.
-	const looseUserPrepend = entries.filter((e) => e.placement === "user-prepend" && e.pin === undefined);
-
-	const firstUserIndex = messages.findIndex(isUserLike);
-	const lastUserIndex = messages.findLastIndex(isUserLike);
-	const lastIndex = messages.length - 1;
-	// Mid-turn, the request ends in the tool result(s) the model is about to
-	// read — that is where a one-shot reminder belongs. Otherwise the last user turn.
-	const tailIndex = lastIndex >= 0 && messages[lastIndex].role === "toolResult" ? lastIndex : lastUserIndex;
-	if (firstUserIndex === -1 && tailIndex === -1) return messages;
-
-	const before = new Map<number, TextContent[]>();
-	const after = new Map<number, TextContent[]>();
-	const push = (map: Map<number, TextContent[]>, index: number, blocks: TextContent[]) => {
-		if (index < 0 || blocks.length === 0) return;
-		map.set(index, [...(map.get(index) ?? []), ...blocks]);
-	};
-
-	push(before, firstUserIndex === -1 ? tailIndex : firstUserIndex, firstPrepend.map(reminderBlock));
-
-	for (const entry of sticky) {
-		const since = entry.since ?? 0;
-		// The block rides the user message that opened the turn during which the
-		// state switched on (the latest user message stamped before `since` — a
-		// standing reminder emitted on before_agent_start is always stamped after
-		// the turn's user message) and every user message after it. The set only
-		// grows while the state holds, so earlier messages never change.
-		let opener = -1;
-		const carriers: number[] = [];
-		messages.forEach((m, index) => {
-			if (!isStickyCarrier(m)) return;
-			const stamp = (m as { timestamp?: number }).timestamp ?? 0;
-			if (stamp >= since) carriers.push(index);
-			else opener = index;
-		});
-		if (opener !== -1) carriers.unshift(opener);
-		if (carriers.length === 0) {
-			// No user turn at all (overflow compaction mid-turn): ride the tail.
-			push(after, tailIndex === -1 ? firstUserIndex : tailIndex, [reminderBlock(entry)]);
-			continue;
-		}
-		for (const index of carriers) push(after, index, [reminderBlock(entry)]);
-	}
-
-	push(after, tailIndex === -1 ? firstUserIndex : tailIndex, lastAppend.map(reminderBlock));
-	if (lastUserIndex !== -1) push(before, lastUserIndex, looseUserPrepend.map(reminderBlock));
-
-	// Pinned one-shots ride the exact message they first landed on; a message
-	// compacted away simply no longer carries its pin. A pinned breadcrumb sits
-	// BEFORE that message's text (after the first-prepend stack, which was
-	// pushed first); every other pin sits after it.
-	if (pinnedEntries.length > 0) {
-		const locate = pinLocator(messages);
-		for (const entry of pinnedEntries) {
-			const index = locate(entry.pin as PinAnchor);
-			if (index === -1) continue;
-			push(entry.placement === "user-prepend" ? before : after, index, [reminderBlock(entry)]);
-		}
-	}
-
-	if (before.size === 0 && after.size === 0) return messages;
-	return messages.map((m, index) => withBlocks(m, before.get(index) ?? [], after.get(index) ?? []));
-}