pi-daddy 0.43.1 → 0.44.0

package/src/kernel/selected-definitions.ts

@@ -0,0 +1,156 @@
+/** Selected Pi 1.0.4 resources, frozen once per extension instance. No independent resource scan. */
+import { createHash } from "node:crypto";
+import { dirname, join, resolve as resolvePath } from "node:path";
+import { lstat, realpath } from "node:fs/promises";
+import { BoundedReadCleanupError, readBoundedBytes } from "./bounded-read.ts";
+import { ceilingForDefinition, parseSkillDefinition, type SkillDefinition } from "./definitions.ts";
+import { resolve } from "./resolve.ts";
+import type { CatalogEntry } from "./catalog.ts";
+export interface SelectedCommand {
+  source?: string;
+  name: string;
+  sourceInfo?: { path?: string };
+}
+const phases = ["plan", "build", "review", "debug", "investigate"];
+const hash = (value: string) => createHash("sha256").update(value, "utf8").digest("hex");
+const object = (x: unknown): x is Record<string, unknown> => !!x && typeof x === "object" && !Array.isArray(x);
+const exact = (x: Record<string, unknown>, keys: string[]) =>
+  Object.keys(x).sort().join(",") === [...keys].sort().join(",");
+async function read(path: string): Promise<string> {
+  if (!(await lstat(path)).isFile()) throw Error(`nonregular selected resource: ${path}`);
+  const result = await readBoundedBytes(path, { maxBytes: 1024 * 1024, timeoutMs: 3000 });
+  if (!result.ok) throw Error(result.detail);
+  return new TextDecoder("utf-8", { fatal: true }).decode(result.bytes);
+}
+async function principalBinding(path: string, inline: SkillDefinition, skillText: string): Promise<SkillDefinition> {
+  const phase = inline.name;
+  const marked = inline.metadata?.["principal-package"] === "principal-pi-skills";
+  if (!phases.includes(phase) || path !== join(dirname(dirname(path)), phase, "SKILL.md")) {
+    if (marked) throw Error("marked Principal skill has a noncanonical phase or path");
+    return inline;
+  }
+  const root = dirname(dirname(path));
+  let packageText: string;
+  try {
+    packageText = await read(join(root, "package.json"));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT" && !marked) return inline;
+    throw error;
+  }
+  const pkg: unknown = JSON.parse(packageText);
+  if (!object(pkg) || pkg.name !== "principal-pi-skills") {
+    if (marked) throw Error("marked Principal skill has missing or wrong package identity");
+    return inline;
+  }
+  const manifest: unknown = JSON.parse(await read(join(root, "principal-agents.json")));
+  if (
+    !object(manifest) ||
+    !exact(manifest, ["version", "package", "bindings"]) ||
+    manifest.version !== 1 ||
+    manifest.package !== "principal-pi-skills" ||
+    !object(manifest.bindings) ||
+    !exact(manifest.bindings, phases)
+  )
+    throw Error("invalid Principal binding manifest");
+  for (const name of phases) {
+    const row = manifest.bindings[name];
+    if (
+      !object(row) ||
+      !exact(row, ["skill", "agent", "skillSha256", "agentSha256"]) ||
+      row.skill !== `${name}/SKILL.md` ||
+      row.agent !== `agents/principal-${name}.md` ||
+      typeof row.skillSha256 !== "string" ||
+      !/^[a-f0-9]{64}$/.test(row.skillSha256) ||
+      typeof row.agentSha256 !== "string" ||
+      !/^[a-f0-9]{64}$/.test(row.agentSha256)
+    )
+      throw Error("invalid Principal binding row");
+  }
+  const row = manifest.bindings[phase] as Record<string, string>;
+  const agentPath = join(root, row.agent);
+  if (
+    (await realpath(agentPath)) !== join(await realpath(root), row.agent) ||
+    (await realpath(path)) !== join(await realpath(root), row.skill)
+  )
+    throw Error("Principal binding path escaped its selected package");
+  const agentText = await read(agentPath);
+  if (hash(skillText) !== row.skillSha256 || hash(agentText) !== row.agentSha256)
+    throw Error("Principal binding hash mismatch");
+  const agent = parseSkillDefinition(agentPath, agentText);
+  if (!agent) throw Error("Principal delegated definition is malformed");
+  const inlineCeiling = ceilingForDefinition(inline),
+    delegatedCeiling = ceilingForDefinition(agent);
+  if (
+    inlineCeiling.undeclared ||
+    delegatedCeiling.undeclared ||
+    inlineCeiling.patterns.length ||
+    delegatedCeiling.patterns.length
+  )
+    throw Error("Principal binding needs two declared pattern-free ceilings");
+  const ceiling = resolve({
+    requested: delegatedCeiling.capabilities,
+    parentGrant: inlineCeiling.capabilities,
+    subsumption: false,
+  }).effective;
+  const header = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/.exec(agentText)!;
+  return {
+    ...agent,
+    name: phase,
+    source: agentPath,
+    sourceHash: hash(agentText),
+    selectedSkillHash: hash(skillText),
+    body: agentText.slice(header[0].length),
+    allowedTools: ceiling.join(","),
+    runtimePreferences: agent.runtimePreferences ?? inline.runtimePreferences,
+    ...(typeof pkg.version === "string" ? { packageVersion: pkg.version } : {}),
+    binding: Object.freeze({ package: "principal-pi-skills", phase }),
+  };
+}
+export async function selectedDefinitions(commands: readonly SelectedCommand[]): Promise<{
+  definitions: Map<string, SkillDefinition>;
+  skills: CatalogEntry[];
+  skips: string[];
+}> {
+  const definitions = new Map<string, SkillDefinition>();
+  const skills: CatalogEntry[] = [],
+    skips: string[] = [],
+    seen = new Set<string>();
+  for (const command of commands) {
+    if (command.source !== "skill" || !command.name.startsWith("skill:")) continue;
+    const name = command.name.slice(6);
+    if (seen.has(name)) {
+      definitions.delete(name);
+      skips.push(`${name}: duplicate selected resource`);
+      continue;
+    }
+    seen.add(name);
+    try {
+      if (!command.sourceInfo?.path) throw Error("selected resource lacks a public source path");
+      const path = resolvePath(command.sourceInfo.path);
+      const text = await read(path);
+      const parsed = parseSkillDefinition(path, text);
+      if (!parsed || parsed.name !== name) throw Error("selected name/path does not match definition");
+      const bound = await principalBinding(path, parsed, text);
+      const definitionId = hash(
+        JSON.stringify({
+          name,
+          source: bound.source,
+          sourceHash: bound.sourceHash,
+          selectedSkillHash: bound.selectedSkillHash,
+          body: bound.body,
+          allowedTools: bound.allowedTools,
+          runtimePreferences: bound.runtimePreferences,
+          binding: bound.binding,
+          packageVersion: bound.packageVersion,
+        }),
+      );
+      if (bound.metadata) Object.freeze(bound.metadata);
+      definitions.set(name, Object.freeze({ ...bound, definitionId }));
+      skills.push({ capability: `skill:${name}`, kind: "skill", source: path });
+    } catch (error) {
+      if (error instanceof BoundedReadCleanupError) throw error;
+      skips.push(`${name}: ${String(error)}`);
+    }
+  }
+  return { definitions, skills: skills.filter((s) => definitions.has(s.capability.slice(6))), skips };
+}

