fix(handlers): address maintainer feedback on lines_of_code semantics

- activity.ts: guard sessionDiffTotals writes so setBoundedMap only fires on
  insert; updates to an existing key now use plain .set(). Prevents evicting an
  unrelated active session when the map is at MAX_PENDING, which would cause
  that session's next session.diff to be treated as first-seen and re-emit its
  full cumulative diff as a delta — reintroducing the double-count bug for the
  evicted session.
- docs: stop calling the counter "net". It is gross positive churn — negative
  deltas (additions/deletions shrinking, e.g. cumulative +10/-0 -> +5/-5) are
  dropped, so sums do not reconcile to net after any revert, full or partial.
  lines_of_code.total gauge is the authoritative live cumulative. Counter
  description, gauge description, handler docstring, and README all updated.
- tests: add regression for the partial-revert case (+10/-0 -> +5/-5) that
  exercises the semantics gap the maintainer flagged — asserts counter emits
  gross (added=10, removed=5) and gauge tracks live cumulative (added=[10,5],
  removed=[0,5]).

Author: Jeevan1351

README.md

@@ -31,8 +31,8 @@ An [opencode](https://opencode.ai) plugin that exports telemetry via OpenTelemet
 | `opencode.session.count` | Counter | Incremented on each `session.created` event |
 | `opencode.token.usage` | Counter | Per token type: `input`, `output`, `reasoning`, `cacheRead`, `cacheCreation` |
 | `opencode.cost.usage` | Counter | USD cost per completed assistant message |
-| `opencode.lines_of_code.count` | Counter | Emits only the positive delta since the previous `session.diff`, so summing the counter avoids the old double-counting. **Caveats:** when opencode reports a cumulative drop (a revert), the negative delta is skipped — so summing the counter reflects gross additions across non-revert deltas and can overstate net after a revert. Rewrites that happen and are reverted *within a single message* aren't captured at all (opencode publishes the per-message cumulative, not intra-message churn). Use `opencode.lines_of_code.total` for the authoritative live total. |
-| `opencode.lines_of_code.total` | Gauge | Current cumulative lines added/removed for the session, refreshed on every `session.diff`. Drops back to `0` if opencode reports a revert to baseline. Authoritative for "what does this session currently amount to". |
+| `opencode.lines_of_code.count` | Counter | **Gross positive churn, not a net total.** Emits the positive delta of `additions`/`deletions` since the previous `session.diff` for the same session; negative deltas (when opencode's cumulative `additions` or `deletions` shrinks vs. the last event) are dropped. Summing the counter therefore reports gross lines added/removed across forward transitions — it does *not* reconcile back to the session's current state after any revert (full or partial). Intra-message rewrites that opencode collapses in its per-message cumulative are not visible here at all. Use `opencode.lines_of_code.total` for the authoritative live cumulative. |
+| `opencode.lines_of_code.total` | Gauge | **Authoritative live cumulative lines added/removed for the session.** Refreshed on every `session.diff` with opencode's current cumulative value. Drops back to `0` if opencode reports a revert to baseline, and tracks partial reverts faithfully. Query this (not the counter) to answer "what does this session currently amount to". |
 | `opencode.commit.count` | Counter | Git commits detected via bash tool |
 | `opencode.tool.duration` | Histogram | Tool execution time in milliseconds |
 | `opencode.cache.count` | Counter | Cache activity per message: `type=cacheRead` or `type=cacheCreation` |

src/handlers/activity.ts

@@ -6,10 +6,12 @@ import type { HandlerContext } from "../types.ts"
 /**
  * Records lines-added/removed for a `session.diff` event. opencode publishes each event
  * with the cumulative session diff (first snapshot → latest), so we emit two instruments:
- * `opencode.lines_of_code.count` (Counter) receives only the positive delta since the
- * previous event for this session, so summing across a session yields the net total without
- * double counting. `opencode.lines_of_code.total` (Gauge) records the current cumulative
- * total, overwritten on every event.
+ * `opencode.lines_of_code.count` (Counter) receives only the *positive* per-event delta
+ * for each dimension (additions, deletions). Negative deltas — opencode reporting a smaller
+ * cumulative for a dimension than the previous event — are dropped, so the counter reports
+ * gross positive churn and does not reconcile to net after any revert (full or partial).
+ * `opencode.lines_of_code.total` (Gauge) mirrors opencode's current cumulative value on
+ * every event and is the authoritative live view.
  */
 export function handleSessionDiff(e: EventSessionDiff, ctx: HandlerContext) {
   const sessionID = e.properties.sessionID
@@ -25,7 +27,15 @@ export function handleSessionDiff(e: EventSessionDiff, ctx: HandlerContext) {
   const prev = ctx.sessionDiffTotals.get(sessionID) ?? { additions: 0, deletions: 0 }
   const deltaAdded = totalAdded - prev.additions
   const deltaRemoved = totalRemoved - prev.deletions
-  setBoundedMap(ctx.sessionDiffTotals, sessionID, { additions: totalAdded, deletions: totalRemoved })
+  const nextTotals = { additions: totalAdded, deletions: totalRemoved }
+  if (ctx.sessionDiffTotals.has(sessionID)) {
+    // Existing session: update in place. Calling setBoundedMap on a full map would
+    // evict an unrelated session here, and that session's next session.diff would
+    // be treated as first-seen — reintroducing the cumulative double-count bug.
+    ctx.sessionDiffTotals.set(sessionID, nextTotals)
+  } else {
+    setBoundedMap(ctx.sessionDiffTotals, sessionID, nextTotals)
+  }
 
   const baseAttrs = { ...ctx.commonAttrs, "session.id": sessionID }
 

src/otel.ts

@@ -147,11 +147,11 @@ export function createInstruments(prefix: string): Instruments {
     }),
     linesCounter: meter.createCounter(`${prefix}lines_of_code.count`, {
       unit: "{line}",
-      description: "Positive per-event delta of lines added/removed; sum reflects gross additions across non-revert deltas and may overstate net after a revert. Use lines_of_code.total for the authoritative live cumulative value.",
+      description: "Gross positive churn of lines added/removed across a session. Emits the positive delta vs. the previous session.diff; negative deltas (cumulative shrinkage) are dropped, so sums do not reconcile to net after any revert. Use lines_of_code.total for the authoritative live cumulative.",
     }),
     linesTotalGauge: meter.createGauge(`${prefix}lines_of_code.total`, {
       unit: "{line}",
-      description: "Authoritative live cumulative lines added/removed for the current session, refreshed on every session.diff; drops back to 0 if opencode reports a revert to baseline.",
+      description: "Authoritative live cumulative lines added/removed for the current session. Mirrors opencode's session.diff cumulative value on every event; tracks partial and full reverts faithfully.",
     }),
     commitCounter: meter.createCounter(`${prefix}commit.count`, {
       unit: "{commit}",

tests/handlers/activity.test.ts

@@ -91,6 +91,27 @@ describe("handleSessionDiff", () => {
     expect(added).toEqual([5])
   })
 
+  test("linesCounter is gross-only across a partial revert (additions shrink, deletions grow)", () => {
+    // Cumulative goes {additions:10, deletions:0} -> {additions:5, deletions:5}.
+    // Delta is {added:-5, removed:+5}. Negative added is skipped; positive removed
+    // is emitted. Counter ends at added=10, removed=5 while the authoritative live
+    // cumulative is added=5, removed=5 — the counter is GROSS, not net. Live
+    // cumulative state is surfaced via linesTotalGauge (see next test).
+    const { ctx, counters, gauges } = makeCtx()
+    handleSessionDiff(makeSessionDiff("ses_1", [{ file: "a.ts", additions: 10, deletions: 0 }]), ctx)
+    handleSessionDiff(makeSessionDiff("ses_1", [{ file: "a.ts", additions: 5, deletions: 5 }]), ctx)
+
+    const added = counters.lines.calls.filter((c) => c.attrs["type"] === "added").map((c) => c.value)
+    const removed = counters.lines.calls.filter((c) => c.attrs["type"] === "removed").map((c) => c.value)
+    expect(added).toEqual([10])
+    expect(removed).toEqual([5])
+
+    const gaugeAdded = gauges.linesTotal.calls.filter((c) => c.attrs["type"] === "added").map((c) => c.value)
+    const gaugeRemoved = gauges.linesTotal.calls.filter((c) => c.attrs["type"] === "removed").map((c) => c.value)
+    expect(gaugeAdded).toEqual([10, 5])
+    expect(gaugeRemoved).toEqual([0, 5])
+  })
+
   test("linesTotalGauge records cumulative totals, including zero after revert", () => {
     const { ctx, gauges } = makeCtx()
     handleSessionDiff(makeSessionDiff("ses_1", [{ file: "a.ts", additions: 5, deletions: 2 }]), ctx)