feat(cli): flag dominant operations and clean labels in colony gain (#540)

Top spend now reports its share of total tokens, and a `Hot loop:` callout
fires when a single op holds >=70% of token spend across >=100 calls (e.g.
`task_plan_list` at 98%). The `Saved:` / `USD saved:` prefix labels are
renamed to `Net:` / `Net USD:` so the line no longer reads "Saved: X saved".
The live sessions header drops its trailing `, -` when cost isn't configured.

Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>

Author: NagyVikt

.changeset/spotty-spoons-pick.md

@@ -0,0 +1,10 @@
+---
+'colonyq': patch
+---
+
+Surface hot-loop dominance and drop double-"saved" labels in `colony gain`.
+Top spend now reports the operation's share of total tokens, and a `Hot loop:`
+callout fires when one operation owns ≥70% of token spend across ≥100 calls.
+The "Saved:" / "USD saved:" labels are renamed to "Net:" / "Net USD:" so the
+phrase no longer reads "Saved: X saved", and the live sessions header drops the
+trailing `, -` when cost isn't configured.

apps/cli/src/commands/gain.ts

@@ -445,12 +445,21 @@ function writeLiveOverview(
   }
   const topSpend = findTopTokenSpend(rows);
   if (topSpend !== null) {
+    const share = totals.total_tokens > 0 ? topSpend.total_tokens / totals.total_tokens : 0;
+    const shareLabel = formatShare(share);
     w.write(
       `${kleur.dim('Top spend:')} ${topSpend.operation} ${formatTokens(
         topSpend.total_tokens,
-      )} tokens across ${topSpend.calls} call${topSpend.calls === 1 ? '' : 's'} ` +
-        `(avg ${formatTokens(avgTokens(topSpend))}/call)\n`,
+      )} tokens (${shareLabel} of total) across ${topSpend.calls} call${
+        topSpend.calls === 1 ? '' : 's'
+      } (avg ${formatTokens(avgTokens(topSpend))}/call)\n`,
     );
+    if (share >= 0.7 && topSpend.calls >= 100) {
+      w.write(
+        `${kleur.yellow('Hot loop:')} ${topSpend.operation} dominates token spend ` +
+          `(${shareLabel}); narrow filters, raise compact mode, or cache the result.\n`,
+      );
+    }
   }
 }
 
@@ -464,11 +473,14 @@ function writeLiveSessionSection(
   w.write('\n');
   w.write(`${kleur.bold('Live sessions')}\n`);
   const truncation = summary.sessions_truncated ? `; showing ${sessions.length}` : '';
+  const costSuffix = costBasis.configured
+    ? `, ${formatUsdConfigured(summary.avg_total_cost_usd)}`
+    : '';
   w.write(
     kleur.dim(
       `Sessions with receipts: ${summary.session_count}${truncation}; avg/session: ${summary.avg_calls} calls, ${formatTokens(
         summary.avg_total_tokens,
-      )} tokens, ${formatUsd(summary.avg_total_cost_usd, costBasis)}.\n`,
+      )} tokens${costSuffix}.\n`,
     ),
   );
   const head = padRow(
@@ -585,7 +597,7 @@ function writeGainFocus(
         matchedCalls,
         totalCalls,
       )})`,
-      `${kleur.dim('Saved:')} ${formatTokenDelta(savedTokens)}`,
+      `${kleur.dim('Net:')} ${formatTokenDelta(savedTokens)}`,
       `${kleur.dim('Next:')} ${next}`,
     ].join('  '),
   );
@@ -600,7 +612,7 @@ function writeGainFocus(
   if (comparisonCost !== null && comparisonCost.totals.calls > 0) {
     process.stdout.write(
       [
-        `${kleur.dim('USD saved:')} ${formatUsdDelta(comparisonCost.totals.saved_cost_usd)}`,
+        `${kleur.dim('Net USD:')} ${formatUsdDelta(comparisonCost.totals.saved_cost_usd)}`,
         `${kleur.dim('Colony spent:')} ${formatUsdConfigured(
           comparisonCost.totals.colony_cost_usd,
         )}`,
@@ -737,6 +749,13 @@ function formatPercent(part: number, whole: number): string {
   return `${value.toFixed(1)}%`;
 }
 
+function formatShare(ratio: number): string {
+  if (!Number.isFinite(ratio) || ratio <= 0) return '0%';
+  const pct = ratio * 100;
+  if (pct >= 10) return `${Math.round(pct)}%`;
+  return `${pct.toFixed(1)}%`;
+}
+
 function avgTokens(row: Pick<McpMetricsAggregateRow, 'calls' | 'total_tokens'>): number {
   return row.calls <= 0 ? 0 : Math.round(row.total_tokens / row.calls);
 }

apps/cli/test/gain.test.ts

@@ -107,7 +107,7 @@ describe('gain command output', () => {
     expect(output).toContain('Errors: 1 (50%)');
     expect(output).toContain('Cost total: $0.000125');
     expect(output).toContain('Needs attention: 1x search TASK_NOT_FOUND - task 6 not found');
-    expect(output).toContain('Top spend: search 75 tokens across 2 calls');
+    expect(output).toContain('Top spend: search 75 tokens (100% of total) across 2 calls');
     expect(output).toContain('Operations');
     expect(output).toContain('OK');
     expect(output).toContain('Tok total');
@@ -252,6 +252,104 @@ describe('gain command output', () => {
     );
   });
 
+  it('flags a hot loop when one operation dominates token spend at high call volume', () => {
+    let output = '';
+    vi.spyOn(process.stdout, 'write').mockImplementation((chunk: string | Uint8Array) => {
+      output += String(chunk);
+      return true;
+    });
+
+    const dominantRow: McpMetricsAggregateRow = {
+      operation: 'task_plan_list',
+      calls: 7597,
+      ok_count: 7597,
+      error_count: 0,
+      error_reasons: [],
+      ...METRIC_DETAIL,
+      input_bytes: 0,
+      output_bytes: 0,
+      total_bytes: 0,
+      input_tokens: 92_800,
+      output_tokens: 34_480_000,
+      total_tokens: 34_580_000,
+      input_cost_usd: 0,
+      output_cost_usd: 0,
+      total_cost_usd: 0,
+      avg_cost_usd: 0,
+      avg_input_tokens: 12,
+      avg_output_tokens: 4_500,
+      total_duration_ms: 7597 * 55,
+      avg_duration_ms: 55,
+      last_ts: Date.now(),
+    };
+    const totals: McpMetricsAggregateRow = {
+      ...dominantRow,
+      operation: '',
+      total_tokens: 35_260_000,
+      input_tokens: 171_500,
+      output_tokens: 35_080_000,
+    };
+
+    writeLiveSection(
+      [dominantRow],
+      totals,
+      SESSION_SUMMARY,
+      [SESSION_ROW],
+      { input_usd_per_1m_tokens: 0, output_usd_per_1m_tokens: 0, configured: false },
+      168,
+      undefined,
+    );
+
+    expect(output).toContain('Top spend: task_plan_list 34.58M tokens (98% of total)');
+    expect(output).toContain('Hot loop:');
+    expect(output).toContain('task_plan_list dominates token spend');
+  });
+
+  it('omits cost suffix from live sessions header when cost is not configured', () => {
+    let output = '';
+    vi.spyOn(process.stdout, 'write').mockImplementation((chunk: string | Uint8Array) => {
+      output += String(chunk);
+      return true;
+    });
+
+    const row: McpMetricsAggregateRow = {
+      operation: 'search',
+      calls: 1,
+      ok_count: 1,
+      error_count: 0,
+      error_reasons: [],
+      ...METRIC_DETAIL,
+      input_bytes: 0,
+      output_bytes: 0,
+      total_bytes: 0,
+      input_tokens: 25,
+      output_tokens: 50,
+      total_tokens: 75,
+      input_cost_usd: 0,
+      output_cost_usd: 0,
+      total_cost_usd: 0,
+      avg_cost_usd: 0,
+      avg_input_tokens: 25,
+      avg_output_tokens: 50,
+      total_duration_ms: 40,
+      avg_duration_ms: 40,
+      last_ts: Date.now(),
+    };
+
+    writeLiveSection(
+      [row],
+      row,
+      SESSION_SUMMARY,
+      [SESSION_ROW],
+      { input_usd_per_1m_tokens: 0, output_usd_per_1m_tokens: 0, configured: false },
+      168,
+      undefined,
+    );
+
+    expect(output).toContain('Sessions with receipts: 1');
+    expect(output).not.toContain('tokens, -.');
+  });
+
   it('prints live metrics before the live comparison model', () => {
     let output = '';
     vi.spyOn(process.stdout, 'write').mockImplementation((chunk: string | Uint8Array) => {
@@ -315,9 +413,9 @@ describe('gain command output', () => {
     expect(output).toContain('Search result shape');
     expect(output).toContain('Gain focus');
     expect(output).toContain('Coverage: 1 / 1 live calls (100%)');
-    expect(output).toContain('Saved: 4.9k saved');
+    expect(output).toContain('Net: 4.9k saved');
     expect(output).toContain('Top saving: Search result shape 4.9k saved across 1 call');
-    expect(output).toContain('USD saved: $0.008208 saved');
+    expect(output).toContain('Net USD: $0.008208 saved');
     expect(output).toContain('Colony spent: $0.000125');
     expect(output).toContain('Standard est: $0.008333');
     expect(output).toContain('Live matched total');

openspec/changes/agent-claude-fix-gain-output-double-word-and-add-hot-2026-05-14-13-40/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-14

openspec/changes/agent-claude-fix-gain-output-double-word-and-add-hot-2026-05-14-13-40/notes.md

@@ -0,0 +1,26 @@
+# agent-claude-fix-gain-output-double-word-and-add-hot-2026-05-14-13-40 (minimal / T1)
+
+Branch: `agent/claude/fix-gain-output-double-word-and-add-hot-2026-05-14-13-40`
+
+Tighten `colony gain` so dominance jumps off the page and the labels stop reading like
+duplicated verbs.
+
+- Top spend line now shows `(N% of total)` so an operation owning 98% of token spend
+  is impossible to miss when scanning.
+- New `Hot loop:` callout fires when a single op holds ≥70% of token spend across
+  ≥100 calls, with a one-line nudge (narrow filters / compact mode / cache result).
+- `Saved:` / `USD saved:` prefix labels renamed to `Net:` / `Net USD:` to drop the
+  "Saved: X saved" double-word; `formatTokenDelta` / `formatUsdDelta` still emit the
+  "X saved" / "X over" phrase verbatim so the `Top saving:` sentence reads naturally.
+- Live sessions header trims its trailing `, -` when cost isn't configured.
+
+## Handoff
+
+- Handoff: change=`agent-claude-fix-gain-output-double-word-and-add-hot-2026-05-14-13-40`; branch=`agent/<your-name>/<branch-slug>`; scope=`TODO`; action=`continue this sandbox or finish cleanup after a usage-limit/manual takeover`.
+- Copy prompt: Continue `agent-claude-fix-gain-output-double-word-and-add-hot-2026-05-14-13-40` on branch `agent/<your-name>/<branch-slug>`. Work inside the existing sandbox, review `openspec/changes/agent-claude-fix-gain-output-double-word-and-add-hot-2026-05-14-13-40/notes.md`, continue from the current state instead of creating a new sandbox, and when the work is done run `gx branch finish --branch agent/<your-name>/<branch-slug> --base dev --via-pr --wait-for-merge --cleanup`.
+
+## Cleanup
+
+- [ ] Run: `gx branch finish --branch agent/<your-name>/<branch-slug> --base dev --via-pr --wait-for-merge --cleanup`
+- [ ] Record PR URL + `MERGED` state in the completion handoff.
+- [ ] Confirm sandbox worktree is gone (`git worktree list`, `git branch -a`).