package/src/kernel/skill-packages.ts

@@ -5,7 +5,8 @@
  * Names, ceilings and bytes are checked before they can enter the generated shell grant.
  */
 
-import { readdir, readFile, realpath } from "node:fs/promises";
+import { readdir, realpath } from "node:fs/promises";
+import { readOptionalAuthorityText } from "./authority-text.ts";
 import { readBoundedBytes } from "./bounded-read.ts";
 import { homedir } from "node:os";
 import { join, resolve, sep } from "node:path";
@@ -143,7 +144,11 @@ function refusalFor(skill: DiscoveredSkill): RefusedSkill | null {
 }
 
 /** One `pi.skills` entry: a directory holding `SKILL.md`, or a `.md` file — the same two shapes pi allows. */
-async function readSkill(packageDir: string, entry: string): Promise<DiscoveredSkill | "not-utf8" | null> {
+async function readSkill(
+  packageDir: string,
+  entry: string,
+  reader: typeof readBoundedBytes,
+): Promise<DiscoveredSkill | "not-utf8" | null> {
   const target = resolve(packageDir, entry);
   // A manifest is data from another package, so an entry escaping its own directory is refused rather than
   // followed. **`realpath`, not a lexical prefix test** (R-80): `resolve()` normalises `..` and knows
@@ -158,7 +163,7 @@ async function readSkill(packageDir: string, entry: string): Promise<DiscoveredS
     // `loadDefinitions` and accepted here, so `pi-daddy init` wrote `agent:advice` into the operator's grant
     // for a definition the session could never load, and the eventual `delegate` said only
     // `unknown agent "advice"`. An unreadable entry lands in `unreadable`, which `init` already prints.
-    const read = await readBoundedBytes(path, {
+    const read = await reader(path, {
       maxBytes: DEFINITION_MAX_BYTES,
       timeoutMs: DEFINITION_READ_TIMEOUT_MS,
     });
@@ -180,13 +185,14 @@ async function readSkill(packageDir: string, entry: string): Promise<DiscoveredS
 }
 
 /** Read one installed package, if it declares skills. `null` means "not a skill package", not an error. */
-export async function readSkillPackage(packageDir: string): Promise<SkillPackage | null> {
+export async function readSkillPackage(
+  packageDir: string,
+  reader: typeof readBoundedBytes = readBoundedBytes,
+): Promise<SkillPackage | null> {
   let manifest: { name?: string; version?: string; pi?: { skills?: unknown } };
-  try {
-    manifest = JSON.parse(await readFile(join(packageDir, "package.json"), "utf8"));
-  } catch {
-    return null;
-  }
+  const text = await readOptionalAuthorityText(join(packageDir, "package.json"));
+  if (text === undefined) return null;
+  manifest = JSON.parse(text);
   const declared = manifest.pi?.skills;
   if (!Array.isArray(declared) || declared.length === 0) return null;
 
@@ -195,7 +201,7 @@ export async function readSkillPackage(packageDir: string): Promise<SkillPackage
   const refused: RefusedSkill[] = [];
   for (const entry of declared) {
     if (typeof entry !== "string") continue;
-    const skill = await readSkill(packageDir, entry);
+    const skill = await readSkill(packageDir, entry, reader);
     if (skill === null) {
       unreadable.push(entry);
     } else if (skill === "not-utf8") {
@@ -243,7 +249,11 @@ export function skillPackageRoots(cwd: string): string[] {
   return [join(cwd, "node_modules"), join(agentDir, "npm", "node_modules")];
 }
 
-export async function discoverSkillPackages(cwd: string): Promise<SkillPackage[]> {
+/** The optional reader is a trusted per-loader dependency, never package metadata or requester input. */
+export async function discoverSkillPackages(
+  cwd: string,
+  reader: typeof readBoundedBytes = readBoundedBytes,
+): Promise<SkillPackage[]> {
   const resolved = await resolveSkillResources(cwd);
   const packages: SkillPackage[] = [];
   const seenSkills = new Set<string>();
@@ -260,15 +270,12 @@ export async function discoverSkillPackages(cwd: string): Promise<SkillPackage[]
     }),
   );
   for (const root of configuredRoots) {
-    try {
-      configuredNames.add(JSON.parse(await readFile(join(root, "package.json"), "utf8")).name);
-    } catch {
-      /* absent */
-    }
+    const text = await readOptionalAuthorityText(join(root, "package.json"));
+    if (text !== undefined) configuredNames.add(JSON.parse(text).name);
   }
   for (const resource of resolved.skills) {
     // Same bound, same reason: this is the third `SKILL.md` reader and it feeds `planInit`.
-    const resourceRead = await readBoundedBytes(resource.path, {
+    const resourceRead = await reader(resource.path, {
       maxBytes: DEFINITION_MAX_BYTES,
       timeoutMs: DEFINITION_READ_TIMEOUT_MS,
     });
@@ -281,12 +288,11 @@ export async function discoverSkillPackages(cwd: string): Promise<SkillPackage[]
     let name = resource.metadata.source;
     let version = "local";
     if (resource.metadata.origin === "package" && resource.metadata.baseDir) {
-      try {
-        const manifest = JSON.parse(await readFile(join(resource.metadata.baseDir, "package.json"), "utf8"));
+      const text = await readOptionalAuthorityText(join(resource.metadata.baseDir, "package.json"));
+      if (text !== undefined) {
+        const manifest = JSON.parse(text);
         name = manifest.name ?? name;
         version = manifest.version ?? version;
-      } catch {
-        /* the resource can be used without optional display metadata */
       }
     } else name = `${resource.metadata.scope} skills`;
     let pkg = packages.find((p) => p.name === name && p.version === version);
@@ -313,7 +319,7 @@ export async function discoverSkillPackages(cwd: string): Promise<SkillPackage[]
   const seenNames = new Set(packages.map((p) => p.name));
   for (const dir of dirs) {
     if (configuredRoots.has(resolve(dir))) continue;
-    const found = await readSkillPackage(dir);
+    const found = await readSkillPackage(dir, reader);
     if (!found || configuredNames.has(found.name) || seenNames.has(found.name)) continue;
     seenNames.add(found.name);
     found.skills = found.skills.filter((skill) => !runtimeNames.has(skill.definition.name));
@@ -324,23 +330,19 @@ export async function discoverSkillPackages(cwd: string): Promise<SkillPackage[]
 
 /** Append every package directory under one `node_modules`, scoped packages included. */
 async function collectFrom(root: string, dirs: string[]): Promise<void> {
-  let entries: string[];
+  let entries;
   try {
-    entries = await readdir(root);
-  } catch {
-    return; // a root that does not exist is a normal state, not a failure
+    entries = await readdir(root, { withFileTypes: true });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
   }
-
-  for (const entry of entries.sort()) {
-    if (entry.startsWith(".")) continue; // .bin, .package-lock.json
-    if (entry.startsWith("@")) {
-      try {
-        for (const scoped of (await readdir(join(root, entry))).sort()) dirs.push(join(root, entry, scoped));
-      } catch {
-        continue;
-      }
-    } else {
-      dirs.push(join(root, entry));
-    }
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (entry.name.startsWith(".") || (!entry.isDirectory() && !entry.isSymbolicLink())) continue;
+    if (entry.name.startsWith("@")) {
+      const scoped = await readdir(join(root, entry.name), { withFileTypes: true });
+      for (const child of scoped.sort((a, b) => a.name.localeCompare(b.name)))
+        if (child.isDirectory() || child.isSymbolicLink()) dirs.push(join(root, entry.name, child.name));
+    } else dirs.push(join(root, entry.name));
   }
 }

package/src/kernel/skill-resources.ts

@@ -1,5 +1,6 @@
 /** Read Pi's configured resource surface without locks, installs, extension execution or model calls. */
-import { readFileSync, statSync } from "node:fs";
+import { statSync } from "node:fs";
+import { readOptionalAuthorityText } from "./authority-text.ts";
 import { join } from "node:path";
 import { DefaultPackageManager, getAgentDir, SettingsManager } from "@earendil-works/pi-coding-agent";
 import { piProjectDir } from "./project-paths.ts";
@@ -21,17 +22,15 @@ export function skillResourceName(path: string): string {
 
 export async function resolveSkillResources(cwd: string): Promise<SkillResources> {
   const agentDir = getAgentDir();
+  // Read before Pi's synchronous storage callback: only known absence receives its default.
+  const texts = {
+    global: await readOptionalAuthorityText(join(agentDir, "settings.json")),
+    project: await readOptionalAuthorityText(join(piProjectDir(cwd), "settings.json")),
+  };
   const settingsManager = SettingsManager.fromStorage({
     withLock(scope, read) {
-      const path = scope === "global" ? join(agentDir, "settings.json") : join(piProjectDir(cwd), "settings.json");
-      let text: string | undefined;
-      try {
-        text = readFileSync(path, "utf8");
-      } catch (error) {
-        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-      }
       // This storage is intentionally read-only: no lock files or migrated settings are persisted.
-      read(text);
+      read(texts[scope]);
     },
   });
   const errors = settingsManager.drainErrors();

package/src/kernel/workspace.ts

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { execFile } from "node:child_process";
 import { once } from "node:events";
 import { mkdir, readFile, realpath, rename, stat, writeFile } from "node:fs/promises";
-import { readBoundedFile } from "./bounded-read.ts";
+import { readBoundedFile, BoundedReadCleanupError } from "./bounded-read.ts";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { promisify } from "node:util";
@@ -59,13 +59,17 @@ const REGISTRY_READ_TIMEOUT_MS = 2_000;
 /** A registry is an operator-authored JSON file; anything approaching this is not one. */
 const REGISTRY_MAX_BYTES = 1 << 20;
 
-export async function loadWorkspaceRegistry(path: string): Promise<WorkspaceRegistryFile> {
+/** The optional reader is a trusted loader dependency, never registry/request input. */
+export async function loadWorkspaceRegistry(
+  path: string,
+  readFile: typeof readBoundedFile = readBoundedFile,
+): Promise<WorkspaceRegistryFile> {
   // The guards this call carries — non-blocking open, every check on the held descriptor, a deadline between
   // chunks, the size bound checked twice — were worked out HERE and now live in `bounded-read.ts`, because a
   // second session-start reader went on using a bare `readFile` rather than copying them. The mapping from a
   // reason to a refusal stays here: only this caller knows that an unreadable registry is a governance
   // refusal naming the file, and its messages are unchanged.
-  const read = await readBoundedFile(path, {
+  const read = await readFile(path, {
     maxBytes: REGISTRY_MAX_BYTES,
     timeoutMs: REGISTRY_READ_TIMEOUT_MS,
   });
@@ -151,7 +155,8 @@ export async function loadWorkspaceRegistry(path: string): Promise<WorkspaceRegi
 }
 
 /**
- * The registered workspace ids, for `planInit` to scaffold and `/grants` to list. `[]` when there is no registry or it is broken.
+ * The registered workspace ids, for `planInit` to scaffold and `/grants` to list.
+ * No registry or malformed/unreadable data yields []; physical cleanup failure still rejects, with its owner.
  *
  * Fails SOFT, and only because nothing here is an authority: this decides which ids appear as COMMENTS in a
  * generated file. `loadWorkspaceRegistry` throws a GovernanceRefusal naming the file, and that refusal is
@@ -172,11 +177,13 @@ export async function loadWorkspaceRegistry(path: string): Promise<WorkspaceRegi
 export async function registeredWorkspaceIds(
   registryPath = process.env[ENV_WORKSPACE_REGISTRY],
   onRefusal?: (reason: string) => void,
+  loadRegistry: typeof loadWorkspaceRegistry = loadWorkspaceRegistry,
 ): Promise<string[]> {
   if (!registryPath) return [];
   try {
-    return Object.keys((await loadWorkspaceRegistry(registryPath)).workspaces).sort();
+    return Object.keys((await loadRegistry(registryPath)).workspaces).sort();
   } catch (error) {
+    if (error instanceof BoundedReadCleanupError) throw error;
     onRefusal?.(error instanceof Error ? error.message : String(error));
     return [];
   }

package/src/products/dashboard-cli.ts

@@ -144,7 +144,7 @@ export async function dashboardFrame(options: DashboardFrameOptions): Promise<st
         details: options.details,
         history: options.history,
         modelRows: options.session?.rows,
-        episodeCost: options.session ? { cost: options.session.cost, ceiling: options.session.ceiling } : undefined,
+        episodeCost: options.session ? { cost: options.session.cost } : undefined,
       });
   return waiting ? `${rendered}\n\nwaiting for ledger ${ledgerPath}` : rendered;
 }

package/src/products/dashboard-render.ts

@@ -9,7 +9,7 @@ export interface DashboardRenderOptions {
   completedRoots?: number;
   completedChildren?: number;
   modelRows?: Array<{ definition: string; model: string; thinking: string; source: string }>;
-  episodeCost?: { cost: number; ceiling: number };
+  episodeCost?: { cost: number | null };
 }
 
 const ACTIVE = new Set<DashboardState>(["authorised", "starting", "running"]);
@@ -217,7 +217,11 @@ export function renderDashboard(projection: DashboardProjection, options: Dashbo
       lines.push(`${clean(row.definition)}  ${clean(row.model)}  ${clean(row.thinking)}  ${clean(row.source)}`);
     lines.push("edit: m <definition> <provider:model> <thinking> | m all <provider:model> <thinking>");
     if (options.episodeCost)
-      lines.push(`episode cost $${options.episodeCost.cost} / $${options.episodeCost.ceiling} ceiling`);
+      lines.push(
+        options.episodeCost.cost === null
+          ? "episode cost unavailable (usage coverage partial)"
+          : `reported episode cost $${options.episodeCost.cost} (coverage partial)`,
+      );
     lines.push("");
   }
 

package/src/products/dashboard-session-client.ts

@@ -2,8 +2,7 @@ import { createConnection } from "node:net";
 
 export interface DashboardSessionSnapshot {
   rows: Array<{ definition: string; model: string; thinking: string; source: string }>;
-  cost: number;
-  ceiling: number;
+  cost: number | null;
 }
 
 export async function dashboardSessionRequest(

package/src/products/episode-report.ts

@@ -13,7 +13,13 @@ export interface EpisodeReportOptions {
   model?: string;
   groupBy?: EpisodeGroupBy;
 }
-export interface EpisodeReportRow {
+export interface CostEvidence {
+  /** Null unless every recorded child has a terminal cost observation. Scope excludes unrecorded/root work. */
+  cost: number | null;
+  observedCost: number;
+  costCoverage: "complete" | "partial" | "unavailable";
+}
+export interface EpisodeReportRow extends CostEvidence {
   episode: string;
   started: string;
   definition: string;
@@ -26,7 +32,6 @@ export interface EpisodeReportRow {
   outputTokens: number;
   cacheReadTokens: number;
   reasoningTokens: number;
-  cost: number;
   compactions: number;
   turns: number;
   durationMs: number;
@@ -34,20 +39,25 @@ export interface EpisodeReportRow {
   commit: string;
   outcome: "" | "positive" | "negative" | "unknown";
 }
-export interface EpisodeReportGroup {
+export interface EpisodeReportGroup extends CostEvidence {
   value: string;
   count: number;
   inputTokens: number;
   outputTokens: number;
   cacheReadTokens: number;
   reasoningTokens: number;
-  cost: number;
 }
 export interface EpisodeReport {
+  costScope: "recorded-child-executions";
   rows: EpisodeReportRow[];
   groups?: EpisodeReportGroup[];
   groupBy?: EpisodeGroupBy;
-  totals?: { episodes: number; cost: number; tokens: number; p50EpisodeCost: number; p95EpisodeCost: number };
+  totals?: CostEvidence & {
+    episodes: number;
+    tokens: number;
+    p50EpisodeCost: number | null;
+    p95EpisodeCost: number | null;
+  };
 }
 interface EpisodeAccumulator {
   episode: string;
@@ -65,6 +75,7 @@ interface EpisodeAccumulator {
   cacheReadTokens: number;
   reasoningTokens: number;
   cost: number;
+  reportedCosts: number;
   compactions: number;
   turns: number;
   children: Set<string>;
@@ -103,6 +114,7 @@ function episodeOf(episodes: Map<string, EpisodeAccumulator>, id: string, at: nu
     cacheReadTokens: 0,
     reasoningTokens: 0,
     cost: 0,
+    reportedCosts: 0,
     compactions: 0,
     turns: 0,
     children: new Set(),
@@ -174,7 +186,11 @@ export function reportEpisodes(input: {
       episode.cacheReadTokens += number(usage.cacheRead);
       episode.reasoningTokens += number(usage.reasoning);
     }
-    if (usage && object(usage.cost)) episode.cost += number(usage.cost.total);
+    const charge = usage && object(usage.cost) ? usage.cost.total : undefined;
+    if (typeof charge === "number" && Number.isFinite(charge) && charge >= 0) {
+      episode.cost += charge;
+      episode.reportedCosts++;
+    }
     episode.compactions += number(body.compactionCount);
   }
   const activity = readRecords(input.activityText);
@@ -203,7 +219,14 @@ export function reportEpisodes(input: {
       outputTokens: episode.outputTokens,
       cacheReadTokens: episode.cacheReadTokens,
       reasoningTokens: episode.reasoningTokens,
-      cost: episode.cost,
+      cost: episode.children.size > 0 && episode.reportedCosts === episode.children.size ? episode.cost : null,
+      observedCost: episode.cost,
+      costCoverage:
+        episode.children.size > 0 && episode.reportedCosts === episode.children.size
+          ? "complete"
+          : episode.reportedCosts > 0
+            ? "partial"
+            : "unavailable",
       compactions: episode.compactions,
       turns: episode.turns,
       durationMs: Math.max(0, episode.endedMs - episode.startedMs),
@@ -237,36 +260,58 @@ export function reportEpisodes(input: {
         cacheReadTokens: 0,
         reasoningTokens: 0,
         cost: 0,
+        observedCost: 0,
+        costCoverage: "complete",
       };
+      const summary = summarizeCosts(group.count ? [group, row] : [row]);
       group.count += 1;
       group.inputTokens += row.inputTokens;
       group.outputTokens += row.outputTokens;
       group.cacheReadTokens += row.cacheReadTokens;
       group.reasoningTokens += row.reasoningTokens;
-      group.cost += row.cost;
+      Object.assign(group, summary);
       groups.set(value, group);
     }
     return {
+      costScope: "recorded-child-executions",
       rows: [],
       groups: [...groups.values()].sort((a, b) => a.value.localeCompare(b.value)),
       groupBy: input.options.groupBy,
     };
   }
-  const costs = rows.map((row) => row.cost);
+  const summary = summarizeCosts(rows);
+  const costs = rows.flatMap((row) => (row.cost === null ? [] : [row.cost]));
   return {
+    costScope: "recorded-child-executions",
     rows,
     totals: {
       episodes: rows.length,
-      cost: costs.reduce((sum, value) => sum + value, 0),
+      ...summary,
       tokens: rows.reduce((sum, row) => sum + row.inputTokens + row.outputTokens, 0),
-      p50EpisodeCost: percentile(costs, 0.5),
-      p95EpisodeCost: percentile(costs, 0.95),
+      p50EpisodeCost: summary.cost === null ? null : percentile(costs, 0.5),
+      p95EpisodeCost: summary.cost === null ? null : percentile(costs, 0.95),
     },
   };
 }
 
+/** Summaries never treat an unobserved charge as a measured zero. */
+function summarizeCosts(values: readonly CostEvidence[]): CostEvidence {
+  const observedCost = values.reduce((sum, row) => sum + row.observedCost, 0);
+  const complete = values.length > 0 && values.every((row) => row.costCoverage === "complete");
+  return {
+    cost: complete ? observedCost : null,
+    observedCost,
+    costCoverage: complete
+      ? "complete"
+      : values.some((row) => row.costCoverage !== "unavailable")
+        ? "partial"
+        : "unavailable",
+  };
+}
+const costScope = "Cost coverage refers only to recorded child executions; root and unrecorded work are not measured.";
 const escapeCell = (value: unknown): string => String(value).replaceAll("|", "\\|").replaceAll("\n", " ");
-const cost = (value: number): string => value.toFixed(6).replace(/\.?0+$/, "") || "0";
+const cost = (value: number | null): string =>
+  value === null ? "unavailable" : value.toFixed(6).replace(/\.?0+$/, "") || "0";
 function duration(ms: number): string {
   const seconds = Math.round(ms / 1000);
   const minutes = Math.floor(seconds / 60);
@@ -290,6 +335,8 @@ export function renderEpisodeReport(report: EpisodeReport, json: boolean): strin
       "cacheReadTokens",
       "reasoningTokens",
       "cost",
+      "observed cost",
+      "cost coverage",
     ];
     return `${table(
       headers,
@@ -301,8 +348,10 @@ export function renderEpisodeReport(report: EpisodeReport, json: boolean): strin
         group.cacheReadTokens,
         group.reasoningTokens,
         cost(group.cost),
+        cost(group.observedCost),
+        group.costCoverage,
       ]),
-    )}\n`;
+    )}\n\n${costScope}\n`;
   }
   const headers = [
     "episode",
@@ -318,6 +367,8 @@ export function renderEpisodeReport(report: EpisodeReport, json: boolean): strin
     "cacheReadTokens",
     "reasoningTokens",
     "cost",
+    "observed cost",
+    "cost coverage",
     "compactions",
     "turns",
     "duration",
@@ -339,6 +390,8 @@ export function renderEpisodeReport(report: EpisodeReport, json: boolean): strin
     row.cacheReadTokens,
     row.reasoningTokens,
     cost(row.cost),
+    cost(row.observedCost),
+    row.costCoverage,
     row.compactions,
     row.turns,
     duration(row.durationMs),
@@ -348,10 +401,20 @@ export function renderEpisodeReport(report: EpisodeReport, json: boolean): strin
   ]);
   const totals = report.totals!;
   const totalsTable = table(
-    ["episodes", "cost", "tokens", "p50 episode cost", "p95 episode cost"],
-    [[totals.episodes, cost(totals.cost), totals.tokens, cost(totals.p50EpisodeCost), cost(totals.p95EpisodeCost)]],
+    ["episodes", "cost", "tokens", "p50 episode cost", "p95 episode cost", "observed cost", "cost coverage"],
+    [
+      [
+        totals.episodes,
+        cost(totals.cost),
+        totals.tokens,
+        cost(totals.p50EpisodeCost),
+        cost(totals.p95EpisodeCost),
+        cost(totals.observedCost),
+        totals.costCoverage,
+      ],
+    ],
   );
-  return `${table(headers, rows)}\n\n${totalsTable}\n`;
+  return `${table(headers, rows)}\n\n${totalsTable}\n\n${costScope}\n`;
 }
 
 export function commitsFromGitLog(log: string): Map<string, string> {