@gajae-code/coding-agent 0.8.2 → 0.9.0

package/src/system-prompt.ts

@@ -14,6 +14,7 @@ import { loadSkills, type Skill } from "./extensibility/skills";
 import customSystemPromptTemplate from "./prompts/system/custom-system-prompt.md" with { type: "text" };
 import projectPromptTemplate from "./prompts/system/project-prompt.md" with { type: "text" };
 import systemPromptTemplate from "./prompts/system/system-prompt.md" with { type: "text" };
+import volatileProjectContextTemplate from "./prompts/system/volatile-project-context.md" with { type: "text" };
 import { shortenPath } from "./tools/render-utils";
 import { AGENTS_MD_LIMIT, buildWorkspaceTree, type WorkspaceTree } from "./workspace-tree";
 
@@ -242,9 +243,12 @@ function dedupeExactContextFiles(
 }
 
 /**
- * Load all project context files using the capability API.
+ * Load all context files using the capability API.
  * Returns {path, content, depth} entries for all discovered context files.
- * Files are sorted by depth (descending) so files closer to cwd appear last/more prominent.
+ * Native user-global files (`~/.gjc/agent/AGENTS.md`) come first, then project
+ * files sorted by depth (descending) so files closer to cwd appear last/more
+ * prominent. User-home files from foreign providers (`~/.claude/CLAUDE.md`,
+ * `~/.codex/AGENTS.md`, …) stay excluded — only gjc's own user config applies.
  */
 export async function loadProjectContextFiles(
 	options: LoadContextFilesOptions = {},
@@ -252,28 +256,32 @@ export async function loadProjectContextFiles(
 	const resolvedCwd = options.cwd ?? getProjectDir();
 
 	const result = await loadCapability(contextFileCapability.id, { cwd: resolvedCwd });
+	const items = result.items as ContextFile[];
+
+	// Native user-global context applies everywhere and is least specific, so it
+	// renders first — project files rendered later take precedence over it.
+	const userFiles = items
+		.filter(item => item.level === "user" && item._source.provider === "native")
+		.map(item => ({ path: item.path, content: item.content }));
 
 	// Convert project-level ContextFile items and preserve depth info
-	const files = result.items
-		.filter(item => (item as ContextFile).level === "project")
-		.map(item => {
-			const contextFile = item as ContextFile;
-			return {
-				path: contextFile.path,
-				content: contextFile.content,
-				depth: contextFile.depth,
-			};
-		});
+	const projectFiles = items
+		.filter(item => item.level === "project")
+		.map(item => ({
+			path: item.path,
+			content: item.content,
+			depth: item.depth,
+		}));
 
 	// Sort by depth (descending): higher depth (farther from cwd) comes first,
 	// so files closer to cwd appear later and are more prominent
-	files.sort((a, b) => {
+	projectFiles.sort((a, b) => {
 		const depthA = a.depth ?? -1;
 		const depthB = b.depth ?? -1;
 		return depthB - depthA;
 	});
 
-	return dedupeExactContextFiles(files);
+	return dedupeExactContextFiles([...userFiles, ...projectFiles]);
 }
 
 /**
@@ -368,6 +376,13 @@ export interface BuildSystemPromptOptions {
 	secretsEnabled?: boolean;
 	/** Pre-loaded workspace tree (skips discovery if provided). May be a Promise to allow early kick-off. */
 	workspaceTree?: WorkspaceTree | Promise<WorkspaceTree>;
+	/**
+	 * Render a trimmed role-agent base prompt for subagent sessions: omits the
+	 * workflow-surface/routing/self-awareness (`<gjc-runtime>`) and `<soul>` blocks
+	 * that only apply to the top-level interactive/print agent. Tool safety, repo
+	 * safety, and the completion contract are retained. Default: false.
+	 */
+	subagent?: boolean;
 }
 
 /** Result of building provider-facing system prompt messages. */
@@ -375,6 +390,29 @@ export interface BuildSystemPromptResult {
 	/** Ordered system prompt blocks. Providers should preserve entries as distinct messages/blocks. */
 	systemPrompt: string[];
 }
+export interface BuildVolatileProjectContextOptions {
+	cwd?: string;
+	date?: string;
+	workspaceTree?: WorkspaceTree;
+}
+
+export function buildVolatileProjectContext(options: BuildVolatileProjectContextOptions = {}): string {
+	const resolvedCwd = options.cwd ?? getProjectDir();
+	const date = options.date ?? new Date().toISOString().slice(0, 10);
+	return prompt
+		.render(volatileProjectContextTemplate, {
+			date,
+			cwd: shortenPath(resolvedCwd.replace(/\\/g, "/")),
+			workspaceTree: options.workspaceTree ?? {
+				rootPath: resolvedCwd,
+				rendered: "",
+				truncated: false,
+				totalLines: 0,
+				agentsMdFiles: [],
+			},
+		})
+		.trim();
+}
 
 /** Build the system prompt with tools, guidelines, and context */
 export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}): Promise<BuildSystemPromptResult> {
@@ -403,6 +441,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		eagerTasks = false,
 		secretsEnabled = false,
 		workspaceTree: providedWorkspaceTree,
+		subagent = false,
 	} = options;
 	const resolvedCwd = cwd ?? getProjectDir();
 
