---
title: "Configure and run Situational Awareness"
description: "Edit the SA Directive, read the per-agent uncertainty badge, interpret the wave situation report, and handle fixation warnings."
slug: guides/situational-awareness/configure-and-run
section: guides
subsection: situational-awareness
canonical_url: https://cerevisor.com/docs/guides/situational-awareness/configure-and-run
last_verified: 2026-05-18
last_verified_version: "1.2.0"
updated_at: 2026-05-18T15:08:18.053416+00:00
---

SA is on by default in v1.2.0. This page covers the user-facing controls: the SA Directive (what the harness gets told to do), the per-agent uncertainty badge (what you see), the wave situation report (what carries between waves), and the fixation warning (what fires when the loop gets stuck).

## The SA Directive

The **SA Directive** is an always-on framing appended to every agent's system prompt, alongside the Wow Directive. It tells the model to maintain situational awareness throughout the task instead of charging at completion.

**Toggle and edit:** **Settings → Workflow → SA Directive.** The toggle defaults to **enabled**. The text is editable.

The default directive (restored when you clear the field while enabled) is:

> Maintain situational awareness throughout this task. Before claiming completion, ask: what changed since I started, what do I actually know vs. assume, what's likely next, and what's still unknown? Name uncertainty explicitly, prefer 'I don't know yet' over fabrication. Attribute every load-bearing claim to its source (a file you read, a tool result you observed, an instruction from the user, or your own inference). Surface gaps and contradictions instead of papering over them.

**Why a separate directive (not a flag on the Wow Directive):** Wow asks *is this output worth showing off?*. SA asks *does this output honestly surface what the agent doesn't know?*. Conflating them would force you to lose one to tune the other.

**Persistence:** The directive lives in `electron-store`, not in the workflow file. It applies globally to every workflow this Cerevisor install runs.

## The per-agent uncertainty badge

When an agent run completes, the harness composes an **uncertainty snapshot** and emits it on the orchestrator's event stream. The renderer mirrors the most recent snapshot per agent on the canvas as the **Agent Situation Badge**.

Each snapshot carries:

| Field | What it tells you |
|---|---|
| `value` | Self-reported confidence in `[0, 1]` if the agent emitted a marker. `null` if it didn't. |
| `justification` | One-line reason the model wrote for its confidence value. |
| `verifierState` | `passed`, `rejected`, `skipped`, or `absent` (the semantic verifier's verdict, if it ran). |
| `verifierConfidence` | The verifier's own confidence in its verdict. |
| `verifierReason` | Verifier reasoning or skip-reason, shown in the badge's tooltip. |
| `signals` | Human-readable badges: "no confidence marker", "verifier rejected", "high confidence", etc. |

Badges that warrant your attention: any **verifier rejected** outcome, any agent that finished with **no confidence marker** at all (the model didn't even self-assess), and any cluster of **low-confidence** snapshots on a single role.

The badge resets at the start of each new run so a previous run's snapshots don't bleed into the new one.

## The Wave Situation Report

After every wave completes (`wave_completed`), the harness assembles a **Wave Situation Report** and renders it as markdown in the run drawer between waves.

The report carries:

- The wave index and completion timestamp.
- A per-agent summary: agent id, name, status (`completed` / `failed` / `skipped`), uncertainty snapshot.
- **Files produced this wave**, grouped by agent.
- **Files the wave expected to produce but didn't** (`missingFiles`), so you can see contract gaps before downstream waves consume bad inputs.
- **Notes**: free-form markdown summarizing what changed, what's still unknown, and what the next wave should pay attention to.

The report's summary block surfaces five numbers prominently:

| Counter | Meaning |
|---|---|
| `completed` | Agents in this wave that finished successfully. |
| `failed` | Agents that errored. |
| `skipped` | Agents skipped by a conditional or gate. |
| `overconfidentMisses` | Agents that reported high confidence but failed the verifier. |
| `missingConfidenceMarkers` | Agents that produced output without self-assessing. |

The report is also injected into the next wave's downstream agents as a `contextNotes` segment, so the harness's own SA carries across waves, not just yours.

The renderer caps the report mirror at **32 entries** per session to keep memory bounded across long runs (FIFO eviction by `waveIndex`).

## Fixation warnings

During [Loop & Enhance](../advanced/loop-and-enhance.md) cycles, the harness fingerprints each round's plan. If the same fingerprint matches a prior round, the orchestrator emits a `loop_fixation_warning` event. The SA panel shows recent warnings (capped at 16, newest first) with:

- The round that fixated.
- The matching prior round.
- The fingerprint that repeated.

A fixation warning flips the SA state label to `fixation-risk`. The chat builder uses this as a signal to suggest changing approach rather than running another round.

## What gets reset between runs

When a new workflow run starts, SA's renderer state resets:

- Per-agent uncertainty snapshots: cleared.
- Wave situation reports: cleared.
- Fixation warnings: cleared.

The persistent SA Directive (the framing text and toggle) is unaffected; only the live per-run state resets.

## Reading the snapshot programmatically

Every snapshot type is JSON-serializable and crosses the IPC boundary without special handling. Skills and MCP tools that want to read SA state should consume the composed `SituationSnapshot` rather than rebuilding the picture themselves; the snapshot already reflects belief attribution, freshness, and cross-slice consistency.

## Where to go next

- [Overview](./overview.md): the three slices, state labels, belief attribution.
- [Harness memory and meta-cognition](../memory-and-learning/harness-memory-and-meta-cognition.md): the upstream source of patterns and observations SA reads from.
- [Loop & Enhance](../advanced/loop-and-enhance.md): the source of fixation warnings.