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(core): mine durable decisions from agent session transcripts (#775)

Raghav Chamadiyabed0cbd28f2a
diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.md
index 3c8d29757..faac80593 100644
--- a/docs/CLI_REFERENCE.md
+++ b/docs/CLI_REFERENCE.md
@@ -127,6 +127,15 @@ plus the exported `knowledge-graph.json`. In docs mode it also regenerates the
affected wiki pages. Index-only updates carry forward the previously generated
layer names and node summaries, so no LLM call is ever made without docs mode.
+Docs-mode updates (and `init`) also mine local coding-agent session
+transcripts for durable decisions: user corrections, explicit choices with a
+stated reason, and failed approaches replaced by working ones. Candidates
+pass deterministic gates and a verbatim-quote grounding check; a decision
+observed in two or more sessions (or one direct user correction) is promoted
+into the decision records with `source: session`. Everything stays on your
+machine. Disable with `decisions.session_mining: false` in
+`.repowise/config.yaml` (see [CONFIG.md](CONFIG.md)).
+
If any best-effort step fails (git metadata, decisions, dead code, ...), the
run still exits 0 but lists the degraded steps in the completion panel (and in
the `done` event's `degraded` array with `--progress json`); the next update
diff --git a/docs/CONFIG.md b/docs/CONFIG.md
index cc57ceb96..2674902d4 100644
--- a/docs/CONFIG.md
+++ b/docs/CONFIG.md
@@ -181,6 +181,7 @@ stay enabled.
```yaml
decisions:
+ session_mining: true # mine agent-session transcripts (see below)
sources:
comment: false # LLM comment archaeology (top central files)
# inline_marker: false # WHY:/DECISION: markers
@@ -191,6 +192,19 @@ decisions:
# pr: false
```
+`session_mining` (default on) lets `repowise update` mine coding-agent
+session transcripts (Claude Code's `~/.claude/projects/`) for durable
+decisions: user corrections, explicit choices with a stated reason, and
+failed approaches replaced by working ones. Candidates pass deterministic
+gates first, then one batched LLM structuring call per update, and every
+produced field must quote the transcript verbatim or it is dropped. A
+decision observed in two or more sessions is promoted as `active` with
+`source: session`; a direct user correction promotes after one. Everything
+stays local: transcripts are read from your machine, staging lives in
+`.repowise/sessions/sessions.db`, and only the distilled decision text about
+the codebase is stored. Set `session_mining: false` to turn the whole
+pipeline off.
+
Dismissals are sticky: `repowise decision dismiss` keeps the record as a
`dismissed` tombstone, so reindexing never re-proposes the same decision, and
a confirmed (`active`) decision is never walked back to `proposed` by a
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/command.py b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
index 3dddf7324..2854df3da 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
@@ -792,6 +792,28 @@ def run_update(
if verbose:
console.print(f"[yellow]Decision re-scan skipped: {exc}[/yellow]")
+ # Session-sourced decisions: mine agent transcript lines appended since
+ # the last update, structure new candidates in one batched LLM pass, and
+ # collect the observation-qualified promotions. They ride the same
+ # decision upsert as the marker re-scan below. Everything stays local;
+ # `decisions.session_mining: false` in .repowise/config.yaml disables it.
+ session_decisions: list = []
+ try:
+ from repowise.core.sessions.miners.decisions import (
+ mine_session_decisions,
+ session_mining_enabled,
+ )
+
+ if session_mining_enabled(cfg):
+ session_decisions = run_async(mine_session_decisions(repo_path, provider=provider))
+ if session_decisions and verbose:
+ promoted_titles = {d.title for d in session_decisions}
+ console.print(f"Session decisions promoted: [green]{len(promoted_titles)}[/green]")
+ except Exception as exc:
+ degraded.append(f"Session decision mining: {exc}")
+ if verbose:
+ console.print(f"[yellow]Session decision mining skipped: {exc}[/yellow]")
+
# Count of decision records touched by evolution, surfaced in the panel.
decisions_evolved = 0
@@ -1047,7 +1069,7 @@ def run_update(
generated_pages=generated_pages,
file_diffs=file_diffs,
git_meta_map=git_meta_map,
- new_decision_markers=new_decision_markers,
+ new_decision_markers=[*new_decision_markers, *session_decisions],
decision_vector_store=decision_vector_store,
provider=provider,
partial_health_report=partial_health_report,
@@ -1134,7 +1156,7 @@ def run_update(
show_full_completion(
generated_pages=generated_pages,
decay_count=len(affected.decay_only),
- decisions_changed=len(new_decision_markers) + decisions_evolved,
+ decisions_changed=len(new_decision_markers) + len(session_decisions) + decisions_evolved,
provider=provider,
cost=cost_tracker.session_cost,
tokens=cost_tracker.session_tokens,
diff --git a/packages/core/src/repowise/core/analysis/decisions/provenance.py b/packages/core/src/repowise/core/analysis/decisions/provenance.py
index c608299b2..bc45168c0 100644
--- a/packages/core/src/repowise/core/analysis/decisions/provenance.py
+++ b/packages/core/src/repowise/core/analysis/decisions/provenance.py
@@ -38,6 +38,7 @@ __all__ = [
SOURCE_RANK: dict[str, int] = {
"cli": 9, # human-authored manual entry — most authoritative
"adr": 8, # architecture decision records (structured, intentional)
+ "session": 7, # mined from agent-session transcripts (user-corroborated)
"pr": 7, # PR / squash-merge body
"commit": 6, # individual commit message
"git_archaeology": 6, # alias for commit-mined decisions
diff --git a/packages/core/src/repowise/core/pipeline/phases/analysis.py b/packages/core/src/repowise/core/pipeline/phases/analysis.py
index ad975ff3b..1f4e8265b 100644
--- a/packages/core/src/repowise/core/pipeline/phases/analysis.py
+++ b/packages/core/src/repowise/core/pipeline/phases/analysis.py
@@ -263,7 +263,8 @@ async def _run_decision_extraction(
# Sources run concurrently inside extract_all(); drive a determinate
# bar so users see live progress. ``decisions.sources`` in the repo
# config can disable individual sources (#751).
- enabled = enabled_source_names(load_repo_config(repo_path))
+ repo_cfg = load_repo_config(repo_path)
+ enabled = enabled_source_names(repo_cfg)
if progress:
progress.on_phase_start("decisions", len(enabled))
@@ -284,6 +285,31 @@ async def _run_decision_extraction(
timeout=DECISION_EXTRACTION_TIMEOUT_SECS,
)
+ # Session-sourced decisions: a repo indexed for the first time on a
+ # machine with existing agent-session history gets them at init, not
+ # only from the first update. Appended after extract_all's substring
+ # gate on purpose: the miner enforces its own grounding contract, and
+ # re-gating without a source_text would wipe its verification. A
+ # server-side index has no transcript directory and no-ops here.
+ try:
+ from repowise.core.sessions.miners.decisions import (
+ mine_session_decisions,
+ session_mining_enabled,
+ )
+
+ if llm_client is not None and session_mining_enabled(repo_cfg):
+ session_decisions = await asyncio.wait_for(
+ mine_session_decisions(repo_path, provider=llm_client),
+ timeout=DECISION_EXTRACTION_TIMEOUT_SECS,
+ )
+ if session_decisions:
+ report.decisions.extend(session_decisions)
+ report.by_source["session"] = len(session_decisions)
+ report.total_found = len(report.decisions)
+ except Exception as exc:
+ if progress:
+ progress.on_message("warning", f"Session decision mining skipped: {exc}")
+
if progress:
bs = report.by_source
total_decisions = report.total_found
@@ -296,7 +322,8 @@ async def _run_decision_extraction(
f"{bs.get('pr', 0)} PR · "
f"{bs.get('git_archaeology', 0)} git · "
f"{bs.get('comment', 0)} comments · "
- f"{bs.get('readme_mining', 0)} docs",
+ f"{bs.get('readme_mining', 0)} docs · "
+ f"{bs.get('session', 0)} session",
)
_phase_done(progress, "decisions")
diff --git a/packages/core/src/repowise/core/sessions/README.md b/packages/core/src/repowise/core/sessions/README.md
index e7fe228ed..250c0b86b 100644
--- a/packages/core/src/repowise/core/sessions/README.md
+++ b/packages/core/src/repowise/core/sessions/README.md
@@ -15,6 +15,8 @@ own machine and never leave it.
| `adapters/base.py` | The `HarnessAdapter` contract: `discover()` + `normalize()`, with shared `iter_events()` built on top |
| `adapters/claude_code.py` | First adapter: `~/.claude/projects/<munged-cwd>/*.jsonl` |
| `cursor.py` | `CursorStore` (byte offset + mtime per file) and `iter_new_events` for incremental scans |
+| `staging.py` | `SessionStagingStore`: the `.repowise/sessions/sessions.db` sidecar (WAL) holding mined candidates, observation counts, and DB-backed cursors |
+| `miners/decisions.py` | Session-sourced decisions: deterministic gates over Events, one batched LLM structuring pass per update, observation-counted promotion |
## The contract
diff --git a/packages/core/src/repowise/core/sessions/miners/__init__.py b/packages/core/src/repowise/core/sessions/miners/__init__.py
new file mode 100644
index 000000000..805db8030
--- /dev/null
+++ b/packages/core/src/repowise/core/sessions/miners/__init__.py
@@ -0,0 +1,7 @@
+"""Feature miners over the normalized session-event stream.
+
+Each miner is a consumer of :class:`repowise.core.sessions.Event`; none of
+them parse transcripts themselves. Import miners directly (they pull in
+their feature's dependencies, which the base ``core.sessions`` package
+deliberately does not).
+"""
diff --git a/packages/core/src/repowise/core/sessions/miners/decisions.py b/packages/core/src/repowise/core/sessions/miners/decisions.py
new file mode 100644
index 000000000..12d24b791
--- /dev/null
+++ b/packages/core/src/repowise/core/sessions/miners/decisions.py
@@ -0,0 +1,694 @@
+"""Session-sourced decisions: mine durable choices out of agent transcripts.
+
+Transcripts are the highest-grade decision source there is: "no, don't use
+approach A, it broke prod, use B" is a real decision with real rationale, and
+without this miner it evaporates when the session ends. This module turns
+those moments into ``decision_records`` rows via three stages:
+
+1. **Deterministic gates** (:func:`mine_events`) over the normalized
+ :class:`~repowise.core.sessions.Event` stream, no LLM involved:
+
+ - *user correction*: an interrupt with guidance, or a pushback-leading
+ user message ("no, ...", "don't ...", "instead ...");
+ - *explicit choice*: a sentence carrying both a decision verb and a
+ causal cue (the :data:`CAUSAL_MARKERS` vocabulary) near file-touching
+ tool activity;
+ - *dead end*: repeated failures of one command/target followed by success
+ with a different one (the delta is the lesson).
+
+ Each candidate carries verbatim transcript quotes plus the files in play
+ from surrounding tool activity.
+
+2. **One batched LLM structuring pass** per ``repowise update``
+ (config-gated ``decisions.session_mining``, default on): candidates to
+ ``{title, decision, rationale, affected_files, source_quote}``. Every
+ produced field is then grounded against the verbatim quotes with the
+ shared :func:`~repowise.core.analysis.decisions.provenance.verify_quote`
+ logic (see :func:`_gate_structured`), so a fluent-but-invented rationale
+ never becomes institutional memory.
+
+3. **Observation-counted promotion** through the staging sidecar
+ (:class:`~repowise.core.sessions.staging.SessionStagingStore`): a decision
+ observed in 2+ distinct sessions promotes to ``active`` with
+ ``source="session"``; a user correction promotes on one observation.
+ Promoted decisions ride the normal ``bulk_upsert_decisions`` path, so
+ semantic dedup, evidence rows, node links, get_why, and the CLAUDE.md
+ Standing-decisions block all come for free.
+
+Privacy: transcripts never leave the machine. Mining is local and the only
+thing stored is distilled decision text about the codebase, with verbatim
+quotes as evidence. Kill switch: ``decisions.session_mining: false`` in
+``.repowise/config.yaml``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections import deque
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import structlog
+
+from repowise.core.analysis.decisions.extractor import ExtractedDecision
+from repowise.core.analysis.decisions.provenance import (
+ compute_confidence,
+ rank_for_source,
+ verify_quote,
+)
+from repowise.core.analysis.decisions.rationale_comments import CAUSAL_MARKERS
+from repowise.core.distill.corrections import command_anchor
+from repowise.core.sessions import ClaudeCodeAdapter, Event
+from repowise.core.sessions.cursor import iter_new_events
+from repowise.core.sessions.staging import SessionStagingStore
+
+logger = structlog.get_logger(__name__)
+
+__all__ = [
+ "SessionCandidate",
+ "mine_events",
+ "mine_session_decisions",
+ "session_mining_enabled",
+]
+
+# ---------------------------------------------------------------------------
+# Gate vocabularies, precision-first on purpose. A missed decision costs one
+# session of memory; a false one pollutes the record for every future session.
+# ---------------------------------------------------------------------------
+
+#: A user message opening with one of these reads as pushback on what the
+#: agent just did or proposed. Matched at the start of the message only.
+PUSHBACK_LEADS: tuple[str, ...] = (
+ "no,",
+ "no.",
+ "no ",
+ "nope",
+ "don't",
+ "dont ",
+ "do not",
+ "stop ",
+ "stop.",
+ "wait",
+ "not like that",
+ "that's wrong",
+ "thats wrong",
+ "that is wrong",
+ "undo",
+ "revert",
+ "instead",
+ "never ",
+ "actually,",
+ "actually ",
+)
+
+#: A sentence needs one of these to read as a choice being made (paired with
+#: a :data:`CAUSAL_MARKERS` cue for the stated reason). Word-bounded so e.g.
+#: "beca**use** it" never reads as the verb "use". Deliberately excludes
+#: "instead of" / "rather than": those are already causal cues, and letting
+#: one phrase satisfy both conditions turned every narrated trade-off in
+#: assistant prose into a candidate (dogfood: 796 hits, mostly noise).
+DECISION_VERB_RE = re.compile(
+ r"\b(?:use|using|went with|go(?:ing)? with|stick with|switch(?:ed)? to|chose"
+ r"|decided|always|never|must)\b|decision:"
+)
+
+#: Consecutive failures of one anchor before it counts as a dead end.
+DEAD_END_FAILURES = 3
+#: Tool events after the failure streak within which the successful
+#: different-anchor call must land.
+_DEAD_END_LOOKAHEAD = 8
+
+#: Tool events after a candidate during which touched files still attach to
+#: it (a correction is usually followed by the agent acting on it).
+_FORWARD_FILE_EVENTS = 10
+#: Trailing tool-touched files kept as "files in play" context.
+_TRAILING_FILES = 8
+
+_QUOTE_CAP = 600
+_MAX_QUOTES_PER_EVENT = 2
+
+_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+")
+
+
+@dataclass
+class SessionCandidate:
+ """One gate hit: a moment where a durable decision may have been made."""
+
+ kind: str # user_correction | explicit_choice | dead_end
+ quotes: list[str]
+ files: list[str] = field(default_factory=list)
+ session_id: str | None = None
+ ts: float | None = None
+
+ @property
+ def hash(self) -> str:
+ """Content identity for staging dedup (kind + normalized quotes)."""
+ norm = " ".join(" ".join(q.lower().split()) for q in self.quotes)
+ return hashlib.sha256(f"{self.kind}|{norm}".encode()).hexdigest()[:16]
+
+
+# ---------------------------------------------------------------------------
+# Stage 1: deterministic gates over one session's event stream
+# ---------------------------------------------------------------------------
+
+
+def _clip(text: str, cap: int = _QUOTE_CAP) -> str:
+ text = text.strip()
+ 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
+
+ lines = [ln for ln in text.splitlines() if INTERRUPT_MARKER not in ln]
+ 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:
+ guidance = _interrupt_guidance(event.text)
+ return _clip(guidance) if len(guidance) >= 8 else None
+ low = event.text.strip().lower()
+ if len(low) >= 12 and low.startswith(PUSHBACK_LEADS):
+ return _clip(event.text)
+ return None
+
+
+def _choice_sentences(text: str) -> list[str]:
+ """Sentences that state a choice and its reason, verbatim."""
+ out: list[str] = []
+ for sentence in _SENTENCE_SPLIT_RE.split(text):
+ sentence = sentence.strip()
+ if not 30 <= len(sentence) <= 400:
+ continue
+ low = sentence.lower()
+ if DECISION_VERB_RE.search(low) and any(m in low for m in CAUSAL_MARKERS):
+ out.append(sentence)
+ if len(out) == _MAX_QUOTES_PER_EVENT:
+ break
+ return out
+
+
+def _tool_failure(payload: Any, is_error: bool) -> str | None:
+ """The failure text when this result records one, else None."""
+ if isinstance(payload, str) and _EXIT_CODE_RE.match(payload):
+ return payload
+ if is_error and isinstance(payload, str):
+ return payload
+ return None
+
+
+def _result_anchor(name: str, use_input: dict[str, Any]) -> str:
+ """Identity a retried attempt shares: command anchor, or tool + file."""
+ command = use_input.get("command")
+ if isinstance(command, str) and command.strip():
+ return command_anchor(command)
+ 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()
+ return f"{name}:{basename}"
+ return name.lower()
+
+
+def mine_events(events: Iterable[Event], repo_prefix: str) -> list[SessionCandidate]:
+ """Run the deterministic candidate gates over one session's events.
+
+ *repo_prefix* is the lowercased resolved repo root; only events whose
+ ``cwd`` sits inside it count (same scoping as the distill miners). Pure
+ and streaming: state is bounded regardless of transcript size.
+ """
+ candidates: list[SessionCandidate] = []
+ trailing_files: deque[str] = deque(maxlen=_TRAILING_FILES)
+ #: Candidates still collecting forward files, with their remaining budget.
+ open_candidates: list[list[Any]] = [] # [candidate, remaining_tool_events]
+ #: tool_use id -> (tool name, input) awaiting its result.
+ pending: dict[str, tuple[str, dict[str, Any]]] = {}
+ #: (anchor, consecutive failure count, last failure text, last input repr)
+ streak: list[Any] = ["", 0, "", ""]
+ #: An anchor that just hit the failure threshold, awaiting the pivot.
+ open_dead_end: list[Any] | None = None # [anchor, error, attempt, budget]
+
+ def _add(candidate: SessionCandidate) -> None:
+ candidates.append(candidate)
+ open_candidates.append([candidate, _FORWARD_FILE_EVENTS])
+
+ for event in events:
+ cwd = (event.cwd or "").lower().rstrip("\\/")
+ if cwd and not cwd.startswith(repo_prefix):
+ continue
+
+ if event.kind == "assistant" and event.tool_uses:
+ files = _event_files(event)
+ for f in files:
+ trailing_files.append(f)
+ for entry in open_candidates:
+ entry[0].files.extend(f for f in files if f not in entry[0].files)
+ entry[1] -= 1
+ open_candidates = [e for e in open_candidates if e[1] > 0]
+ for use in event.tool_uses:
+ pending[use.id] = (use.name, use.input)
+ # Results normally arrive within a couple of events; anything
+ # older is an orphan (cancelled call) and must not accumulate.
+ while len(pending) > 200:
+ pending.pop(next(iter(pending)))
+
+ if event.tool_results:
+ for result in event.tool_results:
+ record = pending.pop(result.tool_use_id, None)
+ if record is None:
+ continue
+ name, use_input = record
+ anchor = _result_anchor(name, use_input)
+ failure = _tool_failure(result.payload, result.is_error)
+ if failure is not None:
+ if streak[0] == anchor:
+ streak[1] += 1
+ else:
+ streak[:] = [anchor, 1, "", ""]
+ streak[2] = failure
+ command = use_input.get("command")
+ streak[3] = (
+ command
+ if isinstance(command, str)
+ else f"{name} {json.dumps(use_input, ensure_ascii=False)}"
+ )
+ if streak[1] >= DEAD_END_FAILURES:
+ open_dead_end = [anchor, streak[2], streak[3], _DEAD_END_LOOKAHEAD]
+ else:
+ if open_dead_end is not None and anchor != open_dead_end[0]:
+ attempt = _clip(str(open_dead_end[2]), 300)
+ error = _clip(
+ str(open_dead_end[1]).splitlines()[0] if open_dead_end[1] else "", 300
+ )
+ pivot_command = use_input.get("command")
+ pivot = _clip(
+ pivot_command
+ if isinstance(pivot_command, str)
+ else f"{name} {json.dumps(use_input, ensure_ascii=False)}",
+ 300,
+ )
+ _add(
+ SessionCandidate(
+ kind="dead_end",
+ quotes=[q for q in (attempt, error, pivot) if q],
+ files=list(dict.fromkeys(trailing_files)),
+ session_id=event.session_id,
+ ts=event.ts,
+ )
+ )
+ open_dead_end = None
+ if streak[0] == anchor or (
+ open_dead_end is not None and anchor == open_dead_end[0]
+ ):
+ # It worked eventually: a retry loop, not a dead end.
+ streak[:] = ["", 0, "", ""]
+ open_dead_end = None
+ if open_dead_end is not None:
+ open_dead_end[3] -= 1
+ if open_dead_end[3] <= 0:
+ open_dead_end = None
+ continue
+
+ if _is_prose_user_text(event):
+ quote = _correction_quote(event)
+ if quote is not None:
+ _add(
+ SessionCandidate(
+ kind="user_correction",
+ quotes=[quote],
+ files=list(dict.fromkeys(trailing_files)),
+ session_id=event.session_id,
+ ts=event.ts,
+ )
+ )
+ continue
+
+ # 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):
+ continue
+ if event.kind == "assistant" and event.sidechain:
+ continue
+ if event.kind not in ("user", "assistant"):
+ continue
+ sentences = _choice_sentences(event.text)
+ if sentences:
+ _add(
+ SessionCandidate(
+ kind="explicit_choice",
+ quotes=[_clip(s) for s in sentences],
+ files=list(dict.fromkeys(trailing_files)),
+ session_id=event.session_id,
+ ts=event.ts,
+ )
+ )
+
+ # A choice with no code in play is a conversation, not a decision record.
+ return [c for c in candidates if c.kind != "explicit_choice" or c.files]
+
+
+# ---------------------------------------------------------------------------
+# Stage 2: one batched LLM structuring pass, substring-gated
+# ---------------------------------------------------------------------------
+
+_SYSTEM_PROMPT = (
+ "You are an architectural decision extractor. You extract durable, "
+ "codebase-level decisions from coding-agent session transcripts. "
+ "Return only valid JSON. Never invent rationale not present in the source."
+)
+
+SESSION_MINING_PROMPT = """\
+Below are excerpts from coding-agent sessions in one repository. Each \
+candidate is a moment where a durable decision about this codebase may have \
+been made: the user correcting the agent, an explicit choice with a stated \
+reason, or a failed approach replaced by a working one.
+
+{candidates_block}
+
+For each candidate that records a DURABLE decision or rule (something every \
+future session should follow), return a JSON object:
+{{
+ "candidate": <the candidate number>,
+ "title": "short imperative title",
+ "decision": "what to do (or avoid), grounded in the excerpt",
+ "rationale": "why, only if the excerpt states it",
+ "affected_files": ["subset of the candidate's files this governs"],
+ "source_quote": "one sentence copied verbatim from the excerpt"
+}}
+
+Skip candidates that are one-off task instructions, session-specific \
+guidance, questions, or venting. Return a JSON array; [] if none qualify.
+"""
+
+#: Cap on raw candidates structured per update; the remainder stays staged
+#: and is picked up by the next update's pass.
+MAX_STRUCTURED_PER_UPDATE = 60
+_LLM_CHUNK = 12
+
+# This miner needs user prose, assistant prose, tool uses, and results; in
+# Claude Code all of them are "user"/"assistant" entries. Both compact and
+# spaced JSON spellings are matched; what this skips is the fat non-dialog
+# lines (file-history snapshots, queue operations, system hooks).
+_PREFILTER_TOKENS = (
+ '"type":"user"',
+ '"type": "user"',
+ '"type":"assistant"',
+ '"type": "assistant"',
+)
+
+
+def _prefilter(raw: str) -> bool:
+ return any(tok in raw for tok in _PREFILTER_TOKENS)
+
+
+def session_mining_enabled(repo_config: dict[str, Any] | None) -> bool:
+ """Resolve the ``decisions.session_mining`` config gate (default on)."""
+ cfg = repo_config or {}
+ decisions_cfg = cfg.get("decisions") or {}
+ if not isinstance(decisions_cfg, dict):
+ return True
+ return decisions_cfg.get("session_mining", True) is not False
+
+
+def _candidates_block(raws: list[dict[str, Any]]) -> str:
+ parts: list[str] = []
+ for i, raw in enumerate(raws):
+ files = ", ".join(raw["files"][:8]) or "(none recorded)"
+ quotes = "\n".join(raw["quotes"])
+ parts.append(
+ f"--- Candidate {i} ({raw['kind']}) ---\n"
+ f"Files in play: {files}\n"
+ f"Transcript excerpt:\n{quotes}\n"
+ )
+ return "\n".join(parts)
+
+
+def _parse_structured(content: str) -> list[dict[str, Any]]:
+ """Parse the LLM response into candidate-indexed objects (tolerant)."""
+ content = content.strip()
+ if content.startswith("```"):
+ content = "\n".join(
+ line for line in content.splitlines() if not line.strip().startswith("```")
+ )
+ try:
+ data = json.loads(content)
+ except json.JSONDecodeError:
+ match = re.search(r"\[.*\]", content, re.DOTALL)
+ if not match:
+ return []
+ try:
+ data = json.loads(match.group())
+ except json.JSONDecodeError:
+ return []
+ if isinstance(data, dict):
+ data = [data]
+ return [item for item in data if isinstance(item, dict)]
+
+
+_PUNCT_RE = re.compile(r"[^\w\s]")
+
+
+def _gate_structured(item: dict[str, Any], raw: dict[str, Any]) -> dict[str, Any] | None:
+ """Ground one structured candidate in its verbatim transcript quotes.
+
+ The product guarantee, adapted to this source: ``source_quote`` must
+ verify (exact or fuzzy) against the excerpt, since that quote is the evidence
+ a human reviews. The ``decision`` is by design a normalization of
+ informal transcript language ("dont" becomes "do not"), so it is held to
+ a punctuation-stripped content-word overlap with the excerpt rather than
+ the full 0.6 token gate, and a ``rationale`` that fails the same check
+ is dropped (never invented "why") without killing the candidate.
+ Returns the gated dict, or None when the candidate is rejected.
+ """
+ title = str(item.get("title") or "").strip()
+ decision = str(item.get("decision") or "").strip()
+ if not title or not decision:
+ return None
+ source_text = "\n".join(raw["quotes"])
+ verification = verify_quote(str(item.get("source_quote") or ""), source_text)
+ if verification == "unverified":
+ return None
+ plain_source = _PUNCT_RE.sub(" ", source_text)
+ plain_decision = _PUNCT_RE.sub(" ", decision)
+ if verify_quote(plain_decision, plain_source, fuzzy_threshold=0.3) == "unverified":
+ return None # a wild claim riding a valid quote is still rejected
+ rationale = str(item.get("rationale") or "").strip()
+ if rationale:
+ plain_rationale = _PUNCT_RE.sub(" ", rationale)
+ if verify_quote(plain_rationale, plain_source, fuzzy_threshold=0.5) == "unverified":
+ rationale = ""
+ claimed = item.get("affected_files")
+ files = [f for f in claimed if f in raw["files"]] if isinstance(claimed, list) else []
+ if not files and raw["kind"] != "user_correction":
+ # A choice/dead end is about the code in play; a correction with no
+ # named files is a repo-wide rule, and linking it to whatever files
+ # happened to be open would govern the wrong code (dogfood: the
+ # em-dash rule pinned to an unrelated docs file).
+ files = raw["files"]
+ return {
+ "title": title,
+ "decision": decision,
+ "rationale": rationale,
+ "source_quote": str(item.get("source_quote") or "").strip(),
+ "verification": verification,
+ "affected_files": files,
+ }
+
+
+# ---------------------------------------------------------------------------
+# Stage 3: promotion into decision_records dicts
+# ---------------------------------------------------------------------------
+
+_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.
+
+ One member per observing session (capped) so each session becomes its own
+ evidence row via the ``bulk_upsert_decisions`` accretion path. The first
+ promotion lands ``active``; later observation-driven re-emissions land
+ ``proposed``, which adds evidence but can never overwrite a status a
+ human (or the evolution judge) set deliberately.
+ """
+ structured = row["structured"]
+ status = "active" if row["first_promotion"] else "proposed"
+ files = _relative_files(structured.get("affected_files") or row["files"], repo_root)
+ modules = sorted({f.rsplit("/", 1)[0] for f in files if "/" in f})
+ confidence = compute_confidence(
+ rank_for_source("session"),
+ row["observations"],
+ structured.get("verification", "unverified"),
+ )
+ sessions = row["sessions"][-_MAX_EVIDENCE_SESSIONS:] or [None]
+ return [
+ ExtractedDecision(
+ title=row["title"],
+ decision=structured.get("decision", ""),
+ rationale=structured.get("rationale", ""),
+ affected_files=files,
+ affected_modules=modules,
+ source="session",
+ evidence_commits=[sid] if sid else [],
+ confidence=confidence,
+ status=status,
+ source_quote=structured.get("source_quote", ""),
+ verification=structured.get("verification", "unverified"),
+ )
+ for sid in sessions
+ ]
+
+
+# ---------------------------------------------------------------------------
+# Orchestration: one call per `repowise update`
+# ---------------------------------------------------------------------------
+
+
+async def mine_session_decisions(
+ repo_path: Path,
+ *,
+ provider: Any,
+ 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.
+
+ Reads only transcript lines appended since the last run (cursors live in
+ the staging DB and only advance in the same commit that stages what was
+ read), runs the batched LLM pass over pending candidates, and returns the
+ decisions that qualify for promotion, ready for the caller's normal
+ ``bulk_upsert_decisions`` path. Best-effort at the file level; a failed
+ LLM call leaves candidates staged for the next update.
+ """
+ repo_root = Path(repo_path).resolve()
+ repo_prefix = str(repo_root).lower().rstrip("\\/")
+ adapter = ClaudeCodeAdapter()
+
+ 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):
+ try:
+ events = iter_new_events(adapter, path, store.cursors, prefilter=_prefilter)
+ for candidate in mine_events(events, repo_prefix):
+ if store.add_raw(
+ hash_=candidate.hash,
+ kind=candidate.kind,
+ quotes=candidate.quotes,
+ files=candidate.files,
+ session_id=candidate.session_id,
+ now=now,
+ ):
+ staged += 1
+ except OSError:
+ continue
+ store.prune(now=now)
+ store.cursors.save() # commits the staged raws atomically with the cursors
+
+ # One batched structuring pass over whatever is pending (this run's
+ # hits plus any backlog a previous failed call left behind).
+ pending = store.pending_raws(max_structured)
+ structured_count = 0
+ processed = 0
+ for start in range(0, len(pending), _LLM_CHUNK):
+ chunk = pending[start : start + _LLM_CHUNK]
+ prompt = SESSION_MINING_PROMPT.format(candidates_block=_candidates_block(chunk))
+ try:
+ response = await provider.generate(
+ _SYSTEM_PROMPT, prompt, max_tokens=2000, temperature=0.2
+ )
+ except Exception as exc:
+ logger.warning("session_mining.llm_failed", error=str(exc))
+ break # pending raws stay staged; next update retries
+ processed += len(chunk)
+ by_index = {}
+ for item in _parse_structured(response.content):
+ idx = item.get("candidate")
+ if isinstance(idx, int) and 0 <= idx < len(chunk):
+ by_index[idx] = item
+ for i, raw in enumerate(chunk):
+ gated = _gate_structured(by_index[i], raw) if i in by_index else None
+ if gated is None:
+ store.mark_raw_rejected(raw["hash"])
+ continue
+ store.upsert_structured(
+ raw["hash"],
+ kind=raw["kind"],
+ title=gated["title"],
+ structured=gated,
+ quotes=raw["quotes"],
+ files=gated["affected_files"],
+ session_id=raw["session_id"],
+ now=now,
+ )
+ structured_count += 1
+ store.commit()
+
+ # Promotion: observation-qualified decisions, ready for upsert.
+ decisions: list[ExtractedDecision] = []
+ for row in store.promotable():
+ decisions.extend(_promotion_decisions(row, repo_root))
+ store.mark_emitted(row["key"], observations=row["observations"], now=now)
+ store.commit()
+
+ logger.info(
+ "session_mining.done",
+ staged=staged,
+ structured=structured_count,
+ pending_backlog=max(0, len(pending) - processed),
+ promoted=len(decisions),
+ )
+ return decisions
+ finally:
+ store.close()
diff --git a/packages/core/src/repowise/core/sessions/staging.py b/packages/core/src/repowise/core/sessions/staging.py
new file mode 100644
index 000000000..48de53621
--- /dev/null
+++ b/packages/core/src/repowise/core/sessions/staging.py
@@ -0,0 +1,343 @@
+"""Staging sidecar for session-mined decision candidates.
+
+Candidates mined from agent transcripts live in their own WAL SQLite sidecar
+(``.repowise/sessions/sessions.db``, the OmissionStore pattern from
+:mod:`repowise.core.distill.store`) rather than wiki.db, so update-time writes
+never contend with indexing. The sidecar holds three things:
+
+- ``raw_candidates``: deterministic-gate output awaiting the batched LLM
+ structuring pass. A raw row survives an LLM failure, so nothing mined is
+ ever lost to a flaky call; it is retried on the next update.
+- ``decisions``: structured candidates keyed by normalized title, carrying
+ the distinct sessions that observed them (the promotion counter) and the
+ emit bookkeeping that keeps promotion idempotent across updates.
+- ``cursors``: per-transcript byte offsets, the DB-backed twin of
+ :class:`repowise.core.sessions.cursor.CursorStore` (same ``get`` /
+ ``advance`` / ``save`` surface, so :func:`iter_new_events` consumes it
+ unchanged). Living in the same database means a cursor only advances in
+ the same commit that stages what was read under it.
+
+Everything is local; transcripts and candidates never leave the machine.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import sqlite3
+import time
+from pathlib import Path
+from typing import Any
+
+SESSIONS_DIRNAME = "sessions"
+SESSIONS_DB_FILENAME = "sessions.db"
+
+#: Raw candidates older than this that were never structured are dropped:
+#: they will not gain observations sitting in the queue, and an unbounded
+#: backlog would grow the batched LLM pass forever.
+RAW_TTL_DAYS = 90.0
+
+#: Cap on the distinct session ids tracked per structured decision. Two is
+#: enough to promote; beyond a handful the extra ids only pad evidence.
+_MAX_SESSIONS_TRACKED = 20
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS raw_candidates (
+ hash TEXT PRIMARY KEY,
+ kind TEXT NOT NULL,
+ quotes TEXT NOT NULL,
+ files TEXT NOT NULL,
+ session_id TEXT,
+ created_at REAL NOT NULL,
+ structured_key TEXT
+);
+CREATE TABLE IF NOT EXISTS decisions (
+ key TEXT PRIMARY KEY,
+ kind TEXT NOT NULL,
+ title TEXT NOT NULL,
+ structured TEXT NOT NULL,
+ sessions TEXT NOT NULL,
+ quotes TEXT NOT NULL,
+ files TEXT NOT NULL,
+ first_seen REAL NOT NULL,
+ last_seen REAL NOT NULL,
+ promoted_at REAL,
+ emitted_sessions INTEGER NOT NULL DEFAULT 0
+);
+CREATE TABLE IF NOT EXISTS cursors (
+ file TEXT PRIMARY KEY,
+ offset INTEGER NOT NULL,
+ mtime REAL NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_raw_pending ON raw_candidates(structured_key)
+ WHERE structured_key IS NULL;
+"""
+
+_NON_ALNUM_RE = re.compile(r"[^a-z0-9\s]")
+_WS_RE = re.compile(r"\s+")
+
+
+def normalize_title(title: str) -> str:
+ """Normalize a title for cross-session dedup (mirrors the crud dedup key)."""
+ t = title.lower().strip()
+ t = _NON_ALNUM_RE.sub("", t)
+ return _WS_RE.sub(" ", t)
+
+
+def title_key(title: str) -> str:
+ """Stable 16-hex staging key for a decision title."""
+ return hashlib.sha256(normalize_title(title).encode("utf-8")).hexdigest()[:16]
+
+
+def default_store_path(repo_path: Path) -> Path:
+ return Path(repo_path) / ".repowise" / SESSIONS_DIRNAME / SESSIONS_DB_FILENAME
+
+
+class _DbCursors:
+ """DB-backed transcript cursors with the :class:`CursorStore` surface.
+
+ Mutation is in memory; :meth:`save` writes the rows on the shared
+ connection and commits, so a cursor never lands without whatever the
+ caller staged before calling it.
+ """
+
+ def __init__(self, conn: sqlite3.Connection) -> None:
+ self._conn = conn
+ self._cursors: dict[str, dict[str, Any]] = {
+ row[0]: {"offset": row[1], "mtime": row[2]}
+ for row in conn.execute("SELECT file, offset, mtime FROM cursors")
+ }
+
+ def get(self, file: Path) -> dict[str, Any] | None:
+ return self._cursors.get(str(file))
+
+ def advance(self, file: Path, *, offset: int, mtime: float) -> None:
+ self._cursors[str(file)] = {"offset": offset, "mtime": mtime}
+
+ def save(self) -> None:
+ self._conn.executemany(
+ "INSERT INTO cursors (file, offset, mtime) VALUES (?, ?, ?) "
+ "ON CONFLICT(file) DO UPDATE SET offset = excluded.offset, mtime = excluded.mtime",
+ [(f, c["offset"], c["mtime"]) for f, c in self._cursors.items()],
+ )
+ self._conn.commit()
+
+
+class SessionStagingStore:
+ """Synchronous SQLite staging store for session-mined decisions.
+
+ Synchronous on purpose, like the OmissionStore: the caller is a CLI
+ update step where an asyncio loop around SQLite is pure overhead.
+ """
+
+ def __init__(self, db_path: Path) -> None:
+ self.db_path = db_path
+ db_path.parent.mkdir(parents=True, exist_ok=True)
+ self._conn = sqlite3.connect(db_path)
+ self._conn.execute("PRAGMA journal_mode=WAL")
+ self._conn.execute("PRAGMA synchronous=NORMAL")
+ self._conn.execute("PRAGMA busy_timeout=5000")
+ self._conn.executescript(_SCHEMA)
+ self._conn.commit()
+ self.cursors = _DbCursors(self._conn)
+
+ @classmethod
+ def open_default(cls, repo_path: Path) -> SessionStagingStore:
+ return cls(default_store_path(repo_path))
+
+ # -- raw candidates ------------------------------------------------------
+
+ def add_raw(
+ self,
+ *,
+ hash_: str,
+ kind: str,
+ quotes: list[str],
+ files: list[str],
+ session_id: str | None,
+ now: float | None = None,
+ ) -> bool:
+ """Stage one gate hit; idempotent per content hash. True when new."""
+ cur = self._conn.execute(
+ "INSERT OR IGNORE INTO raw_candidates "
+ "(hash, kind, quotes, files, session_id, created_at) VALUES (?, ?, ?, ?, ?, ?)",
+ (
+ hash_,
+ kind,
+ json.dumps(quotes),
+ json.dumps(files),
+ session_id,
+ now if now is not None else time.time(),
+ ),
+ )
+ return cur.rowcount > 0
+
+ def pending_raws(self, limit: int) -> list[dict[str, Any]]:
+ """Raw candidates awaiting the LLM structuring pass.
+
+ User corrections first (they carry the one-observation fast path),
+ then dead ends, then choices; oldest first within a kind, so a
+ cold-start backlog drains its highest-value candidates first.
+ """
+ rows = self._conn.execute(
+ "SELECT hash, kind, quotes, files, session_id FROM raw_candidates "
+ "WHERE structured_key IS NULL "
+ "ORDER BY CASE kind WHEN 'user_correction' THEN 0 WHEN 'dead_end' THEN 1 ELSE 2 END, "
+ "created_at ASC LIMIT ?",
+ (limit,),
+ ).fetchall()
+ return [
+ {
+ "hash": r[0],
+ "kind": r[1],
+ "quotes": json.loads(r[2]),
+ "files": json.loads(r[3]),
+ "session_id": r[4],
+ }
+ for r in rows
+ ]
+
+ def mark_raw_rejected(self, hash_: str) -> None:
+ """The LLM (or the substring gate) ruled this raw out; never retry it."""
+ self._conn.execute("UPDATE raw_candidates SET structured_key = '' WHERE hash = ?", (hash_,))
+
+ # -- structured decisions --------------------------------------------------
+
+ def upsert_structured(
+ self,
+ raw_hash: str,
+ *,
+ kind: str,
+ title: str,
+ structured: dict[str, Any],
+ quotes: list[str],
+ files: list[str],
+ session_id: str | None,
+ now: float | None = None,
+ ) -> str:
+ """Fold one structured candidate into its normalized-title row.
+
+ Merges the observing session id, quotes, and files into the existing
+ row (a ``user_correction`` kind is sticky: it carries the fast
+ promotion path, so a later ``explicit_choice`` observation never
+ weakens it) and links the raw row so it is not re-structured.
+ Returns the decision key.
+ """
+ ts = now if now is not None else time.time()
+ key = title_key(title)
+ row = self._conn.execute(
+ "SELECT kind, sessions, quotes, files FROM decisions WHERE key = ?", (key,)
+ ).fetchone()
+ if row is None:
+ sessions = [session_id] if session_id else []
+ self._conn.execute(
+ "INSERT INTO decisions "
+ "(key, kind, title, structured, sessions, quotes, files, first_seen, last_seen) "
+ "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+ (
+ key,
+ kind,
+ title,
+ json.dumps(structured),
+ json.dumps(sessions),
+ json.dumps(quotes),
+ json.dumps(files),
+ ts,
+ ts,
+ ),
+ )
+ else:
+ merged_kind = "user_correction" if "user_correction" in (kind, row[0]) else row[0]
+ sessions = json.loads(row[1])
+ if session_id and session_id not in sessions:
+ sessions = [*sessions, session_id][:_MAX_SESSIONS_TRACKED]
+ merged_quotes = list(dict.fromkeys(json.loads(row[2]) + quotes))[:_MAX_SESSIONS_TRACKED]
+ merged_files = list(dict.fromkeys(json.loads(row[3]) + files))
+ self._conn.execute(
+ "UPDATE decisions SET kind = ?, structured = ?, sessions = ?, quotes = ?, "
+ "files = ?, last_seen = ? WHERE key = ?",
+ (
+ merged_kind,
+ json.dumps(structured),
+ json.dumps(sessions),
+ json.dumps(merged_quotes),
+ json.dumps(merged_files),
+ ts,
+ key,
+ ),
+ )
+ self._conn.execute(
+ "UPDATE raw_candidates SET structured_key = ? WHERE hash = ?", (key, raw_hash)
+ )
+ return key
+
+ # -- promotion ---------------------------------------------------------
+
+ def promotable(self) -> list[dict[str, Any]]:
+ """Decisions that qualify for (re-)emission into decision_records.
+
+ Qualifies when 2+ distinct sessions observed it, or on a single
+ observation for a user correction (the fast path). Emits only when
+ there is something new to say: never promoted before, or observed by
+ more sessions than the last emission. A promoted decision is therefore not
+ re-upserted (and can never resurrect a human status change) on every
+ update.
+ """
+ rows = self._conn.execute(
+ "SELECT key, kind, title, structured, sessions, quotes, files, "
+ "promoted_at, emitted_sessions FROM decisions"
+ ).fetchall()
+ out: list[dict[str, Any]] = []
+ for r in rows:
+ sessions = json.loads(r[4])
+ observations = max(1, len(sessions))
+ qualifies = observations >= 2 or r[1] == "user_correction"
+ if not qualifies:
+ continue
+ first_promotion = r[7] is None
+ if not first_promotion and observations <= r[8]:
+ continue
+ out.append(
+ {
+ "key": r[0],
+ "kind": r[1],
+ "title": r[2],
+ "structured": json.loads(r[3]),
+ "sessions": sessions,
+ "quotes": json.loads(r[5]),
+ "files": json.loads(r[6]),
+ "first_promotion": first_promotion,
+ "observations": observations,
+ }
+ )
+ return out
+
+ def mark_emitted(self, key: str, *, observations: int, now: float | None = None) -> None:
+ self._conn.execute(
+ "UPDATE decisions SET promoted_at = COALESCE(promoted_at, ?), "
+ "emitted_sessions = ? WHERE key = ?",
+ (now if now is not None else time.time(), observations, key),
+ )
+
+ # -- lifecycle -----------------------------------------------------------
+
+ def prune(self, *, now: float | None = None) -> None:
+ """Drop never-structured raws past the TTL (see :data:`RAW_TTL_DAYS`)."""
+ cutoff = (now if now is not None else time.time()) - RAW_TTL_DAYS * 86400.0
+ self._conn.execute(
+ "DELETE FROM raw_candidates WHERE structured_key IS NULL AND created_at < ?",
+ (cutoff,),
+ )
+
+ def commit(self) -> None:
+ self._conn.commit()
+
+ def close(self) -> None:
+ self._conn.close()
+
+ def __enter__(self) -> SessionStagingStore:
+ return self
+
+ def __exit__(self, *exc: object) -> None:
+ self.close()
diff --git a/tests/unit/sessions/test_decision_miner.py b/tests/unit/sessions/test_decision_miner.py
new file mode 100644
index 000000000..08161b04a
--- /dev/null
+++ b/tests/unit/sessions/test_decision_miner.py
@@ -0,0 +1,282 @@
+"""Deterministic-gate tests for the session decision miner."""
+
+from __future__ import annotations
+
+from repowise.core.sessions import Event, ToolResult, ToolUse
+from repowise.core.sessions.miners.decisions import (
+ SessionCandidate,
+ mine_events,
+ session_mining_enabled,
+)
+
+REPO_PREFIX = "c:\\users\\x\\repo"
+CWD = "C:\\Users\\x\\repo"
+
+
+def _user(text: str, **kw) -> Event:
+ return Event(kind="user", cwd=CWD, session_id="sess-1", text=text, **kw)
+
+
+def _tool_call(name: str, tool_input: dict, use_id: str = "t1") -> Event:
+ return Event(
+ kind="assistant",
+ cwd=CWD,
+ session_id="sess-1",
+ tool_uses=[ToolUse(id=use_id, name=name, input=tool_input)],
+ )
+
+
+def _tool_result(use_id: str, payload) -> Event:
+ is_error = isinstance(payload, str)
+ return Event(
+ kind="user",
+ cwd=CWD,
+ session_id="sess-1",
+ tool_results=[ToolResult(tool_use_id=use_id, is_error=is_error, payload=payload)],
+ )
+
+
+def _kinds(candidates: list[SessionCandidate]) -> list[str]:
+ return [c.kind for c in candidates]
+
+
+# ---------------------------------------------------------------------------
+# user_correction
+# ---------------------------------------------------------------------------
+
+
+def test_interrupt_with_guidance_is_correction():
+ events = [
+ _user("[Request interrupted by user for tool use]\nno, use commit-tree instead of amend")
+ ]
+ (candidate,) = mine_events(events, REPO_PREFIX)
+ assert candidate.kind == "user_correction"
+ assert candidate.quotes == ["no, use commit-tree instead of amend"]
+ assert candidate.session_id == "sess-1"
+
+
+def test_interrupt_without_guidance_is_skipped():
+ events = [_user("[Request interrupted by user]")]
+ assert mine_events(events, REPO_PREFIX) == []
+
+
+def test_pushback_lead_is_correction():
+ events = [_user("No, always run tests with the venv python, bare python is stale")]
+ (candidate,) = mine_events(events, REPO_PREFIX)
+ assert candidate.kind == "user_correction"
+ assert "venv python" in candidate.quotes[0]
+
+
+def test_short_pushback_is_skipped():
+ assert mine_events([_user("no")], REPO_PREFIX) == []
+
+
+def test_meta_compact_sidechain_and_tag_text_skipped():
+ events = [
+ _user("Don't ever do that again, use the helper because it exists", is_meta=True),
+ _user(
+ "Don't ever do that again, use the helper because it exists", is_compact_summary=True
+ ),
+ _user("Don't ever do that again, use the helper because it exists", sidechain=True),
+ _user("<local-command-stdout>no, don't use this text</local-command-stdout>"),
+ ]
+ assert mine_events(events, REPO_PREFIX) == []
+
+
+def test_off_repo_cwd_is_skipped():
+ event = Event(kind="user", cwd="C:\\elsewhere", session_id="s", text="No, do it differently")
+ assert mine_events([event], REPO_PREFIX) == []
+
+
+def test_forward_files_attach_to_correction():
+ events = [
+ _user("No, keep the parser in the adapter module, don't inline it"),
+ _tool_call("Edit", {"file_path": "C:\\Users\\x\\repo\\adapter.py"}),
+ ]
+ (candidate,) = mine_events(events, REPO_PREFIX)
+ assert candidate.files == ["C:\\Users\\x\\repo\\adapter.py"]
+
+
+# ---------------------------------------------------------------------------
+# explicit_choice
+# ---------------------------------------------------------------------------
+
+CHOICE_TEXT = "We chose sqlite for staging because hook-time writes must not contend with indexing."
+
+
+def test_choice_near_file_activity_is_candidate():
+ events = [
+ _tool_call("Write", {"file_path": "C:\\Users\\x\\repo\\staging.py"}),
+ _tool_result("t1", {"ok": True}),
+ Event(kind="assistant", cwd=CWD, session_id="sess-1", text=CHOICE_TEXT),
+ ]
+ (candidate,) = mine_events(events, REPO_PREFIX)
+ assert candidate.kind == "explicit_choice"
+ assert candidate.quotes == [CHOICE_TEXT]
+ assert candidate.files == ["C:\\Users\\x\\repo\\staging.py"]
+
+
+def test_choice_with_no_files_anywhere_is_dropped():
+ events = [Event(kind="assistant", cwd=CWD, session_id="sess-1", text=CHOICE_TEXT)]
+ assert mine_events(events, REPO_PREFIX) == []
+
+
+def test_choice_needs_both_verb_and_causal_cue():
+ events = [
+ _tool_call("Write", {"file_path": "C:\\Users\\x\\repo\\a.py"}),
+ Event(
+ kind="assistant", cwd=CWD, session_id="s", text="We chose sqlite for the staging store."
+ ),
+ Event(
+ kind="assistant",
+ cwd=CWD,
+ session_id="s",
+ text="It is nice because it is simple and light.",
+ ),
+ ]
+ assert mine_events(events, REPO_PREFIX) == []
+
+
+def test_sidechain_assistant_choice_is_skipped():
+ events = [
+ _tool_call("Write", {"file_path": "C:\\Users\\x\\repo\\a.py"}),
+ Event(kind="assistant", cwd=CWD, session_id="s", text=CHOICE_TEXT, sidechain=True),
+ ]
+ assert mine_events(events, REPO_PREFIX) == []
+
+
+# ---------------------------------------------------------------------------
+# dead_end
+# ---------------------------------------------------------------------------
+
+
+def _fail_pair(i: int, command: str) -> list[Event]:
+ use_id = f"f{i}"
+ return [
+ _tool_call("Bash", {"command": command}, use_id),
+ _tool_result(use_id, "Error: Exit code 1\nboom"),
+ ]
+
+
+def test_three_failures_then_pivot_is_dead_end():
+ events = [
+ *_fail_pair(1, "pytest tests/bad"),
+ *_fail_pair(2, "pytest tests/bad -k x"),
+ *_fail_pair(3, "pytest tests/bad -q"),
+ _tool_call("Bash", {"command": "ruff check ."}, "ok1"),
+ _tool_result("ok1", {"stdout": "clean", "stderr": ""}),
+ ]
+ (candidate,) = mine_events(events, REPO_PREFIX)
+ assert candidate.kind == "dead_end"
+ assert any("ruff check ." in q for q in candidate.quotes)
+ assert any("Error: Exit code 1" in q for q in candidate.quotes)
+
+
+def test_retry_that_eventually_works_is_not_dead_end():
+ events = [
+ *_fail_pair(1, "pytest tests/bad"),
+ *_fail_pair(2, "pytest tests/bad"),
+ *_fail_pair(3, "pytest tests/bad"),
+ _tool_call("Bash", {"command": "pytest tests/good"}, "ok1"),
+ _tool_result("ok1", {"stdout": "1 passed", "stderr": ""}),
+ ]
+ # Same anchor (pytest) succeeding is a corrected retry, not a dead end.
+ assert mine_events(events, REPO_PREFIX) == []
+
+
+def test_two_failures_is_below_threshold():
+ events = [
+ *_fail_pair(1, "pytest tests/bad"),
+ *_fail_pair(2, "pytest tests/bad -q"),
+ _tool_call("Bash", {"command": "ruff check ."}, "ok1"),
+ _tool_result("ok1", {"stdout": "clean", "stderr": ""}),
+ ]
+ assert mine_events(events, REPO_PREFIX) == []
+
+
+# ---------------------------------------------------------------------------
+# LLM-output grounding gate
+# ---------------------------------------------------------------------------
+
+RAW = {
+ "kind": "user_correction",
+ "quotes": ["dont add star count for repowise, its not 5k yet, and thats cringy"],
+ "files": ["a.py", "b.py"],
+}
+
+
+def _item(**overrides):
+ base = {
+ "title": "Avoid star counts",
+ "decision": "Do not add a star count for repowise",
+ "rationale": "its not 5k yet and thats cringy",
+ "affected_files": [],
+ "source_quote": RAW["quotes"][0],
+ }
+ base.update(overrides)
+ return base
+
+
+def test_gate_accepts_normalized_decision_with_verbatim_quote():
+ from repowise.core.sessions.miners.decisions import _gate_structured
+
+ gated = _gate_structured(_item(), RAW)
+ assert gated is not None
+ assert gated["verification"] == "exact"
+ assert gated["rationale"] # grounded, survives normalization
+
+
+def test_gate_rejects_unverifiable_quote():
+ from repowise.core.sessions.miners.decisions import _gate_structured
+
+ assert _gate_structured(_item(source_quote="we agreed to adopt Redis"), RAW) is None
+ assert _gate_structured(_item(source_quote=""), RAW) is None
+
+
+def test_gate_rejects_wild_decision_riding_valid_quote():
+ from repowise.core.sessions.miners.decisions import _gate_structured
+
+ wild = _item(decision="Migrate all caching infrastructure to Redis clusters immediately")
+ assert _gate_structured(wild, RAW) is None
+
+
+def test_gate_drops_ungrounded_rationale_but_keeps_candidate():
+ from repowise.core.sessions.miners.decisions import _gate_structured
+
+ gated = _gate_structured(_item(rationale="star counts hurt conversion metrics badly"), RAW)
+ assert gated is not None
+ assert gated["rationale"] == ""
+
+
+def test_gate_files_fallback_depends_on_kind():
+ from repowise.core.sessions.miners.decisions import _gate_structured
+
+ # A correction with no LLM-named files is a repo-wide rule: no linkage.
+ assert _gate_structured(_item(), RAW)["affected_files"] == []
+ # A choice inherits the files in play when the LLM names none.
+ choice_raw = {**RAW, "kind": "explicit_choice"}
+ assert _gate_structured(_item(), choice_raw)["affected_files"] == ["a.py", "b.py"]
+ # An LLM-named subset is honored either way (and clamped to files in play).
+ named = _item(affected_files=["b.py", "zz.py"])
+ assert _gate_structured(named, RAW)["affected_files"] == ["b.py"]
+
+
+# ---------------------------------------------------------------------------
+# candidate identity + config gate
+# ---------------------------------------------------------------------------
+
+
+def test_candidate_hash_is_content_stable():
+ a = SessionCandidate(kind="user_correction", quotes=["No, use B"])
+ b = SessionCandidate(kind="user_correction", quotes=["no, use b"])
+ c = SessionCandidate(kind="explicit_choice", quotes=["no, use b"])
+ assert a.hash == b.hash
+ assert a.hash != c.hash
+
+
+def test_session_mining_enabled_parsing():
+ assert session_mining_enabled(None) is True
+ assert session_mining_enabled({}) is True
+ assert session_mining_enabled({"decisions": {"session_mining": True}}) is True
+ assert session_mining_enabled({"decisions": {"session_mining": False}}) is False
+ assert session_mining_enabled({"decisions": "garbage"}) is True
diff --git a/tests/unit/sessions/test_session_decisions_e2e.py b/tests/unit/sessions/test_session_decisions_e2e.py
new file mode 100644
index 000000000..4c27069f5
--- /dev/null
+++ b/tests/unit/sessions/test_session_decisions_e2e.py
@@ -0,0 +1,229 @@
+"""End-to-end session decision mining: transcript -> gates -> LLM -> promotion."""
+
+from __future__ import annotations
+
+import json
+
+from repowise.core.analysis.decisions.provenance import SOURCE_RANK
+from repowise.core.sessions.adapters.claude_code import transcript_dir_for
+from repowise.core.sessions.miners.decisions import mine_session_decisions
+from repowise.core.sessions.staging import SessionStagingStore, default_store_path
+
+CORRECTION = "No, always run the unit suite with the venv python, bare python is a stale install"
+
+
+class FakeResponse:
+ def __init__(self, content: str) -> None:
+ self.content = content
+
+
+class FakeProvider:
+ """Echoes a grounded structuring result for every candidate it is shown."""
+
+ def __init__(self, items_per_candidate: dict | None = None) -> None:
+ self.calls: list[str] = []
+ self._item = items_per_candidate or {
+ "title": "Run tests with the venv python",
+ "decision": "always run the unit suite with the venv python",
+ "rationale": "bare python is a stale install",
+ "affected_files": [],
+ "source_quote": CORRECTION,
+ }
+
+ async def generate(self, system: str, prompt: str, **kw) -> FakeResponse:
+ self.calls.append(prompt)
+ count = prompt.count("--- Candidate ")
+ items = [{"candidate": i, **self._item} for i in range(count)]
+ return FakeResponse(json.dumps(items))
+
+
+def _write_transcript(repo_root, projects_root, name: str, session_id: str, text: str) -> None:
+ directory = transcript_dir_for(repo_root, projects_root)
+ directory.mkdir(parents=True, exist_ok=True)
+ entry = {
+ "type": "user",
+ "cwd": str(repo_root),
+ "timestamp": "2026-07-11T10:00:00.000Z",
+ "sessionId": session_id,
+ "message": {"role": "user", "content": [{"type": "text", "text": text}]},
+ }
+ (directory / name).write_text(json.dumps(entry) + "\n", encoding="utf-8")
+
+
+async def test_correction_mines_structures_and_promotes(tmp_path):
+ repo_root = tmp_path / "repo"
+ repo_root.mkdir()
+ 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.status == "active" # correction fast path, first promotion
+ assert decision.verification == "exact"
+ assert decision.evidence_commits == ["sess-1"]
+ assert decision.source_quote == CORRECTION
+ assert 0 < decision.confidence < 1
+ assert len(provider.calls) == 1
+
+ # Second run: no new transcript lines -> no LLM call, nothing re-promoted.
+ again = await mine_session_decisions(
+ repo_root, provider=provider, projects_root=projects_root, now=200.0
+ )
+ assert again == []
+ assert len(provider.calls) == 1
+
+
+async def test_second_session_reemits_as_proposed_evidence(tmp_path):
+ repo_root = tmp_path / "repo"
+ repo_root.mkdir()
+ projects_root = tmp_path / "projects"
+ provider = FakeProvider()
+ _write_transcript(repo_root, projects_root, "one.jsonl", "sess-1", CORRECTION)
+ await mine_session_decisions(
+ repo_root, provider=provider, projects_root=projects_root, now=100.0
+ )
+
+ _write_transcript(
+ repo_root, projects_root, "two.jsonl", "sess-2", CORRECTION + " and stays that way"
+ )
+ decisions = await mine_session_decisions(
+ repo_root, provider=provider, projects_root=projects_root, now=200.0
+ )
+ assert decisions # one member per observing session
+ assert {d.status for d in decisions} == {"proposed"}
+ assert {d.evidence_commits[0] for d in decisions} == {"sess-1", "sess-2"}
+
+
+async def test_ungrounded_llm_output_is_rejected_not_retried(tmp_path):
+ repo_root = tmp_path / "repo"
+ repo_root.mkdir()
+ projects_root = tmp_path / "projects"
+ provider = FakeProvider(
+ items_per_candidate={
+ "title": "Adopt Redis for caching",
+ "decision": "migrate all caching to Redis", # nowhere in the quotes
+ "rationale": "",
+ "affected_files": [],
+ "source_quote": "",
+ }
+ )
+ _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
+ )
+ assert decisions == []
+
+ with SessionStagingStore(default_store_path(repo_root)) as store:
+ assert store.pending_raws(10) == [] # rejected, not left for retry
+ assert store.promotable() == []
+
+
+async def test_llm_failure_leaves_candidates_staged(tmp_path):
+ repo_root = tmp_path / "repo"
+ repo_root.mkdir()
+ projects_root = tmp_path / "projects"
+
+ class FailingProvider:
+ async def generate(self, *a, **kw):
+ raise RuntimeError("provider down")
+
+ _write_transcript(repo_root, projects_root, "one.jsonl", "sess-1", CORRECTION)
+ decisions = await mine_session_decisions(
+ repo_root, provider=FailingProvider(), projects_root=projects_root, now=100.0
+ )
+ assert decisions == []
+
+ with SessionStagingStore(default_store_path(repo_root)) as store:
+ assert len(store.pending_raws(10)) == 1 # staged, retried next update
+
+ # Retry with a working provider structures the backlog without re-reading
+ # the transcript (the cursor already advanced past it).
+ provider = FakeProvider()
+ decisions = await mine_session_decisions(
+ repo_root, provider=provider, projects_root=projects_root, now=200.0
+ )
+ (decision,) = decisions
+ assert decision.status == "active"
+
+
+async def test_init_pipeline_appends_session_decisions(tmp_path, monkeypatch):
+ """The full-index decision phase folds mined session decisions in."""
+ from types import SimpleNamespace
+
+ from repowise.core.analysis.decisions.extractor import ExtractedDecision
+ from repowise.core.pipeline.phases.analysis import _run_decision_extraction
+
+ calls = []
+
+ async def fake_mine(repo_path, *, provider, **kw):
+ calls.append(repo_path)
+ return [ExtractedDecision(title="Use X", source="session", status="active")]
+
+ monkeypatch.setattr("repowise.core.sessions.miners.decisions.mine_session_decisions", fake_mine)
+
+ class Graph:
+ def graph(self):
+ return None
+
+ class Provider:
+ async def generate(self, *a, **kw):
+ return SimpleNamespace(content="[]")
+
+ report = await _run_decision_extraction(
+ tmp_path,
+ llm_client=Provider(),
+ graph_builder=Graph(),
+ git_meta_map={},
+ parsed_files=[],
+ progress=None,
+ )
+ assert calls == [tmp_path]
+ assert [d.title for d in report.decisions if d.source == "session"] == ["Use X"]
+ assert report.by_source["session"] == 1
+ assert report.total_found == len(report.decisions)
+
+
+async def test_init_pipeline_respects_session_mining_gate(tmp_path, monkeypatch):
+ from types import SimpleNamespace
+
+ from repowise.core.pipeline.phases.analysis import _run_decision_extraction
+
+ (tmp_path / ".repowise").mkdir()
+ (tmp_path / ".repowise" / "config.yaml").write_text(
+ "decisions:\n session_mining: false\n", encoding="utf-8"
+ )
+
+ async def fake_mine(repo_path, *, provider, **kw):
+ raise AssertionError("must not mine when the config gate is off")
+
+ monkeypatch.setattr("repowise.core.sessions.miners.decisions.mine_session_decisions", fake_mine)
+
+ class Graph:
+ def graph(self):
+ return None
+
+ class Provider:
+ async def generate(self, *a, **kw):
+ return SimpleNamespace(content="[]")
+
+ report = await _run_decision_extraction(
+ tmp_path,
+ llm_client=Provider(),
+ graph_builder=Graph(),
+ git_meta_map={},
+ parsed_files=[],
+ progress=None,
+ )
+ assert report is not None
+ assert "session" not in report.by_source
+
+
+def test_session_rank_sits_between_adr_and_commit():
+ assert SOURCE_RANK["session"] == 7
+ assert SOURCE_RANK["adr"] > SOURCE_RANK["session"] > SOURCE_RANK["commit"]
diff --git a/tests/unit/sessions/test_staging.py b/tests/unit/sessions/test_staging.py
new file mode 100644
index 000000000..7f31935ab
--- /dev/null
+++ b/tests/unit/sessions/test_staging.py
@@ -0,0 +1,193 @@
+"""Staging-store tests: raw queue, observation counting, promotion, cursors."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from repowise.core.sessions import ClaudeCodeAdapter
+from repowise.core.sessions.cursor import iter_new_events
+from repowise.core.sessions.staging import SessionStagingStore, title_key
+
+
+def store(tmp_path):
+ s = SessionStagingStore(tmp_path / "sessions.db")
+ yield s
+ s.close()
+
+
+def _raw(store, *, hash_="raw1", kind="explicit_choice", session_id="s1"):
+ return store.add_raw(
+ hash_=hash_,
+ kind=kind,
+ quotes=["we chose sqlite because it is local"],
+ files=["a.py"],
+ session_id=session_id,
+ now=100.0,
+ )
+
+
+STRUCTURED = {
+ "title": "Use sqlite for staging",
+ "decision": "we chose sqlite",
+ "rationale": "because it is local",
+ "source_quote": "we chose sqlite because it is local",
+ "verification": "exact",
+ "affected_files": ["a.py"],
+}
+
+
+def test_add_raw_is_idempotent(store):
+ assert _raw(store) is True
+ assert _raw(store) is False
+ assert len(store.pending_raws(10)) == 1
+
+
+def test_mark_raw_rejected_removes_from_pending(store):
+ _raw(store)
+ store.mark_raw_rejected("raw1")
+ assert store.pending_raws(10) == []
+
+
+def test_upsert_structured_merges_sessions_and_kind(store):
+ _raw(store, hash_="r1", kind="explicit_choice", session_id="s1")
+ _raw(store, hash_="r2", kind="user_correction", session_id="s2")
+ key = store.upsert_structured(
+ "r1",
+ kind="explicit_choice",
+ title=STRUCTURED["title"],
+ structured=STRUCTURED,
+ quotes=["q1"],
+ files=["a.py"],
+ session_id="s1",
+ now=100.0,
+ )
+ same_key = store.upsert_structured(
+ "r2",
+ kind="user_correction",
+ title="use SQLITE for staging!", # same normalized title
+ structured=STRUCTURED,
+ quotes=["q2"],
+ files=["b.py"],
+ session_id="s2",
+ now=101.0,
+ )
+ assert same_key == key == title_key(STRUCTURED["title"])
+ assert store.pending_raws(10) == []
+
+ (row,) = store.promotable()
+ assert sorted(row["sessions"]) == ["s1", "s2"]
+ assert row["kind"] == "user_correction" # correction kind is sticky
+ assert sorted(row["files"]) == ["a.py", "b.py"]
+
+
+def test_single_choice_observation_does_not_promote(store):
+ _raw(store, hash_="r1")
+ store.upsert_structured(
+ "r1",
+ kind="explicit_choice",
+ title=STRUCTURED["title"],
+ structured=STRUCTURED,
+ quotes=["q"],
+ files=[],
+ session_id="s1",
+ )
+ assert store.promotable() == []
+
+
+def test_single_correction_observation_promotes(store):
+ _raw(store, hash_="r1", kind="user_correction")
+ store.upsert_structured(
+ "r1",
+ kind="user_correction",
+ title=STRUCTURED["title"],
+ structured=STRUCTURED,
+ quotes=["q"],
+ files=[],
+ session_id="s1",
+ )
+ (row,) = store.promotable()
+ assert row["first_promotion"] is True
+ assert row["observations"] == 1
+
+
+def test_emit_bookkeeping_requires_new_observations(store):
+ _raw(store, hash_="r1", kind="user_correction", session_id="s1")
+ store.upsert_structured(
+ "r1",
+ kind="user_correction",
+ title=STRUCTURED["title"],
+ structured=STRUCTURED,
+ quotes=["q"],
+ files=[],
+ session_id="s1",
+ )
+ (row,) = store.promotable()
+ store.mark_emitted(row["key"], observations=row["observations"])
+ assert store.promotable() == [] # nothing new to say
+
+ # A new session observing the same decision re-qualifies it, but as a
+ # re-emission (first_promotion False -> upserted as proposed evidence).
+ _raw(store, hash_="r2", kind="explicit_choice", session_id="s2")
+ store.upsert_structured(
+ "r2",
+ kind="explicit_choice",
+ title=STRUCTURED["title"],
+ structured=STRUCTURED,
+ quotes=["q2"],
+ files=[],
+ session_id="s2",
+ )
+ (row,) = store.promotable()
+ assert row["first_promotion"] is False
+ assert row["observations"] == 2
+
+
+def test_prune_drops_stale_unstructured_raws(store):
+ _raw(store, hash_="old")
+ store.prune(now=100.0 + 91 * 86400.0)
+ assert store.pending_raws(10) == []
+
+
+def test_state_survives_reopen(tmp_path):
+ path = tmp_path / "sessions.db"
+ with SessionStagingStore(path) as s:
+ _raw(s, hash_="r1", kind="user_correction")
+ s.upsert_structured(
+ "r1",
+ kind="user_correction",
+ title=STRUCTURED["title"],
+ structured=STRUCTURED,
+ quotes=["q"],
+ files=[],
+ session_id="s1",
+ )
+ s.commit()
+ with SessionStagingStore(path) as s:
+ (row,) = s.promotable()
+ assert row["title"] == STRUCTURED["title"]
+
+
+def test_db_cursors_drive_iter_new_events(tmp_path):
+ """The DB-backed cursor store satisfies the iter_new_events contract."""
+ adapter = ClaudeCodeAdapter()
+ transcript = tmp_path / "session.jsonl"
+ line = json.dumps(
+ {"type": "user", "sessionId": "s1", "message": {"role": "user", "content": "hello"}}
+ )
+ transcript.write_text(line + "\n", encoding="utf-8")
+
+ path = tmp_path / "sessions.db"
+ with SessionStagingStore(path) as store:
+ events = list(iter_new_events(adapter, transcript, store.cursors))
+ assert [e.text for e in events] == ["hello"]
+ store.cursors.save()
+
+ with transcript.open("a", encoding="utf-8", newline="\n") as fh:
+ fh.write(line.replace("hello", "again") + "\n")
+
+ with SessionStagingStore(path) as store:
+ events = list(iter_new_events(adapter, transcript, store.cursors))
+ assert [e.text for e in events] == ["again"]