--- title: "Situational Awareness overview" description: "What the SA pillar is, the three slices (taskwork, agent, teamwork), and the discrete state labels the harness uses to describe its own posture." slug: guides/situational-awareness/overview section: guides subsection: situational-awareness canonical_url: https://cerevisor.com/docs/guides/situational-awareness/overview last_verified: 2026-05-18 last_verified_version: "1.2.0" updated_at: 2026-05-18T15:08:18.053416+00:00 --- ## What SA is **Situational Awareness** is Cerevisor's continuously-updated, three-level picture of a workflow run. The pillar sits on top of memory, the orchestrator, and persistence; it does not own state, it composes signals already produced by the rest of the harness into typed snapshots that the chat builder, the orchestrator, and the renderer can all read. The pillar is grounded in three pieces of academic work: - **Endsley's 3-level SA**: perception (what's happening), comprehension (what it means), projection (what's likely next). - **Endsley 2023's human-AI SA split**: when humans and AI work together, awareness divides into taskwork, agent, and teamwork dimensions. - **Distributed SA**: awareness lives across people, tools, and artifacts, not inside any single component. In Cerevisor, this turns into: snapshots that name uncertainty explicitly, attribute every load-bearing claim to its source, and surface gaps instead of papering over them. ## The three slices Every situation snapshot has three slices. The chat builder and the run drawer surface them as separate panels. ### 1. Taskwork SA: awareness of the task What this workflow is, what's changed since you last interacted, what other workflows in the workspace you've touched. - **`sinceLastSession`**: how many runs happened since you last opened the chat builder for this workflow, how many succeeded, how many didn't, when the most recent run was, and up to three newly-detected blind spots. - **`siblingWorkflows`**: other workflows in the same workspace with their last-run timestamp and status. The chat-builder opener uses this slice to lead with concrete deltas instead of "what would you like to build?". ### 2. Agent SA: awareness of the agents What the harness believes about its own agents' recent uncertainty and the patterns it thinks hold. - **`lastUncertaintyByRole`**: the most recent uncertainty snapshot for each role that has run, capped to keep the panel readable. - **`topPatterns`**: patterns the harness believes hold (e.g. "researcher does better with three sub-questions than five"), each tagged with its source (`user-explicit`, `user-implicit`, `harness-inferred`, `harness-extrapolated`) and a confidence value. - **`openBlindSpots`**: known unknowns the harness is currently tracking. This is the panel you read when something feels off. If an agent ran with `verifierState: 'rejected'` or no confidence marker at all, that shows up here before you have to dig through audit logs. ### 3. Teamwork SA: awareness of the working relationship What you and the harness have agreed on, where you disagree, and what's still an open question. - **`openDisagreements`**: places where you claimed one thing and the harness's observations suggest another. Each item carries your claim, the harness's observation, and the confidence gap. - **`conversationState`**: when a chat-builder session is active, the running accumulator of what you've accepted, rejected, clarified, and the questions still on the table. This is the slice that prevents the harness from suggesting the same thing again after you already pushed back. ## State labels Every snapshot carries a coarse `SAStateLabel` summarizing the harness's overall posture for this workflow: | State | Meaning | |---|---| | **`baseline`** | No prior runs to compare against. First-time territory. | | **`high-confidence-known-domain`** | Mature profile + recent runs + stable patterns. The harness has been here many times. | | **`low-confidence-new-domain`** | Sparse profile or many recent surprises. Be skeptical of confident-sounding suggestions. | | **`fixation-risk`** | The same Loop & Enhance round fingerprint or pattern has repeated. The harness might be stuck. | | **`context-stale`** | Freshness score is below threshold (see Context Freshness below). | | **`unknown`** | Not enough data to label. | The label appears as a small badge in the chat-builder header and the run drawer. ## Context Freshness SA tracks how stale the harness's current picture is via a unified `ContextFreshness` score in `[0, 1]` (1 = fresh), composed from four sub-ratios: | Component | What it measures | |---|---| | `patternStalenessRatio` | Fraction of believed patterns that have been confirmed recently. | | `folderAgeRatio` | How recently the workflow's folder.md was updated. | | `profileAgeRatio` | How recently your user profile was touched. | | `runRecencyRatio` | How recently any run completed for this workflow. | A `score` below the threshold flips the state label to `context-stale`. The full breakdown is visible in the SA panel. ## Unknowns: things the harness doesn't yet know SA surfaces "unknowns" as first-class objects you can read, ask about, and resolve. Each unknown has a kind, a one-line explanation, and a suggested question the chat builder can ask to close the gap. | Kind | Triggered when | |---|---| | `profile-blank` | A profile section is empty. | | `folder-missing` | The workflow has no folder.md, or it's empty. | | `role-unobserved` | An agent role has never run in this workspace. | | `pattern-untested` | A believed workflow pattern has no successful runs yet. | | `user-preference-implicit` | The harness inferred a preference but never asked you to confirm it. | The chat builder volunteers these as topics for first-turn conversations, rather than waiting for you to wonder why a suggestion feels off. ## Belief attribution A central design choice in SA: every stored belief or pattern carries a `BeliefSource` tag so the chat builder can phrase suggestions as **"you told me X"** vs **"I inferred X"** instead of conflating the two. Tags: | Source | What it means | |---|---| | `user-explicit` | You typed it directly. | | `user-implicit` | Observed from your behavior. | | `harness-inferred` | Derived from one or more runs. | | `harness-extrapolated` | Generalized beyond the direct evidence. | Strength is separately tagged (`asserted`, `observed`, `guessed`) and a timestamp is attached to each marker. This is how the harness avoids the failure mode where it confidently restates back to you something it actually only inferred once. ## How SA composes with the rest of the harness SA is the read layer on top of: - [Harness memory and meta-cognition](../memory-and-learning/harness-memory-and-meta-cognition.md): the observation store, the self-portrait, the per-role learnings. - [Disagreements and proposals](../memory-and-learning/disagreements-and-proposals.md): the source of `openDisagreements`. - [Loop & Enhance](../advanced/loop-and-enhance.md): the source of `fixation-risk` warnings. - The semantic verifier: the source of `verifierState` per agent run. SA does not duplicate these systems; it composes their outputs into one coherent picture. ## Where to go next - [Configure and run](./configure-and-run.md): the SA Directive, the per-agent uncertainty badge, the wave situation report.