estela 0.3.4 → 0.4.0

package/README.md

@@ -241,6 +241,103 @@ estela ai-cost
 Cache is counted separately because it's usually most of the bill — ignoring it
 underestimated spend fivefold.
 
+### What that spend delivered
+
+`--by` breaks the cost down by delivery: by branch, or by ticket and PR.
+
+```sh
+estela ai-cost --by branch --month 2026-10            # by branch
+estela ai-cost --by item --client acme --json         # by ticket or PR, for one client
+estela ai-cost --by branch --from 2026-10-01 --csv cost.csv
+```
+
+Each row has its hours and two figures: the cost at API prices, which measures
+usage, and your subscription split by usage, which is the money paid. It also
+says what the attribution is based on: the branch the agent recorded, the number
+in the branch (`feat/12-login`), a `#12` in a commit, set by hand with `estela
+entry link`, or the PR's merge commit ("Merge pull request #31 from …"). Anything
+without a basis goes whole to "Unattributed": nothing is spread by guesswork.
+
+A PR merged with squash leaves no merge in git, so its branch isn't linked to the
+PR. Copilot doesn't store tokens, so its hours count but its cost is unknown
+(marked with `*`). The report only reads what's recorded: it never recalculates
+approved or invoiced days.
+
+### Planned versus delivered
+
+```sh
+estela project tracker --project shop --system github --plan-label planned
+estela delivery --project shop --month 2026-10
+estela delivery --project shop --milestone "Sprint 4" --json
+```
+
+Three blocks, each with its hours and AI cost: what was planned and delivered in
+the period (an issue closed as completed, or closed by a merged PR), what was
+planned and not delivered, and what was delivered without being planned. Planned
+means it carries a GitHub label or milestone. Each line's cost is that of the
+hours linked to it: the PR's branch (squash merges included) and its number in
+branches, commits or set by hand.
+
+It reads GitHub with `gh`, the official CLI, if it's installed and logged in.
+That's the only call off your machine, only for projects with `--system github`,
+and `--offline` avoids it. What it reads is saved, so the report works offline and
+`--undelivered` knows which branches were squash-merged. Without `gh` the command
+says so and shows what git says was delivered.
+
+### What each client asked for
+
+```sh
+estela delivery --project shop --by client --month 2026-10
+estela client alias --client acme --label "acme-retail"
+```
+
+An issue or PR labelled `cliente:<name>` is that client's request, and a PR
+inherits the labels of the issues it closes. The report gives the period's AI
+spend on each client's requests, against the rest. An hour that served requests
+from two clients goes to "Several", unsplit. The label's name is matched against
+your clients' ids and names; if nothing matches, it shows as "unmapped" until you
+give it an alias. Change the prefix with `estela project tracker --client-label`.
+
+Estela knows nothing about revenue or contracts, and doesn't estimate them: it
+only links spend to who asked for the work.
+
+### The report for finance
+
+```sh
+estela summary                                     # the last closed month, in Markdown
+estela summary --month 2026-10 --out october.csv   # as CSV, for a spreadsheet
+estela summary --client acme --format json
+```
+
+For someone who doesn't code: what was paid for AI, by client and project, what
+was delivered (and the plan, if `estela delivery` read it), what each client asked
+for, and what never got delivered. The headlines talk about money and deliveries;
+tokens, sessions and list prices go at the end, under how it's calculated. A closed
+month adds up to exactly that month's fee, and the clients plus what falls outside
+projects make up the total. It never calls anything off your machine.
+
+### The spend that never got delivered
+
+```sh
+estela ai-cost --undelivered                    # all history, branches idle 14 days
+estela ai-cost --undelivered --month 2026-10 --stale-days 30 --json
+```
+
+Per project, as a figure and as a percentage of spend, two blocks that never
+overlap:
+
+- **Sessions without a commit:** a stretch of one chat with no commit of yours in
+  that repo during it or in the half hour after. The ones that did get a commit on
+  their branch later are shown apart: iterating before you're happy is work too.
+- **Unmerged branches:** they exist, aren't integrated, and have been idle for N
+  days. Only their cost that isn't already in a session without a commit.
+
+It's a signal to review, not a verdict. What can't be known isn't counted and is
+shown apart: a branch deleted with no recorded merge may have been squash-merged,
+and before your first recognised commit in a repo you may have been committing
+with another email (check it with `estela author`). A squash also makes a branch
+that still exists look unmerged.
+
 ## Which project is eating your quota
 
 On Claude Max/Pro or Codex with a subscription, the quota runs out before you

