@sayknow-cli/coding-agent 0.3.7 → 0.3.8

package/src/task/executor.ts

@@ -34,6 +34,7 @@ import type { AuthStorage } from "../session/auth-storage";
 import { SKILL_PROMPT_MESSAGE_TYPE } from "../session/messages";
 import { SessionManager } from "../session/session-manager";
 import { truncateTail } from "../session/streaming-output";
+import { sessionRoot } from "../skc-runtime/session-layout";
 import type { ContextFileEntry } from "../tools";
 import { jtdToJsonSchema, normalizeSchema } from "../tools/jtd-to-json-schema";
 import { type ReportFindingDetails, toReviewFinding } from "../tools/review";
@@ -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,
@@ -139,6 +141,8 @@ export interface ExecutorOptions {
 	artifactsDir?: string;
 	/** Path to parent conversation context file */
 	contextFile?: string;
+	/** Whether the parent runtime actually exposes IRC coordination. */
+	ircAvailable?: boolean;
 	eventBus?: EventBus;
 	contextFiles?: ContextFileEntry[];
 	skills?: Skill[];
@@ -243,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();
@@ -319,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(
@@ -345,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;
@@ -374,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 = "";
 					}
 				}
 			}
@@ -401,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;
@@ -623,7 +705,7 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 				: agent.spawns.join(",");
 
 	const lspEnabled = enableLsp ?? true;
-	const ircEnabled = subagentSettings.get("irc.enabled") === true;
+	const ircEnabled = options.ircAvailable === true;
 	const contextFileForPrompt = ircEnabled ? undefined : options.contextFile;
 	const skipPythonPreflight = Array.isArray(toolNames) && !toolNames.includes("eval");
 
