refactor(agent): tidy rtk-savings reader from review feedback

Address qa-swarm + Greptile review on #3146:

- Guard the parsed JSON before indexing `summary` so a `"null"`/non-object
  payload returns null explicitly rather than throwing into the caller's catch.
- Thread the resolved `env` through to the `rtk gain` exec, so the binary is
  run against the same environment it was resolved from.
- Simplify the run-gain seam to return stdout directly (drop the unused stderr).
- Clarify that the counts are RTK's own token estimates (not bytes), and that
  the zero-guard is on command count.

Generated-By: PostHog Code
Task-Id: ea7c6128-03d7-492c-a1c8-734175f03927

Author: pauldambra

packages/agent/src/server/agent-server.ts

@@ -3394,6 +3394,7 @@ ${signedCommitInstructions}
         notification: {
           jsonrpc: "2.0",
           method: POSTHOG_NOTIFICATIONS.RTK_SAVINGS,
+          // snake_case: these land as PostHog event properties.
           params: {
             task_id: this.config.taskId,
             run_id: this.config.runId,

packages/agent/src/server/rtk-savings.test.ts

@@ -15,7 +15,7 @@ const GAIN_JSON = JSON.stringify({
 });
 
 function gain(stdout: string) {
-  return vi.fn().mockResolvedValue({ stdout, stderr: "" });
+  return vi.fn().mockResolvedValue(stdout);
 }
 
 describe("resolveRtkSavings", () => {
@@ -26,7 +26,7 @@ describe("resolveRtkSavings", () => {
       runGain,
     });
 
-    expect(runGain).toHaveBeenCalledWith("/bundled/rtk");
+    expect(runGain).toHaveBeenCalledWith("/bundled/rtk", expect.anything());
     expect(savings).toEqual({
       totalCommands: 2,
       inputTokens: 502691,
@@ -54,6 +54,8 @@ describe("resolveRtkSavings", () => {
     ],
     ["malformed JSON", "not json"],
     ["missing summary block", JSON.stringify({ daily: [] })],
+    ["the payload is JSON null", "null"],
+    ["the payload is a non-object", "42"],
   ])("returns null when %s", async (_label, stdout) => {
     const savings = await resolveRtkSavings({
       resolveBinary: () => "/bundled/rtk",

packages/agent/src/server/rtk-savings.ts

@@ -5,8 +5,10 @@ import { resolveRtkPrefix } from "../adapters/claude/session/rtk";
 const execFileAsync = promisify(execFile);
 
 /**
- * The `summary` block of `rtk gain --format json` — RTK's own tally of how much
- * command output it compressed away before it reached the model.
+ * The `summary` block of `rtk gain --format json` — RTK's own tally of the
+ * output it compressed away before it reached the model. The counts are RTK's
+ * token estimates (its own output labels them "Input/Output tokens" and "Tokens
+ * saved"), not raw bytes.
  */
 export interface RtkSavingsSummary {
   totalCommands: number;
@@ -16,26 +18,24 @@ export interface RtkSavingsSummary {
   avgSavingsPct: number;
 }
 
-interface GainOutput {
-  stdout: string;
-  stderr: string;
-}
-
 interface ResolveRtkSavingsOptions {
   env?: NodeJS.ProcessEnv;
   /** Resolves the rtk binary to invoke; undefined disables reporting. Overridable for tests. */
   resolveBinary?: (env: NodeJS.ProcessEnv) => string | undefined;
-  /** Runs `rtk gain` and returns its stdio; overridable for tests. */
-  runGain?: (binary: string) => Promise<GainOutput>;
+  /** Runs `rtk gain` and returns its stdout; overridable for tests. */
+  runGain?: (binary: string, env: NodeJS.ProcessEnv) => Promise<string>;
 }
 
 function toFiniteNumber(value: unknown): number {
   return typeof value === "number" && Number.isFinite(value) ? value : 0;
 }
 
 function parseGainSummary(stdout: string): RtkSavingsSummary | null {
-  const parsed = JSON.parse(stdout) as { summary?: Record<string, unknown> };
-  const summary = parsed.summary;
+  const parsed: unknown = JSON.parse(stdout);
+  // `JSON.parse("null")` returns null, and a non-object payload has no summary —
+  // guard before indexing rather than leaning on the caller's try/catch.
+  if (!parsed || typeof parsed !== "object") return null;
+  const summary = (parsed as { summary?: Record<string, unknown> }).summary;
   if (!summary || typeof summary !== "object") return null;
   return {
     totalCommands: toFiniteNumber(summary.total_commands),
@@ -46,13 +46,16 @@ function parseGainSummary(stdout: string): RtkSavingsSummary | null {
   };
 }
 
-async function defaultRunGain(binary: string): Promise<GainOutput> {
-  const { stdout, stderr } = await execFileAsync(
+async function defaultRunGain(
+  binary: string,
+  env: NodeJS.ProcessEnv,
+): Promise<string> {
+  const { stdout } = await execFileAsync(
     binary,
     ["gain", "--format", "json"],
-    { timeout: 5_000 },
+    { timeout: 5_000, env },
   );
-  return { stdout, stderr };
+  return stdout;
 }
 
 /**
@@ -73,9 +76,9 @@ export async function resolveRtkSavings({
   if (!binary) return null;
 
   try {
-    const { stdout } = await runGain(binary);
+    const stdout = await runGain(binary, env);
     const summary = parseGainSummary(stdout);
-    // Nothing was compressed this run — no point emitting a zero.
+    // No rtk-wrapped commands ran this session — nothing worth reporting.
     if (!summary || summary.totalCommands <= 0) return null;
     return summary;
   } catch {