feat(stella-observatory): Sessions tab — session replay & inspection, prompt diff (#1511), tendencies, self-improvement residue

[macanderson]

What & why

stella observe gets a session-first inspection surface: a Sessions tab listing every session of the workspace (the ~/.stella/sessions/ registry — with the read-time pid-liveness crash downgrade — merged with per-session store rollups), drilling session → turn → step → tool call through the existing execution drawer. On top of it:

• Prompt diff, served (stella-observatory: what CHANGED between two model calls — surface stella inspect --diff in the dashboard #1511): /api/execution-context-diff is stella inspect --diff in the dashboard — unified hunks in git's exact shape between one call's receipt-reconstructed context and its resolved baseline (prev/first/prompt, same-role, whole-session — the semantics crates/stella-cli/src/inspect.rs is careful about, including reporting the resolved base and the minimal: false coarse flag). The pure differ is extracted from stella-cli's inspect::diff into a new zero-dependency leaf crate stella-diff (the stella-home precedent, per stella-observatory: what CHANGED between two model calls — surface stella inspect --diff in the dashboard #1511's triage) rather than becoming a fourth acknowledged copy; the CLI now links it, behavior-preserving (its 10 inspect_cli tests pass unchanged).
• Behavioural tendencies: /api/execution-tendencies — a sanctioned per-execution events fold (retries, loop detections by kind + aborts, budget denials, compactions + tokens reclaimed, policy verdicts, speculation discards, steering, provider fallbacks) rendered as a strip in the drawer.
• Self-improvement residue per session: mined lessons (reflections joined through executions.session_id), durable memory writes (recovered from the save_memory tool-call log), memory citations, skills applied, subagents dispatched, MCP traffic, task board, and PRs.
• The tier chain closes: the Org/hub project drill now lands on the project's Sessions tab, so the descent runs org → workspace → repo → project → session → turn → step → call → block/tool without a dead end. Tool leaderboard gains p90/p99 (the durations window was already materialized for p50).

Design constraints honoured: no cross-execution events queries (the session view fans out one execution at a time through the existing per-execution routes); younger tables (skill_usage, mcp_usage, step_receipt) are folded in separate queries so an older store blanks one column, not the whole view; every route degrades to an empty payload on missing files/tables/columns; every interpolated string in the page goes through esc().

Exemplars followed: self_driving.rs for the file-backed module shape, sent_context.rs for the sibling-module seam, stella-home (#1139) for the leaf-crate extraction.

Closes #1511

The witness

• This PR includes a witness test (fails on main, passes here)

tests/schema_conformance.rs::context_diff_names_the_moved_line_and_reports_identity_honestly — two same-role calls whose system prefixes differ by one line across a turn boundary produce exactly one hunk naming that line; a byte-identical pair reports changed: false; prev on a role's first call resolves to prompt and says so. 404s on main (route absent). The sessions routes are additionally covered by every_route_survives_the_real_store_schema with seeded-data pointers (/sessions/0/id, /turns/0/id, /retries), the older-store degradation sweep, and every_served_route_is_fetched_by_the_embedded_page.

The gate

• cargo fmt --check
• cargo clippy -p stella-diff -p stella-observatory -p stella-cli --all-targets -- -D warnings (workspace clippy/test run in CI)
• cargo test -p stella-observatory -p stella-diff (87 tests) and -p stella-cli --test inspect_cli (10) green locally
• Docs updated: observatory README (layout, acknowledged copies), new stella-diff README, AGENTS.md workspace table + crate counts
• Closes #1511 appears both above and as a commit trailer

Nothing left behind

• Filed: stella-store: project behavioural tendencies per turn (turn_tendencies) so they aggregate beyond one execution #1868 (turn_tendencies store projection for cross-session aggregation), stella-store: replicate session_id to the usage hub so the org drill can reach sessions #1869 (replicate session_id to the usage hub so the org drill reaches sessions), stella-observatory: real per-turn git diffs in session replay from the work journal (refs/stella/<session>/turn/<n>) #1870 (real per-turn git diffs from the work journal's unread refs/stella/<session>/turn/<n>), stella-observatory: surface context.db's self-improvement plane — promotion audit trail, episodes, selection health #1871 (context.db promotion audit trail / episodes unread by the observatory), stella-cli: skill_usage is recorded only on the deck path — pipeline and headless runs report zero skill telemetry #1872 (skill_usage recorded only on the deck path)

Ground-rule check

• No I/O added to stella-core. New deps, both justified in manifests: stella-diff (new zero-dep leaf crate, extraction not addition) and libc in the observatory (one kill(pid, 0) liveness probe, an acknowledged copy of stella_store::sessions::pid_alive; opens nothing, writes nothing).
• No new outbound network calls.

Anything reviewers should know?

• The hub project drill previously landed on Overview; it now lands on Sessions — deliberate, called out here in case anyone preferred the old landing.
• sessions.rs reads the machine-global registry but filters records to the served workspace (canonicalized path compare, falling back to string compare for deleted workspaces).
• The /api/session id is the one client string that meets the filesystem; it is charset-gated (safe_session_id) before any read.

Summary by Sourcery

Introduce a workspace-wide Sessions tab with session replay, behavioural tendencies, and self-improvement views, and share a unified prompt-diff implementation between CLI and observatory via a new stella-diff crate.

New Features:

• Add a Sessions tab to the observatory dashboard that lists all workspace sessions with per-session metrics and supports drilling into turns and executions for replay.
• Expose a prompt-diff view in the execution drawer that shows unified diffs between a call’s reconstructed context and its resolved baseline, including scope toggling.
• Surface behavioural tendencies for each execution, summarizing retries, loops, compactions, policy decisions, and related events alongside the transcript.
• Provide session-level panels for skills and agents usage, MCP traffic, self-improvement residue (lessons and memory activity), and task/pr outcomes.
• Add p90 and p99 latency percentiles to the tool leaderboard in the observatory UI.

Enhancements:

• Route hub project-level drilldowns to land on a project’s Sessions tab to extend the org→workspace→repo→project→session inspection chain.
• Ensure sessions-related queries and tendencies folds degrade gracefully on older or partially populated stores, and keep interpolated strings escaped for safety.
• Extract the unified diff logic into a new dependency-free stella-diff crate and wire stella-cli’s inspect command to use it instead of an internal module.

Documentation:

• Update observatory and workspace documentation to describe the Sessions plane, the new prompt-diff route, and the stella-diff crate in the crate layout and god-file tables.

Tests:

• Extend observatory schema conformance tests to cover sessions, session detail, execution tendencies, and execution-context-diff routes with seeded data.
• Add a witness test that validates prompt-diff semantics across turns, within turns, and for first-call baselines, matching the expected unified diff behaviour.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
stella-cli-docs	Ignored	Preview	Aug 6, 2026 11:10am

[sourcery-ai]

Reviewer's Guide

Adds a new Sessions tab and supporting backend in stella-observatory to list and replay sessions (including tendencies and self-improvement residue), introduces a shared stella-diff crate for unified prompt diffs used by both CLI and observatory, and extends telemetry/tool leaderboards and schema tests to cover the new functionality.

Sequence diagram for execution context diff and tendencies in the drawer

sequenceDiagram
  actor User
  participant UI as Browser_UI
  participant OBS as Observatory_HTTP
  participant DB as Observatory_db
  participant CTX as context_diff
  participant SESS as sessions
  participant DIFF as stella_diff
  participant STORE as store_db

  User->>UI: Open execution drawer
  UI->>OBS: GET /api/execution-journal?id
  UI->>OBS: GET /api/execution-context?id
  UI->>OBS: GET /api/execution-tendencies?id

  OBS->>DB: execution_tendencies(id)
  DB->>SESS: execution_tendencies(conn, id)
  SESS->>STORE: SELECT event_type,payload FROM events
  SESS-->>DB: tendencies JSON
  DB-->>OBS: tendencies JSON
  OBS-->>UI: tendencies JSON

  User->>UI: Click "what changed" on a call
  UI->>OBS: GET /api/execution-context-diff?id&turn&step&call_seq&base=prev&only=all

  OBS->>DB: execution_context_diff(id, turn, step, call_seq, base, only)
  DB->>CTX: payload(conn, id, turn, step, call_seq, base, only)
  CTX->>STORE: step_receipt / executions / events queries
  CTX->>DIFF: unified_diff(old_doc, new_doc, 3)
  DIFF-->>CTX: Diff { hunks, added, removed, minimal }
  CTX-->>DB: diff payload JSON
  DB-->>OBS: diff payload JSON
  OBS-->>UI: diff payload JSON
  UI-->>User: Render unified diff hunks

Loading

File-Level Changes

Change	Details	Files
Add a Sessions tab UI for session listing, drill-down, replay, and self-improvement surfaces in the observatory dashboard.	Introduce a new sessions tab and panel layout in the observatory index.html, with cards for session list, turn list, skills/agents, MCP traffic, self-improvement, and outcomes. Implement client-side rendering and interaction logic for sessions: fetching /api/sessions, default selection, per-session summary metrics, and turn table rendering with badges and derived stats. Wire clicks on session rows to openSession and on turn rows to openDrawer, reusing the existing execution drawer for per-turn replay. Ensure the sessions tab is lazily loaded, never cached, and refreshed when live polling or SSE indicate changes to keep liveness and status up to date.	crates/stella-observatory/src/assets/index.html
Implement backend routes and data-folds for sessions, session detail, and per-execution behavioural tendencies, including joining registry and store data.	Add new observatory routes /api/sessions, /api/session, and /api/execution-tendencies in the HTTP responder, delegating to Observatory methods. Implement Observatory::sessions, ::session, and ::execution_tendencies in db.rs to call into the new sessions/context modules and manage missing-store degradations. Create sessions.rs to read ~/.stella/sessions registry files with pid-based liveness downgrade, join them with per-session rollups from store tables, and expose /api/sessions payloads. In sessions.rs, implement per-session detail view: session_turns aggregation, per-turn extras (skills, MCP servers, receipts, reflections), session-level aggregates (skills, MCP, agents, memory citations, task board, PRs, lessons, memory writes) with per-table graceful degradation. Add pid_alive helper that mirrors stella_store::sessions::pid_alive using libc::kill(pid, 0) on Unix and a safe_session_id gate to prevent path traversal when reading registry files. Add execution_tendencies folding over events for retries, loop detections, compactions, policy decisions, speculation discards, steering, provider fallbacks, and usage_incomplete, returning an all-zero payload when events/schema are missing.	crates/stella-observatory/src/lib.rs crates/stella-observatory/src/db.rs crates/stella-observatory/src/sessions.rs
Expose prompt context diff functionality via a shared stella-diff crate and an observatory route that mirrors stella inspect --diff semantics.	Extract unified diff implementation from stella-cli into a new stella-diff crate with public Diff, Hunk, DiffLine, Op, and unified_diff, maintaining longest-common-subsequence behaviour with an LCS_AREA_CAP and tests. Wire stella-cli inspect.rs to use stella_diff::Diff, Op, unified_diff instead of its internal diff module, keeping behaviour and tests unchanged. Add stella-diff as a dependency in stella-cli and stella-observatory Cargo manifests and register the crate in the workspace Cargo.toml. Introduce context_diff.rs in stella-observatory to implement /api/execution-context-diff: reconstruct the target call, resolve baselines (prev/first/prompt) across the whole session by role, and produce JSON parallel to stella inspect --diff --format json including hunks lines with op tags. Expose execution_context_diff on Observatory, returning a not-found payload when manifest entries are absent or store is missing.	crates/stella-diff/src/lib.rs crates/stella-diff/Cargo.toml crates/stella-diff/README.md crates/stella-cli/src/inspect.rs crates/stella-cli/Cargo.toml crates/stella-observatory/src/context_diff.rs crates/stella-observatory/src/db.rs crates/stella-observatory/src/lib.rs Cargo.toml
Extend the observatory UI to show per-execution behavioural tendencies and integrate the prompt diff controls into the execution drawer.	Fetch /api/execution-tendencies alongside /api/execution-context in loadDrawer and render a Tendencies section using badges for nonzero counters and maps for loop kinds and policy verdicts, with proper escaping. Update the context-sent section to add a "what changed" button per call that triggers loadContextDiff with base=prev and selectable scope (system vs all roles). Implement loadContextDiff on the client to call /api/execution-context-diff with appropriate query params, handle missing receipts gracefully, render diff metadata (base_label, target_label, added/removed, scope, coarse/minimal, prompt baseline) and hunks with coloring matching git-like +/- semantics, and support toggling scope via a dedicated button. Ensure new client-side handlers are wired after drawer render and that they coexist with existing sent-context and journal functionality.	crates/stella-observatory/src/assets/index.html
Update tool leaderboard metrics and hub drill behaviour to close the org→workspace→repo→project→session descent and surface higher percentiles.	Extend model/tool leaderboard aggregation to compute p90 and p99 latency from already-materialized durations and expose them in JSON (p50_ms, p90_ms, p99_ms, max_ms). Update tooltip rendering for top tools in index.html to include p90 and p99 latencies in the tooltip text. Change hub drill UI copy and behaviour so drilling into a project sets state.project and switches to the Sessions tab instead of Overview, continuing the descent into sessions and per-execution replay. Keep refresh logic consistent by reloading the sessions tab on cursor moves and SSE changes when sessions is the active tab.	crates/stella-observatory/src/db.rs crates/stella-observatory/src/assets/index.html
Broaden tests and documentation to cover the new sessions and diff functionality and maintain schema and degradation guarantees.	Extend schema_conformance.rs to seed a real store workspace with session_id on executions, behavioural events, task board and pull request rows, and system-prefix drift receipts; add ROUTES entries for /api/sessions, /api/session, /api/execution-tendencies, and /api/execution-context-diff and a witness test verifying baseline resolution and naming of the drift line for context diff. Update observatory tests to treat the new routes as part of the "degrade to empty payload, not errors" set when workspace/store artifacts are missing. Add README entries in stella-observatory to describe context_diff.rs and sessions.rs modules and update the acknowledged copies list and layout table. Update AGENTS.md to account for the new stella-diff crate, adjust crate counts and the god-files summary. Ensure sent_context.rs exposes manifest_entries and journal_payloads as pub(crate) for reuse by context_diff, preserved without changing existing behaviour.	crates/stella-observatory/tests/schema_conformance.rs crates/stella-observatory/src/tests.rs crates/stella-observatory/README.md AGENTS.md crates/stella-observatory/src/sent_context.rs

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#1511	Implement a backend route /api/execution-context-diff that serves a unified diff between a specific model call’s reconstructed context and a resolved baseline (prev/first/prompt), matching stella inspect --diff --format json semantics (same-role, whole-session baseline search across executions, only role filter, resolved base reported, minimal flag, non-500 degradation).	✅
#1511	Add a dashboard UI control in the execution drawer’s Context sent section to show "what changed since the previous call of this role", consuming /api/execution-context-diff, rendering unified hunks with add/remove colouring, supporting role scope toggling, and wired into the existing tests and degradation behavior so empty/missing data yields empty payloads rather than errors.	✅
#1511	Eliminate a fourth copy of the unified differ by either copying it with explicit acknowledgment and drift-gate or (preferably) extracting it into a pure leaf crate, and update documentation (observatory README, AGENTS.md) accordingly while keeping db.rs under the file-size ratchet by placing new logic in sibling modules.	✅

Possibly linked issues

• #stella-observatory #? (phase 3 prompt diff): They both request and implement /api/execution-context-diff and the dashboard “what changed” prompt diff UI using stella-diff.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.