pi-crew 0.10.2 → 0.10.4

package/src/ui/run-snapshot-cache.ts

@@ -25,6 +25,8 @@ import type {
 export interface RunSnapshotCache extends RunSnapshotCacheBase {
 	preloadStale(runId: string): Promise<RunUiSnapshot | undefined>;
 	preloadAllStale(runIds: string[]): Promise<void>;
+	/** Task 17 (perf/review-2026-08-24): watcher-facing coalesced async refresh. */
+	scheduleRefresh(runId: string): void;
 }
 
 /** WP-7 (R7): the plans slice + Plan pane load only when this flag is set —
@@ -191,9 +193,18 @@ function sameStamps(a: SnapshotStamps, b: SnapshotStamps): boolean {
 	);
 }
 
-/** Tail-read JSONL lines from a file, returning parsed objects (limited). */
-function tailJsonlLines<T>(filePath: string, limit: number, parse: (line: string) => T | undefined): T[] {
-	if (limit <= 0) return [];
+/** Raw tail-window of a file: split lines plus whether the window clipped content. */
+interface TailContent {
+	lines: string[];
+	approximate: boolean;
+}
+
+/**
+ * PERF (2026-08-24): single tail read of a file, shareable across consumers.
+ * `approximate` mirrors the old tailApproximate() stat (size > MAX_TAIL_BYTES)
+ * so callers keep reporting clipped mailboxes without re-statting.
+ */
+function readTailContent(filePath: string): TailContent {
 	try {
 		const stat = fs.statSync(filePath);
 		const bytesToRead = Math.min(stat.size, MAX_TAIL_BYTES);
@@ -201,21 +212,35 @@ function tailJsonlLines<T>(filePath: string, limit: number, parse: (line: string
 		try {
 			const buffer = Buffer.alloc(bytesToRead);
 			fs.readSync(fd, buffer, 0, bytesToRead, stat.size - bytesToRead);
-			const lines = buffer.toString("utf-8").split(/\r?\n/).filter(Boolean);
-			return lines
-				.flatMap((line) => {
-					const item = parse(line);
-					return item ? [item] : [];
-				})
-				.slice(-limit);
+			return {
+				lines: buffer.toString("utf-8").split(/\r?\n/).filter(Boolean),
+				approximate: stat.size > MAX_TAIL_BYTES,
+			};
 		} finally {
 			fs.closeSync(fd);
 		}
 	} catch {
-		return [];
+		return { lines: [], approximate: false };
 	}
 }
 
+/** Parse pre-read tail lines, keeping the last `limit` parseable items. */
+function parseTailLines<T>(lines: string[], limit: number, parse: (line: string) => T | undefined): T[] {
+	if (limit <= 0) return [];
+	return lines
+		.flatMap((line) => {
+			const item = parse(line);
+			return item ? [item] : [];
+		})
+		.slice(-limit);
+}
+
+/** Tail-read JSONL lines from a file, returning parsed objects (limited). */
+function tailJsonlLines<T>(filePath: string, limit: number, parse: (line: string) => T | undefined): T[] {
+	if (limit <= 0) return [];
+	return parseTailLines(readTailContent(filePath).lines, limit, parse);
+}
+
 /** Async tail-read JSONL lines from a file, returning parsed objects (limited). */
 async function tailJsonlLinesAsync<T>(filePath: string, limit: number, parse: (line: string) => T | undefined): Promise<T[]> {
 	if (limit <= 0) return [];
@@ -406,8 +431,9 @@ async function readDeliveryMessagesAsync(filePath: string): Promise<Record<strin
 	}
 }
 
-function readGroupJoinMailbox(filePath: string, delivery: Record<string, MailboxMessageStatus>): RunUiGroupJoin[] {
-	return tailJsonlLines(filePath, MAX_TAIL_LINES, (line) => {
+/** Parse pre-read outbox lines into group-join records (ack status from `delivery`). */
+function parseGroupJoinLines(lines: string[], delivery: Record<string, MailboxMessageStatus>): RunUiGroupJoin[] {
+	return parseTailLines(lines, MAX_TAIL_LINES, (line) => {
 		try {
 			const parsed = JSON.parse(line) as unknown;
 			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
@@ -464,14 +490,6 @@ interface MailboxKindCount extends MailboxCount {
 	message: number;
 }
 
-function tailApproximate(filePath: string): boolean {
-	try {
-		return fs.statSync(filePath).size > MAX_TAIL_BYTES;
-	} catch {
-		return false;
-	}
-}
-
 async function tailApproximateAsync(filePath: string): Promise<boolean> {
 	try {
 		return (await fs.promises.stat(filePath)).size > MAX_TAIL_BYTES;
@@ -481,8 +499,13 @@ async function tailApproximateAsync(filePath: string): Promise<boolean> {
 }
 
 function readMailboxCounts(filePath: string, delivery: Record<string, MailboxMessageStatus>): MailboxKindCount {
+	return mailboxCountsFrom(readTailContent(filePath), delivery);
+}
+
+/** Count unread/pending by kind from a pre-read tail window (shared outbox read). */
+function mailboxCountsFrom(tail: TailContent, delivery: Record<string, MailboxMessageStatus>): MailboxKindCount {
 	const kindCounts = { steer: 0, followUp: 0, response: 0, message: 0 };
-	const items = tailJsonlLines(filePath, MAX_TAIL_LINES, (line) => {
+	const items = parseTailLines(tail.lines, MAX_TAIL_LINES, (line) => {
 		try {
 			const parsed = JSON.parse(line) as unknown;
 			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return 0;
@@ -514,7 +537,7 @@ function readMailboxCounts(filePath: string, delivery: Record<string, MailboxMes
 	const count = items.reduce((sum, val) => sum + val, 0);
 	return {
 		count,
-		approximate: tailApproximate(filePath),
+		approximate: tail.approximate,
 		steer: kindCounts.steer,
 		followUp: kindCounts.followUp,
 		response: kindCounts.response,
@@ -564,10 +587,12 @@ async function readMailboxCountsAsync(filePath: string, delivery: Record<string,
 	};
 }
 
-function groupJoinsFrom(manifest: TeamRunManifest): RunUiGroupJoin[] {
-	const root = path.join(manifest.stateRoot, "mailbox");
-	const delivery = readDeliveryMessages(path.join(root, "delivery.json"));
-	return readGroupJoinMailbox(path.join(root, "outbox.jsonl"), delivery).slice(-5);
+function groupJoinsFrom(
+	manifest: TeamRunManifest,
+	delivery: Record<string, MailboxMessageStatus>,
+	outboxTail: TailContent,
+): RunUiGroupJoin[] {
+	return parseGroupJoinLines(outboxTail.lines, delivery).slice(-5);
 }
 
 async function groupJoinsFromAsync(manifest: TeamRunManifest): Promise<RunUiGroupJoin[]> {
@@ -587,11 +612,15 @@ function mergeKindCounts(a: MailboxKindCount, b: MailboxKindCount): MailboxKindC
 	};
 }
 
-function mailboxFrom(manifest: TeamRunManifest, agents: CrewAgentRecord[]): RunUiMailbox {
+function mailboxFrom(
+	manifest: TeamRunManifest,
+	agents: CrewAgentRecord[],
+	delivery: Record<string, MailboxMessageStatus>,
+	outboxTail: TailContent,
+): RunUiMailbox {
 	const root = path.join(manifest.stateRoot, "mailbox");
-	const delivery = readDeliveryMessages(path.join(root, "delivery.json"));
 	let inbox = readMailboxCounts(path.join(root, "inbox.jsonl"), delivery);
-	let outbox = readMailboxCounts(path.join(root, "outbox.jsonl"), delivery);
+	let outbox = mailboxCountsFrom(outboxTail, delivery);
 	const tasksRoot = path.join(root, "tasks");
 	try {
 		for (const entry of fs.readdirSync(tasksRoot, {
@@ -865,8 +894,14 @@ export function createRunSnapshotCache(cwd: string, options: RunSnapshotCacheOpt
 			if (previous) return previous;
 			throw new Error(`Run '${runId}' could not be parsed.`);
 		}
-		const mailbox = mailboxFrom(loaded.manifest, agents);
-		const groupJoins = groupJoinsFrom(loaded.manifest);
+		// PERF (2026-08-24): mailboxFrom and groupJoinsFrom each parsed
+		// delivery.json and tailed outbox.jsonl — read both once here and
+		// thread the results into both consumers.
+		const mailboxRoot = path.join(loaded.manifest.stateRoot, "mailbox");
+		const delivery = readDeliveryMessages(path.join(mailboxRoot, "delivery.json"));
+		const outboxTail = readTailContent(path.join(mailboxRoot, "outbox.jsonl"));
+		const mailbox = mailboxFrom(loaded.manifest, agents, delivery, outboxTail);
+		const groupJoins = groupJoinsFrom(loaded.manifest, delivery, outboxTail);
 		const recentEvents = safeRecentEvents(loaded.manifest.eventsPath, recentEventsLimit);
 		const base = {
 			runId: loaded.manifest.runId,
@@ -1048,7 +1083,7 @@ export function createRunSnapshotCache(cwd: string, options: RunSnapshotCacheOpt
 	}
 	const pendingRefreshes = new Map<string, ReturnType<typeof setTimeout>>();
 	const INVAL_COALESCE_MS = 80;
-	const scheduleRefresh = (runId: string): void => {
+	const scheduleCoalescedRefresh = (runId: string): void => {
 		const existing = pendingRefreshes.get(runId);
 		if (existing) clearTimeout(existing);
 		const timer = setTimeout(() => {
@@ -1062,10 +1097,10 @@ export function createRunSnapshotCache(cwd: string, options: RunSnapshotCacheOpt
 		pendingRefreshes.set(runId, timer);
 	};
 	const unsubState = runEventBus.onChannel("run:state", (event) => {
-		if (entries.has(event.runId)) scheduleRefresh(event.runId);
+		if (entries.has(event.runId)) scheduleCoalescedRefresh(event.runId);
 	});
 	const unsubLifecycle = runEventBus.onChannel("worker:lifecycle", (event) => {
-		if (entries.has(event.runId)) scheduleRefresh(event.runId);
+		if (entries.has(event.runId)) scheduleCoalescedRefresh(event.runId);
 	});
 	const unsubscribe = () => {
 		unsubState();
@@ -1085,6 +1120,19 @@ export function createRunSnapshotCache(cwd: string, options: RunSnapshotCacheOpt
 		refreshIfStale(runId: string): RunUiSnapshot {
 			return localRefreshIfStale(runId);
 		},
+		/**
+		 * PERF (2026-08-24): watcher-facing refresh. The fs.watch path used to
+		 * call the SYNC refresh() directly on every file event — a full
+		 * snapshot rebuild (manifest+tasks parse, agents.json, mailbox readdir,
+		 * per-agent tail reads, 2x stringify+sha256) many times per second,
+		 * blocking the UI event loop. This routes through the same 80ms
+		 * coalesced → async (preloadStale) pipeline the run event bus uses.
+		 * FLICKER FIX semantics preserved: buildAsync re-sets the entry in
+		 * place; nothing is deleted.
+		 */
+		scheduleRefresh(runId: string): void {
+			scheduleCoalescedRefresh(runId);
+		},
 		preloadStale,
 		preloadAllStale,
 		invalidate(runId?: string): void {

package/src/ui/settings-overlay.ts

@@ -345,7 +345,10 @@ const EFFECTIVE_DEFAULTS: Record<string, unknown> = {
 	"ui.dashboardPlacement": "center",
 	"ui.dashboardWidth": 72,
 	"ui.autoOpenDashboard": false,
-	"ui.widgetPlacement": "aboveEditor",
+	// G17 sync (2026-09-10 review): canonical DEFAULT_UI.widgetPlacement =
+	// "bottom" (defaults.ts / install.mjs / project-init) — was drifted
+	// "aboveEditor" in this duplicated EFFECTIVE_DEFAULTS map.
+	"ui.widgetPlacement": "bottom",
 	"autonomous.enabled": true,
 	"autonomous.injectPolicy": true,
 	"autonomous.preferAsyncForLongTasks": false,

package/src/ui/transcript-cache.ts

@@ -3,11 +3,25 @@ import * as fs from "node:fs";
 export interface TranscriptCacheEntry {
 	path: string;
 	mtimeMs: number;
+	/**
+	 * Byte offset of the END of the cached text. Equals `offset + raw.length`
+	 * (normally the file size at read time; only smaller if a concurrent
+	 * writer shrank the file mid-read, which forces a fresh read next time).
+	 */
 	size: number;
+	/**
+	 * Byte offset of the START of the cached text. Zero for whole-file reads;
+	 * positive once the tail cap front-trims, because the cached text then
+	 * starts partway into the file — not at offset 0.
+	 */
+	offset: number;
+	/** Undecoded bytes backing the cached text, spanning [offset, size). */
+	raw: Buffer;
 	lines: string[];
 	parsedAt: number;
 	readCount: number;
 	mode: "tail" | "full";
+	/** Bytes actually read from disk on the most recent read (delta for appends). */
 	bytesRead: number;
 	truncated: boolean;
 }
@@ -47,34 +61,100 @@ export function getTranscriptCacheEntry(path: string, options: TranscriptReadOpt
 	return transcriptCache.get(cacheKey(path, normalized)) ?? transcriptCache.get(path);
 }
 
+interface TranscriptReadResult {
+	raw: Buffer;
+	offset: number;
+	bytesRead: number;
+	truncated: boolean;
+}
+
+/**
+ * Fresh read: whole file, or the last `maxTailBytes` bytes with the leading
+ * partial line skipped. Operates on raw bytes so a later append can extend
+ * the buffer and decode exactly like a fresh read of the same byte range.
+ */
 function readTranscriptText(
 	path: string,
 	stat: fs.Stats,
 	options: Required<Pick<TranscriptReadOptions, "full">> & {
 		maxTailBytes: number;
 	},
-): { text: string; bytesRead: number; truncated: boolean } {
+): TranscriptReadResult {
 	if (options.full || stat.size <= options.maxTailBytes) {
-		return {
-			text: fs.readFileSync(path, "utf-8"),
-			bytesRead: stat.size,
-			truncated: false,
-		};
+		const raw = fs.readFileSync(path);
+		return { raw, offset: 0, bytesRead: raw.length, truncated: false };
 	}
 	const bytesToRead = Math.min(stat.size, options.maxTailBytes);
 	const fd = fs.openSync(path, "r");
 	try {
 		const buffer = Buffer.alloc(bytesToRead);
 		fs.readSync(fd, buffer, 0, bytesToRead, stat.size - bytesToRead);
-		let text = buffer.toString("utf-8");
-		const firstNewline = text.search(/\r?\n/);
-		if (firstNewline >= 0) text = text.slice(firstNewline + (text[firstNewline] === "\r" && text[firstNewline + 1] === "\n" ? 2 : 1));
-		return { text, bytesRead: bytesToRead, truncated: true };
+		// Skip through the first newline so the tail starts on a line boundary
+		// (0x0a is ASCII, so a byte scan matches the old decoded-text scan).
+		const firstNewline = buffer.indexOf(0x0a);
+		const start = firstNewline >= 0 ? firstNewline + 1 : 0;
+		return {
+			raw: buffer.subarray(start),
+			offset: stat.size - bytesToRead + start,
+			bytesRead: bytesToRead,
+			truncated: true,
+		};
 	} finally {
 		fs.closeSync(fd);
 	}
 }
 
+/**
+ * Incremental read for append-only growth: read only [previous.size, size) and
+ * extend the cached bytes, then re-apply the tail cap by trimming the FRONT.
+ * Returns null when the delta could not be read completely (concurrent
+ * shrink/rotation) so the caller falls back to a fresh read.
+ */
+function appendTranscriptText(
+	path: string,
+	previous: TranscriptCacheEntry,
+	stat: fs.Stats,
+	options: Required<Pick<TranscriptReadOptions, "full">> & {
+		maxTailBytes: number;
+	},
+): TranscriptReadResult | null {
+	const deltaLength = stat.size - previous.size;
+	const fd = fs.openSync(path, "r");
+	let delta: Buffer;
+	try {
+		delta = Buffer.alloc(deltaLength);
+		let read = 0;
+		while (read < deltaLength) {
+			const n = fs.readSync(fd, delta, read, deltaLength - read, previous.size + read);
+			if (n <= 0) break;
+			read += n;
+		}
+		if (read < deltaLength) return null;
+	} finally {
+		fs.closeSync(fd);
+	}
+	let raw = Buffer.concat([previous.raw, delta], previous.raw.length + deltaLength);
+	let offset = previous.offset;
+	const endOffset = previous.size + deltaLength;
+	if (!options.full && endOffset - offset > options.maxTailBytes) {
+		// Keep the tail bounded: drop to the start of the new window, then
+		// through the first newline so the front stays a complete line.
+		const windowStart = endOffset - options.maxTailBytes;
+		const firstNewline = raw.indexOf(0x0a, windowStart - offset);
+		const drop = firstNewline >= 0 ? firstNewline + 1 : windowStart - offset;
+		// Copy (not subarray) so a huge append does not keep its pre-trim
+		// buffer alive through the retained view.
+		raw = Buffer.from(raw.subarray(drop));
+		offset += drop;
+	}
+	return {
+		raw,
+		offset,
+		bytesRead: deltaLength,
+		truncated: !options.full && offset > 0,
+	};
+}
+
 export function readTranscriptLinesCached(
 	path: string,
 	parse: (text: string) => string[],
@@ -98,12 +178,20 @@ export function readTranscriptLinesCached(
 		return previous.lines;
 	}
 	try {
-		const read = readTranscriptText(path, stat, normalized);
-		const lines = parse(read.text);
+		// Append-only growth (size grew, mtime not older): read only the new
+		// bytes and extend the cached range. Any shrink or backdated mtime
+		// falls through to a fresh read below.
+		const read =
+			previous && stat.size > previous.size && stat.mtimeMs >= previous.mtimeMs
+				? (appendTranscriptText(path, previous, stat, normalized) ?? readTranscriptText(path, stat, normalized))
+				: readTranscriptText(path, stat, normalized);
+		const lines = parse(read.raw.toString("utf-8"));
 		const entry: TranscriptCacheEntry = {
 			path,
 			mtimeMs: stat.mtimeMs,
-			size: stat.size,
+			size: read.offset + read.raw.length,
+			offset: read.offset,
+			raw: read.raw,
 			lines,
 			parsedAt: now,
 			readCount: (previous?.readCount ?? 0) + 1,

package/src/ui/transcript-viewer.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import { agentOutputPath, readCrewAgents } from "../runtime/crew-agent-records.ts";
 import type { TeamRunManifest } from "../state/types.ts";
 import { resolveRealContainedPath } from "../utils/safe-paths.ts";
-import { pad, truncate, truncateToVisualLines } from "../utils/visual.ts";
+import { pad, truncate, truncateToVisualLines, truncateToVisualLinesTail } from "../utils/visual.ts";
 import type { InteractiveComponent } from "./component.ts";
 import { renderDiff } from "./render-diff.ts";
 import { colorForStatus, iconForStatus, type RunStatus } from "./status-colors.ts";
@@ -234,17 +234,60 @@ interface ViewerState {
 	autoScroll: boolean;
 	lastHeight: number;
 	scroll: number;
+	// PERF (2026-08-24): full-wrap cache for the scroll-up path. ViewerState is
+	// built per render, so these are per-render scratch: the tail branch is the
+	// hot path (bottom-pinned ~500ms re-render) and never needs the full wrap;
+	// renders that fall to the else branch pay one full wrap each — the same
+	// price the pre-optimization code paid on EVERY render.
+	fullVisual: string[] | null;
+	sourceLen: number;
 }
 
 function renderViewerBase(state: ViewerState, width: number, lines: string[], title: string, subtitle: string): string[] {
 	const inner = Math.max(20, width - 4);
+	// PERF (2026-08-24): transcripts grow to thousands of lines; wrapping every
+	// grapheme of the whole tail to display 16 rows was the largest CPU sink in
+	// the UI. Bottom-pinned (autoScroll) renders use the tail window — O(visible
+	// rows); scrolling up pays one full wrap per render (what the old code paid
+	// on EVERY render) and can page through the whole transcript.
 	const bodyText = lines.join("\n");
-	const { visualLines, skippedCount } = truncateToVisualLines(bodyText, state.lastHeight, inner);
-	const maxScroll = Math.max(0, visualLines.length - state.lastHeight);
+	let visualLines: string[];
+	let skippedCount: number;
+	let maxScroll: number;
+	let tailWindow = false;
+	if (state.autoScroll && (state.fullVisual === null || state.sourceLen !== lines.length)) {
+		const tail = truncateToVisualLinesTail(bodyText, state.lastHeight, inner);
+		visualLines = tail.visualLines;
+		skippedCount = tail.skippedCount;
+		maxScroll = skippedCount; // bottom-pinned: everything above the window
+		state.fullVisual = null;
+		state.sourceLen = lines.length;
+		tailWindow = true;
+	} else {
+		if (state.fullVisual === null || state.sourceLen !== lines.length) {
+			// MAX_SAFE_INTEGER is never a real allocation: truncateToVisualLines
+			// returns early while visualLines.length <= limit (always true), so
+			// slice(-limit) never runs — this is just "wrap everything".
+			const full = truncateToVisualLines(bodyText, Number.MAX_SAFE_INTEGER, inner);
+			state.fullVisual = full.visualLines;
+			state.sourceLen = lines.length;
+		}
+		visualLines = state.fullVisual!;
+		skippedCount = 0;
+		maxScroll = Math.max(0, visualLines.length - state.lastHeight);
+	}
 	if (state.autoScroll) state.scroll = maxScroll;
 	state.scroll = Math.min(state.scroll, maxScroll);
-	const visible = visualLines.slice(state.scroll, state.scroll + state.lastHeight);
-	const statusLine = `${visualLines.length} lines · ${visualLines.length ? Math.round(((state.scroll + visible.length) / visualLines.length) * 100) : 100}% · auto-scroll ${state.autoScroll ? "on" : "off"}`;
+	// The tail window IS the bottom-pinned view: state.scroll holds the offset
+	// into the FULL wrap (skippedCount lines above), so slicing the ≤ lastHeight
+	// window at it would render an empty body. Display the window directly.
+	const visible = tailWindow ? visualLines : visualLines.slice(state.scroll, state.scroll + state.lastHeight);
+	// Tail-branch total is a lower bound: skippedCount counts SOURCE lines and
+	// each may wrap to several visual lines. "≥" flags that (short transcripts
+	// and the full-wrap branch keep the exact count).
+	const totalLines = tailWindow ? skippedCount + visible.length : visualLines.length;
+	const totalLabel = tailWindow && skippedCount > 0 ? `≥ ${totalLines}` : `${totalLines}`;
+	const statusLine = `${totalLabel} lines · ${totalLines ? Math.round(((state.scroll + visible.length) / totalLines) * 100) : 100}% · auto-scroll ${state.autoScroll ? "on" : "off"}`;
 	const fg = (color: Parameters<TranscriptTheme["fg"]>[0], text: string) => state.theme.fg(color, text);
 	const row = (text: string) => `${fg("border", "│")} ${pad(truncate(text, inner), inner)} ${fg("border", "│")}`;
 	const linesOut: string[] = [
@@ -267,6 +310,11 @@ export class DurableTextViewer implements Component {
 	private scroll = 0;
 	private lastHeight = 16;
 	private autoScroll = true;
+	// PERF (2026-08-24): whether the PREVIOUS render was bottom-pinned. The
+	// tail branch tracks `scroll` in source-line units, which is not a valid
+	// index into the full wrap — the first manual render after a pinned one
+	// clamps to the exact visual bottom instead of slicing at that stale value.
+	private prevAutoScroll = true;
 	private title: string;
 	private subtitle: string;
 	private lines: string[];
@@ -312,6 +360,7 @@ export class DurableTextViewer implements Component {
 		} else if (data === "g" || data === "\u001b[H") {
 			this.scroll = 0;
 			this.autoScroll = false;
+			this.prevAutoScroll = false; // explicit top — do not pin to bottom
 		} else if (data === "G" || data === "\u001b[F") {
 			this.scroll = maxScroll;
 			this.autoScroll = true;
@@ -321,18 +370,23 @@ export class DurableTextViewer implements Component {
 	}
 
 	render(width: number): string[] {
-		return renderViewerBase(
-			{
-				theme: this.theme,
-				autoScroll: this.autoScroll,
-				lastHeight: this.lastHeight,
-				scroll: this.scroll,
-			},
-			width,
-			this.lines,
-			this.title,
-			this.subtitle,
-		);
+		// Leaving the pinned state (k/PgUp/a): the stale source-unit scroll
+		// would slice the full wrap in the wrong place — clamp to its bottom.
+		if (!this.autoScroll && this.prevAutoScroll) this.scroll = Number.MAX_SAFE_INTEGER;
+		const state: ViewerState = {
+			theme: this.theme,
+			autoScroll: this.autoScroll,
+			lastHeight: this.lastHeight,
+			scroll: this.scroll,
+			fullVisual: null,
+			sourceLen: 0,
+		};
+		const rendered = renderViewerBase(state, width, this.lines, this.title, this.subtitle);
+		// Write the clamped/updated scroll back so handleInput's scroll math
+		// starts from the position the user actually saw.
+		this.scroll = state.scroll;
+		this.prevAutoScroll = this.autoScroll;
+		return rendered;
 	}
 }
 
@@ -340,6 +394,8 @@ export class DurableTranscriptViewer implements Component {
 	private scroll = 0;
 	private lastHeight = 16;
 	private autoScroll = true;
+	// See DurableTextViewer.prevAutoScroll — same pinned→manual transition guard.
+	private prevAutoScroll = true;
 	private manifest: TeamRunManifest;
 	private theme: TranscriptTheme;
 	private done: (result: undefined) => void;
@@ -406,6 +462,7 @@ export class DurableTranscriptViewer implements Component {
 		} else if (data === "g" || data === "\u001b[H") {
 			this.scroll = 0;
 			this.autoScroll = false;
+			this.prevAutoScroll = false; // explicit top — do not pin to bottom
 		} else if (data === "G" || data === "\u001b[F") {
 			this.scroll = maxScroll;
 			this.autoScroll = true;
@@ -415,6 +472,7 @@ export class DurableTranscriptViewer implements Component {
 			this.fullTranscript = !this.fullTranscript;
 			this.scroll = 0;
 			this.autoScroll = !this.fullTranscript;
+			this.prevAutoScroll = this.autoScroll; // explicit reset — no bottom pin
 			// The full/tail toggle changes the read options, so refresh the cache
 			// with a single explicit read rather than per keystroke.
 			this.cached = this.readTranscript(this.manifest, this.taskId, {
@@ -432,17 +490,27 @@ export class DurableTranscriptViewer implements Component {
 		// Keep the per-keypress cache in sync with the latest rendered content
 		// (the read is TTL-cached at ~500ms, so this stays cheap on each tick).
 		this.cached = data;
-		return renderViewerBase(
-			{
-				theme: this.theme,
-				autoScroll: this.autoScroll,
-				lastHeight: this.lastHeight,
-				scroll: this.scroll,
-			},
+		// Leaving the pinned state (k/PgUp/a): the stale source-unit scroll
+		// would slice the full wrap in the wrong place — clamp to its bottom.
+		if (!this.autoScroll && this.prevAutoScroll) this.scroll = Number.MAX_SAFE_INTEGER;
+		const state: ViewerState = {
+			theme: this.theme,
+			autoScroll: this.autoScroll,
+			lastHeight: this.lastHeight,
+			scroll: this.scroll,
+			fullVisual: null,
+			sourceLen: 0,
+		};
+		const rendered = renderViewerBase(
+			state,
 			width,
 			data.lines,
 			"pi-crew transcript",
 			`${data.title} · ${data.truncated ? `tail ${Math.round(data.bytesRead / 1024)}KB/${Math.round(data.size / 1024)}KB` : `full ${Math.round(data.size / 1024)}KB`} · f ${this.fullTranscript ? "tail" : "full"}`,
 		);
+		// Write the clamped/updated scroll back (see DurableTextViewer.render).
+		this.scroll = state.scroll;
+		this.prevAutoScroll = this.autoScroll;
+		return rendered;
 	}
 }