Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(savings): recover the savings agents were shown but nobody banked (#2440)

Raghav Chamadiya6ebeb0af128a
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/command.py b/packages/cli/src/repowise/cli/commands/init_cmd/command.py
index f4200e244..711ac187a 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/command.py
@@ -104,6 +104,30 @@ from .reporting import show_analysis_summary, show_completion
from .workspace import _workspace_init
+def _catch_up_savings(repo_path: Path) -> None:
+ """Bank the savings this repository's agents were shown before indexing.
+
+ Keyless, time-budgeted and best-effort, following the session-decision
+ stage that runs here for the same reason: the history is already on disk,
+ and a first index that ignores it shows an empty savings page for a
+ repository that has been saving tokens for months.
+
+ Not in ``repowise update``: update runs on every commit, and this reads a
+ corpus bounded by how much the user has worked rather than by the repo.
+ """
+ try:
+ from repowise.core.savings.transcript import sync_transcript_savings
+
+ outcome = sync_transcript_savings(repo_path)
+ except Exception:
+ return
+ if outcome.recorded:
+ console.print(
+ f" [{OK}]✓[/] Recovered {outcome.saved_input_tokens:,} saved tokens "
+ f"from agent history"
+ )
+
+
def _record_init_outcome(
*,
result: Any,
@@ -1684,6 +1708,8 @@ def init_command(
phase_timings: dict[str, float] = callback.timings
console.print(f" [{OK}]✓[/] Database updated")
+ _catch_up_savings(repo_path)
+
# Persist the onboarding choice so subsequent `repowise update` runs
# honor it without re-passing the flag. Default True is omitted to keep
# config files tidy — only the override is recorded.
diff --git a/packages/cli/src/repowise/cli/commands/savings_cmd.py b/packages/cli/src/repowise/cli/commands/savings_cmd.py
new file mode 100644
index 000000000..40b7fb2bf
--- /dev/null
+++ b/packages/cli/src/repowise/cli/commands/savings_cmd.py
@@ -0,0 +1,91 @@
+"""``repowise savings sync`` — record savings the ledger never saw.
+
+The ledger only ever held what happened while it was running, so a repository
+indexed today shows an empty savings page despite months of agent history on
+disk. The core transcript surface reads that history back; this exposes it.
+
+Deliberately not wired into ``repowise update``: update runs on every commit
+and this reads a corpus bounded by how much the user has worked rather than by
+the repository. ``init`` runs it once, and this command re-runs it on demand.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from repowise.cli.helpers import console
+from repowise.cli.output import emit_json, format_option
+
+
+def savings_group() -> None:
+ """Work with this repository's agent savings ledger."""
+
+
+@savings_group.command("sync")
[email protected]("path", required=False, default=None)
+ "--dry-run",
+ is_flag=True,
+ help="Report what would be recorded without writing anything.",
+)
+ "--budget",
+ type=float,
+ default=None,
+ metavar="SECONDS",
+ help="Seconds of transcript reading. Raise it to finish a large backlog sooner.",
+)
+@format_option()
+def sync_command(path: str | None, dry_run: bool, budget: float | None, fmt: str) -> None:
+ """Record savings your agents were shown but the ledger never banked.
+
+ Reads only what has been appended since the last run, so repeating it is
+ cheap. A non-zero ``deferred`` means the time budget ran out and there is
+ more to read; run it again.
+ """
+ from repowise.core.savings.transcript import SYNC_BUDGET_S, sync_transcript_savings
+
+ repo_root = Path(path).resolve() if path else Path.cwd().resolve()
+ result = sync_transcript_savings(
+ repo_root,
+ budget=SYNC_BUDGET_S if budget is None else budget,
+ dry_run=dry_run,
+ )
+
+ if fmt == "json":
+ emit_json(
+ {
+ "repository": str(repo_root),
+ "dry_run": dry_run,
+ "recorded": result.recorded,
+ "saved_input_tokens": result.saved_input_tokens,
+ "already_recorded": result.already_recorded,
+ "transcripts_read": result.transcripts_read,
+ "deferred": result.deferred,
+ "per_agent": result.per_harness,
+ }
+ )
+ return
+
+ verb = "Would record" if dry_run else "Recorded"
+ console.print(
+ f"{verb} [bold]{result.recorded}[/bold] savings events "
+ f"([bold]{result.saved_input_tokens:,}[/bold] input tokens) "
+ f"from {result.transcripts_read} transcripts."
+ )
+ if result.already_recorded:
+ console.print(
+ f" {result.already_recorded} already in the ledger and left alone.",
+ style="dim",
+ )
+ for agent, tokens in sorted(result.per_harness.items(), key=lambda kv: -kv[1]):
+ console.print(f" {agent}: {tokens:,} tokens", style="dim")
+ if result.deferred:
+ console.print(
+ f" {result.deferred} transcripts not reached within the time budget. "
+ f"Run this again to continue.",
+ style="yellow",
+ )
diff --git a/packages/cli/src/repowise/cli/main.py b/packages/cli/src/repowise/cli/main.py
index 533c0b777..ff516026f 100644
--- a/packages/cli/src/repowise/cli/main.py
+++ b/packages/cli/src/repowise/cli/main.py
@@ -80,6 +80,7 @@ _OSS_COMMANDS: tuple[tuple[str, str], ...] = (
("distill", "distill_cmd:distill_command"),
("expand", "expand_cmd:expand_command"),
("saved", "saved_cmd:saved_command"),
+ ("savings", "savings_cmd:savings_group"),
("security", "security_cmd:security_command"),
("corrections", "corrections_cmd:corrections_command"),
("export", "export_cmd:export_command"),
diff --git a/packages/core/src/repowise/core/distill/markers.py b/packages/core/src/repowise/core/distill/markers.py
index efcf19d70..dedb8a0a6 100644
--- a/packages/core/src/repowise/core/distill/markers.py
+++ b/packages/core/src/repowise/core/distill/markers.py
@@ -10,6 +10,7 @@ that crashes the terminal would violate the never-make-things-worse rule.
from __future__ import annotations
import re
+from dataclasses import dataclass
REF_LENGTH = 12
@@ -17,10 +18,30 @@ _MARKER_TEMPLATE = (
"[repowise#{ref}: {lines} lines omitted (~{tokens} tokens); restore: repowise expand {ref}]"
)
-MARKER_RE = re.compile(r"\[repowise#(?P<ref>[0-9a-f]{12}):[^\]]*\]")
+#: Matches any marker and recovers its ref; the counts are optional groups so
+#: one pattern serves callers that want only the ref and callers that want both.
+MARKER_RE = re.compile(
+ r"\[repowise#(?P<ref>[0-9a-f]{12}):"
+ r"(?:\s*(?P<lines>\d+) lines omitted \(~(?P<tokens>\d+) tokens\))?"
+ r"[^\]]*\]"
+)
OMISSION_ID_RE = re.compile(r"^repowise#(?P<ref>[0-9a-f]{12})$")
+@dataclass(frozen=True, slots=True)
+class ParsedMarker:
+ """One complete marker read back out of delivered text.
+
+ ``text`` is the marker verbatim, so a reader reconstructing what an output
+ cost before distillation can subtract the marker's own size.
+ """
+
+ ref: str
+ text: str
+ lines_omitted: int
+ tokens_omitted: int
+
+
def render_marker(ref: str, lines_omitted: int, tokens_omitted: int) -> str:
"""Render the omission marker for *ref*."""
if not is_valid_ref(ref):
@@ -42,6 +63,32 @@ def parse_marker_refs(text: str) -> list[str]:
return refs
+def parse_markers(text: str) -> list[ParsedMarker]:
+ """Return every *complete* marker in *text*, in order, one per ref.
+
+ Unlike :func:`parse_marker_refs` this requires both counts, which is also
+ what keeps the documented example marker out: it prints a rounded
+ ``~6.1k`` and is quoted into transcripts often enough to matter.
+ """
+ seen: set[str] = set()
+ markers: list[ParsedMarker] = []
+ for match in MARKER_RE.finditer(text):
+ ref = match.group("ref")
+ tokens = match.group("tokens")
+ if tokens is None or ref in seen:
+ continue
+ seen.add(ref)
+ markers.append(
+ ParsedMarker(
+ ref=ref,
+ text=match.group(0),
+ lines_omitted=int(match.group("lines")),
+ tokens_omitted=int(tokens),
+ )
+ )
+ return markers
+
+
def is_valid_ref(ref: str) -> bool:
"""True when *ref* looks like a store key (12 lowercase hex chars)."""
return bool(re.fullmatch(r"[0-9a-f]{12}", ref))
diff --git a/packages/core/src/repowise/core/distill/missed.py b/packages/core/src/repowise/core/distill/missed.py
index 1cda40781..f81887f14 100644
--- a/packages/core/src/repowise/core/distill/missed.py
+++ b/packages/core/src/repowise/core/distill/missed.py
@@ -63,8 +63,6 @@ RATIO_FLOOR: dict[str, float] = {
#: estimated savings fall under it would not have produced a marker anyway.
_MIN_EST_TOKENS = 40
-_SHELL_TOOLS = ("Bash", "PowerShell")
-
def empty_report(days: float = DEFAULT_WINDOW_DAYS) -> dict[str, Any]:
return {
@@ -140,13 +138,17 @@ def _scan_file(
prefilter = adapter.prefilter(INTENT_SHELL_CALLS)
for event in adapter.iter_events(path, prefilter=prefilter):
if event.kind == "assistant" and event.tool_uses:
- _collect_tool_use(event, cutoff, repo_prefix, pending)
+ _collect_tool_use(event, cutoff, repo_prefix, pending, adapter.shell_tool_names)
elif pending and event.tool_results:
_collect_result(event, pending, per_filter)
def _collect_tool_use(
- event: Event, cutoff: float, repo_prefix: str, pending: dict[str, str]
+ event: Event,
+ cutoff: float,
+ repo_prefix: str,
+ pending: dict[str, str],
+ shell_tools: frozenset[str],
) -> None:
if event.ts is not None and event.ts < cutoff:
return
@@ -154,7 +156,7 @@ def _collect_tool_use(
if not cwd.startswith(repo_prefix):
return
for use in event.tool_uses:
- if use.name not in _SHELL_TOOLS:
+ if use.name not in shell_tools:
continue
command = str(use.input.get("command") or "")
if not command or normalize_command(command).startswith("repowise"):
diff --git a/packages/core/src/repowise/core/distill/store.py b/packages/core/src/repowise/core/distill/store.py
index f221f5e98..973f5a704 100644
--- a/packages/core/src/repowise/core/distill/store.py
+++ b/packages/core/src/repowise/core/distill/store.py
@@ -15,6 +15,7 @@ import hashlib
import sqlite3
import time
import zlib
+from collections.abc import Sequence
from pathlib import Path
import structlog
@@ -57,6 +58,31 @@ def default_store_path(start: Path | None = None) -> Path:
return home / ".repowise" / OMISSIONS_DIRNAME / OMISSIONS_DB_FILENAME
+#: Kept under SQLite's 999-variable ceiling with room to spare.
+_REF_QUERY_BATCH = 400
+
+
+def omission_sources(conn: sqlite3.Connection, refs: Sequence[str]) -> dict[str, str]:
+ """``ref -> source`` for the refs *conn* still holds, batched.
+
+ ``source`` reads ``"<origin>:<filter>"`` -- ``cli:git_diff``,
+ ``hook-codex:test_output`` -- and is the only record of which filter
+ produced a ref. Rows are TTL-pruned, so a ref may legitimately be absent.
+ """
+ found: dict[str, str] = {}
+ for start in range(0, len(refs), _REF_QUERY_BATCH):
+ batch = refs[start : start + _REF_QUERY_BATCH]
+ placeholders = ",".join("?" for _ in batch)
+ found.update(
+ (ref, str(source))
+ for ref, source in conn.execute(
+ f"SELECT ref, source FROM omissions WHERE ref IN ({placeholders})",
+ list(batch),
+ )
+ )
+ return found
+
+
def content_ref(content: str) -> str:
"""Stable 12-hex ref for *content* (truncated SHA-256)."""
return hashlib.sha256(content.encode("utf-8")).hexdigest()[:REF_LENGTH]
@@ -243,6 +269,10 @@ class OmissionStore:
"""Grouped ledger totals (see :func:`tracking.savings_rollup`)."""
return tracking.savings_rollup(self._conn, by=by, since=since)
+ def omission_sources(self, refs: Sequence[str]) -> dict[str, str]:
+ """``ref -> source`` for the refs still held. Pruned refs are absent."""
+ return omission_sources(self._conn, refs)
+
def savings(self) -> SavingsRepository:
"""The canonical event ledger, sharing this store's connection.
diff --git a/packages/core/src/repowise/core/savings/repository.py b/packages/core/src/repowise/core/savings/repository.py
index 8c8833e96..1b93bc3d7 100644
--- a/packages/core/src/repowise/core/savings/repository.py
+++ b/packages/core/src/repowise/core/savings/repository.py
@@ -3,6 +3,7 @@
from __future__ import annotations
import sqlite3
+from collections.abc import Sequence
from datetime import datetime, timedelta
from typing import Any
@@ -18,6 +19,9 @@ from repowise.core.savings.reporting import (
breakdown_rows,
)
+#: Kept under SQLite's 999-variable ceiling with room to spare.
+_REF_QUERY_BATCH = 400
+
_EVENT_COLUMNS = (
"event_id",
"schema_version",
@@ -85,6 +89,28 @@ class SavingsRepository:
[*params, limit],
).fetchall()
+ def recorded_omission_refs(self, refs: Sequence[str]) -> set[str]:
+ """Which of *refs* an event already claims, via ``idx_..._omissions_ref``.
+
+ The idempotency key cannot answer this for a producer reading a
+ transcript: a live event's key is seeded on a random id, so it carries
+ no content identity. The omission ref does, and it is the same 12 hex
+ characters in the ledger and in the marker the agent was shown.
+ """
+ found: set[str] = set()
+ for start in range(0, len(refs), _REF_QUERY_BATCH):
+ batch = refs[start : start + _REF_QUERY_BATCH]
+ placeholders = ",".join("?" for _ in batch)
+ found.update(
+ row[0]
+ for row in self._conn.execute(
+ "SELECT DISTINCT omission_ref FROM savings_event_omissions "
+ f"WHERE omission_ref IN ({placeholders})",
+ list(batch),
+ )
+ )
+ return found
+
def record_event(self, event: SavingsEvent) -> bool:
"""Atomically insert an event and its links; return false for a retry."""
values = [getattr(event, column) for column in _EVENT_COLUMNS[:-1]]
diff --git a/packages/core/src/repowise/core/savings/transcript.py b/packages/core/src/repowise/core/savings/transcript.py
new file mode 100644
index 000000000..e555e967f
--- /dev/null
+++ b/packages/core/src/repowise/core/savings/transcript.py
@@ -0,0 +1,453 @@
+"""Savings an agent was shown but the ledger never recorded.
+
+Repowise writes its own before and after into the text the agent receives: a
+distilled command output ends in an omission marker carrying the token count
+that was dropped. So the delivered text is measurable, the omitted count is
+readable, and their sum is what the output cost before distillation. That is a
+*measured* saving recovered from the transcript, not an estimate of one.
+
+This exists because the ledger only ever recorded what happened while it was
+running. A repository indexed today has months of agent history on disk and an
+empty savings page; a machine that upgraded Repowise has events only from its
+next call onward. Both are catch-up, which is why this is a cursored surface
+rather than a migration: it runs at ``init``, again on demand, and reads only
+what has been appended since it last looked.
+
+Three rules it does not get to relax:
+
+- **Shell results only.** A marker in prose, a pull-request body or a test
+ fixture is not a saving. A marker in an MCP response is one the MCP surface
+ accounts for itself, and re-deriving it from a post-budget transcript reads
+ fields the budgeter sheds first.
+- **One event per omission ref.** The ref is content-addressed, so the same
+ ref twice is the same distilled output. Counting it once undersells a
+ genuine repeat, which is the floor this ledger is meant to be.
+- **Never repriced.** These happened at rates nobody recorded, so they are
+ counted in tokens and left unvalued rather than valued at today's rate.
+"""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+import time
+from collections.abc import Iterable, Sequence
+from contextlib import closing
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from repowise.core.distill.budget import estimate_tokens
+from repowise.core.distill.engine import HOST_OUTPUT_CAP_CHARS
+from repowise.core.distill.markers import ParsedMarker, parse_markers
+from repowise.core.distill.store import OmissionStore, omission_sources
+from repowise.core.savings.correlation import new_event_id, scoped_idempotency_key
+from repowise.core.sessions import (
+ INTENT_TOOL_CALLS,
+ Event,
+ ToolResult,
+ get_adapter,
+ registered_adapters,
+)
+from repowise.core.sessions.adapters.base import HarnessAdapter, RawPrefilter
+from repowise.core.sessions.cursor import CursorStore, iter_new_events
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["ESTIMATOR", "SYNC_BUDGET_S", "TranscriptSyncResult", "sync_transcript_savings"]
+
+#: Names this population in ``savings_events.estimator``. Live distill writes
+#: ``chars_per_token_floor_v1``, so a report can always separate the two --
+#: which matters because only two of the six agents keep transcripts, and a
+#: backfilled window's per-agent split is therefore skewed by method.
+ESTIMATOR = "transcript_marker_v1"
+
+#: Seconds of transcript reading per run, split across harnesses. Stopping
+#: between files is safe: cursors are per file and saved after the loop, so
+#: the next run resumes where this one stopped. Stopping *within* a file is
+#: what ``_rewind`` covers.
+SYNC_BUDGET_S = 20.0
+
+#: The host truncation the live path applies, in tokens. ``estimate_tokens``
+#: is ``len // 4``, so capping characters and capping tokens agree exactly.
+HOST_OUTPUT_CAP_TOKENS = HOST_OUTPUT_CAP_CHARS // 4
+
+#: Cursors for this surface alone. Sharing the decision miner's would starve
+#: whichever ran second, silently: that cursor advances as bytes are read.
+_CURSOR_FILENAME = "transcript-cursors.json"
+
+_SIDECAR_DIR = (".repowise", "omissions")
+_SIDECAR_DB = "omissions.db"
+
+
+@dataclass(slots=True)
+class TranscriptSyncResult:
+ """What one sync pass read, recorded and left for next time."""
+
+ recorded: int = 0
+ saved_input_tokens: int = 0
+ #: Markers whose ref an event already claims.
+ already_recorded: int = 0
+ transcripts_read: int = 0
+ #: Transcripts the time budget did not reach. Non-zero means run again.
+ deferred: int = 0
+ #: Events the ledger refused, usually a contended sidecar. Non-zero holds
+ #: the cursors back so the next run re-reads rather than losing them.
+ write_failures: int = 0
+ per_harness: dict[str, int] = field(default_factory=dict)
+
+ @property
+ def complete(self) -> bool:
+ return self.deferred == 0
+
+
+@dataclass(slots=True)
+class _Candidate:
+ """One marker found in a shell result, before the ledger is consulted."""
+
+ marker: ParsedMarker
+ harness: str
+ occurred_at: datetime
+ delivered_tokens: int
+ session_id: str | None
+
+
+def sync_transcript_savings(
+ repo_root: Path,
+ *,
+ harnesses: Sequence[str] | None = None,
+ projects_root: Path | None = None,
+ budget: float = SYNC_BUDGET_S,
+ dry_run: bool = False,
+ now: float | None = None,
+) -> TranscriptSyncResult:
+ """Record savings this repository's agents were shown but never banked.
+
+ Creates the savings sidecar if it does not exist. A deliberate departure
+ from the recorder, which never creates one because a hook or an MCP call
+ is not the place to decide a repository has opted in. Being called *is*
+ that decision here: this runs from ``init`` and from an explicit command.
+
+ With *dry_run* nothing is written and no sidecar is created; the result
+ reports what a real run would record, and the cursors do not advance.
+ """
+ repo_root = Path(repo_root).resolve()
+ names = tuple(harnesses) if harnesses else tuple(registered_adapters())
+ result = TranscriptSyncResult()
+ if not names:
+ return result
+
+ cursors = CursorStore(repo_root.joinpath(*_SIDECAR_DIR, _CURSOR_FILENAME))
+ candidates: dict[str, _Candidate] = {}
+ per_harness_budget = budget / len(names)
+ for name in names:
+ try:
+ _sweep(
+ name,
+ repo_root=repo_root,
+ projects_root=projects_root,
+ cursors=cursors,
+ candidates=candidates,
+ budget=per_harness_budget,
+ result=result,
+ )
+ except Exception as exc:
+ # One harness must not cost another's progress: the cursor save
+ # below is shared, so an escape here would discard every advance.
+ logger.warning("savings transcript sweep failed: %s: %s", name, exc)
+
+ if dry_run:
+ _apply(repo_root, candidates, result, store=None)
+ return result
+
+ with closing(_open_store(repo_root)) as store:
+ _apply(repo_root, candidates, result, store=store)
+ if result.write_failures:
+ # The recorder never raises -- a contended sidecar comes back as False,
+ # not as an exception -- so an advanced cursor here would step past a
+ # marker nothing recorded and nothing can find again. Re-reading costs
+ # one pass; the ref anti-join makes it free of double counting.
+ return result
+ cursors.save()
+ return result
+
+
+def _open_store(repo_root: Path) -> OmissionStore:
+ return OmissionStore(repo_root.joinpath(*_SIDECAR_DIR, _SIDECAR_DB))
+
+
+def _sweep(
+ harness: str,
+ *,
+ repo_root: Path,
+ projects_root: Path | None,
+ cursors: CursorStore,
+ candidates: dict[str, _Candidate],
+ budget: float,
+ result: TranscriptSyncResult,
+) -> None:
+ adapter = get_adapter(harness)
+ shell_tools = adapter.shell_tool_names
+ if not shell_tools:
+ return
+ deadline = time.monotonic() + budget
+ discovered = adapter.discover(repo_root, projects_root=projects_root)
+ for index, path in enumerate(discovered):
+ if time.monotonic() > deadline:
+ result.deferred += len(discovered) - index
+ return
+ resume = cursors.get(path)
+ try:
+ events = iter_new_events(adapter, path, cursors, prefilter=_gate(adapter))
+ unpaired = _collect(events, harness, repo_root, shell_tools, candidates)
+ result.transcripts_read += 1
+ except OSError:
+ continue
+ if unpaired:
+ # A shell call whose result has not been written yet. Its marker is
+ # past the cursor, and the pairing that identifies it as a shell
+ # result is behind it, so advancing now would make the marker
+ # unattributable forever. Re-read this file next time instead.
+ _rewind(cursors, path, resume)
+
+
+def _gate(adapter: HarnessAdapter) -> RawPrefilter | None:
+ """The adapter's tool-call gate, widened to keep every marker line.
+
+ The tool call and the result carrying its marker are separate lines, and
+ only the pair says a marker came from a shell command, so a marker-only
+ gate sees results it can no longer attribute. Widening rather than
+ narrowing matters because the cursor advances per line read: a line this
+ gate drops is consumed, not revisited.
+ """
+ tool_gate = adapter.prefilter(INTENT_TOOL_CALLS)
+ if tool_gate is None:
+ return None
+
+ def gate(raw_line: str) -> bool:
+ return tool_gate(raw_line) or "repowise#" in raw_line
+
+ return gate
+
+
+def _collect(
+ events: Iterable[Event],
+ harness: str,
+ repo_root: Path,
+ shell_tools: frozenset[str],
+ candidates: dict[str, _Candidate],
+) -> set[str]:
+ """Collect markers from shell results; return shell calls left unanswered."""
+ shell_calls: set[str] = set()
+ for event in events:
+ for use in event.tool_uses:
+ if use.name in shell_tools:
+ shell_calls.add(use.id)
+ for block in event.tool_results:
+ if block.tool_use_id not in shell_calls:
+ continue
+ shell_calls.discard(block.tool_use_id)
+ if not _in_repo(event, repo_root):
+ continue
+ _harvest(block, event, harness, candidates)
+ return shell_calls
+
+
+def _harvest(
+ block: ToolResult,
+ event: Event,
+ harness: str,
+ candidates: dict[str, _Candidate],
+) -> None:
+ for text in _result_texts(block):
+ for marker in parse_markers(text):
+ candidates.setdefault(
+ marker.ref,
+ _Candidate(
+ marker=marker,
+ harness=harness,
+ occurred_at=_occurred_at(event),
+ delivered_tokens=estimate_tokens(text),
+ session_id=event.session_id,
+ ),
+ )
+
+
+def _rewind(cursors: CursorStore, path: Path, resume: dict[str, Any] | None) -> None:
+ """Put *path*'s cursor back where this pass found it."""
+ if resume is None:
+ cursors.advance(path, offset=0, mtime=0.0)
+ else:
+ cursors.advance(path, offset=resume["offset"], mtime=resume["mtime"])
+
+
+def _in_repo(event: Event, repo_root: Path) -> bool:
+ """True when the event states a ``cwd`` inside *repo_root*.
+
+ A stated ``cwd`` is required rather than assumed, which is also what the
+ sibling scan in ``distill.missed`` does. One harness files transcripts by
+ date and returns every rollout on the machine from ``discover``, so for it
+ ``cwd`` is the only thing separating this repository from another, and
+ reading an absent one as "no opinion" would bank a second repository's
+ savings here -- in a ledger whose ref anti-join is per repository, so both
+ would count it.
+ """
+ if not event.cwd:
+ return False
+ try:
+ cwd = Path(event.cwd).resolve()
+ except OSError:
+ return False
+ return cwd == repo_root or repo_root in cwd.parents
+
+
+def _occurred_at(event: Event) -> datetime:
+ return datetime.fromtimestamp(event.ts if event.ts is not None else time.time(), UTC)
+
+
+def _result_texts(block: ToolResult) -> Iterable[str]:
+ """Every string a tool result carries, across the shapes harnesses use.
+
+ A result is a bare string, a list of content blocks, or a record of named
+ streams, depending on the harness and the tool.
+ """
+ for blob in (block.content, block.payload):
+ yield from _strings_in(blob)
+
+
+def _strings_in(blob: Any) -> Iterable[str]:
+ if isinstance(blob, str):
+ yield blob
+ elif isinstance(blob, list):
+ for item in blob:
+ yield from _strings_in(item)
+ elif isinstance(blob, dict):
+ # A content block names its own text; a stream record does not, so
+ # every string it holds is output.
+ text = blob.get("text")
+ if isinstance(text, str):
+ yield text
+ else:
+ yield from (value for value in blob.values() if isinstance(value, str))
+
+
+def _accounting(candidate: _Candidate) -> tuple[int, int]:
+ """``(baseline, delivered)`` input tokens for one recovered marker.
+
+ ``delivered`` is the text the marker was found in, which for a shell
+ result is the command output the model read back. ``baseline`` adds back
+ what the marker says was dropped, minus the
+ marker's own cost, then re-applies the host truncation the live path
+ applies -- bytes past it never reached the model and cannot be claimed.
+ """
+ delivered = candidate.delivered_tokens
+ kept = max(delivered - estimate_tokens(candidate.marker.text), 0)
+ stored = kept + candidate.marker.tokens_omitted
+ return min(stored, HOST_OUTPUT_CAP_TOKENS), delivered
+
+
+def _payload(
+ repo_root: Path, candidate: _Candidate, operation: str, surface: str
+) -> dict[str, Any]:
+ baseline, delivered = _accounting(candidate)
+ return {
+ "event_id": new_event_id(),
+ # Scoped on the ref, so a re-read is a retry rather than a second
+ # saving even if the ref anti-join is ever bypassed.
+ "idempotency_key": scoped_idempotency_key(
+ str(repo_root), surface, ESTIMATOR, candidate.marker.ref
+ ),
+ "occurred_at": candidate.occurred_at,
+ "surface": surface,
+ # The live path writes unknown here because it cannot see who invoked
+ # it. A transcript names the harness it came from.
+ "integration": candidate.harness,
+ "agent": candidate.harness,
+ "operation": operation,
+ "evidence_kind": "measured",
+ "estimator": ESTIMATOR,
+ "token_unit": "estimated_tokens",
+ "result_state": "success",
+ "is_usable": True,
+ "baseline_input_tokens": baseline,
+ "pre_budget_input_tokens": baseline,
+ "delivered_input_tokens": delivered,
+ "omission_refs": (candidate.marker.ref,),
+ "session_id": candidate.session_id,
+ }
+
+
+def _apply(
+ repo_root: Path,
+ candidates: dict[str, _Candidate],
+ result: TranscriptSyncResult,
+ *,
+ store: OmissionStore | None,
+) -> None:
+ """Consult the ledger for every candidate, and record the ones it lacks.
+
+ *store* is None for a dry run, which reads the sidecar if one exists and
+ writes nothing either way.
+ """
+ if not candidates:
+ return
+ refs = list(candidates)
+ if store is not None:
+ known = store.savings().recorded_omission_refs(refs)
+ origins = store.omission_sources(refs)
+ else:
+ known, origins = _read_only_lookup(repo_root, refs)
+
+ from repowise.core.savings import recorder
+
+ for ref, candidate in candidates.items():
+ if ref in known:
+ result.already_recorded += 1
+ continue
+ operation, surface = _origin(origins.get(ref))
+ payload = _payload(repo_root, candidate, operation, surface)
+ if store is not None and not recorder.record_event_in(store, repo_root, payload):
+ result.write_failures += 1
+ continue
+ saved = max(payload["baseline_input_tokens"] - payload["delivered_input_tokens"], 0)
+ result.recorded += 1
+ result.saved_input_tokens += saved
+ result.per_harness[candidate.harness] = result.per_harness.get(candidate.harness, 0) + saved
+
+
+def _origin(source: str | None) -> tuple[str, str]:
+ """``omissions.source`` as ``(operation, surface)``.
+
+ It reads ``"<origin>:<filter>"`` -- ``cli:git_diff``,
+ ``hook-codex:test_output``, ``mcp:get_context`` -- and is the only record
+ of which surface and filter produced a ref. It is TTL-pruned, so most refs
+ a transcript reaches are past it and record the filter as unknown rather
+ than guessing one.
+ """
+ if not source:
+ return "unknown", "distill"
+ origin, _, filter_name = source.partition(":")
+ if origin.startswith("hook"):
+ surface = "hook"
+ elif origin == "mcp":
+ surface = "mcp"
+ else:
+ surface = "distill"
+ return filter_name or "unknown", surface
+
+
+def _read_only_lookup(repo_root: Path, refs: Sequence[str]) -> tuple[set[str], dict[str, str]]:
+ database = repo_root.joinpath(*_SIDECAR_DIR, _SIDECAR_DB)
+ if not database.is_file():
+ return set(), {}
+ from repowise.core.savings.repository import SavingsRepository
+
+ try:
+ with closing(sqlite3.connect(f"file:{database}?mode=ro", uri=True)) as conn:
+ return (
+ SavingsRepository(conn).recorded_omission_refs(refs),
+ omission_sources(conn, refs),
+ )
+ except sqlite3.Error:
+ return set(), {}
diff --git a/packages/core/src/repowise/core/sessions/adapters/base.py b/packages/core/src/repowise/core/sessions/adapters/base.py
index bbb4a9f21..74a086b59 100644
--- a/packages/core/src/repowise/core/sessions/adapters/base.py
+++ b/packages/core/src/repowise/core/sessions/adapters/base.py
@@ -62,6 +62,15 @@ class HarnessAdapter(ABC):
#: neither is the other's source of truth.
edit_tool_names: ClassVar[frozenset[str]] = frozenset()
+ #: Tool names whose result is a shell command's output, in this harness's
+ #: vocabulary. Per adapter for the same reason ``edit_tool_names`` is: one
+ #: harness spells it ``Bash``, another splits one interactive shell across
+ #: ``exec_command``, ``write_stdin`` and ``wait``. Consumers use it to tell
+ #: command output from a tool call's structured response. Empty means the
+ #: adapter declared none, and such a consumer sees no shell results rather
+ #: than guessing.
+ shell_tool_names: ClassVar[frozenset[str]] = frozenset()
+
@abstractmethod
def discover(self, repo_root: Path, *, projects_root: Path | None = None) -> list[Path]:
"""Transcript files for sessions rooted at *repo_root*, sorted.
diff --git a/packages/core/src/repowise/core/sessions/adapters/claude_code.py b/packages/core/src/repowise/core/sessions/adapters/claude_code.py
index 83d41a604..518448ca5 100644
--- a/packages/core/src/repowise/core/sessions/adapters/claude_code.py
+++ b/packages/core/src/repowise/core/sessions/adapters/claude_code.py
@@ -61,6 +61,7 @@ class ClaudeCodeAdapter(HarnessAdapter):
edit_tool_names: ClassVar[frozenset[str]] = frozenset(
{"Edit", "Write", "MultiEdit", "NotebookEdit"}
)
+ shell_tool_names: ClassVar[frozenset[str]] = frozenset({"Bash", "PowerShell"})
def discover(self, repo_root: Path, *, projects_root: Path | None = None) -> list[Path]:
directory = transcript_dir_for(repo_root, projects_root)
diff --git a/packages/core/src/repowise/core/sessions/adapters/codex.py b/packages/core/src/repowise/core/sessions/adapters/codex.py
index 2ff7910a3..e41f2ce39 100644
--- a/packages/core/src/repowise/core/sessions/adapters/codex.py
+++ b/packages/core/src/repowise/core/sessions/adapters/codex.py
@@ -73,6 +73,12 @@ class CodexAdapter(HarnessAdapter):
#: nothing scrapes the ``*** Update File:`` markers out of it yet, so no
#: Codex edit currently reaches a consumer of this set.
edit_tool_names: ClassVar[frozenset[str]] = frozenset({"edit_file"})
+ #: ``bash`` is what _normalize_tool_name folds ``exec``/``run_command``
+ #: onto; the other three are Codex's interactive shell, where one command
+ #: opens a session and its output arrives across later calls.
+ shell_tool_names: ClassVar[frozenset[str]] = frozenset(
+ {"bash", "shell_command", "exec_command", "write_stdin", "wait"}
+ )
def __init__(self):
self._tool_calls: dict[str, ToolUse] = {}
diff --git a/packages/web/src/app/repos/[id]/costs/page.test.tsx b/packages/web/src/app/repos/[id]/costs/page.test.tsx
new file mode 100644
index 000000000..6e80355b7
--- /dev/null
+++ b/packages/web/src/app/repos/[id]/costs/page.test.tsx
@@ -0,0 +1,317 @@
+// @vitest-environment jsdom
+
+/**
+ * The costs page's host-owned behaviour.
+ *
+ * The shared savings primitives are tested in `@repowise-dev/ui`. What is only
+ * true here is what the host owns: the reset notice's storage key and its
+ * fail-open reads, and which of the four report states the page is in --
+ * unavailable, loading, error, or a report. Those are the three places this
+ * page can lie to a reader on its own.
+ */
+
+import React from "react";
+import { SWRConfig } from "swr";
+import { cleanup, render, screen, waitFor, fireEvent } from "@testing-library/react";
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { CostSummary, Savings } from "@/lib/api/costs";
+
+const mocks = vi.hoisted(() => ({
+ getSavings: vi.fn(),
+ getCostSummary: vi.fn(),
+ repoId: { current: "repo-1" },
+}));
+
+vi.mock("@/lib/api/costs", () => ({
+ getSavings: mocks.getSavings,
+ getCostSummary: mocks.getCostSummary,
+}));
+
+vi.mock("next/navigation", () => ({
+ useParams: () => ({ id: mocks.repoId.current }),
+}));
+
+vi.mock("next/link", () => ({
+ default: ({
+ href,
+ children,
+ ...rest
+ }: {
+ href: string;
+ children?: React.ReactNode;
+ }) => (
+ <a href={href} {...rest}>
+ {children}
+ </a>
+ ),
+}));
+
+import CostsPage from "./page";
+import { ACCOUNTING_METHOD_VERSION } from "@repowise-dev/ui/savings";
+
+beforeAll(() => {
+ // jsdom implements no layout, so `ViewTabs` scrolling its active tab into
+ // view on mount throws rather than doing nothing.
+ Element.prototype.scrollIntoView = vi.fn();
+});
+
+/** A report with something in it. Every figure is a wire field; the page does
+ * no arithmetic, so the values only have to be distinguishable. */
+function makeSavings(overrides: Partial<Savings> = {}): Savings {
+ return {
+ available: true,
+ window_days: null,
+ as_of: "2026-09-19T00:00:00Z",
+ first_event_at: "2026-09-01T00:00:00Z",
+ last_event_at: "2026-09-19T00:00:00Z",
+
+ unique_events: 12,
+ successful_or_usable_partial_events: 11,
+ saving_interactions: 9,
+ mcp_queries_answered: 4,
+ dead_ends: 1,
+
+ saved_input_tokens: 400_000,
+ measured_saved_input_tokens: 400_000,
+ inferred_saved_input_tokens: 0,
+ priced_saved_input_tokens: 0,
+ unpriced_saved_input_tokens: 400_000,
+ priced_input_savings_usd: 0,
+ saved_output_tokens: null,
+ priced_saved_output_tokens: 0,
+ unpriced_saved_output_tokens: 0,
+ priced_output_savings_usd: 0,
+
+ per_operation: [{ group: "rg", events: 9, saved_input_tokens: 400_000 }],
+ per_surface: [{ group: "distill", events: 9, saved_input_tokens: 400_000 }],
+ per_agent: [
+ {
+ agent: "claude_code",
+ agent_display_name: "Claude Code",
+ events: 9,
+ saved_input_tokens: 400_000,
+ },
+ ],
+ per_model: [{ group: null, events: 9, saved_input_tokens: 400_000 }],
+ per_day: [{ group: "2026-09-19", events: 9, saved_input_tokens: 400_000 }],
+
+ opportunity_count: 0,
+ opportunity_tokens_excluded: 0,
+ per_opportunity_kind: [],
+ missed_events: 0,
+ missed_tokens_est: 0,
+ missed_window_days: 0,
+ reread_events: 0,
+ reread_tokens_est: 0,
+ ...overrides,
+ };
+}
+
+function makeSpend(overrides: Partial<CostSummary> = {}): CostSummary {
+ return {
+ total_cost_usd: 1.25,
+ total_calls: 7,
+ total_input_tokens: 5000,
+ total_output_tokens: 900,
+ since: "2026-09-01T00:00:00Z",
+ ...overrides,
+ };
+}
+
+/** A fresh SWR cache per render, so a key resolved in one test is not served
+ * from cache in the next. */
+function renderPage() {
+ return render(
+ <SWRConfig value={{ provider: () => new Map(), errorRetryCount: 0, dedupingInterval: 0 }}>
+ <CostsPage />
+ </SWRConfig>,
+ );
+}
+
+let repoCounter = 0;
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ window.localStorage.clear();
+ // A distinct repository per test keeps the notice's storage key, which is
+ // keyed on the repository, from carrying between them.
+ repoCounter += 1;
+ mocks.repoId.current = `repo-${repoCounter}`;
+ mocks.getSavings.mockResolvedValue(makeSavings());
+ mocks.getCostSummary.mockResolvedValue(makeSpend());
+});
+
+afterEach(() => {
+ cleanup();
+ vi.restoreAllMocks();
+});
+
+describe("costs page reset notice", () => {
+ it("writes dismissal under the repository and accounting-method version", async () => {
+ renderPage();
+
+ const dismiss = await screen.findByRole("button", {
+ name: "Dismiss the savings accounting notice",
+ });
+ fireEvent.click(dismiss);
+
+ await waitFor(() =>
+ expect(
+ screen.queryByText(/Savings accounting has been upgraded/),
+ ).toBeNull(),
+ );
+ // The exact key, not merely "some key": a repository-only key would hide a
+ // later methodology change, and a version-only key would hide the notice
+ // for every other repository.
+ expect(
+ window.localStorage.getItem(
+ `repowise:savings-reset-dismissed:${mocks.repoId.current}:v${ACCOUNTING_METHOD_VERSION}`,
+ ),
+ ).toBe("1");
+ });
+
+ it("stays dismissed for a repository that already stored the key", async () => {
+ window.localStorage.setItem(
+ `repowise:savings-reset-dismissed:${mocks.repoId.current}:v${ACCOUNTING_METHOD_VERSION}`,
+ "1",
+ );
+
+ renderPage();
+
+ await screen.findByRole("heading", { name: "Repowise model spend" });
+ expect(
+ screen.queryByText(/Savings accounting has been upgraded/),
+ ).toBeNull();
+ });
+
+ it("shows again for the same repository under a later accounting version", async () => {
+ window.localStorage.setItem(
+ `repowise:savings-reset-dismissed:${mocks.repoId.current}:v${ACCOUNTING_METHOD_VERSION + 1}`,
+ "1",
+ );
+
+ renderPage();
+
+ expect(
+ await screen.findByText(/Savings accounting has been upgraded/),
+ ).toBeTruthy();
+ });
+
+ it("shows the notice when storage cannot be read", async () => {
+ vi.spyOn(Storage.prototype, "getItem").mockImplementation(() => {
+ throw new Error("storage blocked");
+ });
+
+ renderPage();
+
+ // Fail open: an explanation shown twice beats a restarted total never
+ // explained.
+ expect(
+ await screen.findByText(/Savings accounting has been upgraded/),
+ ).toBeTruthy();
+ });
+
+ it("hides the notice even when the dismissal cannot be stored", async () => {
+ vi.spyOn(Storage.prototype, "setItem").mockImplementation(() => {
+ throw new Error("storage blocked");
+ });
+
+ renderPage();
+ fireEvent.click(
+ await screen.findByRole("button", {
+ name: "Dismiss the savings accounting notice",
+ }),
+ );
+
+ // The reader asked for it to go away now. It returns on the next mount,
+ // which is the cost of storage being unavailable, not a reason to ignore
+ // the click.
+ await waitFor(() =>
+ expect(
+ screen.queryByText(/Savings accounting has been upgraded/),
+ ).toBeNull(),
+ );
+ });
+});
+
+describe("costs page savings states", () => {
+ it("says nothing has been measured when the report is unavailable", async () => {
+ mocks.getSavings.mockResolvedValue(makeSavings({ available: false }));
+
+ renderPage();
+
+ expect(
+ await screen.findByRole("heading", { name: "No agent savings recorded yet" }),
+ ).toBeTruthy();
+ // Unavailable is a semantic state, not a load state, and not an error.
+ expect(screen.queryByText("Loading agent savings")).toBeNull();
+ expect(screen.queryByText("Couldn't load agent savings")).toBeNull();
+ // Nor is it a measured zero: no figure is published for a report that has
+ // nothing behind it.
+ expect(screen.queryByRole("heading", { name: "Savings by source" })).toBeNull();
+ });
+
+ it("reserves the report while it is in flight", async () => {
+ mocks.getSavings.mockReturnValue(new Promise<Savings>(() => {}));
+
+ renderPage();
+
+ // The skeleton announces itself through a `role="status"` region. Queried
+ // by its text, not by an accessible name: `status` takes its name from the
+ // author, so a name-scoped query here matches nothing and passes whatever
+ // the page does.
+ expect(await screen.findByText("Loading agent savings")).toBeTruthy();
+ // A pending fetch is not an empty repository.
+ expect(
+ screen.queryByRole("heading", { name: "No agent savings recorded yet" }),
+ ).toBeNull();
+ });
+
+ it("renders the report once it resolves", async () => {
+ renderPage();
+
+ expect(
+ await screen.findByRole("heading", { name: "Savings by source" }),
+ ).toBeTruthy();
+ expect(screen.queryByText("Loading agent savings")).toBeNull();
+ });
+});
+
+describe("costs page error copy", () => {
+ it("reassures about spend only when spend actually loaded", async () => {
+ mocks.getSavings.mockRejectedValue(new Error("savings down"));
+
+ renderPage();
+
+ expect(
+ await screen.findByText(
+ "The savings endpoint did not respond. Model spend below is unaffected.",
+ ),
+ ).toBeTruthy();
+ });
+
+ it("makes no claim about spend when spend failed too", async () => {
+ mocks.getSavings.mockRejectedValue(new Error("savings down"));
+ mocks.getCostSummary.mockRejectedValue(new Error("spend down"));
+
+ renderPage();
+
+ expect(
+ await screen.findByText("The savings endpoint did not respond."),
+ ).toBeTruthy();
+ // This sentence sat directly above a spend error before the fix.
+ expect(screen.queryByText(/Model spend below is unaffected/)).toBeNull();
+ expect(screen.getByText("Couldn't load model spend")).toBeTruthy();
+ });
+
+ it("keeps the savings report when only spend fails", async () => {
+ mocks.getCostSummary.mockRejectedValue(new Error("spend down"));
+
+ renderPage();
+
+ expect(await screen.findByText("Couldn't load model spend")).toBeTruthy();
+ expect(screen.getByRole("heading", { name: "Savings by source" })).toBeTruthy();
+ expect(screen.queryByText("Couldn't load agent savings")).toBeNull();
+ });
+});
diff --git a/tests/unit/cli/test_lazy_commands.py b/tests/unit/cli/test_lazy_commands.py
index d2e36c363..ce3f20fcb 100644
--- a/tests/unit/cli/test_lazy_commands.py
+++ b/tests/unit/cli/test_lazy_commands.py
@@ -39,7 +39,7 @@ _EXPECTED_NAMES = frozenset(
"export", "generate", "generate-claude-md", "health", "hook",
"impacted-tests", "init", "login", "logout", "mcp", "overlap", "reindex",
"restyle",
- "risk", "saved", "search", "security", "serve", "status", "symbol",
+ "risk", "saved", "savings", "search", "security", "serve", "status", "symbol",
"telemetry", "uninstall", "update", "watch", "whats-new", "whoami", "why",
"wiki-styles", "workspace",
}
diff --git a/tests/unit/savings/test_transcript.py b/tests/unit/savings/test_transcript.py
new file mode 100644
index 000000000..79669f662
--- /dev/null
+++ b/tests/unit/savings/test_transcript.py
@@ -0,0 +1,595 @@
+"""The transcript savings surface: what it counts, and what it refuses to.
+
+Transcript lines follow the Claude Code JSONL shape, matching
+``tests/unit/distill/test_missed_savings.py``: an assistant entry carries
+``message.content[]`` ``tool_use`` blocks with a top-level ``cwd`` and
+``timestamp``; the paired user entry carries a ``tool_result`` block and a
+top-level ``toolUseResult`` with ``stdout``/``stderr``.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from datetime import UTC, datetime
+from pathlib import Path
+
+import pytest
+
+from repowise.core.distill.budget import estimate_tokens
+from repowise.core.distill.markers import render_marker
+from repowise.core.savings import recorder
+from repowise.core.savings.transcript import (
+ ESTIMATOR,
+ HOST_OUTPUT_CAP_TOKENS,
+ sync_transcript_savings,
+)
+from repowise.core.sessions import transcript_dir_for
+
+NOW = time.time()
+
+#: Long enough that the omitted count dominates, short enough to stay well
+#: under the host cap so a test about the cap is the only one that hits it.
+KEPT = "ok\n" * 40
+
+
+def _iso(ts: float) -> str:
+ return datetime.fromtimestamp(ts, tz=UTC).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+def _pair(
+ output: str,
+ *,
+ cwd: str,
+ tool: str = "Bash",
+ block_id: str = "toolu_01",
+ ts: float = NOW,
+) -> list[dict]:
+ return [
+ {
+ "type": "assistant",
+ "cwd": cwd,
+ "timestamp": _iso(ts),
+ "message": {
+ "role": "assistant",
+ "content": [
+ {
+ "type": "tool_use",
+ "id": block_id,
+ "name": tool,
+ "input": {"command": "pytest -q"},
+ }
+ ],
+ },
+ },
+ {
+ "type": "user",
+ "cwd": cwd,
+ "timestamp": _iso(ts + 1),
+ "message": {
+ "role": "user",
+ "content": [{"type": "tool_result", "tool_use_id": block_id, "content": "..."}],
+ },
+ "toolUseResult": {"stdout": output, "stderr": ""},
+ },
+ ]
+
+
+def _distilled(ref: str, tokens_omitted: int, kept: str = KEPT) -> str:
+ return kept + "\n" + render_marker(ref, 100, tokens_omitted) + "\n"
+
+
+def repo(tmp_path: Path) -> Path:
+ root = tmp_path / "myrepo"
+ (root / ".repowise").mkdir(parents=True)
+ return root
+
+
+def projects(tmp_path: Path, repo: Path) -> Path:
+ root = tmp_path / "projects"
+ transcript_dir_for(repo, root).mkdir(parents=True)
+ return root
+
+
+def _write(projects: Path, repo: Path, entries: list[dict], name: str = "s1") -> Path:
+ path = transcript_dir_for(repo, projects) / f"{name}.jsonl"
+ path.write_text("\n".join(json.dumps(e) for e in entries) + "\n", encoding="utf-8")
+ return path
+
+
+def _sync(repo: Path, projects: Path, **kwargs):
+ return sync_transcript_savings(
+ repo, harnesses=("claude_code",), projects_root=projects, **kwargs
+ )
+
+
+def _events(repo: Path) -> list[sqlite3.Row]:
+ database = repo / ".repowise" / "omissions" / "omissions.db"
+ with sqlite3.connect(database) as conn:
+ conn.row_factory = sqlite3.Row
+ return conn.execute("SELECT * FROM savings_events").fetchall()
+
+
+# -- what it counts ---------------------------------------------------------
+
+
+def test_a_distilled_shell_result_becomes_one_measured_event(repo: Path, projects: Path) -> None:
+ output = _distilled("aaaaaaaaaaaa", 900)
+ _write(projects, repo, _pair(output, cwd=str(repo)))
+
+ result = _sync(repo, projects)
+
+ assert result.recorded == 1
+ (event,) = _events(repo)
+ assert event["evidence_kind"] == "measured"
+ assert event["result_state"] == "success"
+ # delivered is the text the agent actually received; baseline adds back
+ # what the marker says was dropped, minus the marker's own cost.
+ delivered = estimate_tokens(output)
+ marker_cost = estimate_tokens(render_marker("aaaaaaaaaaaa", 100, 900))
+ assert event["delivered_input_tokens"] == delivered
+ assert event["baseline_input_tokens"] == max(delivered - marker_cost, 0) + 900
+ assert event["saved_input_tokens"] == (
+ event["baseline_input_tokens"] - event["delivered_input_tokens"]
+ )
+ assert result.saved_input_tokens == event["saved_input_tokens"]
+
+
+def test_the_event_is_attributed_to_the_harness_it_came_from(repo: Path, projects: Path) -> None:
+ """The live path writes unknown here; a transcript knows who was running."""
+ _write(projects, repo, _pair(_distilled("bbbbbbbbbbbb", 500), cwd=str(repo)))
+
+ _sync(repo, projects)
+
+ (event,) = _events(repo)
+ assert event["agent"] == "claude_code"
+ assert event["integration"] == "claude_code"
+
+
+def test_backfilled_events_are_stamped_apart_from_live_ones(repo: Path, projects: Path) -> None:
+ """Only two of six agents keep transcripts, so the two populations must
+ stay separable or the per-agent split can never be labelled."""
+ _write(projects, repo, _pair(_distilled("cccccccccccc", 500), cwd=str(repo)))
+
+ _sync(repo, projects)
+
+ (event,) = _events(repo)
+ # The literal, not the constant: comparing the module's own value to
+ # itself passes whatever the value is, including the live one.
+ assert event["estimator"] == "transcript_marker_v1"
+ assert ESTIMATOR != "chars_per_token_floor_v1"
+
+
+def test_history_is_not_valued_at_todays_rates(repo: Path, projects: Path) -> None:
+ _write(projects, repo, _pair(_distilled("dddddddddddd", 500), cwd=str(repo)))
+
+ _sync(repo, projects)
+
+ (event,) = _events(repo)
+ assert event["model"] is None
+ assert event["input_rate_usd_per_million"] is None
+
+
+def test_the_event_carries_the_transcripts_own_timestamp(repo: Path, projects: Path) -> None:
+ then = NOW - 90 * 86400
+ _write(projects, repo, _pair(_distilled("eeeeeeeeeeee", 500), cwd=str(repo), ts=then))
+
+ _sync(repo, projects)
+
+ (event,) = _events(repo)
+ assert event["occurred_at"].startswith(datetime.fromtimestamp(then, UTC).strftime("%Y-%m-%d"))
+
+
+def test_the_host_truncation_caps_the_baseline(repo: Path, projects: Path) -> None:
+ """Bytes past the host's own cap never reached the model and cannot be
+ claimed -- the same ceiling the live path applies."""
+ _write(projects, repo, _pair(_distilled("ffffffffffff", 5_000_000), cwd=str(repo)))
+
+ _sync(repo, projects)
+
+ (event,) = _events(repo)
+ assert event["baseline_input_tokens"] == HOST_OUTPUT_CAP_TOKENS
+
+
+def test_the_filter_name_is_recovered_when_the_omission_row_survives(
+ repo: Path, projects: Path
+) -> None:
+ from repowise.core.distill.store import OmissionStore
+
+ store = OmissionStore(repo / ".repowise" / "omissions" / "omissions.db")
+ ref = store.put("x" * 100, source="cli:git_diff", original_tokens=900, kept_tokens=25)
+ store.close()
+ _write(projects, repo, _pair(_distilled(ref, 800), cwd=str(repo)))
+
+ _sync(repo, projects)
+
+ (event,) = _events(repo)
+ assert event["operation"] == "git_diff"
+ assert event["surface"] == "distill"
+
+
+def test_a_pruned_ref_records_an_unknown_filter_rather_than_a_guess(
+ repo: Path, projects: Path
+) -> None:
+ _write(projects, repo, _pair(_distilled("999999999999", 800), cwd=str(repo)))
+
+ _sync(repo, projects)
+
+ (event,) = _events(repo)
+ assert event["operation"] == "unknown"
+
+
+# -- what it refuses to count ----------------------------------------------
+
+
+def test_a_marker_in_an_mcp_result_is_left_to_the_mcp_surface(repo: Path, projects: Path) -> None:
+ _write(
+ projects,
+ repo,
+ _pair(_distilled("111111111111", 900), cwd=str(repo), tool="mcp__repowise__get_context"),
+ )
+
+ result = _sync(repo, projects)
+
+ assert result.recorded == 0
+
+
+def test_a_marker_in_prose_is_not_a_saving(repo: Path, projects: Path) -> None:
+ """Markers appear in documentation, pull-request bodies and fixtures. An
+ entry with no tool result at all carries no evidence of a command."""
+ _write(
+ projects,
+ repo,
+ [
+ {
+ "type": "assistant",
+ "cwd": str(repo),
+ "timestamp": _iso(NOW),
+ "message": {
+ "role": "assistant",
+ "content": [
+ {"type": "text", "text": _distilled("222222222222", 900)},
+ ],
+ },
+ }
+ ],
+ )
+
+ result = _sync(repo, projects)
+
+ assert result.recorded == 0
+
+
+def test_the_documented_example_marker_is_not_counted(repo: Path, projects: Path) -> None:
+ """The docs print ``~6.1k tokens``, rounded. It is quoted into transcripts
+ often enough that admitting it would put a fabricated saving in the
+ ledger, and requiring both counts is what keeps it out."""
+ example = (
+ KEPT + "\n[repowise#a1b2c3d4e5f6: 230 lines omitted (~6.1k tokens); "
+ "restore: repowise expand a1b2c3d4e5f6]\n"
+ )
+ _write(projects, repo, _pair(example, cwd=str(repo)))
+
+ result = _sync(repo, projects)
+
+ assert result.recorded == 0
+
+
+def test_another_repositorys_session_is_not_counted(
+ repo: Path, projects: Path, tmp_path: Path
+) -> None:
+ other = tmp_path / "elsewhere"
+ other.mkdir()
+ _write(projects, repo, _pair(_distilled("333333333333", 900), cwd=str(other)))
+
+ result = _sync(repo, projects)
+
+ assert result.recorded == 0
+
+
+# -- deduplication ----------------------------------------------------------
+
+
+def test_the_same_ref_in_two_sessions_is_one_saving(repo: Path, projects: Path) -> None:
+ """The ref is content-addressed, so the same ref is the same distilled
+ output -- a compaction replay, usually. Counting once is the floor."""
+ output = _distilled("444444444444", 900)
+ _write(projects, repo, _pair(output, cwd=str(repo)), name="s1")
+ _write(projects, repo, _pair(output, cwd=str(repo), block_id="toolu_02"), name="s2")
+
+ result = _sync(repo, projects)
+
+ assert result.recorded == 1
+ assert len(_events(repo)) == 1
+
+
+def test_a_ref_the_ledger_already_claims_is_left_alone(repo: Path, projects: Path) -> None:
+ """Dedup rides the omission ref, not the idempotency key: a live event's
+ key is seeded on a random id and carries no content identity."""
+ from repowise.core.distill.store import OmissionStore
+
+ database = repo / ".repowise" / "omissions" / "omissions.db"
+ OmissionStore(database).close()
+ assert recorder.record_event(
+ repo,
+ {
+ "event_id": "11111111-1111-4111-8111-111111111111",
+ "idempotency_key": "sha256:" + "0" * 64,
+ "occurred_at": datetime.now(UTC),
+ "surface": "distill",
+ "integration": "unknown",
+ "agent": "unknown",
+ "operation": "git_diff",
+ "evidence_kind": "measured",
+ "estimator": "chars_per_token_floor_v1",
+ "token_unit": "estimated_tokens",
+ "result_state": "success",
+ "is_usable": True,
+ "baseline_input_tokens": 1000,
+ "delivered_input_tokens": 100,
+ "omission_refs": ("555555555555",),
+ },
+ )
+ _write(projects, repo, _pair(_distilled("555555555555", 900), cwd=str(repo)))
+
+ result = _sync(repo, projects)
+
+ assert result.recorded == 0
+ assert result.already_recorded == 1
+ assert len(_events(repo)) == 1
+
+
+def test_a_second_run_over_unchanged_transcripts_records_nothing(
+ repo: Path, projects: Path
+) -> None:
+ _write(projects, repo, _pair(_distilled("666666666666", 900), cwd=str(repo)))
+
+ assert _sync(repo, projects).recorded == 1
+ second = _sync(repo, projects)
+
+ assert second.recorded == 0
+ assert len(_events(repo)) == 1
+
+
+def test_a_second_run_picks_up_what_was_appended_since(repo: Path, projects: Path) -> None:
+ path = _write(projects, repo, _pair(_distilled("777777777777", 900), cwd=str(repo)))
+ assert _sync(repo, projects).recorded == 1
+
+ with path.open("a", encoding="utf-8") as handle:
+ for entry in _pair(_distilled("888888888888", 900), cwd=str(repo), block_id="toolu_09"):
+ handle.write(json.dumps(entry) + "\n")
+
+ assert _sync(repo, projects).recorded == 1
+ assert len(_events(repo)) == 2
+
+
+def test_the_cursor_is_this_surfaces_own(repo: Path, projects: Path) -> None:
+ """Sharing the decision miner's staging cursors would starve whichever ran
+ second: that cursor advances as the bytes are read."""
+ _write(projects, repo, _pair(_distilled("aaaaaaaaaaa1", 900), cwd=str(repo)))
+
+ _sync(repo, projects)
+
+ assert (repo / ".repowise" / "omissions" / "transcript-cursors.json").is_file()
+ assert not (repo / ".repowise" / "sessions").exists()
+
+
+# -- writing, and not writing ----------------------------------------------
+
+
+def test_sync_creates_the_sidecar_the_recorder_never_would(repo: Path, projects: Path) -> None:
+ """Being run is the opt-in the recorder cannot assume from a hook."""
+ database = recorder.sidecar_path(repo)
+ _write(projects, repo, _pair(_distilled("aaaaaaaaaaa2", 900), cwd=str(repo)))
+ assert not database.exists()
+
+ _sync(repo, projects)
+
+ assert database.is_file()
+
+
+def test_a_dry_run_writes_nothing_at_all(repo: Path, projects: Path) -> None:
+ _write(projects, repo, _pair(_distilled("aaaaaaaaaaa3", 900), cwd=str(repo)))
+
+ result = _sync(repo, projects, dry_run=True)
+
+ assert result.recorded == 1
+ assert result.saved_input_tokens > 0
+ assert not recorder.sidecar_path(repo).exists()
+ assert not (repo / ".repowise" / "omissions" / "transcript-cursors.json").exists()
+
+
+def test_a_dry_run_leaves_the_next_real_run_everything_to_do(repo: Path, projects: Path) -> None:
+ _write(projects, repo, _pair(_distilled("aaaaaaaaaaa4", 900), cwd=str(repo)))
+
+ _sync(repo, projects, dry_run=True)
+
+ assert _sync(repo, projects).recorded == 1
+
+
+def test_an_exhausted_budget_defers_rather_than_dropping(
+ repo: Path, projects: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """The deadline is checked between files, so a stop leaves whole files
+ unread and the next run picks them up."""
+ for index in range(4):
+ _write(
+ projects,
+ repo,
+ _pair(_distilled(f"{index}00000000000", 900), cwd=str(repo)),
+ name=f"s{index}",
+ )
+
+ # Expire after the second file rather than before the first, so the stop
+ # is mid-sweep: a budget that runs out before any read defers everything
+ # and proves nothing about resuming.
+ ticks = iter([0.0, 0.0, 1.0, 99.0, 99.0, 99.0])
+ monkeypatch.setattr("repowise.core.savings.transcript.time.monotonic", lambda: next(ticks))
+ result = _sync(repo, projects, budget=50.0)
+
+ assert result.deferred > 0
+ assert not result.complete
+ assert result.recorded + result.deferred == 4
+
+ monkeypatch.undo()
+ rest = _sync(repo, projects)
+ assert rest.deferred == 0
+ assert len(_events(repo)) == 4
+
+
+def test_a_repository_with_no_transcripts_records_nothing(repo: Path, tmp_path: Path) -> None:
+ empty = tmp_path / "no-transcripts"
+ empty.mkdir()
+
+ result = sync_transcript_savings(repo, harnesses=("claude_code",), projects_root=empty)
+
+ assert result.recorded == 0
+ assert result.transcripts_read == 0
+
+
+# -- scoping, pairing and origins ------------------------------------------
+
+
+def test_a_session_that_states_no_directory_is_not_claimed(repo: Path, projects: Path) -> None:
+ """One harness returns every rollout on the machine from `discover`, so a
+ stated cwd is the only thing separating this repository from another.
+ Reading an absent one as "no opinion" would bank another repo's savings
+ here, and the anti-join is per repository so both would count it."""
+ entries = _pair(_distilled("aaaaaaaaaaa5", 900), cwd=str(repo))
+ for entry in entries:
+ del entry["cwd"]
+ _write(projects, repo, entries)
+
+ assert _sync(repo, projects).recorded == 0
+
+
+def test_a_session_in_a_subdirectory_is_this_repositorys(repo: Path, projects: Path) -> None:
+ nested = repo / "packages" / "core"
+ nested.mkdir(parents=True)
+ _write(projects, repo, _pair(_distilled("aaaaaaaaaaa6", 900), cwd=str(nested)))
+
+ assert _sync(repo, projects).recorded == 1
+
+
+def test_a_result_whose_call_was_never_seen_is_not_attributed(repo: Path, projects: Path) -> None:
+ """Without its tool_use, nothing says the marker came from a shell command
+ rather than an MCP response."""
+ _, result_entry = _pair(_distilled("aaaaaaaaaaa7", 900), cwd=str(repo))
+ _write(projects, repo, [result_entry])
+
+ assert _sync(repo, projects).recorded == 0
+
+
+def test_a_call_still_running_holds_its_file_back_rather_than_losing_it(
+ repo: Path, projects: Path
+) -> None:
+ """The pairing that identifies a shell result sits behind the cursor. If
+ the cursor advanced past an unanswered call, the marker appended later
+ could never be attributed, and nothing would look for it again."""
+ call, result_entry = _pair(_distilled("aaaaaaaaaaa8", 900), cwd=str(repo))
+ path = _write(projects, repo, [call])
+
+ assert _sync(repo, projects).recorded == 0
+
+ with path.open("a", encoding="utf-8") as handle:
+ handle.write(json.dumps(result_entry) + "\n")
+
+ assert _sync(repo, projects).recorded == 1
+
+
+def test_an_mcp_sourced_ref_keeps_the_mcp_surface(repo: Path, projects: Path) -> None:
+ from repowise.core.distill.store import OmissionStore
+
+ store = OmissionStore(repo / ".repowise" / "omissions" / "omissions.db")
+ ref = store.put("y" * 100, source="mcp:get_context", original_tokens=900, kept_tokens=25)
+ store.close()
+ _write(projects, repo, _pair(_distilled(ref, 800), cwd=str(repo)))
+
+ _sync(repo, projects)
+
+ (event,) = _events(repo)
+ assert event["surface"] == "mcp"
+ assert event["operation"] == "get_context"
+
+
+def test_a_hook_sourced_ref_keeps_the_hook_surface(repo: Path, projects: Path) -> None:
+ from repowise.core.distill.store import OmissionStore
+
+ store = OmissionStore(repo / ".repowise" / "omissions" / "omissions.db")
+ ref = store.put("z" * 100, source="hook-codex:test_output", original_tokens=900, kept_tokens=25)
+ store.close()
+ _write(projects, repo, _pair(_distilled(ref, 800), cwd=str(repo)))
+
+ _sync(repo, projects)
+
+ (event,) = _events(repo)
+ assert event["surface"] == "hook"
+ assert event["operation"] == "test_output"
+
+
+def test_a_refused_write_holds_the_cursor_back(
+ repo: Path, projects: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """The recorder never raises: a contended sidecar comes back as False. An
+ advanced cursor would step past a marker nothing recorded."""
+ _write(projects, repo, _pair(_distilled("aaaaaaaaaaa9", 900), cwd=str(repo)))
+ monkeypatch.setattr("repowise.core.savings.recorder.record_event_in", lambda *a, **k: False)
+
+ refused = _sync(repo, projects)
+ assert refused.recorded == 0
+ assert refused.write_failures == 1
+
+ monkeypatch.undo()
+ assert _sync(repo, projects).recorded == 1
+
+
+def test_one_harness_failing_does_not_cost_the_other_its_reads(
+ repo: Path, projects: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ _write(projects, repo, _pair(_distilled("aaaaaaaaaab1", 900), cwd=str(repo)))
+ real = sync_transcript_savings.__globals__["get_adapter"]
+
+ def explode(name: str):
+ if name == "codex":
+ raise RuntimeError("codex adapter is broken")
+ return real(name)
+
+ monkeypatch.setattr("repowise.core.savings.transcript.get_adapter", explode)
+
+ result = sync_transcript_savings(
+ repo, harnesses=("codex", "claude_code"), projects_root=projects
+ )
+
+ assert result.recorded == 1
+
+
+def test_a_dry_run_against_an_existing_ledger_sees_what_it_already_holds(
+ repo: Path, projects: Path
+) -> None:
+ _write(projects, repo, _pair(_distilled("aaaaaaaaaab2", 900), cwd=str(repo)))
+ assert _sync(repo, projects).recorded == 1
+
+ # A fresh cursor file, so the dry run re-reads the same marker rather than
+ # finding nothing appended.
+ (repo / ".repowise" / "omissions" / "transcript-cursors.json").unlink()
+ dry = _sync(repo, projects, dry_run=True)
+
+ assert dry.recorded == 0
+ assert dry.already_recorded == 1
+
+
+def test_every_marker_in_one_result_is_counted(repo: Path, projects: Path) -> None:
+ output = (
+ KEPT
+ + "\n"
+ + render_marker("aaaaaaaaaab3", 10, 400)
+ + "\n"
+ + render_marker("aaaaaaaaaab4", 10, 500)
+ + "\n"
+ )
+ _write(projects, repo, _pair(output, cwd=str(repo)))
+
+ assert _sync(repo, projects).recorded == 2