@oh-my-pi/pi-coding-agent 16.2.4 → 16.2.5

package/src/session/agent-session.ts

@@ -534,6 +534,13 @@ export interface AgentSessionConfig {
 	 * inherits this so its requests undergo the same shaping as the main turn.
 	 */
 	transformProviderContext?: (context: Context, model: Model) => Context | Promise<Context>;
+	/**
+	 * Stream wrapper passed to side-channel requests (`/btw`, `/omfg`, IRC
+	 * auto-replies, and handoff generation) so they apply the same provider
+	 * shaping and host-level request wrappers as normal agent turns. Defaults
+	 * to plain `streamSimple` when omitted.
+	 */
+	sideStreamFn?: StreamFn;
 	/**
 	 * Stream wrapper passed to the advisor agent so its requests apply the
 	 * session's `providers.openrouterVariant`, `providers.antigravityEndpoint`,
@@ -1459,6 +1466,7 @@ export class AgentSession {
 	#onResponse: SimpleStreamOptions["onResponse"] | undefined;
 	#onSseEvent: SimpleStreamOptions["onSseEvent"] | undefined;
 	#transformProviderContext: ((context: Context, model: Model) => Context | Promise<Context>) | undefined;
+	#sideStreamFn: StreamFn;
 	#advisorStreamFn: StreamFn | undefined;
 	#convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
 	#rebuildSystemPrompt:
@@ -1788,6 +1796,7 @@ export class AgentSession {
 		this.#requestedToolNames = config.requestedToolNames;
 		this.#transformContext = config.transformContext ?? (messages => messages);
 		this.#transformProviderContext = config.transformProviderContext;
+		this.#sideStreamFn = config.sideStreamFn ?? streamSimple;
 		this.#advisorStreamFn = config.advisorStreamFn;
 		this.#onPayload = config.onPayload;
 		this.rawSseDebugBuffer = config.rawSseDebugBuffer ?? new RawSseDebugBuffer();
@@ -9195,6 +9204,10 @@ export class AgentSession {
 				model,
 				{
 					streamOptions: handoffStreamOptions,
+					completeImpl: async (requestModel, requestContext, requestOptions) => {
+						const stream = await this.#sideStreamFn(requestModel, requestContext, requestOptions);
+						return stream.result();
+					},
 					telemetry: resolveTelemetry(this.agent.telemetry, this.sessionId),
 					// Honor the user's /model thinking selection on the handoff path.
 					// Clamped per-model inside generateHandoffFromContext via
@@ -9482,16 +9495,18 @@ export class AgentSession {
 		const errorIsFromBeforeCompaction =
 			compactionEntry !== null && assistantMessage.timestamp < new Date(compactionEntry.timestamp).getTime();
 		if (sameModel && !errorIsFromBeforeCompaction && AIError.isContextOverflow(assistantMessage, contextWindow)) {
-			// Remove the error message from agent state (it IS saved to session for history,
-			// but we don't want it in context for the retry)
-			const messages = this.agent.state.messages;
-			if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
-				this.agent.replaceMessages(messages.slice(0, -1));
-			}
+			// Clear the failed turn from active context so the retry (or the next
+			// user prompt) does not replay it. The persisted branch entry stays
+			// for now: when no recovery path runs, the user-facing transcript
+			// MUST keep the only assistant message explaining why the turn
+			// stopped. The branch entry is dropped further down, but only on the
+			// paths that actually schedule a retry/compaction.
+			this.#removeAssistantMessageFromActiveContext(assistantMessage);
 
 			// Try context promotion first - switch to a larger model and retry without compacting
 			const promoted = await this.#tryContextPromotion(assistantMessage);
 			if (promoted) {
+				await this.#dropPersistedAssistantTurn(assistantMessage);
 				// Retry on the promoted (larger) model without compacting
 				this.#scheduleAgentContinue({ delayMs: 100, generation });
 				return COMPACTION_CHECK_CONTINUATION;
@@ -9500,7 +9515,9 @@ export class AgentSession {
 			// No promotion target available fall through to compaction
 			const compactionSettings = this.settings.getGroup("compaction");
 			if (compactionSettings.enabled && compactionSettings.strategy !== "off") {
-				return await this.#runAutoCompaction("overflow", true, false, allowDefer, { autoContinue });
+				return await this.#runRecoveryCompactionWithRollback("overflow", assistantMessage, allowDefer, {
+					autoContinue,
+				});
 			}
 			return COMPACTION_CHECK_NONE;
 		}
@@ -9512,13 +9529,14 @@ export class AgentSession {
 		// otherwise compaction/handoff. Unlike overflow, the *input* is fine, so we
 		// allow the handoff strategy to actually run.
 		if (sameModel && !errorIsFromBeforeCompaction && assistantMessage.stopReason === "length") {
-			const messages = this.agent.state.messages;
-			if (messages.length > 0 && messages[messages.length - 1].role === "assistant") {
-				this.agent.replaceMessages(messages.slice(0, -1));
-			}
+			// Same active-context vs persisted-history split as the overflow path
+			// above: clear the dead turn from agent state so it cannot be replayed,
+			// but keep it on the branch unless promotion or compaction actually runs.
+			this.#removeAssistantMessageFromActiveContext(assistantMessage);
 
 			const promoted = await this.#tryContextPromotion(assistantMessage);
 			if (promoted) {
+				await this.#dropPersistedAssistantTurn(assistantMessage);
 				logger.debug("Context promotion triggered by response.incomplete (length stop)", {
 					from: `${assistantMessage.provider}/${assistantMessage.model}`,
 				});
@@ -9532,7 +9550,7 @@ export class AgentSession {
 					model: `${assistantMessage.provider}/${assistantMessage.model}`,
 					strategy: incompleteCompactionSettings.strategy,
 				});
-				return await this.#runAutoCompaction("incomplete", true, false, allowDefer, {
+				return await this.#runRecoveryCompactionWithRollback("incomplete", assistantMessage, allowDefer, {
 					autoContinue,
 					triggerContextTokens: calculateContextTokens(assistantMessage.usage),
 				});
@@ -9797,6 +9815,54 @@ export class AgentSession {
 		}
 	}
 
+	/**
+	 * Drop a recoverable assistant turn from the persisted session branch once a
+	 * recovery path (context promotion or compaction) is committed. Waits for the
+	 * in-flight `message_end` persistence slot first so the branch entry exists
+	 * before we reparent past it. Active context removal is the caller's
+	 * responsibility — recovery paths clear it eagerly so the retry never
+	 * replays the failed turn, while no-recovery paths leave the persisted entry
+	 * (and the user-visible transcript line) in place.
+	 */
+	async #dropPersistedAssistantTurn(assistantMessage: AssistantMessage): Promise<void> {
+		await this.#waitForSessionMessagePersistence(assistantMessage);
+		this.#discardAssistantTurn(assistantMessage);
+	}
+
+	/**
+	 * Drop the failed assistant turn from persisted history, run
+	 * {@link #runAutoCompaction} for an `overflow` / `incomplete` recovery, and
+	 * restore the assistant entry if compaction did not actually commit
+	 * anything (no usable model/preparation, hook cancel, or compaction error).
+	 *
+	 * Compaction has to see a clean branch — otherwise its `prepareCompaction`
+	 * pass would keep the failed turn in the kept region and the retry would
+	 * replay it. But a NONE return that was not paired with a fresh compaction
+	 * summary means no recovery is in progress, and leaving the branch
+	 * reparented would erase the only user-visible explanation for why the turn
+	 * stopped. Reverting the drop in that case preserves the transcript while
+	 * still letting a real recovery path own the rewrite.
+	 */
+	async #runRecoveryCompactionWithRollback(
+		reason: "overflow" | "incomplete",
+		assistantMessage: AssistantMessage,
+		allowDefer: boolean,
+		options: { autoContinue: boolean; triggerContextTokens?: number },
+	): Promise<CompactionCheckResult> {
+		const compactionEntryBefore = getLatestCompactionEntry(this.sessionManager.getBranch());
+		await this.#dropPersistedAssistantTurn(assistantMessage);
+		const result = await this.#runAutoCompaction(reason, true, false, allowDefer, options);
+		const recoveryCommitted =
+			result.continuationScheduled || result.deferredHandoff || result.automaticContinuationBlocked === true;
+		if (!recoveryCommitted) {
+			const compactionEntryAfter = getLatestCompactionEntry(this.sessionManager.getBranch());
+			if (compactionEntryAfter === compactionEntryBefore) {
+				this.sessionManager.appendMessage(assistantMessage);
+			}
+		}
+		return result;
+	}
+
 	/**
 	 * Drop an assistant turn from BOTH the live agent context and the persisted
 	 * session branch (reparenting the leaf to the turn's parent), so a discarded
@@ -10694,6 +10760,18 @@ export class AgentSession {
 						tools: this.agent.state.tools,
 						sessionId: this.sessionId,
 						promptCacheKey: this.sessionId,
+						// Route every summarization HTTP request through the
+						// session's side-stream transport so the provider
+						// concurrency cap (e.g. providers.ollama-cloud.maxConcurrency)
+						// brackets compaction the same way it brackets the live
+						// agent turn — without this, multiple ollama-cloud
+						// subagents auto/manually compacting issued uncapped
+						// summary requests in parallel (chatgpt-codex review on
+						// #3751).
+						completeImpl: async (requestModel, requestContext, requestOptions) => {
+							const stream = await this.#sideStreamFn(requestModel, requestContext, requestOptions);
+							return stream.result();
+						},
 					},
 				);
 			} catch (error) {
@@ -12904,7 +12982,7 @@ export class AgentSession {
 		let providerReplyText = "";
 		let emittedReplyText = "";
 		let assistantMessage: AssistantMessage | undefined;
-		const stream = streamSimple(model, obfuscateProviderContext(this.#obfuscator, context), options);
+		const stream = await this.#sideStreamFn(model, obfuscateProviderContext(this.#obfuscator, context), options);
 		for await (const event of stream) {
 			if (event.type === "text_delta") {
 				providerReplyText += event.delta;
@@ -13522,6 +13600,12 @@ export class AgentSession {
 				metadata: this.agent.metadataForProvider(model.provider),
 				convertToLlm: messages => this.#convertToLlmForSideRequest(messages),
 				telemetry: resolveTelemetry(this.agent.telemetry, this.sessionId),
+				// Same per-provider concurrency cap rationale as the compaction
+				// path above (chatgpt-codex review on #3751).
+				completeImpl: async (requestModel, requestContext, requestOptions) => {
+					const stream = await this.#sideStreamFn(requestModel, requestContext, requestOptions);
+					return stream.result();
+				},
 			});
 			this.#branchSummaryAbortController = undefined;
 			if (result.aborted) {

package/src/task/executor.ts

@@ -56,7 +56,6 @@ import { ToolAbortError } from "../tools/tool-errors";
 import type { EventBus } from "../utils/event-bus";
 import { buildNamedToolChoice } from "../utils/tool-choice";
 import type { WorkspaceTree } from "../workspace-tree";
-import { Semaphore } from "./parallel";
 import { subprocessToolRegistry } from "./subprocess-tool-registry";
 import {
 	type AgentDefinition,
@@ -199,51 +198,6 @@ function installSubagentRetryFallbackChain(args: {
 	return role;
 }
 
-const PROVIDER_MAX_CONCURRENCY_SETTINGS: Record<string, SettingPath> = {
-	"ollama-cloud": "providers.ollama-cloud.maxConcurrency",
-};
-
-interface ProviderSemaphoreEntry {
-	limit: number;
-	semaphore: Semaphore;
-}
-
-const providerSemaphores = new Map<string, ProviderSemaphoreEntry>();
-
-/**
- * Resolve the configured concurrency ceiling for a provider, or `undefined`
- * when the provider has no cap concept at all. A configured value `<= 0` means
- * "unlimited" and maps to `Infinity` — still a tracked ceiling, so every run
- * holds a slot and a later finite resize counts work started while unlimited.
- */
-function getProviderConcurrencyLimit(settings: Settings, provider: string): number | undefined {
-	const settingPath = PROVIDER_MAX_CONCURRENCY_SETTINGS[provider];
-	if (!settingPath) return undefined;
-	const raw = settings.get(settingPath);
-	const limit = Number.isFinite(raw) ? Math.trunc(raw) : 0;
-	return limit > 0 ? limit : Number.POSITIVE_INFINITY;
-}
-
-function getProviderSemaphore(settings: Settings, provider: string): Semaphore | undefined {
-	const limit = getProviderConcurrencyLimit(settings, provider);
-	if (limit === undefined) return undefined;
-	// Always hand out (and acquire on) the single shared limiter, even when
-	// unlimited (Infinity). Resizing it in place — rather than replacing it —
-	// keeps every in-flight slot counted, so a runtime or mixed limit change can
-	// never push concurrency past the cap (issue #3464 review feedback).
-	const existing = providerSemaphores.get(provider);
-	if (existing) {
-		if (existing.limit !== limit) {
-			existing.limit = limit;
-			existing.semaphore.resize(limit);
-		}
-		return existing.semaphore;
-	}
-	const semaphore = new Semaphore(limit);
-	providerSemaphores.set(provider, { limit, semaphore });
-	return semaphore;
-}
-
 function renderIrcPeerRoster(selfId: string): string {
 	const peers = AgentRegistry.global()
 		.list()
@@ -2028,8 +1982,6 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 		let sessionOpenedAt: number | undefined;
 		let sessionCreatedAt: number | undefined;
 		let readyAt: number | undefined;
-		let providerSemaphore: Semaphore | undefined;
-		let providerSemaphoreAcquired = false;
 
 		try {
 			checkAbort();
@@ -2098,13 +2050,6 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				? resolvedThinkingLevel
 				: (thinkingLevel ?? resolvedThinkingLevel);
 			resolvedAt = performance.now();
-			if (model) {
-				providerSemaphore = getProviderSemaphore(settings, model.provider);
-				if (providerSemaphore) {
-					await providerSemaphore.acquire(abortSignal);
-					providerSemaphoreAcquired = true;
-				}
-			}
 
 			const effectiveCwd = worktree ?? cwd;
 			const sessionManager = sessionFile
@@ -2395,10 +2340,6 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				}
 				if (exitCode === 0) exitCode = 1;
 			}
