one-code-extension 0.3.1 → 0.4.1

package/extensions/btw/panel.ts

@@ -0,0 +1,179 @@
+/**
+ * Pure state, key decoding, and rendering for the `/btw` answer overlay — Claude
+ * Code's side-question panel: a focused, scrollable view of the answer with the
+ * question dim above it. `↑/↓` (and PgUp/PgDn) scroll, `c` copies the answer,
+ * `Esc` closes.
+ *
+ * Kept free of pi imports so the scroll maths and layout are unit-tested; the
+ * extension owns the overlay, repaint, and the actual clipboard write. CC's
+ * panel also offers `f to fork`; One Code omits it (pi exposes no primitive to
+ * branch a session with an injected exchange) — docs/decisions/btw.md.
+ */
+
+import { panelTopRule, safeThemePaint, truncateLine, wrapPlainText } from "../lib/tui-render.ts";
+
+export const BTW_MAX_HEIGHT = 24;
+
+/** Key hint shown at the foot of the panel. Every key here is discoverable. */
+export const BTW_HINT = "↑/↓ to scroll · c to copy · Esc to close";
+
+/** Most echoed question lines shown in the header, so it can't starve the body. */
+export const MAX_QUESTION_LINES = 4;
+
+/**
+ * The panel's body state. The pure module owns the text for each phase so every
+ * appearance (loading, error, answer) is rendered — and tested — here rather
+ * than assembled by the extension wiring.
+ */
+export type BtwBody = { kind: "loading" } | { kind: "error"; message: string } | { kind: "answer"; text: string };
+
+/** The text shown in the body for a given phase. */
+function bodyText(body: BtwBody): string {
+	switch (body.kind) {
+		case "loading":
+			return "Thinking…";
+		case "error":
+			return `Side question failed: ${body.message}`;
+		case "answer":
+			return body.text || "(no answer)";
+	}
+}
+
+export interface BtwPanelState {
+	/** First body line shown (0 = top). */
+	offset: number;
+	/** Largest valid offset for the current viewport; render keeps it current. */
+	maxOffset: number;
+	/** Visible body lines in the current viewport; render keeps it current. */
+	viewport: number;
+	/** Set for one frame after a copy so the footer can confirm it. */
+	copied: boolean;
+}
+
+export function initialBtwState(): BtwPanelState {
+	return { offset: 0, maxOffset: 0, viewport: 1, copied: false };
+}
+
+export type BtwKey = { kind: "up" | "down" | "pageUp" | "pageDown" | "top" | "bottom" | "copy" | "close" };
+
+export function decodeBtwKey(data: string): BtwKey | undefined {
+	switch (data) {
+		case "\x1b[A":
+		case "\x1bOA":
+		case "\x10": // ctrl+p
+			return { kind: "up" };
+		case "\x1b[B":
+		case "\x1bOB":
+		case "\x0e": // ctrl+n
+			return { kind: "down" };
+		case "\x1b[5~":
+			return { kind: "pageUp" };
+		case "\x1b[6~":
+			return { kind: "pageDown" };
+		case "\x1b[H":
+		case "\x1bOH":
+			return { kind: "top" };
+		case "\x1b[F":
+		case "\x1bOF":
+			return { kind: "bottom" };
+		case "c":
+		case "C":
+			return { kind: "copy" };
+		case "\x1b":
+		case "\x03": // ctrl+c
+		case "q":
+			return { kind: "close" };
+		default:
+			return undefined;
+	}
+}
+
+export type BtwEffect = { kind: "copy" } | { kind: "close" };
+
+/** Page size for PgUp/PgDn: nearly a full viewport, one line of overlap for orientation. */
+function pageStep(viewport: number): number {
+	return Math.max(1, viewport - 1);
+}
+
+/**
+ * Apply a key to the scroll state. Returns an effect for the extension to run
+ * (copy, close) or undefined for a scroll (repaint only). Offsets are clamped to
+ * `state.maxOffset`, and pages by `state.viewport` — both set by the most recent
+ * render from the real viewport.
+ */
+export function applyBtwKey(state: BtwPanelState, key: BtwKey): BtwEffect | undefined {
+	state.copied = false;
+	const step = pageStep(state.viewport);
+	switch (key.kind) {
+		case "up":
+			state.offset = Math.max(0, state.offset - 1);
+			return undefined;
+		case "down":
+			state.offset = Math.min(state.maxOffset, state.offset + 1);
+			return undefined;
+		case "pageUp":
+			state.offset = Math.max(0, state.offset - step);
+			return undefined;
+		case "pageDown":
+			state.offset = Math.min(state.maxOffset, state.offset + step);
+			return undefined;
+		case "top":
+			state.offset = 0;
+			return undefined;
+		case "bottom":
+			state.offset = state.maxOffset;
+			return undefined;
+		case "copy":
+			return { kind: "copy" };
+		case "close":
+			return { kind: "close" };
+	}
+}
+
+/**
+ * Render the panel to at most `height` lines. The header (the dim question) and
+ * footer (rule + key hint, with a scroll indicator and a copy confirmation) are
+ * fixed; the answer scrolls within what remains. Clamps and writes back
+ * `state.offset`/`state.maxOffset` so key handling scrolls against the real
+ * body length. Every line is width-truncated (pi-tui crashes on an overwide
+ * line).
+ */
+export function renderBtwPanel(
+	input: { state: BtwPanelState; question: string; body: BtwBody; width: number; height: number },
+	theme?: unknown,
+): string[] {
+	const { state, question, body, width, height } = input;
+	const paint = safeThemePaint(theme);
+	const inner = Math.max(1, width);
+
+	// Cap the echoed question so a long one (a pasted paragraph or URL) cannot
+	// grow the header past the panel height and starve the answer of rows; a
+	// truncated last line gets an ellipsis. The answer is what scrolls, not the
+	// question.
+	const questionLines = wrapPlainText(question.trim(), inner);
+	const shownQuestion =
+		questionLines.length > MAX_QUESTION_LINES
+			? [...questionLines.slice(0, MAX_QUESTION_LINES - 1), truncateLine(`${questionLines[MAX_QUESTION_LINES - 1]}…`, inner)]
+			: questionLines;
+	const header = [
+		paint("accent", truncateLine("Side question", inner)),
+		...shownQuestion.map((line) => paint("muted", truncateLine(line, inner))),
+		panelTopRule(paint, inner),
+	];
+
+	const bodyAll = wrapPlainText(bodyText(body), inner);
+	const capacity = Math.max(1, height - header.length - 2); // 2 = footer rule + hint
+	state.viewport = capacity;
+	state.maxOffset = Math.max(0, bodyAll.length - capacity);
+	state.offset = Math.min(Math.max(0, state.offset), state.maxOffset);
+
+	const visible = bodyAll.slice(state.offset, state.offset + capacity).map((line) => truncateLine(line, inner));
+	// Pad a short answer so the footer sits at the panel's foot, not mid-screen.
+	while (visible.length < capacity) visible.push("");
+
+	const scrollNote = state.maxOffset > 0 ? `  (${state.offset + 1}-${Math.min(state.offset + capacity, bodyAll.length)} of ${bodyAll.length})` : "";
+	const hint = state.copied ? "Copied to clipboard" : `${BTW_HINT}${scrollNote}`;
+	const footer = [panelTopRule(paint, inner), paint("muted", truncateLine(hint, inner))];
+
+	return [...header, ...visible, ...footer];
+}

