pi-legion 3.0.3 → 4.0.0

package/src/runs/worktree.ts

@@ -19,6 +19,26 @@ export function worktreePathFor(runDir: string, name: string): string {
 	return path.join(runDir, "worktrees", sanitizeNameForFs(name));
 }
 
+/**
+ * Budget for the git plumbing probes (`rev-parse`): a handful of stat/read on
+ * the repo metadata, measured in single-digit milliseconds on a warm local
+ * checkout. 5s is ~1000x headroom, and short enough that a hung NFS/network
+ * path (see the #227-series bare-child hangs) surfaces as a probe failure
+ * instead of freezing the parent event loop.
+ *
+ * NOT the budget for mutating commands — see GIT_WORKTREE_TIMEOUT_MS.
+ */
+export const GIT_PROBE_TIMEOUT_MS = 5_000;
+
+/**
+ * Budget for `git worktree add` / `git worktree remove`. These copy the checkout
+ * and may run hooks or a slow `post-checkout`, so they need a far bigger budget
+ * than the probes: 120s is generous for a large repo on slow storage while still
+ * bounding a hang. Deliberately separate from GIT_PROBE_TIMEOUT_MS — one shared
+ * value would either be absurdly loose for `rev-parse` or too tight for `add`.
+ */
+export const GIT_WORKTREE_TIMEOUT_MS = 120_000;
+
 /**
  * Who decides whether this launch gets an isolated worktree.
  *
@@ -46,24 +66,132 @@ export function resolveLaunchWorktree(opts: {
 
 /**
  * True when cwd is itself a linked git worktree (child of a main checkout).
- * Detected via `git rev-parse --git-dir` vs `--git-common-dir`: they differ
- * inside any linked worktree, including ones created by other agent runs.
- * Non-git directories report both as ".git" and are treated as not-in-worktree;
- * the later createChildWorktree call owns the "not a repo" error.
+ * Detected by comparing the cwd's git dir against the repository's common git
+ * dir: they are the same path in a main checkout and differ inside any linked
+ * worktree (including ones created by other agent runs).
+ *
+ * ## Why the paths are resolved before comparing (#237 P10)
+ *
+ * A raw string compare of the two paths is wrong. From a *subdirectory* of a
+ * normal repo git reports them inconsistently: `--git-dir` comes back absolute
+ * (`/repo/.git`) while `--git-common-dir` stays relative (`../../.git`), so the
+ * compare claims "inside a linked worktree" for every subdirectory of a plain
+ * repo — silently suppressing worktree creation for launches whose cwd is one.
+ * Both values are therefore requested with `--path-format=absolute` so they are
+ * resolved by git itself.
+ *
+ * ## Old git cannot corrupt the answer
+ *
+ * `--path-format` needs git >= 2.31. Older git does not reject the unknown long
+ * option — `rev-parse` treats it as a REVISION and echoes it, exiting 0 with
+ * `--path-format=absolute\n.git\n.git` (verified: any `--fake-flag=x` behaves
+ * this way). An unvalidated 2-line parse would then take the flag string as
+ * `gitDir`, see it differ from `commonDir`, and return true for EVERY repo
+ * including main-checkout roots — strictly worse than the bug being fixed.
+ * The parsed shape is therefore validated strictly (exactly two non-empty
+ * absolute paths) and, when git answers in any other shape, the call falls back
+ * to `probeLegacyGitDirs`, which resolves the relative path against the REAL
+ * cwd. A throw (non-git cwd, or the timeout firing) is not a shape problem and
+ * is never retried: it reports false, so one hang costs one budget, not three.
+ *
+ * Supported minimum: git 2.31 (2021-03). On anything older the fallback runs
+ * and produces identical answers — pinned by a shim test that emulates the
+ * echo, plus a direct test of the fallback against real fixtures.
+ *
+ * Non-git directories make `rev-parse` exit 128 (it does NOT report `.git` for
+ * both); the throw is swallowed and treated as not-in-worktree. The later
+ * createChildWorktree call owns the "not a repo" error.
+ *
+ * `fs.realpathSync` is deliberately NOT applied to the resolved pair: git
+ * already canonicalizes its first path segment via getcwd(), so a symlinked
+ * cwd reports a consistent absolute pair for repo roots, repo subdirectories
+ * and symlinked linked-worktree paths alike (verified). It IS applied in the
+ * legacy fallback, where the relative path must be resolved against the real
+ * cwd rather than the symlinked one.
  */
 export function isInsideChildWorktree(cwd: string): boolean {
 	try {
-		const gitDir = execFileSync("git", ["-C", cwd, "rev-parse", "--git-dir"], {
-			stdio: ["ignore", "pipe", "pipe"],
-			encoding: "utf8",
-		}).trim();
-		const commonDir = execFileSync(
+		const out = execFileSync(
 			"git",
-			["-C", cwd, "rev-parse", "--git-common-dir"],
-			{ stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" },
+			["-C", cwd, "rev-parse", "--path-format=absolute", "--git-dir", "--git-common-dir"],
+			{
+				stdio: ["ignore", "pipe", "pipe"],
+				encoding: "utf8",
+				timeout: GIT_PROBE_TIMEOUT_MS,
+			},
 		).trim();
-		return gitDir !== commonDir && gitDir !== "" && commonDir !== "";
+		const pair = parseAbsoluteGitDirs(out);
+		// git answered, but not in the shape --path-format promises: the option was
+		// echoed back as a revision (git < 2.31). Never guess from that output —
+		// re-probe the portable way.
+		if (!pair) return probeLegacyGitDirs(cwd);
+		return pair[0] !== pair[1];
+	} catch {
+		// git refused or never answered (non-git cwd exits 128; a hung path hits
+		// the timeout). Both mean "not a child worktree", and neither justifies a
+		// second and third probe — that would multiply a single budget by three.
+		return false;
+	}
+}
+
+/**
+ * Capability test for `--path-format` (git >= 2.31), and the shape guard that
+ * makes it safe: returns the two git-dir paths only when git answered with
+ * exactly two non-empty absolute paths.
+ *
+ * There is deliberately no separate capability probe or cache — one would cost
+ * a process on every supported call and, worse, a probe that times out on a hung
+ * path would have to be cached as a lie ("unsupported") or re-paid forever.
+ * This runs on output the caller already had to fetch, and rejects what old git
+ * produces (an echoed option, a third line, or a lone `.git`).
+ */
+function parseAbsoluteGitDirs(out: string): [string, string] | null {
+	const lines = out
+		.split("\n")
+		.map((line) => line.trim())
+		.filter((line) => line !== "");
+	if (lines.length !== 2) return null;
+	const [gitDir, commonDir] = lines as [string, string];
+	// Requires both paths absolute. Note this is `path.isAbsolute`, which is
+	// platform-specific: on Windows `path.isAbsolute("C:/foo")` is true, so native
+	// `C:/...` output passes here and the legacy probe is NOT reached. The
+	// rejection branch only fires for a genuinely relative/non-path line, which
+	// is what an old git echoing the option produces on every platform.
+	if (!path.isAbsolute(gitDir) || !path.isAbsolute(commonDir)) return null;
+	return [gitDir, commonDir];
+}
+
+/**
+ * Portable probe for git < 2.31: two plain `rev-parse` calls, then resolve both
+ * results against the REAL cwd. `--git-dir` may come back absolute while
+ * `--git-common-dir` is relative to the cwd, so a raw compare is meaningless —
+ * and `path.resolve(cwd, ...)` alone is not enough either: with a symlinked cwd
+ * git anchors its output at the symlink TARGET, so resolving against the
+ * symlinked spelling reintroduces the very subdirectory false positive this
+ * branch exists to fix (verified: /tmp/link->/tmp/repo, cwd /tmp/link/a yields
+ * `/tmp/repo/.git` vs `../../.git`, which resolves to `/tmp/.git`).
+ *
+ * This IS the capability fallback referenced above.
+ *
+ * Exported for the regression test that pins the fallback's semantics without
+ * requiring an actual old git on the machine.
+ */
+export function probeLegacyGitDirs(cwd: string): boolean {
+	try {
+		const read = (flag: string): string =>
+			execFileSync("git", ["-C", cwd, "rev-parse", flag], {
+				stdio: ["ignore", "pipe", "pipe"],
+				encoding: "utf8",
+				timeout: GIT_PROBE_TIMEOUT_MS,
+			}).trim();
+		const gitDir = read("--git-dir");
+		const commonDir = read("--git-common-dir");
+		if (gitDir === "" || commonDir === "") return false;
+		const realCwd = fs.realpathSync(cwd);
+		return path.resolve(realCwd, gitDir) !== path.resolve(realCwd, commonDir);
 	} catch {
+		// Non-git cwd (rev-parse exits 128), hung git, vanished directory: all
+		// "not a child worktree", matching what the modern path reports.
 		return false;
 	}
 }
@@ -74,17 +202,36 @@ export function worktreeBranchFor(name: string, nonce?: string): string {
 	return `pi-subagent/${sanitizeNameForFs(name)}-${tag}`;
 }
 
-export function isGitRepo(cwd: string): boolean {
+/**
+ * Whether the cwd sits in a work tree. Tri-state on purpose: a probe that
+ * could not run (timeout / spawn failure) is NOT the same finding as "this is
+ * not a repo", and callers word their error differently for each.
+ */
+type RepoProbe = "repo" | "not-a-repo" | "unavailable";
+
+function probeRepo(cwd: string): RepoProbe {
 	try {
 		execFileSync("git", ["-C", cwd, "rev-parse", "--is-inside-work-tree"], {
 			stdio: "ignore",
+			timeout: GIT_PROBE_TIMEOUT_MS,
 		});
-		return true;
-	} catch {
-		return false;
+		return "repo";
+	} catch (error) {
+		// A hung path is surfaced as deferred truth, not as a verdict on the cwd.
+		return isTimeoutError(error) ? "unavailable" : "not-a-repo";
 	}
 }
 
+export function isGitRepo(cwd: string): boolean {
+	return probeRepo(cwd) === "repo";
+}
+
+function isTimeoutError(error: unknown): boolean {
+	if (!error || typeof error !== "object") return false;
+	const { code, signal } = error as { code?: unknown; signal?: unknown };
+	return code === "ETIMEDOUT" || code === "ABORT_ERR" || signal === "SIGTERM";
+}
+
 export interface ChildWorktree {
 	path: string;
 	branch: string;
@@ -95,7 +242,17 @@ export function createChildWorktree(opts: {
 	runDir: string;
 	name: string;
 }): ChildWorktree {
-	if (!isGitRepo(opts.repoCwd)) {
+	const probe = probeRepo(opts.repoCwd);
+	if (probe !== "repo") {
+		// Distinguish "you pointed at the wrong directory" from "git did not
+		// answer": the first is a caller mistake (INVALID_PARAMS), the second is
+		// an environment failure (START_FAILED) and must not accuse the path.
+		if (probe === "unavailable") {
+			throw new SubagentError(
+				`worktree: true could not inspect ${opts.repoCwd}: git did not answer within ${GIT_PROBE_TIMEOUT_MS}ms`,
+				ErrorCodes.START_FAILED,
+			);
+		}
 		throw new SubagentError(
 			`worktree: true requires a git repository; ${opts.repoCwd} is not one`,
 			ErrorCodes.INVALID_PARAMS,
@@ -111,7 +268,7 @@ export function createChildWorktree(opts: {
 			execFileSync(
 				"git",
 				["-C", opts.repoCwd, "worktree", "add", "-b", branch, dest, "HEAD"],
-				{ stdio: ["ignore", "pipe", "pipe"] },
+				{ stdio: ["ignore", "pipe", "pipe"], timeout: GIT_WORKTREE_TIMEOUT_MS },
 			);
 			return { path: dest, branch };
 		} catch (error) {
@@ -131,8 +288,20 @@ export function createChildWorktree(opts: {
 }
 
 function worktreeErrorMessage(error: unknown): string {
-	if (error && typeof error === "object" && "stderr" in error) {
-		return String((error as { stderr?: Buffer | string }).stderr ?? error);
+	if (error && typeof error === "object") {
+		const { stderr, message, code } = error as {
+			stderr?: Buffer | string | null;
+			message?: unknown;
+			code?: unknown;
+		};
+		const detail = stderr === undefined || stderr === null ? "" : String(stderr).trim();
+		if (detail !== "") return detail;
+		// A timeout kill leaves stderr EMPTY (no git output, just SIGTERM), so the
+		// stderr-only extraction used to yield "" and the operator saw a bare
+		// "git worktree add failed: " with no diagnostic. Fall through to the
+		// Error message ("spawnSync git ETIMEDOUT") and then the code.
+		if (typeof message === "string" && message !== "") return message;
+		if (typeof code === "string" && code !== "") return code;
 	}
 	return String(error);
 }
@@ -146,7 +315,7 @@ export function removeChildWorktree(opts: {
 		execFileSync(
 			"git",
 			["-C", opts.repoCwd, "worktree", "remove", "--force", opts.dest],
-			{ stdio: "ignore" },
+			{ stdio: "ignore", timeout: GIT_WORKTREE_TIMEOUT_MS },
 		);
 	} catch {
 		try {

package/src/shared/ignored-kind.ts

@@ -0,0 +1,57 @@
+/**
+ * One-shot reporting for configuration values that are still parsed but no
+ * longer honoured.
+ *
+ * v4 runs `kind: pi` only. The `kind` key survives in three places (role
+ * frontmatter, `subagents.presets.<name>.kind`, `subagents.agentOverrides.
+ * <name>.kind`) and each is re-parsed every time the agent catalog is loaded —
+ * which happens on several UI paths, not once per process. Reporting on every
+ * parse would emit the same line a dozen times as the user moves through the UI,
+ * so the report is deduplicated per (source, subject) pair for the lifetime of
+ * the process.
+ *
+ * The dedupe key deliberately excludes the file path for presets and overrides:
+ * the same role in a project and a user settings file is the same surprise, and
+ * two lines would read as two problems.
+ */
+
+const reported = new Set<string>();
+
+/**
+ * Emit `message` once per unique `key`. Returns whether it was emitted.
+ *
+ * `emit` is injectable so tests can assert on the calls without owning stderr.
+ */
+export function reportIgnoredOnce(
+	key: string,
+	message: string,
+	emit: (message: string) => void = (line) => console.error(line),
+): boolean {
+	if (reported.has(key)) return false;
+	reported.add(key);
+	emit(message);
+	return true;
+}
+
+/** Reset the dedupe set. Unit tests only: no production path clears it. */
+export function resetIgnoredReportsForTests(): void {
+	reported.clear();
+}
+
+/**
+ * The standard line for an ignored non-`pi` kind.
+ *
+ * Names where the value came from, the role or preset it applies to, the value
+ * the user actually wrote, and what happens instead — so the message is
+ * actionable without opening the source.
+ */
+export function ignoredKindMessage(input: {
+	origin: string;
+	subject: string;
+	value: unknown;
+}): string {
+	return (
+		`[pi-legion] ${input.origin} ${input.subject} sets kind ${JSON.stringify(input.value)}; ` +
+		`v4 supports kind: pi only, so that field is ignored and it runs as kind: pi.`
+	);
+}

package/src/shared/progress.ts

@@ -21,6 +21,13 @@ export interface LiveProgress {
 	usageTotal?: number;
 	/** Cumulative output tokens only (numerator for tok/s). */
 	tokensOut?: number;
+	/**
+	 * Prompt size of the last assistant message (`input+cacheRead+cacheWrite`):
+	 * how full the context is right now, not a lifetime total. Absolute value
+	 * only — session JSONL records no `contextWindow`, so there is no honest
+	 * percentage to show.
+	 */
+	contextTokens?: number;
 	/**
 	 * Cumulative model-generation wall ms from the session (denominator for
 	 * tok/s). See ParsedSession.generationMs.
@@ -41,6 +48,9 @@ export function progressFromSession(parsed: ParsedSession): LiveProgress {
 		...turnClock(lastTurn, turnInFlight),
 		...(total > 0 ? { usageTotal: total } : {}),
 		...(tokensOut > 0 ? { tokensOut } : {}),
+		...(parsed.lastContextTokens !== undefined && parsed.lastContextTokens > 0
+			? { contextTokens: parsed.lastContextTokens }
+			: {}),
 		...(parsed.generationMs > 0 ? { generationMs: parsed.generationMs } : {}),
 	};
 }
@@ -85,6 +95,7 @@ export function mergeProgress(...parts: Array<LiveProgress | undefined>): LivePr
 		}
 		if (part.usageTotal && part.usageTotal > 0) out.usageTotal = part.usageTotal;
 		if (part.tokensOut && part.tokensOut > 0) out.tokensOut = part.tokensOut;
+		if (part.contextTokens && part.contextTokens > 0) out.contextTokens = part.contextTokens;
 		if (part.generationMs && part.generationMs > 0) out.generationMs = part.generationMs;
 	}
 	return out;

package/src/shared/session.ts

@@ -120,19 +120,28 @@ function userTextOf(content: unknown): string {
 	return parts.join(" ");
 }
 
-/** Accumulate token usage from an assistant message into the running total. */
+/**
+ * Accumulate token usage from an assistant message into the running total.
+ *
+ * Returns this message's context size — `input + cacheRead + cacheWrite`, the
+ * prompt the model actually saw. `usage` is a lifetime sum across every
+ * message, so it cannot answer "how full is the context right now"; the caller
+ * keeps only the LAST returned value. `undefined` when the message carried no
+ * usage object (nothing was reported, which is not the same as zero).
+ */
 function accumulateUsage(
 	target: Usage,
 	message: Record<string, unknown>,
-): void {
+): number | undefined {
 	const usage = message.usage as Record<string, unknown> | undefined;
-	if (!usage || typeof usage !== "object") return;
+	if (!usage || typeof usage !== "object") return undefined;
 	const cost = usage.cost as Record<string, unknown> | undefined;
 	target.input += num(usage.input);
 	target.output += num(usage.output);
 	target.cacheRead += num(usage.cacheRead);
 	target.cacheWrite += num(usage.cacheWrite);
 	target.cost += num(cost?.total);
+	return num(usage.input) + num(usage.cacheRead) + num(usage.cacheWrite);
 }
 
 /**
@@ -232,7 +241,10 @@ function applyAssistant(
 	clock.awaitingSince = undefined;
 	clock.awaitingWall = undefined;
 
-	accumulateUsage(parsed.usage, message);
+	const contextTokens = accumulateUsage(parsed.usage, message);
+	// Later assistant messages overwrite earlier ones: the newest prompt size is
+	// the one that describes the context the model is holding now.
+	if (contextTokens !== undefined) parsed.lastContextTokens = contextTokens;
 	if (typeof message.model === "string") parsed.model = message.model;
 	if (stopReason) parsed.stopReason = stopReason;
 	// `output`: the last non-empty text anywhere (kept for display/back-compat).
@@ -369,7 +381,7 @@ function num(v: unknown): number {
 const SESSION_READ_CHUNK_BYTES = 1024 * 1024;
 export const DEFAULT_SESSION_MAX_LINE_BYTES = 32 * 1024 * 1024;
 export const SESSION_MAX_LINE_BYTES_ENV = "PI_LEGION_SESSION_MAX_LINE_BYTES";
-const SESSION_CACHE_MAX_ENTRIES = 64;
+export const SESSION_CACHE_MAX_ENTRIES = 64;
 
 /** Per-line cap: one JSONL row larger than this is skipped (counted as torn). */
 export function resolveSessionMaxLineBytes(env: NodeJS.ProcessEnv = process.env): number {
@@ -379,7 +391,8 @@ export function resolveSessionMaxLineBytes(env: NodeJS.ProcessEnv = process.env)
 	return Number.isFinite(n) && n >= 1 ? Math.floor(n) : DEFAULT_SESSION_MAX_LINE_BYTES;
 }
 
-interface SessionParseState {
+/** Append-only JSONL byte cursor shared by parseSessionFile and live-overlay (#234). */
+export interface SessionByteCursor {
 	dev: number;
 	ino: number;
 	/** Byte offset just past the last complete line consumed. */
@@ -387,6 +400,9 @@ interface SessionParseState {
 	/** Bytes at the head and just before `offset`; a mismatch means rewrite. */
 	head: Buffer;
 	boundary: Buffer;
+}
+
+interface SessionParseState extends SessionByteCursor {
 	parsed: ParsedSession;
 	/** Generation-interval clock; survives across incremental polls. */
 	clock: GenerationClock;
@@ -400,18 +416,30 @@ function readAt(fd: number, start: number, length: number): Buffer {
 	return buf.subarray(0, n);
 }
 
-function fingerprint(fd: number, offset: number): { head: Buffer; boundary: Buffer } {
+export function sessionFileFingerprint(fd: number, offset: number): { head: Buffer; boundary: Buffer } {
 	const head = readAt(fd, 0, Math.min(FINGERPRINT_BYTES, offset));
 	const start = Math.max(0, offset - FINGERPRINT_BYTES);
 	return { head, boundary: readAt(fd, start, offset - start) };
 }
 
-function stillValid(fd: number, stat: fs.Stats, state: SessionParseState): boolean {
+export function sessionFileStillValid(
+	fd: number,
+	stat: fs.Stats,
+	state: Pick<SessionByteCursor, "dev" | "ino" | "offset" | "head" | "boundary">,
+): boolean {
 	if (state.dev !== stat.dev || state.ino !== stat.ino || stat.size < state.offset) return false;
-	const now = fingerprint(fd, state.offset);
+	const now = sessionFileFingerprint(fd, state.offset);
 	return now.head.equals(state.head) && now.boundary.equals(state.boundary);
 }
 
+function fingerprint(fd: number, offset: number): { head: Buffer; boundary: Buffer } {
+	return sessionFileFingerprint(fd, offset);
+}
+
+function stillValid(fd: number, stat: fs.Stats, state: SessionParseState): boolean {
+	return sessionFileStillValid(fd, stat, state);
+}
+
 /** Incremental parse cache: append-only session files are only read past `offset`. */
 const sessionParseCache = new Map<string, SessionParseState>();
 
@@ -420,6 +448,16 @@ export function clearSessionParseCache(): void {
 	sessionParseCache.clear();
 }
 
+/** Test hook: number of cached paths, so the LRU cap is asserted not assumed. */
+export function sessionParseCacheSize(): number {
+	return sessionParseCache.size;
+}
+
+/** Test hook: whether a path is cached, so eviction order is asserted, not inferred. */
+export function sessionParseCacheHas(path: string): boolean {
+	return sessionParseCache.has(path);
+}
+
 function applyLine(parsed: ParsedSession, raw: string, clock: GenerationClock): void {
 	const line = raw.trim();
 	if (!line) return;
@@ -433,23 +471,24 @@ function applyLine(parsed: ParsedSession, raw: string, clock: GenerationClock):
 
 /**
  * Stream complete lines from `fd` starting at `start`, never holding more than
- * one chunk plus one (capped) line in memory. Returns the offset just past the
- * last complete line; a trailing partial line is left for the next call.
+ * one chunk plus one (capped) line in memory. A trailing partial line is left
+ * for the next call (offset stays before it). Oversized rows are skipped and
+ * counted in `tornLines` — same policy as parseSessionFile (#36).
  */
-function consumeLines(
+export function readCompleteSessionLines(
 	fd: number,
 	start: number,
 	size: number,
-	parsed: ParsedSession,
-	clock: GenerationClock,
 	maxLineBytes: number,
-): number {
+): { offset: number; lines: string[]; tornLines: number } {
 	const chunk = Buffer.allocUnsafe(SESSION_READ_CHUNK_BYTES);
 	let pos = start;
 	let consumed = start;
 	let pending: Buffer[] = [];
 	let pendingBytes = 0;
 	let skipping = false;
+	const lines: string[] = [];
+	let tornLines = 0;
 	while (pos < size) {
 		const n = fs.readSync(fd, chunk, 0, Math.min(chunk.length, size - pos), pos);
 		if (n <= 0) break;
@@ -457,12 +496,12 @@ function consumeLines(
 		for (let i = 0; i < n; i++) {
 			if (chunk[i] !== 0x0a) continue;
 			if (skipping) {
-				parsed.tornLines += 1;
+				tornLines += 1;
 				skipping = false;
 			} else {
 				const piece = chunk.subarray(lineStart, i);
 				const text = pendingBytes ? Buffer.concat([...pending, piece]).toString("utf8") : piece.toString("utf8");
-				applyLine(parsed, text, clock);
+				lines.push(text);
 			}
 			pending = [];
 			pendingBytes = 0;
@@ -482,7 +521,148 @@ function consumeLines(
 		}
 		pos += n;
 	}
-	return consumed;
+	return { offset: consumed, lines, tornLines };
+}
+
+/**
+ * Stream complete lines from `fd` starting at `start`, never holding more than
+ * one chunk plus one (capped) line in memory. Returns the offset just past the
+ * last complete line; a trailing partial line is left for the next call.
+ */
+function consumeLines(
+	fd: number,
+	start: number,
+	size: number,
+	parsed: ParsedSession,
+	clock: GenerationClock,
+	maxLineBytes: number,
+): number {
+	const { offset, lines, tornLines } = readCompleteSessionLines(fd, start, size, maxLineBytes);
+	for (const text of lines) applyLine(parsed, text, clock);
+	parsed.tornLines += tornLines;
+	return offset;
+}
+
+/** Result of an incremental JSONL append read (#234). */
+export interface SessionJsonlDelta {
+	/** Fingerprint cursor after committing complete lines. */
+	cursor: SessionByteCursor;
+	/** Newly completed lines since `previous` (provisional excluded). */
+	lines: string[];
+	/** Trailing incomplete bytes for this call only — do not commit. */
+	provisional: string;
+	fileSize: number;
+	/** True when `previous` was discarded (rewrite / truncate / inode change). */
+	reset: boolean;
+	/** Oversized lines skipped while scanning this delta. */
+	tornLines: number;
+}
+
+function emptyByteCursor(stat: fs.Stats): SessionByteCursor {
+	return {
+		dev: stat.dev,
+		ino: stat.ino,
+		offset: 0,
+		head: Buffer.alloc(0),
+		boundary: Buffer.alloc(0),
+	};
+}
+
+/**
+ * Seek to `previous.offset` and parse only appended bytes (#234).
+ *
+ * Same rewrite detection and trailing-partial policy as `parseSessionFile`:
+ * provisional bytes are returned for this call but must not be committed by the
+ * caller. Pass `undefined` for a cold read from byte 0. Missing files yield
+ * `undefined`.
+ */
+export function readSessionJsonlDelta(
+	path: string,
+	previous: SessionByteCursor | undefined,
+): SessionJsonlDelta | undefined {
+	let fd: number | undefined;
+	try {
+		fd = fs.openSync(path, "r");
+		const stat = fs.fstatSync(fd);
+		const reset = !previous || !sessionFileStillValid(fd, stat, previous);
+		const cursor = reset
+			? emptyByteCursor(stat)
+			: {
+				dev: previous.dev,
+				ino: previous.ino,
+				offset: previous.offset,
+				head: previous.head,
+				boundary: previous.boundary,
+			};
+		const maxLineBytes = resolveSessionMaxLineBytes();
+		const before = cursor.offset;
+		const read = readCompleteSessionLines(fd, cursor.offset, stat.size, maxLineBytes);
+		cursor.offset = read.offset;
+		cursor.dev = stat.dev;
+		cursor.ino = stat.ino;
+		if (cursor.offset !== before) Object.assign(cursor, sessionFileFingerprint(fd, cursor.offset));
+		let provisional = "";
+		if (cursor.offset < stat.size && stat.size - cursor.offset <= maxLineBytes) {
+			const tail = Buffer.allocUnsafe(stat.size - cursor.offset);
+			const n = fs.readSync(fd, tail, 0, tail.length, cursor.offset);
+			provisional = tail.subarray(0, n).toString("utf8");
+		}
+		return {
+			cursor,
+			lines: read.lines,
+			provisional,
+			fileSize: stat.size,
+			reset,
+			tornLines: read.tornLines,
+		};
+	} catch {
+		return undefined;
+	} finally {
+		if (fd !== undefined) {
+			try { fs.closeSync(fd); } catch { /* ignore */ }
+		}
+	}
+}
+
+/**
+ * Snapshot the cache object for one caller (#237 P7).
+ *
+ * `state.parsed` is mutated IN PLACE across polls: `accumulateUsage` adds into
+ * the existing `usage` object, `currentTurn` pushes turns, `applyAssistant`
+ * pushes into a turn's `assistants` and writes `turn.endedAt`, and
+ * `applyToolResult` bumps `turn.toolResults`/`toolErrors`. The caller must never
+ * receive those objects, because the provisional tail below is parsed into the
+ * returned value: sharing a turn would push the provisional assistant into the
+ * CACHED turn, and the next poll's real commit would count it a second time
+ * (a silent, permanent over-count in `turns`/`assistants`).
+ *
+ * The depth here is the minimum that makes every write point above land on a
+ * fresh object — not "as deep as structuredClone":
+ *   - `usage`  — mutated in place, so it needs its own object.
+ *   - `turns`  — grown with `push`, so it needs its own array.
+ *   - each turn — `endedAt`/`toolResults`/`toolErrors` are written back, so the
+ *     turn objects themselves must be fresh.
+ *   - each turn's `assistants` — grown with `push`, so it needs its own array.
+ *   - each assistant and its `tools` — nothing in production writes these
+ *     today (they are built once as a literal), but a caller can, and the
+ *     whole point is that no mutation any caller makes reaches the cache. It
+ *     costs ~0.01ms on a 5MB session and removes the last aliased object.
+ * Anything deeper is pure waste. For scale: `structuredClone` at this call site
+ * cost ~2.2x a warm parse that does no copy at all (P7), and the ~1ms/file it
+ * burned is what this function gives back.
+ */
+function projectForCaller(parsed: ParsedSession): ParsedSession {
+	return {
+		...parsed,
+		usage: { ...parsed.usage },
+		turns: parsed.turns.map((turn): TurnRecord => ({
+			...turn,
+			assistants: turn.assistants.map((assistant): TurnRecord["assistants"][number] => ({
+				...assistant,
+				tools: assistant.tools.slice(),
+			})),
+		})),
+	};
 }
 
 function finalizeParsed(parsed: ParsedSession): ParsedSession {
@@ -528,7 +708,7 @@ export function parseSessionFile(path: string): ParsedSession {
 			const oldest = sessionParseCache.keys().next().value;
 			if (oldest !== undefined) sessionParseCache.delete(oldest);
 		}
-		const result = structuredClone(state.parsed);
+		const result = projectForCaller(state.parsed);
 		if (state.offset < stat.size && stat.size - state.offset <= maxLineBytes) {
 			const tail = Buffer.allocUnsafe(stat.size - state.offset);
 			const n = fs.readSync(fd, tail, 0, tail.length, state.offset);