Watchdog Contract#
Safety watchdogs places watchdogs among the write gates and says what they do not cover, and Safety watchdogs sets one up. This page is the exact behaviour: the hold record and where it lives, the routes and frames of the web terminal, and the fields of a verdict’s audit entry.
The hold record#
One file per session, var/state/session_holds/<session_key>/record.json in the deployment
repository. osprey_connectors.session_hold owns its format, its reader and its writer. A
session key is one path segment: it starts with a letter or digit, continues with letters,
digits, ., _ and -, and runs to 128 characters.
{
"schema": 1,
"session_key": "<key>",
"flags": [
{
"flag_id": "<id>",
"source": "guard-circumvention",
"reason": "Asked the agent to edit hooks, settings or configuration to loosen a gate.",
"prompt_ref": "<record_session_id>:<submission_id>",
"prompt_excerpt": "<at most 200 characters>",
"opened_at": "2026-10-31T00:00:00Z",
"state": "open",
"stop_unconfirmed": false,
"started": []
}
]
}
A session is held while any flag’s state is open. A flag closes only by an answer that
names it, and stays in the record, closed, with answer, operator and answered_at.
The web terminal gives every session it launches the store through
OSPREY_SESSION_HOLD_DIR, and only when the build has an enabled watchdog. A process without
that variable or a session key is never held. Under a store, the hold fails closed: a
missing or unreadable record, a record of another schema or another session, a symbolic link at
the directory or the record, and an unsafe key all hold. Such a record is reported as the one
flag hold-record-unreadable, with source session_hold, and answering it writes a fresh
record. GET /api/watchdog/flags reports no flags only for a key with no running session and
nothing on disk: a session that has not started.
Writes hold an exclusive lock on record.json.lock and land atomically, so a reader sees the
old record or the new one and two writers never lose each other’s flag.
Where the hold refuses#
A held session’s write is refused with the reason session_held, naming the watchdogs that
raised the hold where the record can be read:
Writes are paused: this session has an unanswered hold the operator must answer. Raised by: guard-circumvention.
[osprey-refusal: session_held]
Site |
What it refuses |
|---|---|
|
Every write tool it judges, Bluesky lane tools included. |
The MCP servers’ write-tool clamp |
Every tool the render classifies as a write, except read/write tools such as
|
|
Each asks again as it executes, so a write approved while the flag was open is refused.
|
The connector |
Every put, as a term of the write verdict (the verdict’s order). |
The terminal’s panel proxy |
A call that would fire a dispatch job. |
A CANOPY panel’s data process |
Every click on a screen, while any live session of its terminal is held. |
Stopping a plan or a run, and control_target_set, are never held.
The routes#
Route |
Tier |
Purpose |
|---|---|---|
|
panel token |
The trigger hook hands over one prompt. |
|
operator |
The session’s open flags. |
|
operator |
The operator’s answer. |
The last two are outside the panel tier, so an agent holding the panel token can neither read its flags nor release its own hold.
POST /api/watchdog/prompt#
The body holds session_key, record_session_id and submission_id, each a UUID, and
prompt, up to 1,000,000 characters. The answer comes before anything is judged: 202 with
{"accepted": true, "duplicate": false}, with duplicate: true for a prompt already seen,
which is not judged again.
Status |
|
When |
|---|---|---|
400 |
|
An id is not a UUID. |
404 |
|
No watchdog runs in this build. |
404 |
|
The key names no session this process runs. |
On any failure the hook falls back to judging the prompt in a process of its own, with the session key where it has one, so a refused or unreachable intake cannot leave a web session unheld. A session with no key is judged and recorded, and never held.
GET /api/watchdog/flags#
?session_key=<key> answers {"enabled": true, "flags": [...]}. Each flag carries
flag_id, source, reason, prompt_ref, prompt_excerpt, opened_at,
stop_unconfirmed and started, plus watchdog, which repeats source. In a build
with no watchdog it answers {"enabled": false, "flags": []}. A key that is not a safe path
segment is 400 invalid_session_id.
GET /api/terminal/posture?session_id=<key> reports the same state as one field, held.
POST /api/watchdog/flags/answer#
The body is {"session_key": "<key>", "flag_ids": ["<id>"], "answer": "stop" | "continue"},
with up to 256 ids. It answers {"released": [...], "stop_unconfirmed": [...]}. Only the
named flags are touched, so a flag that joined after the dialog was drawn stays open and the
session stays held. A flag already closed is ignored. A record that cannot be written is 503
hold_record_unavailable, and an unsafe key is 400 invalid_session_id.
continue closes the named flags.
stop ends what is running in that session first, in the terminal by an interrupt and in
the chat by cancelling the turn, which also denies pending approvals and stops background
agents. It never terminates the session. Then it reads what the agent started. A flag closes
only if the turn has ended and nothing the agent started is still running, and this holds when
no turn was running too. Otherwise the flag stays open with stop_unconfirmed: true and
started naming the commands, and a process table that could not be read counts as a command
still running. A hookless terminal cannot confirm its turn ended, so it stays unconfirmed.
Answering again repeats the check; Continue releases it, audited as such.
Frames#
Frames are change notices on the terminal’s event stream (/api/files/events) and the chat
feed. They carry ids and never prompt text, and the hold record stays the only truth: a client
re-reads GET /api/watchdog/flags on any frame, and a low-rate poll recovers one it missed.
|
Fields |
Sent when |
|---|---|---|
|
|
A flag opened, or a Stop marked it unconfirmed. |
|
|
An answer released flags. |
|
|
|
The audit entries#
Every entry is on the safety_watchdog surface of the
audit trail, with the watchdog as subject, and joined on the
record session the prompt belongs to, whichever process wrote it. session is the session
key, or the record session where there is none. detail holds key=value identifiers
separated by spaces, and never the prompt, the judge’s prose or an agent’s message.
|
|
|
|---|---|---|
|
the option id where the judge has one; otherwise the decision |
the verdict fields below |
|
the |
the verdict fields below |
|
|
the answer fields below |
|
|
the answer fields below; |
|
|
the answer fields below, with |
Verdict fields: prompt_ref, engine, status (ok or unavailable),
score and threshold where the engine has them, uncalibrated, error_type when
unavailable, latency_s, entries_kept, entries_cut, tokens_estimate,
drain_timed_out, record_available, input_sha256 (the hash of the session view the
judge read), cost_usd where known, and refused_tools where an agent judge was refused
any.
Answer fields: prompt_ref, flag_id, operator, and where they apply denied
(pending approvals), stopped (background agents), after_stop_unconfirmed and started
(commands still running). on_behalf_of carries the operator too, and an answering surface
that can name nobody records operator=<unattributed>.
``error_type`` is one of timeout, budget, in_flight_bound, intake_lost,
no_probabilities, decision_error, missing_key, parse_error, run_error or
intake_failed.
No decision word or field says “safe”; a value that happens to contain the word is masked.
What each engine reads#
Decision. The instructions and the session’s prompts, answers, tool calls and tool results,
newest kept first, bounded by the route’s max_state_plus_question_tokens (30,000 by default)
and cut to fit rather than refused. Facility option ids never reach the model. The score is the
summed probability of the flag options; the reason is the text of the likeliest flag option.
The route, model and interactive budget (three seconds in all) are under api.jev, and the
model id is pinned.
Agent. The session view, the watchdog’s references/, and the read tools of the
controls and osprey_facility_knowledge servers plus its tools. Its
servers run in read-only mode, its environment ties it to no session, and a refused call is
reported in refused_tools. An application’s read tools reach its backend with a read
credential minted for the run: it opens only the GET and HEAD agent routes of the
applications whose tool servers the run is given, and is revoked when the run ends. A run that reaches timeout_s or max_cost_usd, or that finds no room
under the in-flight bound, is unavailable.