pi-daddy 0.41.1 → 0.43.0

package/extensions/session-model-prompt.ts

@@ -0,0 +1,179 @@
+import { readFile } from "node:fs/promises";
+import { appendLedgerEvent, buildSessionConfigEvent } from "../src/governance/ledger.ts";
+import { readRecords } from "../src/governance/record.ts";
+import {
+  parseConfiguredModel,
+  parseThinkingLevel,
+  resolveDefinitionRuntime,
+  THINKING_LEVELS,
+  type DefinitionRuntimeChoice,
+  type DefinitionRuntimeSettings,
+} from "./definition-runtime.ts";
+
+export interface SessionModelPromptState {
+  episodeId: string;
+  ledgerPath?: string;
+  definitions: Map<string, { name: string }>;
+  definitionRuntimeSettings: DefinitionRuntimeSettings;
+  definitionRuntimeOverrides: Map<string, DefinitionRuntimeChoice>;
+  sessionModelPrompt: "ask" | "never";
+  sessionModelPrompted: boolean;
+  sessionModelPromptInFlight?: Promise<void>;
+}
+export interface SessionModelPromptUI {
+  hasUI: boolean;
+  input(title: string, placeholder?: string): Promise<string | undefined>;
+  notify(message: string, type?: "info" | "warning" | "error"): void;
+}
+
+async function historicalDefinitions(path: string | undefined): Promise<string[]> {
+  if (!path) return [];
+  try {
+    const parsed = readRecords(await readFile(path, "utf8"));
+    return parsed.records
+      .map((record) => record.body as { event?: unknown; agentType?: unknown })
+      .filter((body) => body.event === "capability_decision" && typeof body.agentType === "string")
+      .map((body) => body.agentType as string)
+      .filter((name) => name !== "delegate");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+export function sessionModelRows(state: SessionModelPromptState, names: readonly string[]) {
+  return names.map((name) => {
+    const selected = resolveDefinitionRuntime({
+      definition: name,
+      explicit: {},
+      session: state.definitionRuntimeOverrides,
+      settings: state.definitionRuntimeSettings,
+    });
+    return {
+      definition: name,
+      model: selected.model ?? "pi default",
+      thinking: selected.thinking ?? "pi default",
+      source: `${selected.modelSource}/${selected.thinkingSource}`,
+    };
+  });
+}
+
+function table(state: SessionModelPromptState, names: readonly string[]): string {
+  const rows = sessionModelRows(state, names).map(
+    (row) => `${row.definition}\t${row.model}\t${row.thinking}\t${row.source}`,
+  );
+  return ["definition\tmodel\tthinking\tsource", ...rows].join("\n");
+}
+
+export function applySessionModelEdits(
+  raw: string,
+  names: readonly string[],
+  target: Map<string, DefinitionRuntimeChoice>,
+): string | null {
+  const next = new Map(target);
+  for (const line of raw
+    .split(/\r?\n/)
+    .map((value) => value.trim())
+    .filter(Boolean)) {
+    const parts = line.split(/\s+/);
+    if (parts.length !== 3) return "Each edit must be: <definition> <provider:model> <thinking>.";
+    const [subject, rawModel, rawThinking] = parts;
+    const model = parseConfiguredModel(rawModel);
+    const thinking = parseThinkingLevel(rawThinking);
+    if (!model || !thinking)
+      return `Invalid model or thinking. Model must be provider:model; thinking must be one of: ${THINKING_LEVELS.join(", ")}.`;
+    const selected = subject === "all" ? [...names] : [subject];
+    if (selected.some((name) => !names.includes(name)))
+      return `Unknown definition ${subject}. Known definitions: ${names.join(", ") || "(none)"}.`;
+    for (const name of selected) next.set(name, { model, thinking });
+  }
+  target.clear();
+  for (const [name, value] of next) target.set(name, value);
+  return null;
+}
+
+async function record(
+  state: SessionModelPromptState,
+  outcome: "kept" | "changed",
+  trigger: "first-delegation" | "grants-models",
+): Promise<void> {
+  if (!state.ledgerPath) return;
+  await appendLedgerEvent(
+    { path: state.ledgerPath, strict: true },
+    buildSessionConfigEvent({
+      episodeId: state.episodeId,
+      outcome,
+      trigger,
+      overrides: state.definitionRuntimeOverrides,
+      now: new Date(),
+    }),
+  );
+}
+
+async function choose(
+  state: SessionModelPromptState,
+  current: readonly string[],
+  ui: SessionModelPromptUI,
+  trigger: "first-delegation" | "grants-models",
+): Promise<void> {
+  const names = [...new Set([...(await historicalDefinitions(state.ledgerPath)), ...current])].sort();
+  if (state.sessionModelPrompt === "never" || !ui.hasUI) {
+    await record(state, "kept", trigger);
+    return;
+  }
+  while (true) {
+    const answer = await ui.input(
+      `Child model defaults\n\n${table(state, names)}\n\nPress Enter to keep, or enter edits one per line.`,
+      "<definition> <provider:model> <thinking> | all <provider:model> <thinking>",
+    );
+    if (answer === undefined) throw new Error("session model selection was dismissed; no child was spawned");
+    if (!answer.trim()) {
+      await record(state, "kept", trigger);
+      return;
+    }
+    const invalid = await saveSessionModelEdits(state, answer, names, trigger);
+    if (invalid) {
+      ui.notify(invalid, "error");
+      continue;
+    }
+    return;
+  }
+}
+
+export async function saveSessionModelEdits(
+  state: SessionModelPromptState,
+  raw: string,
+  names: readonly string[],
+  trigger: "first-delegation" | "grants-models",
+): Promise<string | null> {
+  const invalid = applySessionModelEdits(raw, names, state.definitionRuntimeOverrides);
+  if (invalid) return invalid;
+  await record(state, "changed", trigger);
+  return null;
+}
+
+export async function ensureSessionModelPrompt(
+  state: SessionModelPromptState,
+  current: readonly string[],
+  ui: SessionModelPromptUI,
+): Promise<void> {
+  if (state.sessionModelPrompted) return;
+  if (!state.sessionModelPromptInFlight) {
+    state.sessionModelPromptInFlight = choose(state, current, ui, "first-delegation").then(() => {
+      state.sessionModelPrompted = true;
+    });
+  }
+  try {
+    await state.sessionModelPromptInFlight;
+  } finally {
+    state.sessionModelPromptInFlight = undefined;
+  }
+}
+
+export async function changeSessionModels(state: SessionModelPromptState, ui: SessionModelPromptUI): Promise<void> {
+  await choose(state, [...state.definitions.keys()], ui, "grants-models");
+}
+
+export function renderSessionModels(state: SessionModelPromptState): string {
+  return table(state, [...state.definitions.keys()].sort());
+}

package/extensions/session.ts

@@ -67,6 +67,14 @@ import {
 } from "../src/kernel/workspace-pin.ts";
 import { loadWorkspaceRegistry } from "../src/kernel/workspace.ts";
 import { reconcileAcceptedWorkspaces } from "../src/governance/workspace-acceptance.ts";
+import { EpisodeCostGate, episodeCostCeilingFromSettings } from "../src/governance/episode-cost-gate.ts";
+import {
+  definitionRuntimeSettingsFrom,
+  parseConfiguredModel,
+  parseThinkingLevel,
+  type DefinitionRuntimeChoice,
+  type DefinitionRuntimeSettings,
+} from "./definition-runtime.ts";
 
 /**
  * Run governed children in herdr panes instead of captured child processes.
@@ -101,7 +109,13 @@ import {
   ENV_ACTIVITY_ROOT,
   ENV_ACTIVITY_TASK,
 } from "../src/products/activity-timeline.ts";
-import { ENV_HERDR_KEEP_PANE, ENV_GOVERNANCE, ENV_ADVISOR, ENV_EPISODE_ID } from "../src/kernel/env-names.ts";
+import {
+  ENV_HERDR_KEEP_PANE,
+  ENV_GOVERNANCE,
+  ENV_ADVISOR,
+  ENV_EPISODE_ID,
+  ENV_EPISODE_COST_CEILING,
+} from "../src/kernel/env-names.ts";
 export { ENV_HERDR_KEEP_PANE, ENV_GOVERNANCE } from "../src/kernel/env-names.ts";
 import { adoptLegacyEnvironment } from "../src/kernel/env-names.ts";
 
@@ -161,6 +175,13 @@ export interface GrantsSession extends NativeSessionHost {
   allowUnresolvedModels: boolean;
   /** Results from pi's synchronous model catalogue, shared by every delegation in this session. */
   readonly modelResolutionCache: Map<string, boolean>;
+  /** Committed per-definition and global child runtime defaults. */
+  readonly definitionRuntimeSettings: DefinitionRuntimeSettings;
+  /** PD-7's future session controls write here; deliberately empty in this commit. */
+  readonly definitionRuntimeOverrides: Map<string, DefinitionRuntimeChoice>;
+  readonly sessionModelPrompt: "ask" | "never";
+  sessionModelPrompted: boolean;
+  sessionModelPromptInFlight?: Promise<void>;
   /** Path to this extension, so a child granted `tool:delegate` can delegate in turn. */
   readonly extensionPath?: string;
   /** Hook-only observer path for leaf children; it exposes no tools. */
@@ -192,6 +213,8 @@ export interface GrantsSession extends NativeSessionHost {
   inheritedApprovals: Map<string, string | undefined>;
   /** ONE single-flight queue for the whole session — see `obtainApprovals` for why it lives here. */
   readonly approvalGateFor: ReturnType<typeof createApprovalGateProvider>;
+  /** One cumulative cost threshold shared by every child in this episode. */
+  readonly episodeCostGate: EpisodeCostGate;
   /** Set at `session_start`; `process.cwd()` until then. */
   cwd: string;
   /** This session's own grant. Starts as the inherited upper bound, tightened once tools are observed. */
@@ -436,7 +459,10 @@ export function createGrantsSession(
   // G7 / A-S4 + B-I4: strict, three-way parsing that fails CLOSED. A malformed bound used to yield
   // `NaN`, and every comparison against `NaN` is false, so depth limiting switched itself off.
   const bounds = depthConfig(environment[ENV_DEPTH], environment[ENV_MAX_DEPTH]);
-  const { depth, maxDepth } = bounds;
+  const costConfig = episodeCostConfiguration(storeCwd, environment[ENV_EPISODE_COST_CEILING]);
+  const runtimeConfig = projectDefinitionRuntimeConfiguration(storeCwd);
+  const depth = bounds.depth;
+  const maxDepth = costConfig.malformed || runtimeConfig.malformed ? 0 : bounds.maxDepth;
   const emptyCatalog = makeCatalog([]);
   // ADR-0077. The environment decides whether there is an advisor at all; the project's settings block may only
   // narrow it. The block IS read — the first version passed `undefined` and every narrowing the release advertised
@@ -456,7 +482,11 @@ export function createGrantsSession(
     inherited,
     depth,
     maxDepth,
-    malformedBounds: bounds.malformed,
+    malformedBounds: [
+      ...bounds.malformed,
+      ...(costConfig.malformed ? [costConfig.malformed] : []),
+      ...(runtimeConfig.malformed ? [runtimeConfig.malformed] : []),
+    ],
     definitionSkips: [],
     workspacePin: undefined,
     pinSettled: false,
@@ -496,6 +526,10 @@ export function createGrantsSession(
     allowUnresolvedModels: environment[ENV_ALLOW_UNRESOLVED_MODELS] === "1",
     nativeSessionRoot: nativeSessionRootFromEnv(process.env),
     modelResolutionCache: new Map<string, boolean>(),
+    definitionRuntimeSettings: runtimeConfig.settings,
+    definitionRuntimeOverrides: new Map<string, DefinitionRuntimeChoice>(),
+    sessionModelPrompt: runtimeConfig.prompt,
+    sessionModelPrompted: false,
     extensionPath,
     observerExtensionPath,
     activityRootId,
@@ -504,6 +538,7 @@ export function createGrantsSession(
     sessionApprovalBindings: new Map<string, ApprovalBinding>(),
     inheritedApprovals: parseInherited(environment[ENV_APPROVED]),
     approvalGateFor: createApprovalGateProvider(),
+    episodeCostGate: new EpisodeCostGate(costConfig.ceiling),
     cwd: process.cwd(),
     ownGrant: deriveOwnGrant(inherited, null),
     observed: false,
@@ -609,6 +644,72 @@ export function reconcileAdvisorSession(session: GrantsSession, environment: Nod
   });
 }
 
+function episodeCostConfiguration(cwd: string, inherited: string | undefined): { ceiling: number; malformed?: string } {
+  if (inherited !== undefined) {
+    const value = Number(inherited);
+    return Number.isFinite(value) && value > 0
+      ? { ceiling: value }
+      : { ceiling: episodeCostCeilingFromSettings(undefined), malformed: ENV_EPISODE_COST_CEILING };
+  }
+  const path = projectSettingsPath(cwd);
+  try {
+    const stats = statSync(path);
+    if (!stats.isFile() || stats.size > 1024 * 1024) {
+      return { ceiling: episodeCostCeilingFromSettings(undefined), malformed: "settings.json episodeCostCeiling" };
+    }
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    if (parsed && typeof parsed === "object" && Object.hasOwn(parsed, "episodeCostCeiling")) {
+      const value = (parsed as Record<string, unknown>).episodeCostCeiling;
+      if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        return { ceiling: episodeCostCeilingFromSettings(undefined), malformed: "settings.json episodeCostCeiling" };
+      }
+    }
+    return { ceiling: episodeCostCeilingFromSettings(parsed) };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { ceiling: episodeCostCeilingFromSettings(undefined) };
+    }
+    return { ceiling: episodeCostCeilingFromSettings(undefined), malformed: "settings.json episodeCostCeiling" };
+  }
+}
+
+function projectDefinitionRuntimeConfiguration(cwd: string): {
+  settings: DefinitionRuntimeSettings;
+  prompt: "ask" | "never";
+  malformed?: string;
+} {
+  const empty = { settings: definitionRuntimeSettingsFrom(undefined), prompt: "ask" as const };
+  try {
+    const path = projectSettingsPath(cwd);
+    const stats = statSync(path);
+    if (!stats.isFile() || stats.size > 1024 * 1024) return { ...empty, malformed: "settings.json model defaults" };
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+      return { ...empty, malformed: "settings.json model defaults" };
+    const root = parsed as Record<string, unknown>;
+    if (root.sessionModelPrompt !== undefined && !["ask", "never"].includes(String(root.sessionModelPrompt)))
+      return { ...empty, malformed: "settings.json sessionModelPrompt" };
+    const candidates = [root.defaults, ...(Array.isArray(root.definitions) ? root.definitions : [])];
+    for (const candidate of candidates) {
+      if (candidate === undefined) continue;
+      if (!candidate || typeof candidate !== "object" || Array.isArray(candidate))
+        return { ...empty, malformed: "settings.json model defaults" };
+      const value = candidate as Record<string, unknown>;
+      if (value.model !== undefined && !parseConfiguredModel(value.model))
+        return { ...empty, malformed: "settings.json model" };
+      if (value.thinking !== undefined && !parseThinkingLevel(value.thinking))
+        return { ...empty, malformed: "settings.json thinking" };
+    }
+    return {
+      settings: definitionRuntimeSettingsFrom(root),
+      prompt: root.sessionModelPrompt === "never" ? "never" : "ask",
+    };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return empty;
+    return { ...empty, malformed: "settings.json model defaults" };
+  }
+}
+
 function projectAdvisorBlock(cwd: string, env: NodeJS.ProcessEnv = process.env): unknown {
   // Only when an advisor could exist at all. This runs in every session including every child, before any hook, and
   // a child can never use the result because `PI_DADDY_ADVISOR` is stripped from it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-daddy",
-  "version": "0.41.1",
+  "version": "0.43.0",
   "description": "Capability governance for pi sub-agents: spawn Agent Skills (SKILL.md) definitions whose allowed-tools becomes a grant that can only narrow going down a delegation tree, enforced by pi's own --tools allowlist, with an append-only ledger.",
   "keywords": [
     "pi-package",

package/src/advisors/advisor.ts

@@ -41,6 +41,17 @@ export interface AdviceRecord {
   /** Present only when advice came back. */
   answers?: Readonly<Record<string, { value: string | number | boolean; confidence?: number }>>;
   model?: string;
+  resolvedModel: { provider: string; modelId: string } | null;
+  modelSource: "explicit" | "session" | "definition" | "global" | "pi";
+  thinkingLevel: string | null;
+  thinkingSource: "explicit" | "session" | "advisor" | "definition" | "global" | "pi";
+  tokenDetail: {
+    inputTokens: number | null;
+    outputTokens: number | null;
+    cacheReadTokens: number | null;
+    cacheWriteTokens: number | null;
+    reasoningTokens: number | null;
+  };
   /**
    * Why there is no advice. `declined` means the advisor answered with nothing; `error` means it could not be
    * reached or its response was unrecognised; `cancelled` means the CALLER went away, which is not the advisor's
@@ -49,9 +60,22 @@ export interface AdviceRecord {
   outcome: "answered" | "disabled" | "timeout" | "error" | "declined" | "cancelled";
 }
 
+export interface AdviceAttribution {
+  resolvedModel: { provider: string; modelId: string } | null;
+  modelSource: AdviceRecord["modelSource"];
+  thinkingLevel: string | null;
+  thinkingSource: AdviceRecord["thinkingSource"];
+}
+
 export interface Advisor {
   task(task: string): string | TaskDigest;
-  ask(purpose: string, request: AdviceRequest, signal?: AbortSignal, executionId?: string): Promise<Advice | null>;
+  ask(
+    purpose: string,
+    request: AdviceRequest,
+    signal?: AbortSignal,
+    executionId?: string,
+    attribution?: AdviceAttribution | ((advice: Advice | null) => AdviceAttribution),
+  ): Promise<Advice | null>;
 }
 
 export function createAdvisor(input: {
@@ -74,8 +98,17 @@ export function createAdvisor(input: {
       }
       return digestTask(task);
     },
-    async ask(purpose, request, signal, executionId) {
+    async ask(purpose, request, signal, executionId, attribution) {
       const started = Date.now();
+      const attributionFor = (advice: Advice | null): AdviceAttribution =>
+        typeof attribution === "function"
+          ? attribution(advice)
+          : (attribution ?? {
+              resolvedModel: advice?.resolvedModel ?? null,
+              modelSource: "pi",
+              thinkingLevel: null,
+              thinkingSource: "pi",
+            });
       const base = {
         ...(input.episodeId ? { episodeId: input.episodeId } : {}),
         ...(executionId ? { executionId } : {}),
@@ -83,6 +116,14 @@ export function createAdvisor(input: {
         purpose,
         decider: input.decider.name,
         questions: Object.keys(request.questions),
+        ...attributionFor(null),
+        tokenDetail: {
+          inputTokens: null,
+          outputTokens: null,
+          cacheReadTokens: null,
+          cacheWriteTokens: null,
+          reasoningTokens: null,
+        },
       };
       const write = async (entry: AdviceRecord) => {
         try {
@@ -125,6 +166,8 @@ export function createAdvisor(input: {
             ]),
           ),
           ...(advice.model ? { model: advice.model } : {}),
+          ...attributionFor(advice),
+          ...(advice.tokenDetail ? { tokenDetail: advice.tokenDetail } : {}),
         });
         return advice;
       } catch {

package/src/advisors/decider.ts

@@ -46,6 +46,14 @@ export interface Advice {
   answers: Readonly<Record<string, Answer>>;
   /** What actually answered, as the transport reported it — a dated model id, not the one we asked for. */
   model?: string;
+  resolvedModel?: { provider: string; modelId: string };
+  tokenDetail?: {
+    inputTokens: number | null;
+    outputTokens: number | null;
+    cacheReadTokens: number | null;
+    cacheWriteTokens: number | null;
+    reasoningTokens: number | null;
+  };
 }
 
 export interface Decider {

package/src/advisors/jev.ts

@@ -93,9 +93,42 @@ export function parseAdvice(request: AdviceRequest, body: unknown): Advice | nul
     if (!parsed) return null;
     answers[key] = parsed;
   }
-  return { answers, ...(typeof envelope.model === "string" ? { model: envelope.model } : {}) };
+  const model = typeof envelope.model === "string" ? envelope.model : undefined;
+  const provider = typeof envelope.provider === "string" ? envelope.provider : undefined;
+  const tokenDetail = parseTokenDetail(envelope.usage);
+  return {
+    answers,
+    ...(model ? { model } : {}),
+    ...(model && provider ? { resolvedModel: { provider, modelId: model } } : {}),
+    ...(tokenDetail ? { tokenDetail } : {}),
+  };
 }
 
+function parseTokenDetail(value: unknown): Advice["tokenDetail"] | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  const usage = value as Record<string, unknown>;
+  const details = object(usage.input_tokens_details ?? usage.prompt_tokens_details);
+  const outputDetails = object(usage.output_tokens_details ?? usage.completion_tokens_details);
+  const read = (...keys: string[]): number | null => {
+    const reported = keys.map((key) => usage[key]).find((entry) => typeof entry === "number" && Number.isFinite(entry));
+    return typeof reported === "number" && reported > 0 ? reported : null;
+  };
+  const nested = (source: Record<string, unknown> | undefined, key: string): number | null => {
+    const reported = source?.[key];
+    return typeof reported === "number" && Number.isFinite(reported) && reported > 0 ? reported : null;
+  };
+  return {
+    inputTokens: read("input_tokens", "prompt_tokens"),
+    outputTokens: read("output_tokens", "completion_tokens"),
+    cacheReadTokens: read("cache_read_tokens") ?? nested(details, "cached_tokens"),
+    cacheWriteTokens: read("cache_write_tokens"),
+    reasoningTokens: read("reasoning_tokens") ?? nested(outputDetails, "reasoning_tokens"),
+  };
+}
+
+const object = (value: unknown): Record<string, unknown> | undefined =>
+  typeof value === "object" && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+
 export interface JevConfig {
   apiKey: string;
   model?: string;

package/src/cli.ts

@@ -36,9 +36,17 @@ import {
   type SkillPackage,
 } from "./kernel/skill-packages.ts";
 import { adoptLegacyEnvironment, legacyEnvironmentWarning } from "./kernel/env-names.ts";
-import { PI_PROJECT_DIR, PROJECT_FILES, PROJECT_STATE_DIRNAME } from "./kernel/project-paths.ts";
+import {
+  activityTimelinePath,
+  PI_PROJECT_DIR,
+  PROJECT_FILES,
+  PROJECT_STATE_DIRNAME,
+  projectLedgerPath,
+} from "./kernel/project-paths.ts";
 import { repairLedger } from "./governance/record.ts";
 import { importLegacyLedger } from "./governance/ledger.ts";
+import { commitsForRepo, renderEpisodeReport, reportEpisodes, type EpisodeGroupBy } from "./products/episode-report.ts";
+import { updateEpisodeOutcomes } from "./products/episode-outcomes.ts";
 
 /** The reviewable record, as the operator sees it relative to the project (ADR-0076 PR 3c). */
 const SETTINGS_REL = `${PI_PROJECT_DIR}/${PROJECT_STATE_DIRNAME}/${PROJECT_FILES.settings}`;
@@ -50,6 +58,9 @@ Usage:
                                            packages that declare skills (package.json "pi": {"skills": …})
   pi-daddy ledger repair <path> [--yes]   show the damaged tail of a ledger; --yes truncates it (ADR-0076)
   pi-daddy ledger import <source> <target> copy a pre-format ledger into the record format; the source is untouched
+  pi-daddy report [--since <date>] [--definition <name>] [--model <id>]
+                  [--group-by definition|model|thinking] [--json]
+  pi-daddy outcomes                       append changed episode outcomes from Git and CI
   pi-daddy --help | --version
 
 init references skills already enabled in Pi at their installed or local paths. Legacy unregistered npm
@@ -61,13 +72,18 @@ stays unspawnable. Capabilities that can change your machine
             It never rewrites ${SETTINGS_REL} — delete that file if you want it regenerated.`;
 
 export interface ParsedArgs {
-  command: "init" | "ledger-repair" | "ledger-import" | "help" | "version";
+  command: "init" | "ledger-repair" | "ledger-import" | "report" | "outcomes" | "help" | "version";
   importTarget?: string;
   /** `ledger repair <path>`: the ledger file; `yes` applies, otherwise preview only. */
   ledgerPath?: string;
   yes?: boolean;
   dir?: string;
   force: boolean;
+  since?: string;
+  definition?: string;
+  model?: string;
+  groupBy?: EpisodeGroupBy;
+  json?: boolean;
   /** Non-empty means refuse: argv said something this program does not understand. */
   errors: string[];
 }
@@ -105,6 +121,39 @@ export function parseArgs(argv: string[]): ParsedArgs {
     if (unknown.length) return { command: "help", force: false, errors: [`unknown option "${unknown[0]}"`] };
     return { command: "ledger-repair", force: false, errors: [], ledgerPath: target, yes: flags.includes("--yes") };
   }
+  if (command === "outcomes") {
+    return tail.length === 0
+      ? { command: "outcomes", force: false, errors: [] }
+      : { command: "outcomes", force: false, errors: [`unknown option ${tail[0]}`] };
+  }
+  if (command === "report") {
+    const parsed: ParsedArgs = { command: "report", force: false, errors: [] };
+    for (let index = 0; index < tail.length; index += 1) {
+      const flag = tail[index];
+      if (flag === "--json") {
+        parsed.json = true;
+        continue;
+      }
+      if (!["--since", "--definition", "--model", "--group-by"].includes(flag)) {
+        parsed.errors.push(`unknown option ${flag}`);
+        continue;
+      }
+      const value = tail[index + 1];
+      if (!value || value.startsWith("-")) {
+        parsed.errors.push(`${flag} needs a value`);
+        continue;
+      }
+      index += 1;
+      if (flag === "--since") {
+        if (Number.isNaN(Date.parse(value))) parsed.errors.push("--since needs a valid date");
+        else parsed.since = value;
+      } else if (flag === "--definition") parsed.definition = value;
+      else if (flag === "--model") parsed.model = value;
+      else if (["definition", "model", "thinking"].includes(value)) parsed.groupBy = value as EpisodeGroupBy;
+      else parsed.errors.push("--group-by needs definition, model, or thinking");
+    }
+    return parsed;
+  }
   if (command !== "init") return { command: "help", force: false, errors: [`unknown command "${command}"`] };
   const errors: string[] = [];
   let force = false;
@@ -325,6 +374,45 @@ export async function main(argv: string[]): Promise<number> {
     console.log(USAGE);
     return 0;
   }
+  if (parsed.command === "outcomes") {
+    const cwd = process.cwd();
+    const result = await updateEpisodeOutcomes({
+      cwd,
+      ledgerPath: projectLedgerPath(cwd),
+      activityPath: activityTimelinePath(cwd),
+    });
+    console.log(`pi-daddy: ${result.appended} outcome record(s) appended for ${result.outcomes.length} episode(s)`);
+    return 0;
+  }
+  if (parsed.command === "report") {
+    const cwd = process.cwd();
+    const readOptional = async (path: string): Promise<string> => {
+      try {
+        return await readFile(path, "utf8");
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") return "";
+        throw error;
+      }
+    };
+    const [ledgerText, activityText, commitByEpisode] = await Promise.all([
+      readOptional(projectLedgerPath(cwd)),
+      readOptional(activityTimelinePath(cwd)),
+      commitsForRepo(cwd),
+    ]);
+    const output = reportEpisodes({
+      ledgerText,
+      activityText,
+      commitByEpisode,
+      options: {
+        ...(parsed.since ? { since: parsed.since } : {}),
+        ...(parsed.definition ? { definition: parsed.definition } : {}),
+        ...(parsed.model ? { model: parsed.model } : {}),
+        ...(parsed.groupBy ? { groupBy: parsed.groupBy } : {}),
+      },
+    });
+    console.log(renderEpisodeReport(output, parsed.json === true).trimEnd());
+    return 0;
+  }
   if (parsed.command === "ledger-import") {
     const source = resolvePath(process.cwd(), parsed.ledgerPath!),
       target = resolvePath(process.cwd(), parsed.importTarget!);