@tallshort/pi-inclusive-cost 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Serhii Chernenko
+Copyright (c) 2026 tallshort
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,148 @@
-# Temporary Holding Version
+# @tallshort/pi-inclusive-cost
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@tallshort/pi-inclusive-cost?logo=npm)](https://www.npmjs.com/package/@tallshort/pi-inclusive-cost)
+[![npm downloads](https://img.shields.io/npm/dm/@tallshort/pi-inclusive-cost?logo=npm)](https://www.npmjs.com/package/@tallshort/pi-inclusive-cost)
+[![CI](https://github.com/tallshort/pi-inclusive-cost/actions/workflows/ci.yml/badge.svg)](https://github.com/tallshort/pi-inclusive-cost/actions/workflows/ci.yml)
+[![GitHub stars](https://img.shields.io/github/stars/tallshort/pi-inclusive-cost?style=flat)](https://github.com/tallshort/pi-inclusive-cost/stargazers)
+
+A [Pi coding agent](https://pi.dev) extension that shows **inclusive cost** for the current session, including supported subagents and delegated workflows, not just the main thread.
+
+> [!NOTE]
+> This repository is the `tallshort`-maintained fork of [serhii-chernenko/pi-inclusive-cost](https://github.com/serhii-chernenko/pi-inclusive-cost), which remains the upstream project.
+
+## What this fork adds
+
+Compared with upstream, this fork adds:
+
+- Attributed cost collectors for Pi Fabric, Pi Taskflow, and a broad set of named subagent extensions.
+- Strict current-chat attribution with stable contribution identities, cumulative-cost deduplication, and no blanket scans of unrelated shared histories.
+- Lifecycle-aware accounting for persisted foreground, background, and nested work, plus backend-specific resume, cache, and recompute semantics.
+- A modular collector architecture with backend-specific source precedence, conservative fallbacks, and regression coverage.
+
+Example statusline with illustrative values:
+
+```text
+↑1.9M ↓176k R62M CH8.9% $34.609 (sub) 66.8%/272k (auto)             (openai-codex) gpt-5.6-sol • medium
+$37.72 (incl)
+```
+
+## The problem
+
+Pi's built-in statusline sums cost from the current session's own message history only. If you use a subagent extension (e.g. one that spawns background workers, reviewers, researchers, etc.), those subagent sessions are written to their own nested session files and are invisible to the built-in cost total — so the number in your statusline can understate what a task actually cost by a wide margin.
+
+## What this does
+
+The extension rebuilds a deduplicated total from persisted records attributable to the current chat.
+
+### Collectors
+
+| Collector | Attributed source |
+| --- | --- |
+| Standard Pi sessions | Root and linked child Session JSONL files containing `usage.cost.total` |
+| `@pi-archimedes/subagent` | Attributed synchronous `details.results[].usage.cost` records |
+| `pi-subagents-lite` | Foreground `Agent` tool-result cost and attributed background completion messages |
+| `@ian-pascoe/pi-minimal-subagents` | Root Session registry `turn-settled` usage, keyed by stable agent and turn identity |
+| `pi-better-subagents` | Attributed launch run IDs and their retained sandboxed per-run standard child Session usage |
+| Explicit Herdr child Sessions | Attributed `pi-herdr-agents` launch paths and `@henryqw/pi-subagent` direct-session results |
+| `@bacnh85/pi-subagent` | Attributed foreground tool-result usage and background completion messages |
+| `pi-subagents-j0k3r` | Attributed `subagent_*` tool-result task usage, with an explicitly referenced standard session as fallback |
+| `@ferris1225/pi-subagents` | Run IDs from attributed launch results and cumulative usage from persisted `subagent_status` results; explicit standard sessions are fallback only |
+| Pi Dynamic Workflows | Attributed `workflow` run IDs and cumulative cost from the run's small persisted v2 head |
+| Pi Fabric | Run IDs and cumulative usage from `fabric_exec` rendered output or structured agent audit details, with attributable `.fabric` exports as fallback |
+| Pi Taskflow | Run IDs returned by `taskflow`, then usage-bearing trace events or an older snapshot fallback |
+
+### Supported extensions
+
+| Extension | Collector | Notes |
+| --- | --- | --- |
+| Standard full-session subagent modes | Standard Pi sessions | Layout-based compatibility for nested `session.jsonl` or parent-linked sibling sessions; not a blanket claim about any package named `pi-subagents` |
+| `@pi-archimedes/subagent` | `@pi-archimedes/subagent` | Synchronous results expose stable child Session IDs and usage without persisting child Session files |
+| `pi-subagents-lite` | `pi-subagents-lite` | Foreground calls persist cumulative cost; background completions are linked to attributed launch IDs |
+| `@ian-pascoe/pi-minimal-subagents` | `@ian-pascoe/pi-minimal-subagents` | Registry V2 settled-turn usage is authoritative; legacy V1 records and child Session totals are not collected |
+| `pi-better-subagents` | `pi-better-subagents` | Strictly attributed retained sandboxed child Sessions only; shared session trees and large `output.log` files are not scanned |
+| `@henryqw/pi-subagent` | Explicit Herdr child Sessions | Direct mode only: attributed launch and completion records identify standard child Sessions; isolated mode has no collectible persisted usage |
+| `pi-herdr-agents` | Explicit Herdr child Sessions | Attributed launch records identify standard child Sessions; fork-inherited parent entries are excluded |
+| `@gotgenes/pi-subagents` | Standard Pi sessions | Independently maintained hard fork of `@tintinweb/pi-subagents`; supported through its `tasks/*.jsonl` layout |
+| `@nklisch/pi-subagents` | Standard Pi sessions | Maintained MIT fork of `@gotgenes/pi-subagents`; retains the same `tasks/*.jsonl` persistence while adding ordered lifecycle interception |
+| `@xzzpig/pi-subagents` | Standard Pi sessions | Fork of `nicobailon/pi-subagents`; persisted native children use the same nested-session mechanism |
+| `oira666_pi-subagent` | Standard Pi sessions | Persisted RPC children use nested `subagents/.../session.jsonl` files under the parent session stem |
+| `@bacnh85/pi-subagent` | `@bacnh85/pi-subagent` | In-memory foreground results are keyed by parent tool call; background completions are keyed by task ID |
+| `pi-subagents-j0k3r` | `pi-subagents-j0k3r` | Parent tool results provide stable task identities and usage; explicit child sessions are fallback only |
+| `@ferris1225/pi-subagents` | `@ferris1225/pi-subagents` | Launch results establish stable run IDs; persisted status results provide usage; detached completion text is not parsed |
+| Pi Dynamic Workflows | Pi Dynamic Workflows | Exact parent Session identity and run ID locate a small cumulative run head; large event logs are not read |
+| Pi Fabric | Pi Fabric | Requires the parent chat to retain the Fabric run ID in rendered output or structured audit details |
+| Pi Taskflow | Pi Taskflow | Requires the parent chat to retain the Taskflow run ID |
+
+Support for a named subagent extension means its attributable persisted mode is covered; in-memory or explicitly non-persistent modes remain out of scope. In particular, `@henryqw/pi-subagent` isolated mode uses `--no-session` and does not persist its internally observed usage in the parent result, so only direct mode is collected. The generic first row is based only on the standard persisted layout.
+
+The statusline shows `$X.XX (incl)` whenever attributable delegated work exists. `/cost` keeps the compact three-line summary: `Direct (this thread)`, `Inclusive (+ subagents & delegated work)`, and `Subagent/delegated contributions folded in`. Refresh happens on session start, at the end of every turn, and when the agent run ends.
+
+See [`docs/DESIGN.md`](docs/DESIGN.md) for persistence layouts, source precedence, resume/cache/recompute behavior, contribution keys, and deduplication invariants.
+
+It intentionally does not perform its own token-based cost estimation—it sums monetary cost fields already persisted by supported runtimes, such as Session `usage.cost.total` or Dynamic Workflows `tokenUsage.cost`. These values are themselves **client-side estimates** computed from reported token counts and local model pricing, not authoritative provider bills. When a runtime marks token usage as estimated but has no monetary cost, that unknown cost is omitted rather than treated as free.
+
+## Install
+
+```bash
+pi install npm:@tallshort/pi-inclusive-cost
+```
+
+or directly from source:
+
+```bash
+pi install git:github.com/tallshort/pi-inclusive-cost
+```
+
+Restart Pi, or run `/reload`.
+
+## Commands
+
+- `/cost` — direct cost, inclusive cost from subagents and other delegated work, and the number of subagent/delegated contributions folded into the total.
+
+## Not currently collected
+
+| Extension | Reason |
+| --- | --- |
+| `@esso0428/pi-subagents` | Defaults to in-memory children and custom `.output` transcripts without attributable priced usage |
+| `@narumitw/pi-subagents` | Starts children with `--no-session` and exposes neither stable `jobId + usage.cost` data nor attributable child Sessions; upstream support is required first |
+| `wj-pi-subagents` | Starts children with `--no-session`; child replies contain text but no usage/cost |
+
+`@tintinweb/pi-subagents` is intentionally not given a package-specific collector: its optional `reportUsage` mode reports child cost through the parent Pi tool result, so collecting the same child usage again could double-count it.
+
+The unscoped `pi-subagents` name in the preserved upstream limitation below did not include a package identity or version range. Treat it as a description of the observed artifacts-only layout, not as a claim about every similarly named npm package or fork.
+
+## Known limitation: newer artifacts-only subagent storage isn't covered yet
+
+`pi-subagents` has changed how it persists at least one subagent mode (parallel/fork batches) between versions. Older versions always wrote a full session file for every subagent invocation, nested or as a flat sibling — the two mechanisms above. A newer mode instead writes only to `<project-cwd>/.pi-subagents/artifacts/<runId>_<agent>_<index>_meta.json` (plus a `_transcript.jsonl` with a different record schema), with **no corresponding session file anywhere** — nested or sibling. That cost is currently invisible to this extension.
+
+This wasn't skipped by accident: there's no reliable way to attribute a given artifacts file back to one specific chat. The only correlation lead found (a `session_info` entry naming the subagent, written into the parent's own session file) turns out to depend on the `pi-intercom` package being installed — not a safe thing to build a core feature on. A worktree-wide sum without that correlation would also reintroduce exactly the cross-chat over-counting problem this extension was built to avoid in the first place (multiple unrelated chats in the same project folder getting lumped together). Until there's a first-party, version-stable way to scope this correctly, it's left uncovered rather than shipped fragile or wrong.
+
+Collector-specific limitations for Fabric and Taskflow are documented in [`docs/DESIGN.md`](docs/DESIGN.md).
+
+## Don't expect this to match your provider's billing dashboard exactly
+
+`usage.cost.total` is computed locally from token counts and a local price table — it is not your provider's authoritative bill. Even with accurate, current pricing, a locally-summed total can diverge from what your provider's own usage dashboard reports, for reasons outside this extension's control: reporting lag on the provider's side, per-request billing multipliers instead of per-token metering, or negotiated/enterprise rates that differ from the public price list. If you need a number that reconciles with billing, treat this as a fast local signal, not a substitute for your provider's own dashboard.
+
+For a full project-wide audit across every chat (not just the current one), use a dedicated usage-dashboard tool — this extension is meant for a quick, live, per-chat signal in the statusline.
+
+## Releases
+
+The first scoped release must create the public npm package before Trusted Publishing can be attached. From the clean release commit:
+
+```bash
+npm login
+npm publish --access public
+npm trust github '@tallshort/pi-inclusive-cost' \
+  --repo tallshort/pi-inclusive-cost \
+  --file publish.yml \
+  --allow-publish \
+  --yes
+git tag v0.2.0
+git push origin main v0.2.0
+```
+
+For later releases, bump `version` in `package.json`, commit, then push the matching tag. The tag workflow type-checks, tests, publishes through npm Trusted Publishing, and creates a GitHub Release with generated notes. It skips npm publication when that exact package version already exists, so the first-release tag only creates the matching GitHub Release. No npm token is stored in the repository; `npm trust` requires npm CLI ≥11.15.0.
+
+## License
+
+MIT

package/collectors/archimedes.ts

@@ -0,0 +1,115 @@
+import { isDeepStrictEqual } from "node:util";
+
+import {
+	asRecord,
+	finiteNonNegative,
+	setGreatestContribution,
+	sumContributions,
+	type AttributedToolResult,
+	type CollectorSummary,
+} from "./shared.js";
+
+interface ArchimedesResult {
+	identity: string;
+	record: Record<string, unknown>;
+}
+
+export function collectArchimedes(toolResults: AttributedToolResult[]): CollectorSummary {
+	const contributions = new Map<string, number>();
+	const parentReported = new Set<string>();
+
+	for (const result of toolResults) {
+		if (reportedToolCost(result.usage) === undefined) continue;
+		for (const child of archimedesResults(result)) parentReported.add(child.identity);
+	}
+
+	for (const result of toolResults) {
+		for (const child of archimedesResults(result)) {
+			if (parentReported.has(child.identity)) continue;
+			const cost = finiteNonNegative(asRecord(child.record.usage)?.cost);
+			if (cost !== undefined) setGreatestContribution(contributions, child.identity, cost);
+		}
+	}
+
+	return {
+		cost: sumContributions(contributions),
+		count: contributions.size,
+	};
+}
+
+function archimedesResults(result: AttributedToolResult): ArchimedesResult[] {
+	if (result.toolName !== "subagent") return [];
+	const details = asRecord(result.details);
+	if (!details || !Array.isArray(details.results) || !Array.isArray(details.progress)) return [];
+	if (details.mode !== "single" && details.mode !== "parallel") return [];
+	if (details.progress.length !== details.results.length) return [];
+
+	const children: ArchimedesResult[] = [];
+	for (let index = 0; index < details.results.length; index++) {
+		const record = asRecord(details.results[index]);
+		const progress = asRecord(details.progress[index]);
+		if (!isArchimedesResult(record, progress)) continue;
+		const identity = archimedesIdentity(result, record, index);
+		if (identity) children.push({ identity, record });
+	}
+	return children;
+}
+
+function isArchimedesResult(
+	result: Record<string, unknown> | null,
+	detailsProgress: Record<string, unknown> | null,
+): result is Record<string, unknown> {
+	if (!result || !detailsProgress || typeof result.agent !== "string" || typeof result.task !== "string") return false;
+	if (typeof result.exitCode !== "number") return false;
+	if (result.childSessionId !== undefined && typeof result.childSessionId !== "string") return false;
+	if (result.model !== undefined && typeof result.model !== "string") return false;
+	if (result.finalOutput !== undefined && typeof result.finalOutput !== "string") return false;
+	if (result.error !== undefined && typeof result.error !== "string") return false;
+
+	const progress = asRecord(result.progress);
+	if (!progress || (progress.status !== "completed" && progress.status !== "failed")) return false;
+	if (progress.agent !== result.agent || progress.task !== result.task) return false;
+	for (const field of ["toolCount", "inputTokens", "outputTokens", "tokens", "cost", "durationMs"] as const) {
+		if (finiteNonNegative(progress[field]) === undefined) return false;
+	}
+	if (!isDeepStrictEqual(detailsProgress, progress)) return false;
+
+	const summary = asRecord(result.progressSummary);
+	if (!summary || finiteNonNegative(summary.toolCount) === undefined
+		|| finiteNonNegative(summary.tokens) === undefined
+		|| finiteNonNegative(summary.durationMs) === undefined) return false;
+	if (summary.toolCount !== progress.toolCount || summary.tokens !== progress.tokens
+		|| summary.durationMs !== progress.durationMs) return false;
+
+	const usage = asRecord(result.usage);
+	if (result.usage !== undefined && !isArchimedesUsage(usage)) return false;
+	return true;
+}
+
+function archimedesIdentity(
+	result: AttributedToolResult,
+	child: Record<string, unknown>,
+	index: number,
+): string | undefined {
+	if (typeof child.childSessionId === "string" && isPiSessionId(child.childSessionId)) {
+		return `archimedes:${child.childSessionId.toLowerCase()}`;
+	}
+	if (!result.toolCallId) return undefined;
+	return `archimedes-fallback:${result.sessionFile}:${result.toolCallId}:${index}`;
+}
+
+function isArchimedesUsage(usage: Record<string, unknown> | null): boolean {
+	if (!usage) return false;
+	for (const field of ["input", "output", "cacheRead", "cacheWrite", "cost", "turns"] as const) {
+		if (finiteNonNegative(usage[field]) === undefined) return false;
+	}
+	return true;
+}
+
+function isPiSessionId(value: string): boolean {
+	return /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+
+function reportedToolCost(value: unknown): number | undefined {
+	return finiteNonNegative(asRecord(asRecord(value)?.cost)?.total);
+}

package/collectors/bacnh85.ts

@@ -0,0 +1,77 @@
+import {
+	asRecord,
+	finiteNonNegative,
+	setGreatestContribution,
+	sumContributions,
+	type AttributedCustomMessage,
+	type AttributedToolResult,
+	type CollectorSummary,
+} from "./shared.js";
+
+const BACNH85_TOOL_NAME = "subagent";
+const BACNH85_COMPLETION_TYPE = "pi-subagent-complete";
+
+export function collectBacnh85(
+	toolResults: AttributedToolResult[],
+	customMessages: AttributedCustomMessage[],
+): CollectorSummary {
+	const contributions = new Map<string, number>();
+
+	for (const result of toolResults) {
+		if (result.toolName !== BACNH85_TOOL_NAME || !result.toolCallId) continue;
+		if (reportedToolCost(result.usage) !== undefined) continue;
+		const details = asRecord(result.details);
+		if (!isBacnh85Details(details) || details.runner === "herdr") continue;
+		const results = details.results as unknown[];
+		for (let index = 0; index < results.length; index++) {
+			const child = asRecord(results[index]);
+			if (!isBacnh85Result(child)) continue;
+			const cost = finiteNonNegative(asRecord(child.usage)?.cost);
+			if (cost === undefined) continue;
+			setGreatestContribution(
+				contributions,
+				`bacnh85:${result.sessionFile}:${result.toolCallId}:${index}`,
+				cost,
+			);
+		}
+	}
+
+	for (const message of customMessages) {
+		if (message.customType !== BACNH85_COMPLETION_TYPE) continue;
+		const details = asRecord(message.details);
+		if (details?.background !== true || typeof details.task_id !== "string" || !details.task_id.startsWith("bg-")) continue;
+		const cost = finiteNonNegative(asRecord(details.usage)?.cost);
+		if (cost === undefined) continue;
+		setGreatestContribution(
+			contributions,
+			`bacnh85-background:${message.sessionFile}:${details.task_id}`,
+			cost,
+		);
+	}
+
+	return {
+		cost: sumContributions(contributions),
+		count: contributions.size,
+	};
+}
+
+function isBacnh85Details(details: Record<string, unknown> | null): details is Record<string, unknown> & { results: unknown[] } {
+	if (!details || !Array.isArray(details.results)) return false;
+	if (details.mode !== "single" && details.mode !== "parallel" && details.mode !== "chain") return false;
+	if (details.agentScope !== "user" && details.agentScope !== "project" && details.agentScope !== "both") return false;
+	return details.projectAgentsDir === null || typeof details.projectAgentsDir === "string";
+}
+
+function isBacnh85Result(result: Record<string, unknown> | null): result is Record<string, unknown> {
+	return result !== null
+		&& typeof result.agent === "string"
+		&& typeof result.task === "string"
+		&& typeof result.exitCode === "number"
+		&& Array.isArray(result.messages)
+		&& typeof result.stderr === "string";
+}
+
+function reportedToolCost(value: unknown): number | undefined {
+	const usage = asRecord(value);
+	return finiteNonNegative(asRecord(usage?.cost)?.total);
+}

package/collectors/better.ts

@@ -0,0 +1,316 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { StringDecoder } from "node:string_decoder";
+
+import {
+	asRecord,
+	contentText,
+	finiteNonNegative,
+	readJsonFile,
+	sumContributions,
+	type AttributedToolResult,
+	type CollectorSummary,
+} from "./shared.js";
+
+const RUN_ID = /^sa_[a-z0-9]+_[a-z0-9]+$/i;
+const MAX_SESSION_LINE_BYTES = 16 * 1024 * 1024;
+const READ_CHUNK_BYTES = 64 * 1024;
+const MAX_SESSION_CANDIDATES = 32;
+const RUN_STATUSES = new Set(["running", "completed", "failed", "killed", "orphaned", "lost"]);
+
+interface ParentIdentity {
+	sessionId: string;
+	cwd: string;
+}
+
+interface RunReference {
+	runId: string;
+	parent: ParentIdentity;
+}
+
+interface SessionScan {
+	cost?: number;
+	nested: RunReference[];
+}
+
+export function collectBetter(
+	toolResults: AttributedToolResult[],
+	registryRoot = defaultRegistryRoot(),
+): CollectorSummary {
+	const queue: RunReference[] = [];
+	const parentCache = new Map<string, ParentIdentity | null>();
+	for (const result of toolResults) {
+		const parent = sessionIdentity(result.sessionFile, parentCache);
+		if (!parent) continue;
+		for (const runId of extractRunIds(result.toolName, result.content)) queue.push({ runId, parent });
+	}
+
+	const contributions = new Map<string, number>();
+	const processed = new Set<string>();
+	const attempted = new Set<string>();
+	while (queue.length > 0) {
+		const reference = queue.shift()!;
+		const attemptKey = `${reference.runId}\0${reference.parent.sessionId}\0${reference.parent.cwd}`;
+		if (attempted.has(attemptKey) || processed.has(reference.runId)) continue;
+		attempted.add(attemptKey);
+		if (!validRunMeta(registryRoot, reference)) continue;
+		const sessionFile = findRunSessionFile(registryRoot, reference.runId);
+		if (!sessionFile) continue;
+		const scan = scanRunSession(sessionFile, reference.runId);
+		if (!scan) continue;
+		processed.add(reference.runId);
+		if (scan.cost !== undefined) contributions.set(`better:${reference.runId}`, scan.cost);
+		queue.push(...scan.nested);
+	}
+
+	return { cost: sumContributions(contributions), count: contributions.size };
+}
+
+function defaultRegistryRoot(): string {
+	let temporaryRoot = os.tmpdir();
+	try {
+		temporaryRoot = fs.realpathSync(temporaryRoot);
+	} catch {
+		// An unavailable temp root simply produces no attributable runs.
+	}
+	return path.join(temporaryRoot, "pi-better-subagents");
+}
+
+function sessionIdentity(
+	sessionFile: string,
+	cache: Map<string, ParentIdentity | null>,
+): ParentIdentity | null {
+	if (cache.has(sessionFile)) return cache.get(sessionFile) ?? null;
+	const identity = readSessionHeader(sessionFile);
+	cache.set(sessionFile, identity);
+	return identity;
+}
+
+function extractRunIds(toolName: string, content: unknown): string[] {
+	const text = contentText(content);
+	const found = new Set<string>();
+	const referencedIds = new Set([...text.matchAll(/\bsa_[a-z0-9]+_[a-z0-9]+\b/gi)].map((match) => match[0]!));
+	if (toolName === "subagent_spawn") {
+		const firstLine = text.split(/\r?\n/, 1)[0] ?? "";
+		const match = /^Subagent launched: .*\bid=(sa_[a-z0-9]+_[a-z0-9]+) \(pid \d+\)\.$/i.exec(firstLine);
+		const runId = match?.[1];
+		return runId && referencedIds.size === 1 && referencedIds.has(runId) ? [runId] : [];
+	}
+	if (toolName === "subagent_spawn_batch") {
+		const lines = text.split(/\r?\n/);
+		const header = /^Batch .+ launched ([1-9]\d*) subagent\(s\):$/.exec(lines[0] ?? "");
+		const expected = Number(header?.[1]);
+		if (!header || !Number.isSafeInteger(expected) || lines.length < expected + 1) return [];
+		for (let index = 1; index <= expected; index += 1) {
+			const match = /^• .* → (sa_[a-z0-9]+_[a-z0-9]+)(?: · .*|\s*)$/i.exec(lines[index] ?? "");
+			if (!match?.[1] || !RUN_ID.test(match[1])) return [];
+			found.add(match[1]);
+		}
+		const remainder = lines.slice(expected + 1);
+		if (remainder.some((line) => !/^Failed \(\d+\): .+$/.test(line) && !/^Skipped \(capacity\): .+$/.test(line))) return [];
+		if (found.size !== expected || referencedIds.size !== found.size
+			|| [...referencedIds].some((runId) => !found.has(runId))) return [];
+	}
+	return [...found];
+}
+
+function validRunMeta(registryRoot: string, reference: RunReference): boolean {
+	const runDirectory = containedRunDirectory(registryRoot, reference.runId);
+	if (!runDirectory) return false;
+	const metaPath = path.join(runDirectory, "meta.json");
+	try {
+		if (fs.lstatSync(metaPath).isSymbolicLink()) return false;
+		const resolvedMeta = fs.realpathSync(metaPath);
+		if (!resolvedMeta.startsWith(`${runDirectory}${path.sep}`)) return false;
+	} catch {
+		return false;
+	}
+	const meta = asRecord(readJsonFile(metaPath));
+	if (!meta || meta.id !== reference.runId || meta.sessionId !== reference.runId) return false;
+	if (typeof meta.status !== "string" || !RUN_STATUSES.has(meta.status)) return false;
+	const origin = asRecord(meta.callbackOrigin);
+	return origin?.sessionId === reference.parent.sessionId && origin.cwd === reference.parent.cwd;
+}
+
+function containedRunDirectory(registryRoot: string, runId: string): string | null {
+	const runsRoot = path.resolve(registryRoot, "runs");
+	const candidate = path.join(runsRoot, runId);
+	try {
+		if (fs.lstatSync(candidate).isSymbolicLink()) return null;
+		const resolved = fs.realpathSync(candidate);
+		return resolved.startsWith(`${runsRoot}${path.sep}`) && fs.statSync(resolved).isDirectory()
+			? resolved
+			: null;
+	} catch {
+		return null;
+	}
+}
+
+function findRunSessionFile(registryRoot: string, runId: string): string | null {
+	const sessionsRoot = path.resolve(registryRoot, "sessions");
+	const candidatePaths = new Set<string>();
+	collectJsonlFiles(path.join(sessionsRoot, runId), sessionsRoot, candidatePaths, true);
+	if (candidatePaths.size > MAX_SESSION_CANDIDATES) return null;
+	const matching = [...candidatePaths].filter((file) => readSessionHeader(file)?.sessionId === runId);
+	return matching.length === 1 ? matching[0]! : null;
+}
+
+function collectJsonlFiles(
+	candidate: string,
+	root: string,
+	found: Set<string>,
+	recurse: boolean,
+): void {
+	let stat: fs.Stats;
+	try {
+		stat = fs.lstatSync(candidate);
+	} catch {
+		return;
+	}
+	if (found.size > MAX_SESSION_CANDIDATES) return;
+	if (stat.isSymbolicLink()) return;
+	if (stat.isFile()) {
+		if (!candidate.endsWith(".jsonl")) return;
+		let resolved: string;
+		try {
+			resolved = fs.realpathSync(candidate);
+		} catch {
+			return;
+		}
+		if (resolved.startsWith(`${root}${path.sep}`)) found.add(resolved);
+		return;
+	}
+	if (!recurse || !stat.isDirectory()) return;
+	let names: string[];
+	try {
+		names = fs.readdirSync(candidate);
+	} catch {
+		return;
+	}
+	for (const name of names) {
+		if (found.size > MAX_SESSION_CANDIDATES) break;
+		collectJsonlFiles(path.join(candidate, name), root, found, true);
+	}
+}
+
+function readSessionHeader(file: string): ParentIdentity | null {
+	let identity: ParentIdentity | null = null;
+	visitJsonLines(file, (value, index) => {
+		if (index !== 0) return false;
+		identity = identityFromHeader(value);
+		return false;
+	}, 1);
+	return identity;
+}
+
+function identityFromHeader(value: unknown): ParentIdentity | null {
+	const header = asRecord(value);
+	return header?.type === "session" && typeof header.id === "string" && header.id.length > 0
+		&& typeof header.cwd === "string" && header.cwd.length > 0
+		? { sessionId: header.id, cwd: header.cwd }
+		: null;
+}
+
+function scanRunSession(file: string, expectedSessionId: string): SessionScan | null {
+	let validHeader = false;
+	let foundCost = false;
+	let cost = 0;
+	const nested: RunReference[] = [];
+	let parent: ParentIdentity | undefined;
+	const complete = visitJsonLines(file, (value, index) => {
+		if (index === 0) {
+			parent = identityFromHeader(value) ?? undefined;
+			if (!parent || parent.sessionId !== expectedSessionId) return false;
+			validHeader = true;
+			return true;
+		}
+		const record = asRecord(value);
+		if (!validHeader || record?.type !== "message") return true;
+		const message = asRecord(record.message);
+		if (message?.role === "assistant") {
+			const usage = asRecord(message.usage);
+			const costRecord = asRecord(usage?.cost);
+			const value = finiteNonNegative(costRecord?.total);
+			if (value !== undefined) {
+				foundCost = true;
+				cost += value;
+			}
+		}
+		if (message?.role === "toolResult" && typeof message.toolName === "string" && parent) {
+			for (const runId of extractRunIds(message.toolName, message.content)) nested.push({ runId, parent });
+		}
+		return true;
+	});
+	if (!complete || !validHeader) return null;
+	return { cost: foundCost ? cost : undefined, nested };
+}
+
+function visitJsonLines(
+	file: string,
+	visitor: (value: unknown, index: number) => boolean,
+	lineLimit = Number.POSITIVE_INFINITY,
+): boolean {
+	let descriptor: number;
+	try {
+		descriptor = fs.openSync(file, "r");
+	} catch {
+		return false;
+	}
+	const decoder = new StringDecoder("utf8");
+	const chunk = Buffer.allocUnsafe(READ_CHUNK_BYTES);
+	let pending = "";
+	let pendingBytes = 0;
+	let searchFrom = 0;
+	let index = 0;
+	let keepReading = true;
+	try {
+		while (keepReading && index < lineLimit) {
+			const bytes = fs.readSync(descriptor, chunk, 0, chunk.length, null);
+			if (bytes === 0) break;
+			const piece = decoder.write(chunk.subarray(0, bytes));
+			pending += piece;
+			pendingBytes += Buffer.byteLength(piece);
+			let newline = pending.indexOf("\n", searchFrom);
+			if (newline < 0) {
+				if (pendingBytes > MAX_SESSION_LINE_BYTES) return false;
+				searchFrom = pending.length;
+				continue;
+			}
+			while (newline >= 0 && index < lineLimit) {
+				const consumed = pending.slice(0, newline + 1);
+				const line = consumed.slice(0, -1).replace(/\r$/, "");
+				pending = pending.slice(newline + 1);
+				pendingBytes -= Buffer.byteLength(consumed);
+				searchFrom = 0;
+				if (!line.trim()) {
+					newline = pending.indexOf("\n");
+					continue;
+				}
+				if (Buffer.byteLength(line) > MAX_SESSION_LINE_BYTES) return false;
+				let value: unknown;
+				try {
+					value = JSON.parse(line);
+				} catch {
+					return false;
+				}
+				keepReading = visitor(value, index++);
+				if (!keepReading) break;
+				newline = pending.indexOf("\n");
+			}
+			if (newline < 0) searchFrom = pending.length;
+		}
+		pending += decoder.end();
+		if (keepReading && index < lineLimit && pending.trim()) {
+			if (Buffer.byteLength(pending) > MAX_SESSION_LINE_BYTES) return false;
+			try {
+				keepReading = visitor(JSON.parse(pending), index);
+			} catch {
+				return false;
+			}
+		}
+		return keepReading || index > 0;
+	} finally {
+		fs.closeSync(descriptor);
+	}
+}