Add policy-bound encrypted agent session restoration and audit traces

docs/agent-session-controls.md

@@ -0,0 +1,82 @@
+# 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.