package/extensions/btw/prompt.ts

@@ -0,0 +1,45 @@
+/**
+ * Pure pieces of Claude Code's `/btw` ("by the way") side-question feature: a
+ * lightweight, one-off question answered against the current conversation's
+ * context while the main agent keeps working. Prompt text is verbatim from CC's
+ * capture (captures/btw.json, CC 2.1.278): a `<system-reminder>` that frames the
+ * answering model as a separate, tool-less instance, prepended to the user's
+ * question as the final user message.
+ *
+ * Kept free of pi imports so the message assembly and text extraction are
+ * unit-tested; the extension owns the model call, the spinner, and the panel.
+ */
+
+/**
+ * CC's verbatim side-question reminder (captures/btw.json message 20). It frames
+ * the answering instance as a separate, lightweight, tool-less agent so the
+ * model answers in one shot from context instead of trying to act. One Code
+ * backs this framing for real: it sends name-only tool stubs (never live tools)
+ * and does not persist the exchange, so there genuinely is no follow-up turn.
+ */
+export const SIDE_QUESTION_REMINDER = `<system-reminder>This is a side question from the user. You must answer this question directly in a single response.
+
+IMPORTANT CONTEXT:
+- You are a separate, lightweight agent spawned to answer this one question
+- The main agent is NOT interrupted - it continues working independently in the background
+- You share the conversation context but are a completely separate instance
+- Do NOT reference being interrupted or what you were "previously doing" - that framing is incorrect
+
+CRITICAL CONSTRAINTS:
+- You have NO tools available - you cannot read files, run commands, search, or take any actions
+- Do NOT write tool calls or tool output as text (for example invoke or function_calls XML blocks) - nothing you write here is executed; if answering would need reading files, running commands, or searching, say that can't be checked from a side question and suggest asking in the main conversation
+- This is a one-off response - there will be no follow-up turns
+- You can ONLY provide information based on what you already know from the conversation context
+- NEVER say things like "Let me try...", "I'll now...", "Let me check...", or promise to take any action
+- If you don't know the answer, say so - do not offer to look it up or investigate
+
+Simply answer the question with the information you have.</system-reminder>`;
+
+/**
+ * The final user message a `/btw` call sends: CC's reminder, a blank line, then
+ * the user's question verbatim (captures/btw.json message 20 is exactly this
+ * string). The question is trimmed of surrounding whitespace only.
+ */
+export function sideQuestionMessage(question: string): string {
+	return `${SIDE_QUESTION_REMINDER}\n\n${question.trim()}`;
+}

