one-code-extension 0.4.1 → 0.5.0

package/extensions/lib/workspace-channel.ts

@@ -0,0 +1,16 @@
+/**
+ * The workspace directories in force when a session starts, announced by the
+ * permissions extension over `pi.events` (jiti isolation, findings §3) so the
+ * system prompt can list them the way Claude Code's environment block does
+ * (` - Additional working directories:`). It is emitted once, at
+ * session_start: the system prompt stays byte-stable for the session, and a
+ * directory added later reaches the model through the /permissions or
+ * /add-dir command output instead.
+ */
+
+export const WORKSPACE_CHANNEL = "one-code:workspace-dirs";
+
+export interface WorkspaceAnnouncement {
+	/** Absolute, resolved paths, in the order the gate applies them. */
+	dirs: string[];
+}

package/extensions/lib/worktree-channel.ts

@@ -4,9 +4,11 @@
  * worktree extension emits on every state change — enter, exit, and the
  * session_start/session_tree restore; the footer shows the worktree's path
  * and branch in place of the process cwd while one is active (Claude Code's
- * footer does the same). The bus does not replay: a late subscriber sees the
- * next change, which is fine here — the footer subscribes at load, and the
- * first emit is the session_start restore.
+ * footer does the same), cron fires and monitors run there, and subagents
+ * and workflow agents are spawned there (`sessionWorkCwd`). The bus does not
+ * replay: a late subscriber sees the next change, which is fine here — every
+ * subscriber subscribes at load, and the first emit is the session_start
+ * restore.
  */
 
 export const WORKTREE_CHANNEL = "one-code:worktree";
@@ -15,4 +17,30 @@ export const WORKTREE_CHANNEL = "one-code:worktree";
 export interface WorktreeLocation {
 	path: string;
 	branch?: string;
+	/** Root of the shared checkout the worktree belongs to, for the child sessions' git-isolation guard. */
+	sharedRoot?: string;
+}
+
+/**
+ * Where the session's work happens: the entered worktree while one is active,
+ * else the session's own cwd. A removed worktree must fail at that path, never
+ * silently redirect work into the original checkout. The worktree extension
+ * announces a missing path on restore and blocks calls until an active missing
+ * worktree is explicitly left. pi fixes a session's cwd at creation, so a child
+ * spawned from `ctx.cwd` would work in the checkout the user meant to protect.
+ */
+export function sessionWorkCwd(entered: WorktreeLocation | null | undefined, sessionCwd: string): string {
+	return entered?.path || sessionCwd;
+}
+
+/**
+ * Subscribe once at load and get `sessionWorkCwd` for the latest announcement:
+ * `(ctx.cwd) => where this session's work happens now`.
+ */
+export function followWorkCwd(events: { on(channel: string, handler: (data: unknown) => void): unknown }): (sessionCwd: string) => string {
+	let entered: WorktreeLocation | null = null;
+	events.on(WORKTREE_CHANNEL, (data) => {
+		entered = data as WorktreeLocation | null;
+	});
+	return (sessionCwd) => sessionWorkCwd(entered, sessionCwd);
 }

package/extensions/lib/worktree-isolation.ts

@@ -6,11 +6,14 @@
  *
  * The registry exists because the association can only resolve at call time:
  * these worktrees live in tmpdirs (not statically recognizable paths), and the
- * child loaders are cached and shared across runs with different cwds.
+ * guard judges each call's `ctx.cwd`, not the cwd its child's loader was built
+ * with (one loader per child session, lib/agent-loader.ts openChildSession).
  * createWorktree/cleanupWorktree (subagents/worktree.ts) register and release
  * entries; reconstructed run records re-register kept worktrees after a
- * process restart (subagents/index.ts); the guard resolves each bash call's
- * cwd against them.
+ * process restart (subagents/index.ts); the worktree the main session entered
+ * with `enter_worktree` is registered too (`followEnteredWorktree`), so a child
+ * spawned there is guarded like an isolated one; the guard resolves each bash
+ * call's cwd against them.
  *
  * Module state is deliberate and safe despite jiti isolation: registration
  * (worktree creation) and lookup (the guard factory) always happen inside the