package/dist/billing/assign.d.ts

@@ -73,5 +73,15 @@ export declare function commitOnlyBlocks(db: DatabaseSync, commits: readonly Com
  * nueva puede devolverlo a su carpeta real.
  */
 export declare function knownTurns(db: DatabaseSync, scanned: readonly AgentTurn[]): AgentTurn[];
-export declare function planEntries(db: DatabaseSync, raw: readonly WorkBlock[]): AssignmentPlan;
+/**
+ * Vuelve a juntar los bloques que `sessionize` partió por un cambio de rama, si
+ * caen en un día ya cerrado de su proyecto: aprobado, facturado o ajustado.
+ *
+ * Partir reparte el mismo rato entre las ramas en que de verdad se trabajó, y
+ * el total no cambia. Pero un día cerrado ya tiene su cifra en la rama en que
+ * quedó (la última del bloque), y una imputación nueva al lado la contaría dos
+ * veces. Así que ahí todo sigue como estaba.
+ */
+export declare function rejoinLockedDays(db: DatabaseSync, blocks: readonly WorkBlock[], projectOf: (repo: string | null) => string | null): WorkBlock[];
+export declare function planEntries(db: DatabaseSync, input: readonly WorkBlock[]): AssignmentPlan;
 //# sourceMappingURL=assign.d.ts.map

package/dist/billing/assign.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.entryId = entryId;
 exports.commitOnlyBlocks = commitOnlyBlocks;
 exports.knownTurns = knownTurns;
+exports.rejoinLockedDays = rejoinLockedDays;
 exports.planEntries = planEntries;
 const shared_1 = require("@estela/shared");
 const store = __importStar(require("../db/store.js"));
@@ -140,6 +141,62 @@ function findDuplicates(db, raw, planned, projectOf) {
     }
     return { stale, protectedDuplicates };
 }
+/**
+ * Vuelve a juntar los bloques que `sessionize` partió por un cambio de rama, si
+ * caen en un día ya cerrado de su proyecto: aprobado, facturado o ajustado.
+ *
+ * Partir reparte el mismo rato entre las ramas en que de verdad se trabajó, y
+ * el total no cambia. Pero un día cerrado ya tiene su cifra en la rama en que
+ * quedó (la última del bloque), y una imputación nueva al lado la contaría dos
+ * veces. Así que ahí todo sigue como estaba.
+ */
+function rejoinLockedDays(db, blocks, projectOf) {
+    if (!blocks.some((b) => b.continuesPrevious))
+        return [...blocks];
+    const closed = db.prepare(`
+    SELECT 1 FROM time_entries WHERE project_id = ? AND local_date = ?
+      AND (approved = 1 OR invoice_id IS NOT NULL OR adjust_reason IS NOT NULL) LIMIT 1`);
+    const isClosed = (b) => {
+        const p = projectOf(b.repoPath);
+        return p !== null && closed.get(p, (0, shared_1.localDate)(b.startedAt)) !== undefined;
+    };
+    // Cadenas: un bloque que continúa al anterior del mismo repo va con él.
+    const chains = [];
+    const lastChain = new Map();
+    for (const b of [...blocks].sort((x, y) => x.startedAt.getTime() - y.startedAt.getTime())) {
+        const key = b.repoPath ?? "";
+        const previous = lastChain.get(key);
+        const tail = previous?.[previous.length - 1];
+        if (b.continuesPrevious && previous && tail && tail.endedAt.getTime() === b.startedAt.getTime()) {
+            previous.push(b);
+            continue;
+        }
+        const chain = [b];
+        chains.push(chain);
+        lastChain.set(key, chain);
+    }
+    return chains.flatMap((chain) => chain.length > 1 && chain.some(isClosed) ? [joinChain(chain)] : chain);
+}
+function joinChain(chain) {
+    const first = chain[0];
+    const last = chain[chain.length - 1];
+    const union = (pick) => [...new Set(chain.flatMap((b) => pick(b) ?? []))];
+    return {
+        startedAt: first.startedAt,
+        endedAt: last.endedAt,
+        seconds: Math.round((last.endedAt.getTime() - first.startedAt.getTime()) / 1000),
+        repoPath: first.repoPath,
+        // La de antes de partir: la última del bloque.
+        branch: last.branch ?? first.branch,
+        turnCount: chain.reduce((n, b) => n + b.turnCount, 0),
+        aiCost: { microUsd: chain.reduce((n, b) => n + b.aiCost.microUsd, 0) },
+        models: union((b) => b.models).sort(),
+        sessionIds: union((b) => b.sessionIds),
+        commits: chain.flatMap((b) => b.commits),
+        unpricedModels: union((b) => b.unpricedModels).sort(),
+        agents: union((b) => b.agents).sort(),
+    };
+}
 /** Cuánto de [from, to] cae dentro de los bloques, sin contar dos veces un solape. */
 function coveredMs(blocks, from, to) {
     const intervals = blocks
@@ -155,7 +212,7 @@ function coveredMs(blocks, from, to) {
     }
     return ms;
 }