package/extensions/clear/index.ts

@@ -13,9 +13,20 @@
  * a clean context — which is what a `/clear` habit wants. Like `/exit`→`/quit`,
  * we cannot fold this into pi's `/new` palette entry (pi has no command
  * aliases), so `/clear` and `/new` are two entries that both reset.
+ *
+ * Claude Code tells the model the conversation was cleared: the new
+ * conversation opens with the `/clear` breadcrumb (caveat, command, empty
+ * stdout — lib/local-command.ts). It cannot be queued from the handler: pi's
+ * `newSession()` replaces the whole runtime (a `session_shutdown` with reason
+ * "new" on the old extension runner, every factory run again — findings §8),
+ * so a reminder queued before the call dies with the old queue. The NEW
+ * instance announces it instead, from its `session_start` with reason "new" —
+ * which is also what pi's own `/new` and an RPC `new_session` produce, and
+ * they are the same user action as far as the model is concerned.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { announceLocalCommand } from "../lib/local-command.ts";
 
 export default function clearExtension(pi: ExtensionAPI) {
 	pi.registerCommand("clear", {
@@ -24,4 +35,8 @@ export default function clearExtension(pi: ExtensionAPI) {
 			await ctx.newSession();
 		},
 	});
+
+	pi.on("session_start", (event) => {
+		if ((event as { reason?: string }).reason === "new") announceLocalCommand(pi, { name: "clear" });
+	});
 }

package/extensions/compaction/fit.ts

@@ -27,16 +27,19 @@
  *
  * Both decisions ask pi-ai's `clampMaxTokensToContext` — the very function
  * `completeSimple` applies to the request — rather than re-deriving its
- * arithmetic, so they can never disagree with the clamp they predict. One
- * trap in that estimator: it anchors on the last assistant message's
- * `usage` total when there is one (`withoutUsage`).
+ * arithmetic, so they can never disagree with the clamp they predict. They
+ * `normalizeContext` the request first, exactly as `completeSimple` does, so the
+ * prompt and tools are counted (pi 0.86.1 carries them in a leading system
+ * message, not separate `Context` fields). One trap in that estimator: it
+ * anchors on the last assistant message's `usage` total when there is one
+ * (`withoutUsage`).
  */
 
 import { type Api, type Context, contentText, type Message, type Model } from "@earendil-works/pi-ai";
 import { PREVIEW_BYTES } from "../lib/persisted-output.ts";
 // Vendored from pi-ai: importing its deep subpaths directly breaks under the
 // bundled app's library loader (distribution review 2026-09-09, H1).
