@agenticprimitives/contracts 0.1.0-alpha.2 → 1.0.0-alpha.10

package/src/AgentAccount.sol

@@ -22,6 +22,33 @@ import "./libraries/WebAuthnLib.sol";
 interface IAgentAccountFactoryView {
     function bundlerSigner() external view returns (address);
     function sessionIssuer() external view returns (address);
+    /// @dev R6.5 — the factory inherits `GovernanceManaged`; its
+    ///      `governance()` getter returns the AgenticGovernance pointer
+    ///      shared across every account it creates. AgentAccount reads
+    ///      this address to call `IGovernanceView.isPaused()` from
+    ///      `whenNotPaused`-guarded entrypoints.
+    function governance() external view returns (address);
+}
+
+/// @dev R6.5 — minimal interface for the pause read. Mirrors the same
+///      selector `GovernanceManaged._pausedSafe()` uses so an EOA or
+///      non-conforming governance contract is treated as "not paused"
+///      (legacy / test deploys still work). Production deploys ALWAYS
+///      use `AgenticGovernance` which implements this interface.
+interface IAgentAccountPauseView {
+    function isPaused() external view returns (bool);
+}
+
+/// @dev Spec 253 — minimal read surface of `ApprovedHashRegistry`. The
+///      account consults it ONLY from `isValidSignature` (the ERC-1271
+///      entrypoint), under the `0x03` sentinel, so a hash the account
+///      itself pre-approved (inside its own custody-gated execute/batch)
+///      validates as an ERC-1271 signature. Address is bound IMMUTABLE in
+///      the impl (see constructor) — never an owner-mutable view — so a
+///      factory/governance key compromise cannot re-point it at an
+///      attacker registry to forge signatures.
+interface IApprovedHashRegistryView {
+    function isApproved(address signer, bytes32 hash) external view returns (bool);
 }
 
 /**
@@ -60,6 +87,14 @@ contract AgentAccount is
     /// @dev The ERC-4337 EntryPoint contract
     IEntryPoint private immutable _entryPoint;
 
+    /// @dev Spec 253 — the `ApprovedHashRegistry` consulted by the `0x03`
+    ///      sentinel branch of `isValidSignature`. IMMUTABLE (baked into
+    ///      impl bytecode, shared by every proxy, changeable only via a
+    ///      custody-gated UUPS upgrade). May be `address(0)` on legacy/test
+    ///      deploys that don't use the sentinel — in which case the
+    ///      sentinel fails CLOSED (see `isValidSignature`).
+    address private immutable _approvedHashRegistry;
+
     /// @dev Authorized DelegationManager (ERC-7710 executor)
     address private _delegationManager;
 
@@ -108,9 +143,21 @@ contract AgentAccount is
     }
 
     /// @dev Spec 007 Phase A.5 — current pending upgrade (set by
-    ///      `upgradeToWithAuthorization` when `_upgradeTimelock > 0`).
+    ///      `scheduleUpgrade` when `_upgradeTimelock > 0`).
     PendingUpgrade private _pendingUpgrade;
 
+    /// @dev CA-1 — transient "the current call stack is an authorized upgrade
+    ///      context" flag. Set while (a) a module action executes
+    ///      (custody-governed, e.g. `CustodyPolicy.ApplySystemUpdate`, which
+    ///      carries its own T5 quorum + timelock) or (b) a matured owner-queued
+    ///      upgrade fires (`executePendingUpgrade`). `_authorizeUpgrade` reads it
+    ///      so that, once an account configures `_upgradeTimelock`, a DIRECT owner
+    ///      `upgradeToAndCall` is refused (must `scheduleUpgrade` then
+    ///      `executePendingUpgrade`), while the custody path keeps working with no
+    ///      double delay. Transient ⇒ tx-global (visible in the nested
+    ///      `_authorizeUpgrade` frame) AND absent from the storage layout.
+    bool private transient _upgradeAuthorizedCtx;
+
     /// @dev Spec 007 Phase A.5 — maximum permitted upgrade timelock to
     ///      protect against an owner accidentally setting an absurdly
     ///      large delay that bricks future migrations.
@@ -127,6 +174,9 @@ contract AgentAccount is
 
     error NotFromSelf();
     error NotCustodianOrSelf();
+    /// @notice R6.5 — thrown when a `whenNotPaused`-guarded entrypoint
+    ///         is called while `AgenticGovernance.isPaused() == true`.
+    error SystemPaused();
     error CustodianAlreadyExists(address owner);
     error CustodianDoesNotExist(address owner);
     error CannotRemoveLastCustodian();
@@ -160,6 +210,13 @@ contract AgentAccount is
     error UpgradeNotReady(uint64 readyAt, uint256 nowTs);
     error PendingUpgradeMismatch(address pending, address attempted);
     error UpgradePending();
+    /// @notice CA-1 — a direct `upgradeToAndCall` was attempted while a per-account
+    ///         upgrade timelock is set; route through `scheduleUpgrade` +
+    ///         `executePendingUpgrade` (or the custody module path) instead.
+    error DirectUpgradeBlocked();
+    /// @notice CA-1 — `scheduleUpgrade` called with no upgrade timelock configured
+    ///         (nothing to queue against — upgrade directly).
+    error UpgradeTimelockNotSet();
 
     // Wave 2A — on-chain authority closure (contract audit C-1..C-3).
     error ValidatorRequired();
@@ -200,10 +257,53 @@ contract AgentAccount is
         _;
     }
 
+    // ─── R6.5 / CON-AgentAccount-005 — system-wide pause modifier ──
+    //
+    //   When `AgenticGovernance.isPaused() == true`, every mutating
+    //   external entrypoint guarded by this modifier reverts with
+    //   `SystemPaused`. Recovery-shaped entrypoints
+    //   (`uninstallModule`, `cancelPendingUpgrade`, `removeCustodian`,
+    //   the three `onlySelf` ceremonies) are deliberately NOT guarded
+    //   — an operator must always be able to remove attack surface
+    //   even during an incident.
+    //
+    //   Reads `governance()` through the factory at each check so a
+    //   factory-level governance rotation propagates to every account
+    //   without per-account migration. Legacy / direct-deploy accounts
+    //   (no factory) and EOA-governance / non-conforming-governance
+    //   deploys are treated as "not paused" so existing test fixtures
+    //   keep working — mirrors `GovernanceManaged._pausedSafe()`.
+    modifier whenNotPaused() {
+        if (_systemPaused()) revert SystemPaused();
+        _;
+    }
+
+    /// @dev R6.5 — `staticcall` chain: factory → governance.isPaused().
+    ///      Returns `false` on any non-conforming hop (legacy
+    ///      compatibility). Production deploys MUST pass a real
+    ///      `AgenticGovernance` to the factory; the production-deploy
+    ///      preflight enforces that invariant.
+    function _systemPaused() internal view returns (bool) {
+        address f = _factory;
+        if (f == address(0)) return false;
+        (bool okF, bytes memory dataF) = f.staticcall(
+            abi.encodeWithSelector(IAgentAccountFactoryView.governance.selector)
+        );
+        if (!okF || dataF.length < 32) return false;
+        address g = abi.decode(dataF, (address));
+        if (g == address(0) || g.code.length == 0) return false;
+        (bool okG, bytes memory dataG) = g.staticcall(
+            abi.encodeWithSelector(IAgentAccountPauseView.isPaused.selector)
+        );
+        if (!okG || dataG.length < 32) return false;
+        return abi.decode(dataG, (bool));
+    }
+
     // ─── Constructor / Initializer ──────────────────────────────────
 
-    constructor(IEntryPoint entryPoint_) {
+    constructor(IEntryPoint entryPoint_, address approvedHashRegistry_) {
         _entryPoint = entryPoint_;
+        _approvedHashRegistry = approvedHashRegistry_;
         _disableInitializers();
     }
 
@@ -331,7 +431,20 @@ contract AgentAccount is
      *      will revert here. Master / bundler / session-issuer
      *      therefore cannot upgrade even by submitting the tx.
      */
