diff --git a/dist/app.py b/dist/app.py
index 630f091..266467d 100644
--- a/dist/app.py
+++ b/dist/app.py
@@ -51,7 +51,7 @@
 
     class IncidentState(Session):
         environment: str
-        reporter: Reporter
+        submitter: Submitter
         ...
 
 ``Session`` deliberately contains *no* domain-specific fields. Adding one
@@ -86,7 +86,7 @@ class IncidentState(Session):
 
 
 # ----- imports for runtime/similarity.py -----
-"""Similarity scoring for incident matching."""
+"""Similarity scoring for session matching."""
 
 from typing import Protocol
 
@@ -265,8 +265,8 @@ class IncidentState(Session):
 
 ``find_similar`` accepts an arbitrary ``filter_kwargs`` mapping — keys
 must correspond to ``IncidentRow`` columns. This decouples the
-framework from incident-specific filter dimensions: apps with a
-``severity``-only schema, or a multi-tenant ``tenant_id`` schema, or
+framework from app-specific filter dimensions: apps with a
+schema with a single status-tier field, a multi-tenant ``tenant_id`` schema, or
 anything else, build their filter on the fly.
 """
 
@@ -297,7 +297,7 @@ class IncidentState(Session):
 The class is parametrised as ``Generic[StateT]`` and routes row
 hydration through ``self._state_cls(...)`` so apps can plug in their
 own ``Session`` subclass via ``RuntimeConfig.state_class``. The row
-schema remains incident-shaped, but unused fields are dropped via
+schema remains the row-level shape, but unused fields are dropped via
 Pydantic's default ``extra='ignore'`` when a narrower ``state_cls`` is
 supplied.
 """
@@ -1113,7 +1113,7 @@ async def _poll(self, registry):
 structured output {is_duplicate, confidence, rationale}.
 
 The pipeline is **framework-level** and never imports the
-incident-management state class (R4 in the Phase-7 plan). Apps inject
+domain-specific Session subclass (R4 in the Phase-7 plan). Apps inject
 domain-specific text via a ``text_extractor: Callable[[Session], str]``
 callable.
 
@@ -1684,7 +1684,7 @@ class MCPConfig(BaseModel):
 
 
 class MetadataConfig(BaseModel):
-    """Relational store for incident metadata. SQLite (dev) or Postgres (prod)."""
+    """Relational store for session metadata. SQLite (dev) or Postgres (prod)."""
     url: str = "sqlite:///incidents/incidents.db"
     pool_size: int = 5      # postgres only; sqlite uses NullPool
     echo: bool = False
@@ -2516,7 +2516,7 @@ def to_agent_input(self) -> str:
 
         Apps subclass ``Session`` and override this to surface the
         domain shape (``Incident X / Environment Y / Query Z`` for the
-        incident-management app, ``PR title / repo / diff stats`` for
+        example app, ``PR title / repo / diff stats`` for
         code review, etc.). The framework default keeps the prompt
         framework-agnostic — id + status only — so that any app that
         has not overridden the hook still gets a usable preamble.
@@ -2548,7 +2548,7 @@ def id_format(cls, *, seq: int, prefix: str = "SES") -> str:
 
         ``prefix`` is supplied by ``SessionStore._next_id`` from
         ``FrameworkAppConfig.session_id_prefix`` so each app picks its
-        own namespace via plain config (e.g. ``INC`` for incident
+        own namespace via plain config (e.g. ``INC`` for the example incident
         management, ``REVIEW`` for code review, ``HR`` for HR cases,
         ...). Apps with truly bespoke id shapes can still override this
         classmethod on their ``Session`` subclass and ignore ``prefix``.
@@ -4115,7 +4115,7 @@ def _ef(i, key, default: Any = ""):
                     _ef(i, "summary", "") or "",
                     " ".join(_ef(i, "tags", []) or []),
                 ])),
-                "incident": i,
+                "session": i,
             }
             for i in candidates_inc
         ]
@@ -4125,7 +4125,7 @@ def _ef(i, key, default: Any = ""):
             threshold=self.similarity_threshold if threshold is None else threshold,
             limit=limit,
         )
-        return [(c["incident"], float(s)) for c, s in results]
+        return [(c["session"], float(s)) for c, s in results]
 
 # ====== module: runtime/storage/session_store.py ======
 
@@ -4207,7 +4207,7 @@ class StaleVersionError(RuntimeError):
 
 
 class SessionStore(Generic[StateT]):
-    """Active session/incident lifecycle store, parametrised on ``StateT``.
+    """Active session lifecycle store, parametrised on ``StateT``.
 
     Owns CRUD on the row schema plus the vector write-through. Read-only
     similarity search lives in ``HistoryStore``.