-import { clampMaxTokensToContext, estimateMessageTokens } from "../lib/pi-ai-estimate.ts";
+import { clampMaxTokensToContext, estimateMessageTokens, normalizeContext } from "../lib/pi-ai-estimate.ts";
 
 /**
  * The least output room a replay must leave for the summary. Below it the
@@ -60,7 +63,7 @@ export const CLEARED_RESULT_HEAD_CHARS = PREVIEW_BYTES;
  */
 export function replayFits(reason: "manual" | "threshold" | "overflow", model: Model<Api>, request: Context, maxTokens: number): boolean {
 	if (reason === "overflow") return false;
-	return clampMaxTokensToContext(model, request, maxTokens) >= MIN_REPLAY_SUMMARY_TOKENS;
+	return clampMaxTokensToContext(model, normalizeContext(request), maxTokens) >= MIN_REPLAY_SUMMARY_TOKENS;
 }
 
 /**
@@ -80,7 +83,7 @@ export function fitToBudget(model: Model<Api>, request: Context, maxTokens: numb
 
 	let cleared = 0;
 	for (const { index } of candidates) {
-		if (clampMaxTokensToContext(model, fitted, maxTokens) >= STANDALONE_SUMMARY_TOKENS) break;
+		if (clampMaxTokensToContext(model, normalizeContext(fitted), maxTokens) >= STANDALONE_SUMMARY_TOKENS) break;
 		messages[index] = clearToolResult(messages[index]);
 		cleared++;
 	}

package/extensions/doctor/build.ts

@@ -17,7 +17,10 @@ import { readJsonFile } from "../lib/atomic-write.ts";
 import { oneCodeSettingsPath } from "../lib/one-code-settings.ts";
 import { webSearchSettingsFrom } from "../web/backends.ts";
 import { collectCompat, importedConfigSection, mcpSection } from "./compat.ts";
-import { checkDependencies, dependenciesSection } from "./dependencies.ts";
+import { checkDependencies, dependenciesSection, type ShellsInput } from "./dependencies.ts";
+import { readSettingsEnv } from "../lib/claude-settings.ts";
+import { resolveBashSpawn, resolvePowerShellSpawn } from "../lib/shell-spawn.ts";
+import { shellToolPolicy } from "../powershell/policy.ts";
 import { collectModelFacts, modelsSection } from "./models.ts";
 import { computePresets, presetsSection } from "./presets.ts";
 import {
@@ -181,7 +184,7 @@ export function buildDoctorReport({ env, registry, session }: BuildInput): Docto
 	sections.push(mcpSection(compat, session, env.home));
 
 	const webSearchSettings = webSearchSettingsFrom(readJsonFile<{ webSearch?: unknown }>(oneCodeSettingsPath(env.home, env.env))?.webSearch);
-	const deps = checkDependencies({ cwd: env.cwd, env: env.env, platform: env.platform, mcpServers: compat.mcp.servers, sessionModel: session.model, webSearchSettings });
+	const deps = checkDependencies({ cwd: env.cwd, env: env.env, platform: env.platform, agentDir: env.agentDir, mcpServers: compat.mcp.servers, sessionModel: session.model, webSearchSettings, shells: resolveShells(env.env, env.home, env.platform) });
 	findings.push(...deps.findings);
 	sections.push(dependenciesSection(deps));
 
@@ -224,3 +227,20 @@ function summaryText(input: {
 export function oneCodeVersion(env: NodeJS.ProcessEnv = process.env): string {
 	return env.CC_VERSION ?? extensionVersion();
 }
+
+/** The shell tools exactly as a session resolves them (bash/index.ts, powershell/index.ts). */
+export function resolveShells(procEnv: NodeJS.ProcessEnv, home: string, platform: string): ShellsInput {
+	const plat = platform as NodeJS.Platform;
+	const bash = resolveBashSpawn({ env: procEnv, settingsEnv: readSettingsEnv(home) });
+	const powershell = resolvePowerShellSpawn({ platform: plat, env: procEnv });
+	const policy = shellToolPolicy({ platform: plat, env: procEnv, bash: !!bash.spawn, powershell: !!powershell });
+	return {
+		bash: bash.spawn?.shell,
+		bashWarning: bash.warning,
+		powershell: powershell?.shell,
+		powershellWanted: policy.powershellWanted,
+		bashExpected: policy.bashExpected,
+		primary: policy.primary,
+		notices: policy.notices,
+	};
+}

package/extensions/doctor/dependencies.ts

@@ -11,11 +11,12 @@
  * providers it depends on a third-party key.
  */
 
-import { accessSync, constants, existsSync } from "node:fs";
-import { delimiter, join } from "node:path";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { whichOnPath } from "../lib/which.ts";
 import type { Api, Model } from "@earendil-works/pi-ai";
 import { getProviderKind } from "pi-web-search/src/api.ts";
-import { INSTALL_HINTS } from "../lsp/install-hints.ts";
+import { installHint, serverInstallHint } from "../lsp/install-hints.ts";
 import { SERVERS } from "../lsp/servers.ts";
 import { typescriptPreflight } from "../lsp/servers.ts";
 import type { McpServer } from "../mcp/config.ts";
@@ -43,30 +44,6 @@ export interface DependencyReport {
 	findings: Finding[];
 }
 