-    function _authorizeUpgrade(address) internal view override onlySelf {}
+    function _authorizeUpgrade(address) internal view override onlySelf {
+        // CA-1: the per-account upgrade timelock is now ENFORCED here (it was
+        // previously dead code — set via `setUpgradeTimelock` but never consulted,
+        // so a direct `upgradeToAndCall` fired immediately). When a timelock is
+        // configured, a direct owner upgrade is refused; the owner must
+        // `scheduleUpgrade` then `executePendingUpgrade` after the delay. Authorized
+        // contexts — a custody-module action (its own T5 quorum + timelock) or the
+        // matured owner queue — set `_upgradeAuthorizedCtx` and pass through, so the
+        // custody path is not double-delayed. A zero timelock keeps the
+        // immediate-upgrade default (backward-compatible).
+        if (_upgradeTimelock != 0 && !_upgradeAuthorizedCtx) {
+            revert DirectUpgradeBlocked();
+        }
+    }
 
     /**
      * @notice DEPRECATED — single-signature upgrade path (contract audit C-3).
@@ -358,10 +471,25 @@ contract AgentAccount is
         revert LegacyUpgradePathDisabled();
     }
 
+    /// @notice CA-1 — queue an implementation upgrade subject to the per-account
+    ///         upgrade timelock. The owner signs a userOp that calls this
+    ///         (`onlySelf`); the bound implementation can then be applied via
+    ///         `executePendingUpgrade` once `_upgradeTimelock` has elapsed. Only
+    ///         meaningful when a timelock is configured — with none set, upgrade
+    ///         directly. Overwrites any existing pending upgrade.
+    function scheduleUpgrade(address newImplementation) external onlySelf {
+        if (newImplementation == address(0)) revert ZeroAddress();
+        uint256 tl = _upgradeTimelock;
+        if (tl == 0) revert UpgradeTimelockNotSet();
+        uint64 readyAt = uint64(block.timestamp + tl);
+        _pendingUpgrade = PendingUpgrade({newImplementation: newImplementation, readyAt: readyAt});
+        emit UpgradeProposed(newImplementation, readyAt);
+    }
+
     /// @notice Execute a previously-queued upgrade. Permissionless once
     ///         the timelock has expired — anyone can pay the gas, but
     ///         the implementation address was bound at queue time.
-    function executePendingUpgrade() external {
+    function executePendingUpgrade() external whenNotPaused {
         PendingUpgrade memory p = _pendingUpgrade;
         if (p.readyAt == 0) revert NoPendingUpgrade();
         if (block.timestamp < p.readyAt) revert UpgradeNotReady(p.readyAt, block.timestamp);
@@ -369,7 +497,12 @@ contract AgentAccount is
         // impl can't replay this state.
         delete _pendingUpgrade;
         emit UpgradeAuthorized(p.newImplementation);
+        // CA-1: authorize the nested `_authorizeUpgrade` for this matured queue
+        // (transient, tx-global). Cleared after so a later same-tx direct upgrade
+        // isn't inadvertently authorized.
+        _upgradeAuthorizedCtx = true;
         this.upgradeToAndCall(p.newImplementation, "");
+        _upgradeAuthorizedCtx = false;
     }
 
     /// @notice Cancel a queued upgrade during the timelock window. Owner
@@ -689,7 +822,7 @@ contract AgentAccount is
         uint256 moduleTypeId,
         address module,
         bytes calldata initData
-    ) external onlySelfOrFactoryInit {
+    ) external onlySelfOrFactoryInit whenNotPaused {
         if (module == address(0)) revert ZeroAddress();
         if (!_isSupportedModuleType(moduleTypeId)) revert UnsupportedModuleType(moduleTypeId);
 
@@ -837,6 +970,7 @@ contract AgentAccount is
     function executeFromModule(address target, uint256 value, bytes calldata data)
         external
         nonReentrant
+        whenNotPaused
         returns (bytes memory)
     {
         ModulesStorage storage $ = _modulesStorage();
@@ -844,7 +978,14 @@ contract AgentAccount is
             revert NotInstalledExecutor(msg.sender);
         }
         emit ModuleExecuted(msg.sender, target, value);
+        // CA-1: a module action is a custody-governed context (only an installed
+        // EXECUTOR — the CustodyPolicy — reaches here, gated upstream by its own
+        // T5 quorum + timelock). Authorize any upgrade it dispatches so the custody
+        // path is exempt from the per-account `_upgradeTimelock` (no double delay).
+        // Transient + nonReentrant, cleared after the call.
+        _upgradeAuthorizedCtx = true;
         (bool ok, bytes memory ret) = target.call{value: value}(data);
+        _upgradeAuthorizedCtx = false;
         if (!ok) {
             assembly { revert(add(ret, 32), mload(ret)) }
         }
@@ -891,7 +1032,7 @@ contract AgentAccount is
     ///      EntryPoint / self / DelegationManager; the guard hardens
     ///      against a malicious target re-entering through one of those
     ///      callers.
-    function execute(address target, uint256 value, bytes calldata data) external override nonReentrant {
+    function execute(address target, uint256 value, bytes calldata data) external override nonReentrant whenNotPaused {
         _requireForExecute();
 
         ModulesStorage storage $ = _modulesStorage();
@@ -944,7 +1085,7 @@ contract AgentAccount is
     ///      OUTER `execute` already holds the guard, so external re-entry
     ///      is blocked; `_requireForExecute` restricts entry to
     ///      EntryPoint / self / DM (DM has its own `nonReentrant`).
-    function executeBatch(Call[] calldata calls) external override {
+    function executeBatch(Call[] calldata calls) external override whenNotPaused {
         _requireForExecute();
 
         ModulesStorage storage $ = _modulesStorage();
@@ -1018,6 +1159,21 @@ contract AgentAccount is
         bytes32 hash,
         bytes calldata signature
     ) external view override(IAgentAccount, IERC1271) returns (bytes4) {
+        // Spec 253 — approved-hash sentinel (ERC-1271 ONLY). A bare 1-byte
+        // 0x03 validates iff THIS account pre-approved `hash` in the
+        // (immutable) ApprovedHashRegistry — letting an org batch its
+        // outbound-delegation approvals into one deploy userOp. Checked on
+        // the RAW signature before the ERC-6492 unwrap: a 1-byte sig can't
+        // carry a 32-byte 6492 suffix, so there's no smuggling path. This
+        // branch is unreachable from `_validateSignature`/`_validateSig`
+        // (the userOp-auth path), where 0x03 is an unknown type → false.
+        // Fails CLOSED if the registry is unset/not-a-contract (ADR-0013).
+        if (signature.length == 1 && uint8(signature[0]) == SIG_TYPE_APPROVED_HASH) {
+            if (_approvedHashRegistry.code.length == 0) return bytes4(0xffffffff);
+            return IApprovedHashRegistryView(_approvedHashRegistry).isApproved(address(this), hash)
+                ? ERC1271_MAGIC_VALUE
+                : bytes4(0xffffffff);
+        }
         bytes memory inner = signature;
         if (signature.length >= 32 && bytes32(signature[signature.length - 32:]) == ERC6492_MAGIC) {
             (, , bytes memory unwrapped) = abi.decode(
@@ -1033,6 +1189,12 @@ contract AgentAccount is
 
     uint8 internal constant SIG_TYPE_ECDSA    = 0x00;
     uint8 internal constant SIG_TYPE_WEBAUTHN = 0x01;
+    /// @dev Spec 253 — approved-hash sentinel. Honored ONLY by
+    ///      `isValidSignature` (ERC-1271), NEVER by `_validateSig` /
+    ///      `_validateSignature` (the userOp-auth path) — there `0x03` is an
+    ///      unknown type and returns false. A bare 1-byte `0x03` means
+    ///      "this hash is pre-approved in the ApprovedHashRegistry".
+    uint8 internal constant SIG_TYPE_APPROVED_HASH = 0x03;
 
     /// @dev Internal dispatcher. Accepts plain 65-byte ECDSA sigs as legacy
     ///      form AND type-prefixed sigs (first byte = SIG_TYPE_*).
@@ -1061,11 +1223,14 @@ contract AgentAccount is
 
     function _verifyEcdsa(bytes32 hash, bytes memory sig) internal view returns (bool) {
         // Try raw hash first — matches EntryPoint v0.8 (EIP-712 userOpHash signed directly).
+        // R6.3: third return (sigVersion) intentionally discarded; we rely on `err` + custodian-set membership.
+        // slither-disable-next-line unused-return
         (address recovered, ECDSA.RecoverError err,) = ECDSA.tryRecover(hash, sig);
         if (err == ECDSA.RecoverError.NoError && _externalCustodians[recovered]) return true;
         // Fall back to eth-signed-message wrap — matches v0.7 and legacy ERC-1271
         // callers that pre-prefix the digest.
         bytes32 ethSigned = hash.toEthSignedMessageHash();
+        // slither-disable-next-line unused-return
         (recovered, err,) = ECDSA.tryRecover(ethSigned, sig);
         return err == ECDSA.RecoverError.NoError && _externalCustodians[recovered];
     }
@@ -1079,9 +1244,12 @@ contract AgentAccount is
         bytes memory sig,
         address expected
     ) internal pure returns (bool) {
+        // R6.3: third return (sigVersion) intentionally discarded; the `err` discriminant + `recovered == expected` is the auth.
+        // slither-disable-next-line unused-return
         (address recovered, ECDSA.RecoverError err,) = ECDSA.tryRecover(hash, sig);
         if (err == ECDSA.RecoverError.NoError && recovered == expected) return true;
         bytes32 ethSigned = MessageHashUtils.toEthSignedMessageHash(hash);
+        // slither-disable-next-line unused-return
         (recovered, err,) = ECDSA.tryRecover(ethSigned, sig);
         return err == ECDSA.RecoverError.NoError && recovered == expected;
     }
@@ -1105,11 +1273,23 @@ contract AgentAccount is
             PasskeyEntry storage key = $.keys[a.credentialIdDigest];
             if (key.x == 0 && key.y == 0) return false;
             // H7-C.1 / CON-WEBAUTHN-001: pin per-credential rpIdHash + require UP.
-            // UV is not required at the library layer; account policy can layer
-            // UV requirement in via a future policy module if needed.
+            // R8.2 / ATL-SEC-03: require UV (User Verification) at the library
+            // layer. Wave H1 made the JS-side ceremony pass
+            // `userVerification: 'required'` for custody-grade flows
+            // (demo-sso, demo-sso-next, demo-org, demo-web-recovery); the
+            // third-party audit (2026-05-31) correctly observed that the
+            // contract still passed `requireUv: false` here. That meant a
+            // permissive authenticator could produce a UP-only assertion
+            // and we'd accept it. R8.2 makes UV strictly required on every
+            // ERC-1271 verify. Browser ceremonies that pass
+            // `userVerification: 'preferred'` will be REJECTED at the
+            // signature step — those apps (demo-web, demo-web-pro) MUST
+            // upgrade to `'required'` for production deployments. Tests
+            // exercising lower-assurance flows can install a separate
+            // passkey-validator module that relaxes this check.
             bytes32 rpIdHash = $.rpIdHashOf[a.credentialIdDigest];
             if (rpIdHash == bytes32(0)) return false;
-            return WebAuthnLib.verify(a, hash, key.x, key.y, rpIdHash, false);
+            return WebAuthnLib.verify(a, hash, key.x, key.y, rpIdHash, /*requireUv*/ true);
         } catch {
             return false;
         }
