one-code-extension 0.4.0 → 0.5.0

package/extensions/lib/reminders.ts

@@ -1,7 +1,8 @@
 /**
  * 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.
+ * pi's `context` event. Context and sticky snapshots are stored as hidden custom
+ * entries by the owner, never as rendered transcript messages.
  *
  * Cross-extension contract: emit on the event bus channel
  * `one-code:system-reminder` with `{ text, scope?, placement? }` to enqueue from
@@ -16,14 +17,18 @@
  *   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.
+ *   mode, a worktree session, ultracode). Appended to EVERY user message
+ *   stamped after the state switched on (`since`). Mid-turn it first rides the
+ *   switching call's tool result (`toolCallId` → `tailPin`), or the first
+ *   carrier after the switch, never the already-cached turn opener. That pin
+ *   and every later user carrier keep identical bytes. Switching off CLOSES
+ *   the lifetime (`until`) and freezes its actual user carriers (`userPins`),
+ *   so queued input cannot acquire past state. It never removes blocks from
+ *   history. Re-entry opens a separate lifetime. Closed lifetimes
+ *   are persisted alongside open ones and dropped only when all their carriers
+ *   leave the context (compaction/fork). They never migrate onto a compaction
+ *   summary; retained messages still carry their historical blocks. Legacy
+ *   `opener` anchors are honored on resume, but never created for new states.
  * - `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:
@@ -33,8 +38,8 @@
  *   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).
+ *   message on every later request, byte-identical. Pins are persisted with
+ *   sticky lifetimes so a resume also preserves the switch announcements.
  * - `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
@@ -82,11 +87,18 @@ export type PinAnchor = { kind: "toolResult"; toolCallId: string } | { kind: "us
 
 /**
  * `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,17 +106,37 @@ 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;
 
+/**
+ * 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;
+}
+
 /** A drained reminder with everything the injector needs to place it. */
 export interface ReminderEntry {
+	/** Present in session snapshots; not rendered into the request. */
+	key?: string;
 	text: string;
 	placement: ReminderPlacement;
 	order: number;
@@ -115,11 +147,28 @@ export interface ReminderEntry {
 	 */
 	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.
+	 * `sticky-append` only: when the state switched on. Every user message
+	 * stamped at or after it carries the block while open. Closing freezes the
+	 * actual carriers in `userPins`; legacy snapshots use `until` as the end.
 	 */
 	since?: number;
+	/** `sticky-append` only: exclusive end of a closed lifetime; absent while active. */
+	until?: number;
+	/** Actual user carriers of the last request; frozen on close, so queued input cannot acquire old state. */
+	userPins?: number[];
+	/** Pending sticky activation belongs to this call, not another result in its parallel batch. */
+	toolCallId?: string;
+	/**
+	 * Legacy `sticky-append` anchor from older snapshots. Honored to keep their
+	 * bytes stable on resume; new lifetimes use null, never an earlier opener.
+	 */
+	opener?: number | null;
+	/**
+	 * `sticky-append` only: its first mid-turn tool result, or the tail of a
+	 * request without any user carrier (overflow compaction). Once chosen it
+	 * stays on that message, even after later user turns arrive or state closes.
+	 */
+	tailPin?: PinAnchor;
 	/** Set on a pinned one-shot: the exact message it rides on every request. */
 	pin?: PinAnchor;
 	/**
@@ -128,6 +177,17 @@ export interface ReminderEntry {
 	 * result. Defaults to false.
 	 */
 	raw?: boolean;
+	/**
+	 * `first-prepend` only: sent only inside the mid-conversation system
+	 * message, never on the user message of a model without one (Claude Code's
+	 * auto-mode note).
+	 */
+	systemRoleOnly?: boolean;
+	/**
+	 * `sticky-append` only: never on the message that carries the context
+	 * stack, which already says the same (the first prompt's `<total_tokens>`).
+	 */
+	skipStackCarrier?: boolean;
 }
 
 export interface ReminderPayload {
@@ -135,7 +195,7 @@ export interface ReminderPayload {
 	scope?: ReminderScope;
 	/** Key so a reminder can be replaced (next-turn) or replaced/removed (every-turn). */
 	key?: string;
-	/** Remove the every-turn reminder registered under `key` instead of enqueueing. */
+	/** Close a sticky lifetime under `key`; remove other every-turn reminders. */
 	remove?: boolean;
 	/** Where in the message stack this reminder lands. Defaults to `last-append`. */
 	placement?: ReminderPlacement;
@@ -145,6 +205,10 @@ export interface ReminderPayload {
 	suffix?: string;
 	/** Emit the text bare, with no `<system-reminder>` frame. */
 	raw?: boolean;
+	/** `first-prepend` only: sent only inside the mid-conversation system message (see ReminderEntry). */
+	systemRoleOnly?: boolean;
+	/** `sticky-append` only: never on the message that carries the context stack (see ReminderEntry). */
+	skipStackCarrier?: boolean;
 	/** `user-prepend` only: skip when the same text is already pending (the shared caveat). */
 	once?: boolean;
 	/**
@@ -153,6 +217,13 @@ export interface ReminderPayload {
 	 * brought back (the `<total_tokens>` line rides every user message in CC).
 	 */
 	since?: number;
+	/**
+	 * The tool call whose result this reminder belongs to. For `last-append`,
+	 * only that result's `tool_result` hook takes the one-shot. For a new sticky
+	 * lifetime, that result is its first pin. Both avoid attaching a switch or
+	 * countdown to another call in a parallel batch.
+	 */
+	toolCallId?: string;
 }
 
 interface StoredReminder extends ReminderEntry {
@@ -166,10 +237,14 @@ type EnqueueOptions = {
 	order?: number;
 	suffix?: string;
 	raw?: boolean;
+	systemRoleOnly?: boolean;
+	skipStackCarrier?: 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;
+	/** The switching tool result, or the hook that takes a one-shot (see ReminderPayload). */
+	toolCallId?: string;
 };
 
 export class ReminderQueue {
@@ -177,15 +252,34 @@ export class ReminderQueue {
 	/** Delivered one-shots, each fixed to the message it first rode (see `pin`). */
 	private pinned: StoredReminder[] = [];
 	private everyTurn = new Map<string, StoredReminder>();
+	/** Open and closed lifetimes in original insertion order, independent of live keys. */
+	private sticky: StoredReminder[] = [];
 	private readonly now: () => number;
+	/** Only restored keys are protected; fresh sessions retain their existing emitter behavior. */
+	private restoredKeys = new Set<string>();
+	private pendingCapabilities = new Set<string>();
+	private changes = 0;
 
 	constructor(now: () => number = Date.now) {
 		this.now = now;
 	}
 
+	/**
+	 * Moves on every change to what the queue holds (a drain only when it
+	 * re-anchored, pinned or dropped something), so the owner can skip
+	 * serializing a snapshot that cannot have changed.
+	 */
+	get version(): number {
+		return this.changes;
+	}
+
 	enqueue(text: string, opts?: EnqueueOptions): void {
 		if (!text.trim()) return;
 		const placement = opts?.placement ?? "last-append";
+		if (placement === "first-prepend" && opts?.key) {
+			if (this.restoredKeys.has(opts.key)) return;
+			this.pendingCapabilities.delete(opts.key);
+		}
 		const entry: StoredReminder = {
 			text,
 			placement,
@@ -193,20 +287,30 @@ export class ReminderQueue {
 			suffix: opts?.suffix,
 			key: opts?.key,
 			raw: opts?.raw,
+			toolCallId: opts?.toolCallId,
 		};
+		if (opts?.systemRoleOnly) entry.systemRoleOnly = true;
+		if (opts?.skipStackCarrier) entry.skipStackCarrier = true;
+		const key = opts?.key ?? text;
+		const previous = this.everyTurn.get(key);
 		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();
+			// Re-emitting an unchanged standing fact keeps both its anchors and its
+			// position among other blocks. A changed fact opens a new lifetime.
+			const same = previous?.placement === placement && previous.text === text &&
+				previous.suffix === entry.suffix && previous.raw === entry.raw &&
+				previous.skipStackCarrier === entry.skipStackCarrier && previous.order === entry.order ? previous : undefined;
+			entry.since = opts?.since ?? same?.since ?? this.now();
+			entry.userPins = [];
+			if (same && same.since === entry.since && opts?.scope === "every-turn") return;
 		}
+		this.changes++;
 		if (opts?.scope === "every-turn") {
-			this.everyTurn.set(opts.key ?? text, entry);
+			if (previous?.placement === "sticky-append") this.remove(key);
+			this.everyTurn.set(key, entry);
+			if (placement === "sticky-append") {
+				entry.key = key;
+				this.sticky.push(entry);
+			}
 			return;
 		}
 		// A breadcrumb run shares one caveat block (`once`): the same text pending
@@ -222,17 +326,132 @@ export class ReminderQueue {
 	}
 
 	remove(key: string): void {
-		this.everyTurn.delete(key);
+		this.changes++;
+		if (!this.restoredKeys.has(key)) {
+			const entry = this.everyTurn.get(key);
+			if (entry?.placement === "sticky-append") entry.until = this.now();
+			this.everyTurn.delete(key);
+		}
+		this.pendingCapabilities.delete(key);
+	}
+
+	/** Seed before startup emitters. Earlier hooks (context-budget) may already have emitted. */
+	restore(stack: readonly ReminderEntry[], sticky: readonly ReminderEntry[], frozenKeys: ReadonlySet<string>, liveKeys: ReadonlySet<string> = new Set(), pinned: readonly ReminderEntry[] = []): void {
+		this.changes++;
+		const early = [...this.everyTurn.values()];
+		this.everyTurn.clear();
+		this.sticky = [];
+		this.pinned = structuredClone([...pinned]);
+		this.restoredKeys = new Set(frozenKeys);
+		this.pendingCapabilities = new Set(stack.flatMap((entry) => entry.key && liveKeys.has(entry.key) ? [entry.key] : []));
+		for (const source of [...stack, ...sticky]) {
+			const entry = structuredClone(source);
+			if (entry.placement === "sticky-append") this.sticky.push(entry);
+			if (entry.until === undefined) this.everyTurn.set(entry.key ?? entry.text, entry);
+		}
+		for (const entry of early) this.enqueue(entry.text, { ...entry, scope: "every-turn" });
+	}
+
+	/**
+	 * A session start with no snapshot (`/clear` after a resume): the previous
+	 * session's resume locks must not keep the new session's emitters out.
+	 */
+	releaseRestore(): void {
+		this.restoredKeys.clear();
+		this.pendingCapabilities.clear();
+	}
+
+	/** The first request has seen all startup/turn emitters. An absent capability is gone. */
+	finishRestore(): void {
+		if (this.pendingCapabilities.size > 0) this.changes++;
+		for (const key of this.pendingCapabilities) this.everyTurn.delete(key);
+		this.pendingCapabilities.clear();
+	}
+
+	/** A compaction replaces these facts atomically, bypassing only their resume locks. */
+	replaceFirstPrepend(keys: readonly string[], entries: readonly ReminderEntry[]): void {
+		this.changes++;
+		const replaced = new Set(keys);
+		for (const key of replaced) this.everyTurn.delete(key);
+		this.nextTurn = this.nextTurn.filter((entry) => !entry.key || !replaced.has(entry.key));
+		for (const entry of entries) {
+			if (entry.key && replaced.has(entry.key) && entry.placement === "first-prepend") {
+				this.everyTurn.set(entry.key, structuredClone(entry));
+			}
+		}
+	}
+
+	/**
+	 * A `/tree` switch to a branch whose last snapshot is `snapshot`: its
+	 * session facts (`factKeys`, an absent one included), its sticky lifetimes
+	 * and its pins come back, so its messages keep the bytes they were sent
+	 * with. Live state stays live: other first-prepend blocks keep their
+	 * current text, and a lifetime open on the branch stays open only while its
+	 * owner still holds it, else it closes on its recorded carriers. A live
+	 * lifetime the branch shows closed goes on as a new one from now. What the
+	 * branch left behind put here stays until a drain finds its carriers gone.
+	 */
+	restoreBranch(snapshot: { stack: readonly ReminderEntry[]; sticky: readonly ReminderEntry[]; pinned?: readonly ReminderEntry[] }, factKeys: readonly string[]): void {
+		this.replaceFirstPrepend(factKeys, snapshot.stack);
+		const same = (a: ReminderEntry, b: ReminderEntry) => a.key === b.key && a.text === b.text && a.since === b.since;
+		const restored: StoredReminder[] = structuredClone([...snapshot.sticky]);
+		const now = this.now();
+		for (const entry of restored) {
+			if (entry.until !== undefined) continue;
+			const live = this.sticky.find((current) => current.until === undefined && same(current, entry));
+			if (live?.key !== undefined && this.everyTurn.get(live.key) === live) this.everyTurn.set(live.key, entry);
+			else entry.until = now;
+		}
+		this.sticky = [...restored, ...this.sticky.filter((current) => !restored.some((entry) => same(entry, current)))];
+		// The branch's carriers keep their closed copy of a lifetime still live here.
+		for (const [key, live] of this.everyTurn) {
+			if (live.placement !== "sticky-append" || live.until !== undefined || this.sticky.includes(live)) continue;
+			const { toolCallId: _call, tailPin: _pin, opener: _opener, ...state } = live;
+			const reopened: StoredReminder = { ...state, key, since: now, userPins: [] };
+			this.everyTurn.set(key, reopened);
+			this.sticky.push(reopened);
+		}
+		const pinned: StoredReminder[] = structuredClone([...(snapshot.pinned ?? [])]);
+		const known = new Set(pinned.map((entry) => JSON.stringify(strip(entry))));
+		this.pinned = [...pinned, ...this.pinned.filter((entry) => !known.has(JSON.stringify(strip(entry))))];
+		this.changes++;
+	}
+
+	/** A new snapshot supersedes undelivered notices about its old facts. Delivered pins stay history. */
+	cancelPending(keys: readonly string[]): void {
+		const cancelled = new Set(keys);
+		const before = this.nextTurn.length;
+		this.nextTurn = this.nextTurn.filter((entry) => !entry.key || !cancelled.has(entry.key));
+		if (this.nextTurn.length !== before) this.changes++;
+	}
+
+	/** Hidden session metadata, preserving keys and insertion order without changing drain's API. */
+	persistentEntries(placement: "first-prepend" | "sticky-append"): ReminderEntry[] {
+		return [
+			...(placement === "sticky-append" ? this.sticky.map((entry) => ({ ...strip(entry), key: entry.key })) :
+				[...this.everyTurn.entries()].filter(([, entry]) => entry.placement === placement).map(([key, entry]) => ({ ...strip(entry), key }))),
+			...this.nextTurn.filter((entry) => entry.placement === placement).map((entry) => ({ ...strip(entry), key: entry.key })),
+		];
+	}
+
+	/** Delivered steering is history too, especially the notice that closes a sticky state. */
+	persistentPins(): ReminderEntry[] {
+		return this.pinned.map(strip);
 	}
 
 	/**
 	 * Take the pending `last-append` one-shots out of the queue — for the
-	 * `tool_result` hook, which writes them into the stored result. Other
+	 * `tool_result` hook, which writes them into the stored result. A one-shot
+	 * bound to another call's result stays queued for that result's hook. Other
 	 * placements stay queued for the next request.
 	 */
-	takeOneShots(): ReminderEntry[] {
-		const { matching, rest } = partition(this.nextTurn, (r) => r.placement === "last-append");
+	takeOneShots(toolCallId?: string): ReminderEntry[] {
+		const { matching, rest } = partition(
+			this.nextTurn,
+			(r) => r.placement === "last-append" && (r.toolCallId === undefined || r.toolCallId === toolCallId),
+		);
 		this.nextTurn = rest;
+		if (matching.length > 0) this.changes++;
 		return matching.map(strip);
 	}
 
@@ -244,10 +463,16 @@ export class ReminderQueue {
 	 * 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 {
+	pin(anchor: PinAnchor, placement: "last-append" | "user-prepend" = "last-append", messages?: readonly AgentMessage[]): void {
 		const { matching, rest } = partition(this.nextTurn, (r) => r.placement === placement);
-		for (const entry of matching) this.pinned.push({ ...entry, pin: anchor });
+		for (const entry of matching) {
+			// A one-shot bound to a call whose result hook already ran (a read's nested
+			// instructions) rides that call's result, not whichever result ended the batch.
+			const own = entry.toolCallId !== undefined && messages ? ownResultAnchor(messages, entry.toolCallId) : undefined;
+			this.pinned.push({ ...entry, pin: own ?? anchor });
+		}
 		this.nextTurn = rest;
+		if (matching.length > 0) this.changes++;
 	}
 
 	/**
@@ -263,17 +488,51 @@ export class ReminderQueue {
 	 * did exactly that (CACHE-REVIEW-2026-09-04 M3).
 	 */
 	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);
+		const locate = pinLocator(messages);
+		const stackCarrier = messages.findIndex(isUserLike);
+		let changed = false;
+		for (const entry of this.sticky) {
+			if (entry.until !== undefined) continue;
+			if (entry.opener === undefined) {
+				entry.opener = null;
+				changed = true;
+			}
+			// Only live states may find a new carrier after compaction. A closed
+			// state's missing pin must never move to the summary or a later turn.
+			const tailPin = entry.tailPin;
+			if (entry.tailPin && locate(entry.tailPin) === -1) entry.tailPin = undefined;
+			if (entry.tailPin === undefined) entry.tailPin = firstStickyPin(messages, entry);
+			if (!samePin(tailPin, entry.tailPin)) changed = true;
+			// Timestamps alone cannot close a lifetime: a steer typed while it was
+			// active can remain queued until after the switch. Keep only messages
+			// that actually rode the block, including across a startup-time close.
+			const userPins = messages.flatMap((m, index) => carriesSticky(m, entry) &&
+				(!entry.skipStackCarrier || index !== stackCarrier) ? [m.timestamp] : []);
+			// The same array stays while its carriers do, so its lookup set (`carrierSet`) is reused.
+			if (!entry.userPins || entry.userPins.length !== userPins.length || entry.userPins.some((stamp, i) => stamp !== userPins[i])) {
+				entry.userPins = userPins;
+				changed = true;
+			}
+			if ((entry.tailPin || entry.userPins.length > 0) && entry.toolCallId !== undefined) {
+				delete entry.toolCallId;
+				changed = true;
+			}
 		}
+		const sticky = this.sticky.length;
+		this.sticky = this.sticky.filter((entry) => entry.until === undefined ||
+			messages.some((m) => carriesSticky(m, entry)) || (entry.tailPin !== undefined && locate(entry.tailPin) !== -1));
+		const pinned = this.pinned.length;
+		if (this.pinned.length > 0) this.pinned = this.pinned.filter((entry) => locate(entry.pin as PinAnchor) !== -1);
 		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)];
+		if (changed || pending.length > 0 || this.sticky.length !== sticky || this.pinned.length !== pinned) this.changes++;
+		return [...[...this.everyTurn.values()].filter((entry) => entry.placement !== "sticky-append").map(strip),
+			...this.sticky.map(strip), ...this.pinned.map(strip), ...pending.map(strip)];
 	}
 
 	get size(): number {
-		return this.everyTurn.size + this.nextTurn.length + this.pinned.length;
+		return [...this.everyTurn.values()].filter((entry) => entry.placement !== "sticky-append").length +
+			this.sticky.length + this.nextTurn.length + this.pinned.length;
 	}
 
 	/** True when a one-shot of `placement` is waiting to be delivered (the owner decides where). */
@@ -298,7 +557,14 @@ function partition<T>(items: T[], test: (item: T) => boolean): { matching: T[];
 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.systemRoleOnly) entry.systemRoleOnly = true;
+	if (r.skipStackCarrier) entry.skipStackCarrier = true;
 	if (r.since !== undefined) entry.since = r.since;
+	if (r.until !== undefined) entry.until = r.until;
+	if (r.userPins !== undefined) entry.userPins = [...r.userPins];
+	if (r.placement === "sticky-append" && r.toolCallId !== undefined) entry.toolCallId = r.toolCallId;
+	if (r.opener !== undefined) entry.opener = r.opener;
+	if (r.tailPin) entry.tailPin = r.tailPin;
 	if (r.pin !== undefined) entry.pin = r.pin;
 	return entry;
 }
@@ -324,6 +590,49 @@ function pinLocator(messages: AgentMessage[]): (pin: PinAnchor) => number {
 	return (pin) => (pin.kind === "toolResult" ? byToolCall.get(pin.toolCallId) : byTimestamp.get(pin.timestamp)) ?? -1;
 }
 
+function samePin(a: PinAnchor | undefined, b: PinAnchor | undefined): boolean {
+	if (!a || !b) return a === b;
+	return a.kind === "toolResult" ? b.kind === "toolResult" && a.toolCallId === b.toolCallId : b.kind === "user" && a.timestamp === b.timestamp;
+}
+
+/** Each carrier list's lookup set, built once per array: a check runs for every message against every lifetime. */
+const carrierSets = new WeakMap<readonly number[], Set<number>>();
+
+function carrierSet(userPins: readonly number[]): Set<number> {
+	let set = carrierSets.get(userPins);
+	if (!set) carrierSets.set(userPins, (set = new Set(userPins)));
+	return set;
+}
+
+/** Closed lifetimes keep only delivered carriers; legacy snapshots retain their timestamp interval. */
+function carriesSticky(message: AgentMessage, entry: ReminderEntry): boolean {
+	if (!isStickyCarrier(message)) return false;
+	const stamp = (message as { timestamp?: number }).timestamp ?? 0;
+	if (entry.until !== undefined && entry.userPins !== undefined) return carrierSet(entry.userPins).has(stamp);
+	return (stamp >= (entry.since ?? 0) && (entry.until === undefined || stamp < entry.until)) ||
+		(entry.opener !== null && entry.opener !== undefined && stamp === entry.opener);
+}
+
+/** First carrier after activation; never reach back into an earlier user turn. */
+function firstStickyPin(messages: AgentMessage[], entry: ReminderEntry): PinAnchor | undefined {
+	if (entry.until !== undefined) return undefined;
+	if (entry.toolCallId !== undefined) return ownResultAnchor(messages, entry.toolCallId);
+	for (const message of messages) {
+		if (carriesSticky(message, entry)) return undefined;
+		if (message.role === "toolResult" && message.timestamp >= (entry.since ?? 0)) {
+			return { kind: "toolResult", toolCallId: message.toolCallId };
+		}
+	}
+	// Overflow compaction may retain only an old reply/result. With no real
+	// user turn, a live state must still be visible and pinned to that tail.
+	return messages.some(isStickyCarrier) ? undefined : tailAnchor(messages);
+}
+
+/** `toolCallId`'s own result as an anchor, when this request holds it. */
+function ownResultAnchor(messages: readonly AgentMessage[], toolCallId: string): PinAnchor | undefined {
+	return messages.some((m) => m.role === "toolResult" && m.toolCallId === toolCallId) ? { kind: "toolResult", toolCallId } : undefined;
+}
+
 /** 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;
@@ -387,8 +696,13 @@ function toBlocks(content: string | ContentBlock[]): ContentBlock[] {
 	return typeof content === "string" ? [{ type: "text", text: content }] : [...content];
 }
 
+/** A reminder's text exactly as it rides a message: framed (unless raw), then its suffix. */
+export function framedReminderText(entry: Pick<ReminderEntry, "text" | "raw" | "suffix">): string {
+	return (entry.raw ? entry.text : wrapReminder(entry.text)) + (entry.suffix ?? "");
+}
+
 function reminderBlock(entry: ReminderEntry): TextContent {
-	return { type: "text", text: (entry.raw ? entry.text : wrapReminder(entry.text)) + (entry.suffix ?? "") };
+	return { type: "text", text: framedReminderText(entry) };
 }
 
 /**
@@ -473,28 +787,20 @@ export function injectReminders(messages: AgentMessage[], reminders: Array<strin
 
 	push(before, firstUserIndex === -1 ? tailIndex : firstUserIndex, firstPrepend.map(reminderBlock));
 
+	const locate = pinLocator(messages);
 	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 (carriesSticky(m, entry)) carriers.push(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)]);
+		const pin = entry.tailPin ?? firstStickyPin(messages, entry);
+		const pinned = pin ? locate(pin) : -1;
+		if (pinned !== -1 && !carriers.includes(pinned)) carriers.unshift(pinned);
+		if (entry.skipStackCarrier && carriers.includes(firstUserIndex)) {
+			for (const index of carriers.filter((index) => index !== firstUserIndex).sort((a, b) => a - b)) push(after, index, [reminderBlock(entry)]);
 			continue;
 		}
-		for (const index of carriers) push(after, index, [reminderBlock(entry)]);
+		for (const index of carriers.sort((a, b) => a - b)) push(after, index, [reminderBlock(entry)]);
 	}
 
 	push(after, tailIndex === -1 ? firstUserIndex : tailIndex, lastAppend.map(reminderBlock));