one-code-extension 0.4.0 → 0.5.0

package/extensions/lib/request-replay.ts

@@ -0,0 +1,439 @@
+/**
+ * Replaying the session's last provider request with a few messages appended,
+ * so a side call (btw, recap, compaction) reads the prompt cache the session
+ * wrote. Claude Code sends these calls the same way: the main request's
+ * `system`, `tools` and `messages` unchanged, the final assistant reply, then
+ * the side prompt (working-docs/decisions/caching.md "Side calls replay the last
+ * request").
+ *
+ * The request cannot be rebuilt from pi's APIs: tool-search reshapes the wire
+ * `tools` array and context-management edits the body inside pi's request
+ * pipeline, which `completeSimple` bypasses, and one differing byte in `tools`
+ * or `system` misses the whole cache. So the compaction extension (the last to
+ * see `before_provider_request`) publishes the final payload on
+ * LAST_REQUEST_CHANNEL, and a side call sends it back with its tail spliced on
+ * through `completeSimple`'s `onPayload`. pi-ai converts the tail itself (the
+ * call's own context is just the tail), so its wire shape matches the rest by
+ * construction.
+ *
+ * Pure: no pi extension API; only pi-ai types and the vendored estimator.
+ */
+
+import type { Message } from "@earendil-works/pi-ai";
+import { estimateMessageTokens } from "./pi-ai-estimate.ts";
+
+/** The compaction extension publishes a RequestCapture here, or undefined when none is valid. */
+export const LAST_REQUEST_CHANNEL = "one-code:last-request";
+
+/** The provider APIs whose request body can be extended by appending to one list. */
+export type ReplayApi = "anthropic-messages" | "openai-completions" | "openai-responses";
+
+const LIST_KEY: Record<ReplayApi, string> = {
+	"anthropic-messages": "messages",
+	"openai-completions": "messages",
+	"openai-responses": "input",
+};
+
+/** The output cap's field, first match in the captured body wins. */
+const MAX_TOKEN_KEYS: Record<ReplayApi, readonly string[]> = {
+	"anthropic-messages": ["max_tokens"],
+	"openai-completions": ["max_completion_tokens", "max_tokens"],
+	"openai-responses": ["max_output_tokens"],
+};
+
+/** The session's last provider request body, and the model it went to. */
+export interface RequestCapture {
+	api: ReplayApi;
+	provider: string;
+	modelId: string;
+	payload: Record<string, unknown>;
+	/** The last message of the context the body was built from: where a fork's own messages start. */
+	covers?: CoveredThrough;
+	/** The session the body went out for: its id is the routing affinity a fork must send too. */
+	sessionId?: string;
+}
+
+/** A transcript message named by what survives a session fork: its role and timestamp. */
+export interface CoveredThrough {
+	role: string;
+	timestamp: number;
+}
+
+interface ModelRef {
+	api?: string;
+	provider?: string;
+	id?: string;
+}
+
+/** A capture of `payload` for `model`, or undefined when its API cannot be replayed. */
+export function captureRequest(model: ModelRef | undefined, payload: unknown, covers?: CoveredThrough, sessionId?: string): RequestCapture | undefined {
+	const api = model?.api;
+	if (api !== "anthropic-messages" && api !== "openai-completions" && api !== "openai-responses") return undefined;
+	if (!model?.provider || !model.id || !isRecord(payload) || !Array.isArray(payload[LIST_KEY[api]])) return undefined;
+	return { api, provider: model.provider, modelId: model.id, payload, ...(covers ? { covers } : {}), ...(sessionId ? { sessionId } : {}) };
+}
+
+/** The model fields pi-ai reads to choose its session-affinity headers. */
+export interface AffinityModel extends ModelRef {
+	baseUrl?: string;
+	compat?: { sendSessionAffinityHeaders?: boolean; sessionAffinityFormat?: string };
+}
+
+/**
+ * The session-affinity headers pi-ai sends with `sessionId` for `model`, so a
+ * fork can send its parent's: a gateway routes on them (OpenRouter spreads a
+ * model across hosts, each with its own cache), and the fork is a different
+ * session. Extension headers merge after pi-ai's, so these override. A copy
+ * of pi-ai's `createClient` rules for the three replayable APIs, unchanged
+ * from 0.87.1 to 0.99.2 (re-check at a pi bump:
+ * features/pi-adaptation/plan.md §3 step 9).
+ */
+export function affinityHeaders(model: AffinityModel | undefined, sessionId: string): Record<string, string> {
+	if (!model) return {};
+	const openRouter = model.provider === "openrouter" || (model.baseUrl ?? "").includes("openrouter.ai");
+	const send = model.compat?.sendSessionAffinityHeaders ?? openRouter;
+	if (model.api === "anthropic-messages") {
+		if (!send) return {};
+		const format = model.compat?.sessionAffinityFormat ?? (openRouter ? "openrouter" : undefined);
+		return { [format === "openrouter" ? "x-session-id" : "x-session-affinity"]: sessionId };
+	}
+	if (model.api !== "openai-completions" && model.api !== "openai-responses") return {};
+	if (model.api === "openai-completions" && !send) return {};
+	const format = model.compat?.sessionAffinityFormat ?? (openRouter ? "openrouter" : "openai");
+	if (format === "openrouter") return { "x-session-id": sessionId };
+	return {
+		...(format === "openai" ? { session_id: sessionId } : {}),
+		"x-client-request-id": sessionId,
+		...(model.api === "openai-completions" ? { "x-session-affinity": sessionId } : {}),
+	};
+}
+
+/** The last non-system message of a context, as a fork will find it again; undefined without one. */
+export function lastCovered(messages: readonly { role: string; timestamp?: number }[]): CoveredThrough | undefined {
+	for (let index = messages.length - 1; index >= 0; index--) {
+		const { role, timestamp } = messages[index];
+		if (role === "system") continue;
+		return typeof timestamp === "number" ? { role, timestamp } : undefined;
+	}
+	return undefined;
+}
+
+/** True when `model` is the one `capture` went to: a different model has a different cache. */
+export function captureMatches(capture: RequestCapture, model: ModelRef | undefined): boolean {
+	return capture.api === model?.api && capture.provider === model?.provider && capture.modelId === model?.id;
+}
+
+interface MessageLike {
+	role: string;
+	content?: unknown;
+	stopReason?: string;
+}
+
+/**
+ * The last captured request plus the assistant reply that answered it, as one
+ * consumer extension sees them. The reply is kept only when it closes the
+ * exchange cleanly: an errored or aborted reply is omitted from pi's context,
+ * and one that called tools is still waiting on their results (appending it
+ * without them is invalid on every provider), so both leave the tail empty.
+ */
+export class LastExchange<Reply extends MessageLike = MessageLike> {
+	private capture: RequestCapture | undefined;
+	private reply: Reply | undefined;
+
+	/** A new request (or undefined: none valid) replaces the old one and its reply. */
+	setCapture(capture: RequestCapture | undefined): void {
+		this.capture = capture;
+		this.reply = undefined;
+	}
+
+	/** Feed every main-session `message_end`; only assistant messages matter. */
+	noteMessage(message: Reply): void {
+		if (!this.capture || message.role !== "assistant") return;
+		const content = Array.isArray(message.content) ? (message.content as { type?: string }[]) : [];
+		const clean = message.stopReason !== "error" && message.stopReason !== "aborted" && !content.some((block) => block.type === "toolCall");
+		this.reply = clean ? message : undefined;
+	}
+
+	/** The capture and reply when the capture went to `model`; a switched model has its own cache. */
+	forModel(model: ModelRef | undefined): { capture: RequestCapture; reply: Reply | undefined } | undefined {
+		const capture = this.capture;
+		if (!capture || capture.provider !== model?.provider || capture.modelId !== model?.id) return undefined;
+		return { capture, reply: this.reply };
+	}
+}
+
+/**
+ * The captured body with `tail`'s message list (a body pi-ai built for the tail
+ * alone) appended, every other field kept byte for byte. `maxTokens` replaces
+ * the output cap when given.
+ *
+ * Anthropic cache breakpoints: the tail's own markers are dropped, and when the
+ * tail starts with the assistant reply, the markers on the captured request's
+ * last message move to the reply's last text block (Claude Code's placement).
+ * The marker count never grows (the API allows four), the prefix the session
+ * cached is read through the lookback, and the reply gets written for the
+ * user's next turn. A tail that starts with a user message is merged into a
+ * trailing user message, so the roles still alternate.
+ */
+export function extendPayload(capture: RequestCapture, tail: Record<string, unknown>, maxTokens?: number): Record<string, unknown> {
+	const key = LIST_KEY[capture.api];
+	const base = capture.payload[key] as unknown[];
+	const extra = withoutCacheControl(Array.isArray(tail[key]) ? (tail[key] as unknown[]) : []) as unknown[];
+	const list = capture.api === "anthropic-messages" ? appendAnthropic(base, extra) : [...base, ...extra];
+	const out: Record<string, unknown> = { ...capture.payload, [key]: list };
+	if (maxTokens !== undefined) {
+		const keys = MAX_TOKEN_KEYS[capture.api];
+		out[keys.find((k) => k in capture.payload) ?? keys[0]] = maxTokens;
+	}
+	return out;
+}
+
+/** The output cap the captured body carries, if any. */
+function capturedMaxTokens(capture: RequestCapture): number | undefined {
+	for (const key of MAX_TOKEN_KEYS[capture.api]) {
+		const value = capture.payload[key];
+		if (typeof value === "number") return value;
+	}
+	return undefined;
+}
+
+/** A replay that would leave less output room than this is not sent as a replay. */
+export const MIN_REPLAY_OUTPUT_TOKENS = 1024;
+/** The output cap when neither the captured body nor the caller names one. */
+const DEFAULT_REPLAY_OUTPUT_TOKENS = 8192;
+
+/**
+ * The messages a side call appends: the reply that closed the exchange, if
+ * any, then `before` (a side session's earlier exchanges), then its prompt.
+ */
+export function replayTail(reply: Message | undefined, prompt: string, timestamp = Date.now(), before: readonly Message[] = []): Message[] {
+	const question: Message = { role: "user", content: [{ type: "text", text: prompt }], timestamp };
+	return [...(reply ? [reply] : []), ...before, question];
+}
+
+/**
+ * The output cap for a replay, or undefined when too little room is left. The
+ * captured cap was clamped to what that request left of the window, and the
+ * tail spends some of it; `limit` caps it further.
+ */
+export function replayOutputCap(capture: RequestCapture, tail: readonly Message[], limit?: number): number | undefined {
+	const captured = capturedMaxTokens(capture);
+	const room = captured === undefined ? (limit ?? DEFAULT_REPLAY_OUTPUT_TOKENS) : captured - tail.reduce((sum, message) => sum + estimateMessageTokens(message), 0);
+	const cap = limit === undefined ? room : Math.min(limit, room);
+	return cap >= MIN_REPLAY_OUTPUT_TOKENS ? cap : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Forks: every request of a child session that inherits the transcript
+// ---------------------------------------------------------------------------
+
+/**
+ * A fork's context with the messages its parent's captured request already
+ * carries removed: everything up to and including `covers`, system messages
+ * kept (pi requires the leading one). What is left is the fork's own tail: the
+ * reply that answered the capture, the fork's task, and its own turns. A
+ * session fork copies the entries with their timestamps, so the boundary is
+ * found by role and timestamp; undefined when it is not there (the fork
+ * compacted, or the capture belongs to another branch).
+ */
+export function uncoveredMessages<M extends { role: string; timestamp?: number }>(messages: readonly M[], covers: CoveredThrough): M[] | undefined {
+	const boundary = messages.findLastIndex((message) => message.role === covers.role && message.timestamp === covers.timestamp);
+	if (boundary === -1) return undefined;
+	return [...messages.slice(0, boundary + 1).filter((message) => message.role === "system"), ...messages.slice(boundary + 1)];
+}
+
+/** Anthropic's limit on `cache_control` breakpoints in one request. */
+export const MAX_CACHE_MARKERS = 4;
+
+/**
+ * A fork's request: the parent's captured body byte for byte (system prompt,
+ * tools, messages, `prompt_cache_key`, every other field), then the fork's own
+ * tail from `child` (pi's body for the fork's uncovered messages), so the fork
+ * reads the prefix the parent cached (decisions/caching.md, "A call that
+ * inherits the session's context reads the session's cache").
+ *
+ * - Tools stay the parent's. A tool the fork gained after its first request
+ *   (not in `baseline`, the first request's names), or one a tail
+ *   `tool_reference` names, is appended so it stays callable; that breaks the
+ *   cache from there on, as the same load does in the parent.
+ * - The output cap is the smaller of the fork's and the parent's cap less the
+ *   tail, since pi clamped the fork's to a context without the prefix.
+ * - Cache markers: the parent's stay where the parent wrote its entry, the
+ *   tail's mark the fork's own entry, and the earliest are dropped past four.
+ */
+export function forkRequestPayload(capture: RequestCapture, child: Record<string, unknown>, baseline: ReadonlySet<string>): Record<string, unknown> {
+	const key = LIST_KEY[capture.api];
+	const base = capture.payload[key] as unknown[];
+	const tail = (Array.isArray(child[key]) ? (child[key] as WireMessage[]) : []).filter((entry) => entry.role !== "system" && entry.role !== "developer");
+	const out: Record<string, unknown> = { ...capture.payload, [key]: capture.api === "anthropic-messages" ? joinUserTurns(base, tail) : [...base, ...tail] };
+	const tools = forkTools(capture.payload.tools, child.tools, baseline, tail);
+	if (tools) out.tools = tools;
+	const capKey = MAX_TOKEN_KEYS[capture.api].find((k) => typeof capture.payload[k] === "number");
+	// Appended tool schemas spend room too; the parent's own tools are already in its cap.
+	const appended = Array.isArray(tools) && Array.isArray(capture.payload.tools) ? tools.slice(capture.payload.tools.length) : [];
+	const tailRoom = forkOutputRoom(capture, tail);
+	const room = tailRoom === undefined ? undefined : tailRoom - (appended.length > 0 ? Math.ceil(JSON.stringify(appended).length / 4) : 0);
+	if (capKey && room !== undefined) {
+		// Never above the room: the fork chose the fallback before this when too little was left.
+		const own = typeof child[capKey] === "number" ? (child[capKey] as number) : room;
+		out[capKey] = Math.max(1, Math.min(own, room));
+	}
+	capCacheMarkers(out, key, capture, tail);
+	return out;
+}
+
+/**
+ * The output room a fork request leaves: the captured cap (pi clamped it to
+ * what the parent's context left of the window) less a rough size of `tail`.
+ * Undefined when the capture names no cap. A fork whose room is below
+ * `MIN_REPLAY_OUTPUT_TOKENS` must not be spliced: it goes out whole instead.
+ */
+export function forkOutputRoom(capture: RequestCapture, tail: unknown): number | undefined {
+	const capKey = MAX_TOKEN_KEYS[capture.api].find((k) => typeof capture.payload[k] === "number");
+	return capKey === undefined ? undefined : (capture.payload[capKey] as number) - Math.ceil(JSON.stringify(tail).length / 4);
+}
+
+/** The names a body's tool list declares (Anthropic, Chat Completions and Responses shapes). */
+export function toolNames(tools: unknown): string[] {
+	return Array.isArray(tools) ? tools.map(toolName).filter((name): name is string => name !== undefined) : [];
+}
+
+function toolName(tool: unknown): string | undefined {
+	if (!isRecord(tool)) return undefined;
+	if (typeof tool.name === "string") return tool.name;
+	return isRecord(tool.function) && typeof tool.function.name === "string" ? tool.function.name : undefined;
+}
+
+function forkTools(parent: unknown, child: unknown, baseline: ReadonlySet<string>, tail: unknown[]): unknown[] | undefined {
+	if (!Array.isArray(parent)) return Array.isArray(child) ? (withoutCacheControl(child) as unknown[]) : undefined;
+	const declared = new Set(toolNames(parent));
+	const referenced = referencedTools(tail);
+	const extra = (Array.isArray(child) ? child : []).filter((tool) => {
+		const name = toolName(tool);
+		return name !== undefined && !declared.has(name) && (!baseline.has(name) || referenced.has(name));
+	});
+	return extra.length > 0 ? [...parent, ...(withoutCacheControl(extra) as unknown[])] : parent;
+}
+
+/** Tool names the tail's `tool_reference` blocks load (Anthropic tool search). */
+function referencedTools(value: unknown, found = new Set<string>()): Set<string> {
+	if (Array.isArray(value)) for (const entry of value) referencedTools(entry, found);
+	else if (isRecord(value)) {
+		if (value.type === "tool_reference" && typeof value.tool_name === "string") found.add(value.tool_name);
+		for (const entry of Object.values(value)) referencedTools(entry, found);
+	}
+	return found;
+}
+
+/** Anthropic needs alternating roles: a tail that opens with a user turn joins the captured last one. */
+function joinUserTurns(base: unknown[], tail: unknown[]): unknown[] {
+	const last = base.at(-1) as WireMessage | undefined;
+	const first = tail[0] as WireMessage | undefined;
+	if (last?.role === "user" && first?.role === "user") {
+		return [...base.slice(0, -1), { ...last, content: [...blocksOf(last.content), ...blocksOf(first.content)] }, ...tail.slice(1)];
+	}
+	return [...base, ...tail];
+}
+
+/**
+ * Drop the earliest `cache_control` markers (tools, then system, then
+ * messages) past the limit. Copy-on-write: the captured body is shared by
+ * every fork, so only the path to a dropped marker is copied.
+ */
+function capCacheMarkers(payload: Record<string, unknown>, listKey: string, base: RequestCapture, tail: unknown[]): void {
+	const keys = ["tools", "system", listKey].filter((key) => key in payload);
+	// Appended tools carry no markers, so the body holds the capture's and the tail's.
+	const total = captureMarkers(base) + countMarkers(tail);
+	const budget = { drop: total - MAX_CACHE_MARKERS };
+	for (const key of keys) {
+		if (budget.drop <= 0) break;
+		payload[key] = dropFirstMarkers(payload[key], budget);
+	}
+}
+
+/** The captured body's marker count, walked once per capture: the list can hold a 1M-token transcript. */
+const capturedMarkerCounts = new WeakMap<RequestCapture, number>();
+function captureMarkers(capture: RequestCapture): number {
+	let count = capturedMarkerCounts.get(capture);
+	if (count === undefined) {
+		const payload = capture.payload;
+		count = countMarkers(payload.tools) + countMarkers(payload.system) + countMarkers(payload[LIST_KEY[capture.api]]);
+		capturedMarkerCounts.set(capture, count);
+	}
+	return count;
+}
+
+function countMarkers(value: unknown): number {
+	if (Array.isArray(value)) return value.reduce((sum: number, entry) => sum + countMarkers(entry), 0);
+	if (!isRecord(value)) return 0;
+	let count = "cache_control" in value ? 1 : 0;
+	for (const [key, entry] of Object.entries(value)) if (key !== "cache_control") count += countMarkers(entry);
+	return count;
+}
+
+function dropFirstMarkers(value: unknown, budget: { drop: number }): unknown {
+	if (budget.drop <= 0) return value;
+	if (Array.isArray(value)) {
+		let changed = false;
+		const out = value.map((entry) => {
+			const next = dropFirstMarkers(entry, budget);
+			if (next !== entry) changed = true;
+			return next;
+		});
+		return changed ? out : value;
+	}
+	if (!isRecord(value)) return value;
+	let out: Record<string, unknown> | undefined;
+	if ("cache_control" in value) {
+		const { cache_control: _, ...rest } = value;
+		out = rest;
+		budget.drop--;
+	}
+	for (const [key, entry] of Object.entries(out ?? value)) {
+		if (budget.drop <= 0) break;
+		const next = dropFirstMarkers(entry, budget);
+		if (next !== entry) out = { ...(out ?? value), [key]: next };
+	}
+	return out ?? value;
+}
+
+type Block = Record<string, unknown>;
+type WireMessage = { role?: string; content?: unknown } & Record<string, unknown>;
+
+function appendAnthropic(base: unknown[], extra: unknown[]): unknown[] {
+	if (extra.length === 0) return base;
+	const last = base.at(-1) as WireMessage | undefined;
+	const first = extra[0] as WireMessage;
+	if (last && first.role === "assistant") {
+		const markers = blocksOf(last.content).map((block) => block.cache_control).filter((marker) => marker !== undefined);
+		const replyBlocks = blocksOf(first.content);
+		const anchor = replyBlocks.findLastIndex((block) => block.type === "text");
+		if (markers.length === 0 || anchor === -1) return [...base, ...extra];
+		const lastUnmarked = { ...last, content: blocksOf(last.content).map(({ cache_control: _, ...rest }) => rest) };
+		const content = replyBlocks.map((block, index) => (index === anchor ? { ...block, cache_control: markers.at(-1) } : block));
+		return [...base.slice(0, -1), lastUnmarked, { ...first, content }, ...extra.slice(1)];
+	}
+	if (last && last.role === "user" && first.role === "user") {
+		return [...base.slice(0, -1), { ...last, content: [...blocksOf(last.content), ...blocksOf(first.content)] }, ...extra.slice(1)];
+	}
+	return [...base, ...extra];
+}
+
+function blocksOf(content: unknown): Block[] {
+	if (typeof content === "string") return [{ type: "text", text: content }];
+	return Array.isArray(content) ? (content as Block[]) : [];
+}
+
+function withoutCacheControl(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(withoutCacheControl);
+	if (!isRecord(value)) return value;
+	const out: Record<string, unknown> = {};
+	for (const [key, entry] of Object.entries(value)) {
+		if (key !== "cache_control") out[key] = withoutCacheControl(entry);
+	}
+	return out;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/extensions/lib/scratchpad.ts

@@ -14,8 +14,9 @@
  * module state — so each re-derives it through `sessionScratchpadDir`.
  */
 
+import { chmodSync, lstatSync, mkdirSync } from "node:fs";
 import os from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { findGitRoot } from "./git.ts";
 import { projectSlug } from "./memory.ts";
 import { tryRealpath } from "./paths.ts";
@@ -52,21 +53,87 @@ export function sessionScratchpadDir(cwd: string, sessionId: string): string {
 	return scratchpadDir(resolveTmpRoot(), uid, findGitRoot(cwd) ?? cwd, sessionId);
 }
 
-/** Claude Code's Scratchpad Directory prompt section, verbatim (see payload.json). */
-export function scratchpadPromptSection(dir: string): string {
-	return `# Scratchpad Directory
+/** The owner-level directory of a scratchpad path (`<tmp>/onecode-<uid>`). */
+function ownerDirOf(scratchpad: string): string {
+	return dirname(dirname(dirname(scratchpad)));
+}
+
+/** What `ownerDirProblem` needs from an `lstat`. */
+export interface OwnerDirStat {
+	isSymbolicLink: boolean;
+	isDirectory: boolean;
+	uid: number;
+	mode: number;
+}
+
+/**
+ * Why the owner directory cannot hold this user's scratchpads, or undefined.
+ * On a shared `/tmp` the name is predictable from the uid, so another user
+ * can create it first: a symlink, a directory they own, or one anyone may
+ * write lets them read, rename or replace every session's files under it
+ * (the sticky bit on `/tmp` does not protect entries of their directory).
+ * Pure.
+ */
+export function ownerDirProblem(stat: OwnerDirStat, uid: number): string | undefined {
+	if (stat.isSymbolicLink) return "it is a symlink";
+	if (!stat.isDirectory) return "it is not a directory";
+	if (stat.uid !== uid) return `it is owned by uid ${stat.uid}`;
+	if (stat.mode & 0o022) return "others may write to it";
+	return undefined;
+}
 
-IMPORTANT: Always use this scratchpad directory for temporary files instead of \`/tmp\` or other system temp directories:
-\`${dir}\`
+/**
+ * Create the scratchpad private to this user, or return false. The owner
+ * directory is created 0700 and must then be a real directory this user owns
+ * that nobody else may write (`ownerDirProblem`); one created before this
+ * check with a looser mode is tightened to 0700, so other users can neither
+ * list the project paths in it nor read what the model writes. Every level
+ * below is created 0700 too. Windows has no shared temp root (`%TEMP%` is per
+ * user), so there it only creates the directory.
+ */
+export function ensurePrivateScratchpad(dir: string, uid: number | undefined = typeof process.getuid === "function" ? process.getuid() : undefined): boolean {
+	try {
+		if (uid !== undefined) {
+			const owner = ownerDirOf(dir);
+			mkdirSync(owner, { recursive: true, mode: 0o700 });
+			const stat = lstatSync(owner);
+			if (ownerDirProblem({ isSymbolicLink: stat.isSymbolicLink(), isDirectory: stat.isDirectory(), uid: stat.uid, mode: stat.mode }, uid)) return false;
+			if (stat.mode & 0o077) chmodSync(owner, 0o700);
+		}
+		mkdirSync(dir, { recursive: true, mode: 0o700 });
+		return true;
+	} catch {
+		return false;
+	}
+}
 
-Use this directory for ALL temporary file needs:
-- Storing intermediate results or data during multi-step tasks
-- Writing temporary scripts or configuration files
-- Saving outputs that don't belong in the user's project
-- Creating working files during analysis or processing
-- Any file that would otherwise go to \`/tmp\`
+/**
+ * Whether an existing scratchpad sits under a private owner directory, with
+ * no side effects: for a gate that trusts a scratchpad another extension
+ * created.
+ */
+export function isPrivateScratchpad(dir: string, uid: number | undefined = typeof process.getuid === "function" ? process.getuid() : undefined): boolean {
+	if (uid === undefined) return true;
+	try {
+		const stat = lstatSync(ownerDirOf(dir));
+		return ownerDirProblem({ isSymbolicLink: stat.isSymbolicLink(), isDirectory: stat.isDirectory(), uid: stat.uid, mode: stat.mode }, uid) === undefined && (stat.mode & 0o077) === 0;
+	} catch {
+		return false;
+	}
+}
 
-Only use \`/tmp\` if the user explicitly requests it.
+/** The session's scratchpad, created private to this user, or undefined when it cannot be. */
+export function privateSessionScratchpadDir(cwd: string, sessionId: string): string | undefined {
+	const dir = sessionScratchpadDir(cwd, sessionId);
+	return ensurePrivateScratchpad(dir) ? dir : undefined;
+}
 
-The scratchpad directory is session-specific, isolated from the user's project, and can generally be used without permission prompts.`;
+/**
+ * A session's own private temp directory, the scratchpad's parent
+ * (`<tmp>/onecode-<uid>/<project-slug>/<session-id>`), created private to
+ * this user, or undefined when it cannot be.
+ */
+export function privateSessionTempDir(cwd: string, sessionId: string): string | undefined {
+	const scratchpad = sessionScratchpadDir(cwd, sessionId);
+	return ensurePrivateScratchpad(scratchpad) ? dirname(scratchpad) : undefined;
 }

package/extensions/lib/send-now-channel.ts

@@ -0,0 +1,7 @@
+/**
+ * Emitted by the send-now extension just before it aborts a turn to deliver
+ * the queued messages, so the interrupted extension skips its "Interrupted ·
+ * What should One Code do instead?" note for that abort: the user has already
+ * said what to do instead.
+ */
+export const SEND_NOW_CHANNEL = "one-code:send-now";

package/extensions/lib/session-model-tier.ts

@@ -0,0 +1,51 @@
+/**
+ * One request-surface tier per session/model boundary. The first consumer owns
+ * the lifecycle handlers; every consumer reads that owner's value over the
+ * event bus. No module state is shared (each extension has its own jiti copy),
+ * and an extension loaded in isolation still installs its own owner.
+ *
+ * Only session_start and model_select classify. A catalog refresh can affect
+ * automatic model selection immediately, but prompt text, tool descriptions,
+ * and tier-dependent steering keep the same tier until the next boundary.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type PromptTier, resolveModelTier } from "./model-tier.ts";
+import { invalidateCatalogCache } from "./model-catalog-data.ts";
+
+const SESSION_TIER_REQUEST_CHANNEL = "one-code:session-tier-request";
+
+interface TierRequest {
+	owned?: boolean;
+	tier?: PromptTier;
+}
+
+/** Install the owner once on this bus, and return a reader of its frozen tier. */
+export function sessionModelTier(pi: Pick<ExtensionAPI, "events" | "on">): () => PromptTier {
+	const request = (): TierRequest => {
+		const query: TierRequest = {};
+		pi.events.emit(SESSION_TIER_REQUEST_CHANNEL, query);
+		return query;
+	};
+	if (!request().owned) {
+		let tier: PromptTier | undefined;
+		pi.events.on(SESSION_TIER_REQUEST_CHANNEL, (data) => {
+			Object.assign(data as TierRequest, { owned: true, tier });
+		});
+		const resolve = (model: Parameters<typeof resolveModelTier>[0]) => {
+			// Doctor's jiti copy cannot clear our memo. Do not freeze a stale
+			// catalog if the boundary lands inside the disk cache's stat throttle.
+			invalidateCatalogCache();
+			tier = resolveModelTier(model);
+		};
+		// Registered before the first consumer's hooks. Later consumers preserve
+		// their own lifecycle ordering (for example, restored bash mode variants).
+		pi.on("session_start", (_event, ctx) => resolve(ctx.model));
+		pi.on("model_select", (event) => resolve(event.model));
+	}
+	return () => {
+		const tier = request().tier;
+		if (tier === undefined) throw new Error("Request tier is unavailable: emit session_start before building the request surface.");
+		return tier;
+	};
+}

package/extensions/lib/session-work.ts

@@ -0,0 +1,64 @@
+/**
+ * What will wake the session later, for Claude Code's Stop hook payload: its
+ * `session_crons` (cron_create jobs, /loop, schedule_wakeup) and
+ * `background_tasks` (in-flight background work) fields, findings §21.
+ *
+ * The hooks extension emits a `SessionWorkQuery` on SESSION_WORK_CHANNEL and
+ * reads it back once the synchronous emit returns; the background extension,
+ * which owns both lists, fills it (jiti isolation: no shared module state).
+ *
+ * Pure: no pi imports.
+ */
+
+export const SESSION_WORK_CHANNEL = "one-code:session-work";
+
+/** Claude Code's `session_crons` item. */
+export interface SessionCron {
+	id: string;
+	/** The cron expression. */
+	schedule: string;
+	/** False for one-shots, a wakeup's single fire time included. */
+	recurring: boolean;
+	prompt: string;
+}
+
+/** Claude Code's `background_tasks` item. */
+export interface SessionBackgroundTask {
+	id: string;
+	/** Friendly type label: shell, subagent, monitor, workflow; else the raw kind. */
+	type: string;
+	status: string;
+	description: string;
+	/** Only for shell tasks. */
+	command?: string;
+}
+
+export interface SessionWorkQuery {
+	crons: SessionCron[];
+	tasks: SessionBackgroundTask[];
+}
+
+/** The hook payload's field cap (Claude Code: 1000 characters, then an in-string marker). */
+const FIELD_CAP = 1000;
+
+/** Claude Code's clip for these fields: the first 1000 characters, then `… [+N chars]`. */
+export function capField(text: string): string {
+	return text.length <= FIELD_CAP ? text : `${text.slice(0, FIELD_CAP)}… [+${text.length - FIELD_CAP} chars]`;
+}
+
+const TYPE_LABELS: Record<string, string> = { bash: "shell", shell: "shell", agent: "subagent", subagent: "subagent", monitor: "monitor", workflow: "workflow" };
+
+export function sessionCron(job: { id: string; cron: string; recurring: boolean; prompt: string }): SessionCron {
+	return { id: job.id, schedule: job.cron, recurring: job.recurring, prompt: capField(job.prompt) };
+}
+
+export function sessionBackgroundTask(task: { id: string; kind: string; status: string; description: string; command?: string }): SessionBackgroundTask {
+	const type = TYPE_LABELS[task.kind] ?? task.kind;
+	return {
+		id: task.id,
+		type,
+		status: task.status,
+		description: capField(task.description),
+		...(type === "shell" && task.command !== undefined && { command: capField(task.command) }),
+	};
+}