-			if (providerSemaphoreAcquired) {
-				providerSemaphore?.release();
-				providerSemaphoreAcquired = false;
-			}
 			sessionAbortController.abort();
 			try {
 				await untilAborted(AbortSignal.timeout(5000), () => monitor.waitForActiveSessionAbort());
@@ -2429,9 +2370,10 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 		}
 
 		// Launch-latency breakdown (subagent invocation → first chat dispatch).
-		// Phase deltas are performance.now() spans; the semaphore brackets use the
-		// Date.now epochs captured by the spawn site (invokedAt before acquire,
-		// acquiredAt after) so queue wait and pre-run setup are reported apart.
+		// Phase deltas are performance.now() spans; the task-tool concurrency
+		// brackets use the Date.now epochs captured by the spawn site
+		// (invokedAt before acquire, acquiredAt after) so queue wait and
+		// pre-run setup are reported apart.
 		const span = (from: number | undefined, to: number | undefined): number | undefined =>
 			from !== undefined && to !== undefined ? Math.round(to - from) : undefined;
 		const queueMs =

package/src/task/provider-concurrency.ts

@@ -0,0 +1,100 @@
+/**
+ * Per-provider LLM concurrency cap, applied around each provider HTTP request.
+ *
+ * The semaphore brackets only the streaming request itself, not the whole
+ * agent lifetime: a parent subagent releases its slot the moment its LLM
+ * stream finishes producing, so children spawned during tool execution can
+ * acquire slots for their own turns. Holding the slot across the parent's
+ * full conversation deadlocks any spawn tree whose width exceeds
+ * `maxConcurrency` because the parents wait for children that wait for
+ * slots the parents are holding (issue
+ * [#3749](https://github.com/can1357/oh-my-pi/issues/3749)).
+ */
+
+import type { StreamFn } from "@oh-my-pi/pi-agent-core";
+import type { Settings } from "../config/settings";
+import type { SettingPath } from "../config/settings-schema";
+import { Semaphore } from "./parallel";
+
+const PROVIDER_MAX_CONCURRENCY_SETTINGS: Record<string, SettingPath> = {
+	"ollama-cloud": "providers.ollama-cloud.maxConcurrency",
+};
+
+interface ProviderSemaphoreEntry {
+	limit: number;
+	semaphore: Semaphore;
+}
+
+const providerSemaphores = new Map<string, ProviderSemaphoreEntry>();
+
+/**
+ * Resolve the configured concurrency ceiling for a provider, or `undefined`
+ * when the provider has no cap concept at all. A configured value `<= 0` means
+ * "unlimited" and maps to `Infinity` — still a tracked ceiling, so every run
+ * holds a slot and a later finite resize counts work started while unlimited.
+ */
+export function getProviderConcurrencyLimit(settings: Settings, provider: string): number | undefined {
+	const settingPath = PROVIDER_MAX_CONCURRENCY_SETTINGS[provider];
+	if (!settingPath) return undefined;
+	const raw = settings.get(settingPath);
+	const limit = Number.isFinite(raw) ? Math.trunc(raw) : 0;
+	return limit > 0 ? limit : Number.POSITIVE_INFINITY;
+}
+
+/**
+ * Hand out the single shared limiter for `provider` (creating one lazily) and
+ * resize it in place when the configured limit changes. Replacing the
+ * semaphore would orphan in-flight slots on the old instance and let a
+ * runtime or mixed limit value exceed the cap (issue #3464 review feedback).
+ */
+export function getProviderSemaphore(settings: Settings, provider: string): Semaphore | undefined {
+	const limit = getProviderConcurrencyLimit(settings, provider);
+	if (limit === undefined) return undefined;
+	const existing = providerSemaphores.get(provider);
+	if (existing) {
+		if (existing.limit !== limit) {
+			existing.limit = limit;
+			existing.semaphore.resize(limit);
+		}
+		return existing.semaphore;
+	}
+	const semaphore = new Semaphore(limit);
+	providerSemaphores.set(provider, { limit, semaphore });
+	return semaphore;
+}
+
+/**
+ * Wrap a {@link StreamFn} so every LLM HTTP request acquires the provider's
+ * concurrency slot before the request goes out and releases it when the
+ * stream finishes producing (success, error, or abort). Providers without a
+ * configured cap pass straight through.
+ *
+ * The acquire bracket is intentionally narrow (one slot per LLM call), so
+ * spawn trees deeper than `maxConcurrency` no longer deadlock on themselves —
+ * see the module-level comment for the failure mode this fixes.
+ */
+export function wrapStreamFnWithProviderConcurrency(settings: Settings, base: StreamFn): StreamFn {
+	return async (model, context, options) => {
+		const semaphore = getProviderSemaphore(settings, model.provider);
+		if (!semaphore) return base(model, context, options);
+		await semaphore.acquire(options?.signal);
+		let released = false;
+		const release = () => {
+			if (released) return;
+			released = true;
+			semaphore.release();
+		};
+		try {
+			const stream = await base(model, context, options);
+			// EventStream.result() settles when the producer pushes 'done'/'error'
+			// or calls fail() — i.e. once the provider has finished producing.
+			// Releasing here keeps the slot held for the network request and
+			// nothing else.
+			stream.result().then(release, release);
+			return stream;
+		} catch (err) {
+			release();
+			throw err;
+		}
+	};
+}

