Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(episodes): record each agent session as a local, dated episode bound to the files it touched (#1325)
Raghav Chamadiya11fa2ed218af
diff --git a/packages/core/src/repowise/core/pipeline/phases/analysis.py b/packages/core/src/repowise/core/pipeline/phases/analysis.pyindex 715f10eab..c03acb1f7 100644--- a/packages/core/src/repowise/core/pipeline/phases/analysis.py+++ b/packages/core/src/repowise/core/pipeline/phases/analysis.py@@ -314,7 +314,11 @@ async def _run_decision_extraction(session_mining_enabled,)- if llm_client is not None and session_mining_enabled(repo_cfg):+ # Not gated on a provider: the same pass records transcript+ # episodes, which need no model, and gating the read on a key+ # would leave a keyless index with no transcript supply at all.+ # The miner skips its own structuring pass when provider is None.+ if session_mining_enabled(repo_cfg):session_decisions = await asyncio.wait_for(mine_session_decisions(repo_path, provider=llm_client),timeout=DECISION_EXTRACTION_TIMEOUT_SECS,diff --git a/packages/core/src/repowise/core/precedent/store.py b/packages/core/src/repowise/core/precedent/store.pyindex daa48d8b7..6e874ba20 100644--- a/packages/core/src/repowise/core/precedent/store.py+++ b/packages/core/src/repowise/core/precedent/store.py@@ -34,6 +34,13 @@ TIER_STRUCTURAL = "structural"TIER_GIT = "git"TIER_TRANSCRIPT = "transcript"+#: The tiers that describe the repository rather than the machine, and so may+#: be served to somebody who did not derive them. A reader that would put an+#: episode in front of a user asks for these by name: two people asking one+#: question of one repository must get one answer, and a transcript episode+#: exists only on the laptop that recorded it.+SHAREABLE_TIERS = (TIER_STRUCTURAL, TIER_GIT)+#: Rows not re-observed for this long are dropped. Every index refreshes#: ``last_seen_at`` for a fact that still holds, so this evicts only episodes#: whose repository has stopped being indexed — never a live one. (Contrast@@ -42,6 +49,9 @@ TIER_TRANSCRIPT = "transcript"DEFAULT_TTL_DAYS = 90.0#: Row-count cap; oldest-seen rows pruned first when exceeded.DEFAULT_MAX_ROWS = 5000+#: Bound on one ``IN`` list, so a large membership set stays one statement per+#: chunk rather than one variable past whatever SQLite was compiled with.+_IN_CHUNK = 500_SCHEMA = """CREATE TABLE IF NOT EXISTS episodes (@@ -224,6 +234,60 @@ class EpisodeStore:self.prune(now=stamp)return dropped+ def sync_tier(+ self,+ *,+ tier: str,+ kind: str,+ episodes: Iterable[Episode],+ present_subjects: Sequence[str],+ now: float | None = None,+ ) -> int:+ """Accumulate into *tier*, bounded by what still exists.++ The third lifecycle, and the reason it is not one of the other two:++ * :meth:`replace_kinds` says *this run derived the whole kind*, which+ is false here — a run reads only the transcript bytes appended since+ the last one, so a sweep would delete every session it did not+ revisit;+ * :meth:`append_tier` says *this run covered a window and everything in+ it is re-observed*, which is also false — the pass has no window, and+ nothing about reading today's session says last March's still exists.++ What is true, and true of no other tier, is that this one's membership+ can be **enumerated without being read**: the sources are files on+ disk, so a run knows which episodes still have something behind them+ for the cost of the directory listing it already did. That is the+ vouch. *present_subjects* are marked re-observed whether or not they+ were read this run — which is what stops a live episode dying of the+ TTL simply because its session ended — and the rest of *kind* is+ dropped, because its source is gone rather than merely quiet.++ Returns rows dropped for having no source left.+ """+ stamp = time.time() if now is None else now+ ids = [episode_id(tier, kind, s) for s in present_subjects]+ with self._conn: # one transaction: never half-synced+ self._upsert(episodes, stamp)+ # Chunked: a heavy machine's transcript directory can outrun+ # SQLite's per-statement variable limit, and a partial IN list+ # would read as "these are gone" and delete live episodes.+ for start in range(0, len(ids), _IN_CHUNK):+ batch = ids[start : start + _IN_CHUNK]+ placeholders = ",".join("?" * len(batch))+ self._conn.execute(+ f"UPDATE episodes SET last_seen_at = ? WHERE id IN ({placeholders})",+ (stamp, *batch),+ )+ cur = self._conn.execute(+ "DELETE FROM episodes WHERE tier = ? AND kind = ? AND last_seen_at < ?",+ (tier, kind, stamp),+ )+ dropped = cur.rowcount or 0+ self.prune(now=stamp)+ return dropped+def _upsert(self, episodes: Iterable[Episode], stamp: float) -> None:"""Insert or refresh *episodes*. Caller owns the transaction.@@ -322,8 +386,24 @@ class EpisodeStore:# -- reads -------------------------------------------------------------- def list_episodes(self, *, tier: str | None = None, kind: str | None = None) -> list[dict]:- """Episodes, newest birth first. Both filters are optional."""+ def list_episodes(+ self,+ *,+ tier: str | None = None,+ tiers: Sequence[str] | None = None,+ kind: str | None = None,+ subjects: Sequence[str] | None = None,+ ) -> list[dict]:+ """Episodes, newest birth first. Every filter is optional and ANDed.++ *tiers* is the allowlist form, for a reader that must name the tiers it+ is willing to serve rather than take whatever the store happens to+ hold — a new tier is then invisible to it until somebody decides+ otherwise, which is the opposite of the default it replaced.++ An empty *tiers* or *subjects* selects nothing, which is the honest+ reading of an empty allowlist and not the same as ``None``.+ """sql = ("SELECT id, tier, kind, subject, body, evidence, nodes, ""birth_commit, birth_at, last_seen_at FROM episodes"@@ -333,9 +413,26 @@ class EpisodeStore:if tier is not None:clauses.append("tier = ?")params.append(tier)+ if tiers is not None:+ if not tiers:+ return []+ clauses.append(f"tier IN ({','.join('?' * len(tiers))})")+ params.extend(tiers)if kind is not None:clauses.append("kind = ?")params.append(kind)+ if subjects is not None:+ if not subjects:+ return []+ if len(subjects) > _IN_CHUNK:+ # Chunking a SELECT would mean stitching pages back into one+ # ordering; the callers that filter by subject ask about the+ # handful they are writing, so refuse rather than mislead.+ raise ValueError(+ f"subjects filter takes at most {_IN_CHUNK} values, got {len(subjects)}"+ )+ clauses.append(f"subject IN ({','.join('?' * len(subjects))})")+ params.extend(subjects)if clauses:sql += " WHERE " + " AND ".join(clauses)sql += " ORDER BY birth_at DESC, id ASC"diff --git a/packages/core/src/repowise/core/precedent/transcript_episodes.py b/packages/core/src/repowise/core/precedent/transcript_episodes.pynew file mode 100644index 000000000..a2de8beab--- /dev/null+++ b/packages/core/src/repowise/core/precedent/transcript_episodes.py@@ -0,0 +1,390 @@+"""Transcript episodes — one agent session, kept whole, bound to what it touched.++The third and last episode tier, and the only one that is **not shareable**:+structural and git episodes are facts about a repository and travel with it,+while a transcript exists on one laptop. It is labelled ``transcript`` in every+row it writes so a reader can decline it, and no value derived here feeds a+stored score another surface reads.++**Why a whole session rather than a fact mined out of one.** Distillation and+retrieval are different systems with opposite answers on this corpus: mining+sessions for durable records yields ~0.06 per session, while *finding a session+again* months later answered 68% of questions at rank 1. So nothing here is+extracted. The row is the session, and the session's own words are the body.++**Why the body is prose and not the transcript.** "Verbatim" is not affordable+against the raw file and does not need to be. Measured on this machine's corpus+(1,507 sessions, 1,372 MB): what a person and the model actually *said* is+16.6 MB — **1.2%** of the bytes. The rest is tool results, which are file+dumps and command output that the code index already serves better than a+quotation could. Of the 19 questions behind the 68%, 17 are still answerable+from prose alone and 0 are answerable from a session's opening request, which+is what rules out storing a pointer plus an excerpt: that is a label, not a+retrieval system.++**Why this costs no second read.** :func:`TranscriptEpisodeRecorder.observe`+tees the event stream the decision miner is already pulling through the+cursor — every event is yielded onward untouched and folded on the way past.+A second sweep over transcripts would be the same defect as a second ``git+log``, and the cursor makes it worse than wasteful: whichever pass ran first+would leave the second one nothing to read.+"""++from __future__ import annotations++import logging+from collections.abc import Iterable, Iterator, Sequence+from dataclasses import dataclass, field+from datetime import UTC, datetime+from pathlib import Path+from typing import Any++from repowise.core.precedent.store import (+ _IN_CHUNK,+ TIER_TRANSCRIPT,+ Episode,+ EpisodeStore,+)+from repowise.core.sessions.events import event_files, is_prose_user_text, relative_files++_log = logging.getLogger(__name__)++#: The one kind this tier writes. A session is not further classified: the+#: classification is what distillation would have been.+KIND_SESSION = "session"++#: Bound on one row's body. A resource ceiling, not a shape: a session over it+#: is kept and marked rather than dropped. Measured consequence on this+#: machine's heaviest project — p90 is 84 KB, so this holds 98% of sessions+#: whole and truncates the tail that is a transcript of a marathon.+MAX_BODY_BYTES = 128 * 1024++#: Above this many files, the session stops locating anything and is recorded+#: **repo-wide** — kept, with no node set — rather than skipped or truncated.+#: Truncating would leave a scope narrower than the body it describes; skipping+#: would lose the session outright, which is right for a sweeping commit and+#: wrong for a long working session. Chosen above the observed distribution+#: rather than against it: 0 of 80 sampled sessions here reach it, so it is a+#: guard that has never fired on the repository it was written in.+MAX_EPISODE_NODES = 100++#: Read at most this many rows back per merge statement. Taken from the store+#: rather than restated: two independent 500s that must agree forever are one+#: edit away from a ``ValueError`` on the index path.+_MERGE_CHUNK = _IN_CHUNK++#: What turns are joined with. Named because the cap has to account for it.+_JOIN = "\n\n"+++@dataclass+class _Fold:+ """What one transcript contributed, accumulated as its events go past."""++ subject: str+ session_id: str | None = None+ first_ts: float | None = None+ last_ts: float | None = None+ turns: int = 0+ parts: list[str] = field(default_factory=list)+ body_bytes: int = 0+ files: list[str] = field(default_factory=list)++ @property+ def read_something(self) -> bool:+ return self.turns > 0 or bool(self.files)+++def _is_dialog(event: Any) -> bool:+ """Whether this event is the conversation rather than the plumbing.++ Sidechain lines are a subagent's own stream and belong to whatever that+ agent was doing; meta lines are harness bookkeeping the user never saw. A+ post-compaction summary is kept on purpose despite being synthetic: it is+ the only trace left in the file of everything before the compaction, so+ dropping it silently deletes the first half of a long session.++ User turns go through :func:`is_prose_user_text`, the rule the decision+ miner already applies, rather than a second one written here. It is what+ keeps slash-command wrappers and injected reminder blocks out: labelling a+ sample of real episodes found one opening **12 of 20 bodies**, so without+ it the first thing a reader sees is usually harness plumbing.+ """+ if not getattr(event, "text", ""):+ return False+ if event.sidechain or event.is_meta:+ return False+ return is_prose_user_text(event) if event.kind == "user" else True+++class TranscriptEpisodeRecorder:+ """Folds one episode per session out of a stream somebody else is reading.++ Presence is registered when a transcript is *shown* to the recorder, not+ when it yields events: a session already fully consumed by the cursor+ yields nothing and must still count as present, or the next write would+ read its silence as deletion.+ """++ def __init__(self, repo_root: Path) -> None:+ self._repo_root = Path(repo_root)+ self._folds: dict[str, _Fold] = {}+ self._present: list[str] = []++ def note_present(self, paths: Iterable[Path]) -> None:+ """Register transcripts as existing without reading them.++ Presence and reading are different claims, and conflating them deletes+ data: a run may stop reading early on a large first sweep, but every+ transcript it *listed* still has a session behind it. Called with the+ whole discovery result, so a partial sweep never reads its own+ unfinished work as sessions that have gone away.+ """+ for path in paths:+ self._present.append(self._subject(path))++ def observe(self, path: Path, events: Iterable[Any]) -> Iterator[Any]:+ """Yield *events* through untouched, folding what an episode needs.++ Registration happens here rather than inside the generator body: a+ generator function runs no statement until it is iterated, so a+ transcript the caller opens and abandons would silently drop out of+ the presence set and take its episode with it.+ """+ subject = self._subject(path)+ self._present.append(subject)+ fold = self._folds.setdefault(subject, _Fold(subject=subject))+ return self._fold_through(fold, events)++ def _fold_through(self, fold: _Fold, events: Iterable[Any]) -> Iterator[Any]:+ for event in events:+ yield event # first, so a consumer's exception cannot cost the read+ try:+ self._absorb(fold, event)+ except Exception: # pragma: no cover - defensive+ _log.debug("transcript_episodes.absorb_failed", exc_info=True)++ def _absorb(self, fold: _Fold, event: Any) -> None:+ fold.session_id = fold.session_id or event.session_id+ ts = event.ts+ if ts:+ fold.first_ts = ts if fold.first_ts is None else min(fold.first_ts, ts)+ fold.last_ts = ts if fold.last_ts is None else max(fold.last_ts, ts)+ fold.files.extend(event_files(event))+ if not _is_dialog(event):+ return+ text = event.text.strip()+ if not text:+ return+ fold.turns += 1+ # The separator this turn will be joined with counts against the cap+ # too: leaving it out makes the bound wrong by two bytes per turn,+ # which is small and still means the stated cap is not the real one.+ sep = len(_JOIN.encode("utf-8")) if fold.parts else 0+ room = MAX_BODY_BYTES - fold.body_bytes - sep+ if room <= 0:+ return+ chunk = f"{event.kind}: {text}"+ raw = chunk.encode("utf-8", "replace")+ if len(raw) > room:+ # Cut the turn rather than letting it carry the body past the cap.+ # Stopping *before* an oversized turn instead would make the cap a+ # suggestion: one long message can be tens of kilobytes on its own.+ chunk = raw[:room].decode("utf-8", "ignore")+ raw = chunk.encode("utf-8", "replace")+ fold.parts.append(chunk)+ fold.body_bytes += len(raw) + sep++ def _subject(self, path: Path) -> str:+ """Identity of the session: its transcript, as a stable string.++ The transcript rather than the session id, because presence has to be+ answerable from the directory listing alone — the id is inside the file+ and a file past its cursor is never opened. Absolute, and that is+ correct rather than sloppy: this tier is per-machine by definition, and+ a repository that moves should lose the episodes pointing at where it+ used to be.+ """+ return str(path).replace("\\", "/")++ @property+ def present_subjects(self) -> list[str]:+ """Every transcript shown to this recorder, in first-seen order."""+ return list(dict.fromkeys(self._present))++ def pending(self) -> list[_Fold]:+ """Folds that read something and so have an episode to write."""+ return [f for f in self._folds.values() if f.read_something]+++def _nodes_for(+ fold: _Fold, repo_root: Path, prior: Sequence[str] = ()+) -> tuple[tuple[str, ...], int]:+ """(node set, files located) for this session.++ Tool inputs record what a call *reached for*, so they include paths that+ were guessed and never existed — measured at 8.5% of this corpus's nodes,+ two thirds of them directories that were listed rather than edited.+ Keeping only what resolves to a file today is the same discipline as+ dropping paths outside the repository, and it costs one ``stat`` per node.++ The two returns differ only past the ceiling, and the count is what lets a+ reader tell *touched nothing locatable* from *touched too much to locate* —+ both of which are an empty node set, and only one of which is a session+ with nothing to say.+ """+ seen = list(dict.fromkeys([*prior, *relative_files(fold.files, repo_root)]))+ kept = [n for n in seen if (repo_root / n).is_file()]+ if len(kept) > MAX_EPISODE_NODES:+ return (), len(kept)+ return tuple(kept), len(kept)+++def _evidence(fold: _Fold, nodes: Sequence[str], located: int, birth_at: float, body: str) -> str:+ """The one-line label a reader sees beside the body.++ Truncation is read off the stored body rather than carried as a flag from+ the pass that caused it. A later run that finds nothing new has no reason+ to know the body was ever cut, and a flag from *that* pass would quietly+ retract the warning on every long session the moment it ended.+ """+ on = datetime.fromtimestamp(birth_at, tz=UTC).strftime("%Y-%m-%d")+ sid = (fold.session_id or "")[:8] or "unknown"+ if nodes:+ files = "1 file" if len(nodes) == 1 else f"{len(nodes)} files"+ scope = f"touched {files}"+ elif located:+ scope = f"touched {located} files, too many to bind a scope to"+ else:+ scope = "no located files"+ tail = "; body truncated" if len(body.encode("utf-8", "replace")) >= MAX_BODY_BYTES else ""+ return f"session {sid}, {on}, {scope}{tail}"+++def _merged_body(prior_body: str, prior_birth_at: float | None, fold: _Fold) -> str:+ """Prior body plus this run's prose, capped, oldest first.++ A live session is read across several indexes, and the store's upsert+ overwrites rather than appends, so without this the row would end up+ holding only whichever slice of the conversation the last run happened to+ see.++ The guard handles the cursor not being monotonic: ``iter_new_events``+ restarts at byte 0 when a transcript has been truncated or rotated, so+ "everything appended since last time" can turn out to be everything,+ again, and appending it writes the conversation twice.++ **Content cannot decide this on its own, and trying is a bug.** Transcripts+ repeat turns verbatim constantly ("Running the tests.", "Done."), so any+ containment test — anchored or not — eventually reads a genuinely new turn+ as a replay of an old one and silently drops it. What separates the two is+ *when*: a replay re-reads the session's opening turn, so it starts no later+ than the birth already recorded, while new turns are later by construction.+ Time says whether a rewind happened; content says what to keep.+ """+ fresh = _JOIN.join(fold.parts)+ if not prior_body:+ return fresh+ rewound = (+ fold.first_ts is not None+ and prior_birth_at is not None+ and fold.first_ts <= prior_birth_at+ )+ if rewound:+ if fresh.startswith(prior_body):+ return fresh # a replay that has since gone further+ if prior_body.startswith(fresh):+ return prior_body # a replay of what is already held+ sep = len(_JOIN.encode("utf-8"))+ room = MAX_BODY_BYTES - len(prior_body.encode("utf-8", "replace")) - sep+ if room <= 0:+ return prior_body+ add = fresh.encode("utf-8", "replace")[:room].decode("utf-8", "ignore")+ return f"{prior_body}{_JOIN}{add}"+++def derive_transcript_episodes(+ recorder: TranscriptEpisodeRecorder,+ repo_root: Path,+ prior: dict[str, dict] | None = None,+) -> list[Episode]:+ """Episodes for every session this run read. Pure; opens nothing."""+ prior = prior or {}+ out: list[Episode] = []+ for fold in recorder.pending():+ try:+ row = prior.get(fold.subject) or {}+ nodes, located = _nodes_for(fold, repo_root, row.get("nodes") or ())+ body = _merged_body(row.get("body") or "", row.get("birth_at"), fold)+ if not body.strip():+ continue+ birth_at = row.get("birth_at") or fold.first_ts or fold.last_ts+ if not birth_at:+ continue+ out.append(+ Episode(+ tier=TIER_TRANSCRIPT,+ kind=KIND_SESSION,+ subject=fold.subject,+ body=body,+ evidence=_evidence(fold, nodes, located, birth_at, body),+ nodes=nodes,+ # No birth commit: a session is dated, not committed, so+ # its currency is a question the git query cannot answer.+ birth_commit=None,+ birth_at=float(birth_at),+ )+ )+ except Exception: # pragma: no cover - defensive+ _log.debug("transcript_episodes.derive_failed", exc_info=True)+ return out+++def record_transcript_episodes(repo_path: Path | str, recorder: TranscriptEpisodeRecorder) -> int:+ """Persist this run's transcript episodes. Best-effort; never raises.++ A repository that has never been indexed has no ``.repowise`` directory and+ gets no store created underneath it, exactly as the other two tiers.+ """+ try:+ root = Path(repo_path).resolve()+ if not (root / ".repowise").is_dir():+ return 0+ subjects = recorder.present_subjects+ pending = recorder.pending()+ if not subjects and not pending:+ # Nothing was even discovered: this run cannot vouch for the tier's+ # membership, so it must not sweep it. Same rule as a git run that+ # walked no window.+ return 0+ with EpisodeStore.open_for_repo(root) as store:+ prior = _prior_rows(store, [f.subject for f in pending])+ episodes = derive_transcript_episodes(recorder, root, prior)+ store.sync_tier(+ tier=TIER_TRANSCRIPT,+ kind=KIND_SESSION,+ episodes=episodes,+ present_subjects=subjects,+ )+ return len(episodes)+ except Exception: # pragma: no cover - defensive+ _log.debug("transcript_episodes.record_failed", exc_info=True)+ return 0+++def _prior_rows(store: EpisodeStore, subjects: Sequence[str]) -> dict[str, dict]:+ """Existing rows for exactly the sessions about to be rewritten.++ Scoped to those subjects rather than read whole: the tier is one row per+ session with a body measured in tens of kilobytes, so loading all of it to+ update a handful would pull the entire corpus's prose through memory on+ the index path.+ """+ rows: dict[str, dict] = {}+ for start in range(0, len(subjects), _MERGE_CHUNK):+ batch = subjects[start : start + _MERGE_CHUNK]+ for row in store.list_episodes(+ tier=TIER_TRANSCRIPT, kind=KIND_SESSION, subjects=batch+ ):+ rows[row["subject"]] = row+ return rowsdiff --git a/packages/core/src/repowise/core/sessions/events.py b/packages/core/src/repowise/core/sessions/events.pyindex 0a4dd49e4..bc60521b8 100644--- a/packages/core/src/repowise/core/sessions/events.py+++ b/packages/core/src/repowise/core/sessions/events.py@@ -99,6 +99,64 @@ class Event:return INTERRUPT_MARKER in self.text+#: Tool-input keys that name a file. Inputs only: this is what a call said it+#: would operate on, which is why the paths it yields are what a session+#: *reached for* rather than what exists.+FILE_INPUT_KEYS = ("file_path", "path", "notebook_path")+++def event_files(event: Event) -> list[str]:+ """File paths named by this event's tool inputs.++ Deliberately blind to prose and to shell commands: a path argued about in+ a paragraph, or passed to ``git`` inside a command string, is a mention+ rather than a touch, and binding a record to mentions is how a scope stops+ meaning anything. Lives here rather than in a miner because more than one+ consumer folds the same stream and they must agree on what "touched" is.+ """+ files: list[str] = []+ for use in event.tool_uses:+ for key in FILE_INPUT_KEYS:+ value = use.input.get(key)+ if isinstance(value, str) and value.strip():+ files.append(value)+ break+ return files+++def is_prose_user_text(event: Event) -> bool:+ """A message the user actually typed, not harness plumbing.++ Shared because more than one consumer needs the same answer and the cost of+ them disagreeing is silent: a slash-command wrapper or an injected reminder+ block reads as a user turn to anything that only checks ``kind``, and it+ opens the majority of transcripts.+ """+ if event.kind != "user" or event.sidechain or event.is_meta or event.is_compact_summary:+ return False+ if event.tool_results:+ return False+ text = event.text.strip()+ # Command output wrappers, system reminders, and pasted XML-ish blocks+ # start with a tag; none of them are the user speaking.+ return bool(text) and not text.startswith("<")+++def relative_files(files: Iterable[str], repo_root: Any) -> list[str]:+ """Repo-relative POSIX paths, in first-seen order; outsiders dropped."""+ import os.path++ out: list[str] = []+ for f in files:+ try:+ rel = os.path.relpath(f, str(repo_root))+ except (ValueError, OSError):+ continue+ if not rel.startswith(".."):+ out.append(rel.replace("\\", "/"))+ return list(dict.fromkeys(out))++def iter_deduped_usage(events: Iterable[Event]) -> Iterator[Event]:"""Events whose usage should be counted, one per API message.diff --git a/packages/core/src/repowise/core/sessions/miners/decisions.py b/packages/core/src/repowise/core/sessions/miners/decisions.pyindex 51ab7d228..88e534e61 100644--- a/packages/core/src/repowise/core/sessions/miners/decisions.py+++ b/packages/core/src/repowise/core/sessions/miners/decisions.py@@ -46,6 +46,7 @@ from __future__ import annotationsimport hashlibimport jsonimport re+import timefrom collections import dequefrom collections.abc import Iterablefrom dataclasses import dataclass, field@@ -63,8 +64,18 @@ from repowise.core.analysis.decisions.provenance import (from repowise.core.analysis.decisions.rationale_comments import CAUSAL_MARKERSfrom repowise.core.analysis.decisions.scope import resolve_module_nodesfrom repowise.core.distill.corrections import command_anchor+from repowise.core.precedent.transcript_episodes import (+ TranscriptEpisodeRecorder,+ record_transcript_episodes,+)from repowise.core.sessions import INTENT_TURNS, Event, get_adapterfrom repowise.core.sessions.cursor import iter_new_events+from repowise.core.sessions.events import (+ FILE_INPUT_KEYS,+ event_files,+ is_prose_user_text,+ relative_files,+)from repowise.core.sessions.staging import SessionStagingStorelogger = structlog.get_logger(__name__)@@ -133,8 +144,21 @@ _TRAILING_FILES = 8_QUOTE_CAP = 600_MAX_QUOTES_PER_EVENT = 2+#: Wall-clock ceiling on one run's transcript sweep.+#:+#: The corpus this pass reads is bounded by how much the user has worked, not+#: by the repository: a first read starts every cursor at byte 0, and on this+#: machine that is 857 MB across 426 sessions for one repo. Without a ceiling+#: an index's cost depends on a directory that has nothing to do with the code+#: being indexed.+#:+#: Stopping is safe rather than lossy, which is what makes a ceiling the right+#: instrument here: cursors are per file and saved after the loop, so the next+#: run resumes exactly where this one stopped, and steady state (a handful of+#: sessions with new bytes) finishes in well under a tenth of this.+SWEEP_BUDGET_S = 5.0+_EXIT_CODE_RE = re.compile(r"^Error: Exit code (\d+)")-_FILE_INPUT_KEYS = ("file_path", "path", "notebook_path")_SENTENCE_SPLIT_RE = re.compile(r"(?<=[.!?])\s+|\n+")@@ -166,18 +190,6 @@ def _clip(text: str, cap: int = _QUOTE_CAP) -> str:return text if len(text) <= cap else text[: cap - 1] + "…"-def _event_files(event: Event) -> list[str]:- """File paths named by this event's tool inputs."""- files: list[str] = []- for use in event.tool_uses:- for key in _FILE_INPUT_KEYS:- value = use.input.get(key)- if isinstance(value, str) and value.strip():- files.append(value)- break- return files--def _interrupt_guidance(text: str) -> str:"""The user's own words in an interrupt event, marker lines dropped."""from repowise.core.sessions import INTERRUPT_MARKER@@ -186,18 +198,6 @@ def _interrupt_guidance(text: str) -> str:return "\n".join(lines).strip()-def _is_prose_user_text(event: Event) -> bool:- """A message the user actually typed, not harness plumbing."""- if event.kind != "user" or event.sidechain or event.is_meta or event.is_compact_summary:- return False- if event.tool_results:- return False- text = event.text.strip()- # Command output wrappers, system reminders, and pasted XML-ish blocks- # start with a tag; none of them are the user speaking.- return bool(text) and not text.startswith("<")--def _correction_quote(event: Event) -> str | None:"""The verbatim correction text, or None when the gate does not fire."""if event.interrupted:@@ -238,7 +238,7 @@ def _result_anchor(name: str, use_input: dict[str, Any]) -> str:command = use_input.get("command")if isinstance(command, str) and command.strip():return command_anchor(command)- for key in _FILE_INPUT_KEYS:+ for key in FILE_INPUT_KEYS:value = use_input.get(key)if isinstance(value, str) and value.strip():basename = value.replace("\\", "/").rstrip("/").rsplit("/", 1)[-1].lower()@@ -274,7 +274,7 @@ def mine_events(events: Iterable[Event], repo_prefix: str) -> list[SessionCandidcontinueif event.kind == "assistant" and event.tool_uses:- files = _event_files(event)+ files = event_files(event)for f in files:trailing_files.append(f)for entry in open_candidates:@@ -345,7 +345,7 @@ def mine_events(events: Iterable[Event], repo_prefix: str) -> list[SessionCandidopen_dead_end = Nonecontinue- if _is_prose_user_text(event):+ if is_prose_user_text(event):quote = _correction_quote(event)if quote is not None:_add(@@ -361,7 +361,7 @@ def mine_events(events: Iterable[Event], repo_prefix: str) -> list[SessionCandid# Explicit choices: user prose or main-thread assistant prose.if event.text and not event.is_meta and not event.is_compact_summary:- if event.kind == "user" and not _is_prose_user_text(event):+ if event.kind == "user" and not is_prose_user_text(event):continueif event.kind == "assistant" and event.sidechain:continue@@ -523,21 +523,6 @@ def _gate_structured(item: dict[str, Any], raw: dict[str, Any]) -> dict[str, Any_MAX_EVIDENCE_SESSIONS = 5-def _relative_files(files: list[str], repo_root: Path) -> list[str]:- """Repo-relative POSIX paths; files outside the repo are dropped."""- import os.path-- out: list[str] = []- for f in files:- try:- rel = os.path.relpath(f, str(repo_root))- except (ValueError, OSError):- continue- if not rel.startswith(".."):- out.append(rel.replace("\\", "/"))- return list(dict.fromkeys(out))--def _promotion_decisions(row: dict[str, Any], repo_root: Path) -> list[ExtractedDecision]:"""decision_records-ready members for one promotable staging row.@@ -549,7 +534,7 @@ def _promotion_decisions(row: dict[str, Any], repo_root: Path) -> list[Extracted"""structured = row["structured"]status = "active" if row["first_promotion"] else "proposed"- files = _relative_files(structured.get("affected_files") or row["files"], repo_root)+ files = relative_files(structured.get("affected_files") or row["files"], repo_root)modules = resolve_module_nodes(files)confidence = compute_confidence(rank_for_source("session"),@@ -681,12 +666,12 @@ async def apply_injection_feedback(async def mine_session_decisions(repo_path: Path,*,- provider: Any,+ provider: Any | None,projects_root: Path | None = None,max_structured: int = MAX_STRUCTURED_PER_UPDATE,now: float | None = None,) -> list[ExtractedDecision]:- """Mine, structure, and promote session decisions for one repo.+ """Read this repo's new transcript lines once, and serve both consumers.Reads only transcript lines appended since the last run (cursors live inthe staging DB and only advance in the same commit that stages what was@@ -694,6 +679,16 @@ async def mine_session_decisions(decisions that qualify for promotion, ready for the caller's normal``bulk_upsert_decisions`` path. Best-effort at the file level; a failedLLM call leaves candidates staged for the next update.++ The same pass records one transcript episode per session, riding the event+ stream rather than re-reading it. That is not a tidiness point: the cursor+ advances as the file is read, so a second pass over transcripts would find+ nothing left to read, and whichever consumer ran second would be silently+ empty rather than merely slow.++ *provider* may be ``None``. Discovery, folding and staging are keyless and+ run regardless; only the structuring pass needs a model, so a user with no+ API key gets transcript episodes and a staged backlog rather than nothing."""repo_root = Path(repo_path).resolve()repo_prefix = str(repo_root).lower().rstrip("\\/")@@ -701,15 +696,32 @@ async def mine_session_decisions(# This miner needs user prose, assistant prose, tool uses and results:# everything the conversation carries, minus the fat non-dialog lines.prefilter = adapter.prefilter(INTENT_TURNS)+ recorder = TranscriptEpisodeRecorder(repo_root)store = SessionStagingStore.open_default(repo_root)try:# Stage new gate hits from transcript lines appended since last run.staged = 0- for path in adapter.discover(repo_root, projects_root=projects_root):+ deadline = time.monotonic() + SWEEP_BUDGET_S+ deferred = 0+ discovered = adapter.discover(repo_root, projects_root=projects_root)+ # Every discovered transcript is present whether or not this run gets+ # to read it; the episode writer treats absence as deletion.+ recorder.note_present(discovered)+ for index, path in enumerate(discovered):+ if time.monotonic() > deadline:+ # A first index on a machine with a long agent history reads+ # the whole corpus from byte 0, and that corpus is bounded by+ # how much the user has worked, not by the size of the repo:+ # 857 MB across 426 sessions here. Stopping is safe and+ # self-healing rather than lossy, because the cursor is per+ # file and saved below, so the next run resumes exactly where+ # this one stopped. Steady state never reaches the budget.+ deferred = len(discovered) - index+ breaktry:events = iter_new_events(adapter, path, store.cursors, prefilter=prefilter)- for candidate in mine_events(events, repo_prefix):+ for candidate in mine_events(recorder.observe(path, events), repo_prefix):if store.add_raw(hash_=candidate.hash,kind=candidate.kind,@@ -724,12 +736,22 @@ async def mine_session_decisions(store.prune(now=now)store.cursors.save() # commits the staged raws atomically with the cursors+ # After the cursors commit, deliberately: the episode store is a+ # separate sidecar, so writing it first would leave an episode+ # describing bytes the cursor still thinks are unread.+ episodes = record_transcript_episodes(repo_root, recorder)+# One batched structuring pass over whatever is pending (this run's# hits plus any backlog a previous failed call left behind).+ # Queried even with no provider: it is one indexed read, and the+ # structuring loop below is what skips. Forcing this empty instead+ # would report a backlog of zero on exactly the path most likely to+ # have one, since nothing keyless ever drains it.pending = store.pending_raws(max_structured)structured_count = 0processed = 0- for start in range(0, len(pending), _LLM_CHUNK):+ chunk_starts = [] if provider is None else range(0, len(pending), _LLM_CHUNK)+ for start in chunk_starts:chunk = pending[start : start + _LLM_CHUNK]prompt = SESSION_MINING_PROMPT.format(candidates_block=_candidates_block(chunk))try:@@ -776,6 +798,8 @@ async def mine_session_decisions(structured=structured_count,pending_backlog=max(0, len(pending) - processed),promoted=len(decisions),+ episodes=episodes,+ transcripts_deferred=deferred,)return decisionsfinally:diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/episodes.py b/packages/server/src/repowise/server/mcp_server/tool_answer/episodes.pyindex 37f900f86..e2fcbf137 100644--- a/packages/server/src/repowise/server/mcp_server/tool_answer/episodes.py+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/episodes.py@@ -36,7 +36,12 @@ import timefrom pathlib import Pathfrom repowise.core.precedent.currency import commits_since-from repowise.core.precedent.store import TIER_STRUCTURAL, EpisodeStore, default_store_path+from repowise.core.precedent.store import (+ SHAREABLE_TIERS,+ TIER_STRUCTURAL,+ EpisodeStore,+ default_store_path,+)from repowise.server.mcp_server._budget import OmissionCollector, effective_char_budget_log = logging.getLogger(__name__)@@ -62,6 +67,24 @@ _MAX_SCOPED_CANDIDATES = 4#: says nothing about whether the files it changed have moved since._RE_DERIVED_TIERS = frozenset({TIER_STRUCTURAL})+#: The tiers this guard is willing to put in front of a reader, named rather+#: than inherited from whatever the store happens to hold.+#:+#: An unnamed default is how the store's second tier reached this surface last+#: time, and reproducing it with the third showed why that is not survivable+#: here: with 56 of this repository's 426 sessions recorded, the guard went+#: **silent on its own reproduction** and served a session instead. Two things+#: compound. A session touches far more files than a fix commit, so it outranks+#: one on the window's specificity sort; and it has no birth commit, so+#: :func:`_still_true` never reaches the git query and can never suppress it.+#: It wins the window and holds it.+#:+#: The harmlessness bar for a surfaced episode is absolute and is unmeasured+#: for the transcript tier, which is also per-machine — two people asking one+#: question of one repository would get different answers. Until that has been+#: measured, this stays a shareable-tiers allowlist.+_SERVED_TIERS = SHAREABLE_TIERS+#: Room the block needs before it is worth attaching at all._BLOCK_OVERHEAD_CHARS = 400@@ -143,7 +166,7 @@ def _attach(try:with EpisodeStore(store_path) as store:- rows = store.list_episodes()+ rows = store.list_episodes(tiers=_SERVED_TIERS)except Exception:_log.warning("episode store read failed", exc_info=True)returndiff --git a/tests/unit/precedent/test_episode_store.py b/tests/unit/precedent/test_episode_store.pyindex 6f41f4c72..1be70f33c 100644--- a/tests/unit/precedent/test_episode_store.py+++ b/tests/unit/precedent/test_episode_store.py@@ -4,9 +4,13 @@ from __future__ import annotationsfrom pathlib import Path+import pytest+from repowise.core.precedent.store import (+ SHAREABLE_TIERS,TIER_GIT,TIER_STRUCTURAL,+ TIER_TRANSCRIPT,Episode,EpisodeStore,default_store_path,@@ -214,3 +218,180 @@ class TestPaths:assert path.parent.parent.name == ".repowise"assert path.name == "episodes.db"assert not path.exists() # resolving must not create anything+++class TestSyncTier:+ """The third lifecycle: accumulate, bounded by what still exists.++ Its whole reason to exist is that this tier's membership can be enumerated+ without being read, which is true of no other tier.+ """++ def _session(self, subject: str, body: str = "b", birth_at: float = 10.0) -> Episode:+ return Episode(+ tier=TIER_TRANSCRIPT,+ kind="session",+ subject=subject,+ body=body,+ evidence="e",+ nodes=("a.py",),+ birth_at=birth_at,+ )++ def test_a_present_but_unread_member_is_kept_and_re_observed(self, tmp_path: Path) -> None:+ """The case append_tier cannot express and replace_kinds would delete."""+ with _store(tmp_path) as store:+ store.sync_tier(+ tier=TIER_TRANSCRIPT,+ kind="session",+ episodes=[self._session("one"), self._session("two")],+ present_subjects=["one", "two"],+ now=1000.0,+ )+ # A later run reads nothing new but both sources are still there.+ store.sync_tier(+ tier=TIER_TRANSCRIPT,+ kind="session",+ episodes=[],+ present_subjects=["one", "two"],+ now=2000.0,+ )+ rows = store.list_episodes(tier=TIER_TRANSCRIPT)+ assert {r["subject"] for r in rows} == {"one", "two"}+ assert {r["last_seen_at"] for r in rows} == {2000.0}+ # Re-observation must not reset the birth.+ assert {r["birth_at"] for r in rows} == {10.0}++ def test_a_member_whose_source_is_gone_is_dropped(self, tmp_path: Path) -> None:+ with _store(tmp_path) as store:+ store.sync_tier(+ tier=TIER_TRANSCRIPT,+ kind="session",+ episodes=[self._session("one"), self._session("two")],+ present_subjects=["one", "two"],+ now=1000.0,+ )+ store.sync_tier(+ tier=TIER_TRANSCRIPT,+ kind="session",+ episodes=[],+ present_subjects=["one"],+ now=2000.0,+ )+ assert [r["subject"] for r in store.list_episodes(tier=TIER_TRANSCRIPT)] == ["one"]++ def test_it_leaves_other_tiers_and_kinds_alone(self, tmp_path: Path) -> None:+ with _store(tmp_path) as store:+ store.replace_kinds(+ tier=TIER_STRUCTURAL, kinds=["nested_repos"], episodes=[_episode()], now=500.0+ )+ store.sync_tier(+ tier=TIER_TRANSCRIPT,+ kind="session",+ episodes=[self._session("one")],+ present_subjects=["one"],+ now=1000.0,+ )+ assert len(store.list_episodes(tier=TIER_STRUCTURAL)) == 1+ assert len(store.list_episodes(tier=TIER_TRANSCRIPT)) == 1++ def test_membership_larger_than_one_in_list_survives_chunking(self, tmp_path: Path) -> None:+ """A partial IN list would read as "these are gone" and delete live rows."""+ from repowise.core.precedent.store import _IN_CHUNK++ subjects = [f"s{i}" for i in range(_IN_CHUNK + 25)]+ with _store(tmp_path) as store:+ store.sync_tier(+ tier=TIER_TRANSCRIPT,+ kind="session",+ episodes=[self._session(s) for s in subjects],+ present_subjects=subjects,+ now=1000.0,+ )+ store.sync_tier(+ tier=TIER_TRANSCRIPT,+ kind="session",+ episodes=[],+ present_subjects=subjects,+ now=2000.0,+ )+ rows = store.list_episodes(tier=TIER_TRANSCRIPT)+ assert len(rows) == len(subjects)+ assert {r["last_seen_at"] for r in rows} == {2000.0}++ def test_the_transcript_tier_is_capped_without_touching_the_others(+ self, tmp_path: Path+ ) -> None:+ """The tier expected to grow largest is the reason the cap is per tier.++ Sessions accumulate for as long as the harness keeps their transcripts,+ so this is the tier that reaches the cap first; the cold-start facts it+ would otherwise evict are the only supply a history-less repo has.+ """+ (tmp_path / ".repowise").mkdir(exist_ok=True)+ with EpisodeStore(default_store_path(tmp_path), max_rows=3) as store:+ store.replace_kinds(+ tier=TIER_STRUCTURAL, kinds=["nested_repos"], episodes=[_episode()], now=500.0+ )+ subjects = [f"s{i}" for i in range(10)]+ store.sync_tier(+ tier=TIER_TRANSCRIPT,+ kind="session",+ episodes=[+ self._session(s, birth_at=float(i)) for i, s in enumerate(subjects)+ ],+ present_subjects=subjects,+ now=1000.0,+ )++ assert len(store.list_episodes(tier=TIER_STRUCTURAL)) == 1+ kept = store.list_episodes(tier=TIER_TRANSCRIPT)+ assert len(kept) == 3+ # One stamp across the tier is a total tie, so birth has to break+ # it: the newest sessions are the ones worth keeping.+ assert {r["subject"] for r in kept} == {"s7", "s8", "s9"}++class TestListFilters:+ def test_tiers_is_an_allowlist(self, tmp_path: Path) -> None:+ with _store(tmp_path) as store:+ store.replace_kinds(+ tier=TIER_STRUCTURAL, kinds=["nested_repos"], episodes=[_episode()]+ )+ store.sync_tier(+ tier=TIER_TRANSCRIPT,+ kind="session",+ episodes=[+ Episode(+ tier=TIER_TRANSCRIPT,+ kind="session",+ subject="one",+ body="b",+ evidence="e",+ )+ ],+ present_subjects=["one"],+ )+ served = store.list_episodes(tiers=SHAREABLE_TIERS)+ assert {r["tier"] for r in served} == {TIER_STRUCTURAL}+ assert len(store.list_episodes()) == 2++ def test_an_empty_allowlist_selects_nothing(self, tmp_path: Path) -> None:+ with _store(tmp_path) as store:+ store.replace_kinds(+ tier=TIER_STRUCTURAL, kinds=["nested_repos"], episodes=[_episode()]+ )+ assert store.list_episodes(tiers=[]) == []+ assert store.list_episodes(subjects=[]) == []++ def test_the_transcript_tier_is_not_shareable(self) -> None:+ """Asserted rather than commented: this is the whole tier boundary."""+ assert TIER_TRANSCRIPT not in SHAREABLE_TIERS+ assert set(SHAREABLE_TIERS) == {TIER_STRUCTURAL, TIER_GIT}++ def test_too_many_subjects_is_refused_rather_than_silently_paged(+ self, tmp_path: Path+ ) -> None:+ from repowise.core.precedent.store import _IN_CHUNK++ with _store(tmp_path) as store, pytest.raises(ValueError, match="at most"):+ store.list_episodes(subjects=[f"s{i}" for i in range(_IN_CHUNK + 1)])diff --git a/tests/unit/precedent/test_transcript_episodes.py b/tests/unit/precedent/test_transcript_episodes.pynew file mode 100644index 000000000..a0e469043--- /dev/null+++ b/tests/unit/precedent/test_transcript_episodes.py@@ -0,0 +1,570 @@+"""Transcript-tier episodes: one agent session, kept whole, bound to what it touched.++Built on real transcript files run through the real adapter, because every+question worth asserting here is a property of the seam rather than of a mock:+what counts as a touch, what the cursor leaves for a second reader, and what a+run that read nothing is allowed to delete.+"""++from __future__ import annotations++import json+import time++import pytest++from repowise.core.precedent.store import (+ TIER_GIT,+ TIER_TRANSCRIPT,+ Episode,+ EpisodeStore,+ default_store_path,+)+from repowise.core.precedent.transcript_episodes import (+ MAX_BODY_BYTES,+ MAX_EPISODE_NODES,+ TranscriptEpisodeRecorder,+ derive_transcript_episodes,+ record_transcript_episodes,+)+from repowise.core.sessions import INTENT_TURNS, get_adapter++_TS = "2026-08-06T10:00:00.000Z"+++def _line(+ kind: str, text: str = "", *, tools=(), session="s1", cwd=None, ts=_TS, **extra+) -> str:+ """One Claude Code transcript line, in the shape the adapter parses."""+ content: list[dict] = []+ if text:+ content.append({"type": "text", "text": text})+ for name, tool_input in tools:+ content.append({"type": "tool_use", "id": "t1", "name": name, "input": tool_input})+ rec = {+ "type": kind,+ "sessionId": session,+ "timestamp": ts,+ "message": {"role": kind, "content": content},+ **extra,+ }+ if cwd is not None:+ rec["cwd"] = str(cwd)+ return json.dumps(rec)+++def _transcript(tmp_path, name: str, lines: list[str]):+ d = tmp_path / "transcripts"+ d.mkdir(exist_ok=True)+ p = d / name+ p.write_text("\n".join(lines) + "\n", encoding="utf-8")+ return p+++def _repo(tmp_path, *, opted_in: bool = True, files=("a.py",)):+ root = tmp_path / "repo"+ root.mkdir(exist_ok=True)+ for f in files:+ (root / f).parent.mkdir(parents=True, exist_ok=True)+ (root / f).write_text("x = 1\n", encoding="utf-8")+ if opted_in:+ (root / ".repowise").mkdir(exist_ok=True)+ return root+++def _fold(root, *paths) -> TranscriptEpisodeRecorder:+ """Drive one recorder over these transcripts exactly as the miner does.++ One recorder for the whole run, because that is what presence means: the+ miner shows it every transcript ``discover()`` returned, and a recorder+ shown a subset would vouch for a subset.+ """+ adapter = get_adapter()+ rec = TranscriptEpisodeRecorder(root)+ for path in paths:+ with path.open(encoding="utf-8") as fh:+ events = adapter.events_from_lines(+ fh, prefilter=adapter.prefilter(INTENT_TURNS), path=path+ )+ for _ in rec.observe(path, events):+ pass+ return rec+++def _rows(root, **kw) -> list[dict]:+ with EpisodeStore(default_store_path(root)) as store:+ return store.list_episodes(**kw)+++# ---------------------------------------------------------------------------+# What an episode binds to+# ---------------------------------------------------------------------------+++def test_nodes_are_what_tool_calls_touched_not_what_prose_named(tmp_path):+ """The scope rule the whole tier turns on, asserted from both sides.++ A path argued about in a paragraph is a mention; a path passed to a tool is+ a touch. Binding to mentions is how a scope stops discriminating.+ """+ root = _repo(tmp_path, files=("touched.py", "only_discussed.py"))+ path = _transcript(+ tmp_path,+ "s.jsonl",+ [+ _line("user", "please look at only_discussed.py, it seems related"),+ _line(+ "assistant",+ "I will edit the other one instead.",+ tools=[("Edit", {"file_path": str(root / "touched.py")})],+ ),+ ],+ )+ episodes = derive_transcript_episodes(_fold(root, path), root)++ assert len(episodes) == 1+ assert episodes[0].nodes == ("touched.py",)+ # The mention is still in the body: it is evidence, just not scope.+ assert "only_discussed.py" in episodes[0].body+++def test_a_path_named_only_in_a_shell_command_is_not_a_touch(tmp_path):+ root = _repo(tmp_path, files=("real.py",))+ path = _transcript(+ tmp_path,+ "s.jsonl",+ [+ _line(+ "assistant",+ "running the tests",+ tools=[("Bash", {"command": f"pytest {root / 'real.py'}"})],+ )+ ],+ )+ episodes = derive_transcript_episodes(_fold(root, path), root)+ assert episodes and episodes[0].nodes == ()+++def test_a_path_that_is_not_a_file_here_is_dropped(tmp_path):+ """Tool inputs record what was reached for, including guesses that missed."""+ root = _repo(tmp_path, files=("real.py",))+ (root / "adir").mkdir()+ path = _transcript(+ tmp_path,+ "s.jsonl",+ [+ _line(+ "assistant",+ "looking around",+ tools=[+ ("Read", {"file_path": str(root / "real.py")}),+ ("Read", {"file_path": str(root / "guessed" / "nope.py")}),+ ("Glob", {"path": str(root / "adir")}),+ ("Read", {"file_path": str(tmp_path / "outside.py")}),+ ],+ )+ ],+ )+ episodes = derive_transcript_episodes(_fold(root, path), root)+ assert episodes[0].nodes == ("real.py",)+++def test_a_session_over_the_node_ceiling_is_kept_repo_wide(tmp_path):+ """Not skipped and not truncated: kept, with its scope withdrawn.++ A commit above the ceiling is a sweep and is dropped. A session above it is+ an ordinary long session, so dropping it loses the episode outright, while+ truncating would leave a scope narrower than the body describing it.+ """+ files = [f"f{i}.py" for i in range(MAX_EPISODE_NODES + 1)]+ root = _repo(tmp_path, files=files)+ path = _transcript(+ tmp_path,+ "s.jsonl",+ [+ _line(+ "assistant",+ "a very long session",+ tools=[("Edit", {"file_path": str(root / f)}) for f in files],+ )+ ],+ )+ episodes = derive_transcript_episodes(_fold(root, path), root)++ assert len(episodes) == 1+ assert episodes[0].nodes == ()+ assert "too many to bind a scope to" in episodes[0].evidence+++def test_no_located_files_reads_differently_from_too_many(tmp_path):+ root = _repo(tmp_path)+ path = _transcript(tmp_path, "s.jsonl", [_line("user", "just a question")])+ (episode,) = derive_transcript_episodes(_fold(root, path), root)+ assert "no located files" in episode.evidence+++# ---------------------------------------------------------------------------+# The body+# ---------------------------------------------------------------------------+++def test_the_body_is_the_conversation_and_not_the_tool_output(tmp_path):+ root = _repo(tmp_path)+ path = _transcript(+ tmp_path,+ "s.jsonl",+ [+ _line("user", "why is the build failing"),+ _line("assistant", "because the lockfile is stale"),+ ],+ )+ (episode,) = derive_transcript_episodes(_fold(root, path), root)+ assert "why is the build failing" in episode.body+ assert "because the lockfile is stale" in episode.body+++def test_subagent_and_harness_lines_stay_out_of_the_body(tmp_path):+ root = _repo(tmp_path)+ path = _transcript(+ tmp_path,+ "s.jsonl",+ [+ _line("user", "the real question"),+ _line("assistant", "a subagent said this", isSidechain=True),+ _line("user", "a harness reminder", isMeta=True),+ ],+ )+ (episode,) = derive_transcript_episodes(_fold(root, path), root)+ assert "the real question" in episode.body+ assert "a subagent said this" not in episode.body+ assert "a harness reminder" not in episode.body+++def test_a_command_wrapper_does_not_open_the_body(tmp_path):+ """Labelling real episodes found this opening 12 of 20 bodies.++ A slash-command invocation arrives as an ordinary user turn, so anything+ checking only ``kind`` treats harness plumbing as the first thing the user+ said. The miner's shipped rule already knows better; this asserts the+ recorder asks it rather than deciding for itself.+ """+ root = _repo(tmp_path)+ path = _transcript(+ tmp_path,+ "s.jsonl",+ [+ _line("user", "<command-name>/clear</command-name>\n<command-args></command-args>"),+ _line("user", "now the actual request"),+ ],+ )+ (episode,) = derive_transcript_episodes(_fold(root, path), root)++ assert episode.body.startswith("user: now the actual request")+ assert "command-name" not in episode.body+++def test_the_body_cap_is_a_bound_and_not_a_suggestion(tmp_path):+ """One oversized turn must not carry the body past the cap.++ Stopping before an over-long message instead of cutting it makes the cap+ depend on turn size, and a single assistant message here is routinely tens+ of kilobytes.+ """+ root = _repo(tmp_path)+ path = _transcript(+ tmp_path,+ "s.jsonl",+ [+ _line("user", "start"),+ _line("assistant", "x" * (MAX_BODY_BYTES * 2)),+ _line("user", "end"),+ ],+ )+ (episode,) = derive_transcript_episodes(_fold(root, path), root)++ assert len(episode.body.encode("utf-8")) <= MAX_BODY_BYTES+ assert "body truncated" in episode.evidence+++def test_a_session_read_across_two_runs_keeps_both_halves(tmp_path):+ """The store upserts rather than appends, so the merge has to be explicit.++ A session is live while the index runs, so this is the ordinary case rather+ than the corner one: without the merge a row ends up holding whichever+ slice of the conversation the last run happened to see.+ """+ root = _repo(tmp_path, files=("first.py", "second.py"))+ first = _transcript(+ tmp_path,+ "s.jsonl",+ [_line("assistant", "the first half", tools=[("Edit", {"file_path": str(root / "first.py")})])],+ )+ record_transcript_episodes(root, _fold(root, first))++ second = _transcript(+ tmp_path,+ "s.jsonl",+ [_line("assistant", "the second half", tools=[("Edit", {"file_path": str(root / "second.py")})])],+ )+ record_transcript_episodes(root, _fold(root, second))++ (row,) = _rows(root, tier=TIER_TRANSCRIPT)+ assert "the first half" in row["body"]+ assert "the second half" in row["body"]+ assert sorted(row["nodes"]) == ["first.py", "second.py"]+++def test_a_re_read_transcript_is_not_written_twice(tmp_path):+ """The cursor is not monotonic: a truncated file restarts at byte 0.++ So "everything appended since last time" can be everything again, and a+ merge that only ever appends writes the conversation twice.+ """+ root = _repo(tmp_path)+ lines = [_line("user", "the whole thing"), _line("assistant", "and the reply")]+ path = _transcript(tmp_path, "s.jsonl", lines)+ record_transcript_episodes(root, _fold(root, path))+ record_transcript_episodes(root, _fold(root, path))++ (row,) = _rows(root, tier=TIER_TRANSCRIPT)+ assert row["body"].count("the whole thing") == 1+ assert row["body"].count("and the reply") == 1+++# ---------------------------------------------------------------------------+# The tee: the stream must come out the way it went in+# ---------------------------------------------------------------------------+++def test_observe_yields_every_event_unchanged(tmp_path):+ root = _repo(tmp_path)+ path = _transcript(+ tmp_path,+ "s.jsonl",+ [_line("user", "one"), _line("assistant", "two"), _line("user", "three")],+ )+ adapter = get_adapter()+ with path.open(encoding="utf-8") as fh:+ expected = list(+ adapter.events_from_lines(fh, prefilter=adapter.prefilter(INTENT_TURNS), path=path)+ )+ rec = TranscriptEpisodeRecorder(root)+ with path.open(encoding="utf-8") as fh:+ events = adapter.events_from_lines(+ fh, prefilter=adapter.prefilter(INTENT_TURNS), path=path+ )+ seen = list(rec.observe(path, events))++ assert [e.text for e in seen] == [e.text for e in expected]+++def test_a_transcript_shown_but_never_iterated_still_counts_as_present(tmp_path):+ """Presence is registered on show, not on read.++ A session already past its cursor yields nothing, and a run that read its+ silence as absence would delete the episode written when it was new.+ """+ root = _repo(tmp_path)+ path = _transcript(tmp_path, "s.jsonl", [_line("user", "hello")])+ rec = TranscriptEpisodeRecorder(root)+ rec.observe(path, iter(())) # deliberately not iterated++ assert rec.present_subjects == [str(path).replace("\\", "/")]+ assert rec.pending() == []+++def test_a_quiet_session_keeps_its_episode(tmp_path):+ root = _repo(tmp_path)+ path = _transcript(tmp_path, "s.jsonl", [_line("user", "hello")])+ record_transcript_episodes(root, _fold(root, path))+ assert len(_rows(root, tier=TIER_TRANSCRIPT)) == 1++ # Second run: the file is present but has nothing new to give.+ quiet = TranscriptEpisodeRecorder(root)+ quiet.observe(path, iter(()))+ record_transcript_episodes(root, quiet)++ (row,) = _rows(root, tier=TIER_TRANSCRIPT)+ assert "hello" in row["body"]+++def test_a_session_whose_transcript_is_gone_loses_its_episode(tmp_path):+ root = _repo(tmp_path)+ kept = _transcript(tmp_path, "kept.jsonl", [_line("user", "still here")])+ gone = _transcript(tmp_path, "gone.jsonl", [_line("user", "not for long", session="s2")])+ # One recorder across every discovered transcript, which is the production+ # shape: presence is what the whole run saw, so a per-file recorder would+ # have each write delete the file before it.+ record_transcript_episodes(root, _fold(root, kept, gone))+ assert len(_rows(root, tier=TIER_TRANSCRIPT)) == 2++ gone.unlink()+ still_there = TranscriptEpisodeRecorder(root)+ still_there.observe(kept, iter(()))+ record_transcript_episodes(root, still_there)++ rows = _rows(root, tier=TIER_TRANSCRIPT)+ assert [r["subject"] for r in rows] == [str(kept).replace("\\", "/")]+++def test_a_run_that_discovered_nothing_deletes_nothing(tmp_path):+ """The rule the git tier learned: a pass that looked at nothing cannot vouch.++ A transcript directory that has gone missing (a different machine, a moved+ home directory) must read as "cannot tell", not as "every session is gone".+ """+ root = _repo(tmp_path)+ path = _transcript(tmp_path, "s.jsonl", [_line("user", "hello")])+ record_transcript_episodes(root, _fold(root, path))++ record_transcript_episodes(root, TranscriptEpisodeRecorder(root))+ assert len(_rows(root, tier=TIER_TRANSCRIPT)) == 1+++# ---------------------------------------------------------------------------+# Blast radius: the other tiers, and a repo that opted out+# ---------------------------------------------------------------------------+++def test_writing_transcripts_leaves_the_other_tiers_alone(tmp_path):+ root = _repo(tmp_path)+ with EpisodeStore(default_store_path(root)) as store:+ store.append_tier(+ tier=TIER_GIT,+ episodes=[+ Episode(+ tier=TIER_GIT,+ kind="code_fix",+ subject="abc123",+ body="a fix",+ evidence="commit abc123",+ nodes=("a.py",),+ birth_at=1000.0,+ )+ ],+ oldest_birth_at=1.0,+ )+ path = _transcript(tmp_path, "s.jsonl", [_line("user", "hello")])+ record_transcript_episodes(root, _fold(root, path))++ assert len(_rows(root, tier=TIER_GIT)) == 1+ assert len(_rows(root, tier=TIER_TRANSCRIPT)) == 1+++def test_a_repo_that_never_opted_in_gets_no_store(tmp_path):+ root = _repo(tmp_path, opted_in=False)+ path = _transcript(tmp_path, "s.jsonl", [_line("user", "hello")])+ assert record_transcript_episodes(root, _fold(root, path)) == 0+ assert not default_store_path(root).exists()+++def test_recording_never_raises(tmp_path, monkeypatch):+ root = _repo(tmp_path)+ path = _transcript(tmp_path, "s.jsonl", [_line("user", "hello")])+ monkeypatch.setattr(+ "repowise.core.precedent.transcript_episodes.EpisodeStore.open_for_repo",+ lambda *a, **k: (_ for _ in ()).throw(RuntimeError("boom")),+ )+ assert record_transcript_episodes(root, _fold(root, path)) == 0+++def test_no_subprocess_is_spawned(tmp_path, monkeypatch):+ """A session is dated, not committed, so nothing here may ask git anything."""+ import subprocess++ def _forbidden(*a, **k):+ raise AssertionError("no subprocess allowed here")++ monkeypatch.setattr(subprocess, "run", _forbidden)+ monkeypatch.setattr(subprocess, "Popen", _forbidden)+ root = _repo(tmp_path)+ path = _transcript(tmp_path, "s.jsonl", [_line("user", "hello")])+ assert record_transcript_episodes(root, _fold(root, path)) == 1+ (row,) = _rows(root, tier=TIER_TRANSCRIPT)+ assert row["birth_commit"] is None+++def test_the_episode_is_dated_from_the_session_not_the_index(tmp_path):+ root = _repo(tmp_path)+ path = _transcript(tmp_path, "s.jsonl", [_line("user", "hello")])+ record_transcript_episodes(root, _fold(root, path))+ (row,) = _rows(root, tier=TIER_TRANSCRIPT)++ assert row["birth_at"] == pytest.approx(+ time.mktime(time.strptime("2026-08-06 10:00:00", "%Y-%m-%d %H:%M:%S"))+ - time.timezone,+ abs=2,+ )+ assert row["tier"] == TIER_TRANSCRIPT+++def test_a_repeated_turn_later_in_a_session_is_not_mistaken_for_a_replay(tmp_path):+ """The replay guard has to be anchored, not "appears anywhere".++ Transcripts repeat short turns verbatim all the time ("Running the+ tests.", "Done."). An unanchored containment test reads the second one as+ a re-read of the first and drops it, losing real conversation. A replay+ starts where the conversation starts; a repeat does not.+ """+ root = _repo(tmp_path)+ first = _transcript(tmp_path, "s.jsonl", [_line("assistant", "Running the tests.")])+ record_transcript_episodes(root, _fold(root, first))++ # The next run reads only what was appended, and it opens with a turn+ # byte-identical to the one the body already starts with. Only the+ # timestamp separates this from a rewind.+ again = _transcript(+ tmp_path,+ "s.jsonl",+ [_line("assistant", "Running the tests.", ts="2026-08-06T11:00:00.000Z")],+ )+ record_transcript_episodes(root, _fold(root, again))++ (row,) = _rows(root, tier=TIER_TRANSCRIPT)+ assert row["body"].count("Running the tests.") == 2+++def test_the_truncation_label_survives_a_run_that_reads_nothing(tmp_path):+ """Truncation is a property of the stored body, not of the pass that saw it.++ Every long session eventually ends, and the run after that reads nothing.+ A flag carried from that pass would quietly retract the warning exactly+ when the body is at its longest.+ """+ root = _repo(tmp_path)+ path = _transcript(+ tmp_path, "s.jsonl", [_line("assistant", "x" * (MAX_BODY_BYTES * 2))]+ )+ record_transcript_episodes(root, _fold(root, path))+ (row,) = _rows(root, tier=TIER_TRANSCRIPT)+ assert "body truncated" in row["evidence"]++ quiet = TranscriptEpisodeRecorder(root)+ quiet.observe(path, iter(()))+ record_transcript_episodes(root, quiet)++ (row,) = _rows(root, tier=TIER_TRANSCRIPT)+ assert "body truncated" in row["evidence"]+++def test_a_listed_but_unread_transcript_keeps_its_episode(tmp_path):+ """A sweep that stops early must not read its own unfinished work as loss.++ ``note_present`` is what separates "this session exists" from "this run+ read it": the first is answerable from the directory listing, and it is the+ one deletion is allowed to depend on.+ """+ root = _repo(tmp_path)+ read = _transcript(tmp_path, "read.jsonl", [_line("user", "was read")])+ unread = _transcript(tmp_path, "unread.jsonl", [_line("user", "never reached", session="s2")])+ record_transcript_episodes(root, _fold(root, read, unread))+ assert len(_rows(root, tier=TIER_TRANSCRIPT)) == 2++ # A later, budget-limited run: both listed, only one read.+ partial = TranscriptEpisodeRecorder(root)+ partial.note_present([read, unread])+ for _ in partial.observe(read, iter(())):+ pass+ record_transcript_episodes(root, partial)++ assert len(_rows(root, tier=TIER_TRANSCRIPT)) == 2diff --git a/tests/unit/server/mcp/test_answer_episodes.py b/tests/unit/server/mcp/test_answer_episodes.pyindex 452be96a2..f3ba2a0aa 100644--- a/tests/unit/server/mcp/test_answer_episodes.py+++ b/tests/unit/server/mcp/test_answer_episodes.py@@ -22,6 +22,7 @@ import pytestfrom repowise.core.precedent.store import (TIER_GIT,TIER_STRUCTURAL,+ TIER_TRANSCRIPT,Episode,EpisodeStore,default_store_path,@@ -624,3 +625,62 @@ async def test_the_episode_is_served_on_both_paths_and_never_cached(assert provider.calls == 1, "second call must be served from cache"assert cached["_meta"]["cached"] is Trueassert cached["episodes"][0]["kind"] == "formatter_drift"+++# -- the tier gate -----------------------------------------------------------+#+# The store's third tier is per-machine, and the reader used to take whatever+# the store held. Reproduced against this repository's real store before the+# gate existed: with 56 of its 426 sessions recorded, the guard went silent on+# its own formatter reproduction and served a session instead.+++def _session_episode(subject: str, nodes: tuple[str, ...]) -> Episode:+ return Episode(+ tier=TIER_TRANSCRIPT,+ kind="session",+ subject=subject,+ body="user: should we reformat everything\nassistant: sure, run the formatter",+ evidence=f"session {subject[:8]}, 2026-08-01, touched {len(nodes)} files",+ nodes=nodes,+ # A session is dated, not committed. This is what makes it unsuppressable.+ birth_commit=None,+ )+++def test_a_transcript_episode_is_never_served(repo):+ root = repo+ _write(root, _session_episode("abcdef12", ("Makefile", "pyproject.toml")), born=1000.0)++ p = run(payload(), root)+ assert "episodes" not in p+++def test_a_transcript_episode_cannot_take_the_slot_from_a_shareable_one(repo):+ """The regression the gate exists for, in miniature.++ A session touches far more files than a fix commit, so it outranks one on+ the window's specificity sort; and with no birth commit it never reaches+ the git query, so it can never be suppressed. It wins the window and holds+ it — which is why the reader names its tiers instead of taking the store's.+ """+ root = repo+ _write(root, formatter_episode(_head(root)), born=1000.0)+ for i in range(_MAX_SCOPED_CANDIDATES + 2):+ _write(+ root,+ _session_episode(f"session{i:02d}", ("Makefile", "pyproject.toml")),+ born=2000.0 + i,+ )++ p = run(payload(), root)+ assert [e["tier"] for e in p["episodes"]] == [TIER_STRUCTURAL]+++def test_the_served_tiers_are_the_shareable_ones(repo):+ """Asserted on the payload, so a later reader cannot flip it by accident."""+ from repowise.core.precedent.store import SHAREABLE_TIERS+ from repowise.server.mcp_server.tool_answer.episodes import _SERVED_TIERS++ assert tuple(_SERVED_TIERS) == tuple(SHAREABLE_TIERS)+ assert TIER_TRANSCRIPT not in _SERVED_TIERSdiff --git a/tests/unit/sessions/test_session_decisions_e2e.py b/tests/unit/sessions/test_session_decisions_e2e.pyindex 30ae3c30d..eb5db1582 100644--- a/tests/unit/sessions/test_session_decisions_e2e.py+++ b/tests/unit/sessions/test_session_decisions_e2e.py@@ -233,3 +233,70 @@ def test_session_rank_sits_above_adr_and_below_cli():"""assert SOURCE_RANK["session"] == 8assert SOURCE_RANK["cli"] > SOURCE_RANK["session"] > SOURCE_RANK["adr"]+++# ---------------------------------------------------------------------------+# One read, two consumers+# ---------------------------------------------------------------------------+++async def test_the_transcript_read_serves_episodes_without_a_provider(tmp_path):+ """Keyless is the primary path, and this pass is where transcripts are read.++ Gating the read on a provider would leave a user with no API key no+ transcript supply at all, while the episode half needs no model. The+ structuring pass is what skips.+ """+ from repowise.core.precedent.store import TIER_TRANSCRIPT, EpisodeStore+ from repowise.core.precedent.store import default_store_path as episode_store_path++ repo_root = tmp_path / "repo"+ (repo_root / ".repowise").mkdir(parents=True)+ projects_root = tmp_path / "projects"+ _write_transcript(repo_root, projects_root, "one.jsonl", "sess-1", CORRECTION)++ decisions = await mine_session_decisions(+ repo_root, provider=None, projects_root=projects_root, now=100.0+ )++ assert decisions == [] # nothing can be structured without a model+ with EpisodeStore(episode_store_path(repo_root)) as store:+ (row,) = store.list_episodes(tier=TIER_TRANSCRIPT)+ assert CORRECTION in row["body"]+ assert row["subject"].endswith("one.jsonl")+++async def test_the_episode_write_leaves_decision_mining_unchanged(tmp_path):+ """The tee must not perturb the stream it rides.++ Measured on the real corpus as well: 426 transcripts produced 547 candidates+ with and without the recorder attached.+ """+ repo_root = tmp_path / "repo"+ (repo_root / ".repowise").mkdir(parents=True)+ projects_root = tmp_path / "projects"+ provider = FakeProvider()+ _write_transcript(repo_root, projects_root, "one.jsonl", "sess-1", CORRECTION)++ decisions = await mine_session_decisions(+ repo_root, provider=provider, projects_root=projects_root, now=100.0+ )++ (decision,) = decisions+ assert decision.source == "session"+ assert decision.source_quote == CORRECTION+++async def test_a_repo_with_no_transcripts_derives_nothing_and_deletes_nothing(tmp_path):+ """Rule 3a's test: the CI case must be degraded, never broken."""+ from repowise.core.precedent.store import default_store_path as episode_store_path++ repo_root = tmp_path / "repo"+ (repo_root / ".repowise").mkdir(parents=True)+ projects_root = tmp_path / "projects"++ decisions = await mine_session_decisions(+ repo_root, provider=None, projects_root=projects_root, now=100.0+ )+ assert decisions == []+ assert not episode_store_path(repo_root).exists()