Configure and run Situational Awareness

Edit the SA Directive, read the per-agent uncertainty badge, interpret the wave situation report, and handle fixation warnings.

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 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

Back to docs