@@ -1207,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
 					? {
@@ -1215,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;
 
@@ -1231,9 +1338,10 @@ export async function runSubprocess(options: ExecutorOptions): Promise<SingleRes
 
 			const { normalized: normalizedOutputSchema } = normalizeSchema(outputSchema);
 
-			const forkContextNotice = options.forkContextSeed
-				? `This subagent was started with a forked snapshot of the parent conversation. Included ${options.forkContextSeed.metadata.includedMessages} message(s), skipped ${options.forkContextSeed.metadata.skippedMessages}, approximately ${options.forkContextSeed.metadata.approximateTokens} tokens. The snapshot is not live; use IRC for live coordination when enabled.`
-				: "";
+			const forkContextNotice =
+				options.forkContextSeed && options.forkContextSeed.metadata.includedMessages > 0
+					? `This subagent was started with a forked snapshot of the parent conversation. Included ${options.forkContextSeed.metadata.includedMessages} message(s), skipped ${options.forkContextSeed.metadata.skippedMessages}, approximately ${options.forkContextSeed.metadata.approximateTokens} tokens. The snapshot is not live.${ircEnabled ? " Use IRC for live coordination." : " Rely on the explicit assignment and supplied context for coordination."}`
+					: "";
 
 			const agentSubskillBlock = await buildAgentSubskillInjection({
 				cwd,

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";
@@ -178,6 +179,10 @@ export {
 /**
  * Render the tool description from a cached agent list and current settings.
  */
+function hasAvailableIrcTool(session: ToolSession): boolean {
+	return session.settings.get("irc.enabled") === true && session.getToolByName?.("irc") !== undefined;
+}
+
 function renderDescription(
 	agents: AgentDefinition[],
 	maxConcurrency: number,
@@ -299,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:
@@ -381,7 +386,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 			true,
 			disabledAgents,
 			this.#getTaskSimpleMode(),
-			this.session.settings.get("irc.enabled") === true,
+			hasAvailableIrcTool(this.session),
 			this.session.getSessionSpawns() ?? "*",
 		);
 	}
@@ -814,7 +819,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 				? ` Failed to schedule ${failedSchedules.length} task${failedSchedules.length === 1 ? "" : "s"}.`
 				: "";
 
-		const ircEnabled = this.session.settings.get("irc.enabled") === true;
+		const ircEnabled = hasAvailableIrcTool(this.session);
 		const taskIdByItemId = new Map<string, string>();
 		for (let i = 0; i < taskItems.length; i++) {
 			taskIdByItemId.set(taskItems[i].id, uniqueIds[i]);
@@ -1171,7 +1176,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 			// Write parent conversation context for subagents. When IRC is available,
 			// subagents should ask live peers instead of reading a stale markdown dump.
 			await fs.mkdir(effectiveArtifactsDir, { recursive: true });
-			const shouldWriteConversationContext = this.session.settings.get("irc.enabled") !== true;
+			const shouldWriteConversationContext = !hasAvailableIrcTool(this.session);
 			const compactContext = shouldWriteConversationContext ? this.session.getCompactContext?.() : undefined;
 			let contextFilePath: string | undefined;
 			if (compactContext) {
@@ -1298,6 +1303,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						persistArtifacts: !!artifactsDir,
 						artifactsDir: effectiveArtifactsDir,
 						contextFile: contextFilePath,
+						ircAvailable: hasAvailableIrcTool(this.session),
 						enableLsp: subagentLspEnabled,
 						signal,
 						eventBus: this.session.eventBus,
@@ -1360,6 +1366,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						persistArtifacts: !!artifactsDir,
 						artifactsDir: effectiveArtifactsDir,
 						contextFile: contextFilePath,
+						ircAvailable: hasAvailableIrcTool(this.session),
 						enableLsp: subagentLspEnabled,
 						signal,
 						eventBus: this.session.eventBus,

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.
  *
@@ -24,7 +26,7 @@ function escapeRegExp(value: string): string {
  */
 export class AgentOutputManager {
 	#nextId = 0;
-	#initialized = false;
+	#initPromise: Promise<void> | undefined;
 	readonly #getArtifactsDir: () => string | null;
 	readonly #parentPrefix: string | undefined;
 
@@ -33,14 +35,24 @@ export class AgentOutputManager {
 		this.#parentPrefix = options?.parentPrefix;
 	}
 
+	/**
+	 * Memoize the in-flight scan so concurrent `allocate*`/`peekNextIndex`
+	 * calls await the SAME `readdir` before `#nextId` is derived. Assigning the
+	 * promise synchronously (before any `await`) closes the TOCTOU window where a
+	 * boolean "initialized" flag, flipped ahead of the awaited scan, let a second
+	 * caller allocate at `#nextId === 0` while the first was still scanning —
+	 * producing duplicate indices that overwrite prior outputs on resume.
+	 */
+	#ensureInitialized(): Promise<void> {
+		this.#initPromise ??= this.#scanExistingOutputs();
+		return this.#initPromise;
+	}
+
 	/**
 	 * Scan existing agent output files to find the next available ID.
 	 * This ensures we don't overwrite outputs when resuming a session.
 	 */
-	async #ensureInitialized(): Promise<void> {
-		if (this.#initialized) return;
-		this.#initialized = true;
-
+	async #scanExistingOutputs(): Promise<void> {
 		const dir = this.#getArtifactsDir();
 		if (!dir) return;
 
@@ -52,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) {
@@ -103,6 +115,6 @@ export class AgentOutputManager {
 	 */
 	reset(): void {
 		this.#nextId = 0;
-		this.#initialized = false;
+		this.#initPromise = undefined;
 	}
 }

package/src/task/receipt.ts

@@ -77,6 +77,28 @@ function truncateText(value: string | undefined, maxChars: number): string | und
 	return value.length > maxChars ? value.slice(0, maxChars) : value;
 }
 
+const SAFE_REVIEW_SEVERITIES = new Set(["blocker", "critical", "error", "high", "medium", "warning", "low", "info"]);
+const SAFE_REVIEW_PRIORITIES = new Set(["P0", "P1", "P2", "P3"]);
+
+function normalizeReviewFindingSeverity(severity: unknown, priority: unknown): string | undefined {
+	if (typeof severity === "string") {
+		const normalizedPriority = severity.toUpperCase();
+		if (SAFE_REVIEW_PRIORITIES.has(normalizedPriority)) return normalizedPriority;
+		const normalizedSeverity = severity.toLowerCase();
+		if (SAFE_REVIEW_SEVERITIES.has(normalizedSeverity)) return normalizedSeverity;
+	}
+	if (typeof priority === "string") {
+		const normalizedPriority = priority.toUpperCase();
+		if (SAFE_REVIEW_PRIORITIES.has(normalizedPriority)) return normalizedPriority;
+		const normalizedSeverity = priority.toLowerCase();
+		if (SAFE_REVIEW_SEVERITIES.has(normalizedSeverity)) return normalizedSeverity;
+	}
+	if (typeof priority === "number" && Number.isInteger(priority) && priority >= 0 && priority <= 3) {
+		return `P${priority}`;
+	}
+	return undefined;
+}
+
 function buildSafeSynopsis(raw: SingleResult, outputRef: TaskResultReceipt["outputRef"]): string {
 	const status = getStatus(raw);
 	if (raw.modelSubstitutionWarning) {
@@ -117,19 +139,16 @@ function buildReview(raw: SingleResult): TaskResultReceipt["review"] | undefined
 	const rawFindings = Array.isArray(data.report_finding) ? data.report_finding : [];
 	const findings = rawFindings.slice(0, 20).map(item => {
 		const value = item && typeof item === "object" ? (item as Record<string, unknown>) : {};
-		const severity =
-			typeof value.severity === "string"
-				? value.severity
-				: typeof value.priority === "string"
-					? value.priority
-					: undefined;
+		const severity = normalizeReviewFindingSeverity(value.severity, value.priority);
 		const summaryValue = value.summary ?? value.title ?? value.message ?? value.body ?? "finding";
 		return { severity, summary: truncateText(String(summaryValue), 200) ?? "finding" };
 	});
 	if (!reviewYield && findings.length === 0) return undefined;
 	return {
-		overallCorrectness:
+		overallCorrectness: truncateText(
 			typeof reviewYield?.overall_correctness === "string" ? reviewYield.overall_correctness : undefined,
+			200,
+		),
 		findingCount: rawFindings.length,
 		findings: findings.length > 0 ? findings : undefined,
 	};

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 { SKC_SESSION_ACTIVITY_FILE, sessionRoot } from "../skc-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(), "skc-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), SKC_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/);
+		});
+	});
+});