Audit Trail Contract#
Every safety-relevant decision a deployment makes is one audit entry in
the agent record. The process that decided appends it to its own identity’s
spool, var/spool/<identity>/. The agent-record service takes it in
from there. The entry’s surface field names the surface that decided. The
trail has two halves: the record, which keeps every entry for
agent_record.retention_days, and the archive, which keeps each closed day
for good, exported as var/archive/<day>/agent_record/entries.parquet
(The Agent Record). This page is the shape of
that trail — which surface files a decision, what each field holds, who can
read it, and what the trail does not promise. For the policy that produces
most of the refusals, see the protected set. For
the per-target write posture that refuses control-system writes see
The control-target chip.
Both halves are durable by construction: osprey build re-renders
build/ wholesale and never touches var/. A plain osprey reset keeps
the audit files written before the agent record (var/audit), the agent
record and var/archive. osprey reset --purge-audit removes:
var/auditthe agent record on either backend, with the ClickHouse backend’s data volume
the spool feeding it
the record’s exports in the archive (
var/archive/<day>/agent_record/)
It also appends an agent_record_purged line to each of those days’
manifests. It keeps the rest of var/archive: the artifact and Bluesky
copies and the manifests themselves.
Entries, by surface#
The identity is whoever was acting. So on a multi-user deployment, each
person’s entries are written from their own spool, and the record files them
under that person (how it is resolved).
The surface is the layer that decided, so a gallery refusal and a config
refusal never share one.
|
What it records |
|---|---|
|
The settings drawer’s Config tab — |
|
The |
|
The Claude-setup file API ( |
|
The artifact galleries in the settings drawer (Behavior, Safety, Memory, Config), refusing reserved paths across all six of their write and delete operations |
|
The startup restore that puts durably-saved artifact bodies back, refusing store records that name a reserved path |
|
Python runs a safety layer refused — see What executed code may not change |
|
Tool calls on an OSPREY MCP server, allowed and refused alike, on a
surface named for the server: |
|
What the safety hooks denied, and what they put in front of a person |
|
What the code review decided on a notebook edit — see Code review |
|
Requests that changed something through a web API, and the 401s and 403s the login check itself refused |
|
Control-target and write-posture gestures made from the bar on the JupyterLab page, which names no session — the control context belongs to the deployment, so the line joins on the deployment and the moment rather than on an actor |
|
Control-system writes a notebook cell was refused — a write posture, a limit, a target that moved while the cell ran |
|
Each command batch a guarded run fired under its lock, and each it was
refused, with the commands in |
|
Each CANOPY panel write and each panel write refused, under the person
who clicked — see A panel write. Its
|
|
Each batch of live values the channel finder’s value reader fetched,
one allowed entry per batch: |
|
Whether a queued plan’s declared channels answered before it moved, per
run: |
|
Logins and login refusals, where a deployment has a login wall |
|
Each watchdog’s verdict on a prompt, its failures, and the operator’s answer to a flag — see Watchdog Contract |
decision reads allowed or refused on almost all of them.
hook_approval has three words of its own, all on the same
tool_use_id. ask comes first, then either approved or denied:
ask: the hook put the call in front of an approver.approved: the harness reported that the call ran.denied: the turn ended without it — declined or interrupted.
A write the switch’s allowed position let run has no ask: its
approved names approver=write_switch in detail.
safety_watchdog has its own too: flagged, clear, unavailable,
stop, continue and stop_unconfirmed.
Some of that is chatter rather than safety: every request that changes state is
recorded, so moving a panel around the terminal leaves http_mutation
entries next to the config edits. One asymmetry is worth knowing
before you go looking. A refused WebSocket upgrade is recorded; an admitted
one is not. A live session’s activity is its tool records, not its
connection.
The record#
One shape covers every surface, so one reader handles a refused config key
and a refused control-system write alike. It is the audit entry’s body, one
JSON object:
Field |
What it holds |
|---|---|
|
UTC timestamp to the millisecond, |
|
Which layer decided |
|
Who was acting, from the terminal login where there is one |
|
The write posture in force at the time, |
|
Which surface stamped the record — |
|
The session the record is filed under — a terminal or chat session,
|
|
The person a service decided for, where the identity the record is filed under is not that person: the user a login was for, the owner of a queued plan. Absent when there is no such person |
|
The agent harness’s id for the tool call the record is about. Present
on records a tool call produced — the hooks, the MCP servers, the
Python executor — and absent elsewhere. It is the key that joins a
record to its |
|
What the decision was about: a dotted config key, a tool name, or the project-relative path when a whole file is the target |
|
|
|
Short machine-readable reason — |
|
Surface-specific context: for a protected-set refusal, the file the
write was aimed at ( |
|
The role the actor held, where the decision was bound to one: on
|
|
On |
A PUT that would have changed many protected keys at once names the first
ten and counts the rest in the message, but every changed key gets its own
entry. The cap trims the message, never the audit. A refused request leaves
exactly those entries and no others. The surface that decided files the record.
The layers around it stand aside rather than filing the same refusal
again.
Note
Recording is best-effort; refusing is not. An unwritable spool or a record that is down degrades the trail. It never turns a refusal into a server error. An error that reads like the gate malfunctioned is the one shape an operator could mistake for a gate that failed open.
The login behind the record#
Where a deployment has a login wall, the two web surfaces —
http_mutation and web_auth — record who the request came
from in detail, as up to three keys. Which of them are present is itself
part of the message:
Key |
What it holds |
|---|---|
|
The roster account the request is on — the card named in the URL, and the name the login service checked the session against. Present on every record where the request carried a login at all |
|
The account this container serves, written only when the forwarded account is not it. Its presence is the whole signal: one person’s authorization arrived at another person’s container. A request on the right card never writes the key. The same case logs a warning, and it is recorded rather than refused |
|
Who proved the login. Under |
Two forwarded headers carry that from the login service through nginx:
X-Osprey-Auth-Account names the card, X-Osprey-Auth-Subject names the
login that proved it. Under auth.method: password they hold the same value
on a person’s own card, because the roster username is the proof. On a shared
card, the subject header names the opener instead. Under oidc, the two
part on every card. Where a card’s access: rule admitted the session, that
header carries the asserted identity rather than a roster name. Either way only
the account is a name a container can compare itself against.
A deployment that pins an older login-service image with auth.image gets no
account header. The container then falls back to comparing the subject, as it
did before this release. Usually the mapped subject is not the roster name
but an opaque sub or an email. Wherever it is not the roster name, it never
matches, so expected_account= and a warning ride every audited request.
Building against this release’s image is what clears it.
Who the control system saw#
A Channel Access or PV Access server, and a gateway’s put-log, record the
account name of the process that made each write. That name is the card’s
control_identity on a personal card behind a login wall
(Name the account a card writes as), a fixed osprey-* service name on a
shared writer, and osprey everywhere else. The audit trail records the
same name beside the person, so a put-log line can be joined back to who asked
for the write.
The names are read in the process that writes, never from an environment
variable. They travel as keys in detail on a plain record, and as noted
facts on a tool-call record.
ca_user, ca_host and owner are in both:
Key |
What it holds |
|---|---|
|
The account name the control system sees the write arrive under |
|
The host name of the writing container |
|
The person a shared writer acted for: the owner of a dispatched run, or of a queued Bluesky plan. Written only when there is a person to name |
|
The channel a notebook kernel wrote or was refused |
|
The channels a Python executor run attempted to write, in the order first attempted. A fact on the tool-call record only, because it can be long |
Each write route leaves a different record, and joins the put-log by a different key:
Route |
Name on the wire |
Audit record naming the person |
Join key to the put-log |
|---|---|---|---|
|
The card’s identity |
The call’s own record, with |
Account, channel, time |
Notebook kernel write |
The card’s identity |
One |
Account, channel, time |
Refused notebook kernel write |
None; nothing reached the wire |
The kernel’s refusal record, with |
None |
Refused client-library import |
None; nothing reached the wire |
The kernel’s refusal record, reason |
None |
Python executor write |
The card’s identity |
The |
Account, time window, channel when listed |
Dispatched run |
|
The worker’s tool-call records, with |
Worker name, channel, time |
Bluesky plan on a lane OSPREY renders |
|
The lane’s |
Lane name, time window, channel in the plan |
Bluesky plan on an external-worker lane |
The facility worker’s account |
None in OSPREY; the facility’s RE Manager writes under its own account |
None |
The name is attribution, not authentication: see Whose write is it.
Why a login was refused#
The auth_sidecar surface records every login and every login refusal, and
reason is the category it was refused under. Four of those categories
belong to a card whose access: key names a
principal set:
|
What was refused |
|---|---|
|
The token’s |
|
The token carries |
|
Every principal on the card was consulted and none of them admits the asserted identity. The set only ever grants, so an identity nothing on the card covers is refused |
|
The identity the provider asserted cannot be carried in an identity header, so no session naming it could be minted |
The first two are login-time gates, and they do not re-evaluate. Neither claim is written into the session, so no later request can be measured against it. A token is refused for either reason at the moment it arrives. A session already open is untouched by what those claims would say now. Principal coverage is the opposite. The card’s principal set is matched against the session’s identity on every request, so withdrawing a principal closes the card on the next one.
detail on these records names a claim at most. The asserted address, its
domain, and the value of the hosted-domain claim are never written to the
trail.
A password login refused because a guess missed files bad_credential, the
same for a wrong password, an unprovisioned user and an unknown name. A login
whose user’s stored hash cannot be evaluated files credential_unevaluable
instead: the browser sees the ordinary refusal, and the fix is
osprey users passwd <user>.
A login at /auth/enter, which names no card
(Log in without choosing a card), files no_card when it proved who
arrived but no card admits them. The fix is the roster or a card’s
access:, never the password or the provider. A card-less single sign-on
refused before any card is known files under the subject (sign-in), never
under the asserted identity.
The tool-call record#
The default records hold identifiers and, except on the two surfaces in
What the trail is not, never values. Beside them, every
osprey MCP server files one audit entry on the tool_call surface for
each call that ran against something worth naming. Something worth naming is
a control target, an approval, or facts the tool noted while it ran. There is
no switch; it is always written.
It carries no arguments and no result: the agent’s transcript, which the record
holds too, has both once, joined by tool_use_id. Nor does it repeat the
decision and reason the default record for the same call holds. It does not use
the default record shape:
Field |
What it holds |
|---|---|
|
As in the record; |
|
The agent harness’s conversation id |
|
The harness’s id for this call — the key the default records carry too |
|
How long the call took, in milliseconds |
|
The MCP server’s tool prefix, and the |
|
|
|
The control target and its generation when the call started |
|
What the tool noted while it ran — for a control-system write, the limits verdict, each channel’s value before the write, and the attribution facts in Who the control system saw |
The Tiled catalog a plan lane writes is not part of the audit trail. It stays out of the agent record and the archive. It is beamline data, with its own retention and backup, not a record of what the agent was asked and did.
Which directory a record lands in#
The acting identity is resolved once, by one ladder. The same answer is
used twice: as the record’s actor field and as the spool directory the
entry is written to, var/spool/<identity>/. The record takes the identity
from that directory, never from the entry, so an entry cannot claim to be
someone else’s. Resolving those separately is how a trail starts naming one
actor while filing under another, so there is only ever one resolution. Most
specific first:
Rung |
When it answers |
|---|---|
|
A multi-user terminal container. The name is the roster entry’s, so a real person is behind the record. |
|
A container that hosts no single person: a framework service’s key, or
|
The local account |
The single-user laptop case, where the process account is the person.
|
|
An honest floor. A slim image often has no account entry for its uid; that is routine, and an unresolvable identity must never cost the record. |
The hostname is never a rung. It looks like an identity and is not one. A host-network container reports the shared host’s name, so every service on the box would collide into one identity. A bridge-network container reports a fresh container id on every restart.
A value carrying a path separator, or naming . or .., is not a usable
identity and falls to the next rung. The same string becomes a directory name,
and ../elsewhere would file one service’s records under another’s spool.
These variables are the framework’s, not yours to set. The build renders
them into each container from the roster and the service derivation. Setting
one by hand in a shell, a compose override or an MCP server’s env: block
does not relabel a record; it aims one process’s records at another’s spool.
That is why they are stripped from every MCP server spec the build renders,
together with the session’s control-target and write-posture markers. A server
spec that could set any of them could quietly repoint or shed the
evidence of what it did.
Who can read it#
The record decides. Every process reads the record under a login of its
own, and the record answers each login only what that login may see. A
terminal’s login reads what its own identity wrote, so alice’s terminal cannot
read bob’s entries, though both are in one record. Inside a container the admin
tier reads its own entries without a shell. GET /api/audit/recent returns
the newest audit entries this identity wrote, newest first, behind the same
switch as the Config panel (web.config_panel.enabled). It never reaches
another identity’s.
The deployment-wide view is a reader’s. A reader is a person the profile
names under agent_record.readers. A question spanning several people
is answered by a reader, on the history page or with a reader key
(Let others read it). Past the retention
window, it is answered from the archive on the deploy host, where whoever owns
var/archive/ reads every day’s export.
What the trail is not#
It is append-only, not tamper-evident. Entries are only ever added, and OSPREY never rewrites one; it removes them only by whole day, under the retention rule below. But there is no hash chain and no signature. Anyone who can write the record’s files or the archive can edit or delete entries — the host’s administrator included. Nothing in a later read would show that they had. It is an operational record of what the deployment decided, which is what answers “what happened here”. If you need something that holds against someone with write access, ship the archive’s day files off the host as they are written. Send them to a collector the deployment cannot reach back into.
The record keeps it for a window; the archive keeps it for good. The
record removes whole arrival days past agent_record.retention_days. It
removes only the days the archive already holds, so no entry leaves the record
before it has a lasting copy. Nothing in OSPREY deletes the archive’s exports
except osprey reset --purge-audit, which marks each day it purged in that day’s
manifest.
Two surfaces carry a payload: executor and canopy. Every other
default record holds identifiers and config keys only: a surface name, a
username, a tool name, a dotted key, a short reason. It never holds a config
value, a prompt, or an agent message. A record of a write that does not say
what the write was is an alert, not an audit trail, so there are two
exceptions:
The Python executor. A refused run records the code it refused, whole, in a
sourcefield (8000 characters, withsource_truncated: truewhere a longer script was cut).A CANOPY panel write. Every record of a panel write — the attempt, its outcome, a refusal — carries the value, as the last two
detailtokens,value_len=<n> value=<text>.value_lenis the length of the whole value. The text keeps at most 256 characters, fewer where the rest ofdetailleaves less room. It is written as a JSON string with no whitespace, so a value cannot forge a token. A panel write is one click with no tool call behind it, so no tool-call record holds the value.
This matters for anyone reading or forwarding the trail. executor
contains whatever the agent tried to run, including anything the conversation
put into the script. canopy contains every value a person sent to the
machine from a panel. Give both the same care as the code and the setpoints
themselves, and expect executor to be the surface that grows.