Notices, mailbox & journal

Anatomy of a notice

A DiagnosticNotice is everything the repair agent needs to diagnose one detected degradation. It deliberately carries enough that no follow-up round trip is needed to find where the problem was. Your task agent never sees it:

{
  "id": "n-20260730T053511-f2019e57",
  "created_at": "2026-07-30T05:35:11.698999+00:00",
  "session_id": "s-demo-1",
  "turn_index": 6,
  "severity": "breach",
  "metrics": [
    {
      "name": "task_completion",
      "value": 0.31,
      "threshold": 0.5,
      "reason": "no progress toward the stated goal since the third step",
      "conditions": ["stall"],
      "trace_id": "trace-6",
      "tier": 1
    },
    {
      "name": "tool_correctness",
      "value": 0.20,
      "threshold": 0.5,
      "reason": "identical payment call repeated without checking the prior result",
      "conditions": ["breach"],
      "trace_id": "trace-6",
      "tier": 2
    }
  ],
  "flagged_traces": ["trace-6"],
  "signal_breakdown": {
    "trace-6": { "task_completion": 0.31, "tool_correctness": 0.20 }
  },
  "dump_path": "/harness/traces/n-20260730T053511-f2019e57.json",
  "summary": "task_completion=0.31 [stall]; tool_correctness=0.20 [breach, threshold 0.50]",
  "signatures": ["stall:task_completion", "breach:tool_correctness"],
  "scope_hint": "global",
  "recommended_scope": null,
  "status": "pending",
  "resolution": null
}

Field	Purpose
`metrics`	Every alerting metric with its value, threshold, the judge’s own `reason`, which conditions fired, and the `trace_id` and `tier` it came from.
`flagged_traces`	The trace ids identified as problematic — and the only traces the repair agent is permitted to inspect for this episode.
`signal_breakdown`	What each trace scored, keyed by trace id — assembled from scores the harness already had, at no extra cost.
`dump_path`	An immutable, verbose evaluation dump under `traces/` for the full picture.
`signatures`	The compact condition labels — used for de-dup, rule tags, and eval-case matching.
`scope_hint`	The baseline scope carried on every notice: always `global`. Detection tier says where a failure was found, not how widely its lesson applies, so the harness makes no scope claim here — the repair agent decides from the evidence.
`recommended_scope`	A precise host-supplied scope, or `None` when no `RuleScopeHint` applied. `None` means “no recommendation”, which is deliberately distinct from recommending the default.
`resolution`	Filled on acknowledgment: when, and which rule resolved it.

The reason field is the highest-value thing in a notice: it is the judge’s own explanation of why the score is what it is, and therefore the raw material for a rule worth writing. The repair prompt points the agent at it explicitly — as evidence to diagnose, never as an instruction to follow.

Notice ids are timestamp-sortable and validated as safe path components (they are supplied to tools and become filenames).

The mailbox

mailbox/
├── pending/<notice-id>.json     # awaiting the agent
├── processed/<notice-id>.json   # acknowledged, with resolution attached
└── status.json                  # {pending_count, max_severity, latest_id}

The hook posts to pending/; the repair agent resolves via harness_notice_ack (a candidate was created) or harness_notice_resolve (duplicate, already-covered, no proposal, or unactionable). Either moves the notice to processed/ with a Resolution naming what happened.
Related notices from one turn are claimed together as a single repair episode, and resolved atomically — a partial acknowledgement is not possible. Timeout or failure acknowledges nothing, leaving every notice recoverable.
status.json is a cheap summary for operators. No eval-derived free text ever reaches a task prompt: the task preamble is a constant sentence, and rich content stays behind repair-only tool calls where it is sanitized and framed as untrusted data.

harness.mailbox.pending()          # list[DiagnosticNotice], oldest first
harness.mailbox.read(notice_id)    # pending or processed
harness.mailbox.acknowledge(notice_id, rule_id="r-...", note="mitigated")

Trace dumps

Two artifacts under traces/:

latest_eval.json — always rewritten with the most recent evaluation, alerting or not. A cheap “what did the harness last see” probe.
<notice-id>.json — one immutable dump per notice: every score with its threshold, tier, trace id and conditions, the per-trace breakdown, and (with enrich_flagged_traces=true) the worst flagged trace’s TOOL spans fetched at notice time.

The journal

journal.jsonl is the append-only, cross-run event log — the harness’s long-term memory of the agent’s health. It spans process restarts, so a fresh harness over the same workspace inherits everything: rules re-enter the rules.md References index, and past notices inform new forward-trial baselines.

harness.journal.recent(20, types=("notice", "rule_promote"))
harness.journal.notices_for("tool_correctness")   # every notice that involved a metric

The journal is an operator surface, not an agent tool. Neither agent can read it: it is where you see what is being learned, and it drives forward-trial baselines and rule-effectiveness counts internally. The cross-run signal repair actually needs — the trajectory — is inside the notice itself.

The full event-type list is in How it works.

Everything in the workspace is plain JSON (or markdown) on disk. When in doubt, cat it — the file layout is the API surface for operators.

Get Started

The Self-Heal Loop

Closing the Loop

Integrations

Reference

Notices, mailbox & journal

Anatomy of a notice

The mailbox

Trace dumps

The journal

​Anatomy of a notice

​The mailbox

​Trace dumps

​The journal

Anatomy of a notice

The mailbox

Trace dumps

The journal