Add scoped human-unlocked vault agent autofill

docs/agent-vault-controls.md

@@ -0,0 +1,56 @@
+# Controlled agent password autofill
+
+Administrators separately approve `vault:status`, `vault:list` and `vault:fill`
+in signed baseline policy and the individual grant. All start unchecked. Password
+manager enablement, feature visibility/locks, autofill policy, user-profile rules,
+actor destination scope, expiry and targeted revocation remain enforced.
+
+| Action | Arguments | Output |
+| --- | --- | --- |
+| `vault:status` | Optional native `sessionId` | exists, locked, enabled and allowAutofill booleans |
+| `vault:list` | Optional native `sessionId` | Up to 32 opaque credential references and approved HTTPS origins |
+| `vault:fill` | Native `sessionId`, returned `credentialRef` | completed boolean |
+
+The user creates or unlocks the vault through the trusted browser interface.
+Agents cannot unlock, create, export, save, delete or retrieve plaintext passwords.
+Inventory excludes usernames, labels, underlying record IDs and passwords. Origin
+metadata passes the same local/enterprise inspection pipeline before export.
+References expire after 60 seconds, are consumed once and are bound to actor,
+policy, exact native tab/WebContents, context and private vault generation.
+The reference pool is bounded at 32; this is not a complete paginated vault manager.
+
+For filling, keep the target login tab visible and request a fresh inventory after
+unlock. Use its reference only at the saved exact HTTPS origin. A single visible
+same-origin, same-window POST login form is required. Visual protection, foreground
+identity, policy, cancellation and lock state are checked again after waits.
+Passwords pass only into the fixed isolated-world fill script. No arbitrary
+selector, password value or script is accepted from the agent. Filling does not
+submit the form, and a failed response never implies undo or authorizes a retry.
+
+Tab changes and policy updates already lock the vault. Unlock again through the
+trusted UI and refresh references after either event. Lock/reopen and mutation
+attempts advance a private process-local generation; even a same-ID password
+replacement invalidates older references. Status/inventory polling does not renew
+the idle unlock deadline. This generation never appears in public responses.
+
+Durable audit records pre-execution and completed/failed agent actions with verified
+principal attribution, plus vault fill-requested/filled lifecycle events. Ordinary
+audit, SIEM and diagnostic spans contain no credential values, references or native
+record IDs. Debug spans separately name inventory inspection, visual authorization
+and native fill under the protected RPC action.
+
+Actual Windows/Electron proof uses a controlled HTTPS receiver with trust pinned
+to its exact synthetic certificate in the isolated test session. It verifies human
+unlock, real field filling, zero submitted requests, host filtering, actor/ref
+boundaries, replay, relock/reopen, password replacement, central autofill disable,
+targeted revocation and named exported OTLP phases. It does not prove production
+certificate deployment or successful login submission. The separate tab-binding
+unit test holds the vault unlocked to verify binding independently of automatic
+tab-change locking (`artifacts/vault-agent-controls-native-proof.json`).
+
+Outbound DLP still scans a later form submission. A credential matching a secret
+rule can therefore block an otherwise legitimate login; there is no generic
+password-field exception. A future governed allowance must bind one exact
+submission and inspect every remaining field. Persistent sessions, file/vault
+mutations, safe screenshots, broader administration and production key custody
+remain separate open requirements.