@@ -1178,7 +1358,7 @@ contract AgentAccount is
     ///      agenticprimitives AgentAccount is forbidden — enforced via
     ///      the ERC-165 marker. Passkey custodians are not added here;
     ///      use `addPasskey` instead.
-    function addCustodian(address owner) external override onlySelf {
+    function addCustodian(address owner) external override onlySelf whenNotPaused {
         if (owner == address(0)) revert ZeroAddress();
         if (_externalCustodians[owner]) revert CustodianAlreadyExists(owner);
         if (_isAgenticPrimitivesAgent(owner)) {

package/src/AgentAccountFactory.sol

@@ -10,7 +10,7 @@ import "./governance/GovernanceManaged.sol";
 /**
  * @title AgentAccountFactory
  * @notice Single-entry factory for AgentAccount proxies with
- *         deterministic CREATE2 addresses. Phase 6f.5 — collapsed
+ *         deterministic CREATE2 addresses. Phase 6f.5 -- collapsed
  *         createPersonAgent + createMultiSigSmartAgent into one
  *         entry point so every account on chain has the same shape;
  *         the only axis is `mode` on the init params.
@@ -32,7 +32,7 @@ import "./governance/GovernanceManaged.sol";
  *         marker check).
  *
  *         The canonical CustodyPolicy address is wired at construction
- *         (factory-immutable) — there is no per-call validator
+ *         (factory-immutable) -- there is no per-call validator
  *         override. Swapping CustodyPolicy versions means redeploying
  *         the factory, which is the same blast radius as a CREATE2
  *         salt bump.
@@ -41,7 +41,7 @@ import "./governance/GovernanceManaged.sol";
  *   `bundlerSigner` and `sessionIssuer` are factory-level capability
  *   addresses. They are NEVER custodians of any deployed account; each
  *   account reads them off this factory on demand. Phase A.5 made both
- *   mutable under governance — rotation flows through a governance
+ *   mutable under governance -- rotation flows through a governance
  *   proposal + 48h timelock and propagates automatically to every
  *   existing AgentAccount.
  */
@@ -49,6 +49,11 @@ contract AgentAccountFactory is GovernanceManaged {
     AgentAccount public immutable accountImplementation;
     address public immutable delegationManager;
     address public immutable custodyPolicy;
+    /// @dev Spec 253 — the ApprovedHashRegistry baked (immutable) into the
+    ///      AgentAccount impl this factory deploys; surfaced here for
+    ///      deploy-time auditing. The account's `isValidSignature` 0x03
+    ///      sentinel consults it; it is NOT a mutable factory-view.
+    address public immutable approvedHashRegistry;
 
     address public bundlerSigner;
     address public sessionIssuer;
@@ -73,6 +78,21 @@ contract AgentAccountFactory is GovernanceManaged {
     error InsufficientTrusteesForMode(uint8 mode, uint256 actual, uint256 required);
     error TrusteesRequiredForRecoverableMode(uint8 mode);
     error ZeroAddress();
+    /// @notice R9.6 / ATL-SEC-05 -- thrown when `params.custodians.length`
+    ///         exceeds `MAX_INITIAL_CUSTODIANS`. Without this cap,
+    ///         `_buildValidatorInitData` casts `nSigners` to `uint8`
+    ///         and silently truncates at 256, computing a wrong default
+    ///         threshold for a misconfigured account. A self-hurt
+    ///         footgun, not a cross-account vulnerability -- capped so
+    ///         the misconfiguration fails closed at construction.
+    error TooManyInitialCustodians(uint256 actual, uint256 max);
+
+    /// @notice R9.6 / ATL-SEC-05 -- upper bound on initial custodians
+    ///         passed via `AgentAccountInitParams`. 32 is deliberately
+    ///         generous (every smart-account substrate we surveyed
+    ///         caps well below 16) but well under the `uint8` truncation
+    ///         threshold at `_buildValidatorInitData:252`.
+    uint256 public constant MAX_INITIAL_CUSTODIANS = 32;
 
     constructor(
         IEntryPoint entryPoint_,
@@ -80,10 +100,12 @@ contract AgentAccountFactory is GovernanceManaged {
         address custodyPolicy_,
         address bundlerSigner_,
         address sessionIssuer_,
-        address governance_
+        address governance_,
+        address approvedHashRegistry_
     ) GovernanceManaged(governance_) {
         if (custodyPolicy_ == address(0)) revert ZeroAddress();
-        accountImplementation = new AgentAccount(entryPoint_);
+        accountImplementation = new AgentAccount(entryPoint_, approvedHashRegistry_);
+        approvedHashRegistry = approvedHashRegistry_;
         delegationManager = delegationManager_;
         custodyPolicy = custodyPolicy_;
         bundlerSigner = bundlerSigner_;
@@ -134,10 +156,13 @@ contract AgentAccountFactory is GovernanceManaged {
         // timelock (see AgenticGovernance).
         _validateInitParams(params);
 
-        address addr = _getAddressForAgentAccount(params, salt);
+        // CA-F1 (audit 2026-06-10): derive the deploy salt from the FULL custody config so the
+        // counterfactual address commits to mode/trustees/timelocks too — not just custodians/passkey.
+        bytes32 deploySalt = _effectiveSalt(params, timelockOverrides, salt);
+        address addr = _getAddressFromSalt(params, deploySalt);
         if (addr.code.length > 0) return AgentAccount(payable(addr));
 
-        ERC1967Proxy proxy = new ERC1967Proxy{salt: bytes32(salt)}(
+        ERC1967Proxy proxy = new ERC1967Proxy{salt: deploySalt}(
             address(accountImplementation),
             _initData(params)
         );
@@ -159,12 +184,16 @@ contract AgentAccountFactory is GovernanceManaged {
     }
 
     /// @notice Counterfactual address for `createAgentAccount`.
+    /// @dev CA-F1: takes `timelockOverrides` because the address now commits to it. Callers MUST
+    ///      predict with the SAME (params, timelockOverrides, salt) they will deploy with, else the
+    ///      predicted address won't match the deployed one.
     function getAddressForAgentAccount(
         AgentAccountInitParams calldata params,
+        uint32[7] calldata timelockOverrides,
         uint256 salt
     ) external view returns (address) {
         _validateInitParams(params);
-        return _getAddressForAgentAccount(params, salt);
+        return _getAddressFromSalt(params, _effectiveSalt(params, timelockOverrides, salt));
     }
 
     // ─── Internals ──────────────────────────────────────────────────────
@@ -187,22 +216,40 @@ contract AgentAccountFactory is GovernanceManaged {
         );
     }
 
-    function _getAddressForAgentAccount(
+    /// @dev CA-F1 (audit 2026-06-10) — the deploy salt commits to the FULL custody configuration:
+    ///      mode, trustees, and per-tier timelock overrides. `_initData` already folds custodians +
+    ///      the initial passkey into the proxy bytecode hash (and thus the address); those, plus the
+    ///      mode/trustees/timelocks bound here, mean the canonical address IS its complete custody
+    ///      config. Two `createAgentAccount` calls that differ in ANY of these resolve to DIFFERENT
+    ///      addresses, so an attacker can no longer front-run a victim's counterfactual address with a
+    ///      weaker mode, attacker-controlled recovery trustees, or shortened timelocks. The
+    ///      occupied-address branch is consequently reachable only by an identical-config request —
+    ///      which also closes CA-F2 (silent adoption of a mismatched pre-existing account) by
+    ///      construction, with no separate config-equality assertion needed.
+    function _effectiveSalt(
         AgentAccountInitParams calldata params,
+        uint32[7] calldata timelockOverrides,
         uint256 salt
+    ) internal pure returns (bytes32) {
+        return keccak256(abi.encode(salt, params.mode, params.trustees, timelockOverrides));
+    }
+
+    function _getAddressFromSalt(
+        AgentAccountInitParams calldata params,
+        bytes32 deploySalt
     ) internal view returns (address) {
         bytes memory initData = _initData(params);
-        return _create2Address(initData, salt);
+        return _create2Address(initData, deploySalt);
     }
 
-    function _create2Address(bytes memory initData, uint256 salt) internal view returns (address) {
+    function _create2Address(bytes memory initData, bytes32 salt) internal view returns (address) {
         bytes memory proxyBytecode = abi.encodePacked(
             type(ERC1967Proxy).creationCode,
             abi.encode(address(accountImplementation), initData)
         );
         bytes32 bytecodeHash = keccak256(proxyBytecode);
         return address(uint160(uint256(keccak256(
-            abi.encodePacked(bytes1(0xff), address(this), bytes32(salt), bytecodeHash)
+            abi.encodePacked(bytes1(0xff), address(this), salt, bytecodeHash)
         ))));
     }
 
@@ -219,6 +266,13 @@ contract AgentAccountFactory is GovernanceManaged {
 
         bool hasPasskey = params.initialPasskeyX != 0 && params.initialPasskeyY != 0;
         if (params.custodians.length == 0 && !hasPasskey) revert NoInitialSigner();
+        // R9.6 / ATL-SEC-05: cap the initial custodian set so
+        // `_buildValidatorInitData`'s `uint8(nSigners)` cast can't
+        // silently truncate. 32 is well above any rational config and
+        // well below the uint8 boundary.
+        if (params.custodians.length > MAX_INITIAL_CUSTODIANS) {
+            revert TooManyInitialCustodians(params.custodians.length, MAX_INITIAL_CUSTODIANS);
+        }
 
         if (params.mode == 0) return;