gsd-pi 2.77.0-dev.538325aea → 2.77.0-dev.58d3d4d6c

package/packages/pi-coding-agent/src/core/compaction/utils.ts

@@ -3,8 +3,14 @@
  */
 
 import type { AgentMessage } from "@gsd/pi-agent-core";
-import type { Message } from "@gsd/pi-ai";
+import type { AssistantMessage, Message } from "@gsd/pi-ai";
 import { TOOL_RESULT_MAX_CHARS } from "../constants.js";
+
+// Head/tail split for head+tail truncation. Keeps first half + last half up to
+// TOOL_RESULT_MAX_CHARS total. Tool results and other large blocks put their
+// information-dense content (exit codes, verdicts, commit hashes, pass/fail
+// counts) at the tail — pure head-slicing discards that signal. See issue #4665.
+const HEAD_TAIL_HALF = Math.floor(TOOL_RESULT_MAX_CHARS / 2);
 import {
 	createBranchSummaryMessage,
 	createCompactionSummaryMessage,
@@ -189,13 +195,20 @@ export function createSummarizationMessage(promptText: string): [{ role: "user";
 // TOOL_RESULT_MAX_CHARS imported from ../constants.js
 
 /**
- * Truncate text to a maximum character length for summarization.
- * Keeps the beginning and appends a truncation marker.
+ * Truncate text to a maximum character length for summarization, keeping both
+ * the head AND the tail. The tail is where information density lives for tool
+ * output (exit codes, verdicts, pass/fail counts, commit hashes), so pure
+ * head-slicing produced degenerate summaries (see issue #4665).
+ *
+ * Exported for test access only.
  */
-function truncateForSummary(text: string, maxChars: number): string {
+export function truncateForSummary(text: string, maxChars: number): string {
 	if (text.length <= maxChars) return text;
-	const truncatedChars = text.length - maxChars;
-	return `${text.slice(0, maxChars)}\n\n[... ${truncatedChars} more characters truncated]`;
+	const half = Math.floor(maxChars / 2);
+	const head = text.slice(0, half);
+	const tail = text.slice(text.length - half);
+	const truncatedChars = text.length - (head.length + tail.length);
+	return `${head}\n\n[... ${truncatedChars} more characters truncated ...]\n\n${tail}`;
 }
 
 /**
@@ -203,11 +216,15 @@ function truncateForSummary(text: string, maxChars: number): string {
  * This prevents the model from treating it as a conversation to continue.
  * Call convertToLlm() first to handle custom message types.
  *
- * Tool results are truncated to keep the summarization request within
- * reasonable token budgets. Full content is not needed for summarization.
+ * Every content block with a character count above TOOL_RESULT_MAX_CHARS is
+ * head+tail truncated. The issue #4665 fix broadened this from tool-results-
+ * only to every block type — large user pastes, assistant thinking, tool-call
+ * args, and bashExecution-derived blocks also bloat summarization input if
+ * uncapped.
  */
 export function serializeConversation(messages: Message[]): string {
 	const parts: string[] = [];
+	const cap = TOOL_RESULT_MAX_CHARS;
 
 	for (const msg of messages) {
 		if (msg.role === "user") {
@@ -218,7 +235,7 @@ export function serializeConversation(messages: Message[]): string {
 							.filter((c): c is { type: "text"; text: string } => c.type === "text")
 							.map((c) => c.text)
 							.join("");
-			if (content) parts.push(`**User said:** ${content}`);
+			if (content) parts.push(`**User said:** ${truncateForSummary(content, cap)}`);
 		} else if (msg.role === "assistant") {
 			const textParts: string[] = [];
 			const thinkingParts: string[] = [];
@@ -239,13 +256,13 @@ export function serializeConversation(messages: Message[]): string {
 			}
 
 			if (thinkingParts.length > 0) {
-				parts.push(`**Assistant thinking:** ${thinkingParts.join("\n")}`);
+				parts.push(`**Assistant thinking:** ${truncateForSummary(thinkingParts.join("\n"), cap)}`);
 			}
 			if (textParts.length > 0) {
-				parts.push(`**Assistant responded:** ${textParts.join("\n")}`);
+				parts.push(`**Assistant responded:** ${truncateForSummary(textParts.join("\n"), cap)}`);
 			}
 			if (toolCalls.length > 0) {
-				parts.push(`**Assistant tool calls:** ${toolCalls.join("; ")}`);
+				parts.push(`**Assistant tool calls:** ${truncateForSummary(toolCalls.join("; "), cap)}`);
 			}
 		} else if (msg.role === "toolResult") {
 			const content = msg.content
@@ -253,7 +270,7 @@ export function serializeConversation(messages: Message[]): string {
 				.map((c) => c.text)
 				.join("");
 			if (content) {
-				parts.push(`**Tool result:** ${truncateForSummary(content, TOOL_RESULT_MAX_CHARS)}`);
+				parts.push(`**Tool result:** ${truncateForSummary(content, cap)}`);
 			}
 		}
 	}
@@ -261,6 +278,87 @@ export function serializeConversation(messages: Message[]): string {
 	return parts.join("\n\n");
 }
 
+// ============================================================================
+// Token estimation for post-serialization size
+// ============================================================================
+
+/**
+ * Estimate tokens for a message AFTER the summarization serializer will have
+ * capped its large content blocks. Use this when deciding chunk sizes for
+ * summarization — NOT when deciding whether to compact in the first place
+ * (that needs the real in-memory content size via `estimateTokens`).
+ *
+ * See issue #4665: the old chunker used real content size but the serializer
+ * truncated tool results to 2000 chars, so a single 400K-char tool result
+ * looked like 100K tokens (triggering tens of unnecessary chunks) but actually
+ * serialized to ~600 tokens.
+ *
+ * Colocated with `truncateForSummary` / `serializeConversation` so the two
+ * stay in sync — if the serialization cap changes, both functions pick it up
+ * from `TOOL_RESULT_MAX_CHARS`.
+ */
+export function estimateSerializedTokens(message: AgentMessage): number {
+	const cap = TOOL_RESULT_MAX_CHARS;
+	const capLen = (len: number) => Math.min(len, cap);
+	let chars = 0;
+
+	switch (message.role) {
+		case "user": {
+			const content = (message as { content: string | Array<{ type: string; text?: string }> }).content;
+			if (typeof content === "string") {
+				chars = capLen(content.length);
+			} else if (Array.isArray(content)) {
+				let total = 0;
+				for (const block of content) {
+					if (block.type === "text" && block.text) total += block.text.length;
+				}
+				chars = capLen(total);
+			}
+			return Math.ceil(chars / 4);
+		}
+		case "assistant": {
+			const assistant = message as AssistantMessage;
+			let textLen = 0;
+			let thinkingLen = 0;
+			let toolCallsLen = 0;
+			for (const block of assistant.content) {
+				if (block.type === "text") textLen += block.text.length;
+				else if (block.type === "thinking") thinkingLen += block.thinking.length;
+				else if (block.type === "toolCall") toolCallsLen += block.name.length + JSON.stringify(block.arguments).length;
+			}
+			chars = capLen(textLen) + capLen(thinkingLen) + capLen(toolCallsLen);
+			return Math.ceil(chars / 4);
+		}
+		case "custom":
+		case "toolResult": {
+			if (typeof message.content === "string") {
+				chars = capLen(message.content.length);
+			} else {
+				let textLen = 0;
+				let imageChars = 0;
+				for (const block of message.content) {
+					if (block.type === "text" && block.text) textLen += block.text.length;
+					if (block.type === "image") imageChars += 4800;
+				}
+				chars = capLen(textLen) + imageChars;
+			}
+			return Math.ceil(chars / 4);
+		}
+		case "bashExecution": {
+			chars = capLen(message.command.length + message.output.length);
+			return Math.ceil(chars / 4);
+		}
+		case "branchSummary":
+		case "compactionSummary": {
+			// Summary messages are already concise; don't truncate them.
+			chars = message.summary.length;
+			return Math.ceil(chars / 4);
+		}
+	}
+
+	return 0;
+}
+
 // ============================================================================
 // Summarization System Prompt
 // ============================================================================

package/packages/pi-coding-agent/src/core/compaction-orchestrator.test.ts

@@ -0,0 +1,154 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, it, mock, type Mock } from "node:test";
+
+import type { Agent } from "@gsd/pi-agent-core";
+import type { Api, AssistantMessage, Model } from "@gsd/pi-ai";
+
+import { CompactionOrchestrator, type CompactionOrchestratorDeps } from "./compaction-orchestrator.js";
+import { SessionManager } from "./session-manager.js";
+
+function createMockModel(): Model<Api> {
+	return {
+		id: "claude-opus-4-6",
+		name: "Claude Opus 4.6",
+		api: "anthropic-messages" as Api,
+		provider: "anthropic",
+		baseUrl: "https://api.anthropic.com",
+		reasoning: false,
+		input: ["text"],
+		cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+		contextWindow: 200_000,
+		maxTokens: 16_384,
+	} as Model<Api>;
+}
+
+function createAssistantMessage(
+	stopReason: AssistantMessage["stopReason"],
+	contentText: string,
+): AssistantMessage {
+	return {
+		role: "assistant",
+		content: [{ type: "text", text: contentText }],
+		api: "anthropic-messages",
+		provider: "anthropic",
+		model: "claude-opus-4-6",
+		usage: {
+			input: 100,
+			output: 100,
+			cacheRead: 0,
+			cacheWrite: 0,
+			totalTokens: 200,
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+		},
+		stopReason,
+		timestamp: Date.now(),
+		errorMessage: stopReason === "error" ? contentText : undefined,
+	} as AssistantMessage;
+}
+
+function wait(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function createHarness(overrides?: {
+	cancelResult?: boolean;
+	willRetry?: boolean;
+	hasQueuedMessages?: boolean;
+}) {
+	const dir = mkdtempSync(join(tmpdir(), "compaction-orchestrator-test-"));
+	const sessionManager = SessionManager.create(dir, dir);
+	sessionManager.appendMessage({ role: "user", content: "First user message" } as any);
+	sessionManager.appendMessage(createAssistantMessage("stop", "First assistant message"));
+	sessionManager.appendMessage({ role: "user", content: "Second user message" } as any);
+
+	const emittedEvents: Array<Record<string, unknown>> = [];
+	const continueFn = mock.fn(async () => {});
+	const replaceMessages = mock.fn((nextMessages: unknown[]) => {
+		(agent.state.messages as unknown[]) = nextMessages;
+	});
+	const agent = {
+		state: {
+			messages: [
+				{ role: "user", content: "queued follow-up" },
+				createAssistantMessage("error", "context overflow"),
+			],
+		},
+		continue: continueFn,
+		replaceMessages,
+		hasQueuedMessages: () => overrides?.hasQueuedMessages ?? false,
+	} as unknown as Agent;
+
+	const extensionRunner = {
+		hasHandlers: mock.fn(() => true),
+		emit: mock.fn(async () => ({ cancel: overrides?.cancelResult ?? true })),
+	};
+
+	const deps: CompactionOrchestratorDeps = {
+		agent,
+		sessionManager,
+		settingsManager: {
+			getCompactionSettings: () => ({
+				enabled: true,
+				reserveTokens: 16_384,
+				keepRecentTokens: 1,
+			}),
+		} as any,
+		modelRegistry: {
+			isProviderRequestReady: () => true,
+			getApiKey: async () => undefined,
+		} as any,
+		getModel: () => createMockModel(),
+		getSessionId: () => "test-session",
+		getExtensionRunner: () => extensionRunner as any,
+		emit: (event) => emittedEvents.push(event as unknown as Record<string, unknown>),
+		disconnectFromAgent: () => {},
+		reconnectToAgent: () => {},
+		abort: async () => {},
+	};
+
+	return {
+		dir,
+		agent,
+		continueFn,
+		replaceMessages,
+		emittedEvents,
+		extensionRunner,
+		orchestrator: new CompactionOrchestrator(deps),
+		cleanup: () => rmSync(dir, { recursive: true, force: true }),
+	};
+}
+
+describe("CompactionOrchestrator", () => {
+	it("overflow cancel keeps retry intent and resumes the agent (#3971)", async (t) => {
+		const harness = createHarness({ willRetry: true });
+		t.after(harness.cleanup);
+
+		await (harness.orchestrator as any)._runAutoCompaction("overflow", true);
+		await wait(150);
+
+		const endEvent = harness.emittedEvents.find((event) => event.type === "auto_compaction_end");
+		assert.ok(endEvent, "should emit auto_compaction_end");
+		assert.equal(endEvent?.aborted, true, "cancelled compaction should be marked aborted");
+		assert.equal(endEvent?.willRetry, true, "overflow cancel should preserve retry intent");
+		assert.equal(harness.continueFn.mock.callCount(), 1, "overflow cancel should resume the agent");
+		assert.equal(harness.replaceMessages.mock.callCount(), 1, "retry follow-up should trim the error message when present");
+	});
+
+	it("threshold cancel stays non-retrying when no queued messages exist", async (t) => {
+		const harness = createHarness({ willRetry: false, hasQueuedMessages: false });
+		t.after(harness.cleanup);
+
+		await (harness.orchestrator as any)._runAutoCompaction("threshold", false);
+		await wait(150);
+
+		const endEvent = harness.emittedEvents.find((event) => event.type === "auto_compaction_end");
+		assert.ok(endEvent, "should emit auto_compaction_end");
+		assert.equal(endEvent?.aborted, true, "cancelled compaction should be marked aborted");
+		assert.equal(endEvent?.willRetry, false, "threshold cancel should stay non-retrying");
+		assert.equal(harness.continueFn.mock.callCount(), 0, "threshold cancel should not resume the agent without queued work");
+		assert.equal(harness.replaceMessages.mock.callCount(), 0, "non-retry cancel should not trim messages");
+	});
+});

package/packages/pi-coding-agent/src/core/compaction-orchestrator.ts

@@ -14,6 +14,7 @@ import type { AssistantMessage, Model } from "@gsd/pi-ai";
 import { isContextOverflow } from "@gsd/pi-ai";
 import {
 	type CompactionResult,
+	CompactionProducedNoSummaryError,
 	calculateContextTokens,
 	compact,
 	estimateContextTokens,
@@ -332,8 +333,9 @@ export class CompactionOrchestrator {
 						type: "auto_compaction_end",
 						result: undefined,
 						aborted: true,
-						willRetry: false,
+						willRetry,
 					});
+					this._scheduleAutoCompactionFollowup(willRetry);
 					return;
 				}
 
@@ -391,24 +393,15 @@ export class CompactionOrchestrator {
 
 			const result: CompactionResult = { summary, firstKeptEntryId, tokensBefore, details };
 			this._deps.emit({ type: "auto_compaction_end", result, aborted: false, willRetry });
-
-			if (willRetry) {
-				const messages = this._deps.agent.state.messages;
-				const lastMsg = messages[messages.length - 1];
-				if (lastMsg?.role === "assistant" && (lastMsg as AssistantMessage).stopReason === "error") {
-					this._deps.agent.replaceMessages(messages.slice(0, -1));
-				}
-
-				setTimeout(() => {
-					this._deps.agent.continue().catch(() => {});
-				}, 100);
-			} else if (this._deps.agent.hasQueuedMessages()) {
-				setTimeout(() => {
-					this._deps.agent.continue().catch(() => {});
-				}, 100);
-			}
+			this._scheduleAutoCompactionFollowup(willRetry);
 		} catch (error) {
-			const errorMessage = getErrorMessage(error);
+			// Distinguish the "no usable summary" failure (issue #4665) so the UI
+			// can surface a clearer message than a generic compaction failure.
+			// Either way we drop the would-be compaction entry rather than writing
+			// an empty string to the session history.
+			const errorMessage = error instanceof CompactionProducedNoSummaryError
+				? `Compaction produced no usable summary — session history preserved as-is. (${error.message})`
+				: getErrorMessage(error);
 			this._deps.emit({
 				type: "auto_compaction_end",
 				result: undefined,
@@ -423,4 +416,25 @@ export class CompactionOrchestrator {
 			this._autoCompactionAbortController = undefined;
 		}
 	}
+
+	private _scheduleAutoCompactionFollowup(willRetry: boolean): void {
+		if (willRetry) {
+			const messages = this._deps.agent.state.messages;
+			const lastMsg = messages[messages.length - 1];
+			if (lastMsg?.role === "assistant" && (lastMsg as AssistantMessage).stopReason === "error") {
+				this._deps.agent.replaceMessages(messages.slice(0, -1));
+			}
+
+			setTimeout(() => {
+				this._deps.agent.continue().catch(() => {});
+			}, 100);
+			return;
+		}
+
+		if (this._deps.agent.hasQueuedMessages()) {
+			setTimeout(() => {
+				this._deps.agent.continue().catch(() => {});
+			}, 100);
+		}
+	}
 }

package/packages/pi-coding-agent/src/core/compaction-utils.test.ts

@@ -3,7 +3,7 @@ import test from "node:test";
 
 import type { Message } from "@gsd/pi-ai";
 
-import { serializeConversation } from "./compaction/index.js";
+import { serializeConversation, truncateForSummary } from "./compaction/index.js";
 
 test("serializeConversation uses narrative role markers instead of chat-style delimiters (#4054)", () => {
 	const messages: Message[] = [
@@ -48,3 +48,70 @@ test("serializeConversation uses narrative role markers instead of chat-style de
 	assert.ok(!serialized.includes("[Assistant]:"), "chat-style [Assistant]: markers should not remain");
 	assert.ok(!serialized.includes("[Tool result]:"), "chat-style [Tool result]: markers should not remain");
 });
+
+// ---------------------------------------------------------------------------
+// #4665 regression: head+tail truncation keeps verdicts/results
+// ---------------------------------------------------------------------------
+
+test("(#4665) truncateForSummary keeps both head AND tail — tail carries result/verdict text", () => {
+	// Construct a 10K-char fixture where the HEAD is "setup noise" and the TAIL
+	// contains a result line. The old head-only truncation would drop the tail
+	// and lose the result. The fix preserves both.
+	const head = "setup log line A\n".repeat(500); // ~8500 chars of setup
+	const tail = "RESULT: 258 passed, 0 failed. exit_code=0 commit=abc1234";
+	const input = head + tail;
+
+	const out = truncateForSummary(input, 2_000);
+
+	assert.ok(out.length < input.length, "must truncate when over cap");
+	assert.ok(out.includes("setup log line A"), "head content preserved");
+	assert.ok(out.includes("RESULT: 258 passed"), "tail content preserved (issue #4665)");
+	assert.match(out, /more characters truncated/, "emits an elision marker");
+});
+
+test("(#4665) truncateForSummary is a no-op when input is within the cap", () => {
+	const input = "short enough";
+	assert.equal(truncateForSummary(input, 2_000), input);
+});
+
+test("(#4665) serializeConversation caps large user content, not just tool results", () => {
+	// Pre-fix, only toolResult blocks were capped. A large user paste could
+	// still blow out the chunker's token math and the LLM's input budget.
+	const hugeUserText = "U".repeat(100_000);
+	const hugeAssistantText = "A".repeat(100_000);
+	const hugeToolResult = "T".repeat(100_000);
+
+	const messages: Message[] = [
+		{ role: "user", content: hugeUserText } as Message,
+		{
+			role: "assistant",
+			content: [{ type: "text", text: hugeAssistantText }],
+			api: "anthropic-messages",
+			provider: "anthropic",
+			model: "claude-sonnet-4-6",
+			usage: {
+				input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0,
+				cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+			},
+			stopReason: "stop",
+			timestamp: Date.now(),
+		} as Message,
+		{
+			role: "toolResult",
+			content: [{ type: "text", text: hugeToolResult }],
+			toolName: "Bash",
+			toolCallId: "tool-huge",
+		} as Message,
+	];
+
+	const serialized = serializeConversation(messages);
+
+	// Each block is truncated independently to TOOL_RESULT_MAX_CHARS plus the
+	// framing marker, so the serialized output should be a tiny fraction of
+	// the raw 300K chars of content.
+	assert.ok(
+		serialized.length < 10_000,
+		`serialized output should be small after capping all blocks, got ${serialized.length} chars`,
+	);
+	assert.match(serialized, /more characters truncated/, "truncation marker present");
+});

package/packages/pi-coding-agent/src/core/discovery-cache.test.ts

@@ -8,6 +8,12 @@ import { ModelDiscoveryCache } from "./discovery-cache.js";
 let testDir: string;
 let cachePath: string;
 
+function markEntryStale(cache: ModelDiscoveryCache, provider: string): void {
+	const entry = cache.get(provider);
+	assert.ok(entry, `expected cache entry for ${provider}`);
+	entry.fetchedAt = Date.now() - entry.ttlMs - 1;
+}
+
 beforeEach(() => {
 	testDir = join(tmpdir(), `discovery-cache-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
 	mkdirSync(testDir, { recursive: true });
@@ -92,12 +98,7 @@ describe("ModelDiscoveryCache — staleness", () => {
 	it("entries with expired TTL are stale", () => {
 		const cache = new ModelDiscoveryCache(cachePath);
 		cache.set("openai", [{ id: "gpt-4o" }], 1); // 1ms TTL
-
-		// Wait for TTL to expire
-		const start = Date.now();
-		while (Date.now() - start < 5) {
-			// busy wait
-		}
+		markEntryStale(cache, "openai");
 
 		assert.equal(cache.isStale("openai"), true);
 	});
@@ -110,12 +111,7 @@ describe("ModelDiscoveryCache — getAll", () => {
 		const cache = new ModelDiscoveryCache(cachePath);
 		cache.set("openai", [{ id: "gpt-4o" }]);
 		cache.set("stale", [{ id: "old" }], 1);
-
-		// Wait for stale TTL
-		const start = Date.now();
-		while (Date.now() - start < 5) {
-			// busy wait
-		}
+		markEntryStale(cache, "stale");
 
 		const all = cache.getAll();
 		assert.ok(all.has("openai"));
@@ -126,12 +122,7 @@ describe("ModelDiscoveryCache — getAll", () => {
 		const cache = new ModelDiscoveryCache(cachePath);
 		cache.set("openai", [{ id: "gpt-4o" }]);
 		cache.set("stale", [{ id: "old" }], 1);
-
-		// Wait for stale TTL
-		const start = Date.now();
-		while (Date.now() - start < 5) {
-			// busy wait
-		}
+		markEntryStale(cache, "stale");
 
 		const all = cache.getAll(true);
 		assert.ok(all.has("openai"));

package/packages/pi-coding-agent/src/core/extensions/extension-discovery.ts

@@ -0,0 +1,119 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { readManifest, readManifestFromEntryPath } from './extension-registry.js'
+
+function isExtensionFile(name: string): boolean {
+  return name.endsWith('.ts') || name.endsWith('.js')
+}
+
+/**
+ * Resolves the entry-point file(s) for a single extension directory.
+ *
+ * 1. If the directory contains a package.json with a `pi` manifest object,
+ *    the manifest is authoritative:
+ *    - `pi.extensions` array → resolve each entry relative to the directory.
+ *    - `pi: {}` (no extensions) → return empty (library opt-out, e.g. cmux).
+ * 2. Only when no `pi` manifest exists does it fall back to `index.ts` → `index.js`.
+ */
+export function resolveExtensionEntries(dir: string): string[] {
+  const packageJsonPath = join(dir, 'package.json')
+  if (existsSync(packageJsonPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'))
+      if (pkg?.pi && typeof pkg.pi === 'object') {
+        // When a pi manifest exists, it is authoritative — don't fall through
+        // to index.ts/index.js auto-detection. This allows library directories
+        // (like cmux) to opt out by declaring "pi": {} with no extensions.
+        const declared = pkg.pi.extensions
+        if (!Array.isArray(declared) || declared.length === 0) {
+          return []
+        }
+        return declared
+          .filter((entry: unknown): entry is string => typeof entry === 'string')
+          .map((entry: string) => resolve(dir, entry))
+          .filter((entry: string) => existsSync(entry))
+      }
+    } catch {
+      // Ignore malformed manifests and fall back to index.ts/index.js discovery.
+    }
+  }
+
+  const indexTs = join(dir, 'index.ts')
+  if (existsSync(indexTs)) {
+    return [indexTs]
+  }
+
+  const indexJs = join(dir, 'index.js')
+  if (existsSync(indexJs)) {
+    return [indexJs]
+  }
+
+  return []
+}
+
+/**
+ * Discovers all extension entry-point paths under an extensions directory.
+ *
+ * - Top-level .ts/.js files are treated as standalone extension entry points.
+ * - Subdirectories are resolved via `resolveExtensionEntries()` (package.json →
+ *   pi.extensions, then index.ts/index.js fallback).
+ */
+export function discoverExtensionEntryPaths(extensionsDir: string): string[] {
+  if (!existsSync(extensionsDir)) {
+    return []
+  }
+
+  const discovered: string[] = []
+  for (const entry of readdirSync(extensionsDir, { withFileTypes: true })) {
+    const entryPath = join(extensionsDir, entry.name)
+
+    if ((entry.isFile() || entry.isSymbolicLink()) && isExtensionFile(entry.name)) {
+      discovered.push(entryPath)
+      continue
+    }
+
+    if (entry.isDirectory() || entry.isSymbolicLink()) {
+      discovered.push(...resolveExtensionEntries(entryPath))
+    }
+  }
+
+  return discovered
+}
+
+/**
+ * Merge bundled and installed extension entry paths.
+ * Installed extensions with the same manifest ID as a bundled extension take precedence (D-14).
+ * Loader stays dumb — receives a pre-merged path list (D-15).
+ */
+export function mergeExtensionEntryPaths(bundledPaths: string[], installedExtDir: string): string[] {
+  if (!existsSync(installedExtDir)) return bundledPaths
+
+  // Build map: manifest ID → entry paths for installed extensions
+  const installedById = new Map<string, string[]>()
+  for (const entry of readdirSync(installedExtDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue
+    const dir = join(installedExtDir, entry.name)
+    const manifest = readManifest(dir)
+    const entries = resolveExtensionEntries(dir)
+    if (manifest && entries.length > 0) {
+      installedById.set(manifest.id, entries)
+    }
+  }
+
+  if (installedById.size === 0) return bundledPaths
+
+  // Filter bundled paths: skip any whose manifest id is shadowed by installed
+  const merged: string[] = []
+  for (const entryPath of bundledPaths) {
+    const manifest = readManifestFromEntryPath(entryPath)
+    if (manifest && installedById.has(manifest.id)) continue // shadowed by installed
+    merged.push(entryPath)
+  }
+
+  // Append all installed entries
+  for (const entries of installedById.values()) {
+    merged.push(...entries)
+  }
+
+  return merged
+}