@@ -534,6 +573,7 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 	// Build tool descriptions for system prompt rendering.
 	const toolPromptNames = new Map<string, string>(toolNames.map(name => [name, tools?.get(name)?.wireName ?? name]));
 	const toolRefs = Object.fromEntries(toolPromptNames.entries());
+	const hasHiddenToolDiscoveryTool = Object.hasOwn(toolRefs, "search_tool_bm25");
 	const toolInfo = toolNames.map(name => ({
 		name: toolPromptNames.get(name) ?? name,
 		internalName: name,
@@ -575,13 +615,14 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 		cwd: promptCwd,
 		intentTracing: !!intentField,
 		intentField: intentField ?? "",
-		mcpDiscoveryMode,
+		mcpDiscoveryMode: mcpDiscoveryMode && hasHiddenToolDiscoveryTool,
 		hasMCPDiscoveryServers: mcpDiscoveryServerSummaries.length > 0,
 		mcpDiscoveryServerSummaries,
-		toolDiscoveryActive,
+		toolDiscoveryActive: toolDiscoveryActive && hasHiddenToolDiscoveryTool,
 		discoverableTools,
 		eagerTasks,
 		secretsEnabled,
+		subagent,
 	};
 	const rendered = prompt.render(resolvedCustomPrompt ? customSystemPromptTemplate : systemPromptTemplate, data);
 	const systemPrompt = [rendered];

package/src/task/executor.ts

@@ -22,6 +22,7 @@ import { runExtensionCompact, runExtensionSetModel } from "../extensibility/exte
 import { getSessionSlashCommands } from "../extensibility/extensions/get-commands-handler";
 import { buildAgentSubskillInjection, renderAgentPromptAdditions } from "../extensibility/gjc-plugins";
 import { buildSkillPromptMessage, type Skill } from "../extensibility/skills";
+import { sessionRoot } from "../gjc-runtime/session-layout";
 import type { HindsightSessionState } from "../hindsight/state";
 import type { LocalProtocolOptions } from "../internal-urls";
 import subagentSystemPromptTemplate from "../prompts/system/subagent-system-prompt.md" with { type: "text" };
@@ -42,6 +43,7 @@ import type { EventBus } from "../utils/event-bus";
 import { buildNamedToolChoiceResult } from "../utils/tool-choice";
 import type { WorkspaceTree } from "../workspace-tree";
 import { subprocessToolRegistry } from "./subprocess-tool-registry";
+import { persistTaskTokenLog, taskTokenLogFromUsage } from "./token-log";
 import {
 	type AgentDefinition,
 	type AgentProgress,
@@ -245,6 +247,51 @@ function previewOffendingData(value: unknown, maxLength = 500): string {
 	}
 	return serialized.length > maxLength ? `${serialized.slice(0, maxLength)}…` : serialized;
 }
+const PLACEHOLDER_YIELD_PATTERNS = [
+	/^see (?:the )?message body(?:\b|[\s—:.,-])/i,
+	/^(?:complete\s+\w+\s+)?returned inline(?:\b|[\s—:.,-])/i,
+	/^leader persists(?:\b|[\s—:.,-])/i,
+	/^caller persists(?:\b|[\s—:.,-])/i,
+];
+
+const PLACEHOLDER_YIELD_FIELD_NAMES = new Set([
+	"artifactmarkdown",
+	"finalmarkdown",
+	"fullplan",
+	"markdown",
+	"planmarkdown",
+]);
+
+function looksLikePlaceholderYieldString(value: string): boolean {
+	const trimmed = value.trim();
+	if (trimmed.length === 0 || trimmed.length > 500) return false;
+	return PLACEHOLDER_YIELD_PATTERNS.some(pattern => pattern.test(trimmed));
+}
+
+function normalizePlaceholderYieldFieldName(key: string): string {
+	return key.replace(/[^a-z0-9]/gi, "").toLowerCase();
+}
+
+function findPlaceholderYieldPath(value: unknown, path = "$", depth = 0, inspectStrings = true): string | undefined {
+	if (typeof value === "string") {
+		return inspectStrings && looksLikePlaceholderYieldString(value) ? path : undefined;
+	}
+	if (!value || typeof value !== "object" || depth > 4) return undefined;
+	if (Array.isArray(value)) {
+		for (let i = 0; i < value.length; i++) {
+			const found = findPlaceholderYieldPath(value[i], `${path}[${i}]`, depth + 1, false);
+			if (found) return found;
+		}
+		return undefined;
+	}
+	const record = value as Record<string, unknown>;
+	for (const [key, item] of Object.entries(record)) {
+		const shouldInspectString = PLACEHOLDER_YIELD_FIELD_NAMES.has(normalizePlaceholderYieldFieldName(key));
+		const found = findPlaceholderYieldPath(item, `${path}.${key}`, depth + 1, shouldInspectString);
+		if (found) return found;
+	}
+	return undefined;
+}
 
 function tryParseJsonOutput(text: string): unknown | undefined {
 	const trimmed = text.trim();
@@ -321,6 +368,8 @@ interface FinalizeSubprocessOutputResult {
 export const SUBAGENT_WARNING_NULL_YIELD = "SYSTEM WARNING: Subagent called yield with null data.";
 export const SUBAGENT_WARNING_MISSING_YIELD =
 	"SYSTEM WARNING: Subagent exited without calling yield tool after 3 reminders.";
+export const SUBAGENT_WARNING_PLACEHOLDER_YIELD =
+	"SYSTEM WARNING: Subagent yield data contains a placeholder instead of the actual result.";
 
 /** Build a schema_violation outcome — surfaced as a non-zero exit so callers treat it as a failure. */
 function buildSchemaViolationOutcome(
@@ -347,6 +396,21 @@ function buildSchemaViolationOutcome(
 	return { rawOutput, stderr: headline, exitCode: 1 };
 }
 
+function buildPlaceholderYieldOutcome(
+	placeholderPath: string,
+	data: unknown,
+): { rawOutput: string; stderr: string; exitCode: number } {
+	return buildSchemaViolationOutcome(
+		{
+			message:
+				`${SUBAGENT_WARNING_PLACEHOLDER_YIELD} Offending path: ${placeholderPath}. ` +
+				"Return the real payload in yield.result.data or persist a durable artifact receipt.",
+			missingRequired: [],
+		},
+		data,
+	);
+}
+
 export function finalizeSubprocessOutput(args: FinalizeSubprocessOutputArgs): FinalizeSubprocessOutputResult {
 	let { rawOutput, exitCode, stderr } = args;
 	const { yieldItems, reportFindings, doneAborted, signalAborted, outputSchema } = args;
@@ -376,21 +440,29 @@ export function finalizeSubprocessOutput(args: FinalizeSubprocessOutputArgs): Fi
 					stderr = `schema_violation: invalid output schema: ${schemaError}`;
 					exitCode = 1;
 				} else {
-					const verdict = validator ? validator.validate(completeData) : { ok: true as const };
-					if (!verdict.ok) {
-						const outcome = buildSchemaViolationOutcome(verdict, completeData);
+					const placeholderPath = findPlaceholderYieldPath(completeData);
+					if (placeholderPath) {
+						const outcome = buildPlaceholderYieldOutcome(placeholderPath, completeData);
 						rawOutput = outcome.rawOutput;
 						stderr = outcome.stderr;
 						exitCode = outcome.exitCode;
 					} else {
-						try {
-							rawOutput = JSON.stringify(completeData, null, 2) ?? "null";
-						} catch (err) {
-							const errorMessage = err instanceof Error ? err.message : String(err);
-							rawOutput = `{"error":"Failed to serialize yield data: ${errorMessage}"}`;
+						const verdict = validator ? validator.validate(completeData) : { ok: true as const };
+						if (!verdict.ok) {
+							const outcome = buildSchemaViolationOutcome(verdict, completeData);
+							rawOutput = outcome.rawOutput;
+							stderr = outcome.stderr;
+							exitCode = outcome.exitCode;
+						} else {
+							try {
+								rawOutput = JSON.stringify(completeData, null, 2) ?? "null";
+							} catch (err) {
+								const errorMessage = err instanceof Error ? err.message : String(err);
+								rawOutput = `{"error":"Failed to serialize yield data: ${errorMessage}"}`;
+							}
+							exitCode = 0;
+							stderr = "";
 						}
-						exitCode = 0;
-						stderr = "";
 					}
 				}
 			}
@@ -403,21 +475,29 @@ export function finalizeSubprocessOutput(args: FinalizeSubprocessOutputArgs): Fi
 		if (fallback) {
 			const completeData = normalizeCompleteData(fallback.data, reportFindings);
 			const { validator } = buildOutputValidator(outputSchema);
-			const verdict = validator ? validator.validate(completeData) : { ok: true as const };
-			if (!verdict.ok) {
-				const outcome = buildSchemaViolationOutcome(verdict, completeData);
+			const placeholderPath = findPlaceholderYieldPath(completeData);
+			if (placeholderPath) {
+				const outcome = buildPlaceholderYieldOutcome(placeholderPath, completeData);
 				rawOutput = outcome.rawOutput;
 				stderr = outcome.stderr;
 				exitCode = outcome.exitCode;
 			} else {
-				try {
-					rawOutput = JSON.stringify(completeData, null, 2) ?? "null";
-				} catch (err) {
-					const errorMessage = err instanceof Error ? err.message : String(err);
-					rawOutput = `{"error":"Failed to serialize fallback completion: ${errorMessage}"}`;
+				const verdict = validator ? validator.validate(completeData) : { ok: true as const };
+				if (!verdict.ok) {
+					const outcome = buildSchemaViolationOutcome(verdict, completeData);
+					rawOutput = outcome.rawOutput;
+					stderr = outcome.stderr;
+					exitCode = outcome.exitCode;
+				} else {
+					try {
+						rawOutput = JSON.stringify(completeData, null, 2) ?? "null";
+					} catch (err) {
+						const errorMessage = err instanceof Error ? err.message : String(err);
+						rawOutput = `{"error":"Failed to serialize fallback completion: ${errorMessage}"}`;
+					}
+					exitCode = 0;
+					stderr = "";
 				}
-				exitCode = 0;
-				stderr = "";
 			}
 		} else if (!hasOutputSchema && allowFallback && rawOutput.trim().length > 0) {
 			exitCode = 0;
@@ -1209,6 +1289,10 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 			const subagentAgentIdentity: AgentIdentity | undefined = options.parentTelemetry
 				? { id, name: agent.name, description: agent.description }
 				: undefined;
+			let subagentTokenTurn = 0;
+			const tokenLogDir = options.parentSessionId
+				? path.join(sessionRoot(cwd, options.parentSessionId), "token-logs")
+				: undefined;
 			const subagentTelemetry: AgentTelemetryConfig | undefined =
 				options.parentTelemetry && subagentAgentIdentity
 					? {
@@ -1217,6 +1301,27 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 							// Clear parent's conversationId; the child loop falls back to
 							// its own AgentLoopConfig.sessionId.
 							conversationId: undefined,
+							// Intentionally REPLACES (does not chain) the parent's onChatUsage:
+							// the parent handler attributes turns to subagentId "root", so
+							// chaining it here would double-log every subagent turn under root.
+							// Subagent turns are attributed to this child's id instead.
+							onChatUsage: async event => {
+								if (!tokenLogDir) return;
+								subagentTokenTurn += 1;
+								await persistTaskTokenLog(
+									taskTokenLogFromUsage(event.usage, {
+										subagentId: id,
+										agent: agent.name,
+										// Monotonic 1-based sequence per subagent session
+										// (event.stepNumber is 0-based and -1 for oneshots).
+										turn: subagentTokenTurn,
+										at: new Date().toISOString(),
+										model: event.model,
+										cost: event.cost,
+									}),
+									{ dir: tokenLogDir },
+								);
+							},
 						}
 					: undefined;
 

package/src/task/fork-context-advisory.ts

@@ -1,3 +1,4 @@
+import { FORK_CONTEXT_TOKEN_BUDGET_BY_MODE } from "./fork-context-budget";
 import type { ForkContextMode } from "./types";
 
 export interface ForkContextAdvisory {
@@ -12,13 +13,7 @@ export interface ForkContextAdvisory {
  * many parent-context tokens each mode may clone into the child; the actual
  * cloned amount can never exceed the parent context itself.
  */
-const CLONE_BUDGET_BY_MODE = {
-	none: 0,
-	receipt: 2000,
-	"last-turn": 4000,
-	bounded: 8000,
-	full: 15000,
-} as const satisfies Record<ForkContextMode, number>;
+const CLONE_BUDGET_BY_MODE = FORK_CONTEXT_TOKEN_BUDGET_BY_MODE;
 
 const RECEIPT_TRIGGERS = [
 	{ pattern: /as discussed/i, reason: "prior-session-reference:as-discussed" },

package/src/task/fork-context-budget.ts

@@ -0,0 +1,9 @@
+import type { ForkContextMode } from "./types";
+
+export const FORK_CONTEXT_TOKEN_BUDGET_BY_MODE = {
+	none: 0,
+	receipt: 2000,
+	"last-turn": 4000,
+	bounded: 8000,
+	full: 15000,
+} as const satisfies Record<ForkContextMode, number>;

package/src/task/index.ts

@@ -48,6 +48,7 @@ import * as git from "../utils/git";
 import { discoverAgents, filterVisibleAgents, getAgent } from "./discovery";
 import { runSubprocess } from "./executor";
 import { adviseForkContextMode } from "./fork-context-advisory";
+import { FORK_CONTEXT_TOKEN_BUDGET_BY_MODE } from "./fork-context-budget";
 import { getTaskIdValidationError, validateAllocatedTaskId } from "./id";
 import { AgentOutputManager } from "./output-manager";
 import { mapWithConcurrencyLimit, Semaphore } from "./parallel";
@@ -303,11 +304,11 @@ function resolveForkSeedParamsForMode(
 		case "none":
 			return undefined;
 		case "receipt":
-			return { maxMessages: 1, maxTokens: 64 };
+			return { maxMessages: 1, maxTokens: FORK_CONTEXT_TOKEN_BUDGET_BY_MODE.receipt };
 		case "last-turn":
-			return { maxMessages: 2, maxTokens: 250 };
+			return { maxMessages: 2, maxTokens: FORK_CONTEXT_TOKEN_BUDGET_BY_MODE["last-turn"] };
 		case "bounded":
-			return { maxMessages: capMessages(50), maxTokens: 250 };
+			return { maxMessages: capMessages(50), maxTokens: FORK_CONTEXT_TOKEN_BUDGET_BY_MODE.bounded };
 		case "full":
 			return { maxMessages: capMessages(500), maxTokens: resolveForkContextMaxTokens(configuredMaxTokens, model) };
 		default:

package/src/task/output-manager.ts

@@ -14,6 +14,8 @@ function escapeRegExp(value: string): string {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+const RESERVED_OUTPUT_EXTENSIONS_PATTERN = "(?:md|jsonl|patch)";
+
 /**
  * Manages agent output ID allocation to ensure uniqueness.
  *
@@ -62,8 +64,8 @@ export class AgentOutputManager {
 		}
 
 		const pattern = this.#parentPrefix
-			? new RegExp(`^${escapeRegExp(this.#parentPrefix)}\\.(\\d+)-.*\\.md$`)
-			: /^(\d+)-.*\.md$/;
+			? new RegExp(`^${escapeRegExp(this.#parentPrefix)}\\.(\\d+)-.*\\.${RESERVED_OUTPUT_EXTENSIONS_PATTERN}$`)
+			: new RegExp(`^(\\d+)-.*\\.${RESERVED_OUTPUT_EXTENSIONS_PATTERN}$`);
 
 		let maxId = -1;
 		for (const file of files) {

package/src/task/token-log.test.ts

@@ -0,0 +1,188 @@
+import { describe, expect, it } from "bun:test";
+import { appendFile, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { GJC_SESSION_ACTIVITY_FILE, sessionRoot } from "../gjc-runtime/session-layout";
+import {
+	computeCacheHitRate,
+	persistTaskTokenLog,
+	readTaskTokenLogs,
+	resolveTaskTokenLogDir,
+	taskTokenLogFromChat,
+	taskTokenLogFromUsage,
+} from "./token-log";
+
+async function withTempDir<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+	const dir = await mkdtemp(join(tmpdir(), "gjc-token-log-"));
+	try {
+		return await fn(dir);
+	} finally {
+		await rm(dir, { recursive: true, force: true });
+	}
+}
+
+describe("task token log", () => {
+	it("maps raw chat buckets without folding cache into input", () => {
+		const log = taskTokenLogFromChat(
+			{
+				inputTokens: 100,
+				outputTokens: 20,
+				cachedInputTokens: 30,
+				cacheWriteTokens: 5,
+				costUsd: 0.25,
+			},
+			{
+				subagentId: "root",
+				agent: "main",
+				turn: 1,
+				at: "2026-01-01T00:00:00.000Z",
+				model: "model-a",
+			},
+		);
+
+		expect(log.input).toBe(100);
+		expect(log.output).toBe(20);
+		expect(log.cacheRead).toBe(30);
+		expect(log.cacheWrite).toBe(5);
+		expect(log.totalTokens).toBe(155);
+		expect(log.cost).toBe(0.25);
+		expect(log.model).toBe("model-a");
+	});
+
+	it("maps zero-cache chat buckets without inventing cache tokens", () => {
+		const log = taskTokenLogFromChat(
+			{ inputTokens: 7, outputTokens: 3, cachedInputTokens: 0, cacheWriteTokens: 0 },
+			{ subagentId: "root", turn: 2, at: "2026-01-01T00:00:02.000Z" },
+		);
+
+		expect(log.input).toBe(7);
+		expect(log.output).toBe(3);
+		expect(log.cacheRead).toBe(0);
+		expect(log.cacheWrite).toBe(0);
+		expect(log.totalTokens).toBe(10);
+	});
+
+	it("keeps large cache-only reads out of input and hits the cache-rate upper boundary", () => {
+		const log = taskTokenLogFromChat(
+			{ inputTokens: 0, outputTokens: 2, cachedInputTokens: 1_000_000_000, cacheWriteTokens: 0 },
+			{ subagentId: "root", turn: 3, at: "2026-01-01T00:00:03.000Z" },
+		);
+
+		expect(log.input).toBe(0);
+		expect(log.output).toBe(2);
+		expect(log.cacheRead).toBe(1_000_000_000);
+		expect(log.cacheWrite).toBe(0);
+		expect(log.totalTokens).toBe(1_000_000_002);
+		expect(computeCacheHitRate(log.input, log.cacheRead)).toBe(1);
+	});
+
+	it("persists and reads a jsonl round trip", async () => {
+		await withTempDir(async dir => {
+			const first = taskTokenLogFromChat(
+				{ inputTokens: 1, outputTokens: 2, cachedInputTokens: 3, cacheWriteTokens: 4 },
+				{ subagentId: "root", turn: 1, at: "2026-01-01T00:00:00.000Z" },
+			);
+			const second = taskTokenLogFromChat(
+				{ inputTokens: 5, outputTokens: 6, cachedInputTokens: 7, cacheWriteTokens: 8 },
+				{ subagentId: "child", agent: "executor", turn: 1, at: "2026-01-01T00:00:01.000Z" },
+			);
+
+			await persistTaskTokenLog(first, { dir });
+			await persistTaskTokenLog(second, { dir });
+
+			expect(await readTaskTokenLogs(dir)).toEqual([first, second]);
+		});
+	});
+
+	it("prefers the current session manager over a stale latest-active session", async () => {
+		await withTempDir(async cwd => {
+			const currentSessionId = "current-session";
+			const staleSessionId = "stale-session";
+			for (const [sessionId, updatedAt] of [
+				[currentSessionId, "2026-01-01T00:00:00.000Z"],
+				[staleSessionId, "2026-01-01T00:00:10.000Z"],
+			] as const) {
+				const markerPath = join(sessionRoot(cwd, sessionId), GJC_SESSION_ACTIVITY_FILE);
+				await mkdir(join(markerPath, ".."), { recursive: true });
+				await writeFile(
+					markerPath,
+					`${JSON.stringify({ session_id: sessionId, updated_at: updatedAt })}\n`,
+					"utf-8",
+				);
+			}
+
+			await expect(resolveTaskTokenLogDir(cwd, undefined, "")).resolves.toBe(
+				join(sessionRoot(cwd, staleSessionId), "token-logs"),
+			);
+			await expect(resolveTaskTokenLogDir(cwd, { getSessionId: () => currentSessionId }, "")).resolves.toBe(
+				join(sessionRoot(cwd, currentSessionId), "token-logs"),
+			);
+		});
+	});
+
+	it("missing token-log file reads as empty", async () => {
+		await withTempDir(async dir => {
+			expect(await readTaskTokenLogs(dir)).toEqual([]);
+		});
+	});
+
+	it("subtracts cache from the aggregate ChatUsageSnapshot input bucket", () => {
+		// buildUsageSnapshot sets inputTokens = rawInput + cacheRead + cacheWrite.
+		// taskTokenLogFromUsage must recover the raw (cache-excluded) input.
+		const log = taskTokenLogFromUsage(
+			{
+				inputTokens: 135,
+				outputTokens: 20,
+				totalTokens: 155,
+				cachedInputTokens: 30,
+				cacheWriteTokens: 5,
+				reasoningOutputTokens: 0,
+			},
+			{ subagentId: "root", turn: 1, at: "2026-01-01T00:00:00.000Z", cost: { usd: 0.5 } },
+		);
+
+		expect(log.input).toBe(100);
+		expect(log.cacheRead).toBe(30);
+		expect(log.cacheWrite).toBe(5);
+		expect(log.output).toBe(20);
+		expect(log.totalTokens).toBe(155);
+		expect(log.cost).toBe(0.5);
+	});
+
+	it("clamps aggregate input underflow to zero", () => {
+		const log = taskTokenLogFromUsage(
+			{
+				inputTokens: 10,
+				outputTokens: 1,
+				totalTokens: 10,
+				cachedInputTokens: 8,
+				cacheWriteTokens: 5,
+				reasoningOutputTokens: undefined,
+			},
+			{ subagentId: "root", turn: 1, at: "2026-01-01T00:00:00.000Z" },
+		);
+
+		expect(log.input).toBe(0);
+	});
+
+	it("skips a torn or corrupt jsonl line instead of throwing", async () => {
+		await withTempDir(async dir => {
+			const valid = taskTokenLogFromChat(
+				{ inputTokens: 1, outputTokens: 2, cachedInputTokens: 3, cacheWriteTokens: 4 },
+				{ subagentId: "root", turn: 1, at: "2026-01-01T00:00:00.000Z" },
+			);
+			await persistTaskTokenLog(valid, { dir });
+			// A partially-flushed / corrupt trailing line must not abort the read.
+			await appendFile(join(dir, "token-log.jsonl"), '{"subagentId":"root","turn":2,', "utf-8");
+
+			expect(await readTaskTokenLogs(dir)).toEqual([valid]);
+		});
+	});
+
+	it("throws when a non-empty log has no valid entries", async () => {
+		await withTempDir(async dir => {
+			await appendFile(join(dir, "token-log.jsonl"), "not json\n{}\n", "utf-8");
+			await expect(readTaskTokenLogs(dir)).rejects.toThrow(/corrupt token-log/);
+		});
+	});
+});