safetynet/docs/agent-session-controls.md

Managed saved sessions for local agents

Administrators separately opt into sessions:save, sessions:list and sessions:restore in the signed baseline and individual grant. All three controls start unchecked. These are separate from sessions, which inventories currently open native tabs. Existing pairing, expiry, generation, destination, feature and user-profile restrictions still apply. Saving browser tabs never preserves or reactivates agent authority.

Action	Purpose
sessions:save	Save selected native tab IDs as a named collection, optionally replacing an owned collection with its current revision.
sessions:list	Inspect the current actor's approved saved collections and storage revision.
sessions:restore with collection ID	Prepare a short-lived restoration plan without opening tabs.
sessions:restore with returned plan ID	Consume the plan once and restore its approved destinations.

The local collection store accepts at most 16 collections and 32 tabs per collection. Its revision prevents stale replacement. Collection ownership binds to the enrolled device and verified actor; ownership includes the actor's credential generation. Rotation makes old-generation collections inaccessible; no implicit migration restores them. Collections belong to the local device, not a central cross-device sync service. Windows DPAPI encrypts the stored bytes before atomic replacement. Plaintext buffers are cleared. Corrupt files, hard links and unexpected file types fail closed.

Only collection name, approved HTTP(S) URLs, titles, optional group metadata and active-tab index belong in a saved collection. No cookies, authentication tokens, passwords, form values, navigation history or serialized Chromium page state are accepted. Benign query strings and fragments are preserved. URL userinfo, recognized authentication paths, authentication query/fragment parameters and credential-shaped metadata are rejected rather than silently rewritten. Names, titles and URLs also pass current local/enterprise DLP before saving or exporting. Unavailable or incomplete inspection blocks the operation.

Restoration plans expire after 60 seconds, are bounded, and are consumed before use. Policy changes, actor/generation changes, cancellation, changed storage revision and changed collections invalidate plans. Preparing and applying both check current destinations and classify saved metadata. The native implementation preserves existing tabs, applies current navigation enforcement to new tabs, and closes only the tabs created by a failed restoration. Closing failed restoration tabs cannot undo network requests already sent. Restoring URLs does not restore login sessions; a website may require normal authentication again.

Do not retry a mutating action merely because its response or diagnostic export failed. Check current tabs and collections first. Security audit and OpenTelemetry are separate from saved collection contents; diagnostics should contain fixed operation names and timings, never saved URLs, titles or collection names.

Verification status

The adapter and encrypted-store tests cover classification failures, one-use plans, policy/generation/revision changes, ciphertext alteration, ownership and structural bounds. Central admin controls are implemented and tested as explicit opt-in. The actual Windows/Electron admin fixture verified all three scopes in baseline and individual grants, separate-author review, self-approval denial, auditor read-only controls, rotation and policy-history restoration. Its 154 completed API requests exported parent-correlated traces; three GET requests canceled during identity reload are recorded separately and no policy mutation failed (artifacts/agent-grants-history-admin-proof.json).

The actual browser fixture runs two Windows/Electron processes against the same enrolled device and local profile. It saves two tabs with benign query strings, fragments and group metadata, then verifies encrypted storage survives restart. Private decryption inside the isolated fixture checks exact metadata keys without printing plaintext. Edited password/form values and renderer history state are absent; restored pages receive their fresh server defaults. Existing tabs remain and restored groups are verified. Cross-actor plan use, replay and stale revision are denied. After signed central disable, host restriction and targeted revocation reach the browser, a refused commit sends no additional navigation request. Legitimate policy-triggered page reloads are outside that post-policy measurement.

A controlled delayed HTTPS receiver also proves an actual away-and-back activation race: the first restored tab begins navigation, the trusted UI activates an original tab and then the new tab, and restoration fails. Only newly created tabs are removed, existing tabs survive, and the second saved destination is never requested. The first already-started request cannot be undone. Actual trace 583a1d4dbc80fb2cbcb135b1622a4993 records native work (1410.0137 ms), rollback (0.7242 ms) and the failed restoration (1412.796 ms).

Actual exported save/list/restore traces contain correlated named inspection, storage, preflight and native stages, plus all five audit serialization/encryption/ write/fsync/commit stages beneath their audit parent. Proof is in artifacts/session-agent-controls-native-proof.json. These proofs do not establish production key custody, cross-device session sync or a complete browser backup.