omp-conductor 0.19.6 → 0.20.0

package/src/setup.ts

@@ -21,12 +21,14 @@
  * `src/gh.ts` exposing `gh()` (throwing) over `ghTry()` (classifying).
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, relative } from "node:path";
 import { parse as parseYaml } from "yaml";
 import {
+  AGENTS_BRIEF_NAME,
   COMPOSE_BANNER,
+  CONSOLE_BRIEF_NAME,
   ORCHESTRATOR_BRIEF_NAME,
   POLICY_BRIEF_NAME,
   composeOrchestrator,
@@ -51,6 +53,7 @@ import {
 } from "./config.ts";
 import { graphProjectPath, graphRepos } from "./graph.ts";
 import { modelRolesIn, ompSettingsOverlay } from "./omp-settings.ts";
+import { shellQuote } from "./shell.ts";
 import {
   CONFIG_VERSION,
   DEFAULT_ARM_PROOF,
@@ -168,6 +171,12 @@ export interface SetupAnswers {
    * to survive an amend of some other area (#369).
    */
   groomBelow?: GroomTrigger;
+  /**
+   * The OMP model role the daemon's own grooming scouts run under (#1041).
+   * Hand-edited like {@link groomBelow} — the wizard never asks — so it exists
+   * here only to survive an amend of some other area (#369).
+   */
+  groomRole?: string;
   /**
    * Ordered fallback worker models and the provider-failure threshold that
    * starts them. The wizard never asks for either — they are hand-edited —
@@ -583,7 +592,7 @@ export const PROMOTION_DUTIES: { readonly [K in AuthorityHolder]: string } = {
     "operator can take it back by editing this paragraph.",
 };
 
-export { ORCHESTRATOR_BRIEF_NAME, POLICY_BRIEF_NAME };
+export { AGENTS_BRIEF_NAME, CONSOLE_BRIEF_NAME, ORCHESTRATOR_BRIEF_NAME, POLICY_BRIEF_NAME };
 
 /** Shipped floor template — duties, tiers, hard boundaries, Learning loop. */
 const ORCHESTRATOR_TEMPLATE_PATH = join(import.meta.dir, "briefs", "orchestrator.md");
@@ -591,6 +600,13 @@ const ORCHESTRATOR_TEMPLATE_PATH = join(import.meta.dir, "briefs", "orchestrator
 /** Shipped POLICY.md scaffold — Releases, Project context, Reporting, Amendments. */
 const POLICY_TEMPLATE_PATH = join(import.meta.dir, "briefs", "policy.md");
 
+/**
+ * Shipped console floor — the operator console's role, delivery contract,
+ * authority and boundaries. Render-only: it has no `POLICY.md` half, is never
+ * composed, and is never classified by `inspectBriefLayout`.
+ */
+const CONSOLE_TEMPLATE_PATH = join(import.meta.dir, "briefs", "console.md");
+
 /**
  * `repo` writes labels and closes issues; `project` moves cards on the board.
  * Both are load-bearing for an unattended loop, so a missing one is reported
@@ -1014,6 +1030,10 @@ export function buildProject(a: SetupAnswers): ProjectConfig {
       : {}),
     // A documented hand-edited key, so an unrelated amend must not delete it.
     ...(a.groomBelow === undefined ? {} : { groomBelow: a.groomBelow }),
+    // Same contract for the daemon's grooming-scout role: hand-edited, and an
+    // amend that dropped it would silently move grooming back to the harness
+    // default model (#1041).
+    ...(a.groomRole === undefined ? {} : { groomRole: a.groomRole }),
     // The failover chain is hand-edited too: dropping it on an unrelated amend
     // would pin every run of the project onto a dead provider again (#286).
     ...(a.modelFallbacks === undefined ? {} : { modelFallbacks: [...a.modelFallbacks] }),
@@ -1256,6 +1276,7 @@ export function answersFromProject(p: ProjectConfig): SetupAnswers {
   // what keeps the rewritten config identical to the one that was read.
   if (p.workerModel !== undefined) answers.workerModel = p.workerModel;
   if (p.groomBelow !== undefined) answers.groomBelow = p.groomBelow;
+  if (p.groomRole !== undefined) answers.groomRole = p.groomRole;
   if (p.modelFallbacks !== undefined) answers.modelFallbacks = [...p.modelFallbacks];
   if (p.modelFallbackThreshold !== undefined) answers.modelFallbackThreshold = p.modelFallbackThreshold;
   if (p.workerEscalationModel !== undefined) answers.workerEscalationModel = p.workerEscalationModel;
@@ -1365,6 +1386,205 @@ export function renderPolicyForProject(p: ProjectConfig): string {
   return renderBriefTemplate(shippedPolicyTemplate(), briefVarsForProject(p));
 }
 
+// ------------------------------------------------------- the operator console
+//
+// The console is the second session of the two-session split: the tick brain
+// keeps its pane and never receives an operator turn, and this one owns the
+// Telegram conversation 24/7. Everything below provisions its workspace, and
+// the whole point of the shape is what it does NOT do:
+//
+//  - **No tick config.** The tick extension activates only when
+//    `.conductor-tick.json` exists in the session cwd, so a console cwd
+//    without one is inert by construction rather than by a runtime check that
+//    could be got wrong. Nothing here ever writes that file.
+//  - **No POLICY.md, no compose, no layout classification.** The floor is
+//    rendered and written; there is no operator half to merge, so
+//    `refreshComposedBrief` and `inspectBriefLayout` never see this file.
+//  - **Derived, never stamped.** The cwd is a function of the state dir and
+//    the project name, in TypeScript here and in the same shape in
+//    `recover.sh`. A config key would be a second copy of the answer, and the
+//    copy nobody updated is the one a pane would `cd` into.
+
+/**
+ * The console session's own directory: `<stateDir>/console/<project>`.
+ *
+ * Under the state root rather than beside the project's worktrees because the
+ * console is a fleet surface, not a checkout — and because a directory the
+ * worker machinery never touches cannot be force-removed by a re-claim.
+ */
+export function consoleCwdForProject(p: ProjectConfig): string {
+  return join(stateDir(), "console", p.name);
+}
+
+/** The rendered console floor inside {@link consoleCwdForProject}. */
+export function consoleBriefPathForProject(p: ProjectConfig): string {
+  return join(consoleCwdForProject(p), CONSOLE_BRIEF_NAME);
+}
+
+/** Shipped console floor template, placeholders and all. */
+export function shippedConsoleTemplate(): string {
+  return readFileSync(CONSOLE_TEMPLATE_PATH, "utf8");
+}
+
+/**
+ * Rendered console floor for a configured project.
+ *
+ * The same `briefVarsForProject` coordinates the orchestrator floor gets, so a
+ * placeholder either template names is filled from one table — a console that
+ * shipped a literal `{{PROJECT}}` to a session would be reading a template,
+ * not a brief.
+ */
+export function renderConsoleForProject(p: ProjectConfig): string {
+  return renderBriefTemplate(shippedConsoleTemplate(), briefVarsForProject(p));
+}
+
+/**
+ * The shell line that launches the console pane, produced here so
+ * `omp-conductor console` and `recover.sh` cannot print two different commands
+ * for one surface.
+ *
+ * `dmOwner` is the Telegram DM force-claim, and it is a host-level judgement,
+ * not a preference: one state dir may have exactly one DM owner, so a host
+ * with several fleet cwds launches its consoles without it and lets inbound
+ * messages arrive by forum-topic routing instead. Nothing else in this package
+ * sets `OMP_TELEGRAM_DM_OWNER`.
+ */
+export function consolePaneCommand(opts: { cwd: string; dmOwner: boolean }): string {
+  // Quoted because the reader copies what a surface prints: a state root under
+  // a path with a space or a `$` must still `cd` where it says.
+  return `cd ${shellQuote(opts.cwd)} && ${opts.dmOwner ? "OMP_TELEGRAM_DM_OWNER=1 " : ""}omp`;
+}
+
+/**
+ * The `AGENTS.md` link in the console cwd and what provisioning will do about
+ * it, with the same never-clobber discipline the fleet pane's link gets: an
+ * already-correct symlink is kept, a stale one is replaced, and a **regular
+ * file** is an operator's own brief — reported and left untouched.
+ */
+export interface ConsoleLinkPlan {
+  path: string;
+  /** Relative target inside the symlink — `CONSOLE.md`, its own directory. */
+  target: string;
+  action: "create" | "update" | "keep" | "skip";
+  /** Why {@link action} is `skip`; present only then. */
+  skippedReason?: string;
+}
+
+/** What provisioning the console workspace will write, before it writes it. */
+export interface ConsolePlan {
+  /** The directory the console pane runs in. Created by the write. */
+  cwd: string;
+  /** The rendered floor: `create` on a fresh cwd, `keep` when already current. */
+  brief: { path: string; content: string; action: "create" | "update" | "keep" };
+  link: ConsoleLinkPlan;
+}
+
+/**
+ * Plans the console workspace for a project. Pure: reads the filesystem,
+ * writes nothing, so `setup host` can show the whole thing before consent and
+ * `omp-conductor console` can report what it did.
+ */
+export function planConsole(p: ProjectConfig): ConsolePlan {
+  const cwd = consoleCwdForProject(p);
+  const briefPath = consoleBriefPathForProject(p);
+  const content = renderConsoleForProject(p);
+  const linkPath = join(cwd, AGENTS_BRIEF_NAME);
+  // Relative, and inside the same directory, so the whole console cwd stays
+  // movable — the same reason the fleet pane's link is relative.
+  const target = relative(dirname(linkPath), briefPath);
+  // An unreadable existing brief is planned as `update`: rewriting it is the
+  // repair, and a plan that reported `keep` on a file it could not read would
+  // leave the console without a floor.
+  let live: string | undefined;
+  try {
+    live = readFileSync(briefPath, "utf8");
+  } catch {
+    live = undefined;
+  }
+  return {
+    cwd,
+    brief: {
+      path: briefPath,
+      content,
+      action: live === undefined ? (existsSync(briefPath) ? "update" : "create") : live === content ? "keep" : "update",
+    },
+    link: planConsoleLink(linkPath, target),
+  };
+}
+
+function planConsoleLink(path: string, target: string): ConsoleLinkPlan {
+  let st;
+  try {
+    st = lstatSync(path);
+  } catch {
+    // ENOENT, and any unreadable parent, both collapse to a best-effort
+    // create; a filesystem that refuses the link surfaces at write time.
+    return { path, target, action: "create" };
+  }
+  if (st.isSymbolicLink()) {
+    return { path, target, action: readlinkSync(path, "utf8") === target ? "keep" : "update" };
+  }
+  return {
+    path,
+    target,
+    action: "skip",
+    skippedReason: `an existing file at ${path} is not ours to overwrite; left untouched`,
+  };
+}
+
+/** What {@link writeConsole} wrote, plus anything it could not. */
+export interface ConsoleWrite {
+  wrote: string[];
+  /** Best-effort failures the caller surfaces; provisioning continues. */
+  warnings: string[];
+}
+
+/**
+ * Materialises a planned console workspace. Idempotent: a `keep` brief and a
+ * `keep` link touch nothing, so re-running `omp-conductor console` or
+ * `setup host` rewrites nothing and reports an empty write.
+ *
+ * The link is re-`lstat`ed here rather than trusted from the plan, because the
+ * entry can change across the consent gap: an operator who drops their own
+ * `AGENTS.md` where a stale symlink was planned for replacement must keep it.
+ */
+export function writeConsole(plan: ConsolePlan): ConsoleWrite {
+  const wrote: string[] = [];
+  const warnings: string[] = [];
+  mkdirSync(plan.cwd, { recursive: true });
+  if (plan.brief.action !== "keep") {
+    writeFileSync(plan.brief.path, plan.brief.content);
+    wrote.push(plan.brief.path);
+  }
+  if (plan.link.action === "create" || plan.link.action === "update") {
+    const { path, target } = plan.link;
+    try {
+      let existing;
+      try {
+        existing = lstatSync(path);
+      } catch {
+        existing = undefined;
+      }
+      if (existing !== undefined && !existing.isSymbolicLink()) {
+        warnings.push(
+          `${path} is a regular file, not ours to overwrite; console AGENTS.md link skipped`,
+        );
+      } else if (existing !== undefined && readlinkSync(path, "utf8") === target) {
+        // Already correct, however the plan read it.
+      } else {
+        if (existing !== undefined) rmSync(path, { force: true });
+        symlinkSync(target, path);
+        wrote.push(path);
+      }
+    } catch (err) {
+      warnings.push(
+        `could not link ${path} -> ${target}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+  return { wrote, warnings };
+}
+
 /**
  * Composed session brief: rendered floor + shared policy (when present) +
  * POLICY scaffold (or a caller's policy).
@@ -1811,6 +2031,12 @@ export function summarisePlan(
       `  ${"cap escalation".padEnd(CAPS_PLAN_KEY_PAD)}${a.workerEscalationModel.trim()}  (hand-edited)`,
     );
   }
+  // The daemon spends real money grooming unattended (#1041), so which role it
+  // spends it under belongs on the plan a human approves — hand-edited, like
+  // the cap-escalation tier above it, and silent when nobody answered.
+  if (a.groomRole !== undefined && a.groomRole.trim().length > 0) {
+    lines.push(`  ${"groom role".padEnd(CAPS_PLAN_KEY_PAD)}${a.groomRole.trim()}  (hand-edited)`);
+  }
 
   lines.push("", "escalation");
   if (a.telegramChatId !== undefined && a.telegramChatId.trim().length > 0) {

package/src/stats.ts

@@ -17,10 +17,32 @@
  * the doctor `spend-telemetry` finding): a run whose `spendUsd` reads 0.00
  * means harness telemetry was absent, not that the run was free. Such runs are
  * counted separately as **unmetered** and never averaged into a per-issue cost.
+ *
+ * ## Attribution (Phase 4)
+ *
+ * Two additions, both about *where the money went* rather than what it bought:
+ *
+ * - **Per model.** Worker runs grouped by `resolvedModel` — the model the
+ *   harness actually ran and therefore the one that was billed. Never grouped
+ *   by the requested model: a requested model is not evidence of a resolved
+ *   one, and a row that observed none groups under {@link UNRESOLVED_MODEL}
+ *   rather than being guessed into a bucket.
+ * - **Daemon-owned sessions.** To-spec grooming and review adjudication run as
+ *   the daemon's own sessions, not as worker runs, so their cost was logged and
+ *   then lost. They arrive here as `sessionSpendSince` rows and are summed *per
+ *   role*, deliberately outside the issue-journey aggregation: a role row in
+ *   `runs` would corrupt the merged/settled counts, which is why the store
+ *   keeps them in their own table.
+ *
+ * The orchestrator's own tick turns are absent from both, and that absence is
+ * reported rather than hidden ({@link StatsReport.unmeteredRoles}): the tick
+ * extension observes no usage events at all, so there is no number — and a
+ * `$0.00` for it would read as free.
  */
 
 import { utcDay } from "./store.ts";
-import type { RunRecord } from "./types.ts";
+import { SESSION_SPEND_ROLES } from "./types.ts";
+import type { RunRecord, SessionSpendRole, SessionSpendRow } from "./types.ts";
 
 /** The bounded window a report answers over. Day keys are UTC (`YYYY-MM-DD`). */
 export interface StatsWindow {
@@ -57,6 +79,51 @@ export interface RepoStats {
   failureClasses: Record<string, number>;
 }
 
+/**
+ * Worker runs attributed to one billed model (Phase 4).
+ *
+ * Counted over every run in the outcomes this report counts — the failures
+ * included, because money spent losing is precisely what a per-model
+ * comparison exists to expose: a model that burns a budget and never merges
+ * must not read as cheap.
+ *
+ * So this is deliberately a *wider* figure than {@link RepoStats.spendUsd},
+ * which sums merged chains only. The two answer different questions ("what did
+ * delivered work cost" versus "what did this model cost us"), and they are not
+ * meant to add up to each other.
+ */
+export interface ModelStats {
+  /** `resolvedModel`, or {@link UNRESOLVED_MODEL} when the run observed none. */
+  model: string;
+  /** Runs in the window on this model, across every issue. */
+  runs: number;
+  /** Runs whose state is `merged` — the attempt that actually delivered. */
+  merges: number;
+  /** Metered (spendUsd > 0) spend on this model, rounded to cents. */
+  spendUsd: number;
+  /** `spendUsd / merges`; `null` with no merge to divide by — never a zero,
+   *  and never a division by zero. */
+  spendPerMerge: number | null;
+  /** Runs on this model whose spend read $0.00: telemetry absent, not free. */
+  unmeteredRuns: number;
+}
+
+/** One daemon-owned session role's accounting (Phase 4). */
+export interface SessionRoleStats {
+  role: SessionSpendRole;
+  sessions: number;
+  turns: number;
+  /** Summed cost of the sessions that reported one, rounded to cents. */
+  spendUsd: number;
+  /**
+   * Sessions whose provider reported no cost at all. Distinct from a reported
+   * `0` by contract (`SessionSpendRow.spendUsd` is optional for exactly this
+   * reason), so this count is the honest "cost unknown" — never folded into
+   * `spendUsd` as a zero.
+   */
+  unmeteredSessions: number;
+}
+
 /** The stable report shape `--json` prints; the human renderer reads it too. */
 export interface StatsReport {
   project: string;
@@ -72,6 +139,27 @@ export interface StatsReport {
   total: RepoStats;
   /** Per-repo aggregates of the same shape, busiest (by merges) first. */
   repos: RepoStats[];
+  /** Worker runs by billed model, busiest (by runs) first (Phase 4). */
+  models: ModelStats[];
+  /** Daemon-owned session spend by role, in `SESSION_SPEND_ROLES` order. */
+  sessions: SessionRoleStats[];
+  /**
+   * Metered spend on to-spec grooming sessions — the plan's `groomSpendUsd`,
+   * named at the top level because "what did keeping the queue full cost" is a
+   * question asked on its own. Same number as the `groom` row in
+   * {@link StatsReport.sessions}; `groomUnmeteredSessions` is the part of it
+   * whose cost is unknown rather than zero.
+   */
+  groomSpendUsd: number;
+  groomUnmeteredSessions: number;
+  /**
+   * Roles whose spend cannot be observed at all, so no row exists to sum and
+   * no total here includes them. Present in the shape so a consumer adding
+   * `total.spendUsd` to `sessions` knows what is still missing instead of
+   * reading the sum as the fleet's whole bill. Today: `orchestrator` — the
+   * tick extension observes no usage events.
+   */
+  unmeteredRoles: string[];
 }
 
 /** Terminal non-merged run states — everything the failure histogram counts. */
@@ -86,6 +174,16 @@ const FAILED_STATES: ReadonlySet<RunRecord["state"]> = new Set([
 /** Runs with no classified failure fall into this explicit bucket. */
 export const UNCLASSIFIED = "unclassified";
 
+/**
+ * Runs that never observed a resolved model group here (Phase 4).
+ *
+ * Parenthesised so it cannot collide with a real model id, and explicit rather
+ * than omitted: a run predating the column, or one whose harness never reported
+ * the model it ran, still cost money, and dropping it would make the per-model
+ * spend quietly fail to add up to the total.
+ */
+export const UNRESOLVED_MODEL = "(unresolved)";
+
 /** The timestamp a run is placed on the window timeline. Mirrors the store's
  *  `COALESCE(endedAt, startedAt)` convention everywhere else in this package. */
 const WINDOW_KEY = (run: RunRecord): number => run.endedAt ?? run.startedAt;
@@ -216,11 +314,19 @@ export function parseStatsWindow(raw: string, now: number): StatsWindow | undefi
   return undefined;
 }
 
+/**
+ * `sessions` is `store.sessionSpendSince(project, window.sinceEpochMs)`. It is
+ * optional because a caller with nothing to say about daemon-owned sessions —
+ * and every pre-Phase-4 caller — must still get a report; an empty list means
+ * "no grooming or adjudication in this window", which the renderer states as
+ * that rather than as a $0.00 bill.
+ */
 export function computeStats(args: {
   project: string;
   window: StatsWindow;
   ghCalls: number;
   runs: readonly RunRecord[];
+  sessions?: readonly SessionSpendRow[];
 }): StatsReport {
   const chains = new Map<number, RunRecord[]>();
   for (const run of args.runs) {
@@ -234,6 +340,7 @@ export function computeStats(args: {
   const failureRuns: { repo: string; cls: string }[] = [];
   let unmeteredRuns = 0;
   const unmeteredByRepo = new Map<string, number>();
+  const byModel = new Map<string, ModelBucket>();
 
   for (const chain of chains.values()) {
     // One issue merges once; if a weird history ever carried two merged rows,
@@ -262,6 +369,14 @@ export function computeStats(args: {
         unmeteredRuns += 1;
         unmeteredByRepo.set(run.repo, (unmeteredByRepo.get(run.repo) ?? 0) + 1);
       }
+      // Attributed over exactly the runs this report already counts, so the
+      // per-model breakdown adds up to the totals printed beside it. Grouped on
+      // the *resolved* model: that is the one that was billed.
+      const model = modelBucket(byModel, run.resolvedModel ?? UNRESOLVED_MODEL);
+      model.runs += 1;
+      if (run.state === "merged") model.merges += 1;
+      if (run.spendUsd > 0) model.spend += run.spendUsd;
+      else model.unmetered += 1;
       if (merged === undefined && FAILED_STATES.has(run.state) && WINDOW_KEY(run) >= args.window.sinceEpochMs) {
         failureRuns.push({ repo: run.repo, cls: run.failureClass ?? UNCLASSIFIED });
       }
@@ -297,6 +412,21 @@ export function computeStats(args: {
     )
     .sort((a, b) => b.merged - a.merged || b.settled - a.settled || a.repo.localeCompare(b.repo));
 
+  const models = [...byModel.entries()]
+    .map(([model, b]) => ({
+      model,
+      runs: b.runs,
+      merges: b.merges,
+      spendUsd: cents(b.spend),
+      // No merge to divide by is "not measured", never a zero and never a
+      // division by zero — the same rule the per-issue cost follows.
+      spendPerMerge: b.merges === 0 ? null : cents(b.spend / b.merges),
+      unmeteredRuns: b.unmetered,
+    }))
+    .sort((a, b) => b.runs - a.runs || b.spendUsd - a.spendUsd || a.model.localeCompare(b.model));
+  const sessions = summarizeSessions(args.sessions ?? []);
+  const groom = sessions.find((s) => s.role === "groom");
+
   return {
     project: args.project,
     window: args.window,
@@ -304,9 +434,63 @@ export function computeStats(args: {
     empty: outcomes.length === 0,
     total: summarize({ repo: "(all)", outcomes, failureRuns, unmeteredRuns }),
     repos,
+    models,
+    sessions,
+    groomSpendUsd: groom?.spendUsd ?? 0,
+    groomUnmeteredSessions: groom?.unmeteredSessions ?? 0,
+    unmeteredRoles: [...UNMETERED_ROLES],
   };
 }
 
+/** One model's accumulating totals while the chains are walked. */
+interface ModelBucket {
+  runs: number;
+  merges: number;
+  spend: number;
+  unmetered: number;
+}
+
+function modelBucket(map: Map<string, ModelBucket>, model: string): ModelBucket {
+  let found = map.get(model);
+  if (found === undefined) {
+    found = { runs: 0, merges: 0, spend: 0, unmetered: 0 };
+    map.set(model, found);
+  }
+  return found;
+}
+
+/**
+ * Roles the fleet runs whose spend nothing can observe, so no row exists to
+ * sum. The orchestrator session is the case: its tick extension reads content
+ * text out of `message_start` and no usage event at all, so there is no number
+ * to record. Named in the report rather than left out, because a total that
+ * silently omits a whole role is the misreading this surface exists to prevent.
+ */
+const UNMETERED_ROLES = ["orchestrator"] as const;
+
+/**
+ * Daemon-owned session rows reduced per role, in `SESSION_SPEND_ROLES` order so
+ * the shape is stable whether or not a role ran in the window.
+ *
+ * A session whose `spendUsd` is absent is counted in `unmeteredSessions` and
+ * contributes nothing to `spendUsd`: the store's contract distinguishes "the
+ * provider reported no cost" from "the provider reported zero", and collapsing
+ * them here would throw away the only place that distinction exists.
+ */
+function summarizeSessions(rows: readonly SessionSpendRow[]): SessionRoleStats[] {
+  return SESSION_SPEND_ROLES.map((role) => {
+    const mine = rows.filter((r) => r.role === role);
+    const metered = mine.filter((r) => r.spendUsd !== undefined);
+    return {
+      role,
+      sessions: mine.length,
+      turns: mine.reduce((sum, r) => sum + r.turns, 0),
+      spendUsd: cents(metered.reduce((sum, r) => sum + (r.spendUsd ?? 0), 0)),
+      unmeteredSessions: mine.length - metered.length,
+    };
+  });
+}
+
 /** `N` and its unit, for a count line that must not print "0" as a measure. */
 function countLine(n: number, noun: string, plural: string): string {
   return `${n} ${n === 1 ? noun : plural}`;
@@ -350,17 +534,88 @@ function renderRepo(repo: RepoStats, indent: string): string {
   return lines.join("\n");
 }
 
+/**
+ * The attribution block (Phase 4): where the money went, as opposed to what it
+ * bought. Rendered from the same report `--json` carries, and rendered even in
+ * the empty case — a dry queue is exactly when daemon-owned grooming runs, so
+ * hiding this behind "nothing settled" would hide the spend that had no
+ * outcome, which is the one an operator most wants to see.
+ */
+function renderAttribution(report: StatsReport, indent: string): string[] {
+  const lines: string[] = [];
+  if (report.models.length > 0) {
+    lines.push(`${indent}per model:`);
+    for (const m of report.models) {
+      // Nothing metered at all is stated as unknown, not as "$0.00 metered":
+      // the dollar figure is true but reads as free, which is the exact
+      // misreading this whole surface exists to prevent.
+      const cost =
+        m.spendUsd === 0 && m.unmeteredRuns === m.runs
+          ? `cost unknown — no run on this model metered`
+          : m.spendPerMerge === null
+            ? `$${m.spendUsd.toFixed(2)} metered (no merge on this model to divide by)`
+            : `$${m.spendUsd.toFixed(2)} metered ($${m.spendPerMerge.toFixed(2)}/merge)`;
+      const unmetered =
+        m.unmeteredRuns === 0 || m.unmeteredRuns === m.runs
+          ? ""
+          : ` · ${countLine(m.unmeteredRuns, "run", "runs")} unmetered`;
+      lines.push(
+        `${indent}  ${m.model}  ${countLine(m.runs, "run", "runs")}, ` +
+          `${countLine(m.merges, "merge", "merges")}  ${cost}${unmetered}`,
+      );
+    }
+  }
+  const ran = report.sessions.filter((s) => s.sessions > 0);
+  // Silence rather than a row of zeros: "no grooming sessions in this window"
+  // and "grooming cost nothing" are different claims, and only the first is true.
+  if (ran.length > 0) {
+    lines.push(`${indent}daemon sessions:`);
+    for (const s of ran) {
+      // Same rule as the per-model line: an unmetered session's cost is
+      // unknown, so it is a count, never a zero folded into the dollar figure.
+      if (s.spendUsd === 0 && s.unmeteredSessions === s.sessions) {
+        lines.push(
+          `${indent}  ${s.role}  ${countLine(s.sessions, "session", "sessions")}, ` +
+            `${countLine(s.turns, "turn", "turns")}  cost unknown — no session metered`,
+        );
+        continue;
+      }
+      const unknown =
+        s.unmeteredSessions === 0
+          ? ""
+          : ` · ${countLine(s.unmeteredSessions, "session", "sessions")} unmetered (cost unknown, not $0.00)`;
+      lines.push(
+        `${indent}  ${s.role}  ${countLine(s.sessions, "session", "sessions")}, ` +
+          `${countLine(s.turns, "turn", "turns")}  $${s.spendUsd.toFixed(2)} metered${unknown}`,
+      );
+    }
+  }
+  if (report.unmeteredRoles.length > 0) {
+    lines.push(
+      `${indent}  ${report.unmeteredRoles.join(", ")}  unmetered — no usage events are observable for ` +
+        `${report.unmeteredRoles.length === 1 ? "this session" : "these sessions"}, so the cost is unknown and no figure above includes it`,
+    );
+  }
+  return lines;
+}
+
 /** Render the human form of the same {@link StatsReport} `--json` prints. */
 export function renderStatsHuman(report: StatsReport): string {
   const w = report.window;
   const header = `${report.project} — outcomes ${w.sinceDay} → ${w.untilDay}`;
   if (report.empty) {
-    return `${header}\n  nothing settled in the window — no runs recorded, so there are no measurements to report yet (a fresh store or an idle fleet).\n`;
+    return [
+      header,
+      "  nothing settled in the window — no runs recorded, so there are no measurements to report yet (a fresh store or an idle fleet).",
+      ...renderAttribution(report, "  "),
+      "",
+    ].join("\n");
   }
   const lines = [header, renderRepo(report.total, "  "), `  gh api     ${report.ghCalls} tracked ${report.ghCalls === 1 ? "call" : "calls"} in the window`];
   if (report.repos.length > 0) {
     lines.push("  per repo:");
     for (const repo of report.repos) lines.push(renderRepo(repo, "    "));
   }
+  lines.push(...renderAttribution(report, "  "));
   return `${lines.join("\n")}\n`;
 }