package/src/task/worktree.ts

@@ -3,12 +3,16 @@ import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 import * as natives from "@oh-my-pi/pi-natives";
-import { getWorktreeDir, hashPath, logger, Snowflake } from "@oh-my-pi/pi-utils";
+import { getWorktreeDir, logger, Snowflake } from "@oh-my-pi/pi-utils";
 import * as git from "../utils/git";
 import * as jj from "../utils/jj";
 import { mapWithConcurrencyLimit } from "./parallel";
 
 const { IsoBackendKind } = natives;
+
+const TASK_ISOLATION_DIR_PREFIX = "t";
+const TASK_ISOLATION_DIR_DIGEST_CHARS = 9;
+const TASK_ISOLATION_MOUNT_DIR = "m";
 type IsoBackendKind = natives.IsoBackendKind;
 
 /** Baseline state for a single git repository. */
@@ -389,15 +393,20 @@ function errorMessage(err: unknown): string {
 	return err instanceof Error ? err.message : String(err);
 }
 
+function getTaskIsolationSegment(repoRoot: string, id: string): string {
+	const key = `${path.resolve(repoRoot)}\0${id}`;
+	const digest = Bun.hash(key).toString(16).padStart(16, "0").slice(-TASK_ISOLATION_DIR_DIGEST_CHARS);
+	return `${TASK_ISOLATION_DIR_PREFIX}${digest}`;
+}
+
 export async function ensureIsolation(
 	baseCwd: string,
 	id: string,
 	preferred?: IsoBackendKind,
 ): Promise<IsolationHandle> {
 	const repoRoot = await getRepoRoot(baseCwd);
-	const baseDir = getWorktreeDir(`${id}-${hashPath(repoRoot)}`);
-	const mergedDir = path.join(baseDir, "merged");
-
+	const baseDir = getWorktreeDir(getTaskIsolationSegment(repoRoot, id));
+	const mergedDir = path.join(baseDir, TASK_ISOLATION_MOUNT_DIR);
 	const resolution = natives.isoResolve(preferred ?? null);
 	const candidates = resolution.candidates.length > 0 ? resolution.candidates : [resolution.kind];
 	let fallbackReason = resolution.reason ?? null;

package/src/task/yield-assembly.ts

@@ -130,74 +130,62 @@ export function assembleYieldResult(
 	arrayLabels?: ReadonlySet<string>,
 ): AssembledYieldResult | undefined {
 	if (yieldItems.length === 0) return undefined;
+
+	// Terminal = the last non-incremental yield (untyped, or string-typed like
+	// `type: "result"`). Array-typed yields are incremental sections and never
+	// terminate on their own.
 	let terminalItem: YieldItem | undefined;
 	for (let index = yieldItems.length - 1; index >= 0; index--) {
 		const item = yieldItems[index];
-		if (!item) continue;
-		if (!isIncrementalYieldType(item.type)) {
+		if (item && !isIncrementalYieldType(item.type)) {
 			terminalItem = item;
 			break;
 		}
 	}
-	let hasTypedSections = false;
-	for (const item of yieldItems) {
-		if (getYieldLabels(item.type).length > 0) {
-			hasTypedSections = true;
-			break;
-		}
-	}
-	if (terminalItem && typeof terminalItem.type === "string" && terminalItem.data === undefined) {
-		const resolved = resolveYieldPayload(terminalItem, lastAssistantText, getYieldLabels(terminalItem.type));
-		return {
-			data: resolved.value,
-			schemaOverridden: terminalItem.schemaOverridden === true,
-			rawText: resolved.fromLastAssistantText && typeof resolved.value === "string",
-			missingData: resolved.missingData,
-		};
-	}
-	if (!hasTypedSections && terminalItem) {
-		const resolved = resolveYieldPayload(terminalItem, lastAssistantText, []);
-		return {
-			data: resolved.value,
-			schemaOverridden: terminalItem.schemaOverridden === true,
-			rawText: resolved.fromLastAssistantText && typeof resolved.value === "string",
-			missingData: resolved.missingData,
-		};
-	}
 
+	// Sections come ONLY from incremental (array-typed) yields. A string `type`
+	// is a terminal marker, never a section label: folding its data under the
+	// label is what nested a finalize payload (`type: "result"`, `data: {…}`) one
+	// level deep and made output-schema validation report every field missing.
 	const sections: Record<string, unknown> = {};
 	const sectionCounts = new Map<string, number>();
 	let schemaOverridden = false;
 	let missingData = false;
 	let hasSections = false;
-
 	for (const item of yieldItems) {
 		if (item.status === "aborted") continue;
+		if (!isIncrementalYieldType(item.type)) continue;
 		schemaOverridden ||= item.schemaOverridden === true;
 		const labels = getYieldLabels(item.type);
-		if (labels.length === 0) continue;
 		const resolved = resolveYieldPayload(item, lastAssistantText, labels);
 		missingData ||= resolved.missingData;
-		const incremental = isIncrementalYieldType(item.type);
 		for (const label of labels) {
-			appendYieldSection(
-				sections,
-				sectionCounts,
-				label,
-				resolved.value,
-				incremental && (arrayLabels?.has(label) ?? false),
-			);
+			appendYieldSection(sections, sectionCounts, label, resolved.value, arrayLabels?.has(label) ?? false);
 			hasSections = true;
 		}
-		if (!isIncrementalYieldType(item.type)) break;
 	}
 
+	// An explicit terminal payload wins: an untyped final result or a
+	// `type: "result"` finalize that carries `data` is the complete result, used
+	// verbatim — never wrapped in a section.
+	if (terminalItem && terminalItem.data !== undefined) {
+		const resolved = resolveYieldPayload(terminalItem, lastAssistantText, []);
+		return {
+			data: resolved.value,
+			schemaOverridden: terminalItem.schemaOverridden === true,
+			rawText: resolved.fromLastAssistantText && typeof resolved.value === "string",
+			missingData: resolved.missingData,
+		};
+	}
+
+	// A data-less terminal finalize keeps accumulated sections; only when none
+	// exist does the last assistant turn become the raw result.
 	if (hasSections) {
 		return { data: sections, schemaOverridden, rawText: false, missingData };
 	}
 
 	if (!terminalItem) return undefined;
-	const resolved = resolveYieldPayload(terminalItem, lastAssistantText, []);
+	const resolved = resolveYieldPayload(terminalItem, lastAssistantText, getYieldLabels(terminalItem.type));
 	return {
 		data: resolved.value,
 		schemaOverridden: terminalItem.schemaOverridden === true,

package/src/tools/read.ts

@@ -178,7 +178,17 @@ interface HashlineHeaderContext {
 }
 
 function formatReadHashlineHeader(displayPath: string, tag: string): string {
-	return formatHashlineHeader(path.basename(displayPath), tag);
+	// In-workspace reads collapse to the bare filename for brevity: the edit
+	// tool's snapshot-tag recovery rebinds a bare `[name#tag]` onto the in-tree
+	// file it uniquely names. Out-of-workspace reads can't lean on that —
+	// recovery refuses to redirect a write outside the cwd/sandbox
+	// (HashlineFilesystem.allowTagPathRecovery) — so an absolute displayPath
+	// must stay directly resolvable, otherwise the basename resolves against
+	// cwd, misses, and the edit fails with "File not found" (e.g. ~/.claude/*).
+	// `shortenPath` keeps `~/.claude/...` (round-trips through resolveToCwd's ~
+	// expansion) instead of leaking the full home path into the read output.
+	const anchor = path.isAbsolute(displayPath) ? shortenPath(displayPath) : path.basename(displayPath);
+	return formatHashlineHeader(anchor, tag);
 }
 
 function recordFullHashlineContext(

package/src/utils/git.ts

@@ -1712,6 +1712,19 @@ export const repo = {
 		return primaryRootFromRepositorySync(repository);
 	},
 
+	/**
+	 * Linked-worktree metadata for `cwd`, or `null` when `cwd` is the primary
+	 * checkout (or outside a repository). `root` is the worktree's own checkout
+	 * root; `primaryRoot` is the shared main checkout that names the project.
+	 * Resolves purely via on-disk `.git`/`commondir` walking — no subprocess —
+	 * so the status line may call it on every render.
+	 */
+	linkedWorktreeSync(cwd: string): { root: string; primaryRoot: string } | null {
+		const repository = resolveRepositorySync(cwd);
+		if (!repository || !isLinkedWorktree(repository)) return null;
+		return { root: repository.repoRoot, primaryRoot: primaryRootFromRepositorySync(repository) };
+	},
+
 	/** Full GitRepository metadata (sync). */
 	resolveSync(cwd: string): GitRepository | null {
 		return resolveRepositorySync(cwd);