@@ -4326,7 +4326,7 @@ def create(self, *, query: str, environment: str,
     def load(self, incident_id: str) -> StateT:
         if not _SESSION_ID_RE.match(incident_id):
             raise ValueError(
-                f"Invalid incident id {incident_id!r}; expected PREFIX-YYYYMMDD-NNN"
+                f"Invalid session id {incident_id!r}; expected PREFIX-YYYYMMDD-NNN"
             )
         with SqlSession(self.engine) as session:
             row = session.get(IncidentRow, incident_id)
@@ -4334,40 +4334,39 @@ def load(self, incident_id: str) -> StateT:
                 raise FileNotFoundError(incident_id)
             return self._row_to_incident(row)
 
-    def save(self, incident: StateT) -> None:
-        if not _SESSION_ID_RE.match(incident.id):
+    def save(self, session: StateT) -> None:
+        if not _SESSION_ID_RE.match(session.id):
             raise ValueError(
-                f"Invalid incident id {incident.id!r}; expected PREFIX-YYYYMMDD-NNN"
+                f"Invalid session id {session.id!r}; expected PREFIX-YYYYMMDD-NNN"
             )
         # ``_iso(_now())`` returns ``str`` here -- the input datetime is
         # never None -- but the helper's signature is the broader
         # ``Optional[str]``. ``or ""`` keeps pyright + the typed
         # ``Session.updated_at: str`` field consistent without changing
         # behaviour (real value is always present).
-        incident.updated_at = _iso(_now()) or ""
-        sess = incident  # local alias — avoids repeating the domain token in new code
-        expected_version = getattr(sess, "version", 1)
+        session.updated_at = _iso(_now()) or ""
+        expected_version = getattr(session, "version", 1)
         # Bump in-memory BEFORE building the row dict so the persisted
         # row reflects the new version.
-        sess.version = expected_version + 1
-        with SqlSession(self.engine) as session:
-            existing = session.get(IncidentRow, sess.id)
+        session.version = expected_version + 1
+        with SqlSession(self.engine) as db_session:
+            existing = db_session.get(IncidentRow, session.id)
             prior_text = _embed_source_from_row(existing) if existing is not None else ""
             if existing is not None and existing.version != expected_version:
                 # Roll back the in-memory bump so the caller can reload + retry.
-                sess.version = expected_version
+                session.version = expected_version
                 raise StaleVersionError(
-                    f"session {sess.id} version is {existing.version}, "
+                    f"session {session.id} version is {existing.version}, "
                     f"expected {expected_version}"
                 )
-            data = self._incident_to_row_dict(incident)
+            data = self._incident_to_row_dict(session)
             if existing is None:
-                session.add(IncidentRow(**data))
+                db_session.add(IncidentRow(**data))
             else:
                 for k, v in data.items():
                     setattr(existing, k, v)
-            session.commit()
-        self._refresh_vector(incident, prior_text=prior_text)
+            db_session.commit()
+        self._refresh_vector(session, prior_text=prior_text)
 
     def delete(self, incident_id: str) -> StateT:
         with SqlSession(self.engine) as session:
@@ -4566,10 +4565,10 @@ def _row_to_incident(self, row: IncidentRow) -> StateT:
 
         Fields are pulled from typed columns when the state class
         declares them; everything else is merged in from the
-        ``extra_fields`` JSON bag. ``reporter`` is reconstituted from
+        ``extra_fields`` JSON bag. The ``reporter`` field (when present) is reconstituted from
         the typed ``reporter_id`` / ``reporter_team`` columns *only* when
-        the state class has a ``reporter`` field — otherwise it's
-        omitted so apps without a reporter concept (code-review) don't
+        the state class declares it — otherwise it's
+        omitted so apps without that concept (code-review) don't
         receive an unexpected attribute.
         """
         model_fields = self._state_cls.model_fields
@@ -6131,10 +6130,10 @@ def start_session(
         through to app-specific MCP tools.
 
         ``submitter`` is a free-form dict the calling app interprets.
-        For incident-management it is ``{"id": "...", "team": "..."}``;
+        For the example incident-management app it is ``{"id": "...", "team": "..."}``;
         other apps can carry app-specific keys (e.g. code-review's
         ``{"id": "<github-username>", "pr_url": "..."}``). The framework
-        only projects ``id``/``team`` onto the row's reporter columns.
+        only projects ``id``/``team`` onto the row's submitter columns.
 
         Deprecated kwargs (coerced and warned):
           * ``environment`` -> ``state_overrides={"environment": ...}``
@@ -8526,9 +8525,9 @@ async def node(state: GraphState) -> dict:
         # the same reload comment in ``runtime.graph.make_agent_node``
         # for the full rationale.
         try:
-            incident: Session = store.load(inc_id)
+            session: Session = store.load(inc_id)
         except FileNotFoundError:
-            incident = state_session
+            session = state_session
 
         # M3: emit agent_started telemetry before any work happens.
         if event_log is not None:
@@ -8546,7 +8545,7 @@ async def node(state: GraphState) -> dict:
         # live ``Session`` for this run.
         if gateway_cfg is not None:
             run_tools = [
-                wrap_tool(t, session=incident, gateway_cfg=gateway_cfg,
+                wrap_tool(t, session=session, gateway_cfg=gateway_cfg,
                           agent_name=skill.name, store=store,
                           gate_policy=gate_policy,
                           event_log=event_log)
@@ -8570,7 +8569,7 @@ async def node(state: GraphState) -> dict:
             checkpointer=checkpointer,
         )
         inner_thread_id = (
-            f"{inc_id}:agent:{skill.name}:turn{len(incident.agents_run)}"
+            f"{inc_id}:agent:{skill.name}:turn{len(session.agents_run)}"
         )
         inner_cfg = {"configurable": {"thread_id": inner_thread_id}}
 
@@ -8578,7 +8577,7 @@ async def node(state: GraphState) -> dict:
         # start of each agent step so the gateway treats the first
         # tool call of the turn as "no signal yet".
         try:
-            incident.turn_confidence_hint = None
+            session.turn_confidence_hint = None
         except (AttributeError, ValueError):
             pass
 
@@ -8589,7 +8588,7 @@ async def node(state: GraphState) -> dict:
                 inner_has_checkpointer=checkpointer is not None,
                 initial_input={
                     "messages": [
-                        HumanMessage(content=_format_agent_input(incident))
+                        HumanMessage(content=_format_agent_input(session))
                     ]
                 },
             )
@@ -8599,19 +8598,19 @@ async def node(state: GraphState) -> dict:
         except Exception as exc:  # noqa: BLE001
             return _handle_agent_failure(
                 skill_name=skill.name, started_at=started_at, exc=exc,
-                inc_id=inc_id, store=store, fallback=incident,
+                inc_id=inc_id, store=store, fallback=session,
             )
 
         # Tools (e.g. registered patch tools) write straight to disk.
         # Reload so the node's own append of agent_run + tool_calls
         # happens against the tool-mutated state.
-        incident = store.load(inc_id)
+        session = store.load(inc_id)
 
         messages = result.get("messages", [])
         ts = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
 
         agent_confidence, agent_rationale, agent_signal = _harvest_tool_calls_and_patches(
-            messages, skill.name, incident, ts, valid_signals,
+            messages, skill.name, session, ts, valid_signals,
             terminal_tool_names=terminal_tool_names,
             patch_tool_names=patch_tool_names,
         )
@@ -8619,10 +8618,10 @@ async def node(state: GraphState) -> dict:
         # tool call sees the harvested confidence.
         if agent_confidence is not None:
             try:
-                incident.turn_confidence_hint = agent_confidence
+                session.turn_confidence_hint = agent_confidence
             except (AttributeError, ValueError):
                 pass
-        _pair_tool_responses(messages, incident)
+        _pair_tool_responses(messages, session)
 
         # Phase 10 (FOC-03 / D-10-03): parse envelope; reconcile against
         # any typed-terminal-tool-arg confidence. Envelope failure is a
@@ -8632,7 +8631,7 @@ async def node(state: GraphState) -> dict:
         except EnvelopeMissingError as exc:
             return _handle_agent_failure(
                 skill_name=skill.name, started_at=started_at, exc=exc,
-                inc_id=inc_id, store=store, fallback=incident,
+                inc_id=inc_id, store=store, fallback=session,
             )
 
         terminal_tool_for_log = _first_terminal_tool_called_this_turn(
@@ -8668,13 +8667,13 @@ async def node(state: GraphState) -> dict:
                 )
 
         _record_success_run(
-            incident=incident, skill_name=skill.name, started_at=started_at,
+            session=session, skill_name=skill.name, started_at=started_at,
             final_text=final_text, usage=usage,
             confidence=final_confidence, rationale=final_rationale,
             signal=final_signal,
             store=store,
         )
-        next_route_signal = decide_route(incident)
+        next_route_signal = decide_route(session)
         next_node = route_from_skill(skill, next_route_signal)
 
         # M3: emit route_decided + agent_finished. agent_finished carries
@@ -8705,7 +8704,7 @@ async def node(state: GraphState) -> dict:
                     "event_log.record(agent_finished) failed", exc_info=True,
                 )
 
-        return {"session": incident, "next_route": next_node,
+        return {"session": session, "next_route": next_node,
                 "last_agent": skill.name, "error": None}
 
     return node
@@ -8738,7 +8737,7 @@ def _safe_eval(expr: str, ctx: dict[str, Any]) -> Any:
     return eval(code, {"__builtins__": {}}, ctx)  # noqa: S307 — AST-whitelisted
 
 
-def _ctx_for_session(incident: Session) -> dict[str, Any]:
+def _ctx_for_session(session: Session) -> dict[str, Any]:
     """Build the variable namespace dispatch-rule expressions see.
 
     Exposes the live session payload as ``session`` plus a few
@@ -8747,7 +8746,7 @@ def _ctx_for_session(incident: Session) -> dict[str, Any]:
     AST checker already restricts the language so we don't need to
     sandbox the namespace any further.
     """
-    payload = incident.model_dump()
+    payload = session.model_dump()
     return {
         "session": payload,
         "status": payload.get("status"),
@@ -8793,7 +8792,7 @@ def _llm_pick_target(
     *,
     skill: Skill,
     llm: BaseChatModel,
-    incident: Session,
+    session: Session,
 ) -> str:
     """One-shot LLM dispatch: ask the model to choose a subordinate.
 
@@ -8808,7 +8807,7 @@ def _llm_pick_target(
         f"Choose ONE of: {', '.join(skill.subordinates)}.\n"
         f"Reply with only the agent name."
     )
-    payload = json.dumps(incident.model_dump(), default=str)
+    payload = json.dumps(session.model_dump(), default=str)
     msgs = [
         SystemMessage(content=prompt),
         HumanMessage(content=payload),
@@ -8835,7 +8834,7 @@ def _llm_pick_target(
 def _rule_pick_target(
     *,
     skill: Skill,
-    incident: Session,
+    session: Session,
 ) -> tuple[str, str | None]:
     """Walk dispatch_rules in order; return (target, matched_when).
 
@@ -8843,7 +8842,7 @@ def _rule_pick_target(
     fallback case carries ``matched_when=None`` so the audit log can
     distinguish "default" from "rule X matched".
     """
-    ctx = _ctx_for_session(incident)
+    ctx = _ctx_for_session(session)
     for rule in skill.dispatch_rules:
         try:
             if bool(_safe_eval(rule.when, ctx)):
@@ -9018,7 +9017,7 @@ async def node(state: GraphState) -> dict:
 
         rule_matched: str | None = None
         if skill.dispatch_strategy == "rule":
-            target, rule_matched = _rule_pick_target(skill=skill, incident=sess)
+            target, rule_matched = _rule_pick_target(skill=skill, session=sess)
         else:  # "llm"
             if llm is None:
                 logger.warning(
@@ -9027,7 +9026,7 @@ async def node(state: GraphState) -> dict:
                 )
                 target = skill.subordinates[0]
             else:
-                target = _llm_pick_target(skill=skill, llm=llm, incident=sess)
+                target = _llm_pick_target(skill=skill, llm=llm, session=sess)
 
         # Audit: one structured log entry per dispatch.
         try:
@@ -9527,11 +9526,11 @@ def route_from_skill(skill: Skill, signal: str) -> str:
 
 
 class AgentRunRecorder:
-    """Helper to capture an agent's run + tool calls into the incident."""
+    """Helper to capture an agent's run + tool calls into the session."""
 
-    def __init__(self, *, agent: str, incident: Session):
+    def __init__(self, *, agent: str, session: Session):
         self.agent = agent
-        self.incident = incident
+        self.session = session
         self._started_at: str | None = None
 
     def start(self) -> None:
@@ -9539,13 +9538,13 @@ def start(self) -> None:
 
     def record_tool_call(self, tool: str, args: dict, result) -> None:
         ts = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
-        self.incident.tool_calls.append(
+        self.session.tool_calls.append(
             ToolCall(agent=self.agent, tool=tool, args=args, result=result, ts=ts)
         )
 
     def finish(self, *, summary: str) -> None:
         ended_at = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
-        self.incident.agents_run.append(AgentRun(
+        self.session.agents_run.append(AgentRun(
             agent=self.agent,
             started_at=self._started_at or ended_at,
             ended_at=ended_at,
@@ -9705,7 +9704,7 @@ async def _ainvoke_with_retry(executor, input_, *, max_attempts: int = 3,
     raise last_exc or RuntimeError("retry exhausted with no attempts")  # pragma: no cover
 
 
-def _format_agent_input(incident: Session) -> str:
+def _format_agent_input(session: Session) -> str:
     """Build the human-message preamble each agent receives.
 
     Delegates to ``Session.to_agent_input`` so each app subclass owns the
@@ -9713,7 +9712,7 @@ def _format_agent_input(incident: Session) -> str:
     session id + status; ``IncidentState`` and ``CodeReviewState``
     override with their respective shapes.
     """
-    return incident.to_agent_input()
+    return session.to_agent_input()
 
 
 def _merge_patch_metadata(
@@ -9787,7 +9786,7 @@ def _harvest_patch_tool(
 def _harvest_tool_calls_and_patches(
     messages: list,
     skill_name: str,
-    incident: Session,
+    session: Session,
     ts: str,
     valid_signals: frozenset[str] | None = None,
     terminal_tool_names: frozenset[str] = frozenset(),
@@ -9830,7 +9829,7 @@ def _harvest_tool_calls_and_patches(
             # colon; rsplit on the rightmost colon recovers the bare
             # tool name for both prefixed and unprefixed forms.
             tc_original = tc_name.rsplit(":", 1)[-1]
-            incident.tool_calls.append(ToolCall(
+            session.tool_calls.append(ToolCall(
                 agent=skill_name, tool=tc_name, args=tc_args,
                 result=None, ts=ts,
             ))
@@ -9844,11 +9843,11 @@ def _harvest_tool_calls_and_patches(
     return state
 
 
-def _pair_tool_responses(messages: list, incident: Session) -> None:
+def _pair_tool_responses(messages: list, session: Session) -> None:
     """Match ToolMessage responses back to their corresponding ToolCall entries."""
     for msg in messages:
         if msg.__class__.__name__ == "ToolMessage":
-            for entry in reversed(incident.tool_calls):
+            for entry in reversed(session.tool_calls):
                 if entry.tool == getattr(msg, "name", None) and entry.result is None:
                     entry.result = getattr(msg, "content", None)
                     break
@@ -9953,18 +9952,18 @@ def _handle_agent_failure(
     store: "SessionStore",
     fallback: "Session",
 ) -> dict:
-    """Reload incident (absorbing partial tool writes), stamp a failure AgentRun,
+    """Reload session (absorbing partial tool writes), stamp a failure AgentRun,
     persist, and return the error state dict for the LangGraph node.
 
-    ``fallback`` is the in-memory incident from the caller; we use it only
+    ``fallback`` is the in-memory session from the caller; we use it only
     when the on-disk state has gone missing (FileNotFoundError on reload).
     """
     try:
-        incident = store.load(inc_id)
+        session = store.load(inc_id)
     except FileNotFoundError:
-        incident = fallback
+        session = fallback
     ended_at = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
-    incident.agents_run.append(AgentRun(
+    session.agents_run.append(AgentRun(
         agent=skill_name, started_at=started_at, ended_at=ended_at,
         summary=f"agent failed: {exc}",
         token_usage=TokenUsage(),
@@ -9972,15 +9971,15 @@ def _handle_agent_failure(
     # Mark the session as terminally failed so the UI can render a
     # retry control. The retry path (``Orchestrator.retry_session``)
     # is the only documented way to move out of this state.
-    incident.status = "error"
-    store.save(incident)
-    return {"session": incident, "next_route": None,
+    session.status = "error"
+    store.save(session)
+    return {"session": session, "next_route": None,
             "last_agent": skill_name, "error": str(exc)}
 
 
 def _record_success_run(
     *,
-    incident: "Session",
+    session: "Session",
     skill_name: str,
     started_at: str,
     final_text: str,
@@ -9990,10 +9989,10 @@ def _record_success_run(
     signal: str | None,
     store: "SessionStore",
 ) -> None:
-    """Append the success-path AgentRun, update the incident's running token
-    totals, and persist. Mutates ``incident`` in place."""
+    """Append the success-path AgentRun, update the session's running token
+    totals, and persist. Mutates ``session`` in place."""
     ended_at = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
-    incident.agents_run.append(AgentRun(
+    session.agents_run.append(AgentRun(
         agent=skill_name, started_at=started_at, ended_at=ended_at,
         summary=final_text or f"{skill_name} completed",
         token_usage=usage,
@@ -10001,10 +10000,10 @@ def _record_success_run(
         confidence_rationale=rationale,
         signal=signal,
     ))
-    incident.token_usage.input_tokens += usage.input_tokens
-    incident.token_usage.output_tokens += usage.output_tokens
-    incident.token_usage.total_tokens += usage.total_tokens
-    store.save(incident)
+    session.token_usage.input_tokens += usage.input_tokens
+    session.token_usage.output_tokens += usage.output_tokens
+    session.token_usage.total_tokens += usage.total_tokens
+    store.save(session)
 
 
 def make_agent_node(
@@ -10066,9 +10065,9 @@ async def node(state: GraphState) -> dict:
         # pending row, appends a duplicate, then ``store.save`` raises
         # ``StaleVersionError`` because DB has already moved on.
         try:
-            incident = store.load(inc_id)
+            session = store.load(inc_id)
         except FileNotFoundError:
-            incident = state_session
+            session = state_session
 
         # M3 (per-step telemetry): emit agent_started.
         if event_log is not None:
@@ -10110,7 +10109,7 @@ async def node(state: GraphState) -> dict:
             # keys from ``accepted_params``, the inject step skips them,
             # and FastMCP rejects the call as missing required arg.
             run_tools = [
-                wrap_tool(t, session=incident, gateway_cfg=gateway_cfg,
+                wrap_tool(t, session=session, gateway_cfg=gateway_cfg,
                           agent_name=skill.name, store=store,
                           injected_args=injected_args or {},
                           gate_policy=gate_policy,
@@ -10156,7 +10155,7 @@ def _run(**kwargs: Any) -> Any:
                 )
 
             run_tools = [
-                _make_inject_only_wrapper(orig, vis, incident)
+                _make_inject_only_wrapper(orig, vis, session)
                 for orig, vis in zip(tools, visible_tools)
             ]
         else:
@@ -10184,7 +10183,7 @@ def _run(**kwargs: Any) -> Any:
         # checkpointer``. The thread id is derived deterministically
         # from session + agent + the upcoming agent_run index so it is:
         #   * STABLE across the inner pause and the outer resume that
-        #     follows (both observe the same ``len(incident.agents_run)``
+        #     follows (both observe the same ``len(session.agents_run)``
         #     because no new run is recorded mid-pause), and
         #   * UNIQUE per agent invocation so previous invocations of the
         #     same agent within the same session don't bleed in.
@@ -10195,7 +10194,7 @@ def _run(**kwargs: Any) -> Any:
             checkpointer=checkpointer,
         )
         inner_thread_id = (
-            f"{inc_id}:agent:{skill.name}:turn{len(incident.agents_run)}"
+            f"{inc_id}:agent:{skill.name}:turn{len(session.agents_run)}"
         )
         inner_cfg = {"configurable": {"thread_id": inner_thread_id}}
 
@@ -10204,7 +10203,7 @@ def _run(**kwargs: Any) -> Any:
         # re-entry from a HITL pause the hint resets cleanly so a new
         # turn starts from "no signal yet" (None).
         try:
-            incident.turn_confidence_hint = None
+            session.turn_confidence_hint = None
         except (AttributeError, ValueError):
             pass
 
@@ -10215,7 +10214,7 @@ def _run(**kwargs: Any) -> Any:
                 inner_has_checkpointer=checkpointer is not None,
                 initial_input={
                     "messages": [
-                        HumanMessage(content=_format_agent_input(incident))
+                        HumanMessage(content=_format_agent_input(session))
                     ]
                 },
             )
@@ -10259,19 +10258,19 @@ def _run(**kwargs: Any) -> Any:
                 else:
                     return _handle_agent_failure(
                         skill_name=skill.name, started_at=started_at, exc=exc,
-                        inc_id=inc_id, store=store, fallback=incident,
+                        inc_id=inc_id, store=store, fallback=session,
                     )
             else:
                 return _handle_agent_failure(
                     skill_name=skill.name, started_at=started_at, exc=exc,
-                    inc_id=inc_id, store=store, fallback=incident,
+                    inc_id=inc_id, store=store, fallback=session,
                 )
 
         # Tools (e.g. registered patch tools) write straight to disk.
         # Reload so the node's own append of agent_run + tool_calls
         # happens against the tool-mutated state — otherwise saving
         # the stale in-memory object clobbers the tools' writes.
-        incident = store.load(inc_id)
+        session = store.load(inc_id)
 
         messages = result.get("messages", [])
         ts = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
@@ -10279,7 +10278,7 @@ def _run(**kwargs: Any) -> Any:
         # Record tool calls and harvest confidence/signal from configured
         # patch / typed-terminal tools.
         agent_confidence, agent_rationale, agent_signal = _harvest_tool_calls_and_patches(
-            messages, skill.name, incident, ts, valid_signals,
+            messages, skill.name, session, ts, valid_signals,
             terminal_tool_names=terminal_tool_names,
             patch_tool_names=patch_tool_names,
         )
@@ -10287,12 +10286,12 @@ def _run(**kwargs: Any) -> Any:
         # tool call sees the harvested confidence at the gateway.
         if agent_confidence is not None:
             try:
-                incident.turn_confidence_hint = agent_confidence
+                session.turn_confidence_hint = agent_confidence
             except (AttributeError, ValueError):
                 pass
 
         # Pair tool responses with their tool calls.
-        _pair_tool_responses(messages, incident)
+        _pair_tool_responses(messages, session)
 
         # Phase 10 (FOC-03 / D-10-03): parse the structural envelope and
         # reconcile its confidence against any typed-terminal-tool arg
@@ -10303,7 +10302,7 @@ def _run(**kwargs: Any) -> Any:
         except EnvelopeMissingError as exc:
             return _handle_agent_failure(
                 skill_name=skill.name, started_at=started_at, exc=exc,
-                inc_id=inc_id, store=store, fallback=incident,
+                inc_id=inc_id, store=store, fallback=session,
             )
 
         terminal_tool_for_log = _first_terminal_tool_called_this_turn(
@@ -10340,12 +10339,12 @@ def _run(**kwargs: Any) -> Any:
                 )
 
         _record_success_run(
-            incident=incident, skill_name=skill.name, started_at=started_at,
+            session=session, skill_name=skill.name, started_at=started_at,
             final_text=final_text, usage=usage,
             confidence=final_confidence, rationale=final_rationale, signal=final_signal,
             store=store,
         )
-        next_route_signal = decide_route(incident)
+        next_route_signal = decide_route(session)
         next_node = route_from_skill(skill, next_route_signal)
 
         # M3: emit route_decided + agent_finished (carrying token_usage).
@@ -10374,7 +10373,7 @@ def _run(**kwargs: Any) -> Any:
                     "event_log.record(agent_finished) failed", exc_info=True,
                 )
 
-        return {"session": incident, "next_route": next_node,
+        return {"session": session, "next_route": next_node,
                 "last_agent": skill.name, "error": None}
 
     return node
@@ -10421,7 +10420,7 @@ def _decide_from_signal(inc: Session) -> str:
 }
 
 
-def _latest_run_for(incident: Session, agent_name: str | None):
+def _latest_run_for(session: Session, agent_name: str | None):
     """Return the most recent ``AgentRun`` for ``agent_name``, or None.
 
     ``agent_name`` is whichever agent ran immediately before the gate,
@@ -10431,7 +10430,7 @@ def _latest_run_for(incident: Session, agent_name: str | None):
     """
     if not agent_name:
         return None
-    for run in reversed(incident.agents_run):
+    for run in reversed(session.agents_run):
         if run.agent == agent_name:
             return run
     return None
@@ -10493,7 +10492,7 @@ async def gate(state: GraphState) -> dict:
         # value on subsequent executions of the same node.
         from langgraph.types import interrupt
 
-        incident = state["session"]  # pyright: ignore[reportTypedDictNotRequiredAccess] — orchestrator runtime always supplies session
+        session = state["session"]  # pyright: ignore[reportTypedDictNotRequiredAccess] — orchestrator runtime always supplies session
         upstream = state.get("last_agent")
         # Capture the intended downstream target before we overwrite next_route.
         # The upstream agent set next_route to the gated target; we stash it in
@@ -10501,13 +10500,13 @@ async def gate(state: GraphState) -> dict:
         intended_target = state.get("next_route")
         # Reload from disk in case earlier nodes wrote tool-driven patches.
         try:
-            incident = store.load(incident.id)
+            session = store.load(session.id)
         except FileNotFoundError:
             pass
-        upstream_run = _latest_run_for(incident, upstream)
+        upstream_run = _latest_run_for(session, upstream)
         upstream_conf = upstream_run.confidence if upstream_run else None
         if upstream_conf is None or upstream_conf < threshold:
-            incident.status = "awaiting_input"
+            session.status = "awaiting_input"
             # Surface the upstream agent's own summary + rationale so the
             # human reviewer can decide what input to give without scrolling
             # through every step of the agents-run log.
@@ -10522,13 +10521,13 @@ async def gate(state: GraphState) -> dict:
                 "escalation_teams": teams,
                 "intended_target": intended_target,
             }
-            incident.pending_intervention = payload
+            session.pending_intervention = payload
             # CRITICAL ORDERING: persist the Session row BEFORE calling
             # ``interrupt()``. ``interrupt()`` raises ``GraphInterrupt`` on
             # first execution; if we reversed the order the UI (which
             # polls Session.pending_intervention) would never see the
             # pending state. See plan R4 / "Streamlit hand-off".
-            store.save(incident)
+            store.save(session)
             # First execution: this raises GraphInterrupt and the
             # checkpointer captures the paused state.
             # Resume: this returns the value supplied via
@@ -10551,17 +10550,17 @@ async def gate(state: GraphState) -> dict:
                 if isinstance(raw, str) and raw.strip():
                     user_text = raw.strip()
             if user_text is not None:
-                incident.user_inputs.append(user_text)
-            incident.pending_intervention = None
-            incident.status = "in_progress"
-            store.save(incident)
-            return {"session": incident, "next_route": "default",
+                session.user_inputs.append(user_text)
+            session.pending_intervention = None
+            session.status = "in_progress"
+            store.save(session)
+            return {"session": session, "next_route": "default",
                     "gated_target": intended_target, "last_agent": "gate", "error": None}
         # Confidence met threshold — clear any stale intervention payload.
-        if incident.pending_intervention is not None:
-            incident.pending_intervention = None
-            store.save(incident)
-        return {"session": incident, "next_route": "default",
+        if session.pending_intervention is not None:
+            session.pending_intervention = None
+            store.save(session)
+        return {"session": session, "next_route": "default",
                 "gated_target": intended_target, "last_agent": "gate", "error": None}
 
     return gate
@@ -11909,7 +11908,7 @@ class DedupConfig(BaseModel):
     All numeric thresholds are inclusive at the lower bound (``>=``),
     so a candidate hitting exactly ``stage1_threshold`` is considered.
 
-    Defaults are tuned for the incident-management example. Apps that
+    Defaults are tuned for the example app. Apps that
     want different policies override via YAML.
     """
 
@@ -11941,7 +11940,7 @@ def assert_model_exists(self, llm_cfg: "LLMConfig") -> None:
         """Fail fast if ``stage2_model`` is missing from the LLM registry.
 
         Called at orchestrator boot when dedup is enabled. Raising here
-        is preferred over discovering the typo on the first incident.
+        is preferred over discovering the typo on the first session.
         """
         if self.stage2_model not in llm_cfg.models:
             raise ValueError(
@@ -12190,7 +12189,7 @@ def _stage1(
             if env:
                 filter_kwargs["environment"] = env
         # ``status_filter`` is the resolved session bucket — only_closed
-        # maps to "resolved" in the incident-management vocabulary.
+        # maps to "resolved" in the example app vocabulary.
         # Apps that disable only_closed get all statuses other than
         # in-flight via the empty filter (HistoryStore default behaviour
         # already screens deleted rows).
@@ -13546,7 +13545,7 @@ def _assert_envelope_invariant_on_finalize(session: "Session") -> None:
 
 
 def _default_text_extractor(session) -> str:
-    """Default text extraction for the incident-management example.
+    """Default text extraction for the example incident-management app.
 
     Concatenates the operator-supplied ``query``, the intake-summary
     (when present), and any tags. Keeps the framework agnostic of the
@@ -14651,10 +14650,10 @@ async def start_session(self, *, query: str,
         kwargs once the row schema is fully generic).
 
         ``submitter`` is a free-form dict the app interprets. For
-        incident-management it is ``{"id": "...", "team": "..."}``; for
+        the example incident-management app it is ``{"id": "...", "team": "..."}``; for
         other apps it can carry app-specific keys (e.g. code-review's
         ``{"id": "<github-username>", "pr_url": "..."}``). The framework
-        only projects ``id``/``team`` onto the row's reporter columns;
+        only projects ``id``/``team`` onto the row's submitter columns;
         apps unpack the rest via their own MCP tools.
 
         Deprecated kwargs (coerced into ``state_overrides`` / ``submitter``
@@ -14732,7 +14731,7 @@ async def stream_session(self, *, query: str, environment: str,
                              ) -> AsyncIterator[dict]:
         """Start a new session and stream UI events as it runs.
 
-        Internally builds a ``submitter`` dict so the row's reporter
+        Internally builds a ``submitter`` dict so the row's submitter
         columns are populated through the same coercion path
         ``start_session`` uses.
         """
@@ -14782,7 +14781,7 @@ async def stream_investigation(self, *, query: str, environment: str,
         """Deprecated alias for ``stream_session``.
 
         Forwards the legacy positional surface into ``stream_session``;
-        the underlying flow already coerces the reporter pair into
+        the underlying flow already coerces the submitter pair into
         a submitter dict internally so no runtime deprecation fires.
         """
         async for event in self.stream_session(
diff --git a/dist/apps/code-review.py b/dist/apps/code-review.py
index 3ad249b..d437b45 100644
--- a/dist/apps/code-review.py
+++ b/dist/apps/code-review.py
@@ -51,7 +51,7 @@
 
     class IncidentState(Session):
         environment: str
-        reporter: Reporter
+        submitter: Submitter
         ...
 
 ``Session`` deliberately contains *no* domain-specific fields. Adding one
@@ -86,7 +86,7 @@ class IncidentState(Session):
 
 
 # ----- imports for runtime/similarity.py -----
-"""Similarity scoring for incident matching."""
+"""Similarity scoring for session matching."""
 
 from typing import Protocol
 
@@ -265,8 +265,8 @@ class IncidentState(Session):
 
 ``find_similar`` accepts an arbitrary ``filter_kwargs`` mapping — keys
 must correspond to ``IncidentRow`` columns. This decouples the
-framework from incident-specific filter dimensions: apps with a
-``severity``-only schema, or a multi-tenant ``tenant_id`` schema, or
+framework from app-specific filter dimensions: apps with a
+schema with a single status-tier field, a multi-tenant ``tenant_id`` schema, or
 anything else, build their filter on the fly.
 """
 
@@ -297,7 +297,7 @@ class IncidentState(Session):
 The class is parametrised as ``Generic[StateT]`` and routes row
 hydration through ``self._state_cls(...)`` so apps can plug in their
 own ``Session`` subclass via ``RuntimeConfig.state_class``. The row
-schema remains incident-shaped, but unused fields are dropped via
+schema remains the row-level shape, but unused fields are dropped via
 Pydantic's default ``extra='ignore'`` when a narrower ``state_cls`` is
 supplied.
 """
@@ -1113,7 +1113,7 @@ async def _poll(self, registry):
 structured output {is_duplicate, confidence, rationale}.
 
 The pipeline is **framework-level** and never imports the
-incident-management state class (R4 in the Phase-7 plan). Apps inject
+domain-specific Session subclass (R4 in the Phase-7 plan). Apps inject
 domain-specific text via a ``text_extractor: Callable[[Session], str]``
 callable.
 
@@ -1737,7 +1737,7 @@ class MCPConfig(BaseModel):
 
 
 class MetadataConfig(BaseModel):
-    """Relational store for incident metadata. SQLite (dev) or Postgres (prod)."""
+    """Relational store for session metadata. SQLite (dev) or Postgres (prod)."""
     url: str = "sqlite:///incidents/incidents.db"
     pool_size: int = 5      # postgres only; sqlite uses NullPool
     echo: bool = False
@@ -2569,7 +2569,7 @@ def to_agent_input(self) -> str:
 
         Apps subclass ``Session`` and override this to surface the
         domain shape (``Incident X / Environment Y / Query Z`` for the
-        incident-management app, ``PR title / repo / diff stats`` for
+        example app, ``PR title / repo / diff stats`` for
         code review, etc.). The framework default keeps the prompt
         framework-agnostic — id + status only — so that any app that
         has not overridden the hook still gets a usable preamble.
@@ -2601,7 +2601,7 @@ def id_format(cls, *, seq: int, prefix: str = "SES") -> str:
 
         ``prefix`` is supplied by ``SessionStore._next_id`` from
         ``FrameworkAppConfig.session_id_prefix`` so each app picks its
-        own namespace via plain config (e.g. ``INC`` for incident
+        own namespace via plain config (e.g. ``INC`` for the example incident
         management, ``REVIEW`` for code review, ``HR`` for HR cases,
         ...). Apps with truly bespoke id shapes can still override this
         classmethod on their ``Session`` subclass and ignore ``prefix``.
@@ -4168,7 +4168,7 @@ def _ef(i, key, default: Any = ""):
                     _ef(i, "summary", "") or "",
                     " ".join(_ef(i, "tags", []) or []),
                 ])),
-                "incident": i,
+                "session": i,
             }
             for i in candidates_inc
         ]
@@ -4178,7 +4178,7 @@ def _ef(i, key, default: Any = ""):
             threshold=self.similarity_threshold if threshold is None else threshold,
             limit=limit,
         )
-        return [(c["incident"], float(s)) for c, s in results]
+        return [(c["session"], float(s)) for c, s in results]
 
 # ====== module: runtime/storage/session_store.py ======
 
@@ -4260,7 +4260,7 @@ class StaleVersionError(RuntimeError):
 
 
 class SessionStore(Generic[StateT]):
-    """Active session/incident lifecycle store, parametrised on ``StateT``.
+    """Active session lifecycle store, parametrised on ``StateT``.
 
     Owns CRUD on the row schema plus the vector write-through. Read-only
     similarity search lives in ``HistoryStore``.
@@ -4379,7 +4379,7 @@ def create(self, *, query: str, environment: str,
     def load(self, incident_id: str) -> StateT:
         if not _SESSION_ID_RE.match(incident_id):
             raise ValueError(
-                f"Invalid incident id {incident_id!r}; expected PREFIX-YYYYMMDD-NNN"
+                f"Invalid session id {incident_id!r}; expected PREFIX-YYYYMMDD-NNN"
             )
         with SqlSession(self.engine) as session:
             row = session.get(IncidentRow, incident_id)
@@ -4387,40 +4387,39 @@ def load(self, incident_id: str) -> StateT:
                 raise FileNotFoundError(incident_id)
             return self._row_to_incident(row)
 
-    def save(self, incident: StateT) -> None:
-        if not _SESSION_ID_RE.match(incident.id):
+    def save(self, session: StateT) -> None:
+        if not _SESSION_ID_RE.match(session.id):
             raise ValueError(
-                f"Invalid incident id {incident.id!r}; expected PREFIX-YYYYMMDD-NNN"
+                f"Invalid session id {session.id!r}; expected PREFIX-YYYYMMDD-NNN"
             )
         # ``_iso(_now())`` returns ``str`` here -- the input datetime is
         # never None -- but the helper's signature is the broader
         # ``Optional[str]``. ``or ""`` keeps pyright + the typed
         # ``Session.updated_at: str`` field consistent without changing
         # behaviour (real value is always present).
-        incident.updated_at = _iso(_now()) or ""
-        sess = incident  # local alias — avoids repeating the domain token in new code
-        expected_version = getattr(sess, "version", 1)
+        session.updated_at = _iso(_now()) or ""
+        expected_version = getattr(session, "version", 1)
         # Bump in-memory BEFORE building the row dict so the persisted
         # row reflects the new version.
-        sess.version = expected_version + 1
-        with SqlSession(self.engine) as session:
-            existing = session.get(IncidentRow, sess.id)
+        session.version = expected_version + 1
+        with SqlSession(self.engine) as db_session:
+            existing = db_session.get(IncidentRow, session.id)
             prior_text = _embed_source_from_row(existing) if existing is not None else ""
             if existing is not None and existing.version != expected_version:
                 # Roll back the in-memory bump so the caller can reload + retry.
-                sess.version = expected_version
+                session.version = expected_version
                 raise StaleVersionError(
-                    f"session {sess.id} version is {existing.version}, "
+                    f"session {session.id} version is {existing.version}, "
                     f"expected {expected_version}"
                 )
-            data = self._incident_to_row_dict(incident)
+            data = self._incident_to_row_dict(session)
             if existing is None:
-                session.add(IncidentRow(**data))
+                db_session.add(IncidentRow(**data))
             else:
                 for k, v in data.items():
                     setattr(existing, k, v)
-            session.commit()
-        self._refresh_vector(incident, prior_text=prior_text)
+            db_session.commit()
+        self._refresh_vector(session, prior_text=prior_text)
 
     def delete(self, incident_id: str) -> StateT:
         with SqlSession(self.engine) as session:
@@ -4619,10 +4618,10 @@ def _row_to_incident(self, row: IncidentRow) -> StateT:
 
         Fields are pulled from typed columns when the state class
         declares them; everything else is merged in from the
-        ``extra_fields`` JSON bag. ``reporter`` is reconstituted from
+        ``extra_fields`` JSON bag. The ``reporter`` field (when present) is reconstituted from
         the typed ``reporter_id`` / ``reporter_team`` columns *only* when
-        the state class has a ``reporter`` field — otherwise it's
-        omitted so apps without a reporter concept (code-review) don't
+        the state class declares it — otherwise it's
+        omitted so apps without that concept (code-review) don't
         receive an unexpected attribute.
         """
         model_fields = self._state_cls.model_fields
@@ -6184,10 +6183,10 @@ def start_session(
         through to app-specific MCP tools.
 
         ``submitter`` is a free-form dict the calling app interprets.
-        For incident-management it is ``{"id": "...", "team": "..."}``;
+        For the example incident-management app it is ``{"id": "...", "team": "..."}``;
         other apps can carry app-specific keys (e.g. code-review's
         ``{"id": "<github-username>", "pr_url": "..."}``). The framework
-        only projects ``id``/``team`` onto the row's reporter columns.
+        only projects ``id``/``team`` onto the row's submitter columns.
 
         Deprecated kwargs (coerced and warned):
           * ``environment`` -> ``state_overrides={"environment": ...}``
@@ -8579,9 +8578,9 @@ async def node(state: GraphState) -> dict:
         # the same reload comment in ``runtime.graph.make_agent_node``
         # for the full rationale.
         try:
-            incident: Session = store.load(inc_id)
+            session: Session = store.load(inc_id)
         except FileNotFoundError:
-            incident = state_session
+            session = state_session
 
         # M3: emit agent_started telemetry before any work happens.
         if event_log is not None:
@@ -8599,7 +8598,7 @@ async def node(state: GraphState) -> dict:
         # live ``Session`` for this run.
         if gateway_cfg is not None:
             run_tools = [
-                wrap_tool(t, session=incident, gateway_cfg=gateway_cfg,
+                wrap_tool(t, session=session, gateway_cfg=gateway_cfg,
                           agent_name=skill.name, store=store,
                           gate_policy=gate_policy,
                           event_log=event_log)
@@ -8623,7 +8622,7 @@ async def node(state: GraphState) -> dict:
             checkpointer=checkpointer,
         )
         inner_thread_id = (
-            f"{inc_id}:agent:{skill.name}:turn{len(incident.agents_run)}"
+            f"{inc_id}:agent:{skill.name}:turn{len(session.agents_run)}"
         )
         inner_cfg = {"configurable": {"thread_id": inner_thread_id}}
 
@@ -8631,7 +8630,7 @@ async def node(state: GraphState) -> dict:
         # start of each agent step so the gateway treats the first
         # tool call of the turn as "no signal yet".
         try:
-            incident.turn_confidence_hint = None
+            session.turn_confidence_hint = None
         except (AttributeError, ValueError):
             pass
 
@@ -8642,7 +8641,7 @@ async def node(state: GraphState) -> dict:
                 inner_has_checkpointer=checkpointer is not None,
                 initial_input={
                     "messages": [
-                        HumanMessage(content=_format_agent_input(incident))
+                        HumanMessage(content=_format_agent_input(session))
                     ]
                 },
             )
@@ -8652,19 +8651,19 @@ async def node(state: GraphState) -> dict:
         except Exception as exc:  # noqa: BLE001
             return _handle_agent_failure(
                 skill_name=skill.name, started_at=started_at, exc=exc,
-                inc_id=inc_id, store=store, fallback=incident,
+                inc_id=inc_id, store=store, fallback=session,
             )
 
         # Tools (e.g. registered patch tools) write straight to disk.
         # Reload so the node's own append of agent_run + tool_calls
         # happens against the tool-mutated state.
-        incident = store.load(inc_id)
+        session = store.load(inc_id)
 
         messages = result.get("messages", [])
         ts = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
 
         agent_confidence, agent_rationale, agent_signal = _harvest_tool_calls_and_patches(
-            messages, skill.name, incident, ts, valid_signals,
+            messages, skill.name, session, ts, valid_signals,
             terminal_tool_names=terminal_tool_names,
             patch_tool_names=patch_tool_names,
         )
@@ -8672,10 +8671,10 @@ async def node(state: GraphState) -> dict:
         # tool call sees the harvested confidence.
         if agent_confidence is not None:
             try:
-                incident.turn_confidence_hint = agent_confidence
+                session.turn_confidence_hint = agent_confidence
             except (AttributeError, ValueError):
                 pass
-        _pair_tool_responses(messages, incident)
+        _pair_tool_responses(messages, session)
 
         # Phase 10 (FOC-03 / D-10-03): parse envelope; reconcile against
         # any typed-terminal-tool-arg confidence. Envelope failure is a
@@ -8685,7 +8684,7 @@ async def node(state: GraphState) -> dict:
         except EnvelopeMissingError as exc:
             return _handle_agent_failure(
                 skill_name=skill.name, started_at=started_at, exc=exc,
-                inc_id=inc_id, store=store, fallback=incident,
+                inc_id=inc_id, store=store, fallback=session,
             )
 
         terminal_tool_for_log = _first_terminal_tool_called_this_turn(
@@ -8721,13 +8720,13 @@ async def node(state: GraphState) -> dict:
                 )
 
         _record_success_run(
-            incident=incident, skill_name=skill.name, started_at=started_at,
+            session=session, skill_name=skill.name, started_at=started_at,
             final_text=final_text, usage=usage,
             confidence=final_confidence, rationale=final_rationale,
             signal=final_signal,
             store=store,
         )
-        next_route_signal = decide_route(incident)
+        next_route_signal = decide_route(session)
         next_node = route_from_skill(skill, next_route_signal)
 
         # M3: emit route_decided + agent_finished. agent_finished carries
@@ -8758,7 +8757,7 @@ async def node(state: GraphState) -> dict:
                     "event_log.record(agent_finished) failed", exc_info=True,
                 )
 
-        return {"session": incident, "next_route": next_node,
+        return {"session": session, "next_route": next_node,
                 "last_agent": skill.name, "error": None}
 
     return node
@@ -8791,7 +8790,7 @@ def _safe_eval(expr: str, ctx: dict[str, Any]) -> Any:
     return eval(code, {"__builtins__": {}}, ctx)  # noqa: S307 — AST-whitelisted
 
 
-def _ctx_for_session(incident: Session) -> dict[str, Any]:
+def _ctx_for_session(session: Session) -> dict[str, Any]:
     """Build the variable namespace dispatch-rule expressions see.
 
     Exposes the live session payload as ``session`` plus a few
@@ -8800,7 +8799,7 @@ def _ctx_for_session(incident: Session) -> dict[str, Any]:
     AST checker already restricts the language so we don't need to
     sandbox the namespace any further.
     """
-    payload = incident.model_dump()
+    payload = session.model_dump()
     return {
         "session": payload,
         "status": payload.get("status"),
@@ -8846,7 +8845,7 @@ def _llm_pick_target(
     *,
     skill: Skill,
     llm: BaseChatModel,
-    incident: Session,
+    session: Session,
 ) -> str:
     """One-shot LLM dispatch: ask the model to choose a subordinate.
 
@@ -8861,7 +8860,7 @@ def _llm_pick_target(
         f"Choose ONE of: {', '.join(skill.subordinates)}.\n"
         f"Reply with only the agent name."
     )
-    payload = json.dumps(incident.model_dump(), default=str)
+    payload = json.dumps(session.model_dump(), default=str)
     msgs = [
         SystemMessage(content=prompt),
         HumanMessage(content=payload),
@@ -8888,7 +8887,7 @@ def _llm_pick_target(
 def _rule_pick_target(
     *,
     skill: Skill,
-    incident: Session,
+    session: Session,
 ) -> tuple[str, str | None]:
     """Walk dispatch_rules in order; return (target, matched_when).
 
@@ -8896,7 +8895,7 @@ def _rule_pick_target(
     fallback case carries ``matched_when=None`` so the audit log can
     distinguish "default" from "rule X matched".
     """
-    ctx = _ctx_for_session(incident)
+    ctx = _ctx_for_session(session)
     for rule in skill.dispatch_rules:
         try:
             if bool(_safe_eval(rule.when, ctx)):
@@ -9071,7 +9070,7 @@ async def node(state: GraphState) -> dict:
 
         rule_matched: str | None = None
         if skill.dispatch_strategy == "rule":
-            target, rule_matched = _rule_pick_target(skill=skill, incident=sess)
+            target, rule_matched = _rule_pick_target(skill=skill, session=sess)
         else:  # "llm"
             if llm is None:
                 logger.warning(
@@ -9080,7 +9079,7 @@ async def node(state: GraphState) -> dict:
                 )
                 target = skill.subordinates[0]
             else:
-                target = _llm_pick_target(skill=skill, llm=llm, incident=sess)
+                target = _llm_pick_target(skill=skill, llm=llm, session=sess)
 
         # Audit: one structured log entry per dispatch.
         try:
@@ -9580,11 +9579,11 @@ def route_from_skill(skill: Skill, signal: str) -> str:
 
 
 class AgentRunRecorder:
-    """Helper to capture an agent's run + tool calls into the incident."""
+    """Helper to capture an agent's run + tool calls into the session."""
 
-    def __init__(self, *, agent: str, incident: Session):
+    def __init__(self, *, agent: str, session: Session):
         self.agent = agent
-        self.incident = incident
+        self.session = session
         self._started_at: str | None = None
 
     def start(self) -> None:
@@ -9592,13 +9591,13 @@ def start(self) -> None:
 
     def record_tool_call(self, tool: str, args: dict, result) -> None:
         ts = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
-        self.incident.tool_calls.append(
+        self.session.tool_calls.append(
             ToolCall(agent=self.agent, tool=tool, args=args, result=result, ts=ts)
         )
 
     def finish(self, *, summary: str) -> None:
         ended_at = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
-        self.incident.agents_run.append(AgentRun(
+        self.session.agents_run.append(AgentRun(
             agent=self.agent,
             started_at=self._started_at or ended_at,
             ended_at=ended_at,
@@ -9758,7 +9757,7 @@ async def _ainvoke_with_retry(executor, input_, *, max_attempts: int = 3,
     raise last_exc or RuntimeError("retry exhausted with no attempts")  # pragma: no cover
 
 
-def _format_agent_input(incident: Session) -> str:
+def _format_agent_input(session: Session) -> str:
     """Build the human-message preamble each agent receives.
 
     Delegates to ``Session.to_agent_input`` so each app subclass owns the
@@ -9766,7 +9765,7 @@ def _format_agent_input(incident: Session) -> str:
     session id + status; ``IncidentState`` and ``CodeReviewState``
     override with their respective shapes.
     """
-    return incident.to_agent_input()
+    return session.to_agent_input()
 
 
 def _merge_patch_metadata(
@@ -9840,7 +9839,7 @@ def _harvest_patch_tool(
 def _harvest_tool_calls_and_patches(
     messages: list,
     skill_name: str,
-    incident: Session,
+    session: Session,
     ts: str,
     valid_signals: frozenset[str] | None = None,
     terminal_tool_names: frozenset[str] = frozenset(),
@@ -9883,7 +9882,7 @@ def _harvest_tool_calls_and_patches(
             # colon; rsplit on the rightmost colon recovers the bare
             # tool name for both prefixed and unprefixed forms.
             tc_original = tc_name.rsplit(":", 1)[-1]
-            incident.tool_calls.append(ToolCall(
+            session.tool_calls.append(ToolCall(
                 agent=skill_name, tool=tc_name, args=tc_args,
                 result=None, ts=ts,
             ))
@@ -9897,11 +9896,11 @@ def _harvest_tool_calls_and_patches(
     return state
 
 
-def _pair_tool_responses(messages: list, incident: Session) -> None:
+def _pair_tool_responses(messages: list, session: Session) -> None:
     """Match ToolMessage responses back to their corresponding ToolCall entries."""
     for msg in messages:
         if msg.__class__.__name__ == "ToolMessage":
-            for entry in reversed(incident.tool_calls):
+            for entry in reversed(session.tool_calls):
                 if entry.tool == getattr(msg, "name", None) and entry.result is None:
                     entry.result = getattr(msg, "content", None)
                     break
@@ -10006,18 +10005,18 @@ def _handle_agent_failure(
     store: "SessionStore",
     fallback: "Session",
 ) -> dict:
-    """Reload incident (absorbing partial tool writes), stamp a failure AgentRun,
+    """Reload session (absorbing partial tool writes), stamp a failure AgentRun,
     persist, and return the error state dict for the LangGraph node.
 
-    ``fallback`` is the in-memory incident from the caller; we use it only
+    ``fallback`` is the in-memory session from the caller; we use it only
     when the on-disk state has gone missing (FileNotFoundError on reload).
     """
     try:
-        incident = store.load(inc_id)
+        session = store.load(inc_id)
     except FileNotFoundError:
-        incident = fallback
+        session = fallback
     ended_at = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
-    incident.agents_run.append(AgentRun(
+    session.agents_run.append(AgentRun(
         agent=skill_name, started_at=started_at, ended_at=ended_at,
         summary=f"agent failed: {exc}",
         token_usage=TokenUsage(),
@@ -10025,15 +10024,15 @@ def _handle_agent_failure(
     # Mark the session as terminally failed so the UI can render a
     # retry control. The retry path (``Orchestrator.retry_session``)
     # is the only documented way to move out of this state.
-    incident.status = "error"
-    store.save(incident)
-    return {"session": incident, "next_route": None,
+    session.status = "error"
+    store.save(session)
+    return {"session": session, "next_route": None,
             "last_agent": skill_name, "error": str(exc)}
 
 
 def _record_success_run(
     *,
-    incident: "Session",
+    session: "Session",
     skill_name: str,
     started_at: str,
     final_text: str,
@@ -10043,10 +10042,10 @@ def _record_success_run(
     signal: str | None,
     store: "SessionStore",
 ) -> None:
-    """Append the success-path AgentRun, update the incident's running token
-    totals, and persist. Mutates ``incident`` in place."""
+    """Append the success-path AgentRun, update the session's running token
+    totals, and persist. Mutates ``session`` in place."""
     ended_at = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
-    incident.agents_run.append(AgentRun(
+    session.agents_run.append(AgentRun(
         agent=skill_name, started_at=started_at, ended_at=ended_at,
         summary=final_text or f"{skill_name} completed",
         token_usage=usage,
@@ -10054,10 +10053,10 @@ def _record_success_run(
         confidence_rationale=rationale,
         signal=signal,
     ))
-    incident.token_usage.input_tokens += usage.input_tokens
-    incident.token_usage.output_tokens += usage.output_tokens
-    incident.token_usage.total_tokens += usage.total_tokens
-    store.save(incident)
+    session.token_usage.input_tokens += usage.input_tokens
+    session.token_usage.output_tokens += usage.output_tokens
+    session.token_usage.total_tokens += usage.total_tokens
+    store.save(session)
 
 
 def make_agent_node(
@@ -10119,9 +10118,9 @@ async def node(state: GraphState) -> dict:
         # pending row, appends a duplicate, then ``store.save`` raises
         # ``StaleVersionError`` because DB has already moved on.
         try:
-            incident = store.load(inc_id)
+            session = store.load(inc_id)
         except FileNotFoundError:
-            incident = state_session
+            session = state_session
 
         # M3 (per-step telemetry): emit agent_started.
         if event_log is not None:
@@ -10163,7 +10162,7 @@ async def node(state: GraphState) -> dict:
             # keys from ``accepted_params``, the inject step skips them,
             # and FastMCP rejects the call as missing required arg.
             run_tools = [
-                wrap_tool(t, session=incident, gateway_cfg=gateway_cfg,
+                wrap_tool(t, session=session, gateway_cfg=gateway_cfg,
                           agent_name=skill.name, store=store,
                           injected_args=injected_args or {},
                           gate_policy=gate_policy,
@@ -10209,7 +10208,7 @@ def _run(**kwargs: Any) -> Any:
                 )
 
             run_tools = [
-                _make_inject_only_wrapper(orig, vis, incident)
+                _make_inject_only_wrapper(orig, vis, session)
                 for orig, vis in zip(tools, visible_tools)
             ]
         else:
@@ -10237,7 +10236,7 @@ def _run(**kwargs: Any) -> Any:
         # checkpointer``. The thread id is derived deterministically
         # from session + agent + the upcoming agent_run index so it is:
         #   * STABLE across the inner pause and the outer resume that
-        #     follows (both observe the same ``len(incident.agents_run)``
+        #     follows (both observe the same ``len(session.agents_run)``
         #     because no new run is recorded mid-pause), and
         #   * UNIQUE per agent invocation so previous invocations of the
         #     same agent within the same session don't bleed in.
@@ -10248,7 +10247,7 @@ def _run(**kwargs: Any) -> Any:
             checkpointer=checkpointer,
         )
         inner_thread_id = (
-            f"{inc_id}:agent:{skill.name}:turn{len(incident.agents_run)}"
+            f"{inc_id}:agent:{skill.name}:turn{len(session.agents_run)}"
         )
         inner_cfg = {"configurable": {"thread_id": inner_thread_id}}
 
@@ -10257,7 +10256,7 @@ def _run(**kwargs: Any) -> Any:
         # re-entry from a HITL pause the hint resets cleanly so a new
         # turn starts from "no signal yet" (None).
         try:
-            incident.turn_confidence_hint = None
+            session.turn_confidence_hint = None
         except (AttributeError, ValueError):
             pass
 
@@ -10268,7 +10267,7 @@ def _run(**kwargs: Any) -> Any:
                 inner_has_checkpointer=checkpointer is not None,
                 initial_input={
                     "messages": [
-                        HumanMessage(content=_format_agent_input(incident))
+                        HumanMessage(content=_format_agent_input(session))
                     ]
                 },
             )
@@ -10312,19 +10311,19 @@ def _run(**kwargs: Any) -> Any:
                 else:
                     return _handle_agent_failure(
                         skill_name=skill.name, started_at=started_at, exc=exc,
-                        inc_id=inc_id, store=store, fallback=incident,
+                        inc_id=inc_id, store=store, fallback=session,
                     )
             else:
                 return _handle_agent_failure(
                     skill_name=skill.name, started_at=started_at, exc=exc,
-                    inc_id=inc_id, store=store, fallback=incident,
+                    inc_id=inc_id, store=store, fallback=session,
                 )
 
         # Tools (e.g. registered patch tools) write straight to disk.
         # Reload so the node's own append of agent_run + tool_calls
         # happens against the tool-mutated state — otherwise saving
         # the stale in-memory object clobbers the tools' writes.
-        incident = store.load(inc_id)
+        session = store.load(inc_id)
 
         messages = result.get("messages", [])
         ts = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
@@ -10332,7 +10331,7 @@ def _run(**kwargs: Any) -> Any:
         # Record tool calls and harvest confidence/signal from configured
         # patch / typed-terminal tools.
         agent_confidence, agent_rationale, agent_signal = _harvest_tool_calls_and_patches(
-            messages, skill.name, incident, ts, valid_signals,
+            messages, skill.name, session, ts, valid_signals,
             terminal_tool_names=terminal_tool_names,
             patch_tool_names=patch_tool_names,
         )
@@ -10340,12 +10339,12 @@ def _run(**kwargs: Any) -> Any:
         # tool call sees the harvested confidence at the gateway.
         if agent_confidence is not None:
             try:
-                incident.turn_confidence_hint = agent_confidence
+                session.turn_confidence_hint = agent_confidence
             except (AttributeError, ValueError):
                 pass
 
         # Pair tool responses with their tool calls.
-        _pair_tool_responses(messages, incident)
+        _pair_tool_responses(messages, session)
 
         # Phase 10 (FOC-03 / D-10-03): parse the structural envelope and
         # reconcile its confidence against any typed-terminal-tool arg
@@ -10356,7 +10355,7 @@ def _run(**kwargs: Any) -> Any:
         except EnvelopeMissingError as exc:
             return _handle_agent_failure(
                 skill_name=skill.name, started_at=started_at, exc=exc,
-                inc_id=inc_id, store=store, fallback=incident,
+                inc_id=inc_id, store=store, fallback=session,
             )
 
         terminal_tool_for_log = _first_terminal_tool_called_this_turn(
@@ -10393,12 +10392,12 @@ def _run(**kwargs: Any) -> Any:
                 )
 
         _record_success_run(
-            incident=incident, skill_name=skill.name, started_at=started_at,
+            session=session, skill_name=skill.name, started_at=started_at,
             final_text=final_text, usage=usage,
             confidence=final_confidence, rationale=final_rationale, signal=final_signal,
             store=store,
         )
-        next_route_signal = decide_route(incident)
+        next_route_signal = decide_route(session)
         next_node = route_from_skill(skill, next_route_signal)
 
         # M3: emit route_decided + agent_finished (carrying token_usage).
@@ -10427,7 +10426,7 @@ def _run(**kwargs: Any) -> Any:
                     "event_log.record(agent_finished) failed", exc_info=True,
                 )
 
-        return {"session": incident, "next_route": next_node,
+        return {"session": session, "next_route": next_node,
                 "last_agent": skill.name, "error": None}
 
     return node
@@ -10474,7 +10473,7 @@ def _decide_from_signal(inc: Session) -> str:
 }
 
 
-def _latest_run_for(incident: Session, agent_name: str | None):
+def _latest_run_for(session: Session, agent_name: str | None):
     """Return the most recent ``AgentRun`` for ``agent_name``, or None.
 
     ``agent_name`` is whichever agent ran immediately before the gate,
@@ -10484,7 +10483,7 @@ def _latest_run_for(incident: Session, agent_name: str | None):
     """
     if not agent_name:
         return None
-    for run in reversed(incident.agents_run):
+    for run in reversed(session.agents_run):
         if run.agent == agent_name:
             return run
     return None
@@ -10546,7 +10545,7 @@ async def gate(state: GraphState) -> dict:
         # value on subsequent executions of the same node.
         from langgraph.types import interrupt
 
-        incident = state["session"]  # pyright: ignore[reportTypedDictNotRequiredAccess] — orchestrator runtime always supplies session
+        session = state["session"]  # pyright: ignore[reportTypedDictNotRequiredAccess] — orchestrator runtime always supplies session
         upstream = state.get("last_agent")
         # Capture the intended downstream target before we overwrite next_route.
         # The upstream agent set next_route to the gated target; we stash it in
@@ -10554,13 +10553,13 @@ async def gate(state: GraphState) -> dict:
         intended_target = state.get("next_route")
         # Reload from disk in case earlier nodes wrote tool-driven patches.
         try:
-            incident = store.load(incident.id)
+            session = store.load(session.id)
         except FileNotFoundError:
             pass
-        upstream_run = _latest_run_for(incident, upstream)
+        upstream_run = _latest_run_for(session, upstream)
         upstream_conf = upstream_run.confidence if upstream_run else None
         if upstream_conf is None or upstream_conf < threshold:
-            incident.status = "awaiting_input"
+            session.status = "awaiting_input"
             # Surface the upstream agent's own summary + rationale so the
             # human reviewer can decide what input to give without scrolling
             # through every step of the agents-run log.
@@ -10575,13 +10574,13 @@ async def gate(state: GraphState) -> dict:
                 "escalation_teams": teams,
                 "intended_target": intended_target,
             }
-            incident.pending_intervention = payload
+            session.pending_intervention = payload
             # CRITICAL ORDERING: persist the Session row BEFORE calling
             # ``interrupt()``. ``interrupt()`` raises ``GraphInterrupt`` on
             # first execution; if we reversed the order the UI (which
             # polls Session.pending_intervention) would never see the
             # pending state. See plan R4 / "Streamlit hand-off".
-            store.save(incident)
+            store.save(session)
             # First execution: this raises GraphInterrupt and the
             # checkpointer captures the paused state.
             # Resume: this returns the value supplied via
@@ -10604,17 +10603,17 @@ async def gate(state: GraphState) -> dict:
                 if isinstance(raw, str) and raw.strip():
                     user_text = raw.strip()
             if user_text is not None:
-                incident.user_inputs.append(user_text)
-            incident.pending_intervention = None
-            incident.status = "in_progress"
-            store.save(incident)
-            return {"session": incident, "next_route": "default",
+                session.user_inputs.append(user_text)
+            session.pending_intervention = None
+            session.status = "in_progress"
+            store.save(session)
+            return {"session": session, "next_route": "default",
                     "gated_target": intended_target, "last_agent": "gate", "error": None}
         # Confidence met threshold — clear any stale intervention payload.
-        if incident.pending_intervention is not None:
-            incident.pending_intervention = None
-            store.save(incident)
-        return {"session": incident, "next_route": "default",
+        if session.pending_intervention is not None:
+            session.pending_intervention = None
+            store.save(session)
+        return {"session": session, "next_route": "default",
                 "gated_target": intended_target, "last_agent": "gate", "error": None}
 
     return gate
@@ -11962,7 +11961,7 @@ class DedupConfig(BaseModel):
     All numeric thresholds are inclusive at the lower bound (``>=``),
     so a candidate hitting exactly ``stage1_threshold`` is considered.
 
-    Defaults are tuned for the incident-management example. Apps that
+    Defaults are tuned for the example app. Apps that
     want different policies override via YAML.
     """
 
@@ -11994,7 +11993,7 @@ def assert_model_exists(self, llm_cfg: "LLMConfig") -> None:
         """Fail fast if ``stage2_model`` is missing from the LLM registry.
 
         Called at orchestrator boot when dedup is enabled. Raising here
-        is preferred over discovering the typo on the first incident.
+        is preferred over discovering the typo on the first session.
         """
         if self.stage2_model not in llm_cfg.models:
             raise ValueError(
@@ -12243,7 +12242,7 @@ def _stage1(
             if env:
                 filter_kwargs["environment"] = env
         # ``status_filter`` is the resolved session bucket — only_closed
-        # maps to "resolved" in the incident-management vocabulary.
+        # maps to "resolved" in the example app vocabulary.
         # Apps that disable only_closed get all statuses other than
         # in-flight via the empty filter (HistoryStore default behaviour
         # already screens deleted rows).
@@ -13599,7 +13598,7 @@ def _assert_envelope_invariant_on_finalize(session: "Session") -> None:
 
 
 def _default_text_extractor(session) -> str:
-    """Default text extraction for the incident-management example.
+    """Default text extraction for the example incident-management app.
 
     Concatenates the operator-supplied ``query``, the intake-summary
     (when present), and any tags. Keeps the framework agnostic of the
@@ -14704,10 +14703,10 @@ async def start_session(self, *, query: str,
         kwargs once the row schema is fully generic).
 
         ``submitter`` is a free-form dict the app interprets. For
-        incident-management it is ``{"id": "...", "team": "..."}``; for
+        the example incident-management app it is ``{"id": "...", "team": "..."}``; for
         other apps it can carry app-specific keys (e.g. code-review's
         ``{"id": "<github-username>", "pr_url": "..."}``). The framework
-        only projects ``id``/``team`` onto the row's reporter columns;
+        only projects ``id``/``team`` onto the row's submitter columns;
         apps unpack the rest via their own MCP tools.
 
         Deprecated kwargs (coerced into ``state_overrides`` / ``submitter``
@@ -14785,7 +14784,7 @@ async def stream_session(self, *, query: str, environment: str,
                              ) -> AsyncIterator[dict]:
         """Start a new session and stream UI events as it runs.
 
-        Internally builds a ``submitter`` dict so the row's reporter
+        Internally builds a ``submitter`` dict so the row's submitter
         columns are populated through the same coercion path
         ``start_session`` uses.
         """
@@ -14835,7 +14834,7 @@ async def stream_investigation(self, *, query: str, environment: str,
         """Deprecated alias for ``stream_session``.
 
         Forwards the legacy positional surface into ``stream_session``;
-        the underlying flow already coerces the reporter pair into
+        the underlying flow already coerces the submitter pair into
         a submitter dict internally so no runtime deprecation fires.
         """
         async for event in self.stream_session(
diff --git a/dist/apps/incident-management.py b/dist/apps/incident-management.py
index 5885f6c..180145e 100644
--- a/dist/apps/incident-management.py
+++ b/dist/apps/incident-management.py
@@ -51,7 +51,7 @@
 
     class IncidentState(Session):
         environment: str
-        reporter: Reporter
+        submitter: Submitter
         ...
 
 ``Session`` deliberately contains *no* domain-specific fields. Adding one
@@ -86,7 +86,7 @@ class IncidentState(Session):
 
 
 # ----- imports for runtime/similarity.py -----
-"""Similarity scoring for incident matching."""
+"""Similarity scoring for session matching."""
 
 from typing import Protocol
 
@@ -265,8 +265,8 @@ class IncidentState(Session):
 
 ``find_similar`` accepts an arbitrary ``filter_kwargs`` mapping — keys
 must correspond to ``IncidentRow`` columns. This decouples the
-framework from incident-specific filter dimensions: apps with a
-``severity``-only schema, or a multi-tenant ``tenant_id`` schema, or
+framework from app-specific filter dimensions: apps with a
+schema with a single status-tier field, a multi-tenant ``tenant_id`` schema, or
 anything else, build their filter on the fly.
 """
 
@@ -297,7 +297,7 @@ class IncidentState(Session):
 The class is parametrised as ``Generic[StateT]`` and routes row
 hydration through ``self._state_cls(...)`` so apps can plug in their
 own ``Session`` subclass via ``RuntimeConfig.state_class``. The row
-schema remains incident-shaped, but unused fields are dropped via
+schema remains the row-level shape, but unused fields are dropped via
 Pydantic's default ``extra='ignore'`` when a narrower ``state_cls`` is
 supplied.
 """
@@ -1113,7 +1113,7 @@ async def _poll(self, registry):
 structured output {is_duplicate, confidence, rationale}.
 
 The pipeline is **framework-level** and never imports the
-incident-management state class (R4 in the Phase-7 plan). Apps inject
+domain-specific Session subclass (R4 in the Phase-7 plan). Apps inject
 domain-specific text via a ``text_extractor: Callable[[Session], str]``
 callable.
 
@@ -1749,7 +1749,7 @@ class MCPConfig(BaseModel):
 
 
 class MetadataConfig(BaseModel):
-    """Relational store for incident metadata. SQLite (dev) or Postgres (prod)."""
+    """Relational store for session metadata. SQLite (dev) or Postgres (prod)."""
     url: str = "sqlite:///incidents/incidents.db"
     pool_size: int = 5      # postgres only; sqlite uses NullPool
     echo: bool = False
@@ -2581,7 +2581,7 @@ def to_agent_input(self) -> str:
 
         Apps subclass ``Session`` and override this to surface the
         domain shape (``Incident X / Environment Y / Query Z`` for the
-        incident-management app, ``PR title / repo / diff stats`` for
+        example app, ``PR title / repo / diff stats`` for
         code review, etc.). The framework default keeps the prompt
         framework-agnostic — id + status only — so that any app that
         has not overridden the hook still gets a usable preamble.
@@ -2613,7 +2613,7 @@ def id_format(cls, *, seq: int, prefix: str = "SES") -> str:
 
         ``prefix`` is supplied by ``SessionStore._next_id`` from
         ``FrameworkAppConfig.session_id_prefix`` so each app picks its
-        own namespace via plain config (e.g. ``INC`` for incident
+        own namespace via plain config (e.g. ``INC`` for the example incident
         management, ``REVIEW`` for code review, ``HR`` for HR cases,
         ...). Apps with truly bespoke id shapes can still override this
         classmethod on their ``Session`` subclass and ignore ``prefix``.
@@ -4180,7 +4180,7 @@ def _ef(i, key, default: Any = ""):
                     _ef(i, "summary", "") or "",
                     " ".join(_ef(i, "tags", []) or []),
                 ])),
-                "incident": i,
+                "session": i,
             }
             for i in candidates_inc
         ]
@@ -4190,7 +4190,7 @@ def _ef(i, key, default: Any = ""):
             threshold=self.similarity_threshold if threshold is None else threshold,
             limit=limit,
         )
-        return [(c["incident"], float(s)) for c, s in results]
+        return [(c["session"], float(s)) for c, s in results]
 
 # ====== module: runtime/storage/session_store.py ======
 
@@ -4272,7 +4272,7 @@ class StaleVersionError(RuntimeError):
 
 
 class SessionStore(Generic[StateT]):
-    """Active session/incident lifecycle store, parametrised on ``StateT``.
+    """Active session lifecycle store, parametrised on ``StateT``.
 
     Owns CRUD on the row schema plus the vector write-through. Read-only
     similarity search lives in ``HistoryStore``.
@@ -4391,7 +4391,7 @@ def create(self, *, query: str, environment: str,
     def load(self, incident_id: str) -> StateT:
         if not _SESSION_ID_RE.match(incident_id):
             raise ValueError(
-                f"Invalid incident id {incident_id!r}; expected PREFIX-YYYYMMDD-NNN"
+                f"Invalid session id {incident_id!r}; expected PREFIX-YYYYMMDD-NNN"
             )
         with SqlSession(self.engine) as session:
             row = session.get(IncidentRow, incident_id)
@@ -4399,40 +4399,39 @@ def load(self, incident_id: str) -> StateT:
                 raise FileNotFoundError(incident_id)
             return self._row_to_incident(row)
 
-    def save(self, incident: StateT) -> None:
-        if not _SESSION_ID_RE.match(incident.id):
+    def save(self, session: StateT) -> None:
+        if not _SESSION_ID_RE.match(session.id):
             raise ValueError(
-                f"Invalid incident id {incident.id!r}; expected PREFIX-YYYYMMDD-NNN"
+                f"Invalid session id {session.id!r}; expected PREFIX-YYYYMMDD-NNN"
             )
         # ``_iso(_now())`` returns ``str`` here -- the input datetime is
         # never None -- but the helper's signature is the broader
         # ``Optional[str]``. ``or ""`` keeps pyright + the typed
         # ``Session.updated_at: str`` field consistent without changing
         # behaviour (real value is always present).
-        incident.updated_at = _iso(_now()) or ""
-        sess = incident  # local alias — avoids repeating the domain token in new code
-        expected_version = getattr(sess, "version", 1)
+        session.updated_at = _iso(_now()) or ""
+        expected_version = getattr(session, "version", 1)
         # Bump in-memory BEFORE building the row dict so the persisted
         # row reflects the new version.
-        sess.version = expected_version + 1
-        with SqlSession(self.engine) as session:
-            existing = session.get(IncidentRow, sess.id)
+        session.version = expected_version + 1
+        with SqlSession(self.engine) as db_session:
+            existing = db_session.get(IncidentRow, session.id)
             prior_text = _embed_source_from_row(existing) if existing is not None else ""
             if existing is not None and existing.version != expected_version:
                 # Roll back the in-memory bump so the caller can reload + retry.
-                sess.version = expected_version
+                session.version = expected_version
                 raise StaleVersionError(
-                    f"session {sess.id} version is {existing.version}, "
+                    f"session {session.id} version is {existing.version}, "
                     f"expected {expected_version}"
                 )
-            data = self._incident_to_row_dict(incident)
+            data = self._incident_to_row_dict(session)
             if existing is None:
-                session.add(IncidentRow(**data))
+                db_session.add(IncidentRow(**data))
             else:
                 for k, v in data.items():
                     setattr(existing, k, v)
-            session.commit()
-        self._refresh_vector(incident, prior_text=prior_text)
+            db_session.commit()
+        self._refresh_vector(session, prior_text=prior_text)
 
     def delete(self, incident_id: str) -> StateT:
         with SqlSession(self.engine) as session:
@@ -4631,10 +4630,10 @@ def _row_to_incident(self, row: IncidentRow) -> StateT:
 
         Fields are pulled from typed columns when the state class
         declares them; everything else is merged in from the
-        ``extra_fields`` JSON bag. ``reporter`` is reconstituted from
+        ``extra_fields`` JSON bag. The ``reporter`` field (when present) is reconstituted from
         the typed ``reporter_id`` / ``reporter_team`` columns *only* when
-        the state class has a ``reporter`` field — otherwise it's
-        omitted so apps without a reporter concept (code-review) don't
+        the state class declares it — otherwise it's
+        omitted so apps without that concept (code-review) don't
         receive an unexpected attribute.
         """
         model_fields = self._state_cls.model_fields
@@ -6196,10 +6195,10 @@ def start_session(
         through to app-specific MCP tools.
 
         ``submitter`` is a free-form dict the calling app interprets.
-        For incident-management it is ``{"id": "...", "team": "..."}``;
+        For the example incident-management app it is ``{"id": "...", "team": "..."}``;
         other apps can carry app-specific keys (e.g. code-review's
         ``{"id": "<github-username>", "pr_url": "..."}``). The framework
-        only projects ``id``/``team`` onto the row's reporter columns.
+        only projects ``id``/``team`` onto the row's submitter columns.
 
         Deprecated kwargs (coerced and warned):
           * ``environment`` -> ``state_overrides={"environment": ...}``
@@ -8591,9 +8590,9 @@ async def node(state: GraphState) -> dict:
         # the same reload comment in ``runtime.graph.make_agent_node``
         # for the full rationale.
         try:
-            incident: Session = store.load(inc_id)
+            session: Session = store.load(inc_id)
         except FileNotFoundError:
-            incident = state_session
+            session = state_session
 
         # M3: emit agent_started telemetry before any work happens.
         if event_log is not None:
@@ -8611,7 +8610,7 @@ async def node(state: GraphState) -> dict:
         # live ``Session`` for this run.
         if gateway_cfg is not None:
             run_tools = [
-                wrap_tool(t, session=incident, gateway_cfg=gateway_cfg,
+                wrap_tool(t, session=session, gateway_cfg=gateway_cfg,
                           agent_name=skill.name, store=store,
                           gate_policy=gate_policy,
                           event_log=event_log)
@@ -8635,7 +8634,7 @@ async def node(state: GraphState) -> dict:
             checkpointer=checkpointer,
         )
         inner_thread_id = (
-            f"{inc_id}:agent:{skill.name}:turn{len(incident.agents_run)}"
+            f"{inc_id}:agent:{skill.name}:turn{len(session.agents_run)}"
         )
         inner_cfg = {"configurable": {"thread_id": inner_thread_id}}
 
@@ -8643,7 +8642,7 @@ async def node(state: GraphState) -> dict:
         # start of each agent step so the gateway treats the first
         # tool call of the turn as "no signal yet".
         try:
-            incident.turn_confidence_hint = None
+            session.turn_confidence_hint = None
         except (AttributeError, ValueError):
             pass
 
@@ -8654,7 +8653,7 @@ async def node(state: GraphState) -> dict:
                 inner_has_checkpointer=checkpointer is not None,
                 initial_input={
                     "messages": [
-                        HumanMessage(content=_format_agent_input(incident))
+                        HumanMessage(content=_format_agent_input(session))
                     ]
                 },
             )
@@ -8664,19 +8663,19 @@ async def node(state: GraphState) -> dict:
         except Exception as exc:  # noqa: BLE001
             return _handle_agent_failure(
                 skill_name=skill.name, started_at=started_at, exc=exc,
-                inc_id=inc_id, store=store, fallback=incident,
+                inc_id=inc_id, store=store, fallback=session,
             )
 
         # Tools (e.g. registered patch tools) write straight to disk.
         # Reload so the node's own append of agent_run + tool_calls
         # happens against the tool-mutated state.
-        incident = store.load(inc_id)
+        session = store.load(inc_id)
 
         messages = result.get("messages", [])
         ts = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
 
         agent_confidence, agent_rationale, agent_signal = _harvest_tool_calls_and_patches(
-            messages, skill.name, incident, ts, valid_signals,
+            messages, skill.name, session, ts, valid_signals,
             terminal_tool_names=terminal_tool_names,
             patch_tool_names=patch_tool_names,
         )
@@ -8684,10 +8683,10 @@ async def node(state: GraphState) -> dict:
         # tool call sees the harvested confidence.
         if agent_confidence is not None:
             try:
-                incident.turn_confidence_hint = agent_confidence
+                session.turn_confidence_hint = agent_confidence
             except (AttributeError, ValueError):
                 pass
-        _pair_tool_responses(messages, incident)
+        _pair_tool_responses(messages, session)
 
         # Phase 10 (FOC-03 / D-10-03): parse envelope; reconcile against
         # any typed-terminal-tool-arg confidence. Envelope failure is a
@@ -8697,7 +8696,7 @@ async def node(state: GraphState) -> dict:
         except EnvelopeMissingError as exc:
             return _handle_agent_failure(
                 skill_name=skill.name, started_at=started_at, exc=exc,
-                inc_id=inc_id, store=store, fallback=incident,
+                inc_id=inc_id, store=store, fallback=session,
             )
 
         terminal_tool_for_log = _first_terminal_tool_called_this_turn(
@@ -8733,13 +8732,13 @@ async def node(state: GraphState) -> dict:
                 )
 
         _record_success_run(
-            incident=incident, skill_name=skill.name, started_at=started_at,
+            session=session, skill_name=skill.name, started_at=started_at,
             final_text=final_text, usage=usage,
             confidence=final_confidence, rationale=final_rationale,
             signal=final_signal,
             store=store,
         )
-        next_route_signal = decide_route(incident)
+        next_route_signal = decide_route(session)
         next_node = route_from_skill(skill, next_route_signal)
 
         # M3: emit route_decided + agent_finished. agent_finished carries
@@ -8770,7 +8769,7 @@ async def node(state: GraphState) -> dict:
                     "event_log.record(agent_finished) failed", exc_info=True,
                 )
 
-        return {"session": incident, "next_route": next_node,
+        return {"session": session, "next_route": next_node,
                 "last_agent": skill.name, "error": None}
 
     return node
@@ -8803,7 +8802,7 @@ def _safe_eval(expr: str, ctx: dict[str, Any]) -> Any:
     return eval(code, {"__builtins__": {}}, ctx)  # noqa: S307 — AST-whitelisted
 
 
-def _ctx_for_session(incident: Session) -> dict[str, Any]:
+def _ctx_for_session(session: Session) -> dict[str, Any]:
     """Build the variable namespace dispatch-rule expressions see.
 
     Exposes the live session payload as ``session`` plus a few
@@ -8812,7 +8811,7 @@ def _ctx_for_session(incident: Session) -> dict[str, Any]:
     AST checker already restricts the language so we don't need to
     sandbox the namespace any further.
     """
-    payload = incident.model_dump()
+    payload = session.model_dump()
     return {
         "session": payload,
         "status": payload.get("status"),
@@ -8858,7 +8857,7 @@ def _llm_pick_target(
     *,
     skill: Skill,
     llm: BaseChatModel,
-    incident: Session,
+    session: Session,
 ) -> str:
     """One-shot LLM dispatch: ask the model to choose a subordinate.
 
@@ -8873,7 +8872,7 @@ def _llm_pick_target(
         f"Choose ONE of: {', '.join(skill.subordinates)}.\n"
         f"Reply with only the agent name."
     )
-    payload = json.dumps(incident.model_dump(), default=str)
+    payload = json.dumps(session.model_dump(), default=str)
     msgs = [
         SystemMessage(content=prompt),
         HumanMessage(content=payload),
@@ -8900,7 +8899,7 @@ def _llm_pick_target(
 def _rule_pick_target(
     *,
     skill: Skill,
-    incident: Session,
+    session: Session,
 ) -> tuple[str, str | None]:
     """Walk dispatch_rules in order; return (target, matched_when).
 
@@ -8908,7 +8907,7 @@ def _rule_pick_target(
     fallback case carries ``matched_when=None`` so the audit log can
     distinguish "default" from "rule X matched".
     """
-    ctx = _ctx_for_session(incident)
+    ctx = _ctx_for_session(session)
     for rule in skill.dispatch_rules:
         try:
             if bool(_safe_eval(rule.when, ctx)):
@@ -9083,7 +9082,7 @@ async def node(state: GraphState) -> dict:
 
         rule_matched: str | None = None
         if skill.dispatch_strategy == "rule":
-            target, rule_matched = _rule_pick_target(skill=skill, incident=sess)
+            target, rule_matched = _rule_pick_target(skill=skill, session=sess)
         else:  # "llm"
             if llm is None:
                 logger.warning(
@@ -9092,7 +9091,7 @@ async def node(state: GraphState) -> dict:
                 )
                 target = skill.subordinates[0]
             else:
-                target = _llm_pick_target(skill=skill, llm=llm, incident=sess)
+                target = _llm_pick_target(skill=skill, llm=llm, session=sess)
 
         # Audit: one structured log entry per dispatch.
         try:
@@ -9592,11 +9591,11 @@ def route_from_skill(skill: Skill, signal: str) -> str:
 
 
 class AgentRunRecorder:
-    """Helper to capture an agent's run + tool calls into the incident."""
+    """Helper to capture an agent's run + tool calls into the session."""
 
-    def __init__(self, *, agent: str, incident: Session):
+    def __init__(self, *, agent: str, session: Session):
         self.agent = agent
-        self.incident = incident
+        self.session = session
         self._started_at: str | None = None
 
     def start(self) -> None:
@@ -9604,13 +9603,13 @@ def start(self) -> None:
 
     def record_tool_call(self, tool: str, args: dict, result) -> None:
         ts = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
-        self.incident.tool_calls.append(
+        self.session.tool_calls.append(
             ToolCall(agent=self.agent, tool=tool, args=args, result=result, ts=ts)
         )
 
     def finish(self, *, summary: str) -> None:
         ended_at = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
-        self.incident.agents_run.append(AgentRun(
+        self.session.agents_run.append(AgentRun(
             agent=self.agent,
             started_at=self._started_at or ended_at,
             ended_at=ended_at,
@@ -9770,7 +9769,7 @@ async def _ainvoke_with_retry(executor, input_, *, max_attempts: int = 3,
     raise last_exc or RuntimeError("retry exhausted with no attempts")  # pragma: no cover
 
 
-def _format_agent_input(incident: Session) -> str:
+def _format_agent_input(session: Session) -> str:
     """Build the human-message preamble each agent receives.
 
     Delegates to ``Session.to_agent_input`` so each app subclass owns the
@@ -9778,7 +9777,7 @@ def _format_agent_input(incident: Session) -> str:
     session id + status; ``IncidentState`` and ``CodeReviewState``
     override with their respective shapes.
     """
-    return incident.to_agent_input()
+    return session.to_agent_input()
 
 
 def _merge_patch_metadata(
@@ -9852,7 +9851,7 @@ def _harvest_patch_tool(
 def _harvest_tool_calls_and_patches(
     messages: list,
     skill_name: str,
-    incident: Session,
+    session: Session,
     ts: str,
     valid_signals: frozenset[str] | None = None,
     terminal_tool_names: frozenset[str] = frozenset(),
@@ -9895,7 +9894,7 @@ def _harvest_tool_calls_and_patches(
             # colon; rsplit on the rightmost colon recovers the bare
             # tool name for both prefixed and unprefixed forms.
             tc_original = tc_name.rsplit(":", 1)[-1]
-            incident.tool_calls.append(ToolCall(
+            session.tool_calls.append(ToolCall(
                 agent=skill_name, tool=tc_name, args=tc_args,
                 result=None, ts=ts,
             ))
@@ -9909,11 +9908,11 @@ def _harvest_tool_calls_and_patches(
     return state
 
 
-def _pair_tool_responses(messages: list, incident: Session) -> None:
+def _pair_tool_responses(messages: list, session: Session) -> None:
     """Match ToolMessage responses back to their corresponding ToolCall entries."""
     for msg in messages:
         if msg.__class__.__name__ == "ToolMessage":
-            for entry in reversed(incident.tool_calls):
+            for entry in reversed(session.tool_calls):
                 if entry.tool == getattr(msg, "name", None) and entry.result is None:
                     entry.result = getattr(msg, "content", None)
                     break
@@ -10018,18 +10017,18 @@ def _handle_agent_failure(
     store: "SessionStore",
     fallback: "Session",
 ) -> dict:
-    """Reload incident (absorbing partial tool writes), stamp a failure AgentRun,
+    """Reload session (absorbing partial tool writes), stamp a failure AgentRun,
     persist, and return the error state dict for the LangGraph node.
 
-    ``fallback`` is the in-memory incident from the caller; we use it only
+    ``fallback`` is the in-memory session from the caller; we use it only
     when the on-disk state has gone missing (FileNotFoundError on reload).
     """
     try:
-        incident = store.load(inc_id)
+        session = store.load(inc_id)
     except FileNotFoundError:
-        incident = fallback
+        session = fallback
     ended_at = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
-    incident.agents_run.append(AgentRun(
+    session.agents_run.append(AgentRun(
         agent=skill_name, started_at=started_at, ended_at=ended_at,
         summary=f"agent failed: {exc}",
         token_usage=TokenUsage(),
@@ -10037,15 +10036,15 @@ def _handle_agent_failure(
     # Mark the session as terminally failed so the UI can render a
     # retry control. The retry path (``Orchestrator.retry_session``)
     # is the only documented way to move out of this state.
-    incident.status = "error"
-    store.save(incident)
-    return {"session": incident, "next_route": None,
+    session.status = "error"
+    store.save(session)
+    return {"session": session, "next_route": None,
             "last_agent": skill_name, "error": str(exc)}
 
 
 def _record_success_run(
     *,
-    incident: "Session",
+    session: "Session",
     skill_name: str,
     started_at: str,
     final_text: str,
@@ -10055,10 +10054,10 @@ def _record_success_run(
     signal: str | None,
     store: "SessionStore",
 ) -> None:
-    """Append the success-path AgentRun, update the incident's running token
-    totals, and persist. Mutates ``incident`` in place."""
+    """Append the success-path AgentRun, update the session's running token
+    totals, and persist. Mutates ``session`` in place."""
     ended_at = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
-    incident.agents_run.append(AgentRun(
+    session.agents_run.append(AgentRun(
         agent=skill_name, started_at=started_at, ended_at=ended_at,
         summary=final_text or f"{skill_name} completed",
         token_usage=usage,
@@ -10066,10 +10065,10 @@ def _record_success_run(
         confidence_rationale=rationale,
         signal=signal,
     ))
-    incident.token_usage.input_tokens += usage.input_tokens
-    incident.token_usage.output_tokens += usage.output_tokens
-    incident.token_usage.total_tokens += usage.total_tokens
-    store.save(incident)
+    session.token_usage.input_tokens += usage.input_tokens
+    session.token_usage.output_tokens += usage.output_tokens
+    session.token_usage.total_tokens += usage.total_tokens
+    store.save(session)
 
 
 def make_agent_node(
@@ -10131,9 +10130,9 @@ async def node(state: GraphState) -> dict:
         # pending row, appends a duplicate, then ``store.save`` raises
         # ``StaleVersionError`` because DB has already moved on.
         try:
-            incident = store.load(inc_id)
+            session = store.load(inc_id)
         except FileNotFoundError:
-            incident = state_session
+            session = state_session
 
         # M3 (per-step telemetry): emit agent_started.
         if event_log is not None:
@@ -10175,7 +10174,7 @@ async def node(state: GraphState) -> dict:
             # keys from ``accepted_params``, the inject step skips them,
             # and FastMCP rejects the call as missing required arg.
             run_tools = [
-                wrap_tool(t, session=incident, gateway_cfg=gateway_cfg,
+                wrap_tool(t, session=session, gateway_cfg=gateway_cfg,
                           agent_name=skill.name, store=store,
                           injected_args=injected_args or {},
                           gate_policy=gate_policy,
@@ -10221,7 +10220,7 @@ def _run(**kwargs: Any) -> Any:
                 )
 
             run_tools = [
-                _make_inject_only_wrapper(orig, vis, incident)
+                _make_inject_only_wrapper(orig, vis, session)
                 for orig, vis in zip(tools, visible_tools)
             ]
         else:
@@ -10249,7 +10248,7 @@ def _run(**kwargs: Any) -> Any:
         # checkpointer``. The thread id is derived deterministically
         # from session + agent + the upcoming agent_run index so it is:
         #   * STABLE across the inner pause and the outer resume that
-        #     follows (both observe the same ``len(incident.agents_run)``
+        #     follows (both observe the same ``len(session.agents_run)``
         #     because no new run is recorded mid-pause), and
         #   * UNIQUE per agent invocation so previous invocations of the
         #     same agent within the same session don't bleed in.
@@ -10260,7 +10259,7 @@ def _run(**kwargs: Any) -> Any:
             checkpointer=checkpointer,
         )
         inner_thread_id = (
-            f"{inc_id}:agent:{skill.name}:turn{len(incident.agents_run)}"
+            f"{inc_id}:agent:{skill.name}:turn{len(session.agents_run)}"
         )
         inner_cfg = {"configurable": {"thread_id": inner_thread_id}}
 
@@ -10269,7 +10268,7 @@ def _run(**kwargs: Any) -> Any:
         # re-entry from a HITL pause the hint resets cleanly so a new
         # turn starts from "no signal yet" (None).
         try:
-            incident.turn_confidence_hint = None
+            session.turn_confidence_hint = None
         except (AttributeError, ValueError):
             pass
 
@@ -10280,7 +10279,7 @@ def _run(**kwargs: Any) -> Any:
                 inner_has_checkpointer=checkpointer is not None,
                 initial_input={
                     "messages": [
-                        HumanMessage(content=_format_agent_input(incident))
+                        HumanMessage(content=_format_agent_input(session))
                     ]
                 },
             )
@@ -10324,19 +10323,19 @@ def _run(**kwargs: Any) -> Any:
                 else:
                     return _handle_agent_failure(
                         skill_name=skill.name, started_at=started_at, exc=exc,
-                        inc_id=inc_id, store=store, fallback=incident,
+                        inc_id=inc_id, store=store, fallback=session,
                     )
             else:
                 return _handle_agent_failure(
                     skill_name=skill.name, started_at=started_at, exc=exc,
-                    inc_id=inc_id, store=store, fallback=incident,
+                    inc_id=inc_id, store=store, fallback=session,
                 )
 
         # Tools (e.g. registered patch tools) write straight to disk.
         # Reload so the node's own append of agent_run + tool_calls
         # happens against the tool-mutated state — otherwise saving
         # the stale in-memory object clobbers the tools' writes.
-        incident = store.load(inc_id)
+        session = store.load(inc_id)
 
         messages = result.get("messages", [])
         ts = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
@@ -10344,7 +10343,7 @@ def _run(**kwargs: Any) -> Any:
         # Record tool calls and harvest confidence/signal from configured
         # patch / typed-terminal tools.
         agent_confidence, agent_rationale, agent_signal = _harvest_tool_calls_and_patches(
-            messages, skill.name, incident, ts, valid_signals,
+            messages, skill.name, session, ts, valid_signals,
             terminal_tool_names=terminal_tool_names,
             patch_tool_names=patch_tool_names,
         )
@@ -10352,12 +10351,12 @@ def _run(**kwargs: Any) -> Any:
         # tool call sees the harvested confidence at the gateway.
         if agent_confidence is not None:
             try:
-                incident.turn_confidence_hint = agent_confidence
+                session.turn_confidence_hint = agent_confidence
             except (AttributeError, ValueError):
                 pass
 
         # Pair tool responses with their tool calls.
-        _pair_tool_responses(messages, incident)
+        _pair_tool_responses(messages, session)
 
         # Phase 10 (FOC-03 / D-10-03): parse the structural envelope and
         # reconcile its confidence against any typed-terminal-tool arg
@@ -10368,7 +10367,7 @@ def _run(**kwargs: Any) -> Any:
         except EnvelopeMissingError as exc:
             return _handle_agent_failure(
                 skill_name=skill.name, started_at=started_at, exc=exc,
-                inc_id=inc_id, store=store, fallback=incident,
+                inc_id=inc_id, store=store, fallback=session,
             )
 
         terminal_tool_for_log = _first_terminal_tool_called_this_turn(
@@ -10405,12 +10404,12 @@ def _run(**kwargs: Any) -> Any:
                 )
 
         _record_success_run(
-            incident=incident, skill_name=skill.name, started_at=started_at,
+            session=session, skill_name=skill.name, started_at=started_at,
             final_text=final_text, usage=usage,
             confidence=final_confidence, rationale=final_rationale, signal=final_signal,
             store=store,
         )
-        next_route_signal = decide_route(incident)
+        next_route_signal = decide_route(session)
         next_node = route_from_skill(skill, next_route_signal)
 
         # M3: emit route_decided + agent_finished (carrying token_usage).
@@ -10439,7 +10438,7 @@ def _run(**kwargs: Any) -> Any:
                     "event_log.record(agent_finished) failed", exc_info=True,
                 )
 
-        return {"session": incident, "next_route": next_node,
+        return {"session": session, "next_route": next_node,
                 "last_agent": skill.name, "error": None}
 
     return node
@@ -10486,7 +10485,7 @@ def _decide_from_signal(inc: Session) -> str:
 }
 
 
-def _latest_run_for(incident: Session, agent_name: str | None):
+def _latest_run_for(session: Session, agent_name: str | None):
     """Return the most recent ``AgentRun`` for ``agent_name``, or None.
 
     ``agent_name`` is whichever agent ran immediately before the gate,
@@ -10496,7 +10495,7 @@ def _latest_run_for(incident: Session, agent_name: str | None):
     """
     if not agent_name:
         return None
-    for run in reversed(incident.agents_run):
+    for run in reversed(session.agents_run):
         if run.agent == agent_name:
             return run
     return None
@@ -10558,7 +10557,7 @@ async def gate(state: GraphState) -> dict:
         # value on subsequent executions of the same node.
         from langgraph.types import interrupt
 
-        incident = state["session"]  # pyright: ignore[reportTypedDictNotRequiredAccess] — orchestrator runtime always supplies session
+        session = state["session"]  # pyright: ignore[reportTypedDictNotRequiredAccess] — orchestrator runtime always supplies session
         upstream = state.get("last_agent")
         # Capture the intended downstream target before we overwrite next_route.
         # The upstream agent set next_route to the gated target; we stash it in
@@ -10566,13 +10565,13 @@ async def gate(state: GraphState) -> dict:
         intended_target = state.get("next_route")
         # Reload from disk in case earlier nodes wrote tool-driven patches.
         try:
-            incident = store.load(incident.id)
+            session = store.load(session.id)
         except FileNotFoundError:
             pass
-        upstream_run = _latest_run_for(incident, upstream)
+        upstream_run = _latest_run_for(session, upstream)
         upstream_conf = upstream_run.confidence if upstream_run else None
         if upstream_conf is None or upstream_conf < threshold:
-            incident.status = "awaiting_input"
+            session.status = "awaiting_input"
             # Surface the upstream agent's own summary + rationale so the
             # human reviewer can decide what input to give without scrolling
             # through every step of the agents-run log.
@@ -10587,13 +10586,13 @@ async def gate(state: GraphState) -> dict:
                 "escalation_teams": teams,
                 "intended_target": intended_target,
             }
-            incident.pending_intervention = payload
+            session.pending_intervention = payload
             # CRITICAL ORDERING: persist the Session row BEFORE calling
             # ``interrupt()``. ``interrupt()`` raises ``GraphInterrupt`` on
             # first execution; if we reversed the order the UI (which
             # polls Session.pending_intervention) would never see the
             # pending state. See plan R4 / "Streamlit hand-off".
-            store.save(incident)
+            store.save(session)
             # First execution: this raises GraphInterrupt and the
             # checkpointer captures the paused state.
             # Resume: this returns the value supplied via
@@ -10616,17 +10615,17 @@ async def gate(state: GraphState) -> dict:
                 if isinstance(raw, str) and raw.strip():
                     user_text = raw.strip()
             if user_text is not None:
-                incident.user_inputs.append(user_text)
-            incident.pending_intervention = None
-            incident.status = "in_progress"
-            store.save(incident)
-            return {"session": incident, "next_route": "default",
+                session.user_inputs.append(user_text)
+            session.pending_intervention = None
+            session.status = "in_progress"
+            store.save(session)
+            return {"session": session, "next_route": "default",
                     "gated_target": intended_target, "last_agent": "gate", "error": None}
         # Confidence met threshold — clear any stale intervention payload.
-        if incident.pending_intervention is not None:
-            incident.pending_intervention = None
-            store.save(incident)
-        return {"session": incident, "next_route": "default",
+        if session.pending_intervention is not None:
+            session.pending_intervention = None
+            store.save(session)
+        return {"session": session, "next_route": "default",
                 "gated_target": intended_target, "last_agent": "gate", "error": None}
 
     return gate
@@ -11974,7 +11973,7 @@ class DedupConfig(BaseModel):
     All numeric thresholds are inclusive at the lower bound (``>=``),
     so a candidate hitting exactly ``stage1_threshold`` is considered.
 
-    Defaults are tuned for the incident-management example. Apps that
+    Defaults are tuned for the example app. Apps that
     want different policies override via YAML.
     """
 
@@ -12006,7 +12005,7 @@ def assert_model_exists(self, llm_cfg: "LLMConfig") -> None:
         """Fail fast if ``stage2_model`` is missing from the LLM registry.
 
         Called at orchestrator boot when dedup is enabled. Raising here
-        is preferred over discovering the typo on the first incident.
+        is preferred over discovering the typo on the first session.
         """
         if self.stage2_model not in llm_cfg.models:
             raise ValueError(
@@ -12255,7 +12254,7 @@ def _stage1(
             if env:
                 filter_kwargs["environment"] = env
         # ``status_filter`` is the resolved session bucket — only_closed
-        # maps to "resolved" in the incident-management vocabulary.
+        # maps to "resolved" in the example app vocabulary.
         # Apps that disable only_closed get all statuses other than
         # in-flight via the empty filter (HistoryStore default behaviour
         # already screens deleted rows).
@@ -13611,7 +13610,7 @@ def _assert_envelope_invariant_on_finalize(session: "Session") -> None:
 
 
 def _default_text_extractor(session) -> str:
-    """Default text extraction for the incident-management example.
+    """Default text extraction for the example incident-management app.
 
     Concatenates the operator-supplied ``query``, the intake-summary
     (when present), and any tags. Keeps the framework agnostic of the
@@ -14716,10 +14715,10 @@ async def start_session(self, *, query: str,
         kwargs once the row schema is fully generic).
 
         ``submitter`` is a free-form dict the app interprets. For
-        incident-management it is ``{"id": "...", "team": "..."}``; for
+        the example incident-management app it is ``{"id": "...", "team": "..."}``; for
         other apps it can carry app-specific keys (e.g. code-review's
         ``{"id": "<github-username>", "pr_url": "..."}``). The framework
-        only projects ``id``/``team`` onto the row's reporter columns;
+        only projects ``id``/``team`` onto the row's submitter columns;
         apps unpack the rest via their own MCP tools.
 
         Deprecated kwargs (coerced into ``state_overrides`` / ``submitter``
@@ -14797,7 +14796,7 @@ async def stream_session(self, *, query: str, environment: str,
                              ) -> AsyncIterator[dict]:
         """Start a new session and stream UI events as it runs.
 
-        Internally builds a ``submitter`` dict so the row's reporter
+        Internally builds a ``submitter`` dict so the row's submitter
         columns are populated through the same coercion path
         ``start_session`` uses.
         """
@@ -14847,7 +14846,7 @@ async def stream_investigation(self, *, query: str, environment: str,
         """Deprecated alias for ``stream_session``.
 
         Forwards the legacy positional surface into ``stream_session``;
-        the underlying flow already coerces the reporter pair into
+        the underlying flow already coerces the submitter pair into
         a submitter dict internally so no runtime deprecation fires.
         """
         async for event in self.stream_session(
diff --git a/sonar-project.properties b/sonar-project.properties
index 25cf9be..3c31a9f 100644
--- a/sonar-project.properties
+++ b/sonar-project.properties
@@ -14,12 +14,17 @@ sonar.python.version=3.11
 sonar.exclusions=dist/**,scripts/**,docs/**,.venv/**,incidents/**
 sonar.test.exclusions=tests/fixtures/**
 
-# Copy-Paste Detection exclusions. ``runtime/tools/gateway.py`` carries
-# a deliberate sync (``_run``) + async (``_arun``) mirror — every
-# ``BaseTool`` must support both invocation styles. The sibling blocks
-# look like duplication to CPD but are an architectural requirement,
-# not drift; modifying them in tandem is the project convention.
-sonar.cpd.exclusions=src/runtime/tools/gateway.py
+# Copy-Paste Detection exclusions.
+#   * ``runtime/tools/gateway.py`` — deliberate sync (``_run``) + async
+#     (``_arun``) mirror; every ``BaseTool`` must support both
+#     invocation styles. The sibling blocks look like duplication to
+#     CPD but are an architectural requirement, not drift; modifying
+#     them in tandem is the project convention.
+#   * ``runtime/agents/responsive.py`` — the "responsive" agent-kind
+#     factory mirrors ``runtime/graph.py:make_agent_node`` by design:
+#     ``_build_agent_nodes`` dispatches to either factory based on
+#     ``skill.kind``. Same pattern as gateway above.
+sonar.cpd.exclusions=src/runtime/tools/gateway.py,src/runtime/agents/responsive.py
 
 # Coverage exclusions — UI is excluded because Streamlit rendering is exercised
 # manually in a browser, not by the unit-test suite. Coverage gates apply to
diff --git a/src/runtime/agents/responsive.py b/src/runtime/agents/responsive.py
index 97b81b3..a81d769 100644
--- a/src/runtime/agents/responsive.py
+++ b/src/runtime/agents/responsive.py
@@ -103,9 +103,9 @@ async def node(state: GraphState) -> dict:
         # the same reload comment in ``runtime.graph.make_agent_node``
         # for the full rationale.
         try:
-            incident: Session = store.load(inc_id)
+            session: Session = store.load(inc_id)
         except FileNotFoundError:
-            incident = state_session
+            session = state_session
 
         # M3: emit agent_started telemetry before any work happens.
         if event_log is not None:
@@ -123,7 +123,7 @@ async def node(state: GraphState) -> dict:
         # live ``Session`` for this run.
         if gateway_cfg is not None:
             run_tools = [
-                wrap_tool(t, session=incident, gateway_cfg=gateway_cfg,
+                wrap_tool(t, session=session, gateway_cfg=gateway_cfg,
                           agent_name=skill.name, store=store,
                           gate_policy=gate_policy,
                           event_log=event_log)
@@ -147,7 +147,7 @@ async def node(state: GraphState) -> dict:
             checkpointer=checkpointer,
         )
         inner_thread_id = (
-            f"{inc_id}:agent:{skill.name}:turn{len(incident.agents_run)}"
+            f"{inc_id}:agent:{skill.name}:turn{len(session.agents_run)}"
         )
         inner_cfg = {"configurable": {"thread_id": inner_thread_id}}
 
@@ -155,7 +155,7 @@ async def node(state: GraphState) -> dict:
         # start of each agent step so the gateway treats the first
         # tool call of the turn as "no signal yet".
         try:
-            incident.turn_confidence_hint = None
+            session.turn_confidence_hint = None
         except (AttributeError, ValueError):
             pass
 
@@ -166,7 +166,7 @@ async def node(state: GraphState) -> dict:
                 inner_has_checkpointer=checkpointer is not None,
                 initial_input={
                     "messages": [
-                        HumanMessage(content=_format_agent_input(incident))
+                        HumanMessage(content=_format_agent_input(session))
                     ]
                 },
             )
@@ -176,19 +176,19 @@ async def node(state: GraphState) -> dict:
         except Exception as exc:  # noqa: BLE001
             return _handle_agent_failure(
                 skill_name=skill.name, started_at=started_at, exc=exc,
-                inc_id=inc_id, store=store, fallback=incident,
+                inc_id=inc_id, store=store, fallback=session,
             )
 
         # Tools (e.g. registered patch tools) write straight to disk.
         # Reload so the node's own append of agent_run + tool_calls
         # happens against the tool-mutated state.
-        incident = store.load(inc_id)
+        session = store.load(inc_id)
 
         messages = result.get("messages", [])
         ts = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
 
         agent_confidence, agent_rationale, agent_signal = _harvest_tool_calls_and_patches(
-            messages, skill.name, incident, ts, valid_signals,
+            messages, skill.name, session, ts, valid_signals,
             terminal_tool_names=terminal_tool_names,
             patch_tool_names=patch_tool_names,
         )
@@ -196,10 +196,10 @@ async def node(state: GraphState) -> dict:
         # tool call sees the harvested confidence.
         if agent_confidence is not None:
             try:
-                incident.turn_confidence_hint = agent_confidence
+                session.turn_confidence_hint = agent_confidence
             except (AttributeError, ValueError):
                 pass
-        _pair_tool_responses(messages, incident)
+        _pair_tool_responses(messages, session)
 
         # Phase 10 (FOC-03 / D-10-03): parse envelope; reconcile against
         # any typed-terminal-tool-arg confidence. Envelope failure is a
@@ -209,7 +209,7 @@ async def node(state: GraphState) -> dict:
         except EnvelopeMissingError as exc:
             return _handle_agent_failure(
                 skill_name=skill.name, started_at=started_at, exc=exc,
-                inc_id=inc_id, store=store, fallback=incident,
+                inc_id=inc_id, store=store, fallback=session,
             )
 
         terminal_tool_for_log = _first_terminal_tool_called_this_turn(
@@ -245,13 +245,13 @@ async def node(state: GraphState) -> dict:
                 )
 
         _record_success_run(
-            incident=incident, skill_name=skill.name, started_at=started_at,
+            session=session, skill_name=skill.name, started_at=started_at,
             final_text=final_text, usage=usage,
             confidence=final_confidence, rationale=final_rationale,
             signal=final_signal,
             store=store,
         )
-        next_route_signal = decide_route(incident)
+        next_route_signal = decide_route(session)
         next_node = route_from_skill(skill, next_route_signal)
 
         # M3: emit route_decided + agent_finished. agent_finished carries
@@ -282,7 +282,7 @@ async def node(state: GraphState) -> dict:
                     "event_log.record(agent_finished) failed", exc_info=True,
                 )
 
-        return {"session": incident, "next_route": next_node,
+        return {"session": session, "next_route": next_node,
                 "last_agent": skill.name, "error": None}
 
     return node
diff --git a/src/runtime/agents/supervisor.py b/src/runtime/agents/supervisor.py
index 06ece42..7b11354 100644
--- a/src/runtime/agents/supervisor.py
+++ b/src/runtime/agents/supervisor.py
@@ -57,7 +57,7 @@ def _safe_eval(expr: str, ctx: dict[str, Any]) -> Any:
     return eval(code, {"__builtins__": {}}, ctx)  # noqa: S307 — AST-whitelisted
 
 
-def _ctx_for_session(incident: Session) -> dict[str, Any]:
+def _ctx_for_session(session: Session) -> dict[str, Any]:
     """Build the variable namespace dispatch-rule expressions see.
 
     Exposes the live session payload as ``session`` plus a few
@@ -66,7 +66,7 @@ def _ctx_for_session(incident: Session) -> dict[str, Any]:
     AST checker already restricts the language so we don't need to
     sandbox the namespace any further.
     """
-    payload = incident.model_dump()
+    payload = session.model_dump()
     return {
         "session": payload,
         "status": payload.get("status"),
@@ -112,7 +112,7 @@ def _llm_pick_target(
     *,
     skill: Skill,
     llm: BaseChatModel,
-    incident: Session,
+    session: Session,
 ) -> str:
     """One-shot LLM dispatch: ask the model to choose a subordinate.
 
@@ -127,7 +127,7 @@ def _llm_pick_target(
         f"Choose ONE of: {', '.join(skill.subordinates)}.\n"
         f"Reply with only the agent name."
     )
-    payload = json.dumps(incident.model_dump(), default=str)
+    payload = json.dumps(session.model_dump(), default=str)
     msgs = [
         SystemMessage(content=prompt),
         HumanMessage(content=payload),
@@ -154,7 +154,7 @@ def _llm_pick_target(
 def _rule_pick_target(
     *,
     skill: Skill,
-    incident: Session,
+    session: Session,
 ) -> tuple[str, str | None]:
     """Walk dispatch_rules in order; return (target, matched_when).
 
@@ -162,7 +162,7 @@ def _rule_pick_target(
     fallback case carries ``matched_when=None`` so the audit log can
     distinguish "default" from "rule X matched".
     """
-    ctx = _ctx_for_session(incident)
+    ctx = _ctx_for_session(session)
     for rule in skill.dispatch_rules:
         try:
             if bool(_safe_eval(rule.when, ctx)):
@@ -337,7 +337,7 @@ async def node(state: GraphState) -> dict:
 
         rule_matched: str | None = None
         if skill.dispatch_strategy == "rule":
-            target, rule_matched = _rule_pick_target(skill=skill, incident=sess)
+            target, rule_matched = _rule_pick_target(skill=skill, session=sess)
         else:  # "llm"
             if llm is None:
                 logger.warning(
@@ -346,7 +346,7 @@ async def node(state: GraphState) -> dict:
                 )
                 target = skill.subordinates[0]
             else:
-                target = _llm_pick_target(skill=skill, llm=llm, incident=sess)
+                target = _llm_pick_target(skill=skill, llm=llm, session=sess)
 
         # Audit: one structured log entry per dispatch.
         try:
diff --git a/src/runtime/config.py b/src/runtime/config.py
index 234ea2f..7eb61c2 100644
--- a/src/runtime/config.py
+++ b/src/runtime/config.py
@@ -134,7 +134,7 @@ class MCPConfig(BaseModel):
 
 
 class MetadataConfig(BaseModel):
-    """Relational store for incident metadata. SQLite (dev) or Postgres (prod)."""
+    """Relational store for session metadata. SQLite (dev) or Postgres (prod)."""
     url: str = "sqlite:///incidents/incidents.db"
     pool_size: int = 5      # postgres only; sqlite uses NullPool
     echo: bool = False
diff --git a/src/runtime/dedup.py b/src/runtime/dedup.py
index 4892a91..2e2e6aa 100644
--- a/src/runtime/dedup.py
+++ b/src/runtime/dedup.py
@@ -6,7 +6,7 @@
 structured output {is_duplicate, confidence, rationale}.
 
 The pipeline is **framework-level** and never imports the
-incident-management state class (R4 in the Phase-7 plan). Apps inject
+domain-specific Session subclass (R4 in the Phase-7 plan). Apps inject
 domain-specific text via a ``text_extractor: Callable[[Session], str]``
 callable.
 
@@ -61,7 +61,7 @@ class DedupConfig(BaseModel):
     All numeric thresholds are inclusive at the lower bound (``>=``),
     so a candidate hitting exactly ``stage1_threshold`` is considered.
 
-    Defaults are tuned for the incident-management example. Apps that
+    Defaults are tuned for the example app. Apps that
     want different policies override via YAML.
     """
 
@@ -93,7 +93,7 @@ def assert_model_exists(self, llm_cfg: "LLMConfig") -> None:
         """Fail fast if ``stage2_model`` is missing from the LLM registry.
 
         Called at orchestrator boot when dedup is enabled. Raising here
-        is preferred over discovering the typo on the first incident.
+        is preferred over discovering the typo on the first session.
         """
         if self.stage2_model not in llm_cfg.models:
             raise ValueError(
@@ -342,7 +342,7 @@ def _stage1(
             if env:
                 filter_kwargs["environment"] = env
         # ``status_filter`` is the resolved session bucket — only_closed
-        # maps to "resolved" in the incident-management vocabulary.
+        # maps to "resolved" in the example app vocabulary.
         # Apps that disable only_closed get all statuses other than
         # in-flight via the empty filter (HistoryStore default behaviour
         # already screens deleted rows).
diff --git a/src/runtime/graph.py b/src/runtime/graph.py
index 19b589f..65f5550 100644
--- a/src/runtime/graph.py
+++ b/src/runtime/graph.py
@@ -160,11 +160,11 @@ def route_from_skill(skill: Skill, signal: str) -> str:
 
 
 class AgentRunRecorder:
-    """Helper to capture an agent's run + tool calls into the incident."""
+    """Helper to capture an agent's run + tool calls into the session."""
 
-    def __init__(self, *, agent: str, incident: Session):
+    def __init__(self, *, agent: str, session: Session):
         self.agent = agent
-        self.incident = incident
+        self.session = session
         self._started_at: str | None = None
 
     def start(self) -> None:
@@ -172,13 +172,13 @@ def start(self) -> None:
 
     def record_tool_call(self, tool: str, args: dict, result) -> None:
         ts = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
-        self.incident.tool_calls.append(
+        self.session.tool_calls.append(
             ToolCall(agent=self.agent, tool=tool, args=args, result=result, ts=ts)
         )
 
     def finish(self, *, summary: str) -> None:
         ended_at = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
-        self.incident.agents_run.append(AgentRun(
+        self.session.agents_run.append(AgentRun(
             agent=self.agent,
             started_at=self._started_at or ended_at,
             ended_at=ended_at,
@@ -338,7 +338,7 @@ async def _ainvoke_with_retry(executor, input_, *, max_attempts: int = 3,
     raise last_exc or RuntimeError("retry exhausted with no attempts")  # pragma: no cover
 
 
-def _format_agent_input(incident: Session) -> str:
+def _format_agent_input(session: Session) -> str:
     """Build the human-message preamble each agent receives.
 
     Delegates to ``Session.to_agent_input`` so each app subclass owns the
@@ -346,7 +346,7 @@ def _format_agent_input(incident: Session) -> str:
     session id + status; ``IncidentState`` and ``CodeReviewState``
     override with their respective shapes.
     """
-    return incident.to_agent_input()
+    return session.to_agent_input()
 
 
 def _merge_patch_metadata(
@@ -420,7 +420,7 @@ def _harvest_patch_tool(
 def _harvest_tool_calls_and_patches(
     messages: list,
     skill_name: str,
-    incident: Session,
+    session: Session,
     ts: str,
     valid_signals: frozenset[str] | None = None,
     terminal_tool_names: frozenset[str] = frozenset(),
@@ -463,7 +463,7 @@ def _harvest_tool_calls_and_patches(
             # colon; rsplit on the rightmost colon recovers the bare
             # tool name for both prefixed and unprefixed forms.
             tc_original = tc_name.rsplit(":", 1)[-1]
-            incident.tool_calls.append(ToolCall(
+            session.tool_calls.append(ToolCall(
                 agent=skill_name, tool=tc_name, args=tc_args,
                 result=None, ts=ts,
             ))
@@ -477,11 +477,11 @@ def _harvest_tool_calls_and_patches(
     return state
 
 
-def _pair_tool_responses(messages: list, incident: Session) -> None:
+def _pair_tool_responses(messages: list, session: Session) -> None:
     """Match ToolMessage responses back to their corresponding ToolCall entries."""
     for msg in messages:
         if msg.__class__.__name__ == "ToolMessage":
-            for entry in reversed(incident.tool_calls):
+            for entry in reversed(session.tool_calls):
                 if entry.tool == getattr(msg, "name", None) and entry.result is None:
                     entry.result = getattr(msg, "content", None)
                     break
@@ -586,18 +586,18 @@ def _handle_agent_failure(
     store: "SessionStore",
     fallback: "Session",
 ) -> dict:
-    """Reload incident (absorbing partial tool writes), stamp a failure AgentRun,
+    """Reload session (absorbing partial tool writes), stamp a failure AgentRun,
     persist, and return the error state dict for the LangGraph node.
 
-    ``fallback`` is the in-memory incident from the caller; we use it only
+    ``fallback`` is the in-memory session from the caller; we use it only
     when the on-disk state has gone missing (FileNotFoundError on reload).
     """
     try:
-        incident = store.load(inc_id)
+        session = store.load(inc_id)
     except FileNotFoundError:
-        incident = fallback
+        session = fallback
     ended_at = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
-    incident.agents_run.append(AgentRun(
+    session.agents_run.append(AgentRun(
         agent=skill_name, started_at=started_at, ended_at=ended_at,
         summary=f"agent failed: {exc}",
         token_usage=TokenUsage(),
@@ -605,15 +605,15 @@ def _handle_agent_failure(
     # Mark the session as terminally failed so the UI can render a
     # retry control. The retry path (``Orchestrator.retry_session``)
     # is the only documented way to move out of this state.
-    incident.status = "error"
-    store.save(incident)
-    return {"session": incident, "next_route": None,
+    session.status = "error"
+    store.save(session)
+    return {"session": session, "next_route": None,
             "last_agent": skill_name, "error": str(exc)}
 
 
 def _record_success_run(
     *,
-    incident: "Session",
+    session: "Session",
     skill_name: str,
     started_at: str,
     final_text: str,
@@ -623,10 +623,10 @@ def _record_success_run(
     signal: str | None,
     store: "SessionStore",
 ) -> None:
-    """Append the success-path AgentRun, update the incident's running token
-    totals, and persist. Mutates ``incident`` in place."""
+    """Append the success-path AgentRun, update the session's running token
+    totals, and persist. Mutates ``session`` in place."""
     ended_at = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
-    incident.agents_run.append(AgentRun(
+    session.agents_run.append(AgentRun(
         agent=skill_name, started_at=started_at, ended_at=ended_at,
         summary=final_text or f"{skill_name} completed",
         token_usage=usage,
@@ -634,10 +634,10 @@ def _record_success_run(
         confidence_rationale=rationale,
         signal=signal,
     ))
-    incident.token_usage.input_tokens += usage.input_tokens
-    incident.token_usage.output_tokens += usage.output_tokens
-    incident.token_usage.total_tokens += usage.total_tokens
-    store.save(incident)
+    session.token_usage.input_tokens += usage.input_tokens
+    session.token_usage.output_tokens += usage.output_tokens
+    session.token_usage.total_tokens += usage.total_tokens
+    store.save(session)
 
 
 def make_agent_node(
@@ -699,9 +699,9 @@ async def node(state: GraphState) -> dict:
         # pending row, appends a duplicate, then ``store.save`` raises
         # ``StaleVersionError`` because DB has already moved on.
         try:
-            incident = store.load(inc_id)
+            session = store.load(inc_id)
         except FileNotFoundError:
-            incident = state_session
+            session = state_session
 
         # M3 (per-step telemetry): emit agent_started.
         if event_log is not None:
@@ -746,7 +746,7 @@ async def node(state: GraphState) -> dict:
             # keys from ``accepted_params``, the inject step skips them,
             # and FastMCP rejects the call as missing required arg.
             run_tools = [
-                wrap_tool(t, session=incident, gateway_cfg=gateway_cfg,
+                wrap_tool(t, session=session, gateway_cfg=gateway_cfg,
                           agent_name=skill.name, store=store,
                           injected_args=injected_args or {},
                           gate_policy=gate_policy,
@@ -792,7 +792,7 @@ def _run(**kwargs: Any) -> Any:
                 )
 
             run_tools = [
-                _make_inject_only_wrapper(orig, vis, incident)
+                _make_inject_only_wrapper(orig, vis, session)
                 for orig, vis in zip(tools, visible_tools)
             ]
         else:
@@ -820,7 +820,7 @@ def _run(**kwargs: Any) -> Any:
         # checkpointer``. The thread id is derived deterministically
         # from session + agent + the upcoming agent_run index so it is:
         #   * STABLE across the inner pause and the outer resume that
-        #     follows (both observe the same ``len(incident.agents_run)``
+        #     follows (both observe the same ``len(session.agents_run)``
         #     because no new run is recorded mid-pause), and
         #   * UNIQUE per agent invocation so previous invocations of the
         #     same agent within the same session don't bleed in.
@@ -831,7 +831,7 @@ def _run(**kwargs: Any) -> Any:
             checkpointer=checkpointer,
         )
         inner_thread_id = (
-            f"{inc_id}:agent:{skill.name}:turn{len(incident.agents_run)}"
+            f"{inc_id}:agent:{skill.name}:turn{len(session.agents_run)}"
         )
         inner_cfg = {"configurable": {"thread_id": inner_thread_id}}
 
@@ -840,7 +840,7 @@ def _run(**kwargs: Any) -> Any:
         # re-entry from a HITL pause the hint resets cleanly so a new
         # turn starts from "no signal yet" (None).
         try:
-            incident.turn_confidence_hint = None
+            session.turn_confidence_hint = None
         except (AttributeError, ValueError):
             pass
 
@@ -851,7 +851,7 @@ def _run(**kwargs: Any) -> Any:
                 inner_has_checkpointer=checkpointer is not None,
                 initial_input={
                     "messages": [
-                        HumanMessage(content=_format_agent_input(incident))
+                        HumanMessage(content=_format_agent_input(session))
                     ]
                 },
             )
@@ -895,19 +895,19 @@ def _run(**kwargs: Any) -> Any:
                 else:
                     return _handle_agent_failure(
                         skill_name=skill.name, started_at=started_at, exc=exc,
-                        inc_id=inc_id, store=store, fallback=incident,
+                        inc_id=inc_id, store=store, fallback=session,
                     )
             else:
                 return _handle_agent_failure(
                     skill_name=skill.name, started_at=started_at, exc=exc,
-                    inc_id=inc_id, store=store, fallback=incident,
+                    inc_id=inc_id, store=store, fallback=session,
                 )
 
         # Tools (e.g. registered patch tools) write straight to disk.
         # Reload so the node's own append of agent_run + tool_calls
         # happens against the tool-mutated state — otherwise saving
         # the stale in-memory object clobbers the tools' writes.
-        incident = store.load(inc_id)
+        session = store.load(inc_id)
 
         messages = result.get("messages", [])
         ts = datetime.now(timezone.utc).strftime(_UTC_TS_FMT)
@@ -915,7 +915,7 @@ def _run(**kwargs: Any) -> Any:
         # Record tool calls and harvest confidence/signal from configured
         # patch / typed-terminal tools.
         agent_confidence, agent_rationale, agent_signal = _harvest_tool_calls_and_patches(
-            messages, skill.name, incident, ts, valid_signals,
+            messages, skill.name, session, ts, valid_signals,
             terminal_tool_names=terminal_tool_names,
             patch_tool_names=patch_tool_names,
         )
@@ -923,12 +923,12 @@ def _run(**kwargs: Any) -> Any:
         # tool call sees the harvested confidence at the gateway.
         if agent_confidence is not None:
             try:
-                incident.turn_confidence_hint = agent_confidence
+                session.turn_confidence_hint = agent_confidence
             except (AttributeError, ValueError):
                 pass
 
         # Pair tool responses with their tool calls.
-        _pair_tool_responses(messages, incident)
+        _pair_tool_responses(messages, session)
 
         # Phase 10 (FOC-03 / D-10-03): parse the structural envelope and
         # reconcile its confidence against any typed-terminal-tool arg
@@ -939,7 +939,7 @@ def _run(**kwargs: Any) -> Any:
         except EnvelopeMissingError as exc:
             return _handle_agent_failure(
                 skill_name=skill.name, started_at=started_at, exc=exc,
-                inc_id=inc_id, store=store, fallback=incident,
+                inc_id=inc_id, store=store, fallback=session,
             )
 
         terminal_tool_for_log = _first_terminal_tool_called_this_turn(
@@ -976,12 +976,12 @@ def _run(**kwargs: Any) -> Any:
                 )
 
         _record_success_run(
-            incident=incident, skill_name=skill.name, started_at=started_at,
+            session=session, skill_name=skill.name, started_at=started_at,
             final_text=final_text, usage=usage,
             confidence=final_confidence, rationale=final_rationale, signal=final_signal,
             store=store,
         )
-        next_route_signal = decide_route(incident)
+        next_route_signal = decide_route(session)
         next_node = route_from_skill(skill, next_route_signal)
 
         # M3: emit route_decided + agent_finished (carrying token_usage).
@@ -1010,7 +1010,7 @@ def _run(**kwargs: Any) -> Any:
                     "event_log.record(agent_finished) failed", exc_info=True,
                 )
 
-        return {"session": incident, "next_route": next_node,
+        return {"session": session, "next_route": next_node,
                 "last_agent": skill.name, "error": None}
 
     return node
@@ -1057,7 +1057,7 @@ def _decide_from_signal(inc: Session) -> str:
 }
 
 
-def _latest_run_for(incident: Session, agent_name: str | None):
+def _latest_run_for(session: Session, agent_name: str | None):
     """Return the most recent ``AgentRun`` for ``agent_name``, or None.
 
     ``agent_name`` is whichever agent ran immediately before the gate,
@@ -1067,7 +1067,7 @@ def _latest_run_for(incident: Session, agent_name: str | None):
     """
     if not agent_name:
         return None
-    for run in reversed(incident.agents_run):
+    for run in reversed(session.agents_run):
         if run.agent == agent_name:
             return run
     return None
@@ -1129,7 +1129,7 @@ async def gate(state: GraphState) -> dict:
         # value on subsequent executions of the same node.
         from langgraph.types import interrupt
 
-        incident = state["session"]  # pyright: ignore[reportTypedDictNotRequiredAccess] — orchestrator runtime always supplies session
+        session = state["session"]  # pyright: ignore[reportTypedDictNotRequiredAccess] — orchestrator runtime always supplies session
         upstream = state.get("last_agent")
         # Capture the intended downstream target before we overwrite next_route.
         # The upstream agent set next_route to the gated target; we stash it in
@@ -1137,13 +1137,13 @@ async def gate(state: GraphState) -> dict:
         intended_target = state.get("next_route")
         # Reload from disk in case earlier nodes wrote tool-driven patches.
         try:
-            incident = store.load(incident.id)
+            session = store.load(session.id)
         except FileNotFoundError:
             pass
-        upstream_run = _latest_run_for(incident, upstream)
+        upstream_run = _latest_run_for(session, upstream)
         upstream_conf = upstream_run.confidence if upstream_run else None
         if upstream_conf is None or upstream_conf < threshold:
-            incident.status = "awaiting_input"
+            session.status = "awaiting_input"
             # Surface the upstream agent's own summary + rationale so the
             # human reviewer can decide what input to give without scrolling
             # through every step of the agents-run log.
@@ -1158,13 +1158,13 @@ async def gate(state: GraphState) -> dict:
                 "escalation_teams": teams,
                 "intended_target": intended_target,
             }
-            incident.pending_intervention = payload
+            session.pending_intervention = payload
             # CRITICAL ORDERING: persist the Session row BEFORE calling
             # ``interrupt()``. ``interrupt()`` raises ``GraphInterrupt`` on
             # first execution; if we reversed the order the UI (which
             # polls Session.pending_intervention) would never see the
             # pending state. See plan R4 / "Streamlit hand-off".
-            store.save(incident)
+            store.save(session)
             # First execution: this raises GraphInterrupt and the
             # checkpointer captures the paused state.
             # Resume: this returns the value supplied via
@@ -1187,17 +1187,17 @@ async def gate(state: GraphState) -> dict:
                 if isinstance(raw, str) and raw.strip():
                     user_text = raw.strip()
             if user_text is not None:
-                incident.user_inputs.append(user_text)
-            incident.pending_intervention = None
-            incident.status = "in_progress"
-            store.save(incident)
-            return {"session": incident, "next_route": "default",
+                session.user_inputs.append(user_text)
+            session.pending_intervention = None
+            session.status = "in_progress"
+            store.save(session)
+            return {"session": session, "next_route": "default",
                     "gated_target": intended_target, "last_agent": "gate", "error": None}
         # Confidence met threshold — clear any stale intervention payload.
-        if incident.pending_intervention is not None:
-            incident.pending_intervention = None
-            store.save(incident)
-        return {"session": incident, "next_route": "default",
+        if session.pending_intervention is not None:
+            session.pending_intervention = None
+            store.save(session)
+        return {"session": session, "next_route": "default",
                 "gated_target": intended_target, "last_agent": "gate", "error": None}
 
     return gate
diff --git a/src/runtime/orchestrator.py b/src/runtime/orchestrator.py
index 192920e..b72bcf5 100644
--- a/src/runtime/orchestrator.py
+++ b/src/runtime/orchestrator.py
@@ -69,7 +69,7 @@ def _assert_envelope_invariant_on_finalize(session: "Session") -> None:
 
 
 def _default_text_extractor(session) -> str:
-    """Default text extraction for the incident-management example.
+    """Default text extraction for the example incident-management app.
 
     Concatenates the operator-supplied ``query``, the intake-summary
     (when present), and any tags. Keeps the framework agnostic of the
@@ -1179,10 +1179,10 @@ async def start_session(self, *, query: str,
         kwargs once the row schema is fully generic).
 
         ``submitter`` is a free-form dict the app interprets. For
-        incident-management it is ``{"id": "...", "team": "..."}``; for
+        the example incident-management app it is ``{"id": "...", "team": "..."}``; for
         other apps it can carry app-specific keys (e.g. code-review's
         ``{"id": "<github-username>", "pr_url": "..."}``). The framework
-        only projects ``id``/``team`` onto the row's reporter columns;
+        only projects ``id``/``team`` onto the row's submitter columns;
         apps unpack the rest via their own MCP tools.
 
         Deprecated kwargs (coerced into ``state_overrides`` / ``submitter``
@@ -1260,7 +1260,7 @@ async def stream_session(self, *, query: str, environment: str,
                              ) -> AsyncIterator[dict]:
         """Start a new session and stream UI events as it runs.
 
-        Internally builds a ``submitter`` dict so the row's reporter
+        Internally builds a ``submitter`` dict so the row's submitter
         columns are populated through the same coercion path
         ``start_session`` uses.
         """
@@ -1310,7 +1310,7 @@ async def stream_investigation(self, *, query: str, environment: str,
         """Deprecated alias for ``stream_session``.
 
         Forwards the legacy positional surface into ``stream_session``;
-        the underlying flow already coerces the reporter pair into
+        the underlying flow already coerces the submitter pair into
         a submitter dict internally so no runtime deprecation fires.
         """
         async for event in self.stream_session(
diff --git a/src/runtime/service.py b/src/runtime/service.py
index 3cd34f0..c75b5e6 100644
--- a/src/runtime/service.py
+++ b/src/runtime/service.py
@@ -444,10 +444,10 @@ def start_session(
         through to app-specific MCP tools.
 
         ``submitter`` is a free-form dict the calling app interprets.
-        For incident-management it is ``{"id": "...", "team": "..."}``;
+        For the example incident-management app it is ``{"id": "...", "team": "..."}``;
         other apps can carry app-specific keys (e.g. code-review's
         ``{"id": "<github-username>", "pr_url": "..."}``). The framework
-        only projects ``id``/``team`` onto the row's reporter columns.
+        only projects ``id``/``team`` onto the row's submitter columns.
 
         Deprecated kwargs (coerced and warned):
           * ``environment`` -> ``state_overrides={"environment": ...}``
diff --git a/src/runtime/similarity.py b/src/runtime/similarity.py
index 51d3bca..94376fc 100644
--- a/src/runtime/similarity.py
+++ b/src/runtime/similarity.py
@@ -1,4 +1,4 @@
-"""Similarity scoring for incident matching."""
+"""Similarity scoring for session matching."""
 from __future__ import annotations
 from typing import Protocol
 import re
diff --git a/src/runtime/state.py b/src/runtime/state.py
index 213a443..a7f16b4 100644
--- a/src/runtime/state.py
+++ b/src/runtime/state.py
@@ -5,7 +5,7 @@
 
     class IncidentState(Session):
         environment: str
-        reporter: Reporter
+        submitter: Submitter
         ...
 
 ``Session`` deliberately contains *no* domain-specific fields. Adding one
@@ -124,7 +124,7 @@ def to_agent_input(self) -> str:
 
         Apps subclass ``Session`` and override this to surface the
         domain shape (``Incident X / Environment Y / Query Z`` for the
-        incident-management app, ``PR title / repo / diff stats`` for
+        example app, ``PR title / repo / diff stats`` for
         code review, etc.). The framework default keeps the prompt
         framework-agnostic — id + status only — so that any app that
         has not overridden the hook still gets a usable preamble.
@@ -156,7 +156,7 @@ def id_format(cls, *, seq: int, prefix: str = "SES") -> str:
 
         ``prefix`` is supplied by ``SessionStore._next_id`` from
         ``FrameworkAppConfig.session_id_prefix`` so each app picks its
-        own namespace via plain config (e.g. ``INC`` for incident
+        own namespace via plain config (e.g. ``INC`` for the example incident
         management, ``REVIEW`` for code review, ``HR`` for HR cases,
         ...). Apps with truly bespoke id shapes can still override this
         classmethod on their ``Session`` subclass and ignore ``prefix``.
diff --git a/src/runtime/storage/history_store.py b/src/runtime/storage/history_store.py
index c7c8fea..f4a16a3 100644
--- a/src/runtime/storage/history_store.py
+++ b/src/runtime/storage/history_store.py
@@ -11,8 +11,8 @@
 
 ``find_similar`` accepts an arbitrary ``filter_kwargs`` mapping — keys
 must correspond to ``IncidentRow`` columns. This decouples the
-framework from incident-specific filter dimensions: apps with a
-``severity``-only schema, or a multi-tenant ``tenant_id`` schema, or
+framework from app-specific filter dimensions: apps with a
+schema with a single status-tier field, a multi-tenant ``tenant_id`` schema, or
 anything else, build their filter on the fly.
 """
 from __future__ import annotations
@@ -211,7 +211,7 @@ def _ef(i, key, default: Any = ""):
                     _ef(i, "summary", "") or "",
                     " ".join(_ef(i, "tags", []) or []),
                 ])),
-                "incident": i,
+                "session": i,
             }
             for i in candidates_inc
         ]
@@ -221,4 +221,4 @@ def _ef(i, key, default: Any = ""):
             threshold=self.similarity_threshold if threshold is None else threshold,
             limit=limit,
         )
-        return [(c["incident"], float(s)) for c, s in results]
+        return [(c["session"], float(s)) for c, s in results]
diff --git a/src/runtime/storage/session_store.py b/src/runtime/storage/session_store.py
index d3c255e..4d0db9e 100644
--- a/src/runtime/storage/session_store.py
+++ b/src/runtime/storage/session_store.py
@@ -9,7 +9,7 @@
 The class is parametrised as ``Generic[StateT]`` and routes row
 hydration through ``self._state_cls(...)`` so apps can plug in their
 own ``Session`` subclass via ``RuntimeConfig.state_class``. The row
-schema remains incident-shaped, but unused fields are dropped via
+schema remains the row-level shape, but unused fields are dropped via
 Pydantic's default ``extra='ignore'`` when a narrower ``state_cls`` is
 supplied.
 """
@@ -112,7 +112,7 @@ class StaleVersionError(RuntimeError):
 
 
 class SessionStore(Generic[StateT]):
-    """Active session/incident lifecycle store, parametrised on ``StateT``.
+    """Active session lifecycle store, parametrised on ``StateT``.
 
     Owns CRUD on the row schema plus the vector write-through. Read-only
     similarity search lives in ``HistoryStore``.
@@ -231,7 +231,7 @@ def create(self, *, query: str, environment: str,
     def load(self, incident_id: str) -> StateT:
         if not _SESSION_ID_RE.match(incident_id):
             raise ValueError(
-                f"Invalid incident id {incident_id!r}; expected PREFIX-YYYYMMDD-NNN"
+                f"Invalid session id {incident_id!r}; expected PREFIX-YYYYMMDD-NNN"
             )
         with SqlSession(self.engine) as session:
             row = session.get(IncidentRow, incident_id)
@@ -239,40 +239,39 @@ def load(self, incident_id: str) -> StateT:
                 raise FileNotFoundError(incident_id)
             return self._row_to_incident(row)
 
-    def save(self, incident: StateT) -> None:
-        if not _SESSION_ID_RE.match(incident.id):
+    def save(self, session: StateT) -> None:
+        if not _SESSION_ID_RE.match(session.id):
             raise ValueError(
-                f"Invalid incident id {incident.id!r}; expected PREFIX-YYYYMMDD-NNN"
+                f"Invalid session id {session.id!r}; expected PREFIX-YYYYMMDD-NNN"
             )
         # ``_iso(_now())`` returns ``str`` here -- the input datetime is
         # never None -- but the helper's signature is the broader
         # ``Optional[str]``. ``or ""`` keeps pyright + the typed
         # ``Session.updated_at: str`` field consistent without changing
         # behaviour (real value is always present).
-        incident.updated_at = _iso(_now()) or ""
-        sess = incident  # local alias — avoids repeating the domain token in new code
-        expected_version = getattr(sess, "version", 1)
+        session.updated_at = _iso(_now()) or ""
+        expected_version = getattr(session, "version", 1)
         # Bump in-memory BEFORE building the row dict so the persisted
         # row reflects the new version.
-        sess.version = expected_version + 1
-        with SqlSession(self.engine) as session:
-            existing = session.get(IncidentRow, sess.id)
+        session.version = expected_version + 1
+        with SqlSession(self.engine) as db_session:
+            existing = db_session.get(IncidentRow, session.id)
             prior_text = _embed_source_from_row(existing) if existing is not None else ""
             if existing is not None and existing.version != expected_version:
                 # Roll back the in-memory bump so the caller can reload + retry.
-                sess.version = expected_version
+                session.version = expected_version
                 raise StaleVersionError(
-                    f"session {sess.id} version is {existing.version}, "
+                    f"session {session.id} version is {existing.version}, "
                     f"expected {expected_version}"
                 )
-            data = self._incident_to_row_dict(incident)
+            data = self._incident_to_row_dict(session)
             if existing is None:
-                session.add(IncidentRow(**data))
+                db_session.add(IncidentRow(**data))
             else:
                 for k, v in data.items():
                     setattr(existing, k, v)
-            session.commit()
-        self._refresh_vector(incident, prior_text=prior_text)
+            db_session.commit()
+        self._refresh_vector(session, prior_text=prior_text)
 
     def delete(self, incident_id: str) -> StateT:
         with SqlSession(self.engine) as session:
@@ -471,10 +470,10 @@ def _row_to_incident(self, row: IncidentRow) -> StateT:
 
         Fields are pulled from typed columns when the state class
         declares them; everything else is merged in from the
-        ``extra_fields`` JSON bag. ``reporter`` is reconstituted from
+        ``extra_fields`` JSON bag. The ``reporter`` field (when present) is reconstituted from
         the typed ``reporter_id`` / ``reporter_team`` columns *only* when
-        the state class has a ``reporter`` field — otherwise it's
-        omitted so apps without a reporter concept (code-review) don't
+        the state class declares it — otherwise it's
+        omitted so apps without that concept (code-review) don't
         receive an unexpected attribute.
         """
         model_fields = self._state_cls.model_fields
diff --git a/tests/test_genericity_ratchet.py b/tests/test_genericity_ratchet.py
index 37a8496..591d10a 100644
--- a/tests/test_genericity_ratchet.py
+++ b/tests/test_genericity_ratchet.py
@@ -85,7 +85,33 @@
 #                domain Session) on a structurally required code path —
 #                same pattern as the Phase 10/11/12 entries. Net +2
 #                ``incident`` token reuses, no new domain concept.
-BASELINE_TOTAL = 156
+#   156 ->  39   v1.5-B generic-noun pass. Three classes of change:
+#                  (1) ``incident`` local variables in graph.py /
+#                      responsive.py / supervisor.py / dedup.py /
+#                      session_store.py renamed to ``session`` via a
+#                      tokenize-based safe rename (~95 tokens removed).
+#                  (2) Docstring + exception-message text in graph.py /
+#                      state.py / dedup.py / orchestrator.py / service.py /
+#                      similarity.py / config.py / history_store.py /
+#                      session_store.py rewritten to use the framework's
+#                      generic vocabulary; explicit ``incident-management``
+#                      mentions are kept only where they label the example
+#                      app specifically.
+#                  (3) ``history_store.py`` internal dict key changed from
+#                      ``"incident"`` to ``"session"`` (private to that
+#                      module's similarity-search return shape).
+#                The remaining 39 are domain-coupled and intentionally
+#                preserved without functional change: the ``severity``
+#                / ``reporter_*`` SQLAlchemy columns on ``IncidentRow``
+#                (renaming requires a migration), the legacy
+#                ``/incidents/*`` URL routes (public API surface that
+#                v1.4 deprecated but did not remove), the ``reporter_id``
+#                / ``reporter_team`` deprecated kwargs on
+#                ``Orchestrator.start_session`` /
+#                ``OrchestratorService.start_session``, and the
+#                example-app references in dedup default prompts /
+#                docstring callouts.
+BASELINE_TOTAL = 39
 
 
 def test_runtime_leaks_at_or_below_baseline():
diff --git a/tests/test_graph_helpers.py b/tests/test_graph_helpers.py
index d8e9fec..59000dd 100644
--- a/tests/test_graph_helpers.py
+++ b/tests/test_graph_helpers.py
@@ -38,7 +38,7 @@ def test_recorder_appends_agent_run_and_tool_calls():
             "reporter": {"id": "u", "team": "t"},
         },
     )
-    rec = AgentRunRecorder(agent="intake", incident=inc)
+    rec = AgentRunRecorder(agent="intake", session=inc)
     rec.start()
     rec.record_tool_call("get_user_context", {"user_id": "u"}, {"team": "platform"})
     rec.finish(summary="created INC")
diff --git a/tests/test_incident_store.py b/tests/test_incident_store.py
index b18e79d..bce64f4 100644
--- a/tests/test_incident_store.py
+++ b/tests/test_incident_store.py
@@ -60,14 +60,14 @@ def test_list_recent_returns_newest_first(store):
 
 def test_load_invalid_id_raises_value_error(store):
     """IDs not matching INC-YYYYMMDD-NNN must be rejected before any DB ops."""
-    with pytest.raises(ValueError, match="Invalid incident id"):
+    with pytest.raises(ValueError, match="Invalid session id"):
         store.load("../../etc/passwd")
 
 
 def test_save_invalid_id_raises_value_error(store):
     inc = store.create(query="Q", environment="dev", reporter_id="u", reporter_team="t")
     inc.id = "../../malicious"
-    with pytest.raises(ValueError, match="Invalid incident id"):
+    with pytest.raises(ValueError, match="Invalid session id"):
         store.save(inc)
 
 
@@ -85,7 +85,7 @@ def test_load_missing_raises(store):
     "INC-20260430-1",  # too short sequence
 ])
 def test_load_rejects_traversal_and_malformed_ids(store, bad_id):
-    with pytest.raises(ValueError, match="Invalid incident id"):
+    with pytest.raises(ValueError, match="Invalid session id"):
         store.load(bad_id)