-function planEntries(db, raw) {
+function planEntries(db, input) {
     const ownerOf = (0, project_of_js_1.ownerResolver)(db);
     const direct = (repo) => (repo ? store.projectForRepo(db, repo) : null);
     const viaRoot = (repo) => {
@@ -164,6 +221,7 @@ function planEntries(db, raw) {
         const o = ownerOf(repo);
         return o.kind === "project" ? o.projectId : null;
     };
+    const raw = rejoinLockedDays(db, input, (repo) => direct(repo) ?? viaRoot(repo));
     // La carpeta tal cual. Se agrupa por PROYECTO, no por ruta: `repo/` y
     // `repo/src/UI` son el mismo proyecto, y agrupar por ruta daba dos bloques que
     // luego se pisaban al guardarse con el mismo id.

package/dist/billing/sessionize.d.ts

@@ -41,6 +41,12 @@ export interface WorkBlock {
      * bloque construido a mano; los de `sessionize` siempre lo traen.
      */
     readonly agents?: readonly AgentKind[];
+    /**
+     * Empieza donde acaba el bloque anterior del mismo repo, porque la sesión
+     * cambió de rama sin pausa. En un día aprobado o facturado se vuelven a
+     * juntar (ver `rejoinLockedDays`), para no cambiar lo ya cerrado.
+     */
+    readonly continuesPrevious?: boolean;
 }
 export declare function sessionize(turns: readonly AgentTurn[], options?: SessionizeOptions): WorkBlock[];
 /**

package/dist/billing/sessionize.js

@@ -30,26 +30,44 @@ function sessionize(turns, options = {}) {
     for (const bucket of byRepo.values()) {
         bucket.sort((a, b) => a.at.getTime() - b.at.getTime());
         let current = [];
-        const flush = () => {
+        let branch = null;
+        let continued = false;
+        const flush = (until) => {
             if (current.length)
-                blocks.push(buildBlock(current, tailMs));
+                blocks.push(buildBlock(current, tailMs, until, continued));
             current = [];
+            branch = null;
         };
         for (const turn of bucket) {
             const previous = current[current.length - 1];
-            if (previous && turn.at.getTime() - previous.at.getTime() > gapMs)
+            if (previous && turn.at.getTime() - previous.at.getTime() > gapMs) {
                 flush();
+                continued = false;
+            }
+            else if (previous && namedBranch(turn.branch) && branch && namedBranch(turn.branch) !== branch) {
+                // Cambio de rama sin pausa: el bloque se parte en el turno exacto del
+                // cambio, sin cola, para que la suma sea el mismo rato de reloj. Antes
+                // todo el bloque se iba a la última rama, con su coste.
+                flush(turn.at);
+                continued = true;
+            }
             current.push(turn);
+            branch ??= namedBranch(turn.branch);
         }
         flush();
+        continued = false;
     }
     return blocks.sort((a, b) => a.startedAt.getTime() - b.startedAt.getTime());
 }
-function buildBlock(turns, tailMs) {
+/** "HEAD" es un checkout sin rama (HEAD desprendido): no es un cambio de rama. */
+function namedBranch(branch) {
+    return branch && branch !== "HEAD" ? branch : null;
+}
+function buildBlock(turns, tailMs, until, continued = false) {
     const first = turns[0];
     const last = turns[turns.length - 1];
     const startedAt = first.at;
-    const endedAt = new Date(last.at.getTime() + tailMs);
+    const endedAt = until ?? new Date(last.at.getTime() + tailMs);
     let microUsd = 0;
     const models = new Set();
     const unpriced = new Set();
@@ -78,6 +96,7 @@ function buildBlock(turns, tailMs) {
         commits: [],
         unpricedModels: [...unpriced].sort(),
         agents: [...agents].sort(),
+        ...(continued ? { continuesPrevious: true } : {}),
     };
 }
 /**