-/** Minimal `which`: the first PATH entry holding an executable of that name. */
-export function whichOnPath(command: string, env: NodeJS.ProcessEnv, platform: string = process.platform): string | undefined {
-	if (!command) return undefined;
-	if (command.includes("/") || command.includes("\\")) return isExecutable(command) ? command : undefined;
-	const extensions = platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
-	for (const dir of (env.PATH ?? "").split(delimiter)) {
-		if (!dir) continue;
-		for (const ext of extensions) {
-			const candidate = join(dir, command + ext);
-			if (isExecutable(candidate)) return candidate;
-		}
-	}
-	return undefined;
-}
-
-function isExecutable(path: string): boolean {
-	try {
-		accessSync(path, constants.X_OK);
-		return true;
-	} catch {
-		return false;
-	}
-}
-
 /** Languages the working directory plausibly contains, by the LSP table's own root markers. */
 export function projectLanguages(cwd: string): string[] {
 	const seen = new Map<string, string>(); // command → languageId (one per server binary)
@@ -86,9 +63,45 @@ export interface DependencyInput {
 	cwd: string;
 	env: NodeJS.ProcessEnv;
 	platform?: string;
+	/** pi's agent dir; its `bin/` holds the ripgrep pi downloads itself. */
+	agentDir?: string;
 	mcpServers: McpServer[];
 	sessionModel?: Model<Api>;
 	webSearchSettings: WebSearchSettings;
+	/**
+	 * The shell tools as the session resolves them (build.ts, from
+	 * lib/shell-spawn.ts + powershell/policy.ts): which bash, which PowerShell,
+	 * which one is primary, and the startup notices. On Windows this is the
+	 * first thing a user asks the doctor — "which shells did you find?" — and
+	 * the report had no line for it until 2026-09-19 (the Vultr VM session).
+	 */
+	shells?: ShellsInput;
+}
+
+export interface ShellsInput {
+	/** The bash binary the bash tool runs, or undefined when none exists. */
+	bash?: string;
+	/** An ignored CLAUDE_CODE_GIT_BASH_PATH, in the resolver's words. */
+	bashWarning?: string;
+	/** The PowerShell executable the powershell tool would run, or undefined. */
+	powershell?: string;
+	/** From `shellToolPolicy`: the tool is meant to be on (env switch, else Windows). */
+	powershellWanted: boolean;
+	/** From `shellToolPolicy`: a bash is part of this platform's expected shape (not Windows). */
+	bashExpected: boolean;
+	primary: "powershell" | "bash" | "none";
+	notices: string[];
+}
+
+function bashReason(s: ShellsInput): string {
+	if (s.primary === "bash") return "the primary shell tool";
+	if (s.bash) return "the bash tool, alongside PowerShell";
+	return s.bashExpected ? "the bash tool" : "the bash tool (Git for Windows provides one)";
+}
+
+function powershellReason(s: ShellsInput): string {
+	if (!s.powershellWanted) return s.bashExpected ? "the powershell tool (off; CLAUDE_CODE_USE_POWERSHELL_TOOL=1 turns it on with a pwsh on PATH)" : "the powershell tool (off: CLAUDE_CODE_USE_POWERSHELL_TOOL=0)";
+	return s.primary === "powershell" ? "the primary shell tool" : "the powershell tool";
 }
 
 export function checkDependencies(input: DependencyInput): DependencyReport {
@@ -102,8 +115,27 @@ export function checkDependencies(input: DependencyInput): DependencyReport {
 	checks.push({ name: "git", found: !!git, path: git, need: "required", reason: "repository detection, auto mode's recoverability check, worktree isolation", hint: "https://git-scm.com/downloads" });
 	if (!git) findings.push({ level: "warn", text: "git is not on PATH: worktree isolation and auto mode's git-recoverability check are unavailable.", fix: "Install git and make sure it is on the PATH used to launch One Code." });
 
-	const rg = which("rg");
-	checks.push({ name: "rg", found: !!rg, path: rg, need: "optional", reason: "faster code search when the model shells out to ripgrep", hint: "brew install ripgrep" });
+	// pi downloads ripgrep into <agentDir>/bin on first run when PATH has none
+	// and puts that dir on the shell tools' PATH, so a copy there is "found".
+	const rgName = platform === "win32" ? "rg.exe" : "rg";
+	const bundledRg = input.agentDir ? join(input.agentDir, "bin", rgName) : undefined;
+	if (input.shells) {
+		const s = input.shells;
+		checks.push({ name: "bash", found: !!s.bash, path: s.bash, need: s.bashExpected ? "required" : "optional", reason: bashReason(s), hint: s.bashExpected ? undefined : "https://git-scm.com/download/win" });
+		checks.push({ name: "powershell", found: !!s.powershell, path: s.powershell, need: s.powershellWanted ? "required" : "unused", reason: powershellReason(s), hint: "https://aka.ms/powershell" });
+		if (s.bashWarning) findings.push({ level: "warn", text: s.bashWarning, fix: "Point CLAUDE_CODE_GIT_BASH_PATH at a bash.exe or sh.exe, or unset it to use Git for Windows' default location." });
+		for (const notice of s.notices) {
+			const switchSet = notice.includes("CLAUDE_CODE_USE_POWERSHELL_TOOL");
+			findings.push({
+				level: s.primary === "none" ? "error" : "warn",
+				text: notice,
+				fix: switchSet ? "Install PowerShell 7 (pwsh) or unset CLAUDE_CODE_USE_POWERSHELL_TOOL." : "Install Git for Windows or PowerShell 7.",
+			});
+		}
+	}
+
+	const rg = which("rg") ?? (bundledRg && existsSync(bundledRg) ? bundledRg : undefined);
+	checks.push({ name: "rg", found: !!rg, path: rg, need: "optional", reason: "faster code search when the model shells out to ripgrep", hint: installHint("ripgrep", platform) });
 
 	const languages = projectLanguages(cwd);
 	const seenCommands = new Set<string>();
@@ -119,13 +151,13 @@ export function checkDependencies(input: DependencyInput): DependencyReport {
 			path: found,
 			need: needed ? "project" : "unused",
 			reason: `lsp_diagnostics for ${family.join("/")}${needed ? " (this project)" : ""}`,
-			hint: INSTALL_HINTS[config.command],
+			hint: serverInstallHint(config.command, platform),
 		});
 		if (needed && !found) {
 			findings.push({
 				level: "warn",
 				text: `${config.command} is not installed, so the model gets no language-server diagnostics after editing ${family[0]} files here.`,
-				fix: INSTALL_HINTS[config.command] ? `Install it with: ${INSTALL_HINTS[config.command]}` : "Install it and make sure it is on your PATH.",
+				fix: serverInstallHint(config.command, platform) ? `Install it with: ${serverInstallHint(config.command, platform)}` : "Install it and make sure it is on your PATH.",
 			});
 		}
 		if (needed && found && config.command === "typescript-language-server") {

package/extensions/doctor/fix-prompt.ts

@@ -22,13 +22,18 @@
  * kept in substance. Rationale: docs/decisions/doctor.md.
  */
 
+import { modeCycleKey } from "../lib/keys.ts";
+import { UPGRADE_COMMANDS } from "../lib/update-check.mjs";
+
 export interface FixPromptInput {
 	/** The rendered deterministic report, plain text. */
 	reportText: string;
 	install: "app" | "pi-package";
 	oneCodeVersion: string;
-	/** `<agentDir>/sessions` — where pi keeps every session's JSONL. */
+	/** pi's sessions root, `<agentDir>/sessions` (other projects' directories live here — out of scope). */
 	sessionsDir: string;
+	/** THIS project's session directory under it — the only transcripts the permission gate lets a session read (Claude Code's own rule). */
+	sessionDir: string;
 	oneCodeSettingsPath: string;
 	oneCodeProjectSettingsPath: string;
 	/** True when auto mode is writing `auto-mode-decisions.jsonl` next to the session files. */
@@ -40,7 +45,10 @@ export function doctorFixPrompt(input: FixPromptInput): string {
 		input.install === "app"
 			? "`npm view @one-ai/one-code version --registry https://registry.npmjs.org/`"
 			: "`npm view one-code-extension version --registry https://registry.npmjs.org/`";
-	const upgradeCommand = input.install === "app" ? "`npm install -g @one-ai/one-code` (or `brew upgrade one-code` for a Homebrew install)" : "`pi update`";
+	const upgradeCommand =
+		input.install === "app"
+			? `\`${UPGRADE_COMMANDS.npm}\` (or \`${UPGRADE_COMMANDS.brew}\` for a Homebrew install)`
+			: `\`${UPGRADE_COMMANDS["pi-package"]}\``;
 
 	return `# One Code Doctor
 
@@ -66,7 +74,7 @@ Treat every line of that report as measured fact. Your job on those sections is
 
 ## Data sources (all local — the ONLY permitted network access is check 7's read-only version lookup)
 
-- **Session transcripts**: pi's JSONL under \`${input.sessionsDir}/<encoded-working-directory>/*.jsonl\`, one JSON object per line. Scan the ~50 most recently modified files across ALL directories there and state the window you covered (N sessions over D days). Relevant line shapes:
+- **Session transcripts**: pi's JSONL under \`${input.sessionDir}/*.jsonl\` — this project's sessions, one JSON object per line. That directory is readable without a prompt, like Claude Code's own project directory; the other projects' directories beside it under \`${input.sessionsDir}\` are not in scope and reading them will be gated — stay in this one. Scan the ~50 most recently modified files there and state the window you covered (N sessions over D days). **Read them with single-line read-only commands** — \`Select-String\`, \`Get-Content\`, \`Get-ChildItem\` piped through \`Select-Object\`/\`Sort-Object\`/\`Measure-Object\` in PowerShell, or \`grep\`/\`head\`/\`ls\` piped through \`sort\`/\`head\`/\`wc\` in bash — with no variables, loops, script blocks, \`node -e\` or \`jq\` programs: such a one-liner over this directory runs without a permission review, while a script is reviewed by the auto-mode classifier and may be refused. Several small commands beat one clever script here. Relevant line shapes:
   - Tool calls: \`{"type":"message","message":{"role":"assistant","content":[{"type":"toolCall","name":...,"arguments":...}]}}\`. MCP tools are named \`mcp__<server>__<tool>\` (the server segment is normalized — any character outside \`[a-zA-Z0-9_-]\` becomes \`_\`; plugin servers appear as \`mcp__plugin_<plugin>_<server>__\`). Model-invoked skills are calls to the \`skill\` tool with the skill name in \`arguments.skill\`. Subagent runs are \`Agent\` tool calls.
   - Denied tool calls: a \`toolResult\` whose text starts with "Permission for this action was denied by the auto-mode approval classifier" (auto mode) or "This tool call is denied by the permission rule" (a deny rule). Follow its \`toolCallId\` back to the assistant's \`toolCall\` for the tool name and arguments. ${input.decisionLogEnabled ? "Auto mode is also writing `auto-mode-decisions.jsonl` next to each session file — every gate decision with its verdict; prefer it for check 9." : "Auto mode is not logging its decisions (`autoMode.logDecisions` is off), so transcripts are the only denial record."}
   - There are NO usage counters in One Code: whether a skill, plugin or MCP server was used is answered from transcripts alone.
@@ -107,7 +115,7 @@ Installed: ${input.oneCodeVersion} (${input.install === "app" ? "the bundled one
 
 ## Check 8 — permission mode (report only)
 
-Auto mode is One Code's shipped default. If the report shows a different mode pinned by \`permissions.defaultMode\` in \`~/.claude/settings.json\` or a managed file, say so in one line and leave it — One Code does not edit those files, and the user can change the mode with ctrl+q or \`--permission-mode\`. If a repository file pins \`auto\` or \`bypassPermissions\`, the report already explains why it is ignored.
+Auto mode is One Code's shipped default. If the report shows a different mode pinned by \`permissions.defaultMode\` in \`~/.claude/settings.json\` or a managed file, say so in one line and leave it — One Code does not edit those files, and the user can change the mode with ${modeCycleKey()} or \`--permission-mode\`. If a repository file pins \`auto\` or \`bypassPermissions\`, the report already explains why it is ignored.
 
 ## Check 9 — pre-approve frequently denied read-only commands
 

package/extensions/doctor/index.ts

@@ -159,6 +159,7 @@ export default function doctorExtension(pi: ExtensionAPI) {
 			install: install(),
 			oneCodeVersion: oneCodeVersion(),
 			sessionsDir: join(getAgentDir(), "sessions"),
+			sessionDir: ctx.sessionManager.getSessionDir(),
 			oneCodeSettingsPath: oneCodeSettingsPath(home),
 			oneCodeProjectSettingsPath: oneCodeProjectSettingsPath(ctx.cwd, home),
 			decisionLogEnabled: loadAutoModeConfig(home).logDecisions,

package/extensions/doctor/models.ts

@@ -10,6 +10,7 @@
  */
 
 import type { Api, Model } from "@earendil-works/pi-ai";
+import { modeCycleKey } from "../lib/keys.ts";
 import { loadAutoModeConfig } from "../auto-mode/config.ts";
 import { classifierCandidates, describeCandidate, type ClassifierNotice } from "../auto-mode/model-select.ts";
 import { ATTRIBUTION, capabilityFloor, configuredCapabilityKey, type FloorRole, type FloorVerdict, KEY_ADVICE, snapshotAgeMs } from "../lib/capability-index.ts";
@@ -210,7 +211,7 @@ export function modelsSection(facts: ModelFacts, session: SessionView, findings:
 	if (session.permission) {
 		const mode = session.permission.mode;
 		const from = session.permission.source ? ` (${session.permission.source})` : "";
-		lines.push({ text: `Permission mode: ${mode}${from} — ctrl+q cycles, /permissions lists the rules`, level: "dim" });
+		lines.push({ text: `Permission mode: ${mode}${from} — ${modeCycleKey()} cycles, /permissions lists the rules`, level: "dim" });
 	}
 
 	if (facts.sessionTier === "tiny") {

package/extensions/doctor/report.ts

@@ -16,6 +16,7 @@
  */
 
 import type { Api, Model } from "@earendil-works/pi-ai";
+import { tildify } from "../lib/paths.ts";
 import type { McpStatusEvent } from "../lib/mcp-status.ts";
 import { wrapProse } from "../subagents/panel-render.ts";
 import { countNoun } from "../lib/tui-render.ts";
@@ -183,7 +184,5 @@ export function contextLabel(tokens: number | undefined): string {
 
 /** `~/…` for anything under home, so paths stay readable at any width. */
 export function shortenHome(path: string, home: string): string {
-	if (path === home) return "~";
-	const root = home.endsWith("/") ? home : `${home}/`;
-	return path.startsWith(root) ? `~/${path.slice(root.length)}` : path;
+	return tildify(path, home);
 }

package/extensions/doctor/update-lookup.ts

@@ -1,16 +1,19 @@
 /**
  * Newest-release lookup for the doctor's Installation section (pure given a
- * fetch). Mirrors the app's daily update check (app/update-check.mjs): the same
- * registry endpoints, a short timeout, silent on failure, and skipped under
- * pi's offline switch or ONECODE_NO_UPDATE_CHECK — a diagnostic must never hang
- * on the network or restore egress the user turned off.
+ * fetch). Shares the app's daily update notice's mechanism
+ * (lib/update-check.mjs): the same packument, the same "newest installable
+ * version" rule — a day's release age under Homebrew, `dist-tags.latest`
+ * otherwise — a short timeout, silent on failure, and skipped under pi's
+ * offline switch or ONECODE_NO_UPDATE_CHECK — a diagnostic must never hang on
+ * the network or restore egress the user turned off.
  */
 
 import { compareVersions } from "../lib/pi-version.ts";
+import { APP_PACKAGE, EXTENSION_PACKAGE, minReleaseAgeFor, pickAvailableVersion, registryPackumentUrl } from "../lib/update-check.mjs";
 import type { DoctorEnvironment } from "./report.ts";
 
-export const APP_REGISTRY_URL = "https://registry.npmjs.org/@one-ai%2Fone-code/latest";
-export const PACKAGE_REGISTRY_URL = "https://registry.npmjs.org/one-code-extension/latest";
+export const APP_REGISTRY_URL = registryPackumentUrl(APP_PACKAGE);
+export const PACKAGE_REGISTRY_URL = registryPackumentUrl(EXTENSION_PACKAGE);
 export const LOOKUP_TIMEOUT_MS = 3000;
 
 export type LatestLookup = NonNullable<DoctorEnvironment["latest"]>;
@@ -34,11 +37,16 @@ export async function lookupLatestVersion(input: {
 	try {
 		const response = await fetchImpl(url, { signal: AbortSignal.timeout(input.timeoutMs ?? LOOKUP_TIMEOUT_MS) });
 		if (!response.ok) return { status: "unknown", reason: `registry answered ${response.status}` };
-		const body = (await response.json()) as { version?: unknown };
-		if (typeof body.version !== "string") return { status: "unknown", reason: "unexpected registry payload" };
-		const cmp = compareVersions(body.version, input.current);
-		if (cmp === undefined) return { status: "unknown", version: body.version, reason: "unparseable version" };
-		return { status: cmp > 0 ? "behind" : "current", version: body.version };
+		const minReleaseAgeMs = minReleaseAgeFor(input.env);
+		const body = (await response.json()) as { "dist-tags"?: { latest?: unknown }; time?: unknown };
+		const wellFormed = typeof body?.["dist-tags"]?.latest === "string" && (minReleaseAgeMs <= 0 || (typeof body.time === "object" && body.time !== null));
+		if (!wellFormed) return { status: "unknown", reason: "unexpected registry payload" };
+		const latest = pickAvailableVersion(body, { minReleaseAgeMs });
+		// A well-formed packument with nothing old enough is a Homebrew outcome, not a broken registry.
+		if (typeof latest !== "string") return { status: "unknown", reason: "no release is a day old yet (Homebrew installs wait that long)" };
+		const cmp = compareVersions(latest, input.current);
+		if (cmp === undefined) return { status: "unknown", version: latest, reason: "unparseable version" };
+		return { status: cmp > 0 ? "behind" : "current", version: latest };
 	} catch (error) {
 		const message = error instanceof Error ? (error.name === "TimeoutError" ? "timed out" : error.message) : String(error);
 		return { status: "unknown", reason: message };

package/extensions/effort/index.ts

@@ -42,6 +42,7 @@ import {
 	ULTRACODE_MODE_CHANNEL,
 	ULTRACODE_STATUS_KEY,
 } from "./slider.ts";
+import { registerLocalCommand } from "../lib/local-command.ts";
 
 /** The levels pi says the active model can reach; the full ladder when unknown. */
 function supportedLevels(ctx: ExtensionContext): ThinkingLevel[] {
@@ -193,7 +194,7 @@ export default function effortExtension(pi: ExtensionAPI) {
 		if (chosen) applyChoice(chosen, ctx);
 	};
 
-	pi.registerCommand("effort", {
+	registerLocalCommand(pi, "effort", {
 		description: `Set reasoning effort (shift+tab cycles the plain levels): /effort [${EFFORT_CHOICES.join("|")}] — ultracode is ${ULTRACODE_LEVEL} + workflows`,
 		getArgumentCompletions: (prefix) => {
 			const matches = acceptedEffortArgs().filter((value) => value.startsWith(prefix.trim().toLowerCase()));