Required updates for Watcher
Sessions keep the owner assigned when they are created. Uploading a known conversation ID or linking a subagent cannot grant access to earlier transcripts.
When Watcher grades a tool call but the call's decision never reaches it, the grade stays stored as an unlinked grade, together with the messages sent to the grader. These grades now follow the organization's session-content retention period instead of being deleted after eight days.
What's new?
- Personal uploads and ingest-only organization keys record separate sessions, even when their native conversation IDs match.
- Trusted gateway captures and client uploads still share a session when they record for the same developer with matching IDs.
- Creating, retrying or updating a parent–child link requires write access to both sessions in the organization. Owners may differ; links never change ownership or grant transcript access.
- Existing permission names, roles and credentials remain supported. Existing sessions and relationships retain their stored owners.
- Old unattributed sessions remain separate; uploading them again does not transfer ownership or merge their history.
When an Aperture gateway and an unattributed Watcher client record the same native conversation ID, the client's permissions and arrival order matter. Here, the gateway attributes the capture to the developer:
| Client authentication | Gateway records first | Client records first |
|---|---|---|
API key with only sessions:ingest | Two sessions: one ownerless, one owned by the developer. | Two sessions: one ownerless, one owned by the developer. |
API key with sessions:write:any, without user attribution | One session owned by the developer; the client joins it. | Two sessions: one ownerless, one owned by the developer. |
A developer with access only to their own sessions sees the attributed copy.
The Analyzer counts each copy as a separate session,
subject to the viewer's access and filters. A client with sessions:write:any
can link its ownerless subagent to a root owned by the developer. Both sessions
keep their owners and separate access checks.
- With a retention period set, an unlinked grade is deleted once it is older than that period, measured from when the grade was created.
- Without a retention period, which is the default, unlinked grades are kept indefinitely, like session content. Grades that do not record their session cannot be removed by scrubbing a session, so they stay until a retention period is set.
- Each unlinked grade holds the messages sent to the grader, typically tens of kilobytes after compression. Without a retention period, a busy organization's unlinked grades can add several gigabytes of database storage a week, with no limit. To bound it, set a retention period. Self-hosted operators should also watch database storage, since the reference deployment does not grow storage automatically.
Required upgrade steps
Fixed session ownership
These steps apply to affected integrations on both self-hosted deployments and Watcher Cloud. Other integrations need no configuration change.
- If an integration relies on an ingest-only key joining a developer's
personal session, choose whether to keep separate recordings. To combine
them, the integration must authenticate that developer and record for the
same identity. A trusted gateway may use the existing
sessions:write:anygrant and the hook'suserfield. See gateway authentication and session write scope. Do not treat a caller-supplied conversation ID as proof of identity. - If an integration uses
sessions:ingestto link a user-owned session, it must use a credential with write access to both sessions. An ingest-only key may link only unowned sessions. Existingsessions:write:anycredentials need no change to link sessions with different owners. Links never assign the parent's owner to the child or grant access to the child's transcript.
Self-hosted operators use the normal update procedure. Complete the rollout of API and worker instances before relying on these rules; an older instance can still apply the previous ownership behavior.
During a mixed-version rollout, an older instance can change a session's owner.
If the uploader may no longer write to that session, the upload returns 503
with Retry-After.
Retry with bounded backoff and do not advance the upload cursor from that failed
response. Earlier inputs in the batch stay stored; later inputs are not processed.
If watcher doctor lists conversations whose uploads stopped after an ownership
refusal, the server upgrade does not clear those local blocks. Complete
watcher login with your intended identity to retry them. For proxy
authentication, check the identity in your gateway headers or WATCHER_HEADER_*
settings, then run watcher hooks install. See
client troubleshooting.