@@ -22,9 +25,11 @@
 import { homedir } from "node:os";
 import { isAbsolute, join, relative } from "node:path";
 import type { InlineExtension } from "@earendil-works/pi-coding-agent";
+import { findProjectRoot, repositoryWorktrees } from "./git.ts";
+import { WORKTREE_CHANNEL, type WorktreeLocation } from "./worktree-channel.ts";
 import { isWithin, isWritingTool, pathArgument, resolveForContainment, toAbsolute } from "../auto-mode/paths.ts";
 import { analyzeShellCommand } from "../auto-mode/shell-analysis.ts";
-import { worktreeBashGuardReason } from "../worktree/guards.ts";
+import { namesGit, unlistedWorktreesReason, worktreeBashGuardReason } from "../worktree/guards.ts";
 
 export interface WorktreeIsolation {
 	/** The isolated worktree the run works in. */
@@ -61,11 +66,35 @@ export function releaseWorktreeIsolation(worktreePath: string): void {
 	active.delete(worktreePath);
 }
 
+/**
+ * Follow the main session's `enter_worktree` state over `WORKTREE_CHANNEL`
+ * and return a getter for it. The entered worktree is registered in this
+ * extension's registry, so a child spawned there gets the git-isolation and
+ * write guards. The entry stays after the session exits the worktree: a child
+ * started there may still be running, and a registration for a directory no
+ * later child runs in is inert.
+ */
+export function followEnteredWorktree(events: { on(channel: string, handler: (data: unknown) => void): unknown }): () => WorktreeLocation | undefined {
+	let entered: WorktreeLocation | undefined;
+	events.on(WORKTREE_CHANNEL, (data) => {
+		const location = data as WorktreeLocation | null | undefined;
+		entered = location?.path ? location : undefined;
+		if (entered) registerWorktreeIsolation(entered.path, entered.sharedRoot ?? findProjectRoot(entered.path) ?? entered.path);
+	});
+	return () => entered;
+}
+
 /** The registered isolation worktree `cwd` lives in, if any. */
 export function worktreeIsolationFor(cwd: string): WorktreeIsolation | undefined {
 	for (const isolation of active.values()) {
 		if (isWithin(isolation.worktreePath, cwd)) return isolation;
 	}
+	if (active.size === 0) return undefined;
+	const resolved = resolveForContainment(cwd);
+	if (resolved === undefined) return undefined;
+	for (const isolation of active.values()) {
+		if (isWithin(isolation.resolvedWorktreePath, resolved)) return isolation;
+	}
 	return undefined;
 }
 
@@ -79,10 +108,8 @@ export function worktreeIsolationFor(cwd: string): WorktreeIsolation | undefined
 export function sharedCheckoutWriteTarget(target: string, cwd: string, isolation: WorktreeIsolation, home = homedir()): string | undefined {
 	const { worktreePath, sharedRoot, resolvedWorktreePath, resolvedSharedRoot } = isolation;
 	const absolute = toAbsolute(cwd, target, home);
-	// Fast path: spelled under the worktree as registered — the common case for
-	// every write the model does where it was told to (no syscall).
-	if (isWithin(worktreePath, absolute)) return undefined;
-	// Resolved so a write is judged by where it lands, not how it is spelled.
+	// Resolve even paths spelled under the worktree: a symlink there can point
+	// back into the shared checkout.
 	const resolved = resolveForContainment(absolute) ?? absolute;
 	if (isWithin(resolvedWorktreePath, resolved) || !isWithin(resolvedSharedRoot, resolved)) return undefined;
 	// The tail keeps the model's spelling when the path was written under the
@@ -151,15 +178,18 @@ export function worktreeGuardFactory(cwd: string): InlineExtension {
 		name: "agent-worktree-guard",
 		hidden: true,
 		factory: (pi) => {
-			pi.on("tool_call", (event, ctx) => {
+			pi.on("tool_call", async (event, ctx) => {
 				const runCwd = ctx?.cwd ?? cwd;
 				const isolation = worktreeIsolationFor(runCwd);
 				if (!isolation) return undefined;
 				const input = (event.input ?? {}) as Record<string, unknown>;
 				if (event.toolName === "bash") {
 					if (typeof input.command !== "string") return undefined;
+					// Every worktree of the repository, as the main session's guard checks: a linked one may live outside the shared root.
+					const others = namesGit(input.command) ? await repositoryWorktrees(isolation.worktreePath) : [];
+					if (others === undefined) return { block: true, reason: unlistedWorktreesReason(isolation.worktreePath) };
 					const reason =
-						worktreeBashGuardReason({ command: input.command, worktreePath: isolation.worktreePath, sharedRoot: isolation.sharedRoot }) ??
+						worktreeBashGuardReason({ command: input.command, worktreePath: isolation.worktreePath, sharedRoot: isolation.sharedRoot, otherWorktrees: others }) ??
 						worktreeBashWriteGuardReason({ command: input.command, cwd: runCwd, isolation });
 					return reason ? { block: true, reason } : undefined;
 				}

package/extensions/lsp/client.ts

@@ -19,8 +19,9 @@ import { type ChildProcess, spawn } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import type { LspDiagnostic } from "./format.ts";
+import { childProcessEnv } from "../lib/app-launch.mjs";
 import { commandLaunch } from "../lib/command-launch.ts";
-import { killProcessTree } from "../lib/process-tree.ts";
+import { killProcessTree, unrefHandle } from "../lib/process-tree.ts";
 import { createReaderState, encodeMessage, type JsonRpcMessage, readMessages } from "./protocol.ts";
 
 const INITIALIZE_TIMEOUT_MS = 15_000;
@@ -57,10 +58,6 @@ export function configurationResponse(settings: unknown, params: unknown): unkno
 	return Array.from({ length: count }, () => settings ?? {});
 }
 
-function unrefStream(stream: unknown): void {
-	(stream as { unref?: () => void } | null | undefined)?.unref?.();
-}
-
 interface OpenDocument {
 	version: number;
 	text: string;
@@ -101,7 +98,9 @@ export class LspClient {
 	async start(): Promise<void> {
 		if (this.child) return;
 
-		const env = this.options.env ? { ...process.env, ...this.options.env } : process.env;
+		// The user's own environment under the bundled app (lib/app-launch.mjs).
+		const base = childProcessEnv(process.env);
+		const env = this.options.env ? { ...base, ...this.options.env } : base;
 		// On Windows an npm-installed server is a .cmd shim, which a bare spawn
 		// cannot start (lib/command-launch.ts); failure messages keep naming the command.
 		const launch = commandLaunch(this.config.command, this.config.args, env);
@@ -118,9 +117,9 @@ export class LspClient {
 		// are sockets at runtime, so they carry unref() even though the stream
 		// types don't declare it.
 		child.unref();
-		unrefStream(child.stdout);
-		unrefStream(child.stderr);
-		unrefStream(child.stdin);
+		unrefHandle(child.stdout);
+		unrefHandle(child.stderr);
+		unrefHandle(child.stdin);
 
 		let stderr = "";
 		child.stderr?.on("data", (chunk: Buffer) => {

package/extensions/lsp/index.ts

@@ -47,6 +47,9 @@ import {
 import { findProjectRoot, serverForPath, typescriptPreflight } from "./servers.ts";
 import { computeDelta, DeliveredTracker, fingerprintDiagnostic, formatNewDiagnostics, markDelivered } from "./watcher.ts";
 import { registerLocalCommand } from "../lib/local-command.ts";
+import { singleFlight } from "../lib/single-flight.ts";
+import { findProjectRoot as findRepoRoot } from "../lib/git.ts";
+import { createLspTrustGate, PROJECT_CODE_REASON, PROJECT_CODE_SERVERS } from "./trust.ts";
 
 /** Everything needed to spawn/reuse the server responsible for a path. */
 interface ResolvedTarget {
@@ -133,12 +136,28 @@ export default function lspExtension(pi: ExtensionAPI) {
 	const MAX_RESPAWNS = 2;
 	const respawns = new Map<string, number>();
 
-	const clientFor = async (target: ResolvedTarget): Promise<LspClient | undefined> => {
+	/**
+	 * One startup per server key at a time: overlapping calls (two edits, or a
+	 * diagnostics wait racing an edit) share it, since both would otherwise
+	 * pass the empty-map check across the trust and backoff awaits and spawn a
+	 * second server whose predecessor shutdown can no longer reach.
+	 */
+	const startOnce = singleFlight<LspClient | undefined>();
+	const clientFor = (target: ResolvedTarget, ctx: ExtensionContext): Promise<LspClient | undefined> => {
+		const running = clients.get(target.key);
+		if (running?.isRunning) return Promise.resolve(running);
+		return startOnce(target.key, () => startClient(target, ctx));
+	};
+
+	const startClient = async (target: ResolvedTarget, ctx: ExtensionContext): Promise<LspClient | undefined> => {
 		const { key } = target;
 		if (startFailures.has(key)) return undefined;
 
 		const existing = clients.get(key);
 		if (existing?.isRunning) return existing;
+		// A server that runs project code starts only in a trusted project
+		// (trust.ts); checked here so no caller can spawn one without it.
+		if (!(await projectCodeAllowed(target, ctx)) || ctx.signal?.aborted) return undefined;
 		if (existing) {
 			// Crashed mid-session. Respawn with a short backoff, up to MAX_RESPAWNS
 			// times; after that record why so downstream reports the real cause (a
@@ -155,6 +174,8 @@ export default function lspExtension(pi: ExtensionAPI) {
 			await new Promise((resolve) => setTimeout(resolve, 500 * count));
 		}
 
+		if (ctx.signal?.aborted) return undefined;
+
 		// Keyed on the command being spawned, not on where the config came from —
 		// a plugin configuring typescript-language-server hits the same TS7 trap.
 		if (target.command === "typescript-language-server") {
@@ -181,6 +202,33 @@ export default function lspExtension(pi: ExtensionAPI) {
 		}
 	};
 
+	/**
+	 * Consent for a built-in server that runs the project's own code
+	 * (trust.ts): trusted project → start; otherwise ask once per project in an
+	 * interactive session, and with no UI or a "no" leave it off with a
+	 * not-started failure the one-time notice and /lsp report.
+	 */
+	const trustGate = createLspTrustGate({ projectRoot: (dir) => findRepoRoot(dir) ?? dir });
+	const NOT_TRUSTED = "not started:";
+	const projectCodeAllowed = async (target: ResolvedTarget, ctx: ExtensionContext): Promise<boolean> => {
+		if (target.plugin || !PROJECT_CODE_SERVERS.has(target.command)) return true;
+		const why = PROJECT_CODE_REASON[target.command] ?? "runs this project's code";
+		const confirm = ctx.hasUI
+			? async (root: string) =>
+					(await ctx.ui.confirm(
+						`Start ${target.command} in this project?`,
+						`${target.command} ${why}. Allow it only for a project you trust.\n\nThe answer for ${root} is remembered; /lsp trust allows it later.`,
+						{ signal: ctx.signal },
+					)) === true
+			: undefined;
+		if (await trustGate.allowed(target.root, confirm, ctx.signal)) return true;
+		if (ctx.signal?.aborted) return false;
+		if (!startFailures.has(target.key)) {
+			startFailures.set(target.key, `${NOT_TRUSTED} ${target.command} ${why}, and this project is not trusted (run /lsp trust to allow it)`);
+		}
+		return false;
+	};
+
 	/** One-time notice per server key so a missing server doesn't degrade silently. */
 	const reportFailureOnce = (target: ResolvedTarget, notify: (message: string) => void) => {
 		const failure = startFailures.get(target.key);
@@ -270,7 +318,7 @@ export default function lspExtension(pi: ExtensionAPI) {
 					// pending work, and everything the client holds is unref'd —
 					// without a ref the loop drains and pi exits mid-tool (keep-alive.ts).
 					await withKeepAlive(async () => {
-						const client = await clientFor(target);
+						const client = await clientFor(target, ctx);
 						if (client) {
 							tracker.clear(pathToUri(path));
 							forceDeltaScan();
@@ -321,10 +369,13 @@ export default function lspExtension(pi: ExtensionAPI) {
 			// One keep-alive spans both awaits (same pattern as the tool_result hook).
 			const fetched = target
 				? await withKeepAlive(async () => {
-						const client = await clientFor(target);
+						const client = await clientFor(target, ctx);
 						return client && { all: await client.getDiagnostics(path, target.languageId) };
 					})
 				: undefined;
+			if (ctx.signal?.aborted) {
+				return { content: [{ type: "text", text: "Diagnostics cancelled because the turn was stopped." }], details: { available: false }, isError: true };
+			}
 			if (!target || !fetched) {
 				const failure = target ? startFailures.get(target.key) : undefined;
 				return {
@@ -363,8 +414,23 @@ export default function lspExtension(pi: ExtensionAPI) {
 	});
 
 	registerLocalCommand(pi, "lsp", {
-		description: "Show language server status",
+		description: "Show language server status: /lsp [trust]",
+		argumentHint: "[trust]",
+		getArgumentCompletions: () => [
+			{ value: "trust", label: "let servers that run this project's code start here (rust-analyzer, jdtls)" },
+		],
 		handler: async (args, ctx) => {
+			if (args.trim() === "trust") {
+				const root = trustGate.trust(ctx.cwd);
+				for (const [key, failure] of startFailures) {
+					if (failure.startsWith(NOT_TRUSTED)) {
+						startFailures.delete(key);
+						warned.delete(key);
+					}
+				}
+				ctx.ui.notify(`Trusted ${root}: rust-analyzer and jdtls may start here. They run this project's build code.`, "info");
+				return;
+			}
 			const lines = [...clients.entries()].map(
 				([key, client]) => `${client.isRunning ? "running" : "stopped"} ${key} (${client.diagnosticsCount} diagnostics)`,
 			);

package/extensions/lsp/keep-alive.ts

@@ -7,7 +7,7 @@
  * process exits 0 mid-await, silently ending the run right after
  * tool_execution_start. Wrap each outermost LS await in this; keeping the ref
  * at the call sites (not inside the client) preserves drain-on-idle for
- * everything not actively awaited. docs/one-shot-lsp-event-loop-drain.md.
+ * everything not actively awaited. working-docs/one-shot-lsp-event-loop-drain.md.
  */
 export async function withKeepAlive<T>(work: () => Promise<T>): Promise<T> {
 	const keepAlive = setInterval(() => {}, 1_000);

package/extensions/lsp/trust.ts

@@ -0,0 +1,119 @@
+/**
+ * Consent before a language server that runs the project's own code (pure fs).
+ *
+ * The LSP extension starts a server after any edit, outside the permission
+ * gate. Most servers only parse, but some execute the project as part of their
+ * job: rust-analyzer runs `build.rs` build scripts and proc macros (and cargo
+ * honours a `rust-toolchain.toml` that can name any toolchain binary), and
+ * jdtls imports Gradle and Maven builds by running them. In an untrusted
+ * checkout, an approved edit to one `.rs` file therefore also ran the
+ * repository's build script (SECURITY-REVIEW-2026-09-23 M4). Those servers now
+ * start only in a project the user has trusted: once per project root,
+ * persisted under `~/.onecode`, asked on first use in an interactive session
+ * or granted with `/lsp trust`. With no UI they stay off (fails closed, like
+ * project hooks and `.mcp.json` servers). Plugin-provided servers never ask:
+ * installing the plugin was the consent.
+ */
+
+import { readJsonFile, writeJsonAtomic } from "../lib/atomic-write.ts";
+import { consentStorePath } from "../lib/consent-stores.ts";
+import { comparablePath, isPathAtOrUnder } from "../lib/paths.ts";
+import { singleFlight } from "../lib/single-flight.ts";
+
+/** Built-in server commands that execute project code. */
+export const PROJECT_CODE_SERVERS: ReadonlySet<string> = new Set(["rust-analyzer", "jdtls"]);
+
+/** What each of those runs, for the consent dialog and the not-started notice. */
+export const PROJECT_CODE_REASON: Record<string, string> = {
+	"rust-analyzer": "runs this project's build scripts and proc macros",
+	jdtls: "runs this project's Gradle or Maven build to import it",
+};
+
+interface TrustStore {
+	version: 1;
+	roots: Record<string, { trustedAt: string }>;
+}
+
+export function lspTrustStorePath(): string {
+	return consentStorePath("lsp");
+}
+
+function readStore(storePath: string): TrustStore {
+	const store = readJsonFile<TrustStore>(storePath);
+	return store && typeof store === "object" && store.roots && typeof store.roots === "object" ? store : { version: 1, roots: {} };
+}
+
+/** Whether `serverRoot` lies at or under a trusted project root. */
+export function isLspRootTrusted(serverRoot: string, storePath = lspTrustStorePath()): boolean {
+	const target = comparablePath(serverRoot);
+	return Object.keys(readStore(storePath).roots).some((root) => isPathAtOrUnder(target, comparablePath(root)));
+}
+
+/** Trust a project root (and everything under it) for project-code servers. */
+export function persistLspTrust(projectRoot: string, storePath = lspTrustStorePath()): void {
+	const store = readStore(storePath);
+	store.roots[projectRoot] = { trustedAt: new Date().toISOString() };
+	try {
+		writeJsonAtomic(storePath, store, { mode: 0o600 });
+	} catch {
+		// Trust still holds for this session through the caller's own memory.
+	}
+}
+
+/**
+ * The per-session trust decision for project-code servers. Every answer is
+ * keyed by the project the SERVER runs in (the repository holding its root),
+ * never the session's cwd: trusting the current checkout must not start a
+ * server rooted in another one (PR #8 review). One question per project is in
+ * flight at a time; a "yes" is persisted, a "no" holds for the session.
+ */
+export function createLspTrustGate(deps: {
+	/** The project a directory belongs to (its repository root, or itself). */
+	projectRoot: (dir: string) => string;
+	isTrusted?: (serverRoot: string) => boolean;
+	persist?: (projectRoot: string) => void;
+}) {
+	const { projectRoot, isTrusted = (root: string) => isLspRootTrusted(root), persist = (root: string) => persistLspTrust(root) } = deps;
+	const sessionTrust = new Map<string, boolean>();
+	/** Server roots found trusted on disk this process, so the store is read once per root. */
+	const trustedServerRoots = new Set<string>();
+	/** Undefined: the caller that opened the dialog aborted, so nobody decided. */
+	const askOnce = singleFlight<boolean | undefined>();
+	const gate = {
+		/**
+		 * Whether a server rooted at `serverRoot` may start. Without `confirm`
+		 * (no UI), or after a "no" for its project, only stored trust counts.
+		 */
+		async allowed(serverRoot: string, confirm?: (projectRoot: string) => Promise<boolean>, signal?: AbortSignal): Promise<boolean> {
+			if (signal?.aborted) return false;
+			const root = projectRoot(serverRoot);
+			if (sessionTrust.get(root) === true || trustedServerRoots.has(serverRoot)) return true;
+			// The project root is what a "yes" persists; a linked worktree outside
+			// its main checkout is not under it, so both are checked.
+			if (isTrusted(serverRoot) || isTrusted(root)) {
+				trustedServerRoots.add(serverRoot);
+				return true;
+			}
+			if (sessionTrust.get(root) !== undefined || !confirm) return false;
+			const decided = await askOnce(root, async () => {
+				const ok = await confirm(root);
+				// Aborting the turn neither grants trust nor remembers a refusal.
+				if (signal?.aborted) return undefined;
+				sessionTrust.set(root, ok);
+				if (ok) persist(root);
+				return ok;
+			});
+			if (signal?.aborted) return false;
+			// The opener aborted without an answer: a caller still live asks again.
+			return decided ?? gate.allowed(serverRoot, confirm, signal);
+		},
+		/** `/lsp trust`: trust the project `dir` belongs to, persisted. Returns that project root. */
+		trust(dir: string): string {
+			const root = projectRoot(dir);
+			persist(root);
+			sessionTrust.set(root, true);
+			return root;
+		},
+	};
+	return gate;
+}

package/extensions/lsp/watcher.ts

@@ -14,7 +14,7 @@
  *
  * One deliberate divergence: file headers are cwd-relative paths, not
  * basenames — two files with the same basename would otherwise be
- * indistinguishable in one block (docs/decisions/lsp.md).
+ * indistinguishable in one block (working-docs/decisions/lsp.md).
  */
 
 import { relative } from "node:path";

package/extensions/mcp/announce.ts

@@ -10,6 +10,7 @@
  */
 
 import { mcpFailuresReminder, mcpInstructionsReminder } from "./client.ts";
+import { countNoun } from "../lib/tui-render.ts";
 
 export interface McpAnnounced {
 	/** Servers whose instructions the model has been given, with the text it saw. */
@@ -38,13 +39,79 @@ export function emptyAnnounced(): McpAnnounced {
 	return { instructed: new Map(), failed: new Map() };
 }
 
+/**
+ * Store and compare the exact bounded values the reminder puts on the wire.
+ * A changing tail beyond either cap is not a model-visible capability change
+ * and must not become a false resume addendum.
+ */
+function displayedInstructions(name: string, instructions: string): string {
+	const rendered = mcpInstructionsReminder([{ server: { name }, instructions }]);
+	const prefix = "# MCP Server Instructions\n\nThe following MCP servers have provided instructions for how to use their tools and resources:\n\n" + `## ${name}\n`;
+	return rendered?.startsWith(prefix) ? rendered.slice(prefix.length) : instructions;
+}
+function displayedFailure(error: string): string {
+	return error.split("\n")[0].slice(0, 300);
+}
+
+/** Maps are serialized as entry arrays so arbitrary server instructions/errors round-trip exactly. */
+export interface McpAnnouncedBaseline { instructed: Array<[string, string]>; failed: Array<[string, string]> }
+export function serializeMcpAnnounced(announced: McpAnnounced): McpAnnouncedBaseline {
+	return { instructed: [...announced.instructed], failed: [...announced.failed] };
+}
+/**
+ * Best-effort compatibility reader for stacks written before structured MCP
+ * baselines. With the configured server `names`, a section starts only at a
+ * `## <name>` heading, so a `## ` heading inside a server's instructions stays
+ * part of them instead of reading as a server of its own.
+ */
+export function mcpAnnouncedFromReminders(instructions: string | undefined, failures: string | undefined, names?: Iterable<string>): McpAnnounced {
+	const announced = emptyAnnounced();
+	const known = names ? new Set(names) : undefined;
+	const instructionPrefix = "# MCP Server Instructions\n\nThe following MCP servers have provided instructions for how to use their tools and resources:\n\n";
+	if (instructions?.startsWith(instructionPrefix)) {
+		const sections: string[] = [];
+		for (const section of instructions.slice(instructionPrefix.length).split("\n\n## ")) {
+			const normalized = section.startsWith("## ") ? section.slice(3) : section;
+			const newline = normalized.indexOf("\n");
+			const heading = newline > 0 ? normalized.slice(0, newline) : normalized;
+			if (known && sections.length > 0 && !known.has(heading)) sections[sections.length - 1] += `\n\n## ${normalized}`;
+			else sections.push(normalized);
+		}
+		for (const section of sections) {
+			const newline = section.indexOf("\n");
+			if (newline > 0) announced.instructed.set(section.slice(0, newline), section.slice(newline + 1));
+		}
+	}
+	const failurePrefix = "The following MCP servers are configured but failed to connect — their tools (typically named mcp__<server>__*) are unavailable for this session:\n";
+	if (failures?.startsWith(failurePrefix)) {
+		for (const line of failures.slice(failurePrefix.length).split("\n")) {
+			if (!line.startsWith("- ")) break;
+			const colon = line.indexOf(": ", 2);
+			if (colon > 2) announced.failed.set(line.slice(2, colon), line.slice(colon + 2));
+		}
+	}
+	return announced;
+}
+
+export function mcpAnnouncedBaseline(value: unknown): McpAnnounced | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const input = value as Record<string, unknown>;
+	const pairs = (item: unknown): Array<[string, string]> | undefined =>
+		Array.isArray(item) && item.every((pair) => Array.isArray(pair) && pair.length === 2 && typeof pair[0] === "string" && typeof pair[1] === "string")
+			? item as Array<[string, string]>
+			: undefined;
+	const instructed = pairs(input.instructed);
+	const failed = pairs(input.failed);
+	return instructed && failed ? { instructed: new Map(instructed), failed: new Map(failed) } : undefined;
+}
+
 /** What message 1 says after it was (re)written from `snapshot`, before the first request. */
 export function announcedFrom(snapshot: McpSnapshot): McpAnnounced {
 	return {
 		instructed: new Map(
-			snapshot.connected.filter((c) => c.instructions).map((c) => [c.name, c.instructions as string]),
+			snapshot.connected.filter((c) => c.instructions).map((c) => [c.name, displayedInstructions(c.name, c.instructions as string)]),
 		),
-		failed: new Map(snapshot.failed.map((f) => [f.name, f.error])),
+		failed: new Map(snapshot.failed.map((f) => [f.name, displayedFailure(f.error)])),
 	};
 }
 
@@ -53,9 +120,11 @@ export function mcpDelta(announced: McpAnnounced, snapshot: McpSnapshot): McpDel
 	const failedNames = new Set(snapshot.failed.map((f) => f.name));
 	return {
 		newInstructions: snapshot.connected
-			.filter((c) => c.instructions && announced.instructed.get(c.name) !== c.instructions)
-			.map((c) => ({ name: c.name, instructions: c.instructions as string })),
-		newFailures: snapshot.failed.filter((f) => announced.failed.get(f.name) !== f.error),
+			.filter((c) => c.instructions && announced.instructed.get(c.name) !== displayedInstructions(c.name, c.instructions as string))
+			.map((c) => ({ name: c.name, instructions: displayedInstructions(c.name, c.instructions as string) })),
+		newFailures: snapshot.failed
+			.filter((f) => announced.failed.get(f.name) !== displayedFailure(f.error))
+			.map((f) => ({ name: f.name, error: displayedFailure(f.error) })),
 		recovered: [...announced.failed.keys()].filter((name) => connectedNames.has(name)),
 		dropped: [...announced.instructed.keys()].filter((name) => !connectedNames.has(name) && !failedNames.has(name)),
 	};
@@ -97,3 +166,16 @@ export function mcpChangeNotices(delta: McpDelta): string[] {
 	}
 	return notices;
 }
+
+/**
+ * The user's startup notices, Claude Code's wording (`useMcpConnectivityStatus`):
+ * `2 MCP servers failed · /mcp` and `1 MCP server needs auth · /mcp`, with each
+ * server's error left to /mcp. Printing every server's raw error ("fetch
+ * failed" per remote server when offline) buried the prompt.
+ */
+export function mcpStartupNotices(failedServers: number, needsAuth: number): string[] {
+	const out: string[] = [];
+	if (failedServers > 0) out.push(`${countNoun(failedServers, "MCP server")} failed · /mcp`);
+	if (needsAuth > 0) out.push(`${countNoun(needsAuth, "MCP server")} ${needsAuth === 1 ? "needs" : "need"} auth · /mcp`);
+	return out;
+}