one-code-extension 0.3.0 → 0.4.0

package/extensions/lib/paths.ts

@@ -9,8 +9,9 @@
  * other's. See "Own state, borrowed config" in docs/decisions.md.
  */
 
-import { homedir } from "node:os";
-import { join } from "node:path";
+import { realpathSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { isAbsolute, join, relative, resolve } from "node:path";
 
 /**
  * Claude Code's config dir — the compat surface One Code reads, never writes.
@@ -59,3 +60,130 @@ export function expandTilde(path: string, home: string): string {
 export function oneCodeStateDir(env: Record<string, string | undefined> = process.env, home: string = homedir()): string {
 	return env.ONECODE_STATE_DIR || join(home, ".onecode");
 }
+
+/**
+ * A path with forward slashes, in Claude Code's POSIX shape on Windows
+ * (`utils/windowsPaths.ts windowsPathToPosixPath`): `C:\Users\x` becomes
+ * `/c/Users/x`, a UNC `\\server\share` becomes `//server/share`, anything
+ * else only flips its separators. This is the form Claude Code matches
+ * permission path patterns against on Windows, so a rule written for it —
+ * `Read(//c/Users/x/**)` — matches here too. Elsewhere the path is unchanged.
+ */
+export function toPosixPath(path: string): string {
+	if (process.platform !== "win32") return path;
+	if (path.startsWith("\\\\")) return path.replace(/\\/g, "/");
+	const drive = /^([A-Za-z]):[/\\]/.exec(path);
+	if (drive) return `/${drive[1].toLowerCase()}${path.slice(2).replace(/\\/g, "/")}`;
+	return path.replace(/\\/g, "/");
+}
+
+/**
+ * The inverse conversion, for a path spelled the way Git Bash (MSYS2) spells
+ * it, on every platform (pure — `gitBashPathToNative` is the win32-gated
+ * form). Claude Code's `posixPathToWindowsPath` covers the first two shapes:
+ * `/c/Users/x` is `C:\Users\x`, `/cygdrive/c/x` is `C:\x`. The third is Git
+ * for Windows' own mount table: `/tmp/x` is `<tmp>\x`, because its default
+ * fstab mounts `/tmp` on the user's temp dir (`usertemp`; findings §22 saw
+ * `pwd` print `/tmp/…` for a cwd under `%TEMP%`). Every other POSIX absolute
+ * path (`/usr/bin/…`, `/etc/hosts` — files under the Git install) and every
+ * non-POSIX path is returned as given.
+ */
+export function msysPathToWindows(path: string, tmp: string): string {
+	const drive = /^\/(?:cygdrive\/)?([A-Za-z])(?:\/(.*))?$/.exec(path);
+	if (drive) return `${drive[1].toUpperCase()}:\\${(drive[2] ?? "").replace(/\//g, "\\")}`;
+	const temp = /^\/tmp(?:\/(.*))?$/.exec(path);
+	if (temp) return temp[1] ? join(tmp, temp[1]) : tmp;
+	return path;
+}
+
+/**
+ * A token from a bash command line as the path it reaches on this machine:
+ * on Windows the bash tool runs Git Bash, so `/c/…`, `/cygdrive/c/…` and
+ * `/tmp/…` are converted ({@link msysPathToWindows}); elsewhere, and for any
+ * other spelling, the token is unchanged. For bash tokens only — pi's file
+ * tools resolve their paths natively, so a gate judging a file-tool path must
+ * see what `path.resolve` sees.
+ */
+export function gitBashPathToNative(token: string): string {
+	return process.platform === "win32" ? msysPathToWindows(token, tmpdir()) : token;
+}
+
+/**
+ * A Windows system executable by its canonical location, `%SystemRoot%\System32\<name>`
+ * (defaulting to `C:\Windows`), so a PATH entry can never substitute it —
+ * `taskkill.exe`, `cmd.exe`, Windows PowerShell's `powershell.exe`.
+ */
+export function system32Path(name: string, env: Record<string, string | undefined> = process.env): string {
+	return join(env.SystemRoot ?? "C:\\Windows", "System32", name);
+}
+
+/**
+ * The real path of `target`, or undefined when nothing about it resolves:
+ * the native realpath first (on Windows it also expands 8.3 short names and
+ * fixes the case), the JS one as a fallback. Shared by every containment
+ * resolver so "resolved" means one thing.
+ */
+export function tryRealpath(target: string): string | undefined {
+	try {
+		return realpathSync.native(target);
+	} catch {
+		try {
+			return realpathSync(target);
+		} catch {
+			return undefined;
+		}
+	}
+}
+
+/** `path` as given when absolute, else joined onto `base` (no `..` normalisation — the spelling stays recognisable). */
+export function absoluteFrom(base: string, path: string): string {
+	return isAbsolute(path) ? path : join(base, path);
+}
+
+/** Separators as `/`, whatever the platform — for display and for `/`-spelled comparisons. */
+export function forwardSlashes(path: string): string {
+	return path.replace(/\\/g, "/");
+}
+
+/** Filesystems that fold case (darwin, win32): two spellings of one path compare equal. */
+export function foldsCase(): boolean {
+	return process.platform !== "linux";
+}
+
+/**
+ * The one comparison form of a path: resolved, `/` separators, no trailing
+ * slash, case-folded where the filesystem folds (darwin, win32). Every
+ * containment check in the codebase compares these — the shell pre-gate's
+ * `resolveForContainment`/`isWithin`, the permission matcher's session dirs,
+ * the safety floor — so "under this directory" means one thing everywhere.
+ */
+export function comparablePath(path: string): string {
+	const normalized = forwardSlashes(resolve(path)).replace(/\/+$/, "");
+	return foldsCase() ? normalized.toLowerCase() : normalized;
+}
+
+/** Whether `path` is at or under `dir`, on {@link comparablePath} forms. No symlink resolution — resolve both sides first when that matters. */
+export function isPathAtOrUnder(path: string, dir: string): boolean {
+	const target = comparablePath(path);
+	const base = comparablePath(dir);
+	return target === base || target.startsWith(`${base}/`);
+}
+
+/** A `path.relative` result that stays inside its base: non-empty, no `..` hop, not another root/drive. */
+export function isRelativeInside(rel: string): boolean {
+	return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+/**
+ * `~`-abbreviated display form of a path: the home dir itself is `~`, a path
+ * under it is `~/rest` with forward slashes, anything else is returned as
+ * given (`C:\Users\x\.claude` under `C:\Users\x` shows as `~/.claude`;
+ * `path.relative` compares case-insensitively on Windows, like its filesystem).
+ */
+export function tildify(path: string, home: string): string {
+	if (!home) return path;
+	const rest = relative(resolve(home), resolve(path));
+	if (rest === "") return "~";
+	return isRelativeInside(rest) ? `~/${forwardSlashes(rest)}` : path;
+}
+

package/extensions/lib/pi-ai-estimate.ts

@@ -16,7 +16,10 @@
  *
  * So the two consumed helpers (`clampMaxTokensToContext`, `estimateMessageTokens`)
  * and the private estimator chain they depend on are copied here from pi-ai
- * 0.85.0, importing only types from the bare specifier. The two exported helpers
+ * 0.86.1, importing from the bare specifier only types plus `getSystemMessageText`
+ * (which pi-ai re-exports from its entry point, so it needs no vendoring — unlike
+ * the estimate/clamp helpers under `/utils/estimate` and `/api/simple-options`,
+ * which have no bare re-export). The two exported helpers
  * are byte-identical to upstream; the one adaptation is the internal
  * `estimateContextTokens`, narrowed to accept only `Context` (the sole shape we
  * call it with) rather than upstream's `Context | Message[]` overload — the
@@ -24,9 +27,27 @@
  * imports the real deep paths from node_modules and asserts the two exported
  * helpers produce identical numbers, so an upstream change is caught rather than
  * silently drifting.
+ *
+ * pi 0.86.1 changes re-vendored here (from 0.85.0): the `Message` union gained a
+ * `SystemMessage` (its prompt text, `toolsAdded`, and `toolsRemoved` now ride the
+ * transcript, so `estimateMessageTokens` has a `system` branch that calls pi-ai's
+ * `getSystemMessageText`); `addedToolNames` was removed
+ * from `ToolResultMessage`; and `estimateContextTokens` no longer adds
+ * `context.systemPrompt`/`context.tools` separately — it sums the messages alone,
+ * counting the prompt and tools through any `SystemMessage` present.
+ *
+ * pi's `completeSimple`/`streamSimple` run `normalizeContext` (folding
+ * `systemPrompt`/`tools` into a leading `SystemMessage`) BEFORE the clamp, and
+ * `estimateContextTokens` counts the prompt and tools only through that message.
+ * So `normalizeContext` and `createInitialSystemMessage` are vendored here too
+ * (byte-identical to pi-ai's `utils/transcript`), and the compaction extension
+ * normalizes a `Context` before clamping it, exactly as `completeSimple` does —
+ * otherwise a raw `Context`'s `systemPrompt`/`tools` go uncounted and the clamp
+ * over-estimates the output room. `test/unit/pi-ai-estimate.test.ts` locks all
+ * four helpers against the real ones.
  */
 
-import type { Api, Context, ImageContent, Message, Model, TextContent, Tool, Usage } from "@earendil-works/pi-ai";
+import { getSystemMessageText, type Api, type Context, type ImageContent, type Message, type Model, type TextContent, type Usage } from "@earendil-works/pi-ai";
 
 const CHARS_PER_TOKEN = 4;
 const ESTIMATED_IMAGE_CHARS = 4800;
@@ -62,6 +83,9 @@ function estimateTextAndImageContentTokens(content: string | Array<TextContent |
 
 export function estimateMessageTokens(message: Message): number {
 	let chars = 0;
+	if (message.role === "system") {
+		return estimateTextTokens(getSystemMessageText(message)) + estimateToolsTokens(message.toolsAdded) + estimateToolsTokens(message.toolsRemoved);
+	}
 	if (message.role === "user") return estimateTextAndImageContentTokens(message.content);
 	if (message.role === "toolResult") return estimateTextAndImageContentTokens(message.content);
 	for (const block of message.content) {
@@ -122,35 +146,42 @@ function estimateMessages(messages: readonly Message[]): ContextUsageEstimate {
 	return { tokens, usageTokens: 0, trailingTokens: tokens, lastUsageIndex: null };
 }
 
-function estimateToolsTokens(tools: Tool[] | undefined): number {
+// Accepts `Tool[]` (`toolsAdded`) or `ToolReference[]` (`toolsRemoved`); pi's own
+// helper only JSON-stringifies, so the element shape is immaterial.
+function estimateToolsTokens(tools: readonly unknown[] | undefined): number {
 	if (!tools || tools.length === 0) return 0;
 	return estimateTextTokens(safeJsonStringify(tools));
 }
 
+// pi 0.86.1: the prompt and tool declarations ride the transcript as system
+// messages, so this sums the messages alone — no separate systemPrompt/tools
+// term, and no `addedToolNames` accounting (both gone upstream).
 function estimateContextTokens(context: Context): ContextUsageEstimate {
-	const estimate = estimateMessages(context.messages);
-	if (estimate.lastUsageIndex !== null) {
-		const addedNames = new Set(
-			context.messages
-				.slice(estimate.lastUsageIndex + 1)
-				.filter((message) => message.role === "toolResult")
-				.flatMap((message) => (message.role === "toolResult" ? message.addedToolNames ?? [] : [])),
-		);
-		const addedToolTokens = estimateToolsTokens(context.tools?.filter((tool) => addedNames.has(tool.name)));
-		return {
-			tokens: estimate.tokens + addedToolTokens,
-			usageTokens: estimate.usageTokens,
-			trailingTokens: estimate.trailingTokens + addedToolTokens,
-			lastUsageIndex: estimate.lastUsageIndex,
-		};
-	}
-	const prefixTokens = (context.systemPrompt ? estimateTextTokens(context.systemPrompt) : 0) + estimateToolsTokens(context.tools);
-	return {
-		tokens: estimate.tokens + prefixTokens,
-		usageTokens: estimate.usageTokens,
-		trailingTokens: estimate.trailingTokens + prefixTokens,
-		lastUsageIndex: estimate.lastUsageIndex,
-	};
+	return estimateMessages(context.messages);
+}
+
+/**
+ * pi-ai's `createInitialSystemMessage` (`utils/transcript`): the leading system
+ * message carrying the prompt and tool declarations, or undefined when both are
+ * empty. Byte-identical to upstream.
+ */
+export function createInitialSystemMessage(systemPrompt: Context["systemPrompt"], tools: Context["tools"]): Message | undefined {
+	const hasSystemPrompt = systemPrompt !== undefined && systemPrompt.length > 0;
+	const hasTools = tools !== undefined && tools.length > 0;
+	if (!hasSystemPrompt && !hasTools) return undefined;
+	return { role: "system", content: systemPrompt ?? "", ...(hasTools ? { toolsAdded: tools } : {}), timestamp: 0 };
+}
+
+/**
+ * pi-ai's `normalizeContext` (`utils/transcript`): fold `systemPrompt`/`tools`
+ * into a leading system message so the estimate counts them. `completeSimple`
+ * runs this before the clamp; callers of the vendored clamp must do the same.
+ * Returns a plain `Context` (the vendored clamp reads only `.messages`; pi's real
+ * clamp is typed for the branded `TranscriptContext`).
+ */
+export function normalizeContext(context: Context): Context {
+	const initialMessage = createInitialSystemMessage(context.systemPrompt, context.tools);
+	return { messages: initialMessage ? [initialMessage, ...context.messages] : context.messages };
 }
 
 export function clampMaxTokensToContext(model: Model<Api>, context: Context, maxTokens: number): number {

package/extensions/lib/pi-version.ts

@@ -12,7 +12,7 @@
 
 /** Inclusive minimum and exclusive maximum pi version this release is tested against. */
 export const TESTED_PI_MIN = "0.83.0";
-export const TESTED_PI_MAX_EXCLUSIVE = "0.86.0";
+export const TESTED_PI_MAX_EXCLUSIVE = "0.87.0";
 
 /** Dotted-numeric parse; undefined for anything that is not plain x.y.z numbers. */
 export function parseVersion(version: string): number[] | undefined {

package/extensions/lib/process-tree.ts

@@ -1,6 +1,7 @@
 /**
  * Process-tree termination for the shells One Code spawns in the background
- * (`bash run_in_background`, `monitor`).
+ * (`bash run_in_background`, `monitor`), and the one way to wait for such a
+ * child to finish.
  *
  * A `$SHELL -c "cmd"` child is only the leader: with zsh (macOS default) a
  * `cmd; echo` or a pipeline runs the command in further processes, and
@@ -16,20 +17,73 @@
  * `stopProcessTree` adds the grace period: SIGTERM now, SIGKILL if the leader
  * has not exited by then (a command that ignores SIGTERM still closes late,
  * which is exactly the late callback the shutdown paths guard against).
+ *
+ * `waitForChildExit` is the counterpart on the waiting side: it settles on
+ * `exit` plus a short stdio grace, never on `close` alone — a descendant the
+ * kill missed (Windows: a process the `taskkill /T` snapshot did not see) can
+ * hold the inherited pipes open for as long as it lives, and the task must not
+ * wait for it (pi's `waitForChildProcess` has the same shape and reason).
  */
 
-import type { ChildProcess } from "node:child_process";
+import { type ChildProcess, execFile } from "node:child_process";
+import { system32Path } from "./paths.ts";
 
 /** SIGTERM → SIGKILL grace for a stopped background tree (bash tasks, monitors). */
 export const KILL_GRACE_MS = 2_000;
 
-/** `detached` everywhere but Windows, where process groups do not exist. */
-export function detachedSpawnOptions(): { detached: boolean } {
-	return { detached: process.platform !== "win32" };
+/** After `exit`, how long buffered stdio may keep arriving before the wait settles. */
+export const EXIT_STDIO_GRACE_MS = 200;
+
+/** ...and the most it may keep arriving in total: a straggler writing continuously must not keep re-arming the grace. */
+export const EXIT_STDIO_MAX_MS = 2_000;
+
+/**
+ * `detached` everywhere but Windows, where process groups do not exist — except
+ * for a child that must outlive an exiting parent (a fire-and-forget hook),
+ * which is what `detached: true` means on Windows (Node's documented use); the
+ * leader is still killed by pid there.
+ */
+export function detachedSpawnOptions(opts: { outlivesParent?: boolean } = {}): { detached: boolean } {
+	return { detached: process.platform !== "win32" || Boolean(opts.outlivesParent) };
+}
+
+/**
+ * Windows has no process groups and no SIGTERM: `taskkill /T /F` ends the
+ * tree by pid (the same call pi's own `killProcessTree` makes), from System32
+ * so a PATH entry cannot substitute the binary. Whatever taskkill reports, the
+ * leader itself is then terminated directly too — taskkill can fail to kill
+ * (or to find) a member, and the leader's exit is what the waiting side keys
+ * on. `ONECODE_DEBUG_KILL=1` logs taskkill's output to stderr.
+ */
+function taskkillTree(child: ChildProcess): void {
+	const pid = child.pid;
+	if (pid == null) return;
+	const direct = () => {
+		try {
+			child.kill();
+		} catch {
+			// Already gone.
+		}
+	};
+	try {
+		const proc = execFile(system32Path("taskkill.exe"), ["/F", "/T", "/PID", String(pid)], { windowsHide: true }, (error, stdout, stderr) => {
+			if (process.env.ONECODE_DEBUG_KILL) {
+				process.stderr.write(`[process-tree] taskkill /T /F /PID ${pid}: ${error ? `error ${error.message}` : "ok"}\n${stdout}${stderr}`);
+			}
+			direct();
+		});
+		proc.unref();
+	} catch {
+		direct();
+	}
 }
 
 export function killProcessTree(child: ChildProcess, signal: NodeJS.Signals = "SIGTERM"): void {
 	if (child.pid == null) return;
+	if (process.platform === "win32") {
+		taskkillTree(child);
+		return;
+	}
 	try {
 		process.kill(-child.pid, signal);
 	} catch {
@@ -47,6 +101,8 @@ export function killProcessTree(child: ChildProcess, signal: NodeJS.Signals = "S
  */
 export function stopProcessTree(child: ChildProcess, graceMs: number): void {
 	killProcessTree(child, "SIGTERM");
+	// taskkill /F is already forceful; there is no gentler first signal to grace.
+	if (process.platform === "win32") return;
 	if (child.exitCode !== null || child.signalCode !== null) return;
 	const timer = setTimeout(() => {
 		if (child.exitCode === null && child.signalCode === null) killProcessTree(child, "SIGKILL");
@@ -54,3 +110,73 @@ export function stopProcessTree(child: ChildProcess, graceMs: number): void {
 	timer.unref?.();
 	child.once("exit", () => clearTimeout(timer));
 }
+
+export interface ChildExit {
+	code: number | null;
+	signal: NodeJS.Signals | null;
+}
+
+/**
+ * Resolve when the child has exited and its stdio has drained: on `close`
+ * when that arrives promptly, else `EXIT_STDIO_GRACE_MS` after `exit` (the
+ * grace re-arms while output is still arriving, so a burst written just before
+ * exit is not cut) and `EXIT_STDIO_MAX_MS` after `exit` at the latest (a
+ * descendant the kill missed that keeps writing must not hold the wait).
+ * Rejects on a spawn `error`. Listeners the caller attached for `data` keep
+ * working; the streams are destroyed once this settles so a straggler holding
+ * the far end cannot keep them — or the process — alive.
+ */
+export function waitForChildExit(child: ChildProcess): Promise<ChildExit> {
+	return new Promise((resolve, reject) => {
+		let settled = false;
+		let exited: ChildExit | undefined;
+		let grace: NodeJS.Timeout | undefined;
+		let deadline: NodeJS.Timeout | undefined;
+		const cleanup = () => {
+			if (grace) clearTimeout(grace);
+			if (deadline) clearTimeout(deadline);
+			child.removeListener("error", onError);
+			child.removeListener("exit", onExit);
+			child.removeListener("close", onClose);
+			child.stdout?.removeListener("data", onData);
+			child.stderr?.removeListener("data", onData);
+		};
+		const finish = () => {
+			if (settled || !exited) return;
+			settled = true;
+			cleanup();
+			child.stdout?.destroy();
+			child.stderr?.destroy();
+			resolve(exited);
+		};
+		const arm = () => {
+			if (grace) clearTimeout(grace);
+			// Ref'd on purpose: in a one-shot run this timer may be the only handle
+			// left once the pipes have closed, and the promise must still settle.
+			grace = setTimeout(finish, EXIT_STDIO_GRACE_MS);
+		};
+		const onError = (error: Error) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			reject(error);
+		};
+		const onExit = (code: number | null, signal: NodeJS.Signals | null) => {
+			exited = { code, signal };
+			arm();
+			deadline = setTimeout(finish, EXIT_STDIO_MAX_MS);
+		};
+		const onClose = (code: number | null, signal: NodeJS.Signals | null) => {
+			exited ??= { code, signal };
+			finish();
+		};
+		const onData = () => {
+			if (exited && !settled) arm();
+		};
+		child.once("error", onError);
+		child.once("exit", onExit);
+		child.once("close", onClose);
+		child.stdout?.on("data", onData);
+		child.stderr?.on("data", onData);
+	});
+}

package/extensions/lib/reminders.ts

@@ -35,6 +35,15 @@
  *   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.
  *
  * 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
@@ -66,7 +75,7 @@ export const REMINDER_CHANNEL = "one-code:system-reminder";
 export type ReminderScope = "next-turn" | "every-turn";
 
 /** See the module header for which placement fits which kind of reminder. */
-export type ReminderPlacement = "first-prepend" | "sticky-append" | "last-append";
+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 };
@@ -136,6 +145,8 @@ export interface ReminderPayload {
 	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). */
+	once?: boolean;
 	/**
 	 * `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
@@ -157,6 +168,8 @@ type EnqueueOptions = {
 	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;
 };
 
 export class ReminderQueue {
@@ -194,13 +207,18 @@ export class ReminderQueue {
 		}
 		if (opts?.scope === "every-turn") {
 			this.everyTurn.set(opts.key ?? text, entry);
-		} else {
-			// 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);
+			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);
 	}
 
 	remove(key: string): void {
@@ -213,27 +231,30 @@ export class ReminderQueue {
 	 * placements stay queued for the next request.
 	 */
 	takeOneShots(): ReminderEntry[] {
-		const taken = this.nextTurn.filter((r) => r.placement === "last-append");
-		this.nextTurn = this.nextTurn.filter((r) => r.placement !== "last-append");
-		return taken.map(strip);
+		const { matching, rest } = partition(this.nextTurn, (r) => r.placement === "last-append");
+		this.nextTurn = rest;
+		return matching.map(strip);
 	}
 
 	/**
-	 * Fix the pending `last-append` one-shots 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.
+	 * 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): void {
-		for (const entry of this.nextTurn) {
-			if (entry.placement !== "last-append") continue;
-			this.pinned.push({ ...entry, pin: anchor });
-		}
-		this.nextTurn = this.nextTurn.filter((r) => r.placement !== "last-append");
+	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;
 	}
 
 	/**
 	 * Everything to inject on this request: every-turn state, pinned one-shots,
-	 * then whatever is still pending. `messages` is the request being built:
+	 * 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,
@@ -246,21 +267,34 @@ export class ReminderQueue {
 			const locate = pinLocator(messages);
 			this.pinned = this.pinned.filter((entry) => locate(entry.pin as PinAnchor) !== -1);
 		}
-		const pending = this.nextTurn.map(strip);
-		this.nextTurn = [];
-		return [...[...this.everyTurn.values()].map(strip), ...this.pinned.map(strip), ...pending];
+		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)];
 	}
 
 	get size(): number {
 		return this.everyTurn.size + this.nextTurn.length + this.pinned.length;
 	}
 
-	/** True when a one-shot is waiting to be delivered (the owner decides where). */
+	/** 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);
+	}
+
+	/** `hasPending("last-append")` — kept for the existing callers and tests. */
 	get hasPendingOneShots(): boolean {
-		return this.nextTurn.some((r) => r.placement === "last-append");
+		return this.hasPending("last-append");
 	}
 }
 
+/** 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 };
+}
+
 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;
@@ -303,6 +337,17 @@ export function tailAnchor(messages: AgentMessage[]): PinAnchor | undefined {
 	return undefined;
 }
 
+/**
+ * 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.
+ */
+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;
+}
+
 /** 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)];
@@ -406,6 +451,10 @@ export function injectReminders(messages: AgentMessage[], reminders: Array<strin
 	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);
@@ -449,14 +498,18 @@ export function injectReminders(messages: AgentMessage[], reminders: Array<strin
 	}
 
 	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.
+	// 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) push(after, index, [reminderBlock(entry)]);
+			if (index === -1) continue;
+			push(entry.placement === "user-prepend" ? before : after, index, [reminderBlock(entry)]);
 		}
 	}